@emmett-community/emmett-expressjs-with-openapi 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import express, { Request, Response, Router, Application, NextFunction } from 'express';
+import http from 'http';
+import { ProblemDocument } from 'http-problem-details';
+import * as _event_driven_io_emmett from '@event-driven-io/emmett';
+import { Brand, Event, TestEventStream, EventStore } from '@event-driven-io/emmett';
+import supertest, { Test, Response as Response$1 } from 'supertest';
+import TestAgent from 'supertest/lib/agent';
+
+/**
+ * OpenAPI v3 Document type (to avoid requiring express-openapi-validator types directly)
+ */
+type OpenAPIV3Document = any;
+/**
+ * Imported handler modules, keyed by module name.
+ * Automatically populated by the framework when operationHandlers is configured.
+ */
+type ImportedHandlerModules = Record<string, any>;
+/**
+ * Security handlers for custom authentication/authorization logic.
+ * Maps security scheme names to handler functions.
+ *
+ * @see https://cdimascio.github.io/express-openapi-validator-documentation/usage-validate-security/
+ */
+type SecurityHandlers = Record<string, (req: any, scopes: string[], schema: any) => boolean | Promise<boolean>>;
+/**
+ * Configuration options for express-openapi-validator middleware.
+ * This allows optional validation of API requests and responses against an OpenAPI specification.
+ *
+ * @see https://cdimascio.github.io/express-openapi-validator-documentation/
+ */
+type OpenApiValidatorOptions = {
+    /**
+     * Path to the OpenAPI specification file (JSON or YAML)
+     * or an OpenAPI specification object.
+     */
+    apiSpec: string | OpenAPIV3Document;
+    /**
+     * Determines whether the validator should validate requests.
+     * Can be a boolean or an object with detailed request validation options.
+     * @default true
+     * @see https://cdimascio.github.io/express-openapi-validator-documentation/usage-validate-requests/
+     */
+    validateRequests?: boolean | {
+        /**
+         * Allow unknown query parameters (not defined in the spec).
+         * @default false
+         */
+        allowUnknownQueryParameters?: boolean;
+        /**
+         * Coerce types in request parameters.
+         * @default true
+         */
+        coerceTypes?: boolean | 'array';
+        /**
+         * Remove additional properties not defined in the spec.
+         * @default false
+         */
+        removeAdditional?: boolean | 'all' | 'failing';
+    };
+    /**
+     * Determines whether the validator should validate responses.
+     * Can be a boolean or an object with detailed response validation options.
+     * @default false
+     * @see https://cdimascio.github.io/express-openapi-validator-documentation/usage-validate-responses/
+     */
+    validateResponses?: boolean | {
+        /**
+         * Remove additional properties from responses not defined in the spec.
+         * @default false
+         */
+        removeAdditional?: boolean | 'all' | 'failing';
+        /**
+         * Coerce types in responses.
+         * @default true
+         */
+        coerceTypes?: boolean;
+        /**
+         * Callback to handle response validation errors.
+         */
+        onError?: (error: any, body: any, req: any) => void;
+    };
+    /**
+     * Determines whether the validator should validate security.
+     * Can be a boolean or an object with security handlers.
+     * @default true
+     * @see https://cdimascio.github.io/express-openapi-validator-documentation/usage-validate-security/
+     */
+    validateSecurity?: boolean | {
+        /**
+         * Custom security handlers for authentication/authorization.
+         */
+        handlers?: SecurityHandlers;
+    };
+    /**
+     * Defines how the validator should validate formats.
+     * When true, uses ajv-formats for format validation.
+     * When false, format validation is disabled.
+     * Can also be 'fast' or 'full' for different validation modes.
+     * @default true
+     */
+    validateFormats?: boolean | 'fast' | 'full';
+    /**
+     * The base path to the operation handlers directory.
+     * When set to a path, automatically wires OpenAPI operations to handler functions
+     * based on operationId or x-eov-operation-id.
+     * When false, operation handlers are disabled (manual routing required).
+     * @default false
+     * @see https://cdimascio.github.io/express-openapi-validator-documentation/guide-operation-handlers/
+     */
+    operationHandlers?: string | false | {
+        /**
+         * Base path to operation handlers directory.
+         */
+        basePath?: string;
+        /**
+         * Resolver function to map operationId to handler module path.
+         */
+        resolver?: (handlersPath: string, route: string, apiDoc: OpenAPIV3Document) => string;
+    };
+    /**
+     * Paths or pattern to ignore during validation.
+     * @default undefined
+     */
+    ignorePaths?: RegExp | ((path: string) => boolean);
+    /**
+     * Validate the OpenAPI specification itself.
+     * @default true
+     */
+    validateApiSpec?: boolean;
+    /**
+     * $ref parser configuration for handling OpenAPI references.
+     * @default undefined
+     */
+    $refParser?: {
+        mode: 'bundle' | 'dereference';
+    };
+    /**
+     * Serve the OpenAPI specification at a specific path.
+     * When set to a string, the spec will be served at that path.
+     * When false, the spec will not be served.
+     * @default false
+     * @example '/api-docs/openapi.json'
+     */
+    serveSpec?: string | false;
+    /**
+     * File upload configuration options.
+     * @see https://cdimascio.github.io/express-openapi-validator-documentation/usage-file-uploads/
+     */
+    fileUploader?: boolean | {
+        /**
+         * Destination directory for uploaded files.
+         */
+        dest?: string;
+        /**
+         * File size limit in bytes.
+         */
+        limits?: {
+            fileSize?: number;
+            files?: number;
+        };
+    };
+    /**
+     * Optional callback to initialize operation handlers with dependencies.
+     * Called before the OpenAPI validator middleware is configured.
+     *
+     * The framework automatically imports handler modules referenced in your
+     * OpenAPI spec (via x-eov-operation-handler) and passes them as the first parameter.
+     *
+     * @param handlers - Auto-imported handler modules, keyed by module name
+     * @returns void or a Promise that resolves when initialization is complete
+     *
+     * @example
+     * ```typescript
+     * // With automatic import (recommended)
+     * initializeHandlers: async (handlers) => {
+     *   handlers.shoppingCarts.initializeHandlers(eventStore, messageBus, getUnitPrice, getCurrentTime);
+     * }
+     *
+     * // Manual import (still supported for backward compatibility)
+     * import * as handlersModule from './handlers/shoppingCarts';
+     * import { registerHandlerModule } from '@emmett-community/emmett-expressjs-with-openapi';
+     * initializeHandlers: () => {
+     *   const handlersPath = path.join(__dirname, './handlers/shoppingCarts');
+     *   registerHandlerModule(handlersPath, handlersModule);
+     *   handlersModule.initializeHandlers(eventStore, messageBus, getUnitPrice, getCurrentTime);
+     * }
+     * ```
+     */
+    initializeHandlers?: (handlers?: ImportedHandlerModules) => void | Promise<void>;
+};
+/**
+ * Helper function to create OpenAPI validator configuration with sensible defaults.
+ *
+ * @param apiSpec - Path to OpenAPI spec file or OpenAPI document object
+ * @param options - Additional validator options
+ * @returns Complete OpenApiValidatorOptions configuration
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default options
+ * const validatorOptions = createOpenApiValidatorOptions('./openapi.yaml');
+ *
+ * // With response validation enabled
+ * const validatorOptions = createOpenApiValidatorOptions('./openapi.yaml', {
+ *   validateResponses: true
+ * });
+ *
+ * // With custom security handlers
+ * const validatorOptions = createOpenApiValidatorOptions('./openapi.yaml', {
+ *   validateSecurity: {
+ *     handlers: {
+ *       bearerAuth: async (req, scopes) => {
+ *         // Custom authentication logic
+ *         return true;
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Serving the spec at /api-docs
+ * const validatorOptions = createOpenApiValidatorOptions('./openapi.yaml', {
+ *   serveSpec: '/api-docs/openapi.json'
+ * });
+ *
+ * // With dependency injection for operation handlers
+ * type ShoppingCartDeps = {
+ *   eventStore: EventStore;
+ *   messageBus: EventsPublisher;
+ *   getUnitPrice: (productId: string) => Promise<number>;
+ *   getCurrentTime: () => Date;
+ * };
+ *
+ * const validatorOptions = createOpenApiValidatorOptions<ShoppingCartDeps>(
+ *   './openapi.yaml',
+ *   {
+ *     operationHandlers: './handlers',
+ *     initializeHandlers: (deps) => {
+ *       initializeHandlers(
+ *         deps.eventStore,
+ *         deps.messageBus,
+ *         deps.getUnitPrice,
+ *         deps.getCurrentTime
+ *       );
+ *     }
+ *   }
+ * );
+ *
+ * const app = getApplication({
+ *   apis: [myApi],
+ *   openApiValidator: validatorOptions
+ * });
+ * ```
+ */
+declare const createOpenApiValidatorOptions: (apiSpec: string | OpenAPIV3Document, options?: Partial<Omit<OpenApiValidatorOptions, "apiSpec">>) => OpenApiValidatorOptions;
+/**
+ * Type guard to check if express-openapi-validator is available
+ */
+declare const isOpenApiValidatorAvailable: () => Promise<boolean>;
+
+declare const HeaderNames: {
+    IF_MATCH: string;
+    IF_NOT_MATCH: string;
+    ETag: string;
+};
+type WeakETag = Brand<`W/${string}`, 'ETag'>;
+type ETag = Brand<string, 'ETag'>;
+declare const WeakETagRegex: RegExp;
+declare const enum ETagErrors {
+    WRONG_WEAK_ETAG_FORMAT = "WRONG_WEAK_ETAG_FORMAT",
+    MISSING_IF_MATCH_HEADER = "MISSING_IF_MATCH_HEADER",
+    MISSING_IF_NOT_MATCH_HEADER = "MISSING_IF_NOT_MATCH_HEADER"
+}
+declare const isWeakETag: (etag: ETag) => etag is WeakETag;
+declare const getWeakETagValue: (etag: ETag) => string;
+declare const toWeakETag: (value: number | bigint | string) => WeakETag;
+declare const getETagFromIfMatch: (request: Request) => ETag;
+declare const getETagFromIfNotMatch: (request: Request) => ETag;
+declare const setETag: (response: Response, etag: ETag) => void;
+declare const getETagValueFromIfMatch: (request: Request) => string;
+
+type ErrorToProblemDetailsMapping = (error: Error, request: Request) => ProblemDocument | undefined;
+type HttpResponseOptions = {
+    body?: unknown;
+    location?: string;
+    eTag?: ETag;
+};
+declare const DefaultHttpResponseOptions: HttpResponseOptions;
+type HttpProblemResponseOptions = {
+    location?: string;
+    eTag?: ETag;
+} & Omit<HttpResponseOptions, 'body'> & ({
+    problem: ProblemDocument;
+} | {
+    problemDetails: string;
+});
+declare const DefaultHttpProblemResponseOptions: HttpProblemResponseOptions;
+type CreatedHttpResponseOptions = ({
+    createdId: string;
+} | {
+    createdId?: string;
+    url: string;
+}) & HttpResponseOptions;
+declare const sendCreated: (response: Response, { eTag, ...options }: CreatedHttpResponseOptions) => void;
+type AcceptedHttpResponseOptions = {
+    location: string;
+} & HttpResponseOptions;
+declare const sendAccepted: (response: Response, options: AcceptedHttpResponseOptions) => void;
+type NoContentHttpResponseOptions = Omit<HttpResponseOptions, 'body'>;
+declare const send: (response: Response, statusCode: number, options?: HttpResponseOptions) => void;
+declare const sendProblem: (response: Response, statusCode: number, options?: HttpProblemResponseOptions) => void;
+
+type WebApiSetup = (router: Router) => void;
+type ApplicationOptions = {
+    apis?: WebApiSetup[];
+    mapError?: ErrorToProblemDetailsMapping;
+    enableDefaultExpressEtag?: boolean;
+    disableJsonMiddleware?: boolean;
+    disableUrlEncodingMiddleware?: boolean;
+    disableProblemDetailsMiddleware?: boolean;
+    /**
+     * Optional OpenAPI validator configuration.
+     * When provided, enables request/response validation against an OpenAPI specification.
+     * Requires the 'express-openapi-validator' package to be installed.
+     *
+     * @see https://github.com/cdimascio/express-openapi-validator
+     * @example
+     * ```typescript
+     * import { getApplication, createOpenApiValidatorOptions } from '@event-driven-io/emmett-expressjs';
+     *
+     * type AppDeps = {
+     *   eventStore: EventStore;
+     *   messageBus: EventsPublisher;
+     * };
+     *
+     * const app = await getApplication({
+     *   openApiValidator: createOpenApiValidatorOptions<AppDeps>('./openapi.yaml', {
+     *     validateResponses: true,
+     *     operationHandlers: './handlers',
+     *     initializeHandlers: (deps) => {
+     *       initializeHandlers(deps.eventStore, deps.messageBus);
+     *     }
+     *   })
+     * });
+     * ```
+     */
+    openApiValidator?: OpenApiValidatorOptions;
+};
+declare const getApplication: (options: ApplicationOptions) => Promise<express.Application>;
+type StartApiOptions = {
+    port?: number;
+};
+declare const startAPI: (app: Application, options?: StartApiOptions) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+
+type HttpHandler<RequestType extends Request> = (request: RequestType) => Promise<HttpResponse> | HttpResponse;
+declare const on: <RequestType extends Request>(handle: HttpHandler<RequestType>) => (request: RequestType, response: Response, _next: NextFunction) => Promise<void>;
+declare const OK: (options?: HttpResponseOptions) => HttpResponse;
+declare const Created: (options: CreatedHttpResponseOptions) => HttpResponse;
+declare const Accepted: (options: AcceptedHttpResponseOptions) => HttpResponse;
+declare const NoContent: (options?: NoContentHttpResponseOptions) => HttpResponse;
+type HttpResponse = (response: Response) => void;
+declare const HttpResponse: (statusCode: number, options?: HttpResponseOptions) => HttpResponse;
+declare const BadRequest: (options?: HttpProblemResponseOptions) => HttpResponse;
+declare const Forbidden: (options?: HttpProblemResponseOptions) => HttpResponse;
+declare const NotFound: (options?: HttpProblemResponseOptions) => HttpResponse;
+declare const Conflict: (options?: HttpProblemResponseOptions) => HttpResponse;
+declare const PreconditionFailed: (options: HttpProblemResponseOptions) => HttpResponse;
+declare const HttpProblem: (statusCode: number, options?: HttpProblemResponseOptions) => HttpResponse;
+
+type TestRequest = (request: TestAgent<supertest.Test>) => Test;
+declare const existingStream: <EventType extends Event = Event>(streamId: string, events: EventType[]) => TestEventStream<EventType>;
+type ResponseAssert = (response: Response$1) => boolean | void;
+type ApiSpecificationAssert<EventType extends Event = Event> = TestEventStream<EventType>[] | ResponseAssert | [ResponseAssert, ...TestEventStream<EventType>[]];
+declare const expect: <EventType extends Event = Event>(streamId: string, events: EventType[]) => TestEventStream<EventType>;
+declare const expectNewEvents: <EventType extends Event = Event>(streamId: string, events: EventType[]) => TestEventStream<EventType>;
+declare const expectResponse: <Body = unknown>(statusCode: number, options?: {
+    body?: Body;
+    headers?: {
+        [index: string]: string;
+    };
+}) => (response: Response$1) => void;
+declare const expectError: (errorCode: number, problemDetails?: Partial<ProblemDocument>) => (response: Response$1) => void;
+type ApiSpecification<EventType extends Event = Event> = (...givenStreams: TestEventStream<EventType>[]) => {
+    when: (setupRequest: TestRequest) => {
+        then: (verify: ApiSpecificationAssert<EventType>) => Promise<void>;
+    };
+};
+declare const ApiSpecification: {
+    for: <EventType extends Event = Event, Store extends EventStore<_event_driven_io_emmett.ReadEventMetadataWithGlobalPosition> = EventStore<_event_driven_io_emmett.ReadEventMetadataWithGlobalPosition<bigint>>>(getEventStore: () => Store, getApplication: (eventStore: Store) => Application | Promise<Application>) => ApiSpecification<EventType>;
+};
+
+type E2EResponseAssert = (response: Response$1) => boolean | void;
+type ApiE2ESpecificationAssert = [E2EResponseAssert];
+type ApiE2ESpecification = (...givenRequests: TestRequest[]) => {
+    when: (setupRequest: TestRequest) => {
+        then: (verify: ApiE2ESpecificationAssert) => Promise<void>;
+    };
+};
+declare const ApiE2ESpecification: {
+    for: <Store extends EventStore = EventStore<_event_driven_io_emmett.AnyRecordedMessageMetadata>>(getEventStore: () => Store, getApplication: (eventStore: Store) => Application | Promise<Application>) => ApiE2ESpecification;
+};
+
+/**
+ * ESM Resolver for express-openapi-validator operation handlers.
+ *
+ * INTERNAL MODULE - Not part of public API.
+ *
+ * PROBLEM:
+ * When using TypeScript runtime (tsx) with express-openapi-validator's operationHandlers:
+ * - Our code uses `import()` to load handlers (ESM)
+ * - express-openapi-validator uses `require()` to load handlers (CJS)
+ * - Node.js maintains separate module caches for ESM and CJS
+ * - This creates TWO separate instances of the same handler module
+ * - Dependencies injected via module-level variables in one instance don't reach the other
+ *
+ * SOLUTION:
+ * This module monkey-patches Module.prototype.require to intercept when
+ * express-openapi-validator loads operation handlers and forces it to use
+ * dynamic import() instead of require(). This ensures both sides share the
+ * same ESM module instance, allowing module-level variables to work correctly.
+ *
+ * USAGE:
+ * This module is automatically activated by getApplication() when operationHandlers
+ * are configured. Applications don't need to import or configure anything.
+ *
+ * LIMITATIONS:
+ * - Relies on heuristic detection (caller path includes 'express-openapi-validator')
+ * - May break if express-openapi-validator changes its internal loading mechanism
+ * - Adds "magic" behavior that may not be immediately obvious to developers
+ *
+ * FUTURE:
+ * If express-openapi-validator migrates to native ESM, this resolver becomes
+ * unnecessary and will safely become a no-op.
+ */
+/**
+ * Registers a pre-loaded ESM module so it can be returned synchronously
+ * when express-openapi-validator tries to require() it.
+ */
+declare const registerHandlerModule: (modulePath: string, moduleExports: any) => void;
+
+export { Accepted, type AcceptedHttpResponseOptions, ApiE2ESpecification, type ApiE2ESpecificationAssert, ApiSpecification, type ApiSpecificationAssert, type ApplicationOptions, BadRequest, Conflict, Created, type CreatedHttpResponseOptions, DefaultHttpProblemResponseOptions, DefaultHttpResponseOptions, type E2EResponseAssert, type ETag, ETagErrors, type ErrorToProblemDetailsMapping, Forbidden, HeaderNames, type HttpHandler, HttpProblem, type HttpProblemResponseOptions, HttpResponse, type HttpResponseOptions, type ImportedHandlerModules, NoContent, type NoContentHttpResponseOptions, NotFound, OK, type OpenAPIV3Document, type OpenApiValidatorOptions, PreconditionFailed, type ResponseAssert, type SecurityHandlers, type StartApiOptions, type TestRequest, type WeakETag, WeakETagRegex, type WebApiSetup, createOpenApiValidatorOptions, existingStream, expect, expectError, expectNewEvents, expectResponse, getApplication, getETagFromIfMatch, getETagFromIfNotMatch, getETagValueFromIfMatch, getWeakETagValue, isOpenApiValidatorAvailable, isWeakETag, on, registerHandlerModule, send, sendAccepted, sendCreated, sendProblem, setETag, startAPI, toWeakETag };