@jaypie/express 1.2.25 → 1.2.27

package/dist/esm/index.d.ts

@@ -1,13 +1,458 @@
-export { createLambdaHandler, createLambdaStreamHandler, getCurrentInvoke, LambdaRequest, LambdaResponseBuffered, LambdaResponseStreaming, } from "./adapter/index.js";
-export type { ApiGatewayV1Event, CreateLambdaHandlerOptions, FunctionUrlEvent, LambdaContext, LambdaEvent, LambdaHandler, LambdaResponse, LambdaStreamHandler, ResponseStream, } from "./adapter/index.js";
-export { EXPRESS } from "./constants.js";
-export { default as cors } from "./cors.helper.js";
-export type { CorsConfig } from "./cors.helper.js";
-export { default as fabricApiResponse } from "./fabricApiResponse.js";
-export { default as expressHandler } from "./expressHandler.js";
-export type { ExpressHandlerLocals, ExpressHandlerOptions, JaypieHandlerSetup, JaypieHandlerTeardown, JaypieHandlerValidate, } from "./expressHandler.js";
-export { default as expressHttpCodeHandler } from "./http.handler.js";
-export { default as expressStreamHandler } from "./expressStreamHandler.js";
-export type { ExpressStreamHandler, ExpressStreamHandlerLocals, ExpressStreamHandlerOptions, JaypieStreamHandlerSetup, JaypieStreamHandlerTeardown, JaypieStreamHandlerValidate, } from "./expressStreamHandler.js";
-export { default as getCurrentInvokeUuid } from "./getCurrentInvokeUuid.adapter.js";
-export * from "./routes.js";
+import * as express from 'express';
+import { Application, Request, Response, NextFunction } from 'express';
+import { StreamFormat } from '@jaypie/aws';
+import { IncomingHttpHeaders, OutgoingHttpHeaders } from 'node:http';
+import { Readable, Writable } from 'node:stream';
+
+interface LambdaContext {
+    awsRequestId: string;
+    callbackWaitsForEmptyEventLoop?: boolean;
+    functionName?: string;
+    functionVersion?: string;
+    invokedFunctionArn?: string;
+    logGroupName?: string;
+    logStreamName?: string;
+    memoryLimitInMB?: string;
+    [key: string]: unknown;
+}
+interface ApiGatewayV1Event {
+    body?: string | null;
+    headers: Record<string, string>;
+    httpMethod: string;
+    isBase64Encoded: boolean;
+    multiValueHeaders?: Record<string, string[]>;
+    multiValueQueryStringParameters?: Record<string, string[]> | null;
+    path: string;
+    pathParameters?: Record<string, string> | null;
+    queryStringParameters?: Record<string, string> | null;
+    requestContext: {
+        accountId: string;
+        apiId: string;
+        domainName?: string;
+        httpMethod: string;
+        identity: {
+            sourceIp: string;
+            userAgent?: string;
+        };
+        path: string;
+        protocol: string;
+        requestId: string;
+        requestTime?: string;
+        requestTimeEpoch?: number;
+        resourceId?: string;
+        resourcePath?: string;
+        stage: string;
+    };
+    resource?: string;
+    stageVariables?: Record<string, string> | null;
+}
+interface FunctionUrlEvent {
+    body?: string;
+    cookies?: string[];
+    headers: Record<string, string>;
+    isBase64Encoded: boolean;
+    rawPath: string;
+    rawQueryString: string;
+    requestContext: {
+        accountId: string;
+        apiId: string;
+        domainName: string;
+        domainPrefix: string;
+        http: {
+            method: string;
+            path: string;
+            protocol: string;
+            sourceIp: string;
+            userAgent: string;
+        };
+        requestId: string;
+        routeKey: string;
+        stage: string;
+        time: string;
+        timeEpoch: number;
+    };
+    routeKey: string;
+    version: "2.0";
+}
+type LambdaEvent = ApiGatewayV1Event | FunctionUrlEvent;
+interface LambdaResponse {
+    body: string;
+    cookies?: string[];
+    headers: Record<string, string>;
+    isBase64Encoded: boolean;
+    statusCode: number;
+}
+interface ResponseStream {
+    end(): void;
+    write(chunk: string | Uint8Array): void;
+}
+type LambdaHandler = (event: LambdaEvent, context: LambdaContext) => Promise<LambdaResponse>;
+type LambdaStreamHandler = (event: LambdaEvent, context: LambdaContext) => Promise<void>;
+type CreateLambdaHandlerOptions = {
+    /**
+     * Optional name for logging and debugging
+     */
+    name?: string;
+};
+
+interface LambdaRequestOptions {
+    body?: Buffer | null;
+    headers: Record<string, string>;
+    lambdaContext: LambdaContext;
+    lambdaEvent: LambdaEvent;
+    method: string;
+    protocol: string;
+    query?: Record<string, string | string[]>;
+    remoteAddress: string;
+    url: string;
+}
+interface MockSocket {
+    destroy: () => void;
+    encrypted: boolean;
+    remoteAddress: string;
+}
+/**
+ * Mock IncomingMessage that extends Readable stream.
+ * Provides Express-compatible request interface from Lambda Function URL events.
+ */
+declare class LambdaRequest extends Readable {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: IncomingHttpHeaders;
+    readonly httpVersion: string;
+    readonly httpVersionMajor: number;
+    readonly httpVersionMinor: number;
+    complete: boolean;
+    readonly socket: MockSocket;
+    readonly connection: MockSocket;
+    readonly originalUrl: string;
+    readonly path: string;
+    baseUrl: string;
+    body: unknown;
+    params: Record<string, string>;
+    query: Record<string, unknown>;
+    readonly rawBody: string | undefined;
+    readonly _lambdaContext: LambdaContext;
+    readonly _lambdaEvent: LambdaEvent;
+    private bodyBuffer;
+    private bodyPushed;
+    constructor(options: LambdaRequestOptions);
+    _read(): void;
+    get(headerName: string): string | undefined;
+    header(headerName: string): string | undefined;
+    private normalizeHeaders;
+}
+
+/**
+ * Mock ServerResponse that buffers the response.
+ * Collects status, headers, and body chunks, then returns a Lambda response.
+ */
+declare class LambdaResponseBuffered extends Writable {
+    statusCode: number;
+    statusMessage: string;
+    readonly socket: {
+        remoteAddress: string;
+    };
+    _chunks: Buffer[];
+    _ended: boolean;
+    _headers: Map<string, string | string[]>;
+    _headersSent: boolean;
+    _resolve: ((result: LambdaResponse) => void) | null;
+    constructor();
+    _internalGetHeader(name: string): string | undefined;
+    _internalSetHeader(name: string, value: string): void;
+    _internalHasHeader(name: string): boolean;
+    _internalRemoveHeader(name: string): void;
+    getResult(): Promise<LambdaResponse>;
+    setHeader(name: string, value: number | string | string[]): this;
+    getHeader(name: string): number | string | string[] | undefined;
+    removeHeader(name: string): void;
+    getHeaders(): OutgoingHttpHeaders;
+    hasHeader(name: string): boolean;
+    getHeaderNames(): string[];
+    /**
+     * Proxy for direct header access (e.g., res.headers['content-type']).
+     * Required for compatibility with middleware like helmet that access headers directly.
+     * Uses direct _headers access to bypass dd-trace interception.
+     */
+    get headers(): Record<string, string | string[] | undefined>;
+    writeHead(statusCode: number, statusMessageOrHeaders?: OutgoingHttpHeaders | string, headers?: OutgoingHttpHeaders): this;
+    get headersSent(): boolean;
+    /**
+     * Express-style alias for getHeader().
+     * Used by middleware like decorateResponse that use res.get().
+     * Note: Directly accesses _headers to avoid prototype chain issues with bundled code.
+     */
+    get(name: string): number | string | string[] | undefined;
+    /**
+     * Express-style alias for setHeader().
+     * Used by middleware like decorateResponse that use res.set().
+     * Note: Directly accesses _headers to avoid prototype chain issues with bundled code.
+     */
+    set(name: string, value: number | string | string[]): this;
+    status(code: number): this;
+    json(data: unknown): this;
+    send(body?: Buffer | object | string): this;
+    /**
+     * Add a field to the Vary response header.
+     * Used by CORS middleware to indicate response varies by Origin.
+     * Uses direct _headers access to bypass dd-trace interception.
+     */
+    vary(field: string): this;
+    _write(chunk: Buffer | string, encoding: BufferEncoding, // eslint-disable-line no-undef
+    callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    buildResult(): LambdaResponse;
+    private isBinaryContentType;
+}
+
+/**
+ * Mock ServerResponse that streams directly to Lambda responseStream.
+ * Uses awslambda.HttpResponseStream.from() to set status and headers.
+ */
+declare class LambdaResponseStreaming extends Writable {
+    statusCode: number;
+    statusMessage: string;
+    readonly socket: {
+        remoteAddress: string;
+    };
+    _headers: Map<string, string | string[]>;
+    _headersSent: boolean;
+    private _convertedFrom204;
+    private _pendingWrites;
+    private _responseStream;
+    private _wrappedStream;
+    constructor(responseStream: ResponseStream);
+    _internalGetHeader(name: string): string | undefined;
+    _internalSetHeader(name: string, value: string): void;
+    _internalHasHeader(name: string): boolean;
+    _internalRemoveHeader(name: string): void;
+    setHeader(name: string, value: number | string | string[]): this;
+    getHeader(name: string): number | string | string[] | undefined;
+    removeHeader(name: string): void;
+    getHeaders(): OutgoingHttpHeaders;
+    hasHeader(name: string): boolean;
+    getHeaderNames(): string[];
+    /**
+     * Proxy for direct header access (e.g., res.headers['content-type']).
+     * Required for compatibility with middleware like helmet that access headers directly.
+     * Uses direct _headers access to bypass dd-trace interception.
+     */
+    get headers(): Record<string, string | string[] | undefined>;
+    writeHead(statusCode: number, statusMessageOrHeaders?: OutgoingHttpHeaders | string, headers?: OutgoingHttpHeaders): this;
+    get headersSent(): boolean;
+    flushHeaders(): void;
+    /**
+     * Express-style alias for getHeader().
+     * Used by middleware like decorateResponse that use res.get().
+     * Note: Directly accesses _headers to avoid prototype chain issues with bundled code.
+     */
+    get(name: string): number | string | string[] | undefined;
+    /**
+     * Express-style alias for setHeader().
+     * Used by middleware like decorateResponse that use res.set().
+     * Note: Directly accesses _headers to avoid prototype chain issues with bundled code.
+     */
+    set(name: string, value: number | string | string[]): this;
+    status(code: number): this;
+    json(data: unknown): this;
+    send(body?: Buffer | object | string): this;
+    /**
+     * Add a field to the Vary response header.
+     * Used by CORS middleware to indicate response varies by Origin.
+     * Uses direct _headers access to bypass dd-trace interception.
+     */
+    vary(field: string): this;
+    _write(chunk: Buffer | string, encoding: BufferEncoding, // eslint-disable-line no-undef
+    callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+}
+
+/**
+ * Get the current Lambda invoke context.
+ * Used by getCurrentInvokeUuid adapter to get the request ID.
+ */
+declare function getCurrentInvoke(): {
+    context: LambdaContext;
+    event: LambdaEvent;
+} | null;
+/**
+ * Create a Lambda handler that buffers the Express response.
+ * Returns the complete response as a Lambda response object.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { createLambdaHandler } from "@jaypie/express";
+ *
+ * const app = express();
+ * app.get("/", (req, res) => res.json({ message: "Hello" }));
+ *
+ * export const handler = createLambdaHandler(app);
+ * ```
+ */
+declare function createLambdaHandler(app: Application, _options?: CreateLambdaHandlerOptions): LambdaHandler;
+/**
+ * Create a Lambda handler that streams the Express response.
+ * Uses awslambda.streamifyResponse() for Lambda response streaming.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { createLambdaStreamHandler } from "@jaypie/express";
+ *
+ * const app = express();
+ * app.get("/stream", (req, res) => {
+ *   res.setHeader("Content-Type", "text/event-stream");
+ *   res.write("data: Hello\n\n");
+ *   res.end();
+ * });
+ *
+ * export const handler = createLambdaStreamHandler(app);
+ * ```
+ */
+declare function createLambdaStreamHandler(app: Application, _options?: CreateLambdaHandlerOptions): LambdaStreamHandler;
+
+declare const EXPRESS: {
+    readonly PATH: {
+        readonly ANY: RegExp;
+        readonly ID: "/:id";
+        readonly ROOT: RegExp;
+    };
+};
+
+interface CorsConfig {
+    origin?: string | string[];
+    overrides?: Record<string, unknown>;
+}
+/**
+ * CORS middleware with Lambda streaming support.
+ *
+ * For OPTIONS preflight requests, this middleware handles them early and
+ * terminates the response immediately. This is critical for Lambda streaming
+ * handlers where the response stream would otherwise stay open waiting for
+ * streaming data that never comes.
+ *
+ * For regular requests, delegates to the standard cors package behavior.
+ */
+declare const _default: (config?: CorsConfig) => ((req: Request, res: Response, next: NextFunction) => void);
+
+/**
+ * Wrap a service return value in the canonical Jaypie API envelope.
+ *
+ * Rules:
+ * - `null` / `undefined` → `{ data: null }`
+ * - `{ data }` with exactly one key → passthrough
+ * - `{ errors }` with exactly one key → passthrough
+ * - everything else (including `{ data, other }`) → `{ data: value }`
+ *
+ * The "only one key, and that key is `data` or `errors`" check prevents
+ * false positives where a domain object happens to contain a `data` field.
+ */
+declare function fabricApiResponse(result: unknown): unknown;
+
+type JaypieHandlerSetup = (req: Request, res: Response) => Promise<void> | void;
+type JaypieHandlerTeardown = (req: Request, res: Response) => Promise<void> | void;
+type JaypieHandlerValidate = (req: Request, res: Response) => Promise<boolean | void> | boolean | void;
+type ExpressHandlerLocals = (req: Request, res: Response) => Promise<unknown> | unknown;
+interface ExpressHandlerOptions {
+    chaos?: string;
+    /**
+     * When true, the handler's return value is wrapped with
+     * `fabricApiResponse` before `res.json()`. Plain objects become
+     * `{ data: value }`; pre-wrapped `{ data }` or `{ errors }` payloads
+     * pass through unchanged. `null` / `undefined` become `{ data: null }`.
+     */
+    fabric?: boolean;
+    locals?: Record<string, unknown | ExpressHandlerLocals>;
+    name?: string;
+    secrets?: string[];
+    setup?: JaypieHandlerSetup[] | JaypieHandlerSetup;
+    teardown?: JaypieHandlerTeardown[] | JaypieHandlerTeardown;
+    unavailable?: boolean;
+    validate?: JaypieHandlerValidate[] | JaypieHandlerValidate;
+}
+type ExpressHandler<T> = (req: Request, res: Response, ...params: unknown[]) => Promise<T>;
+declare function expressHandler<T>(handler: ExpressHandler<T>, options?: ExpressHandlerOptions): ExpressHandler<T>;
+declare function expressHandler<T>(options: ExpressHandlerOptions, handler: ExpressHandler<T>): ExpressHandler<T>;
+
+declare const httpHandler: (statusCode?: number, context?: ExpressHandlerOptions) => ((req: Request, res: Response) => Promise<Record<string, unknown> | null>);
+
+type JaypieStreamHandlerSetup = (req: Request, res: Response) => Promise<void> | void;
+type JaypieStreamHandlerTeardown = (req: Request, res: Response) => Promise<void> | void;
+type JaypieStreamHandlerValidate = (req: Request, res: Response) => Promise<boolean | void> | boolean | void;
+type ExpressStreamHandlerLocals = (req: Request, res: Response) => Promise<unknown> | unknown;
+interface ExpressStreamHandlerOptions {
+    chaos?: string;
+    contentType?: string;
+    format?: StreamFormat;
+    locals?: Record<string, unknown | ExpressStreamHandlerLocals>;
+    name?: string;
+    secrets?: string[];
+    setup?: JaypieStreamHandlerSetup[] | JaypieStreamHandlerSetup;
+    teardown?: JaypieStreamHandlerTeardown[] | JaypieStreamHandlerTeardown;
+    unavailable?: boolean;
+    validate?: JaypieStreamHandlerValidate[] | JaypieStreamHandlerValidate;
+}
+/**
+ * Streaming Express handler function signature.
+ * Handler should write to the response stream and not return a value.
+ */
+type ExpressStreamHandler = (req: Request, res: Response, ...params: unknown[]) => Promise<void>;
+/**
+ * Creates a streaming Express handler that sets up SSE headers and allows
+ * streaming responses. The handler receives the standard req/res and should
+ * write to res.write() directly.
+ *
+ * Usage:
+ * ```ts
+ * app.get('/stream', expressStreamHandler(async (req, res) => {
+ *   const llmStream = llm.stream("Hello");
+ *   await createExpressStream(llmStream, res);
+ * }));
+ * ```
+ *
+ * The handler sets appropriate SSE headers automatically:
+ * - Content-Type: text/event-stream
+ * - Cache-Control: no-cache
+ * - Connection: keep-alive
+ * - X-Accel-Buffering: no (disables nginx buffering)
+ */
+declare function expressStreamHandler(handler: ExpressStreamHandler, options?: ExpressStreamHandlerOptions): ExpressStreamHandler;
+declare function expressStreamHandler(options: ExpressStreamHandlerOptions, handler: ExpressStreamHandler): ExpressStreamHandler;
+
+/**
+ * Get the current invoke UUID from Lambda context.
+ * Works with Jaypie Lambda adapter (createLambdaHandler/createLambdaStreamHandler).
+ *
+ * @param req - Optional Express request object. Used to extract context
+ *              from Jaypie adapter's _lambdaContext.
+ * @returns The AWS request ID or undefined if not in Lambda context
+ */
+declare function getCurrentInvokeUuid(req?: Request): string | undefined;
+
+interface RequestSummary {
+    baseUrl: string;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    query: Request["query"];
+    url: string;
+}
+declare function summarizeRequest(req: Request): RequestSummary;
+
+interface EchoResponse {
+    req: ReturnType<typeof summarizeRequest>;
+}
+
+declare const badRequestRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const echoRoute: (req: express.Request, res: express.Response) => Promise<EchoResponse>;
+declare const forbiddenRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const goneRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const methodNotAllowedRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const noContentRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const notFoundRoute: (req: express.Request, res: express.Response) => Promise<Record<string, unknown> | null>;
+declare const notImplementedRoute: (req: express.Request, res: express.Response, ...params: unknown[]) => Promise<unknown>;
+
+export { EXPRESS, LambdaRequest, LambdaResponseBuffered, LambdaResponseStreaming, badRequestRoute, _default as cors, createLambdaHandler, createLambdaStreamHandler, echoRoute, expressHandler, httpHandler as expressHttpCodeHandler, expressStreamHandler, fabricApiResponse, forbiddenRoute, getCurrentInvoke, getCurrentInvokeUuid, goneRoute, methodNotAllowedRoute, noContentRoute, notFoundRoute, notImplementedRoute };
+export type { ApiGatewayV1Event, CorsConfig, CreateLambdaHandlerOptions, ExpressHandlerLocals, ExpressHandlerOptions, ExpressStreamHandler, ExpressStreamHandlerLocals, ExpressStreamHandlerOptions, FunctionUrlEvent, JaypieHandlerSetup, JaypieHandlerTeardown, JaypieHandlerValidate, JaypieStreamHandlerSetup, JaypieStreamHandlerTeardown, JaypieStreamHandlerValidate, LambdaContext, LambdaEvent, LambdaHandler, LambdaResponse, LambdaStreamHandler, ResponseStream };

package/dist/esm/index.js

@@ -1073,9 +1073,11 @@ function createLambdaHandler(app, _options) {
             return result;
         }
         catch (error) {
-            // Log any unhandled errors
+            // console, not log: must reach CloudWatch even if the logger itself is broken
+            // eslint-disable-next-line no-console
             console.error("[createLambdaHandler] Unhandled error:", error);
             if (error instanceof Error) {
+                // eslint-disable-next-line no-console
                 console.error("[createLambdaHandler] Stack:", error.stack);
             }
             // Return a proper error response instead of throwing
@@ -1158,7 +1160,8 @@ function createLambdaStreamHandler(app, _options) {
 //
 const EXPRESS = {
     PATH: {
-        ANY: "*",
+        // RegExp matches all paths in Express 4 and 5; "*" throws in 5, "/{*splat}" throws in 4
+        ANY: /(.*)/,
         ID: "/:id",
         ROOT: /^\/?$/,
     },
@@ -1454,6 +1457,10 @@ function getCurrentInvokeUuid(req) {
     return getJaypieAdapterUuid();
 }
 
+//
+//
+// Helpers
+//
 /**
  * Safely set a header value on response.
  * Handles both Express Response and Lambda adapter responses.
@@ -2020,6 +2027,7 @@ function expressHandler(handlerOrOptions, optionsOrHandler) {
             const errorStack = error instanceof Error
                 ? error.stack
                 : new Error("Stack trace").stack?.replace("Error: Stack trace", `Error: ${errorMessage}`);
+            // eslint-disable-next-line no-console -- raw stack must reach CloudWatch even if the logger is broken
             console.error("Express response error stack trace:", errorStack);
             log.fatal(`Express encountered an error while sending the response: ${errorMessage}`);
             log.var({ responseError: error });