counterfact 2.6.0 → 2.7.0

package/dist/server/counterfact-types/index.ts

@@ -1,339 +1,21 @@
-import { OpenApiHeader } from "./open-api-header";
-
-interface OpenApiContent {
-  schema: unknown;
-}
-
-interface Example {
-  description: string;
-  summary: string;
-  value: unknown;
-}
-
-interface CookieOptions {
-  domain?: string;
-  expires?: Date;
-  httpOnly?: boolean;
-  maxAge?: number;
-  path?: string;
-  sameSite?: "lax" | "none" | "strict";
-  secure?: boolean;
-}
-
-const counterfactResponse = Symbol("Counterfact Response");
-
-type COUNTERFACT_RESPONSE = {
-  [counterfactResponse]: typeof counterfactResponse;
-};
-
-type MediaType = `${string}/${string}`;
-
-type MaybePromise<T> = T | Promise<T>;
-
-type OmitAll<T, K extends readonly string[]> = {
-  [P in keyof T as P extends `${string}${K[number]}${string}`
-    ? never
-    : P]: T[P];
-};
-
-type OmitValueWhenNever<Base> = Pick<
-  Base,
-  {
-    [Key in keyof Base]: [Base[Key]] extends [never] ? never : Key;
-  }[keyof Base]
->;
-
-interface OpenApiResponse {
-  content: { [key: MediaType]: OpenApiContent };
-  examples?: { [key: string]: unknown };
-  headers: { [key: string]: { schema: unknown } };
-  requiredHeaders: string;
-}
-
-interface OpenApiResponses {
-  [key: string]: OpenApiResponse;
-}
-
-type IfHasKey<
-  SomeObject,
-  Keys extends readonly string[],
-  Yes,
-  No,
-> = Keys extends [
-  infer FirstKey extends string,
-  ...infer RestKeys extends string[],
-]
-  ? Extract<keyof SomeObject, `${string}${FirstKey}${string}`> extends never
-    ? IfHasKey<SomeObject, RestKeys, Yes, No>
-    : Yes
-  : No;
-
-type SchemasOf<T extends { [key: string]: { schema: unknown } }> = {
-  [K in keyof T]: T[K]["schema"];
-}[keyof T];
-
-type MaybeShortcut<
-  ContentTypes extends MediaType[],
-  Response extends OpenApiResponse,
-> = IfHasKey<
-  Response["content"],
-  ContentTypes,
-  (body: SchemasOf<Response["content"]>) => GenericResponseBuilder<{
-    content: NeverIfEmpty<OmitAll<Response["content"], ContentTypes>>;
-    headers: Response["headers"];
-    requiredHeaders: Response["requiredHeaders"];
-  }>,
-  never
->;
-
-type NeverIfEmpty<Record> = object extends Record ? never : Record;
-
-type MatchFunction<Response extends OpenApiResponse> = <
-  ContentType extends MediaType & keyof Response["content"],
->(
-  contentType: ContentType,
-  body: Response["content"][ContentType]["schema"],
-) => GenericResponseBuilder<{
-  content: NeverIfEmpty<Omit<Response["content"], ContentType>>;
-  headers: Response["headers"];
-  requiredHeaders: Response["requiredHeaders"];
-}>;
-
-type HeaderFunction<Response extends OpenApiResponse> = <
-  Header extends string & keyof Response["headers"],
->(
-  header: Header,
-  value: Response["headers"][Header]["schema"],
-) => GenericResponseBuilder<{
-  content: NeverIfEmpty<Response["content"]>;
-  headers: NeverIfEmpty<Omit<Response["headers"], Header>>;
-  requiredHeaders: Exclude<Response["requiredHeaders"], Header>;
-}>;
-
-type RandomFunction = () => MaybePromise<COUNTERFACT_RESPONSE>;
-
-type ExampleNames<Response extends OpenApiResponse> = Response extends {
-  examples: infer E;
-}
-  ? keyof E & string
-  : never;
-
-interface ResponseBuilder {
-  [status: number | `${number} ${string}`]: ResponseBuilder;
-  binary: (body: Uint8Array | string) => ResponseBuilder;
-  content?: { body: unknown; type: string }[];
-  cookie: (
-    name: string,
-    value: string,
-    options?: CookieOptions,
-  ) => ResponseBuilder;
-  example: (name: string) => ResponseBuilder;
-  header: (name: string, value: string) => ResponseBuilder;
-  headers: { [name: string]: string | string[] };
-  html: (body: unknown) => ResponseBuilder;
-  json: (body: unknown) => ResponseBuilder;
-  match: (contentType: string, body: unknown) => ResponseBuilder;
-  random: () => MaybePromise<ResponseBuilder>;
-  randomLegacy: () => MaybePromise<ResponseBuilder>;
-  status?: number;
-  text: (body: unknown) => ResponseBuilder;
-  xml: (body: unknown) => ResponseBuilder;
-}
-
-export type GenericResponseBuilderInner<
-  Response extends OpenApiResponse = OpenApiResponse,
-> = OmitValueWhenNever<{
-  binary: MaybeShortcut<["application/octet-stream"], Response>;
-  cookie: (
-    name: string,
-    value: string,
-    options?: CookieOptions,
-  ) => GenericResponseBuilder<Response>;
-  header: [keyof Response["headers"]] extends [never]
-    ? never
-    : HeaderFunction<Response>;
-  html: MaybeShortcut<["text/html"], Response>;
-  json: MaybeShortcut<
-    [
-      "application/json",
-      "text/json",
-      "text/x-json",
-      "application/xml",
-      "text/xml",
-    ],
-    Response
-  >;
-  match: [keyof Response["content"]] extends [never]
-    ? never
-    : MatchFunction<Response>;
-  random: [keyof Response["content"]] extends [never] ? never : RandomFunction;
-  example: [ExampleNames<Response>] extends [never]
-    ? never
-    : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
-  text: MaybeShortcut<["text/plain"], Response>;
-  xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
-}>;
-
-type GenericResponseBuilder<
-  Response extends OpenApiResponse = OpenApiResponse,
-> =
-  object extends OmitValueWhenNever<Response>
-    ? COUNTERFACT_RESPONSE
-    : keyof OmitValueWhenNever<Response> extends "headers"
-      ? {
-          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
-          header: HeaderFunction<Response>;
-        }
-      : GenericResponseBuilderInner<Response>;
-
-type ResponseBuilderFactory<
-  Responses extends OpenApiResponses = OpenApiResponses,
-> = {
-  [StatusCode in keyof Responses]: GenericResponseBuilder<
-    Responses[StatusCode]
-  >;
-} & { [key: string]: GenericResponseBuilder<Responses["default"]> };
-
-type HttpStatusCode =
-  | 100
-  | 101
-  | 102
-  | 200
-  | 201
-  | 202
-  | 203
-  | 204
-  | 205
-  | 206
-  | 207
-  | 226
-  | 300
-  | 301
-  | 302
-  | 303
-  | 304
-  | 305
-  | 307
-  | 308
-  | 400
-  | 401
-  | 402
-  | 403
-  | 404
-  | 405
-  | 406
-  | 407
-  | 408
-  | 409
-  | 410
-  | 411
-  | 412
-  | 413
-  | 414
-  | 415
-  | 416
-  | 417
-  | 418
-  | 422
-  | 423
-  | 424
-  | 426
-  | 428
-  | 429
-  | 431
-  | 451
-  | 500
-  | 501
-  | 502
-  | 503
-  | 504
-  | 505
-  | 506
-  | 507
-  | 511;
-
-interface OpenApiParameters {
-  in: "body" | "cookie" | "formData" | "header" | "path" | "query";
-  name: string;
-  required?: boolean;
-  schema?: {
-    [key: string]: unknown;
-    type?: string;
-  };
-  type?: "string" | "number" | "integer" | "boolean";
-}
-
-interface OpenApiOperation {
-  parameters?: OpenApiParameters[];
-  produces?: string[];
-  requestBody?: {
-    content?: {
-      [mediaType: string]: {
-        schema: { [key: string]: unknown };
-      };
-    };
-    required?: boolean;
-  };
-  responses: {
-    [status: string]: {
-      content?: {
-        [type: number | string]: {
-          examples?: { [key: string]: Example };
-          schema: { [key: string]: unknown };
-        };
-      };
-      examples?: { [key: string]: unknown };
-      headers?: {
-        [name: string]: OpenApiHeader;
-      };
-      schema?: { [key: string]: unknown };
-    };
-  };
-}
-
-interface WideResponseBuilder {
-  binary: (body: Uint8Array | string) => WideResponseBuilder;
-  example: (name: string) => WideResponseBuilder;
-  cookie: (
-    name: string,
-    value: string,
-    options?: CookieOptions,
-  ) => WideResponseBuilder;
-  header: (body: unknown) => WideResponseBuilder;
-  html: (body: unknown) => WideResponseBuilder;
-  json: (body: unknown) => WideResponseBuilder;
-  match: (contentType: string, body: unknown) => WideResponseBuilder;
-  random: () => MaybePromise<WideResponseBuilder>;
-  text: (body: unknown) => WideResponseBuilder;
-  xml: (body: unknown) => WideResponseBuilder;
-}
-
-interface WideOperationArgument {
-  body: unknown;
-  context: unknown;
-  headers: { [key: string]: string };
-  path: { [key: string]: string };
-  proxy: (url: string) => { proxyUrl: string };
-  query: { [key: string]: string };
-  response: { [key: number]: WideResponseBuilder };
-}
-
-export type { COUNTERFACT_RESPONSE };
-
+export type { CookieOptions } from "./cookie-options.js";
+export type { COUNTERFACT_RESPONSE } from "./counterfact-response.js";
+export type { ExampleNames } from "./example-names.js";
 export type {
-  CookieOptions,
-  ExampleNames,
-  HttpStatusCode,
-  MaybePromise,
-  MediaType,
-  OmitValueWhenNever,
-  OpenApiOperation,
-  OpenApiParameters,
-  OpenApiResponse,
-  ResponseBuilder,
-  ResponseBuilderFactory,
-  WideOperationArgument,
-  WideResponseBuilder,
-  OmitAll,
-  IfHasKey,
-};
+  GenericResponseBuilder,
+  GenericResponseBuilderInner,
+} from "./generic-response-builder.js";
+export type { HttpStatusCode } from "./http-status-code.js";
+export type { IfHasKey } from "./if-has-key.js";
+export type { MaybePromise } from "./maybe-promise.js";
+export type { MediaType } from "./media-type.js";
+export type { OmitAll } from "./omit-all.js";
+export type { OmitValueWhenNever } from "./omit-value-when-never.js";
+export type { OpenApiHeader } from "./open-api-header.js";
+export type { OpenApiOperation } from "./open-api-operation.js";
+export type { OpenApiParameters } from "./open-api-parameters.js";
+export type { OpenApiResponse } from "./open-api-response.js";
+export type { ResponseBuilder } from "./response-builder.js";
+export type { ResponseBuilderFactory } from "./response-builder-factory.js";
+export type { WideOperationArgument } from "./wide-operation-argument.js";
+export type { WideResponseBuilder } from "./wide-response-builder.js";

package/dist/server/counterfact-types/maybe-promise.ts

@@ -0,0 +1,6 @@
+/**
+ * A value that is either `T` directly or a `Promise<T>`.
+ * Route handlers may return either synchronous values or promises, and
+ * Counterfact will await them transparently.
+ */
+export type MaybePromise<T> = T | Promise<T>;

package/dist/server/counterfact-types/media-type.ts

@@ -0,0 +1,6 @@
+/**
+ * Represents an IANA media type string in the format `type/subtype`
+ * (e.g. `"application/json"`, `"text/plain"`, `"image/png"`).
+ * Used to identify the content type of an HTTP request or response body.
+ */
+export type MediaType = `${string}/${string}`;

package/dist/server/counterfact-types/omit-all.ts

@@ -0,0 +1,11 @@
+/**
+ * Removes all keys from `T` whose names contain any of the strings in `K`
+ * as a substring (prefix, suffix, or exact match).
+ * Used internally to narrow the set of available content-type methods on the
+ * response builder after one has already been called.
+ */
+export type OmitAll<T, K extends readonly string[]> = {
+  [P in keyof T as P extends `${string}${K[number]}${string}`
+    ? never
+    : P]: T[P];
+};

package/dist/server/counterfact-types/omit-value-when-never.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a new type from `Base` that omits any keys whose value type is
+ * `never`. This is used to strip unavailable builder methods (those that
+ * don't apply to the current response shape) from the fluent response builder.
+ */
+export type OmitValueWhenNever<Base> = Pick<
+  Base,
+  {
+    [Key in keyof Base]: [Base[Key]] extends [never] ? never : Key;
+  }[keyof Base]
+>;

package/dist/server/counterfact-types/open-api-content.ts

@@ -0,0 +1,8 @@
+/**
+ * Represents a single content entry in an OpenAPI response object.
+ * The `schema` property holds the JSON Schema definition for the body of
+ * a response with this media type.
+ */
+export interface OpenApiContent {
+  schema: unknown;
+}

package/dist/server/counterfact-types/open-api-operation.ts

@@ -0,0 +1,36 @@
+import type { Example } from "./example.js";
+import type { OpenApiHeader } from "./open-api-header.js";
+import type { OpenApiParameters } from "./open-api-parameters.js";
+
+/**
+ * Describes a single HTTP operation (e.g. `GET /pets`) as defined in an
+ * OpenAPI document. Used internally to derive the strongly-typed argument
+ * and response builder types for generated route handler functions.
+ */
+export interface OpenApiOperation {
+  parameters?: OpenApiParameters[];
+  produces?: string[];
+  requestBody?: {
+    content?: {
+      [mediaType: string]: {
+        schema: { [key: string]: unknown };
+      };
+    };
+    required?: boolean;
+  };
+  responses: {
+    [status: string]: {
+      content?: {
+        [type: number | string]: {
+          examples?: { [key: string]: Example };
+          schema: { [key: string]: unknown };
+        };
+      };
+      examples?: { [key: string]: unknown };
+      headers?: {
+        [name: string]: OpenApiHeader;
+      };
+      schema?: { [key: string]: unknown };
+    };
+  };
+}

package/dist/server/counterfact-types/open-api-parameters.ts

@@ -0,0 +1,16 @@
+/**
+ * Describes a single parameter (path, query, header, cookie, body, or
+ * formData) as defined in an OpenAPI document. Used internally to type the
+ * `path`, `query`, `headers`, and `body` properties of a route handler's
+ * argument object.
+ */
+export interface OpenApiParameters {
+  in: "body" | "cookie" | "formData" | "header" | "path" | "query";
+  name: string;
+  required?: boolean;
+  schema?: {
+    [key: string]: unknown;
+    type?: string;
+  };
+  type?: "string" | "number" | "integer" | "boolean";
+}

package/dist/server/counterfact-types/open-api-response.ts

@@ -0,0 +1,22 @@
+import type { MediaType } from "./media-type.js";
+import type { OpenApiContent } from "./open-api-content.js";
+
+/**
+ * Describes a single HTTP response as modelled in an OpenAPI document.
+ * Contains the allowed content types, optional named examples, and the
+ * required/optional response headers for that response.
+ */
+export interface OpenApiResponse {
+  content: { [key: MediaType]: OpenApiContent };
+  examples?: { [key: string]: unknown };
+  headers: { [key: string]: { schema: unknown } };
+  requiredHeaders: string;
+}
+
+/**
+ * A map of HTTP status codes (or `"default"`) to their corresponding
+ * `OpenApiResponse` definitions for a given operation.
+ */
+export interface OpenApiResponses {
+  [key: string]: OpenApiResponse;
+}

package/dist/server/counterfact-types/random-function.ts

@@ -0,0 +1,9 @@
+import type { COUNTERFACT_RESPONSE } from "./counterfact-response.js";
+import type { MaybePromise } from "./maybe-promise.js";
+
+/**
+ * The type of the `.random()` method on the response builder.
+ * When called, it randomly selects one of the available content-type examples
+ * and returns a completed `COUNTERFACT_RESPONSE`.
+ */
+export type RandomFunction = () => MaybePromise<COUNTERFACT_RESPONSE>;

package/dist/server/counterfact-types/response-builder-factory.ts

@@ -0,0 +1,16 @@
+import type { GenericResponseBuilder } from "./generic-response-builder.js";
+import type { OpenApiResponses } from "./open-api-response.js";
+
+/**
+ * Maps each HTTP status code (or `"default"`) in an OpenAPI operation's
+ * response definitions to the corresponding `GenericResponseBuilder`.
+ * This is the type of the `response` property in a generated route handler's
+ * argument object, allowing handlers to call e.g. `response[200].json(body)`.
+ */
+export type ResponseBuilderFactory<
+  Responses extends OpenApiResponses = OpenApiResponses,
+> = {
+  [StatusCode in keyof Responses]: GenericResponseBuilder<
+    Responses[StatusCode]
+  >;
+} & { [key: string]: GenericResponseBuilder<Responses["default"]> };

package/dist/server/counterfact-types/response-builder.ts

@@ -0,0 +1,31 @@
+import type { CookieOptions } from "./cookie-options.js";
+import type { MaybePromise } from "./maybe-promise.js";
+
+/**
+ * A loosely-typed, chainable response builder used in non-generated contexts
+ * (e.g. middleware or wide/catch-all route handlers) where the exact response
+ * shape is not statically known. For generated route handlers, prefer the
+ * strongly-typed `GenericResponseBuilder`.
+ */
+export interface ResponseBuilder {
+  [status: number | `${number} ${string}`]: ResponseBuilder;
+  binary: (body: Uint8Array | string) => ResponseBuilder;
+  content?: { body: unknown; type: string }[];
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => ResponseBuilder;
+  empty: () => ResponseBuilder;
+  example: (name: string) => ResponseBuilder;
+  header: (name: string, value: string) => ResponseBuilder;
+  headers: { [name: string]: string | string[] };
+  html: (body: unknown) => ResponseBuilder;
+  json: (body: unknown) => ResponseBuilder;
+  match: (contentType: string, body: unknown) => ResponseBuilder;
+  random: () => MaybePromise<ResponseBuilder>;
+  randomLegacy: () => MaybePromise<ResponseBuilder>;
+  status?: number;
+  text: (body: unknown) => ResponseBuilder;
+  xml: (body: unknown) => ResponseBuilder;
+}

package/dist/server/counterfact-types/wide-operation-argument.ts

@@ -0,0 +1,17 @@
+import type { WideResponseBuilder } from "./wide-response-builder.js";
+
+/**
+ * The loosely-typed argument object passed to wide (catch-all) route handlers.
+ * Unlike the generated operation argument types, all fields are typed as
+ * `unknown` or broad index signatures. Use this when writing handlers that
+ * should accept any request without compile-time schema enforcement.
+ */
+export interface WideOperationArgument {
+  body: unknown;
+  context: unknown;
+  headers: { [key: string]: string };
+  path: { [key: string]: string };
+  proxy: (url: string) => { proxyUrl: string };
+  query: { [key: string]: string };
+  response: { [key: number]: WideResponseBuilder };
+}

package/dist/server/counterfact-types/wide-response-builder.ts

@@ -0,0 +1,26 @@
+import type { CookieOptions } from "./cookie-options.js";
+import type { MaybePromise } from "./maybe-promise.js";
+
+/**
+ * A loosely-typed response builder used in wide (catch-all) route handlers
+ * where the response shape is not known at compile time. Unlike the generated
+ * `GenericResponseBuilder`, this interface accepts `unknown` for all body
+ * arguments and does not enforce content-type constraints.
+ */
+export interface WideResponseBuilder {
+  binary: (body: Uint8Array | string) => WideResponseBuilder;
+  empty: () => WideResponseBuilder;
+  example: (name: string) => WideResponseBuilder;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => WideResponseBuilder;
+  header: (body: unknown) => WideResponseBuilder;
+  html: (body: unknown) => WideResponseBuilder;
+  json: (body: unknown) => WideResponseBuilder;
+  match: (contentType: string, body: unknown) => WideResponseBuilder;
+  random: () => MaybePromise<WideResponseBuilder>;
+  text: (body: unknown) => WideResponseBuilder;
+  xml: (body: unknown) => WideResponseBuilder;
+}

package/dist/server/create-koa-app.js

@@ -1,11 +1,9 @@
-import { pathToFileURL } from "node:url";
 import createDebug from "debug";
 import Koa from "koa";
 import bodyParser from "koa-bodyparser";
 import { koaSwagger } from "koa2-swagger-ui";
 import { adminApiMiddleware } from "./admin-api-middleware.js";
 import { openapiMiddleware } from "./openapi-middleware.js";
-import { pageMiddleware } from "./page-middleware.js";
 const debug = createDebug("counterfact:server:create-koa-app");
 export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
     const app = new Koa();
@@ -21,30 +19,13 @@ export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
     }
     debug("basePath: %s", config.basePath);
     debug("routes", registry.routes);
-    app.use(pageMiddleware("/counterfact/", "index", {
-        basePath: config.basePath,
-        methods: ["get", "post", "put", "delete", "patch"],
-        openApiHref: config.openApiPath.includes("://")
-            ? config.openApiPath
-            : pathToFileURL(config.openApiPath).href,
-        openApiPath: config.openApiPath,
-        get routes() {
-            return registry.routes;
-        },
-    }));
     app.use(async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact") {
-            ctx.redirect("/counterfact/");
+            ctx.redirect("/counterfact/swagger");
             return;
         }
         await next();
     });
-    app.use(pageMiddleware("/counterfact/rapidoc", "rapi-doc", {
-        basePath: config.basePath,
-        get routes() {
-            return registry.routes;
-        },
-    }));
     app.use(bodyParser());
     app.use(async (ctx, next) => {
         await next();

package/dist/server/dispatcher.js

@@ -3,6 +3,7 @@ import createDebugger from "debug";
 import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
 import { validateRequest } from "./request-validator.js";
+import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
 function parseCookies(cookieHeader) {
@@ -131,7 +132,7 @@ export class Dispatcher {
         }
         return false;
     }
-    async request({ auth, body, headers = {}, method, path, query, req, }) {
+    async request({ auth, body, headers = {}, method, path, query, rawBody, req, }) {
         debug(`request: ${method} ${path}`);
         debug(`headers: ${JSON.stringify(headers)}`);
         debug(`body: ${JSON.stringify(body)}`);
@@ -177,12 +178,9 @@ export class Dispatcher {
             cookie: parseCookies(headers.cookie ?? headers.Cookie ?? ""),
             headers,
             proxy: async (url) => {
-                if (body !== undefined && headers.contentType !== "application/json") {
-                    throw new Error(`$.proxy() is currently limited to application/json requests. You tried to proxy to ${url} with a Content-Type of ${headers.contentType ?? "[unknown]"}. Please open an issue at https://github.com/pmcelhaney/counterfact/issues and prod me to fix this limitation.`);
-                }
                 delete headers.host;
                 const fetchResponse = await this.fetch(`${url}${req.path ?? ""}`, {
-                    body: body === undefined ? undefined : JSON.stringify(body),
+                    body: body === undefined ? undefined : rawBody,
                     headers: new Headers(headers),
                     method,
                 });
@@ -213,6 +211,21 @@ export class Dispatcher {
                 status: 406,
             };
         }
+        if (this.config?.validateResponses !== false) {
+            const validation = validateResponse(operation, normalizedResponse);
+            if (!validation.valid) {
+                return {
+                    ...normalizedResponse,
+                    appendedHeaders: [
+                        ...(normalizedResponse.appendedHeaders ?? []),
+                        ...validation.errors.map((error) => [
+                            "response-type-error",
+                            error,
+                        ]),
+                    ],
+                };
+            }
+        }
         return normalizedResponse;
     }
 }