@schmock/core 2.4.0 → 2.5.0

package/README.md

@@ -24,6 +24,135 @@ const response = await mock.handle("GET", "/users");
 // → { status: 200, body: [{ id: 1, name: "Alice" }] }
 ```
 
+## For adapter and plugin authors
+
+The root entry also exports the helpers core's own adapters and plugins are
+built from. Application code does not need them.
+
+```typescript
+// Response results, for plugins
+getResponseParts(response: unknown): ResponseParts  // { status, body, headers, kind }
+replaceResponseBody(response: unknown, body: unknown): unknown
+
+// Path prefixes: the namespace and baseUrl rule
+parsePathPrefix(prefix: string): PathPrefix         // { origin: string | null, path: string }
+matchPathPrefix(prefix: PathPrefix, path: string): boolean
+
+// Node ingress: the bridge mock.listen() and the CLI run
+serveNodeRequest(req, res, options: ServeNodeRequestOptions): Promise<void>
+
+// Response shaping
+withDefaultContentType(response: Response): Response
+buildFormattedErrorResponse(options: FormattedErrorOptions): Response
+
+// Headers
+SENSITIVE_HEADER_NAMES: ReadonlySet<string>
+redactHeaders(headers: Record<string, string>): Record<string, string>
+getHeader(headers: Readonly<Record<string, string>> | undefined, name: string): string | undefined
+```
+
+A plugin that reshapes a body reads the result with `getResponseParts()` and
+writes it back with `replaceResponseBody()`, which apply core's envelope rule:
+
+```typescript
+import { getResponseParts, replaceResponseBody } from "@schmock/core";
+
+const wrapPlugin: Schmock.Plugin = {
+  name: "wrap",
+  process(context, response) {
+    const { status, body } = getResponseParts(response);
+    if (body == null || status >= 300 || context.requestShortCircuited) {
+      return { context, response };
+    }
+    return { context, response: replaceResponseBody(response, { data: body }) };
+  },
+};
+```
+
+A prefix matches on a segment boundary, and one trailing slash is ignored:
+
+```typescript
+import { matchPathPrefix, parsePathPrefix } from "@schmock/core";
+
+const prefix = parsePathPrefix("/api/"); // { origin: null, path: "/api" }
+matchPathPrefix(prefix, "/api/users"); // true
+matchPathPrefix(prefix, "/apiv2"); // false
+```
+
+`serveNodeRequest()` serves a mock from any Node server, with the same 400,
+405 and 413 answers as `mock.listen()`:
+
+```typescript
+import { createServer } from "node:http";
+import { schmock, serveNodeRequest } from "@schmock/core";
+
+const mock = schmock();
+mock("GET /users", [{ id: 1 }]);
+
+createServer((req, res) => {
+  void serveNodeRequest(req, res, { handle: mock.handle, maxBodySize: 1024 * 1024 });
+}).listen(3000);
+```
+
+`withDefaultContentType()` adds the content type a body implies, and
+`buildFormattedErrorResponse()` turns an `errorFormatter` result into a
+normalized 500 without ever throwing. The header helpers mask credentials and
+look names up case-insensitively:
+
+```typescript
+import { buildFormattedErrorResponse, getHeader, redactHeaders, withDefaultContentType } from "@schmock/core";
+
+withDefaultContentType({ status: 200, body: { ok: true }, headers: {} });
+// → { status: 200, body: { ok: true }, headers: { "content-type": "application/json" } }
+
+buildFormattedErrorResponse({
+  formatter: (error) => ({ message: error.message }),
+  error: new Error("boom"),
+  method: "GET",
+});
+// → { status: 500, body: { message: "boom" }, headers: { "content-type": "application/json" } }
+
+redactHeaders({ Authorization: "Bearer t" }); // → { Authorization: "[redacted]" }
+getHeader({ "Content-Type": "text/plain" }, "content-type"); // → "text/plain"
+```
+
+### `@schmock/core/adapter`
+
+Transport adapters import the request-admission protocol from a separate entry:
+
+```typescript
+import { schmock } from "@schmock/core";
+import { acquireRequestAdmission } from "@schmock/core/adapter";
+
+const mock = schmock();
+mock("GET /users", [{ id: 1 }]);
+
+const admission = acquireRequestAdmission(mock); // undefined for a non-schmock stub
+if (admission) {
+  try {
+    await admission.handle("GET", "/users");
+  } finally {
+    admission.release();
+  }
+}
+```
+
+It exports `acquireRequestAdmission`, `awaitWithAbort`, `abortReason` and
+`createFetchInterceptor`, and the `RequestAdmission` and `MockRequestHandler`
+types.
+
+### Deprecated
+
+These are planned for removal in the next major version:
+
+- `createFetchInterceptor` from `@schmock/core`. Use `mock.intercept()`; adapter
+  authors import it from `@schmock/core/adapter`.
+- `ExpressAdapterOptions` from `@schmock/core`. Import it from `@schmock/express`.
+- `AngularAdapterOptions` from `@schmock/core`. Import it from `@schmock/angular`.
+
+See [Adapter-author utilities](https://github.com/khalic-lab/schmock/blob/main/docs/api.md#adapter-author-utilities)
+for every signature.
+
 ## Documentation
 
 - [Getting started](https://github.com/khalic-lab/schmock/blob/main/docs/getting-started.md)

package/dist/abort.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The reason an aborted signal carries, or a generic `AbortError` for a
+ * runtime whose signals predate `reason`.
+ */
+export declare function abortReason(signal: AbortSignal): unknown;
 export declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * Settle with `value`, or reject with the signal's abort reason as soon as the
+ * signal aborts, whichever comes first. Without a signal it only awaits the
+ * value. An already-aborted signal rejects instead of throwing, so a caller
+ * that does not `await` the result still sees the abort as a rejection.
+ */
 export declare function awaitWithAbort<T>(value: T | PromiseLike<T>, signal?: AbortSignal): Promise<T>;
-//# sourceMappingURL=abort.d.ts.map

package/dist/abort.js

@@ -1,4 +1,8 @@
-function abortReason(signal) {
+/**
+ * The reason an aborted signal carries, or a generic `AbortError` for a
+ * runtime whose signals predate `reason`.
+ */
+export function abortReason(signal) {
     if ("reason" in signal && signal.reason !== undefined) {
         return signal.reason;
     }
@@ -10,10 +14,17 @@ export function throwIfAborted(signal) {
     if (signal?.aborted)
         throw abortReason(signal);
 }
+/**
+ * Settle with `value`, or reject with the signal's abort reason as soon as the
+ * signal aborts, whichever comes first. Without a signal it only awaits the
+ * value. An already-aborted signal rejects instead of throwing, so a caller
+ * that does not `await` the result still sees the abort as a rejection.
+ */
 export function awaitWithAbort(value, signal) {
     if (!signal)
         return Promise.resolve(value);
-    throwIfAborted(signal);
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
     return new Promise((resolve, reject) => {
         let settled = false;
         const finish = (action) => {

package/dist/adapter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@schmock/core/adapter`: the low-level protocol transport adapters are built
+ * on. Application code uses `mock.handle()`, `mock.listen()` and
+ * `mock.intercept()` from `@schmock/core` instead.
+ *
+ * - `acquireRequestAdmission` pins a request to the mock's routes and plugins
+ *   at arrival, so a concurrent `reset()` cannot change them mid-request.
+ * - `awaitWithAbort` / `abortReason` race a hook or handler against the
+ *   request's abort signal.
+ * - `createFetchInterceptor` is the fetch interception `mock.intercept()` is
+ *   built on.
+ *
+ * @packageDocumentation
+ */
+export { abortReason, awaitWithAbort } from "./abort.js";
+export { acquireRequestAdmission } from "./admission.js";
+export type { CallableMockInstance, InterceptHandle, InterceptOptions, } from "./index.js";
+export { createFetchInterceptor } from "./interceptor.js";
+export type { MockRequestHandler, RequestAdmission } from "./types.js";

package/dist/adapter.js

@@ -0,0 +1,17 @@
+/**
+ * `@schmock/core/adapter`: the low-level protocol transport adapters are built
+ * on. Application code uses `mock.handle()`, `mock.listen()` and
+ * `mock.intercept()` from `@schmock/core` instead.
+ *
+ * - `acquireRequestAdmission` pins a request to the mock's routes and plugins
+ *   at arrival, so a concurrent `reset()` cannot change them mid-request.
+ * - `awaitWithAbort` / `abortReason` race a hook or handler against the
+ *   request's abort signal.
+ * - `createFetchInterceptor` is the fetch interception `mock.intercept()` is
+ *   built on.
+ *
+ * @packageDocumentation
+ */
+export { abortReason, awaitWithAbort } from "./abort.js";
+export { acquireRequestAdmission } from "./admission.js";
+export { createFetchInterceptor } from "./interceptor.js";

package/dist/admission.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The key a callable mock carries its request-admission factory under.
+ *
+ * Registered with `Symbol.for` so that a second copy of `@schmock/core` in the
+ * same process (an adapter resolving its own dependency) still finds it.
+ */
+export declare const REQUEST_ADMISSION_KEY: unique symbol;
+/**
+ * Admit one request against the mock's current routes and plugins.
+ *
+ * A transport acquires the admission when the request arrives, routes it with
+ * `admission.handle`, and calls `admission.release()` once it settles, so a
+ * `mock.reset()` issued meanwhile neither changes the routes the request sees
+ * nor uninstalls its plugins underneath it.
+ *
+ * @returns `undefined` for a value that is not a `schmock()` instance (a
+ *   hand-written stub), which the caller then routes through `mock.handle`.
+ * @throws SchmockError `INVALID_REQUEST_ADMISSION` when the mock's factory
+ *   returns something that is not an admission.
+ */
+export declare function acquireRequestAdmission(mock: Schmock.CallableMockInstance): Schmock.RequestAdmission | undefined;

package/dist/admission.js

@@ -0,0 +1,39 @@
+import { SchmockError } from "./errors.js";
+/**
+ * The key a callable mock carries its request-admission factory under.
+ *
+ * Registered with `Symbol.for` so that a second copy of `@schmock/core` in the
+ * same process (an adapter resolving its own dependency) still finds it.
+ */
+export const REQUEST_ADMISSION_KEY = Symbol.for("@schmock/core.request-admission");
+function isRequestAdmission(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "handle" in value &&
+        typeof value.handle === "function" &&
+        "release" in value &&
+        typeof value.release === "function");
+}
+/**
+ * Admit one request against the mock's current routes and plugins.
+ *
+ * A transport acquires the admission when the request arrives, routes it with
+ * `admission.handle`, and calls `admission.release()` once it settles, so a
+ * `mock.reset()` issued meanwhile neither changes the routes the request sees
+ * nor uninstalls its plugins underneath it.
+ *
+ * @returns `undefined` for a value that is not a `schmock()` instance (a
+ *   hand-written stub), which the caller then routes through `mock.handle`.
+ * @throws SchmockError `INVALID_REQUEST_ADMISSION` when the mock's factory
+ *   returns something that is not an admission.
+ */
+export function acquireRequestAdmission(mock) {
+    const admit = Reflect.get(mock, REQUEST_ADMISSION_KEY);
+    if (typeof admit !== "function")
+        return undefined;
+    const admission = Reflect.apply(admit, mock, []);
+    if (!isRequestAdmission(admission)) {
+        throw new SchmockError("Schmock returned an invalid request admission", "INVALID_REQUEST_ADMISSION");
+    }
+    return admission;
+}

package/dist/binary.d.ts

@@ -5,4 +5,3 @@
  * by SharedArrayBuffer, and Node.js Buffer without referencing its global.
  */
 export declare function isBinaryBody(value: unknown): value is ArrayBuffer | ArrayBufferView;
-//# sourceMappingURL=binary.d.ts.map

package/dist/builder.d.ts

@@ -1,20 +1,19 @@
-import type { CompiledCallableRoute } from "./route-matcher.js";
-interface RequestAdmission {
+import type { RequestGeneration } from "./generations.js";
+import type { RouteTableSnapshot } from "./route-table.js";
+/**
+ * What an admitted request captured at arrival. The transports' public
+ * `Schmock.RequestAdmission` wraps one of these.
+ */
+interface AdmissionSnapshot {
     readonly requestGeneration: RequestGeneration;
     readonly historyGeneration: symbol;
     readonly plugins: readonly Schmock.Plugin[];
-    readonly routes: CompiledCallableRoute[];
-    readonly staticRoutes: Map<string, CompiledCallableRoute>;
+    readonly routes: RouteTableSnapshot;
     readonly state: Record<string, unknown>;
     readonly namespace?: string;
     readonly globalDelay?: number | [number, number];
-    readonly maxHistorySize?: number;
     released: boolean;
 }
-interface RequestGeneration {
-    activeAdmissions: number;
-    retiredPlugins?: readonly Schmock.Plugin[];
-}
 /**
  * Callable mock instance that implements the new API.
  *
@@ -22,27 +21,23 @@ interface RequestGeneration {
  */
 export declare class CallableMockInstance {
     #private;
-    private routes;
-    private staticRoutes;
+    private readonly routeTable;
     private plugins;
     private logger;
-    private requestHistory;
+    private readonly requestHistory;
+    private readonly nodeServer;
     private callableRef;
-    private server;
-    private pendingServerStart;
-    private serverCloseBarrier;
     private interceptHandles;
-    private requestGeneration;
-    private historyGeneration;
+    private readonly generations;
     private interceptOwner;
     private globalConfig;
-    private listeners;
+    private readonly events;
+    private namespaceCache;
     constructor(globalConfig?: Schmock.GlobalConfig);
     defineRoute(route: Schmock.RouteKey, generator: Schmock.Generator, config: Schmock.RouteConfig): this;
     setCallableRef(ref: Schmock.CallableMockInstance): void;
     pipe(plugin: Schmock.Plugin): this;
     private uninstallPlugins;
-    private cloneRecord;
     history(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord[];
     called(method?: Schmock.HttpMethod, path?: string): boolean;
     callCount(method?: Schmock.HttpMethod, path?: string): number;
@@ -51,24 +46,13 @@ export declare class CallableMockInstance {
     getState(): Record<string, unknown>;
     on<E extends Schmock.SchmockEvent>(event: E, listener: (data: Schmock.SchmockEventMap[E]) => void): this;
     off<E extends Schmock.SchmockEvent>(event: E, listener: (data: Schmock.SchmockEventMap[E]) => void): this;
-    private emit;
     reset(): void;
     resetHistory(): void;
     resetState(): void;
-    createRequestAdmission(): {
-        handle: (method: Schmock.HttpMethod, path: string, options?: Schmock.RequestOptions) => Promise<Schmock.Response>;
-        release: () => void;
-    };
+    createRequestAdmission(): Schmock.RequestAdmission;
     listen(port?: number, hostname?: string): Promise<Schmock.ServerInfo>;
     close(): void;
     intercept(options?: Schmock.InterceptOptions): Schmock.InterceptHandle;
-    handle(method: Schmock.HttpMethod, path: string, options?: Schmock.RequestOptions, admission?: RequestAdmission): Promise<Schmock.Response>;
-    /**
-     * Apply configured response delay
-     * Supports both fixed delays and random delays within a range
-     * @private
-     */
-    private applyDelay;
+    handle(method: Schmock.HttpMethod, path: string, options?: Schmock.RequestOptions, admission?: AdmissionSnapshot): Promise<Schmock.Response>;
 }
 export {};
-//# sourceMappingURL=builder.d.ts.map