@schmock/core 2.4.1 → 2.5.0

package/dist/index.d.ts

@@ -112,6 +112,22 @@ namespace Schmock {
    */
   type RouteKey = `${HttpMethod} /${string}`;
 
+  /**
+   * What a synchronous plugin hook (`install`, `uninstall`) may return: any
+   * value except a thenable, which is ignored. A thenable would mean the hook
+   * finishes later, which the synchronous install contract cannot honour.
+   */
+  type PluginHookResult =
+    | void
+    | undefined
+    | null
+    | string
+    | number
+    | boolean
+    | bigint
+    | symbol
+    | (object & { then?: never });
+
   /**
    * Plugin interface for extending Schmock functionality
    */
@@ -125,16 +141,24 @@ namespace Schmock {
      * Called once when the plugin is added via .pipe()
      * Route registrations are committed atomically only when this hook returns
      * synchronously. The scoped instance must not be retained or used later.
-     * Returning a Promise is unsupported and leaves the plugin inactive.
+     *
+     * Returning a Promise is unsupported: `pipe()` rejects it at runtime with
+     * `PLUGIN_ASYNC_INSTALL_UNSUPPORTED`, and the return type makes an
+     * `async install()` a compile error too. Any other return value is
+     * accepted and ignored, so an expression-bodied arrow that registers a
+     * route (`install: (mock) => mock("GET /health", { ok: true })`, which
+     * returns the instance) type-checks as it always has.
      * @param instance - A synchronous, installation-scoped callable instance
      */
-    install?(instance: CallableMockInstance): void;
+    install?(instance: CallableMockInstance): PluginHookResult;
 
     /**
      * Called during reset after every request admitted with this plugin settles.
-     * Cleanup runs in reverse registration order and must complete synchronously.
+     * Cleanup runs in reverse registration order and must complete synchronously;
+     * as with `install`, an async hook is a compile error and any other return
+     * value is ignored.
      */
-    uninstall?(instance: CallableMockInstance): void;
+    uninstall?(instance: CallableMockInstance): PluginHookResult;
 
     /**
      * Inspect or transform a request before its route generator executes.
@@ -651,8 +675,15 @@ namespace Schmock {
       response: AdapterResponse,
       request: AdapterRequest,
     ) => AdapterResponse | void | Promise<AdapterResponse | void>;
-    /** Format errors into custom response bodies */
-    errorFormatter?: (error: Error) => unknown;
+    /**
+     * Format errors into custom response bodies.
+     *
+     * `request` is passed the way the Express and Angular adapters pass
+     * theirs: the request as routed, after `beforeRequest` once that hook has
+     * returned. When the request body itself could not be read, it is the
+     * incoming request without a body.
+     */
+    errorFormatter?: (error: Error, request: AdapterRequest) => unknown;
   }
 
   interface InterceptHandle {
@@ -669,6 +700,86 @@ namespace Schmock {
     readonly active: boolean;
   }
 
+  // ===== Transport Primitives =====
+
+  /**
+   * A route result taken apart the way core's response parser reads it.
+   * Returned by `getResponseParts()`.
+   *
+   * - `"object"`: a `{ status, body, headers? }` envelope. `headers`, when
+   *   present, must be a string record, or the value is not an envelope.
+   * - `"tuple"`: `[status, body]` or `[status, body, headers]`.
+   * - `"plain"`: anything else, delivered whole as the body.
+   */
+  interface ResponseParts {
+    /** The status core answers with: a plain `null`/`undefined` body is 204. */
+    status: number;
+    /** The body element as carried. Core sends no body for `null`/`undefined`. */
+    body: unknown;
+    /**
+     * A copy of the carried headers. A tuple whose third element is not a
+     * string record yields `{}` here, and core rejects it as INVALID_RESPONSE.
+     */
+    headers: Record<string, string>;
+    kind: "plain" | "tuple" | "object";
+  }
+
+  /**
+   * A parsed `baseUrl` or namespace. Returned by `parsePathPrefix()` and read
+   * by `matchPathPrefix()`.
+   */
+  interface PathPrefix {
+    /** The origin an origin-form prefix names, or `null` for a path prefix. */
+    origin: string | null;
+    /**
+     * The canonical (percent-encoded) path, without a trailing slash; `""`
+     * when the prefix is the root and matches every path.
+     */
+    path: string;
+  }
+
+  /** Routes one request: the signature of `CallableMockInstance.handle`. */
+  type MockRequestHandler = (
+    method: HttpMethod,
+    path: string,
+    options?: RequestOptions,
+  ) => Promise<Response>;
+
+  /**
+   * One request admitted against a snapshot of a mock's routes and plugins.
+   * `handle` must be called at most once, and `release` exactly once after
+   * the request settles, so a `reset()` waits for it before uninstalling.
+   * Acquired through `acquireRequestAdmission()` from `@schmock/core/adapter`.
+   */
+  interface RequestAdmission {
+    handle: MockRequestHandler;
+    release(): void;
+    /**
+     * Whether `handle(method, path)` would reach a route, answered from the
+     * same snapshot and by the same resolver `handle` uses: a `false` must
+     * never be wrong, or a request a route answers would be passed through.
+     * The fetch interceptor asks it, when present, to skip reading the body
+     * of a request that will pass through anyway. Admissions from
+     * `schmock()` carry it.
+     */
+    hasRoute?(method: HttpMethod, path: string): boolean;
+  }
+
+  /** Input to `buildFormattedErrorResponse()`. */
+  interface FormattedErrorOptions {
+    /** The `errorFormatter` hook, called exactly once. */
+    formatter: (error: Error) => unknown;
+    /** The error being formatted. */
+    error: Error;
+    /**
+     * Headers of the response being replaced (e.g. `retry-after`). Kept when
+     * they can be sent, minus any content type: a formatted body is JSON.
+     */
+    inheritedHeaders?: Record<string, string>;
+    /** Request method; a HEAD response carries no body. */
+    method: string;
+  }
+
   // ===== Lifecycle Events =====
 
   /**
@@ -771,7 +882,12 @@ namespace Schmock {
    * Context for schema-based data generation
    */
   interface SchemaGenerationContext {
-    schema: JSONSchema7;
+    /**
+     * The schema to generate from. Typed `Schema` so an inline literal may use
+     * the `faker`, `schmockNullable` and `schmockTrueProbability` keywords; a
+     * plain `JSONSchema7` is still accepted.
+     */
+    schema: Schema;
     count?: number;
     overrides?: Record<string, unknown>;
     params?: Record<string, string>;
@@ -784,7 +900,12 @@ namespace Schmock {
    * Options for the faker plugin
    */
   interface FakerPluginOptions {
-    schema: JSONSchema7;
+    /**
+     * The schema to generate from. Typed `Schema` so an inline literal may use
+     * the `faker`, `schmockNullable` and `schmockTrueProbability` keywords; a
+     * plain `JSONSchema7` is still accepted.
+     */
+    schema: Schema;
     count?: number;
     overrides?: Record<string, unknown>;
     seed?: number;
@@ -799,6 +920,10 @@ namespace Schmock {
 
   /**
    * Configuration options for Express adapter
+   *
+   * @deprecated Import `ExpressAdapterOptions` from `@schmock/express`, which
+   * types `req`/`res` as Express's `Request`/`Response`. This copy types them
+   * `unknown` and will be removed in the next major version.
    */
   interface ExpressAdapterOptions {
     errorFormatter?: (error: Error, req: unknown) => unknown;
@@ -825,6 +950,10 @@ namespace Schmock {
 
   /**
    * Configuration options for Angular adapter
+   *
+   * @deprecated Import `AngularAdapterOptions` from `@schmock/angular`, which
+   * types `request` as Angular's `HttpRequest`. This copy types it `unknown`
+   * and will be removed in the next major version.
    */
   interface AngularAdapterOptions {
     baseUrl?: string;
@@ -832,6 +961,26 @@ namespace Schmock {
     errorFormatter?: (error: Error, request: unknown) => unknown;
     transformRequest?: (request: unknown) => AdapterRequestOverride;
     transformResponse?: (response: Response, request: unknown) => Response;
+    /**
+     * `transformRequest` under the fetch interceptor's name; it may be async,
+     * and returning nothing leaves the request unchanged. When both are set,
+     * `transformRequest` is used.
+     */
+    beforeRequest?: (
+      request: unknown,
+    ) =>
+      | AdapterRequestOverride
+      | void
+      | Promise<AdapterRequestOverride | undefined>;
+    /**
+     * `transformResponse` under the fetch interceptor's name; it may be async,
+     * and returning nothing keeps the response. When both are set,
+     * `transformResponse` is used.
+     */
+    beforeResponse?: (
+      response: Response,
+      request: unknown,
+    ) => Response | void | Promise<Response | undefined>;
   }
 
   // ===== OpenAPI Plugin Options =====
@@ -863,17 +1012,19 @@ namespace Schmock {
     allowHttp?: boolean;
     /**
      * Hostnames an `http(s)` `$ref` may target. Empty or omitted means any
-     * host, still minus loopback, link-local and private ranges.
+     * host, still minus loopback, link-local, private and reserved ranges,
+     * checked against every address a host resolves to, so an allow-listed
+     * name that resolves to one is refused too.
      */
     allowedHosts?: string[];
     /** Per-request timeout for http `$ref`s, in ms. Default 5000. */
     timeoutMs?: number;
     /**
-     * Redirects to follow for an http `$ref`. Default 0.
+     * Maximum redirect hops to follow for an http `$ref`. Default 0.
      *
-     * `fetch` exposes no numeric redirect cap, so this behaves as a boolean:
-     * `0` refuses redirects, any positive value follows up to the platform
-     * default. Use `allowedHosts` when the exact destination matters.
+     * Every hop is checked against `allowHttp` and `allowedHosts` before it
+     * is followed. `0` refuses the first redirect; `n` follows up to `n` hops
+     * and refuses the next one.
      */
     redirects?: number;
     /** Maximum size of a single http `$ref` document, in bytes. Default 1 MB. */
@@ -915,18 +1066,27 @@ namespace Schmock {
     /** 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;
+    onSchema?: OnSchemaCallback;
   }
 
+  /** The request an {@link OnSchemaCallback} is generating a response for. */
+  interface OnSchemaContext {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+  }
+
+  /**
+   * `OpenApiOptions.onSchema`: called before a response body is generated.
+   * Return a schema to replace the original, or `undefined` to keep it.
+   */
+  type OnSchemaCallback = (
+    schema: import("json-schema").JSONSchema7,
+    context: OnSchemaContext,
+  ) => import("json-schema").JSONSchema7 | undefined;
+
   /**
    * Seed data source: inline array, file path, or auto-generate count
    */
@@ -963,6 +1123,10 @@ namespace Schmock {
      * How many requests the mock retains for `GET /schmock-admin/history`
      * (`--admin-history-limit`, default 500). Ignored — history is disabled
      * entirely — when `admin` is off.
+     *
+     * It becomes the mock's {@link GlobalConfig.maxHistorySize} and applies
+     * only while the admin API is on; it defaults to 500 where a core mock's
+     * history is unbounded.
      */
     adminHistoryLimit?: number;
     /** Validate the spec against the OpenAPI schema at startup (`--strict`). */
@@ -1020,6 +1184,7 @@ namespace Schmock {
 }
 }
 // >>> schmock ambient namespace <<<
+import { createFetchInterceptor as createAdapterFetchInterceptor } from "./interceptor.js";
 /**
  * Create a new Schmock mock instance with callable API.
  *
@@ -1044,13 +1209,30 @@ namespace Schmock {
  * @returns A callable mock instance
  */
 export declare function schmock(config?: Schmock.GlobalConfig): Schmock.CallableMockInstance;
+/**
+ * @deprecated Use `mock.intercept()`, which also tracks the lease and admits
+ * each request against the mock's routes. Adapter authors who need the raw
+ * interceptor import `createFetchInterceptor` from `@schmock/core/adapter`.
+ * This root export will be removed in the next major version.
+ */
+export declare const createFetchInterceptor: typeof createAdapterFetchInterceptor;
 export { isBinaryBody } from "./binary.js";
-export { getResponseException, HTTP_METHODS, isHttpMethod, isRouteNotFound, isStatusTuple, ROUTE_NOT_FOUND_CODE, toHttpMethod, toRouteKey, } from "./constants.js";
-export { InvalidResponseError, PluginError, ResourceLimitError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
+export { getResponseException, HTTP_METHODS, isHttpMethod, isRouteNotFound, isStatusTuple, matchPathPrefix, parsePathPrefix, ROUTE_NOT_FOUND_CODE, toHttpMethod, toRouteKey, } from "./constants.js";
+export { InvalidHttpMethodError, InvalidResponseError, PluginError, ResourceLimitError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
+export { getHeader, redactHeaders, SENSITIVE_HEADER_NAMES, } from "./headers.js";
 export { badRequest, created, forbidden, noContent, notFound, paginate, serverError, unauthorized, } from "./helpers.js";
-export type { HttpIngressErrorCode } from "./http-helpers.js";
-export { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
-export { createFetchInterceptor } from "./interceptor.js";
-export { normalizeResponse, serializeResponseBody, } from "./response-normalizer.js";
-export type { AdapterRequest, AdapterRequestOverride, AdapterResponse, AngularAdapterOptions, CallableMockInstance, CrudOperationMeta, ExpressAdapterOptions, FakerPluginOptions, Generator, GeneratorFunction, GlobalConfig, HttpMethod, InterceptHandle, InterceptOptions, OpenApiCallbackOptions, OpenApiCallbackRequest, OpenApiOptions, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, ResourceOverride, Response, ResponseBody, ResponseHeaderDef, ResponseResult, RouteConfig, RouteInfo, RouteKey, Schema, SchemaDefinition, SchemaGenerationContext, SeedConfig, SeedSource, ServerInfo, StaticData, } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+export type { HttpErrorReply, HttpIngressErrorCode, NodeRequestLike, NodeResponseLike, ServeNodeRequestOptions, ServeNodeResponseContext, } from "./http-helpers.js";
+export { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, serveNodeRequest, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
+export { buildFormattedErrorResponse, normalizeResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
+export { getResponseParts, replaceResponseBody, } from "./response-parser.js";
+export type { AdapterRequest, AdapterRequestOverride, AdapterResponse, 
+/**
+ * @deprecated Import `AngularAdapterOptions` from `@schmock/angular`; this
+ * copy will be removed in the next major version.
+ */
+AngularAdapterOptions, CallableMockInstance, CrudOperationMeta, 
+/**
+ * @deprecated Import `ExpressAdapterOptions` from `@schmock/express`; this
+ * copy will be removed in the next major version.
+ */
+ExpressAdapterOptions, FakerPluginOptions, FormattedErrorOptions, Generator, GeneratorFunction, GlobalConfig, HttpMethod, InterceptHandle, InterceptOptions, OnSchemaCallback, OnSchemaContext, OpenApiCallbackOptions, OpenApiCallbackRequest, OpenApiOptions, OpenApiRefPolicy, PaginatedResponse, PaginateOptions, PathPrefix, Plugin, PluginContext, PluginHookResult, PluginResult, RequestContext, RequestEndEvent, RequestMatchEvent, RequestNotFoundEvent, RequestOptions, RequestRecord, RequestStartEvent, ResourceOverride, Response, ResponseBody, ResponseHeaderDef, ResponseParts, ResponseResult, RouteConfig, RouteInfo, RouteKey, Schema, SchemaDefinition, SchemaGenerationContext, SchmockEvent, SchmockEventMap, SeedConfig, SeedSource, ServerInfo, StaticData, } from "./types.js";

package/dist/index.js

@@ -1,5 +1,6 @@
+import { REQUEST_ADMISSION_KEY } from "./admission.js";
 import { CallableMockInstance } from "./builder.js";
-const REQUEST_ADMISSION = Symbol.for("@schmock/core.request-admission");
+import { createFetchInterceptor as createAdapterFetchInterceptor } from "./interceptor.js";
 /**
  * Create a new Schmock mock instance with callable API.
  *
@@ -57,22 +58,29 @@ export function schmock(config) {
         close: instance.close.bind(instance),
         intercept: (options) => instance.intercept(options),
     });
-    Object.defineProperty(callableInstance, REQUEST_ADMISSION, {
+    Object.defineProperty(callableInstance, REQUEST_ADMISSION_KEY, {
         value: () => instance.createRequestAdmission(),
     });
     instance.setCallableRef(callableInstance);
     return callableInstance;
 }
+/**
+ * @deprecated Use `mock.intercept()`, which also tracks the lease and admits
+ * each request against the mock's routes. Adapter authors who need the raw
+ * interceptor import `createFetchInterceptor` from `@schmock/core/adapter`.
+ * This root export will be removed in the next major version.
+ */
+export const createFetchInterceptor = createAdapterFetchInterceptor;
 export { isBinaryBody } from "./binary.js";
 // Re-export constants and utilities
-export { getResponseException, HTTP_METHODS, isHttpMethod, isRouteNotFound, isStatusTuple, ROUTE_NOT_FOUND_CODE, toHttpMethod, toRouteKey, } from "./constants.js";
+export { getResponseException, HTTP_METHODS, isHttpMethod, isRouteNotFound, isStatusTuple, matchPathPrefix, parsePathPrefix, ROUTE_NOT_FOUND_CODE, toHttpMethod, toRouteKey, } from "./constants.js";
 // Re-export errors
-export { InvalidResponseError, PluginError, ResourceLimitError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
+export { InvalidHttpMethodError, InvalidResponseError, PluginError, ResourceLimitError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
+// Re-export header helpers
+export { getHeader, redactHeaders, SENSITIVE_HEADER_NAMES, } from "./headers.js";
 // Re-export response helpers
 export { badRequest, created, forbidden, noContent, notFound, paginate, serverError, unauthorized, } from "./helpers.js";
 // Re-export HTTP server helpers
-export { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
-// Re-export types
-// Re-export interceptor
-export { createFetchInterceptor } from "./interceptor.js";
-export { normalizeResponse, serializeResponseBody, } from "./response-normalizer.js";
+export { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, serveNodeRequest, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
+export { buildFormattedErrorResponse, normalizeResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
+export { getResponseParts, replaceResponseBody, } from "./response-parser.js";

package/dist/interceptor.d.ts

@@ -1,15 +1,19 @@
-type InterceptRequestHandler = (method: Schmock.HttpMethod, path: string, requestOptions?: Schmock.RequestOptions) => Promise<Schmock.Response>;
-interface InterceptRequestAdmission {
-    handle: InterceptRequestHandler;
-    release(): void;
-}
+/**
+ * Marks an admission whose `handle()` already returns responses normalized
+ * for the request method (hop-by-hop headers dropped, a HEAD body stripped):
+ * only the admissions a `schmock()` instance of this copy creates. The
+ * interceptor re-normalizes the responses of any other admission, such as a
+ * hand-written one passed to `createFetchInterceptor`. Deliberately
+ * unregistered: an admission from a second copy of `@schmock/core` is simply
+ * normalized again.
+ */
+export declare const NORMALIZED_ADMISSION_KEY: unique symbol;
 /**
  * Create a fetch interceptor that routes requests through mock.handle().
  *
- * `owner` identifies the mock behind the lease. Leases sharing an owner are
- * consulted at most once per request, so a mock held by several leases runs
- * its handler — and emits its lifecycle events — once per network request.
+ * `owner` identifies the mock behind the lease. Leases sharing an owner ask it
+ * each distinct effective request (method and path after the lease's own
+ * beforeRequest) at most once, so a mock held by several leases runs its
+ * handler — and emits its lifecycle events — once per request it is asked.
  */
-export declare function createFetchInterceptor(handle: InterceptRequestHandler, options?: Schmock.InterceptOptions, admitRequest?: () => InterceptRequestAdmission, owner?: symbol): Schmock.InterceptHandle;
-export {};
-//# sourceMappingURL=interceptor.d.ts.map
+export declare function createFetchInterceptor(handle: Schmock.MockRequestHandler, options?: Schmock.InterceptOptions, admitRequest?: () => Schmock.RequestAdmission, owner?: symbol): Schmock.InterceptHandle;