counterfact 2.5.1 → 2.7.0

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

@@ -0,0 +1,164 @@
+import type { COUNTERFACT_RESPONSE } from "./counterfact-response.js";
+import type { CookieOptions } from "./cookie-options.js";
+import type { ExampleNames } from "./example-names.js";
+import type { IfHasKey } from "./if-has-key.js";
+import type { MediaType } from "./media-type.js";
+import type { OmitAll } from "./omit-all.js";
+import type { OmitValueWhenNever } from "./omit-value-when-never.js";
+import type { OpenApiResponse } from "./open-api-response.js";
+import type { RandomFunction } from "./random-function.js";
+
+/**
+ * Returns `never` when `Record` is an empty object type (`{}`), signalling
+ * that there are no remaining choices available on the response builder.
+ */
+type NeverIfEmpty<Record> = object extends Record ? never : Record;
+
+/**
+ * Extracts the union of schema types from a map of media-type content entries.
+ * Used to type the body argument of shortcut methods like `.json()` or `.html()`.
+ */
+type SchemasOf<T extends { [key: string]: { schema: unknown } }> = {
+  [K in keyof T]: T[K]["schema"];
+}[keyof T];
+
+/**
+ * Produces a builder method for a shortcut (e.g. `.json()`, `.html()`) when
+ * the response contains at least one of the given `ContentTypes`, and `never`
+ * otherwise. Calling the method narrows the builder by removing those content
+ * types from the remaining options.
+ */
+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
+>;
+
+/**
+ * The type of the `.match(contentType, body)` method on the generic response
+ * builder. Calling it narrows the builder by removing the chosen content type
+ * from the remaining options.
+ */
+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"];
+}>;
+
+/**
+ * The type of the `.header(name, value)` method on the generic response
+ * builder. Calling it narrows the builder by removing the satisfied header
+ * from the set of required headers.
+ */
+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>;
+}>;
+
+/**
+ * The inner shape of the generic response builder, listing all methods that
+ * are currently available given the remaining response constraints.
+ * Methods whose type resolves to `never` are stripped by `OmitValueWhenNever`.
+ *
+ * Note: `[T] extends [never]` (non-distributive tuple wrapping) is used
+ * alongside `[keyof T] extends [never]` to correctly handle both `T = never`
+ * (spec-generated no-body) and `T = {}` (all content types consumed) cases.
+ * TypeScript evaluates `keyof never` as `string | number | symbol`, so a
+ * direct `[keyof never] extends [never]` check would incorrectly return false.
+ */
+export type GenericResponseBuilderInner<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = OmitValueWhenNever<{
+  binary: MaybeShortcut<["application/octet-stream"], Response>;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => GenericResponseBuilder<Response>;
+  empty: [Response["content"]] extends [never]
+    ? () => COUNTERFACT_RESPONSE
+    : [keyof Response["content"]] extends [never]
+      ? () => COUNTERFACT_RESPONSE
+      : never;
+  header: [Response["headers"]] extends [never]
+    ? never
+    : [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: [Response["content"]] extends [never]
+    ? never
+    : [keyof Response["content"]] extends [never]
+      ? never
+      : MatchFunction<Response>;
+  random: [Response["content"]] extends [never]
+    ? never
+    : [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>;
+}>;
+
+/**
+ * The strongly-typed, fluent response builder generated for each operation in
+ * a route handler. Its available methods are derived from the OpenAPI response
+ * schema: as methods are called, the builder type narrows until all required
+ * content and headers have been provided, at which point it resolves to
+ * `COUNTERFACT_RESPONSE`.
+ *
+ * When a Response type carries an `examples` key it is a spec-generated
+ * response (either the initial no-body builder or a builder that still has
+ * content/headers to satisfy). Those always go through
+ * `GenericResponseBuilderInner`, which exposes `empty()` when `content` is
+ * `never`.
+ *
+ * When a Response type has no `examples` key it is a narrowed type produced
+ * by a method call (e.g. `.json()` sets the body and returns a type without
+ * `examples`). Those go through the existing collapse logic so that
+ * fully-satisfied responses resolve directly to `COUNTERFACT_RESPONSE`.
+ */
+export type GenericResponseBuilder<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = "examples" extends keyof Response
+  ? GenericResponseBuilderInner<Response>
+  : object extends OmitValueWhenNever<Omit<Response, "examples">>
+    ? COUNTERFACT_RESPONSE
+    : keyof OmitValueWhenNever<Omit<Response, "examples">> extends "headers"
+      ? {
+          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
+          header: HeaderFunction<Response>;
+        }
+      : GenericResponseBuilderInner<Response>;

package/dist/server/counterfact-types/http-status-code.ts

@@ -0,0 +1,62 @@
+/**
+ * A union of all standard HTTP status codes.
+ * Used to constrain the status code argument in response builder calls and
+ * generated route handler types.
+ */
+export 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;

package/dist/server/counterfact-types/if-has-key.ts

@@ -0,0 +1,19 @@
+/**
+ * Conditional type that resolves to `Yes` when `SomeObject` has at least one
+ * key that contains any string from `Keys` as a substring, and `No` otherwise.
+ * Used to determine whether a shortcut method (e.g. `.json()`, `.html()`)
+ * should be present on the response builder for a given response type.
+ */
+export 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;

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

@@ -1,329 +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;
-  schema?: {
-    type: string;
-  };
-  type?: "string" | "number" | "integer" | "boolean";
-}
-
-interface OpenApiOperation {
-  parameters?: OpenApiParameters[];
-  produces?: string[];
-  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";
+}