@beignet/core 0.0.1 → 0.0.3

package/src/config/index.ts

@@ -7,19 +7,39 @@
 
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
+/**
+ * Any Standard Schema compatible validator.
+ */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Runtime environment object shape.
+ */
 export type RuntimeEnv = Record<string, string | undefined>;
+
+/**
+ * Map of environment variable names to Standard Schema validators.
+ */
 export type EnvSchemaShape = Record<string, StandardSchema>;
 type EmptyEnvSchemaShape = Record<keyof never, never>;
 type NoInferType<T> = [T][T extends unknown ? 0 : never];
 
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
 export type InferOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
+/**
+ * Infer the parsed output object for an env schema shape.
+ */
 export type InferEnvShape<Shape extends EnvSchemaShape> = {
   [Key in keyof Shape]: InferOutput<Shape[Key]>;
 };
 
+/**
+ * Env schema shape constrained to a client prefix.
+ */
 export type ClientEnvSchemaShape<ClientPrefix extends string> =
   ClientPrefix extends ""
     ? EnvSchemaShape
@@ -36,9 +56,18 @@ type ValidateClientEnvShape<
         : never;
     };
 
+/**
+ * Raw Standard Schema validation issue produced while loading config.
+ */
 export type EnvValidationIssue = StandardSchemaV1.Issue;
 
+/**
+ * Error thrown when Beignet config validation fails.
+ */
 export class ConfigValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
   readonly issues: readonly EnvValidationIssue[];
 
   constructor(issues: readonly EnvValidationIssue[], message?: string) {
@@ -48,12 +77,27 @@ export class ConfigValidationError extends Error {
   }
 }
 
+/**
+ * Options for reading raw environment variables.
+ */
 export interface ReadEnvOptions {
+  /**
+   * Runtime environment object. Defaults to `process.env`.
+   */
   env?: RuntimeEnv;
+  /**
+   * Optional prefix to filter and strip from matching keys.
+   */
   prefix?: string;
+  /**
+   * Treat empty strings as missing values.
+   */
   emptyStringAsUndefined?: boolean;
 }
 
+/**
+ * Options for defining a single validated env loader.
+ */
 export interface DefineEnvOptions<Schema extends StandardSchemaV1> {
   /**
    * Standard Schema for validating the full environment object.
@@ -88,10 +132,19 @@ export interface DefineEnvOptions<Schema extends StandardSchemaV1> {
   onValidationError?: (issues: readonly EnvValidationIssue[]) => never;
 }
 
+/**
+ * Validated env loader returned by `defineEnv(...)`.
+ */
 export interface EnvInstance<Out> {
+  /**
+   * Read and validate the environment.
+   */
   load(options?: { env?: RuntimeEnv }): Out;
 }
 
+/**
+ * Options for `createEnv(...)`.
+ */
 export interface CreateEnvOptions<
   Server extends EnvSchemaShape,
   ClientPrefix extends string,
@@ -156,6 +209,9 @@ export interface CreateEnvOptions<
   onInvalidAccess?: (key: string) => never;
 }
 
+/**
+ * Parsed env object returned by `createEnv(...)`.
+ */
 export type CreateEnvResult<
   Server extends EnvSchemaShape,
   Client extends EnvSchemaShape,
@@ -215,6 +271,9 @@ function prependIssuePath(
   };
 }
 
+/**
+ * Format Standard Schema issues into a single readable message.
+ */
 export function formatStandardSchemaIssues(
   issues: readonly StandardSchemaV1.Issue[],
 ): string {
@@ -226,6 +285,11 @@ export function formatStandardSchemaIssues(
     .join("; ");
 }
 
+/**
+ * Read raw environment variables, optionally filtering by prefix.
+ *
+ * When a prefix is provided, matching keys are stripped before being returned.
+ */
 export function readEnv({
   env = defaultRuntimeEnv(),
   prefix,
@@ -265,6 +329,11 @@ function validationResultValue<Schema extends StandardSchemaV1>(
   throw new Error("Invalid Standard Schema result: missing value");
 }
 
+/**
+ * Validate input with a synchronous Standard Schema.
+ *
+ * Throws when the schema returns a promise because env loading is synchronous.
+ */
 export function parseStandardSchemaSync<Schema extends StandardSchemaV1>(
   schema: Schema,
   input: unknown,
@@ -286,6 +355,9 @@ export function parseStandardSchemaSync<Schema extends StandardSchemaV1>(
   return validationResultValue<Schema>(result);
 }
 
+/**
+ * Validate input with a Standard Schema that may be synchronous or async.
+ */
 export async function parseStandardSchemaAsync<Schema extends StandardSchemaV1>(
   schema: Schema,
   input: unknown,
@@ -323,6 +395,12 @@ function wrapEnvError(err: unknown, prefix?: string): Error {
   );
 }
 
+/**
+ * Define a reusable validated env loader.
+ *
+ * This is useful for provider config and app-level config objects that are
+ * loaded from a prefixed subset of the environment.
+ */
 export function defineEnv<Schema extends StandardSchemaV1>(
   options: DefineEnvOptions<Schema>,
 ): EnvInstance<InferOutput<Schema>> {
@@ -419,6 +497,14 @@ function validateRuntimeEnvStrict(
   );
 }
 
+/**
+ * Create a server/client split env object.
+ *
+ * Server variables are available only on the server. Client variables must use
+ * `clientPrefix` when provided. Validation is synchronous, empty strings are
+ * treated as undefined by default, and client access to server-only keys throws
+ * through the returned proxy.
+ */
 export function createEnv<
   const ClientPrefix extends string = "",
   Server extends EnvSchemaShape = EmptyEnvSchemaShape,

package/src/contracts/contract-builder.ts

@@ -72,8 +72,12 @@ function assertNoCatalogErrorStatusConflicts(
 }
 
 /**
- * Contract builder for constructing HTTP contracts in a fluent API style
- * Schemas are accessible via the .schema property for introspection
+ * Fluent builder for one HTTP contract.
+ *
+ * A contract describes the transport boundary for one endpoint: method, path,
+ * request schemas, response schemas, metadata, and route-owned catalog errors.
+ * Builder methods are immutable; each call returns a new builder with narrower
+ * types.
  */
 export class ContractBuilder<
   TMethod extends HttpMethod,
@@ -130,7 +134,10 @@ export class ContractBuilder<
   }
 
   /**
-   * Access schemas for introspection
+   * Request and response schemas attached to this contract.
+   *
+   * Server adapters use these for validation. Client and frontend integrations
+   * use them for local validation and type inference.
    */
   get schema() {
     return {
@@ -143,36 +150,35 @@ export class ContractBuilder<
   }
 
   /**
-   * Get response schemas for introspection
+   * Response schemas keyed by HTTP status code.
    */
   get responseSchemas(): TResponses {
     return this._responses;
   }
 
   /**
-   * Get the URL path template
+   * URL path template for this contract.
    */
   get pathTemplate(): TPath {
     return this._path;
   }
 
   /**
-   * Get the URL path (alias for pathTemplate)
+   * URL path template alias.
    */
   get path(): TPath {
     return this._path;
   }
 
   /**
-   * Get contract metadata
+   * Metadata consumed by hooks, OpenAPI generation, and app conventions.
    */
   get metadata(): TMeta {
     return this._meta;
   }
 
   /**
-   * Get the contract as an HttpContractConfig object
-   * Use this when passing to adapters that expect the plain config type
+   * Plain contract config consumed by framework internals and integrations.
    */
   get config(): HttpContractConfig<
     TMethod,
@@ -201,7 +207,10 @@ export class ContractBuilder<
   }
 
   /**
-   * Set path parameters schema (chainable builder method)
+   * Attach a schema for dynamic path parameters.
+   *
+   * The schema validates parameters parsed from path templates such as
+   * `/posts/:id` or `/posts/[id]`.
    */
   pathParams<TNewPathParams extends StandardSchemaV1>(
     schema: TNewPathParams,
@@ -232,7 +241,7 @@ export class ContractBuilder<
   }
 
   /**
-   * Set query parameters schema (chainable builder method)
+   * Attach a schema for query parameters.
    */
   query<TNewQuery extends StandardSchemaV1>(
     schema: TNewQuery,
@@ -263,8 +272,9 @@ export class ContractBuilder<
   }
 
   /**
-   * Set request body schema (chainable builder method)
-   * Only available on POST, PUT, and PATCH contracts.
+   * Attach a schema for a JSON request body.
+   *
+   * This method is only available on POST, PUT, and PATCH contracts.
    */
   body<TNewBody extends StandardSchemaV1>(
     this: ContractBuilder<
@@ -315,10 +325,11 @@ export class ContractBuilder<
   }
 
   /**
-   * Add request header schema (chainable).
+   * Attach a request header schema.
    *
    * Multiple schemas are evaluated in declaration order and their parsed
-   * outputs are merged. This keeps group-level headers library-agnostic.
+   * outputs are merged. This lets a contract inherit shared group headers and
+   * still declare route-specific headers.
    */
   headers<TNewHeaders extends StandardSchemaV1>(
     schema: TNewHeaders,
@@ -366,7 +377,12 @@ export class ContractBuilder<
   }
 
   /**
-   * Add or replace response schemas by status code (chainable).
+   * Add or replace route-owned response schemas by status code.
+   *
+   * These schemas describe business responses returned by route handlers.
+   * Framework-owned errors such as request validation failures do not need to be
+   * declared here.
+   *
    * Use `null` for void/empty responses such as 204 No Content.
    */
   responses<TNewResponses extends ContractResponses>(
@@ -404,8 +420,9 @@ export class ContractBuilder<
   /**
    * Declare route-owned application errors from an error catalog.
    *
-   * Catalog errors use Beignet's standard error response envelope. Use
-   * `.responses()` when a route needs a custom error response body.
+   * Catalog errors use Beignet's standard error response envelope and remain
+   * distinguishable from framework-owned errors. Use `.responses()` when a
+   * route needs a custom error response body instead of catalog semantics.
    */
   errors<TErrorDefs extends ContractErrorResponses>(
     errorDefs: TErrorDefs,
@@ -449,7 +466,10 @@ export class ContractBuilder<
   }
 
   /**
-   * Set or merge contract metadata (chainable builder method)
+   * Merge metadata into this contract.
+   *
+   * Hooks and tooling can read metadata for concerns such as auth, rate limits,
+   * idempotency, OpenAPI, or app-specific conventions.
    */
   meta<TNewMeta extends ContractMeta>(
     newMeta: TNewMeta,
@@ -483,7 +503,7 @@ export class ContractBuilder<
   }
 
   /**
-   * Set or merge OpenAPI metadata for this operation (chainable)
+   * Merge OpenAPI operation metadata into this contract.
    */
   openapi(
     patch: Partial<OpenAPIOperationMeta>,
@@ -522,7 +542,7 @@ export class ContractBuilder<
 }
 
 /**
- * Options for creating a contract with the factory function
+ * Options for creating one contract with `createContract(...)`.
  */
 export type CreateContractOptions<
   TMethod extends HttpMethod = HttpMethod,
@@ -537,7 +557,11 @@ export type CreateContractOptions<
 };
 
 /**
- * Create a new HTTP contract with the builder pattern.
+ * Create a new HTTP contract builder.
+ *
+ * Most apps prefer `createContractGroup().namespace(...).prefix(...)` for
+ * related feature contracts. Use this lower-level factory when a standalone
+ * contract is clearer.
  *
  * @example
  * ```ts
@@ -548,6 +572,9 @@ export type CreateContractOptions<
  *   .pathParams(z.object({ id: z.string() }))
  *   .responses({ 200: TodoSchema });
  * ```
+ *
+ * @param options - HTTP method, path template, and optional contract name.
+ * @returns A fluent contract builder.
  */
 export function createContract<
   TMethod extends HttpMethod,

package/src/contracts/contract-group.ts

@@ -103,8 +103,11 @@ function assertNoCatalogErrorStatusConflicts(
 }
 
 /**
- * ContractGroup is a feature-scoped factory for creating related contracts
- * with shared configuration. Immutable — each method returns a new instance.
+ * Feature-scoped factory for related HTTP contracts.
+ *
+ * Contract groups let a feature share a namespace, path prefix, headers,
+ * responses, errors, and metadata across multiple endpoint contracts. The group
+ * is immutable: every configuration method returns a new group.
  */
 export class ContractGroup<
   TSharedResponses extends ContractResponses = Record<never, never>,
@@ -141,7 +144,10 @@ export class ContractGroup<
   }
 
   /**
-   * Set the namespace for all contracts created from this group
+   * Set the namespace for contracts created from this group.
+   *
+   * The namespace prefixes contract names, not paths. Use `prefix(...)` for
+   * path composition.
    */
   namespace(
     ns: string,
@@ -156,10 +162,10 @@ export class ContractGroup<
   }
 
   /**
-   * Add a path prefix to all contracts created from this group.
+   * Add a path prefix to contracts created from this group.
    *
-   * Prefixes compose immutably, so `prefix("/api").prefix("/v1")`
-   * produces paths under `/api/v1`.
+   * Prefixes compose immutably, so `prefix("/api").prefix("/v1")` produces
+   * paths under `/api/v1`.
    */
   prefix<const TNewPrefix extends string>(
     pathPrefix: TNewPrefix,
@@ -183,7 +189,7 @@ export class ContractGroup<
   }
 
   /**
-   * Set shared metadata for all contracts created from this group
+   * Merge shared metadata into contracts created from this group.
    */
   meta<TNewMeta extends ContractMeta>(
     meta: TNewMeta,
@@ -207,8 +213,10 @@ export class ContractGroup<
   }
 
   /**
-   * Set shared response schemas for all contracts created from this group.
-   * Typically used for shared error responses (e.g. 401, 403, 500).
+   * Add shared route-owned response schemas to contracts created from this group.
+   *
+   * Framework-owned responses, such as validation or auth hook failures, do not
+   * need to be declared here.
    */
   responses<TNewResponses extends ContractResponses>(
     responseSchemas: TNewResponses,
@@ -233,7 +241,10 @@ export class ContractGroup<
   }
 
   /**
-   * Set shared route-owned application errors for all contracts in the group.
+   * Declare shared route-owned application errors for contracts in this group.
+   *
+   * Catalog errors use Beignet's standard error envelope and remain separate
+   * from framework-owned errors.
    */
   errors<TErrorDefs extends ContractErrorResponses>(
     errorDefs: TErrorDefs,
@@ -263,7 +274,7 @@ export class ContractGroup<
   }
 
   /**
-   * Add shared request header schema for all contracts created from this group.
+   * Add a shared request header schema to contracts created from this group.
    */
   headers<TNewHeaders extends StandardSchema>(
     schema: TNewHeaders,
@@ -300,7 +311,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a GET contract
+   * Create a GET contract under this group.
    */
   get<const TPath extends string>(
     path: TPath,
@@ -319,7 +330,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a POST contract
+   * Create a POST contract under this group.
    */
   post<const TPath extends string>(
     path: TPath,
@@ -338,7 +349,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a PUT contract
+   * Create a PUT contract under this group.
    */
   put<const TPath extends string>(
     path: TPath,
@@ -357,7 +368,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a PATCH contract
+   * Create a PATCH contract under this group.
    */
   patch<const TPath extends string>(
     path: TPath,
@@ -376,7 +387,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a DELETE contract
+   * Create a DELETE contract under this group.
    */
   delete<const TPath extends string>(
     path: TPath,
@@ -395,7 +406,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a HEAD contract
+   * Create a HEAD contract under this group.
    */
   head<const TPath extends string>(
     path: TPath,
@@ -414,7 +425,7 @@ export class ContractGroup<
   }
 
   /**
-   * Create a OPTIONS contract
+   * Create an OPTIONS contract under this group.
    */
   options<const TPath extends string>(
     path: TPath,
@@ -477,7 +488,10 @@ export class ContractGroup<
 }
 
 /**
- * Create a new ContractGroup for grouping related contracts with shared configuration.
+ * Create a new feature contract group.
+ *
+ * Start here for most feature HTTP surfaces, then add a namespace and path
+ * prefix before defining individual contracts.
  *
  * @example
  * ```ts
@@ -491,6 +505,8 @@ export class ContractGroup<
  *
  * const getTodo = todos.get("/:id")...
  * ```
+ *
+ * @returns An empty immutable contract group.
  */
 export function createContractGroup(): ContractGroup<
   Record<never, never>,

package/src/contracts/contract-like.ts

@@ -1,13 +1,12 @@
 import type { HttpContractConfig } from "./types";
 
 /**
- * A type that represents either a raw HttpContractConfig
- * or a contract-like object with a .config property (e.g., ContractBuilder)
+ * Contract input accepted by APIs that can unwrap builders.
  */
 export type ContractLike = HttpContractConfig | { config: HttpContractConfig };
 
 /**
- * Resolves a ContractLike to its underlying HttpContractConfig
+ * Resolve a contract-like type to its plain `HttpContractConfig`.
  */
 export type ResolveContract<T> = T extends { config: infer C }
   ? C extends HttpContractConfig
@@ -18,7 +17,8 @@ export type ResolveContract<T> = T extends { config: infer C }
     : never;
 
 /**
- * Helper function to resolve a ContractLike to its underlying HttpContractConfig
+ * Resolve a contract builder or plain config to the underlying contract config.
+ *
  * @param c - The contract-like object to resolve
  * @returns The underlying HttpContractConfig
  */

package/src/contracts/index.ts

@@ -4,26 +4,53 @@
  * HTTP contract definitions and builders for Beignet.
  */
 
+/**
+ * Standard Schema type re-exported for contract authors.
+ */
 export type { StandardSchemaV1 } from "@standard-schema/spec";
-
+/**
+ * Idempotency metadata types for contracts.
+ */
+export type { IdempotencyMeta, IdempotencyScopeMode } from "../idempotency";
+/**
+ * Contract builder exports.
+ */
 export {
   ContractBuilder,
   type CreateContractOptions,
   createContract,
 } from "./contract-builder";
+/**
+ * Contract group exports.
+ */
 export { ContractGroup, createContractGroup } from "./contract-group";
+/**
+ * Contract-like helper exports.
+ */
 export {
   type ContractLike,
   type ResolveContract,
   resolveContract,
 } from "./contract-like";
+/**
+ * OpenAPI operation metadata type.
+ */
 export type { OpenAPIOperationMeta } from "./openapi-meta";
+/**
+ * Path template parsing exports.
+ */
 export {
   type ParsedPathTemplate,
   type PathTemplateSegment,
   parsePathTemplate,
 } from "./path-template";
+/**
+ * Rate limit metadata types for contracts.
+ */
 export type { RateLimitMeta, RateLimitScope } from "./rate-limit";
+/**
+ * Contract config and inference types.
+ */
 export type {
   AnyContract,
   BodyHttpMethod,

package/src/contracts/openapi-meta.ts

@@ -1,22 +1,22 @@
 /**
- * OpenAPI operation-level metadata for HTTP contracts
+ * OpenAPI operation-level metadata for HTTP contracts.
  */
 export type OpenAPIOperationMeta = {
-  /** A brief summary of the operation */
+  /** Brief operation summary. */
   summary?: string;
-  /** A detailed description of the operation */
+  /** Detailed operation description. */
   description?: string;
-  /** Tags for grouping operations */
+  /** Tags used to group operations. */
   tags?: string[];
-  /** Marks the operation as deprecated */
+  /** Whether the operation is deprecated. */
   deprecated?: boolean;
-  /** External documentation reference */
+  /** External documentation reference. */
   externalDocs?: {
     description?: string;
     url: string;
   };
-  /** Override for operationId (default is contract.name) */
+  /** Operation ID override. Defaults to `contract.name`. */
   operationId?: string;
-  /** Per-operation security requirements */
+  /** Per-operation security requirements. */
   security?: Array<Record<string, string[]>>;
 };

package/src/contracts/path-template.ts

@@ -1,12 +1,33 @@
+/**
+ * Parsed path segment from a Beignet route template.
+ */
 export type PathTemplateSegment =
   | { kind: "static"; value: string }
   | { kind: "dynamic"; name: string; raw: string };
 
+/**
+ * Parsed representation of a Beignet route path template.
+ */
 export interface ParsedPathTemplate {
+  /**
+   * Dynamic parameter names in declaration order.
+   */
   keys: string[];
+  /**
+   * Static and dynamic path segments.
+   */
   segments: PathTemplateSegment[];
+  /**
+   * Normalized Beignet path using `:param` dynamic syntax.
+   */
   normalizedPath: string;
+  /**
+   * Route shape used for ambiguity detection, ignoring dynamic parameter names.
+   */
   shapeKey: string;
+  /**
+   * OpenAPI-compatible path using `{param}` syntax.
+   */
   openApiPath: string;
 }
 
@@ -43,6 +64,12 @@ function parsePathSegment(path: string, segment: string): PathTemplateSegment {
   return { kind: "static", value: segment };
 }
 
+/**
+ * Parse a Beignet route path template.
+ *
+ * Paths must start with `/`. Dynamic segments may use `:id` or `[id]`.
+ * Catch-all segments and partial dynamic segments are intentionally rejected.
+ */
 export function parsePathTemplate(path: string): ParsedPathTemplate {
   if (!path.startsWith("/")) {
     throw new Error(