feat(types): support generics

[naorpeled]

Basic Type-Safe Setup

import { API, Request, Response, ALBContext, APIGatewayContext, APIGatewayV2Context } from 'lambda-api';
import { ALBEvent, APIGatewayProxyEvent, APIGatewayProxyEventV2 } from 'aws-lambda';

// Initialize with type inference
const api = new API();

Type-Safe Request Handlers

ALB Handler Example

interface UserData {
  id: string;
  name: string;
  email: string;
}

// Type-safe ALB request handler
api.get<UserData, ALBContext>('/users', (req, res) => {
  // req.requestContext is typed as ALBContext
  console.log(req.requestContext.elb.targetGroupArn);
  
  // Type-safe response
  res.json({
    id: '123',
    name: 'John Doe',
    email: 'john@example.com'
  });
});

API Gateway v1 Handler Example

// Type-safe API Gateway v1 request handler
api.post<UserData, APIGatewayContext>('/users', (req, res) => {
  // req.requestContext is typed as APIGatewayContext
  console.log(req.requestContext.requestId);
  console.log(req.requestContext.identity.sourceIp);
  
  res.json({
    id: req.requestContext.requestId,
    name: req.body.name,
    email: req.body.email
  });
});

API Gateway v2 Handler Example

// Type-safe API Gateway v2 request handler
api.put<UserData, APIGatewayV2Context>('/users/:id', (req, res) => {
  // req.requestContext is typed as APIGatewayV2Context
  console.log(req.requestContext.http.sourceIp);
  
  res.json({
    id: req.params.id,
    name: req.body.name,
    email: req.body.email
  });
});

Type-Safe Middleware

Source-Agnostic Middleware

import { Middleware, isApiGatewayContext, isApiGatewayV2Context, isAlbContext } from 'lambda-api';

const sourceAgnosticMiddleware: Middleware = (req, res, next) => {
  // Type guards help narrow down the request context type
  if (isAlbContext(req.requestContext)) {
    // ALB specific logic
    console.log(req.requestContext.elb.targetGroupArn);
  } else if (isApiGatewayV2Context(req.requestContext)) {
    // API Gateway v2 specific logic
    console.log(req.requestContext.http.sourceIp);
  } else if (isApiGatewayContext(req.requestContext)) {
    // API Gateway v1 specific logic
    console.log(req.requestContext.identity.sourceIp);
  }
  
  next();
};

api.use(sourceAgnosticMiddleware);

Source-Specific Middleware

// ALB-specific middleware
const albMiddleware: Middleware<any, ALBContext> = (req, res, next) => {
  // req.requestContext is typed as ALBContext
  console.log(req.requestContext.elb.targetGroupArn);
  next();
};

// API Gateway v2 specific middleware
const apiGwV2Middleware: Middleware<any, APIGatewayV2Context> = (req, res, next) => {
  // req.requestContext is typed as APIGatewayV2Context
  console.log(req.requestContext.http.sourceIp);
  next();
};

Type-Safe Error Handling

import { ErrorHandlingMiddleware } from 'lambda-api';

const errorHandler: ErrorHandlingMiddleware = (error, req, res, next) => {
  if (isAlbContext(req.requestContext)) {
    // ALB specific error handling
    res.status(500).json({
      message: error.message,
      targetGroup: req.requestContext.elb.targetGroupArn
    });
  } else {
    // Default error handling
    res.status(500).json({
      message: error.message
    });
  }
};

api.use(errorHandler);

Advanced Type-Safe Examples

Custom Request Types

interface CustomQuery {
  filter?: string;
  page?: string;
}

interface CustomParams {
  userId: string;
}

interface CustomBody {
  name: string;
  email: string;
}

// Fully typed request handler
api.get<
  UserData,
  ALBContext,
  CustomQuery,
  CustomParams,
  CustomBody
>('/users/:userId', (req, res) => {
  // All properties are properly typed
  const { filter, page } = req.query;
  const { userId } = req.params;
  const { name, email } = req.body;
  
  res.json({
    id: userId,
    name,
    email
  });
});

Response Type Extensions

// Extend Response interface with custom methods
declare module 'lambda-api' {
  interface Response {
    sendWithTimestamp?: (data: any) => void;
  }
}

const responseEnhancer: Middleware = (req, res, next) => {
  res.sendWithTimestamp = (data: any) => {
    res.json({
      ...data,
      timestamp: Date.now()
    });
  };
  next();
};

api.use(responseEnhancer);

// Use custom response method
api.get('/users', (req, res) => {
  res.sendWithTimestamp({ name: 'John' });
});

Using Built-in Auth Property

interface AuthInfo {
  userId: string;
  roles: string[];
  type: 'Bearer' | 'Basic' | 'OAuth' | 'Digest' | 'none';
  value: string | null;
}

function hasAuth(req: Request): req is Request & { auth: AuthInfo } {
  return 'auth' in req && req.auth?.type !== undefined;
}

api.get('/protected', (req, res) => {
  if (hasAuth(req)) {
    // req.auth is now typed as AuthInfo
    const { userId, roles } = req.auth;
    res.json({ userId, roles });
  } else {
    res.status(401).json({ message: 'Unauthorized' });
  }
});

Running the API

// Type-safe run method
export const handler = async (
  event: ALBEvent | APIGatewayProxyEvent | APIGatewayProxyEventV2,
  context: any
) => {
  return api.run(event, context);
};

Type Guards Usage

import {
  isAlbContext,
  isAlbEvent,
  isAlbRequest,
  isApiGatewayContext,
  isApiGatewayEvent,
  isApiGatewayRequest,
  isApiGatewayV2Context,
  isApiGatewayV2Event,
  isApiGatewayV2Request
} from 'lambda-api';

api.use((req, res, next) => {
  // Event type guards
  if (isAlbEvent(req.app._event)) {
    // ALB specific logic
  }
  
  // Context type guards
  if (isAlbContext(req.requestContext)) {
    // ALB specific logic
  }
  
  // Request type guards
  if (isAlbRequest(req)) {
    // ALB specific logic
  }
  
  next();
});

Best Practices

1. Always specify response types for better type inference:

interface ResponseType {
  message: string;
  code: number;
}

api.get<ResponseType>('/status', (req, res) => {
  res.json({
    message: 'OK',
    code: 200
  });
});

2. Use type guards for source-specific logic:

api.use((req, res, next) => {
  if (isAlbContext(req.requestContext)) {
    // ALB-specific logging
    console.log(`ALB Request to ${req.requestContext.elb.targetGroupArn}`);
  }
  next();
});

3. Leverage TypeScript's type inference with middleware:

const typedMiddleware: Middleware<ResponseType, ALBContext> = (req, res, next) => {
  // Full type information available
  next();
};

4. Use source-specific error handling:

api.use((error, req, res, next) => {
  const baseError = {
    message: error.message,
    timestamp: new Date().toISOString()
  };

  if (isAlbContext(req.requestContext)) {
    res.status(500).json({
      ...baseError,
      targetGroup: req.requestContext.elb.targetGroupArn
    });
  } else if (isApiGatewayV2Context(req.requestContext)) {
    res.status(500).json({
      ...baseError,
      stage: req.requestContext.stage
    });
  } else {
    res.status(500).json(baseError);
  }
});

Issues

implements #276
and closes #244

[vandrade-git]

This seems like a great change.

I've just tried on a project I have and noticed a few things. Given:

api.get<Response, ALBContext>('/health', async (req, res) => {
  console.log(req.requestContext.elb); <-- also type any, any, any

  res.json({ status: 'ok' });
});

both req and res have an implicit type any so the type checking does not seem to be doing what is described in the README.

src/index.ts:20:52 - error TS7006: Parameter 'req' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

src/index.ts:20:57 - error TS7006: Parameter 'res' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

This seems to be a limitation of the type

...
(
  | Middleware<TResponse, TContext, TQuery, TParams, TBody>
  | HandlerFunction<TResponse, TContext, TQuery, TParams, TBody>
)
...

Something like:

const health: HandlerFunction<object, ALBContext> = async (req, res) => {
  console.log(req.requestContext.elb);

  res.json({ status: 'ok' });
};
// public health endpoint
api.get<Response, ALBContext>('/health', health);

seems to over fine but it is a bit more cumbersome.

[naorpeled]

This seems like a great change.

I've just tried on a project I have and noticed a few things. Given:

api.get<Response, ALBContext>('/health', async (req, res) => {
  console.log(req.requestContext.elb); <-- also type any, any, any

  res.json({ status: 'ok' });
});

both req and res have an implicit type any so the type checking does not seem to be doing what is described in the README.

src/index.ts:20:52 - error TS7006: Parameter 'req' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

src/index.ts:20:57 - error TS7006: Parameter 'res' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

This seems to be a limitation of the type

...
(
  | Middleware<TResponse, TContext, TQuery, TParams, TBody>
  | HandlerFunction<TResponse, TContext, TQuery, TParams, TBody>
)
...

Something like:

const health: HandlerFunction<object, ALBContext> = async (req, res) => {
  console.log(req.requestContext.elb);

  res.json({ status: 'ok' });
};
// public health endpoint
api.get<Response, ALBContext>('/health', health);

seems to over fine but it is a bit more cumbersome.

I see, I'll dig into it in the next few days.
Thanks for the feedback, very appreciated!

[naorpeled]

@copilot continue this PR and make sure CI fully passes and that this feature works

[Copilot]

@naorpeled I've opened a new pull request, #304, to work on those changes. Once the pull request is ready, I'll request review from you.

[naorpeled]

This seems like a great change.
I've just tried on a project I have and noticed a few things. Given:

api.get<Response, ALBContext>('/health', async (req, res) => {
  console.log(req.requestContext.elb); <-- also type any, any, any

  res.json({ status: 'ok' });
});

both req and res have an implicit type any so the type checking does not seem to be doing what is described in the README.

src/index.ts:20:52 - error TS7006: Parameter 'req' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

src/index.ts:20:57 - error TS7006: Parameter 'res' implicitly has an 'any' type.
20 api.get<Response, ALBContext>('/health', async (req, res) => {

This seems to be a limitation of the type

...
(
  | Middleware<TResponse, TContext, TQuery, TParams, TBody>
  | HandlerFunction<TResponse, TContext, TQuery, TParams, TBody>
)
...

Something like:

const health: HandlerFunction<object, ALBContext> = async (req, res) => {
  console.log(req.requestContext.elb);

  res.json({ status: 'ok' });
};
// public health endpoint
api.get<Response, ALBContext>('/health', health);

seems to over fine but it is a bit more cumbersome.

I see, I'll dig into it in the next few days. Thanks for the feedback, very appreciated!

Sorry for the huge delay with this, hopefully I'll be able to finalize this soon

[Copilot]

Pull request overview

This PR adds generic TypeScript support to lambda-api, addressing issues #276 (ALB TypeScript support) and #244 (generic request/response types). It introduces type-safe generics across route handlers, middleware, and error handlers, along with runtime type guards to discriminate between API Gateway v1, API Gateway v2, and ALB request contexts.

Changes:

• New lib/typeguards.js file exporting runtime type guard functions for API Gateway v1/v2 and ALB contexts, events, and requests
• index.d.ts extensively updated to add generics (TResponse, TContext, TQuery, TParams, TBody) to Request, Response, Middleware, HandlerFunction, ErrorHandlingMiddleware, and all API methods; exports new context types (ALBContext, APIGatewayContext, APIGatewayV2Context), SourceAgnostic* helper types, and type guard declarations
• README.md and index.test-d.ts updated with comprehensive TypeScript documentation and new type-level tests

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
lib/typeguards.js	New module with runtime type guards for discriminating event/context/request sources
index.js	Imports and re-exports the new type guard functions
index.d.ts	Full overhaul of TypeScript declarations to support generics and new context types
index.test-d.ts	Rewrites tsd type tests to validate new generic and type guard features
__tests__/typeguards.unit.js	New unit tests for all type guard functions
README.md	Adds TypeScript documentation, type guard usage examples, and patterns for multi-source handlers

[Copilot]

The updated index.test-d.ts removes type-level test coverage for several previously-tested exports: CookieOptions, CorsOptions, FileOptions, Options, METHODS, RouteError, MethodError, ConfigurationError, ResponseError, and FileError. These types still exist in index.d.ts but are no longer validated by any type test. Since this project uses tsd for type testing, these exports should remain covered to prevent future regressions.

[Copilot]

The TypeScript Support code example in the README uses APIGatewayContext at line 103, but this type is not included in the import statement shown at lines 42-50. Users copying this example would get a TypeScript error. The import block should include APIGatewayContext (and potentially ALBContext for completeness).

Suggested change

	SourceAgnosticMiddleware,
	SourceAgnosticMiddleware,
	APIGatewayContext,
	ALBContext,

[Copilot]

The "Type Safety Examples" code snippet uses UserType at line 1748, but this type is never defined in the code snippet or the surrounding context. This would cause a TypeScript compile error for anyone copying this example. It should be replaced with an actual type definition (e.g., defining interface UserType { id: string; roles: string[]; email: string; } above or using an existing type like UserResponse).

Suggested change

	```typescript
	```typescript
	interface UserType {
	id: string;
	roles: string[];
	email: string;
	}

[Copilot]

The README's second "Handling Multiple Request Sources" section (near the end of the file) uses the non-existent type names APIGatewayRequestContext and ALBRequestContext as type parameters. The correct exported types are APIGatewayContext and ALBContext respectively. Additionally, Response is used as the first type parameter (the response body type), but Response is the response class, not a response body shape. The earlier section of the same README (around line 173) correctly uses APIGatewayContext and ALBContext, making this a clear inconsistency in the documentation.

Suggested change

	api.get<Response, APIGatewayRequestContext>('/api-gateway', (req, res) => {
	console.log(req.requestContext.identity);
	});
	api.get<Response, ALBRequestContext>('/alb', (req, res) => {
	api.get<{ message: string }, APIGatewayContext>('/api-gateway', (req, res) => {
	console.log(req.requestContext.identity);
	});
	api.get<{ message: string }, ALBContext>('/alb', (req, res) => {

[Copilot]

The section heading "## Handling Multiple Request Sources" appears twice in the README — at line 160 and line 1791. This creates a duplicate heading with conflicting content, where the TOC entry at line 295 can only link to one of them. The second occurrence (line 1791) only contains a short code snippet and duplicates content already present in the first. The duplicate section should be merged or removed to avoid confusion.

[Copilot]

The UserQuery and UserParams interfaces defined in the README TypeScript example (lines 92-101) are not compatible with the generic type constraint TQuery extends Record<string, string | undefined>. The interfaces declare non-optional string properties (fields: string, id: string), but the constraint requires values to be string | undefined. Using these definitions at line 103 would cause a TypeScript compile error. The properties should be declared as optional (e.g., fields?: string) or the interfaces should extend Record<string, string | undefined>, consistent with how they are defined in index.test-d.ts.