counterfact 2.6.0 → 2.8.1

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,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;
+}