@beignet/core 0.0.1 → 0.0.2

package/src/application/index.ts

@@ -1,18 +1,18 @@
 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>;
 
 /**
- * Infer the input type accepted by a Standard Schema
+ * Infer the input type accepted by a Standard Schema.
  */
 export type InferInput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferInput<T>;
@@ -20,6 +20,9 @@ export type InferInput<T extends StandardSchemaV1> =
 type SchemaInput<T> = T extends StandardSchemaV1 ? InferInput<T> : never;
 type SchemaOutput<T> = T extends StandardSchemaV1 ? InferOutput<T> : never;
 
+/**
+ * Boundary phase that failed use-case schema validation.
+ */
 export type UseCaseValidationPhase = "input" | "output";
 
 /**
@@ -139,11 +142,20 @@ async function parseSchema<TSchema extends StandardSchemaV1>(
 }
 
 /**
- * Represents a domain event definition (from @beignet/core/domain or compatible).
- * This is a minimal interface to avoid hard dependency on @beignet/core/domain.
+ * Minimal domain event definition accepted by use-case event helpers.
+ *
+ * This matches events from `@beignet/core/events` and compatible app-owned
+ * definitions without forcing the application builder to depend on one event
+ * implementation.
  */
 export interface DomainEventLike {
+  /**
+   * Stable event name.
+   */
   name: string;
+  /**
+   * Standard Schema payload validator.
+   */
   payload: StandardSchema;
 }
 
@@ -157,16 +169,22 @@ export type InferUseCaseEventPayload<E extends DomainEventLike> =
  * Minimal recorder shape accepted by use-case event helpers.
  */
 export interface UseCaseEventRecorderTarget {
+  /**
+   * Record a domain event payload.
+   */
   record<E extends DomainEventLike>(
     event: E,
     payload: InferUseCaseEventPayload<E>,
-  ): void;
+  ): Promise<void> | void;
 }
 
 /**
  * Minimal event-bus shape accepted by use-case event helpers.
  */
 export interface UseCaseEventBusTarget {
+  /**
+   * Publish a domain event payload.
+   */
   publish<E extends DomainEventLike>(
     event: E,
     payload: InferUseCaseEventPayload<E>,
@@ -278,7 +296,7 @@ function createUseCaseEventHelpers<Emits extends readonly DomainEventLike[]>(
         payload,
         useCaseName,
       );
-      recorder.record(declaredEvent, parsed);
+      await recorder.record(declaredEvent, parsed);
     },
     async publish(eventBus, event, payload) {
       const declaredEvent = resolveDeclared(event) as typeof event;
@@ -298,7 +316,10 @@ function createUseCaseEventHelpers<Emits extends readonly DomainEventLike[]>(
 export type UseCaseKind = "command" | "query";
 
 /**
- * Use case definition - the final form consumed by server adapters
+ * Finalized use case definition.
+ *
+ * Use cases validate their input before `run(...)` executes and validate their
+ * output before returning, unless validation is disabled on the builder.
  */
 export interface UseCaseDef<
   Ctx,
@@ -308,13 +329,26 @@ export interface UseCaseDef<
   OutputSchema extends StandardSchemaV1,
   Emits extends readonly DomainEventLike[] = readonly [],
 > {
+  /**
+   * Stable use-case name, usually namespaced by feature.
+   */
   name: Name;
+  /**
+   * Whether this use case is a command or query.
+   */
   kind: Kind;
   /** Input schema, suitable for reuse in HTTP contracts and forms. */
   inputSchema: InputSchema;
   /** Output schema, suitable for reuse in HTTP contracts and clients. */
   outputSchema: OutputSchema;
+  /**
+   * Domain events this use case is allowed to record or publish through the
+   * scoped `events` helper.
+   */
   emits: Emits;
+  /**
+   * Execute the use case with application context and typed input.
+   */
   run: (args: {
     ctx: Ctx;
     input: InferInput<InputSchema>;
@@ -322,19 +356,37 @@ export interface UseCaseDef<
 }
 
 /**
- * Event passed to the onRun hook for instrumentation
+ * Event passed to the `onRun` hook for instrumentation.
  */
 export interface UseCaseRunEvent<Ctx> {
+  /**
+   * Use-case name.
+   */
   name: string;
+  /**
+   * Use-case kind.
+   */
   kind: UseCaseKind;
+  /**
+   * Execution phase being observed.
+   */
   phase: "start" | "end" | "error";
+  /**
+   * Elapsed time for end/error events.
+   */
   durationMs?: number;
+  /**
+   * Error captured for error events.
+   */
   error?: unknown;
+  /**
+   * Application context used for the run.
+   */
   ctx: Ctx;
 }
 
 /**
- * Options for createUseCase
+ * Options for `createUseCase(...)`.
  */
 export interface CreateUseCaseOptions<Ctx> {
   /**
@@ -599,6 +651,9 @@ export interface UseCaseBuilderRoot<Ctx> {
   ): UseCaseBuilder<Ctx, Name, "query", undefined, undefined, readonly []>;
 }
 
+/**
+ * Infer the application context type from a finalized use case.
+ */
 export type UseCaseContext<TUseCase> = TUseCase extends {
   run: (args: {
     ctx: infer Ctx;
@@ -608,6 +663,9 @@ export type UseCaseContext<TUseCase> = TUseCase extends {
   ? Ctx
   : never;
 
+/**
+ * Infer the public input type accepted by a finalized use case.
+ */
 export type UseCaseInput<TUseCase> = TUseCase extends {
   run: (args: {
     ctx: infer _Ctx;
@@ -617,6 +675,9 @@ export type UseCaseInput<TUseCase> = TUseCase extends {
   ? Input
   : never;
 
+/**
+ * Infer the public output type returned by a finalized use case.
+ */
 export type UseCaseOutput<TUseCase> = TUseCase extends {
   run: (args: {
     ctx: infer _Ctx;
@@ -628,6 +689,9 @@ export type UseCaseOutput<TUseCase> = TUseCase extends {
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Small test harness for running use cases with typed inputs.
+ */
 export interface UseCaseTester<Ctx> {
   /**
    * Create a fresh test context.
@@ -677,30 +741,29 @@ export function createUseCaseTester<Ctx>(
   };
 }
 
+/** Empty emits array used as default. */
+const EMPTY_EMITS = [] as const;
+
 /**
  * Create a use case builder with a specific context type.
  *
+ * Create this once in app code, usually in `lib/use-case.ts`, then import that
+ * configured builder from feature use-case modules.
+ *
  * @example
  * ```ts
- * import { createUseCase } from "@beignet/core/application";
- * import type { AppCtx } from "./ctx";
- *
- * export const useCase = createUseCase<AppCtx>();
+ * export const useCase = createUseCase<AppContext>();
  *
  * export const createTodo = useCase
  *   .command("todos.create")
  *   .input(CreateTodoInput)
  *   .output(CreateTodoOutput)
- *   .run(async ({ ctx, input }) => {
- *     const todo = await ctx.ports.db.todos.create(input);
- *     return { id: todo.id, title: todo.title };
- *   });
+ *   .run(async ({ ctx, input }) => ctx.ports.todos.create(input));
  * ```
+ *
+ * @param options - Optional instrumentation and validation configuration.
+ * @returns A root builder for command and query use cases.
  */
-
-/** Empty emits array used as default */
-const EMPTY_EMITS = [] as const;
-
 export function createUseCase<Ctx>(
   options?: CreateUseCaseOptions<Ctx>,
 ): UseCaseBuilderRoot<Ctx> {

package/src/client/client.ts

@@ -23,23 +23,38 @@ import type {
   InferSuccessResponse,
 } from "./types";
 
+/**
+ * Source category for a `ContractError`.
+ */
 export type ContractErrorSource = "http" | "client" | "network" | "contract";
 
+/**
+ * Narrow a contract error union by source.
+ */
 export type ContractErrorWithSource<
   TError,
   TSource extends ContractErrorSource,
 > = Extract<TError, { readonly source: TSource }>;
 
+/**
+ * Narrow a contract error union by HTTP status.
+ */
 export type ContractErrorWithStatus<TError, TStatus extends number> = Extract<
   TError,
   { readonly status: TStatus }
 >;
 
+/**
+ * Narrow a contract error union by Beignet error code.
+ */
 export type ContractErrorWithCode<TError, TCode extends string> = Extract<
   TError,
   { readonly code: TCode }
 >;
 
+/**
+ * Error for a non-2xx HTTP response.
+ */
 export type HttpContractError<
   TBody = unknown,
   TStatus extends number = number,
@@ -49,6 +64,9 @@ export type HttpContractError<
   readonly response: Response;
 };
 
+/**
+ * Error created by the client before a network request is made.
+ */
 export type ClientContractError = ContractError<
   undefined,
   undefined,
@@ -59,6 +77,9 @@ export type ClientContractError = ContractError<
   readonly response: undefined;
 };
 
+/**
+ * Error created when the network request itself fails.
+ */
 export type NetworkContractError = ContractError<
   undefined,
   undefined,
@@ -69,6 +90,9 @@ export type NetworkContractError = ContractError<
   readonly response: undefined;
 };
 
+/**
+ * Error created when a response violates the contract.
+ */
 export type ResponseContractError<
   TBody = unknown,
   TStatus extends number | undefined = number | undefined,
@@ -77,6 +101,9 @@ export type ResponseContractError<
   readonly status: TStatus;
 };
 
+/**
+ * Union of all Beignet client error variants.
+ */
 export type AnyContractError =
   | HttpContractError
   | ClientContractError
@@ -118,9 +145,15 @@ type EndpointCatalogContractError<TContract extends HttpContractConfig> =
       : never
     : never;
 
+/**
+ * Infer route-owned error catalog codes declared by a contract.
+ */
 export type InferEndpointErrorCode<TContract extends HttpContractConfig> =
   EndpointCatalogErrorDefinition<TContract>["code"];
 
+/**
+ * Infer the full typed error union for a contract endpoint.
+ */
 export type InferEndpointContractError<TContract extends HttpContractConfig> =
   | EndpointCatalogContractError<TContract>
   | {
@@ -138,18 +171,39 @@ export type InferEndpointContractError<TContract extends HttpContractConfig> =
     >;
 
 /**
- * HTTP client error with contract metadata
+ * Error thrown by Beignet contract clients.
+ *
+ * `source` distinguishes HTTP error responses, client-side request mistakes,
+ * network failures, and contract drift such as response validation failures.
  */
 export class ContractError<
   TBody = unknown,
   TStatus extends number | undefined = number | undefined,
   TSource extends ContractErrorSource = ContractErrorSource,
 > extends Error {
+  /**
+   * Error source category.
+   */
   readonly source: TSource;
+  /**
+   * HTTP status when a response was available.
+   */
   readonly status: TStatus;
+  /**
+   * Stable error code.
+   */
   readonly code?: string;
+  /**
+   * Parsed response body when available.
+   */
   readonly body?: TBody;
+  /**
+   * Structured error details when available.
+   */
   readonly details?: unknown;
+  /**
+   * Native fetch response when available.
+   */
   readonly response?: Response;
   override cause?: unknown;
 
@@ -175,7 +229,7 @@ export class ContractError<
   }
 
   /**
-   * Check if this error has a specific HTTP status code
+   * Check whether this error has a specific HTTP status code.
    */
   hasStatus<S extends number>(
     status: S,
@@ -184,7 +238,7 @@ export class ContractError<
   }
 
   /**
-   * Check if this error came from a specific source.
+   * Check whether this error came from a specific source.
    */
   hasSource<S extends ContractErrorSource>(
     source: S,
@@ -193,7 +247,7 @@ export class ContractError<
   }
 
   /**
-   * Check if this error has a specific error code
+   * Check whether this error has a specific error code.
    */
   hasCode<C extends string>(code: C): this is this & { code: C } {
     return this.code === code;
@@ -407,7 +461,7 @@ type PathParams = Record<string, PrimitiveParam>;
 type QueryParams = Record<string, QueryParamValue>;
 
 /**
- * Endpoint wrapper for a specific contract
+ * Typed client endpoint for one contract.
  */
 export class Endpoint<
   TContract extends HttpContractConfig,
@@ -418,6 +472,9 @@ export class Endpoint<
     private config: ClientConfig<TProvidedHeaders>,
   ) {}
 
+  /**
+   * Check whether an unknown error is a `ContractError` for this endpoint.
+   */
   isError(err: unknown): err is InferEndpointContractError<TContract>;
   isError<S extends InferEndpointErrorStatus<TContract>>(
     err: unknown,
@@ -497,7 +554,10 @@ export class Endpoint<
   }
 
   /**
-   * Call the endpoint with the given arguments
+   * Call the endpoint and return the parsed success body.
+   *
+   * Throws `ContractError` when the request fails or the response violates the
+   * contract.
    */
   async call(
     ...callArgs: CallArgs<TContract, TProvidedHeaders>
@@ -510,7 +570,8 @@ export class Endpoint<
   }
 
   /**
-   * Call the endpoint and return a typed result instead of throwing ContractError.
+   * Call the endpoint and return a typed result instead of throwing
+   * `ContractError`.
    */
   async safeCall(
     ...callArgs: CallArgs<TContract, TProvidedHeaders>
@@ -951,16 +1012,16 @@ export class Endpoint<
 }
 
 /**
- * Client for making contract-based requests
+ * Client for making contract-based requests.
  */
 export class Client<TProvidedHeaders extends string = never> {
   constructor(private config: ClientConfig<TProvidedHeaders>) {}
 
   /**
-   * Create an endpoint wrapper for a contract
+   * Create an endpoint wrapper for a contract.
    *
-   * Accepts either an HttpContractConfig object or a ContractBuilder
-   * (which has a .config property that returns the config)
+   * Accepts either a plain `HttpContractConfig` or a builder with a `.config`
+   * property.
    */
   endpoint<TContractLike extends ContractLike>(
     contract: TContractLike,
@@ -971,7 +1032,7 @@ export class Client<TProvidedHeaders extends string = never> {
 }
 
 /**
- * Create a configured client
+ * Create a configured Beignet client.
  */
 export function createClient<const TProvidedHeaders extends string = never>(
   config: ClientConfig<TProvidedHeaders> = {},

package/src/client/index.ts

@@ -4,7 +4,13 @@
  * Base HTTP client for making contract-based requests
  */
 
+/**
+ * Schema validation error re-exported for client users.
+ */
 export { SchemaValidationError } from "../errors";
+/**
+ * Contract client error types.
+ */
 export type {
   AnyContractError,
   ClientContractError,
@@ -18,6 +24,9 @@ export type {
   NetworkContractError,
   ResponseContractError,
 } from "./client";
+/**
+ * Contract client runtime helpers.
+ */
 export {
   Client,
   ContractError,
@@ -25,6 +34,9 @@ export {
   Endpoint,
   isContractError,
 } from "./client";
+/**
+ * Contract client inference and call types.
+ */
 export type {
   CallArgs,
   ClientConfig,

package/src/client/types.ts

@@ -10,12 +10,24 @@ import type {
 import type { ErrorResponseBody } from "../errors";
 
 /**
- * Client configuration
+ * Configuration for a Beignet contract client.
  */
 export type ClientConfig<TProvidedHeaders extends string = never> = {
+  /**
+   * Base URL prepended to all endpoint paths.
+   */
   baseUrl?: string;
+  /**
+   * Static or async headers applied to every request.
+   */
   headers?: () => Promise<Record<string, string>> | Record<string, string>;
+  /**
+   * Header keys supplied by global `headers`, making them optional per call.
+   */
   providedHeaders?: readonly TProvidedHeaders[];
+  /**
+   * Fetch implementation. Defaults to global `fetch`.
+   */
   fetch?: typeof fetch;
   /** Enable client-side input validation for path, query, and body. Default: false. */
   validate?: boolean;
@@ -56,7 +68,7 @@ type InferPathParamsFromTemplate<TPath extends string> = [
   : { [K in PathParamNames<TPath>]: PathParamPrimitive };
 
 /**
- * Infer path params from contract
+ * Infer path params accepted by a client call from a contract.
  */
 export type InferPathParams<TContract extends HttpContractConfig> =
   TContract["pathParams"] extends StandardSchemaV1
@@ -64,13 +76,16 @@ export type InferPathParams<TContract extends HttpContractConfig> =
     : InferPathParamsFromTemplate<TContract["path"]>;
 
 /**
- * Infer query params from contract
+ * Infer query params accepted by a client call from a contract.
  */
 export type InferQuery<TContract extends HttpContractConfig> =
   TContract["query"] extends StandardSchemaV1
     ? InferInput<TContract["query"]>
     : undefined;
 
+/**
+ * Infer request headers accepted by a client call from a contract.
+ */
 export type InferHeaders<TContract extends HttpContractConfig> =
   InferHeaderSchemaInput<
     Exclude<TContract["headers"], undefined>
@@ -79,7 +94,7 @@ export type InferHeaders<TContract extends HttpContractConfig> =
     : InferHeaderSchemaInput<Exclude<TContract["headers"], undefined>>;
 
 /**
- * Infer body from contract
+ * Infer JSON request body accepted by a client call from a contract.
  */
 export type InferBody<TContract extends HttpContractConfig> =
   TContract["method"] extends BodyHttpMethod
@@ -135,7 +150,9 @@ type InferResponseType<T> = T extends null
     : unknown;
 
 /**
- * Infer success response from contract (union of all 2xx response types)
+ * Infer success response body from a contract.
+ *
+ * This is the union of all declared 2xx response schemas.
  */
 export type InferSuccessResponse<TContract extends HttpContractConfig> =
   TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
@@ -147,7 +164,9 @@ export type InferSuccessResponse<TContract extends HttpContractConfig> =
     : unknown;
 
 /**
- * Infer error response from contract (union of all non-2xx response types)
+ * Infer declared route-owned error response bodies from a contract.
+ *
+ * This is the union of all declared non-2xx response schemas.
  */
 export type InferErrorResponse<TContract extends HttpContractConfig> =
   TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
@@ -201,27 +220,57 @@ export type InferEndpointErrorResponse<TContract extends HttpContractConfig> =
   | string
   | undefined;
 
+/**
+ * Successful endpoint result returned by `safeCall(...)`.
+ */
 export type EndpointSuccessResult<TContract extends HttpContractConfig> = {
+  /**
+   * Success discriminator.
+   */
   ok: true;
+  /**
+   * HTTP status code.
+   */
   status: number;
+  /**
+   * Parsed response body.
+   */
   data: InferSuccessResponse<TContract>;
+  /**
+   * Native fetch response.
+   */
   response: Response;
 };
 
+/**
+ * Failed endpoint result returned by `safeCall(...)`.
+ */
 export type EndpointErrorResult<TError> = {
+  /**
+   * Failure discriminator.
+   */
   ok: false;
+  /**
+   * HTTP status code when a response was available.
+   */
   status?: number;
+  /**
+   * Contract client error.
+   */
   error: TError;
+  /**
+   * Native fetch response when one was available.
+   */
   response?: Response;
 };
 
+/**
+ * Result union returned by `safeCall(...)`.
+ */
 export type EndpointResult<TContract extends HttpContractConfig, TError> =
   | EndpointSuccessResult<TContract>
   | EndpointErrorResult<TError>;
 
-/**
- * Call arguments for an endpoint
- */
 type RequestArg<
   Name extends "path" | "query" | "body",
   Value,
@@ -275,6 +324,9 @@ type HeadersArgs<
       ? { headers?: HeaderInput<TContract, TProvidedHeaders> }
       : { headers: HeaderInput<TContract, TProvidedHeaders> };
 
+/**
+ * Arguments accepted by an endpoint call for a specific contract.
+ */
 export type EndpointCallArgs<
   TContract extends HttpContractConfig,
   TProvidedHeaders extends string = never,
@@ -289,6 +341,9 @@ export type EndpointCallArgs<
      * and is not validated or JSON-serialized.
      */
     rawBody?: TContract["method"] extends BodyHttpMethod ? BodyInit : never;
+    /**
+     * Abort signal passed to fetch.
+     */
     signal?: AbortSignal;
   } & HeadersArgs<TContract, TProvidedHeaders>;
 
@@ -296,6 +351,12 @@ type HasRequiredKeys<T> = {
   [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
 }[keyof T];
 
+/**
+ * Tuple type used by endpoint calls.
+ *
+ * The args object is optional only when the contract has no required path,
+ * query, body, or header input.
+ */
 export type CallArgs<
   TContract extends HttpContractConfig,
   TProvidedHeaders extends string = never,