@schmock/core 2.1.0 → 2.1.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./schmock.d.ts" />
 /**
  * Create a new Schmock mock instance with callable API.
  *

package/dist/schmock.d.ts

@@ -0,0 +1,692 @@
+/**
+ * Schmock - Schema-driven mock API generator with callable API
+ * @packageDocumentation
+ */
+
+declare namespace Schmock {
+  type JSONSchema7 = import("json-schema").JSONSchema7;
+  /**
+   * HTTP methods supported by Schmock
+   */
+  type HttpMethod =
+    | "GET"
+    | "POST"
+    | "PUT"
+    | "DELETE"
+    | "PATCH"
+    | "HEAD"
+    | "OPTIONS";
+
+  /**
+   * Route key format: 'METHOD /path'
+   *
+   * @example
+   * 'GET /users'
+   * 'POST /users/:id'
+   * 'DELETE /api/posts/:postId/comments/:commentId'
+   */
+  type RouteKey = `${HttpMethod} ${string}`;
+  
+  /**
+   * Plugin interface for extending Schmock functionality
+   */
+  interface Plugin {
+    /** Unique plugin identifier */
+    name: string;
+    /** Plugin version (semver) */
+    version?: string;
+
+    /**
+     * Called once when the plugin is added via .pipe()
+     * Use this to register routes or configure the instance at setup time
+     * @param instance - The callable mock instance
+     */
+    install?(instance: CallableMockInstance): void;
+
+    /**
+     * Process the request through this plugin
+     * First plugin to set response becomes the generator, others transform
+     * @param context - Plugin context with request details
+     * @param response - Response from previous plugin (if any)
+     * @returns Updated context and response
+     */
+    process(context: PluginContext, response?: unknown): PluginResult | Promise<PluginResult>;
+
+    /**
+     * Called when an error occurs
+     * Can handle, transform, or suppress errors
+     * @param error - The error that occurred
+     * @param context - Plugin context
+     * @returns Modified error, response data, or void to continue error propagation
+     */
+    onError?(error: Error, context: PluginContext): Error | ResponseResult | void | Promise<Error | ResponseResult | void>;
+  }
+
+  /**
+   * Alias for response body type
+   */
+  type ResponseBody = unknown;
+
+  /**
+   * Result returned by plugin process method
+   */
+  interface PluginResult {
+    /** Updated context */
+    context: PluginContext;
+    /** Response data (if generated/modified) */
+    response?: unknown;
+  }
+
+  /**
+   * Context passed through plugin pipeline
+   */
+  interface PluginContext {
+    /** Request path */
+    path: string;
+    /** Matched route configuration */
+    route: RouteConfig;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route parameters */
+    params: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body */
+    body?: unknown;
+    /** Shared state between plugins for this request */
+    state: Map<string, unknown>;
+    /** Route-specific state */
+    routeState?: Record<string, unknown>;
+  }
+
+  // ===== Callable API Types =====
+
+  /**
+   * Global configuration options for the mock instance
+   */
+  interface GlobalConfig {
+    /** Base path prefix for all routes */
+    namespace?: string;
+    /** Response delay in ms, or [min, max] for random delay */
+    delay?: number | [number, number];
+    /** Enable debug mode for detailed logging */
+    debug?: boolean;
+    /** Initial shared state object */
+    state?: Record<string, unknown>;
+    /**
+     * Maximum number of requests retained in history (FIFO eviction).
+     * Defaults to unbounded; set this to cap memory growth in long-running servers.
+     */
+    maxHistorySize?: number;
+  }
+
+  /**
+   * Route-specific configuration options
+   */
+  interface RouteConfig {
+    /** MIME type for content type validation (auto-detected if not provided) */
+    contentType?: string;
+    /** Per-route response delay in ms, or [min, max] for random delay (overrides global) */
+    delay?: number | [number, number];
+    /** Additional route-specific options */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Generator types that can be passed to route definitions
+   */
+  type Generator = 
+    | GeneratorFunction
+    | StaticData
+    | JSONSchema7;
+
+  /**
+   * Function that generates responses
+   */
+  type GeneratorFunction = (context: RequestContext) => ResponseResult | Promise<ResponseResult>;
+
+  /**
+   * Static data (non-function) that gets returned as-is
+   */
+  type StaticData = string | number | boolean | null | undefined | Record<string, unknown> | unknown[];
+
+  /**
+   * Context passed to generator functions
+   */
+  interface RequestContext {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request path */
+    path: string;
+    /** Route parameters (e.g., :id) */
+    params: Record<string, string>;
+    /** Query string parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (for POST, PUT, PATCH) */
+    body?: unknown;
+    /** Shared mutable state */
+    state: Record<string, unknown>;
+  }
+
+  /**
+   * Response result types:
+   * - Any value: returns as 200 OK
+   * - [status, body]: custom status with body
+   * - [status, body, headers]: custom status, body, and headers
+   */
+  type ResponseResult =
+    | ResponseBody
+    | [number, unknown]
+    | [number, unknown, Record<string, string>];
+
+  /**
+   * Response object returned by handle method
+   */
+  interface Response {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+  }
+
+  /**
+   * Options for handle method
+   */
+  interface RequestOptions {
+    headers?: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string>;
+  }
+
+  /**
+   * Record of a single request handled by the mock
+   */
+  interface RequestRecord {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request path (without namespace) */
+    path: string;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body */
+    body: unknown;
+    /** Unix timestamp (ms) when request was handled */
+    timestamp: number;
+    /** Response returned for this request */
+    response: { status: number; body: unknown };
+  }
+
+  /**
+   * Main callable mock instance interface
+   */
+  interface CallableMockInstance {
+    /**
+     * Define a route by calling the instance directly
+     * 
+     * @param route - Route pattern in format 'METHOD /path'
+     * @param generator - Response generator (function, static data, or schema)
+     * @param config - Route-specific configuration
+     * @returns The same instance for method chaining
+     * 
+     * @example
+     * ```typescript
+     * const mock = schmock()
+     * mock('GET /users', () => [...users], { contentType: 'application/json' })
+     * mock('POST /users', userData, { contentType: 'application/json' })
+     * ```
+     */
+    (route: RouteKey, generator: Generator, config?: RouteConfig): CallableMockInstance;
+
+    /**
+     * Add a plugin to the pipeline
+     * 
+     * @param plugin - Plugin to add to the pipeline
+     * @returns The same instance for method chaining
+     * 
+     * @example
+     * ```typescript
+     * mock('GET /users', generator, config)
+     *   .pipe(authPlugin())
+     *   .pipe(corsPlugin())
+     * ```
+     */
+    pipe(plugin: Plugin): CallableMockInstance;
+
+    /**
+     * Handle a request and return a response
+     *
+     * @param method - HTTP method
+     * @param path - Request path
+     * @param options - Request options (headers, body, query)
+     * @returns Promise resolving to response object
+     *
+     * @example
+     * ```typescript
+     * const response = await mock.handle('GET', '/users', {
+     *   headers: { 'Authorization': 'Bearer token' }
+     * })
+     * ```
+     */
+    handle(method: HttpMethod, path: string, options?: RequestOptions): Promise<Response>;
+
+    // ===== Request Spy / History API =====
+
+    /**
+     * Get all recorded requests, optionally filtered by method and path
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Array of request records
+     */
+    history(): RequestRecord[];
+    history(method: HttpMethod, path: string): RequestRecord[];
+
+    /**
+     * Check if any request was made, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns true if at least one matching request was recorded
+     */
+    called(): boolean;
+    called(method: HttpMethod, path: string): boolean;
+
+    /**
+     * Get the number of recorded requests, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Number of matching requests
+     */
+    callCount(): number;
+    callCount(method: HttpMethod, path: string): number;
+
+    /**
+     * Get the most recent request, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Most recent matching request record, or undefined
+     */
+    lastRequest(): RequestRecord | undefined;
+    lastRequest(method: HttpMethod, path: string): RequestRecord | undefined;
+
+    // ===== Reset / Lifecycle =====
+
+    /**
+     * Clear all routes, state, plugins, and history
+     */
+    reset(): void;
+
+    /**
+     * Clear only request history, keep routes and state
+     */
+    resetHistory(): void;
+
+    /**
+     * Clear only state, keep routes and history
+     */
+    resetState(): void;
+
+    // ===== Lifecycle Events =====
+
+    /**
+     * Register an event listener
+     */
+    on<E extends SchmockEvent>(event: E, listener: (data: SchmockEventMap[E]) => void): CallableMockInstance;
+
+    /**
+     * Remove an event listener
+     */
+    off<E extends SchmockEvent>(event: E, listener: (data: SchmockEventMap[E]) => void): CallableMockInstance;
+
+    // ===== Introspection =====
+
+    /**
+     * Get all registered routes as an array of route info objects
+     */
+    getRoutes(): RouteInfo[];
+
+    /**
+     * Get the current shared state object
+     */
+    getState(): Record<string, unknown>;
+
+    // ===== Standalone Server =====
+
+    /**
+     * Start a standalone HTTP server
+     *
+     * @param port - Port to listen on (0 for random)
+     * @param hostname - Hostname to bind to (default: "127.0.0.1")
+     * @returns Promise resolving to server info with actual port and hostname
+     * @throws If the server is already running
+     */
+    listen(port?: number, hostname?: string): Promise<ServerInfo>;
+
+    /**
+     * Stop the standalone server (idempotent, no-op if not running)
+     */
+    close(): void;
+
+    // ===== Fetch Interceptor =====
+
+    /**
+     * Intercept globalThis.fetch and route requests through this mock.
+     * Client-side equivalent of listen().
+     *
+     * @param options - Intercept configuration
+     * @returns Handle with restore() to stop intercepting
+     * @throws If already intercepting (call restore() first)
+     */
+    intercept(options?: InterceptOptions): InterceptHandle;
+  }
+
+  /**
+   * Information about a running standalone server
+   */
+  interface ServerInfo {
+    /** Port the server is listening on */
+    port: number;
+    /** Hostname the server is bound to */
+    hostname: string;
+  }
+
+  // ===== Response Helpers =====
+
+  interface PaginateOptions {
+    page?: number;
+    pageSize?: number;
+  }
+
+  interface PaginatedResponse<T> {
+    data: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  }
+
+  // ===== Adapter Types =====
+
+  interface AdapterRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    query: Record<string, string>;
+  }
+
+  interface AdapterResponse {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+  }
+
+  interface InterceptOptions {
+    /**
+     * Only intercept URLs matching this base.
+     *
+     * Two modes:
+     * - Path form ("/api"): match request pathnames whose prefix is the
+     *   base path (with a segment-boundary check, so "/api" never
+     *   matches "/apiv2").
+     * - Origin form ("https://api.example.com" or
+     *   "https://api.example.com/v1"): require the request origin to
+     *   match the base origin AND, if a base path is present, the
+     *   request pathname to start with it. Relative-URL fetches
+     *   (no origin) won't match an origin-form base.
+     */
+    baseUrl?: string;
+    /** Pass unmatched routes to real fetch (default: true) */
+    passthrough?: boolean;
+    /** Modify request before Schmock handles it */
+    beforeRequest?: (
+      request: AdapterRequest,
+    ) => AdapterRequest | void | Promise<AdapterRequest | void>;
+    /** Modify response before returning to caller */
+    beforeResponse?: (
+      response: AdapterResponse,
+      request: AdapterRequest,
+    ) => AdapterResponse | void | Promise<AdapterResponse | void>;
+    /** Format errors into custom response bodies */
+    errorFormatter?: (error: Error) => unknown;
+  }
+
+  interface InterceptHandle {
+    /** Stop intercepting and restore original fetch */
+    restore(): void;
+    /** Whether this interceptor is currently active */
+    readonly active: boolean;
+  }
+
+  // ===== Lifecycle Events =====
+
+  interface RequestStartEvent {
+    method: HttpMethod;
+    path: string;
+    headers: Record<string, string>;
+  }
+
+  interface RequestMatchEvent {
+    method: HttpMethod;
+    path: string;
+    routePath: string;
+    params: Record<string, string>;
+  }
+
+  interface RequestNotFoundEvent {
+    method: HttpMethod;
+    path: string;
+  }
+
+  interface RequestEndEvent {
+    method: HttpMethod;
+    path: string;
+    status: number;
+    duration: number;
+  }
+
+  type SchmockEventMap = {
+    "request:start": RequestStartEvent;
+    "request:match": RequestMatchEvent;
+    "request:notfound": RequestNotFoundEvent;
+    "request:end": RequestEndEvent;
+  };
+
+  type SchmockEvent = keyof SchmockEventMap;
+
+  // ===== Introspection Types =====
+
+  interface RouteInfo {
+    method: HttpMethod;
+    path: string;
+    hasParams: boolean;
+  }
+
+  // ===== OpenAPI Plugin Types =====
+
+  /**
+   * Per-resource configuration override for OpenAPI plugin
+   */
+  interface ResourceOverride {
+    /** Override: which property in list response holds the items array (e.g. "data") */
+    listWrapProperty?: string;
+    /** Override: force flat array for list (ignores any wrapper in the spec) */
+    listFlat?: boolean;
+    /** Override: JSON Schema for error responses (404, etc.) */
+    errorSchema?: JSONSchema7;
+  }
+
+  /**
+   * Response header definition from an OpenAPI spec
+   */
+  interface ResponseHeaderDef {
+    schema?: JSONSchema7;
+    description: string;
+  }
+
+  /**
+   * Per-operation metadata auto-detected from spec or set via overrides
+   */
+  interface CrudOperationMeta {
+    /** Full success response schema (wrapper + items) */
+    responseSchema?: JSONSchema7;
+    /** Response headers from spec */
+    responseHeaders?: Record<string, ResponseHeaderDef>;
+    /** Error response schemas keyed by status code */
+    errorSchemas?: Map<number, JSONSchema7>;
+  }
+
+  // ===== Faker Plugin Types =====
+
+  /**
+   * Context for schema-based data generation
+   */
+  interface SchemaGenerationContext {
+    schema: JSONSchema7;
+    count?: number;
+    overrides?: Record<string, unknown>;
+    params?: Record<string, string>;
+    state?: Record<string, unknown>;
+    query?: Record<string, string>;
+    seed?: number;
+  }
+
+  /**
+   * Options for the faker plugin
+   */
+  interface FakerPluginOptions {
+    schema: JSONSchema7;
+    count?: number;
+    overrides?: Record<string, unknown>;
+    seed?: number;
+  }
+
+  // ===== Express Adapter Types =====
+
+  /**
+   * Override parts of a request before Schmock handles it
+   */
+  interface AdapterRequestOverride {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string>;
+  }
+
+  /**
+   * Configuration options for Express adapter
+   */
+  interface ExpressAdapterOptions {
+    errorFormatter?: (error: Error, req: unknown) => unknown;
+    passErrorsToNext?: boolean;
+    transformHeaders?: (
+      headers: Record<string, string | string[] | undefined>,
+    ) => Record<string, string>;
+    transformQuery?: (query: Record<string, unknown>) => Record<string, string>;
+    beforeRequest?: (
+      req: unknown,
+      res: unknown,
+    ) =>
+      | AdapterRequestOverride
+      | undefined
+      | Promise<AdapterRequestOverride | undefined>;
+    beforeResponse?: (
+      response: Response,
+      req: unknown,
+      res: unknown,
+    ) => Response | undefined | Promise<Response | undefined>;
+  }
+
+  // ===== Angular Adapter Types =====
+
+  /**
+   * Configuration options for Angular adapter
+   */
+  interface AngularAdapterOptions {
+    baseUrl?: string;
+    passthrough?: boolean;
+    errorFormatter?: (error: Error, request: unknown) => unknown;
+    transformRequest?: (request: unknown) => AdapterRequestOverride;
+    transformResponse?: (
+      response: Response,
+      request: unknown,
+    ) => Response;
+  }
+
+  // ===== OpenAPI Plugin Options =====
+
+  /**
+   * Options for the OpenAPI plugin
+   */
+  interface OpenApiOptions {
+    spec: string | object;
+    seed?: SeedConfig;
+    validateRequests?: boolean;
+    validateResponses?: boolean;
+    queryFeatures?: {
+      pagination?: boolean;
+      sorting?: boolean;
+      filtering?: boolean;
+    };
+    resources?: Record<string, ResourceOverride>;
+    debug?: boolean;
+    fakerSeed?: number;
+    security?: boolean;
+    /** Replace response schemas for specific routes. Key format: "METHOD /path" or "METHOD /path STATUS" */
+    schemas?: Record<string, import("json-schema").JSONSchema7>;
+    /** Called before generating a response body. Return a schema to replace the original, or void to keep it. */
+    onSchema?: (
+      schema: import("json-schema").JSONSchema7,
+      context: { method: string; path: string; params: Record<string, string>; query: Record<string, string>; headers: Record<string, string> },
+    ) => import("json-schema").JSONSchema7 | undefined;
+  }
+
+  /**
+   * Seed data source: inline array, file path, or auto-generate count
+   */
+  type SeedSource = unknown[] | string | { count: number };
+
+  /**
+   * Seed configuration mapping resource names to seed sources
+   */
+  type SeedConfig = Record<string, SeedSource>;
+
+  // ===== CLI Types =====
+
+  /**
+   * Options for the CLI server
+   */
+  interface CliOptions {
+    spec: string;
+    port?: number;
+    hostname?: string;
+    seed?: string;
+    cors?: boolean;
+    debug?: boolean;
+    fakerSeed?: number;
+    errors?: boolean;
+    watch?: boolean;
+    admin?: boolean;
+  }
+
+  /**
+   * Running CLI server instance
+   */
+  interface CliServer {
+    server: import("node:http").Server;
+    port: number;
+    hostname: string;
+    close(): void;
+  }
+
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/core",
   "description": "Core functionality for Schmock",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,7 @@
   "scripts": {
     "build": "bun build:lib && bun build:types",
     "build:lib": "bun build --minify --target node --outdir=dist src/index.ts",
-    "build:types": "rm -f tsconfig.tsbuildinfo && tsc --build",
+    "build:types": "rm -f tsconfig.tsbuildinfo && tsc --build && node scripts/embed-ambient-types.js",
     "pretest": "rm -f src/*.js src/*.d.ts || true",
     "test": "vitest",
     "test:watch": "vitest --watch",