@beignet/core 0.0.1 → 0.0.2

package/src/contracts/types.ts

@@ -1,42 +1,93 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { IdempotencyMeta } from "../idempotency";
 import type { OpenAPIOperationMeta } from "./openapi-meta";
 import type { RateLimitMeta } from "./rate-limit";
 
 /**
- * Any Standard Schema validator type
- * Replaces ZodTypeAny to support all Standard Schema compatible libraries
+ * Any Standard Schema compatible validator.
  */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
 
+/**
+ * Response schema for one HTTP status.
+ *
+ * Use `null` for empty responses such as 204.
+ */
 export type ContractResponseSchema = StandardSchema | null;
+
+/**
+ * Response schemas keyed by HTTP status code.
+ */
 export type ContractResponses = Partial<Record<number, ContractResponseSchema>>;
+
+/**
+ * Standard Beignet error response body.
+ */
 export type StandardErrorResponseBody = {
   code: string;
   message: string;
   details?: unknown;
   requestId?: string;
 };
+
+/**
+ * Standard Schema for Beignet's error envelope.
+ */
 export type StandardErrorResponseSchema = StandardSchemaV1<
   unknown,
   StandardErrorResponseBody
 >;
+
+/**
+ * Route-owned error definition stored in contract metadata.
+ */
 export type ContractErrorDefinition = {
+  /**
+   * Stable public error code.
+   */
   code: string;
+  /**
+   * HTTP status code.
+   */
   status: number;
+  /**
+   * Default human-readable message.
+   */
   message: string;
+  /**
+   * Optional details schema for TypeScript inference.
+   */
   details?: StandardSchema;
 };
+
+/**
+ * Route-owned error definitions keyed by catalog key.
+ */
 export type ContractErrorResponses = Record<string, ContractErrorDefinition>;
+
+/**
+ * Convert route-owned error definitions into standard envelope response schemas.
+ */
 export type ResponsesFromErrorDefinitions<T extends ContractErrorResponses> = {
   [K in keyof T as T[K]["status"]]: StandardErrorResponseSchema;
 };
+
+/**
+ * Header schema declaration for a contract.
+ */
 export type ContractHeaderSchemas =
   | StandardSchema
   | readonly StandardSchema[]
   | null;
 
+/**
+ * Header used to distinguish framework-owned and route-owned error responses.
+ */
 export const BEIGNET_ERROR_OWNER_HEADER = "x-beignet-error-owner";
 
+/**
+ * Infer merged header input from one or more Standard Schema header validators.
+ */
 export type InferHeaderSchemaInput<
   T extends ContractHeaderSchemas | undefined,
 > = T extends readonly StandardSchemaV1[]
@@ -45,6 +96,9 @@ export type InferHeaderSchemaInput<
     ? InferInput<T>
     : undefined;
 
+/**
+ * Infer merged header output from one or more Standard Schema header validators.
+ */
 export type InferHeaderSchemaOutput<
   T extends ContractHeaderSchemas | undefined,
 > = T extends readonly StandardSchemaV1[]
@@ -62,19 +116,19 @@ type UnionToIntersection<T> = (
   : never;
 
 /**
- * Infer the output type from a Standard Schema
+ * Infer the parsed output type from a Standard Schema.
  */
 export type InferOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
 /**
- * Infer the input type from a Standard Schema
+ * Infer the input type accepted by a Standard Schema.
  */
 export type InferInput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferInput<T>;
 
 /**
- * HTTP methods supported by contracts
+ * HTTP methods supported by contracts.
  */
 export type HttpMethod =
   | "GET"
@@ -85,20 +139,32 @@ export type HttpMethod =
   | "HEAD"
   | "OPTIONS";
 
+/**
+ * HTTP methods that may carry a JSON request body.
+ */
 export type BodyHttpMethod = Extract<HttpMethod, "POST" | "PUT" | "PATCH">;
 
+/**
+ * Runtime list of HTTP methods that support request bodies.
+ */
 export const BODY_HTTP_METHODS = [
   "POST",
   "PUT",
   "PATCH",
 ] as const satisfies readonly BodyHttpMethod[];
 
+/**
+ * Check whether a method supports a contract request body.
+ */
 export function methodSupportsRequestBody(
   method: HttpMethod,
 ): method is BodyHttpMethod {
   return (BODY_HTTP_METHODS as readonly HttpMethod[]).includes(method);
 }
 
+/**
+ * Runtime Standard Schema for Beignet's standard error envelope.
+ */
 export const STANDARD_ERROR_RESPONSE_SCHEMA: StandardErrorResponseSchema = {
   "~standard": {
     version: 1,
@@ -140,11 +206,12 @@ export const STANDARD_ERROR_RESPONSE_SCHEMA: StandardErrorResponseSchema = {
 };
 
 /**
- * Contract metadata - freeform object for policies, auth, etc.
- * May include an optional openapi namespace for OpenAPI-specific metadata,
- * and an optional rateLimit namespace for rate limiting configuration.
+ * Contract metadata consumed by hooks, OpenAPI, and app conventions.
  */
 export type ContractMeta = {
+  /**
+   * OpenAPI operation metadata.
+   */
   openapi?: OpenAPIOperationMeta;
   /**
    * Optional rate limit configuration for this contract.
@@ -152,11 +219,18 @@ export type ContractMeta = {
    * If absent, no rate limiting is applied.
    */
   rateLimit?: RateLimitMeta;
+  /**
+   * Optional idempotency configuration for this contract.
+   *
+   * This metadata is intended for hooks, docs, and OpenAPI. Use cases should
+   * still call `runIdempotently(...)` for workflows that must be retry-safe.
+   */
+  idempotency?: IdempotencyMeta;
   [namespace: string]: unknown;
 };
 
 /**
- * HTTP contract configuration
+ * Plain HTTP contract configuration consumed by server, client, and tooling.
  */
 export type HttpContractConfig<
   TMethod extends HttpMethod = HttpMethod,
@@ -182,21 +256,48 @@ export type HttpContractConfig<
    * Contract name without the resource namespace.
    */
   localName?: string;
+  /**
+   * HTTP method.
+   */
   method: TMethod;
+  /**
+   * Path template.
+   */
   path: TPath;
+  /**
+   * Path parameter schema.
+   */
   pathParams: TPathParams;
+  /**
+   * Query parameter schema.
+   */
   query: TQuery;
+  /**
+   * Request header schema or schemas.
+   */
   headers?: THeaders;
+  /**
+   * Request body schema.
+   */
   body: TBody;
+  /**
+   * Response schemas keyed by HTTP status code.
+   */
   responses: TResponses;
+  /**
+   * Contract metadata.
+   */
   metadata: TMeta;
 };
 
 /**
- * Any contract type
+ * Any HTTP contract config.
  */
 export type AnyContract = HttpContractConfig;
 
+/**
+ * Normalize a contract header declaration into a schema list.
+ */
 export function getContractHeaderSchemas(
   headers: ContractHeaderSchemas | undefined,
 ): readonly StandardSchema[] {

package/src/contracts/utils.ts

@@ -33,6 +33,12 @@ function getMeaningfulPathSegments(path: string): PathTemplateSegment[] {
   return segments;
 }
 
+/**
+ * Generate a stable contract name from an HTTP method and path.
+ *
+ * `/api` is ignored as a leading path segment so generated names focus on the
+ * resource shape.
+ */
 export function generateContractName(method: HttpMethod, path: string): string {
   const methodPrefix = methodNameMap[method];
   const segments = getMeaningfulPathSegments(path);

package/src/domain/entity.ts

@@ -1,12 +1,12 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 /**
- * Any Standard Schema validator type
+ * Any Standard Schema compatible validator.
  */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
 
 /**
- * Infer the output type from a Standard Schema
+ * Infer the parsed output type from a Standard Schema.
  */
 export type InferOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
@@ -67,7 +67,8 @@ function validateSchemaSync<T>(
 type AnyMethods = Record<string, any>;
 
 /**
- * Represents an instance of an entity with props, methods, and immutable update capability.
+ * Entity instance with validated props, attached methods, and immutable update
+ * helpers.
  */
 export type EntityInstance<
   Name extends string,
@@ -75,7 +76,7 @@ export type EntityInstance<
   Methods extends AnyMethods,
 > = InferOutput<Schema> & {
   /**
-   * Create a new entity instance with updated properties (immutable update).
+   * Create a new validated entity instance with patched properties.
    */
   with(
     patch: Partial<InferOutput<Schema>>,
@@ -89,30 +90,36 @@ export type EntityInstance<
 } & Methods;
 
 /**
- * Represents a defined Entity with schema and factory methods.
+ * Entity definition returned by `defineEntity(...).build()`.
  */
 export interface EntityDef<
   Name extends string,
   Schema extends StandardSchema,
   Methods extends AnyMethods,
 > {
-  /** The name of this entity (for debugging/introspection) */
+  /** Name used for debugging and introspection. */
   name: Name;
-  /** The Standard Schema for validating entity props */
+  /** Standard Schema used to validate entity props. */
   schema: Schema;
-  /** Create a new entity instance from props */
+  /**
+   * Create a new frozen entity instance from props.
+   *
+   * Returns a promise when the underlying Standard Schema validates async.
+   */
   create(
     props: InferOutput<Schema>,
   ):
     | EntityInstance<Name, Schema, Methods>
     | Promise<EntityInstance<Name, Schema, Methods>>;
-  /** Reconstruct an entity instance from JSON (e.g., from persistence) */
+  /**
+   * Reconstruct an entity instance from JSON, usually from persistence.
+   */
   fromJSON(
     json: InferOutput<Schema>,
   ):
     | EntityInstance<Name, Schema, Methods>
     | Promise<EntityInstance<Name, Schema, Methods>>;
-  /** Type alias for the entity instance type */
+  /** Type-only alias for the entity instance type. Undefined at runtime. */
   Type: EntityInstance<Name, Schema, Methods>;
 }
 
@@ -229,7 +236,11 @@ class EntityBuilder<
 }
 
 /**
- * Create a new Entity builder.
+ * Create a new entity builder.
+ *
+ * Entities validate props, attach domain methods, and return frozen immutable
+ * instances. `with(...)` revalidates the merged props. `.Type` is type-only and
+ * should be used with `typeof Entity.Type`.
  *
  * @example
  * ```ts

package/src/domain/events.ts

@@ -2,7 +2,7 @@ import type { EventDef, InferEventPayload, StandardSchema } from "../events";
 import { defineEvent } from "../events";
 
 /**
- * Represents a defined Domain Event with name and payload schema.
+ * Domain event definition with a stable name and payload schema.
  */
 export type DomainEventDef<
   Name extends string = string,
@@ -29,7 +29,10 @@ export type DomainEventDef<
 export type { InferEventPayload };
 
 /**
- * Create a new Domain Event definition.
+ * Create a new domain event definition.
+ *
+ * This is a domain-focused alias around `defineEvent(...)` for applications
+ * that separate domain events from integration events.
  *
  * @example
  * ```ts

package/src/domain/value-object.ts

@@ -1,12 +1,12 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 /**
- * Any Standard Schema validator type
+ * Any Standard Schema compatible validator.
  */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
 
 /**
- * Infer the output type from a Standard Schema
+ * Infer the parsed output type from a Standard Schema.
  */
 export type InferOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
@@ -51,21 +51,27 @@ async function isValid<T>(
 }
 
 /**
- * Represents a defined Value Object with validation and type information.
+ * Value object definition returned by `defineValueObject(...).build()`.
  */
 export interface ValueObjectDef<
   Name extends string,
   Schema extends StandardSchema,
 > {
-  /** The name of this value object (for debugging/introspection) */
+  /** Name used for debugging and introspection. */
   name: Name;
-  /** The schema used for validation (any Standard Schema compatible) */
+  /** Standard Schema used to validate values. */
   schema: Schema;
-  /** Create a validated value object from unknown input (async due to Standard Schema) */
+  /**
+   * Create a validated value from unknown input.
+   *
+   * This is async because Standard Schema validators may be async.
+   */
   create(input: unknown): Promise<InferOutput<Schema>>;
-  /** Type guard to check if an input is valid for this value object (async due to Standard Schema) */
+  /**
+   * Check whether an input is valid for this value object.
+   */
   isValid(input: unknown): Promise<boolean>;
-  /** Type alias for the inferred TypeScript type */
+  /** Type-only alias for the inferred TypeScript type. Undefined at runtime. */
   Type: InferOutput<Schema>;
 }
 
@@ -115,7 +121,11 @@ class ValueObjectBuilder<Name extends string, Schema extends StandardSchema> {
 }
 
 /**
- * Create a new Value Object builder.
+ * Create a new value object builder.
+ *
+ * Value objects are schema-backed primitives for domain concepts such as email
+ * addresses or money values. Beignet does not add a runtime brand; the schema
+ * output controls the runtime value.
  *
  * @example
  * ```ts

package/src/errors/catalog.ts

@@ -8,29 +8,39 @@ type ErrorDetailsSchema = StandardSchemaV1<unknown, unknown>;
 const APP_ERROR_BRAND = Symbol.for("beignet.AppError");
 
 /**
- * Definition of a single error in the catalog
+ * Definition for one application error catalog entry.
  */
 export interface ErrorDef<
   TDetails extends ErrorDetailsSchema | undefined =
     | ErrorDetailsSchema
     | undefined,
 > {
-  /** Unique, stable code used across layers (e.g. "TODO_NOT_FOUND") */
+  /** Unique, stable code used across layers, such as `"POST_NOT_FOUND"`. */
   code: string;
-  /** HTTP status code (e.g. 404, 401, 409, 422, 500, etc.) */
+  /** HTTP status code returned when this error crosses the HTTP boundary. */
   status: number;
-  /** Default human-readable message */
+  /** Default human-readable message. */
   message: string;
-  /** Optional schema for the structured details value */
+  /**
+   * Optional schema for the structured details value.
+   *
+   * Beignet uses this for TypeScript inference. Details are not runtime
+   * validated by `AppError`; validate before constructing errors when needed.
+   */
   details?: TDetails;
 }
 
 /**
- * A mapping of keys to error definitions.
- * Keys can be friendly identifiers, e.g. "TodoNotFound".
+ * App error catalog keyed by developer-friendly names.
+ *
+ * Keys are local identifiers used by `createAppError(...)`; the public stable
+ * error code lives on each `ErrorDef.code`.
  */
 export type ErrorCatalog = Record<string, ErrorDef>;
 
+/**
+ * Infer the details input type for an error definition.
+ */
 export type InferErrorDetails<TDef extends ErrorDef> = TDef extends {
   details: ErrorDetailsSchema;
 }
@@ -38,21 +48,23 @@ export type InferErrorDetails<TDef extends ErrorDef> = TDef extends {
   : unknown;
 
 /**
- * Type-preserving helper to define an error catalog.
+ * Define an application error catalog without losing literal key and code types.
  */
 export function defineErrors<const T extends ErrorCatalog>(defs: T): T {
   return defs;
 }
 
 /**
- * Application error class that domain & application code can throw.
- * Contains the error definition from the catalog and optional structured details.
+ * Application error thrown from use cases, policies, and route handlers.
+ *
+ * The server maps `AppError` instances to Beignet's standard error envelope and
+ * marks them as route-owned errors when the contract declares the catalog entry.
  */
 export class AppError<TDef extends ErrorDef = ErrorDef> extends Error {
   readonly [APP_ERROR_BRAND] = true;
-  /** The error definition from the catalog */
+  /** Error definition from the catalog. */
   readonly def: TDef;
-  /** Optional structured details (for debugging, UI, etc.) */
+  /** Optional structured details for clients, logs, or UI. */
   readonly details?: InferErrorDetails<TDef>;
 
   constructor(
@@ -67,22 +79,31 @@ export class AppError<TDef extends ErrorDef = ErrorDef> extends Error {
     this.details = details;
   }
 
+  /**
+   * Stable public error code.
+   */
   get code(): string {
     return this.def.code;
   }
 
+  /**
+   * HTTP status code associated with this error.
+   */
   get status(): number {
     return this.def.status;
   }
 }
 
 /**
- * Callable helper for creating AppErrors from a catalog.
+ * Callable helper for creating `AppError` instances from a catalog.
  */
 export type AppErrorCreator<TCatalog extends ErrorCatalog> = {
+  /**
+   * Original catalog bound to this creator.
+   */
   catalog: TCatalog;
   /**
-   * Create an AppError from a catalog key.
+   * Create an `AppError` from a catalog key.
    */
   <Key extends keyof TCatalog>(
     key: Key,
@@ -95,7 +116,10 @@ export type AppErrorCreator<TCatalog extends ErrorCatalog> = {
 };
 
 /**
- * Create a callable AppError helper bound to a specific catalog.
+ * Create a callable `AppError` helper bound to a specific catalog.
+ *
+ * The returned function validates the catalog key and preserves each entry's
+ * details type for `options.details`.
  */
 export function createAppError<const T extends ErrorCatalog>(
   catalog: T,
@@ -127,7 +151,7 @@ export function createAppError<const T extends ErrorCatalog>(
 }
 
 /**
- * Type guard to check if an unknown error is an AppError
+ * Check whether an unknown value is a Beignet `AppError`.
  */
 export function isAppError(err: unknown): err is AppError<ErrorDef> {
   if (err instanceof AppError) return true;

package/src/errors/response.ts

@@ -5,17 +5,29 @@
 import type { AppError, ErrorDef } from "./catalog";
 
 /**
- * Standard error response body structure
+ * Standard Beignet error response body.
  */
 export interface ErrorResponseBody {
+  /**
+   * Stable machine-readable error code.
+   */
   code: string;
+  /**
+   * Human-readable error message.
+   */
   message: string;
+  /**
+   * Optional structured details.
+   */
   details?: unknown;
+  /**
+   * Optional request ID for support and log correlation.
+   */
   requestId?: string;
 }
 
 /**
- * Create a standard error response body.
+ * Create a standard error response body and omit undefined optional fields.
  */
 export function createErrorResponseBody(
   args: ErrorResponseBody,
@@ -29,7 +41,7 @@ export function createErrorResponseBody(
 }
 
 /**
- * Check whether a value is a standard error response body.
+ * Check whether a value looks like a standard Beignet error response body.
  */
 export function isErrorResponseBody(
   value: unknown,
@@ -41,7 +53,7 @@ export function isErrorResponseBody(
 }
 
 /**
- * Convert an AppError to a standard error response body
+ * Convert an `AppError` to a standard error response body.
  */
 export function toErrorResponseBody(
   err: AppError<ErrorDef>,

package/src/errors/validation.ts

@@ -1,10 +1,16 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 /**
- * Normalized validation issue with simplified path
+ * Normalized validation issue with a simplified path.
  */
 export interface ValidationIssue {
+  /**
+   * Path to the invalid value.
+   */
   path?: (string | number)[];
+  /**
+   * Human-readable validation message.
+   */
   message: string;
 }
 
@@ -14,6 +20,9 @@ export interface ValidationIssue {
  * regardless of which package threw the error.
  */
 export class SchemaValidationError extends Error {
+  /**
+   * Normalized validation issues.
+   */
   readonly issues: ReadonlyArray<ValidationIssue>;
 
   constructor(rawIssues: ReadonlyArray<StandardSchemaV1.Issue>) {