@beignet/core 0.0.1 → 0.0.2

package/src/schedules/index.ts

@@ -1,155 +1,381 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
+/**
+ * Any Standard Schema compatible validator.
+ */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
 export type InferSchemaOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
+/**
+ * Date input accepted by schedule runners.
+ */
 export type ScheduleDateInput = Date | string | number;
 
+/**
+ * Metadata for one schedule run.
+ */
 export interface ScheduleRunContext {
+  /**
+   * Optional provider run ID.
+   */
   readonly id?: string;
+  /**
+   * Time the provider planned the run.
+   */
   readonly scheduledAt?: Date;
+  /**
+   * Time the runner triggered this execution.
+   */
   readonly triggeredAt: Date;
+  /**
+   * Optional provider or app source label.
+   */
   readonly source?: string;
 }
 
+/**
+ * Minimal schedule definition shape accepted by schedule helpers.
+ */
 export interface SchedulePayloadDef<
   Name extends string = string,
   Payload extends StandardSchema = StandardSchema,
 > {
+  /**
+   * Stable schedule name.
+   */
   readonly name: Name;
+  /**
+   * Standard Schema payload validator.
+   */
   readonly payload: Payload;
 }
 
+/**
+ * Schedule definition created by `defineSchedule(...)`.
+ */
 export interface ScheduleDef<
   Name extends string = string,
   Payload extends StandardSchema = StandardSchema,
   Ctx = unknown,
 > extends SchedulePayloadDef<Name, Payload> {
+  /**
+   * Discriminator for schedule definitions.
+   */
   readonly kind: "schedule";
+  /**
+   * Cron expression consumed by schedule providers.
+   */
   readonly cron: string;
+  /**
+   * Optional IANA timezone consumed by schedule providers.
+   */
   readonly timezone?: string;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   readonly description?: string;
+  /**
+   * Build a payload when the provider does not supply one.
+   */
   createPayload?(
     args: ScheduleCreatePayloadArgs<ScheduleDef<Name, Payload, Ctx>>,
   ): MaybePromise<InferSchemaOutput<Payload>>;
+  /**
+   * Handle a parsed schedule payload.
+   */
   handle(
     args: ScheduleHandleArgs<ScheduleDef<Name, Payload, Ctx>, Ctx>,
   ): MaybePromise<void>;
 }
 
+/**
+ * Infer the parsed payload type for a schedule definition.
+ */
 export type InferSchedulePayload<S extends SchedulePayloadDef> =
   S["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
 
+/**
+ * Arguments passed to a schedule `createPayload` callback.
+ */
 export interface ScheduleCreatePayloadArgs<S extends SchedulePayloadDef> {
+  /**
+   * Schedule definition being run.
+   */
   schedule: S;
+  /**
+   * Run metadata.
+   */
   run: ScheduleRunContext;
 }
 
+/**
+ * Arguments passed to a schedule handler.
+ */
 export interface ScheduleHandleArgs<S extends ScheduleDef, Ctx> {
+  /**
+   * Schedule definition being handled.
+   */
   schedule: S;
+  /**
+   * Parsed schedule payload.
+   */
   payload: InferSchedulePayload<S>;
+  /**
+   * Handler context.
+   */
   ctx: Ctx;
+  /**
+   * Run metadata.
+   */
   run: ScheduleRunContext;
 }
 
+/**
+ * Options for `defineSchedule(...)`.
+ */
 export interface DefineScheduleOptions<
   Name extends string,
   Payload extends StandardSchema,
   Ctx,
 > {
+  /**
+   * Cron expression consumed by schedule providers.
+   */
   cron: string;
+  /**
+   * Optional IANA timezone consumed by schedule providers.
+   */
   timezone?: string;
+  /**
+   * Standard Schema payload validator.
+   */
   payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   description?: string;
+  /**
+   * Build a payload when the provider does not supply one.
+   */
   createPayload?(
     args: ScheduleCreatePayloadArgs<ScheduleDef<Name, Payload, Ctx>>,
   ): MaybePromise<InferSchemaOutput<Payload>>;
+  /**
+   * Handle a parsed schedule payload.
+   */
   handle(
     args: ScheduleHandleArgs<ScheduleDef<Name, Payload, Ctx>, Ctx>,
   ): MaybePromise<void>;
 }
 
+/**
+ * Options for one manual schedule run.
+ */
 export interface ScheduleRunOptions<Payload = unknown> {
+  /**
+   * Payload supplied by the provider or manual runner.
+   */
   payload?: Payload;
+  /**
+   * Optional provider run ID.
+   */
   id?: string;
+  /**
+   * Time the provider planned the run.
+   */
   scheduledAt?: ScheduleDateInput;
+  /**
+   * Time the runner triggered the execution.
+   */
   triggeredAt?: ScheduleDateInput;
+  /**
+   * Optional provider or app source label.
+   */
   source?: string;
 }
 
+/**
+ * Arguments for `runSchedule(...)`.
+ */
 export type ScheduleRunArgs<
   Ctx,
   Payload = unknown,
 > = ScheduleRunOptions<Payload> & {
+  /**
+   * Handler context.
+   */
   ctx: Ctx;
 };
 
+/**
+ * Arguments passed to schedule lifecycle hooks.
+ */
 export interface ScheduleLifecycleArgs<S extends ScheduleDef = ScheduleDef> {
+  /**
+   * Schedule definition being run.
+   */
   schedule: S;
+  /**
+   * Parsed schedule payload.
+   */
   payload: InferSchedulePayload<S>;
+  /**
+   * Run metadata.
+   */
   run: ScheduleRunContext;
 }
 
+/**
+ * Arguments passed to a schedule error hook.
+ */
 export interface ScheduleErrorArgs<S extends ScheduleDef = ScheduleDef> {
+  /**
+   * Schedule definition being run.
+   */
   schedule: S;
+  /**
+   * Parsed payload when validation or payload creation completed.
+   */
   payload?: InferSchedulePayload<S>;
+  /**
+   * Run metadata.
+   */
   run: ScheduleRunContext;
+  /**
+   * Error thrown by payload creation, validation, or the handler.
+   */
   error: unknown;
 }
 
+/**
+ * Schedule lifecycle hook names.
+ */
 export type ScheduleHookName = "start" | "success" | "error";
 
+/**
+ * Arguments passed when a schedule lifecycle hook itself fails.
+ */
 export interface ScheduleHookErrorArgs<S extends ScheduleDef = ScheduleDef> {
+  /**
+   * Schedule definition being run.
+   */
   schedule: S;
+  /**
+   * Parsed payload when available.
+   */
   payload?: InferSchedulePayload<S>;
+  /**
+   * Run metadata.
+   */
   run: ScheduleRunContext;
+  /**
+   * Lifecycle hook that failed.
+   */
   hook: ScheduleHookName;
+  /**
+   * Hook error.
+   */
   error: unknown;
+  /**
+   * Original schedule error when the failing hook is `onError`.
+   */
   scheduleError?: unknown;
 }
 
+/**
+ * Options for the inline schedule runner.
+ */
 export interface InlineScheduleRunnerOptions<Ctx> {
+  /**
+   * Static schedule context or factory evaluated for each run.
+   */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Clock used when run timestamps are not provided.
+   */
   now?: () => Date;
+  /**
+   * Called after payload validation and before the schedule handler.
+   */
   onStart?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
     args: ScheduleLifecycleArgs<S>,
   ): MaybePromise<void>;
+  /**
+   * Called after the schedule handler completes.
+   */
   onSuccess?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
     args: ScheduleLifecycleArgs<S>,
   ): MaybePromise<void>;
+  /**
+   * Called when payload creation, validation, or the handler fails.
+   */
   onError?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
     args: ScheduleErrorArgs<S>,
   ): MaybePromise<void>;
+  /**
+   * Called when a lifecycle hook throws.
+   */
   onHookError?<S extends ScheduleDef<string, StandardSchema, Ctx>>(
     args: ScheduleHookErrorArgs<S>,
   ): MaybePromise<void>;
 }
 
+/**
+ * Port shape for running schedules.
+ */
 export interface ScheduleRunnerPort<Ctx = unknown> {
+  /**
+   * Run a schedule with optional provider metadata and payload.
+   */
   run<S extends ScheduleDef<string, StandardSchema, Ctx>>(
     schedule: S,
     options?: ScheduleRunOptions<InferSchedulePayload<S>>,
   ): Promise<void>;
 }
 
+/**
+ * Local/test schedule runner that executes handlers inline.
+ */
 export interface InlineScheduleRunner<Ctx = unknown>
   extends ScheduleRunnerPort<Ctx> {}
 
+/**
+ * Context-bound schedule helper factory.
+ */
 export interface ScheduleHandlers<Ctx> {
+  /**
+   * Define a schedule with the bound context type.
+   */
   defineSchedule<Name extends string, Payload extends StandardSchema>(
     name: Name,
     options: DefineScheduleOptions<Name, Payload, Ctx>,
   ): ScheduleDef<Name, Payload, Ctx>;
 
+  /**
+   * Create an inline schedule runner with the bound context type.
+   */
   createInlineScheduleRunner(
     options?: InlineScheduleRunnerOptions<Ctx>,
   ): InlineScheduleRunner<Ctx>;
 }
 
+/**
+ * Error thrown when schedule payload validation fails.
+ */
 export class ScheduleValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
   readonly issues: readonly StandardSchemaV1.Issue[];
 
   constructor(args: {
@@ -164,6 +390,9 @@ export class ScheduleValidationError extends Error {
   }
 }
 
+/**
+ * Error thrown when schedule run metadata cannot be normalized.
+ */
 export class ScheduleRunContextError extends Error {
   constructor(message: string) {
     super(message);
@@ -327,6 +556,12 @@ async function runErrorHook<
   }
 }
 
+/**
+ * Define a typed schedule.
+ *
+ * Cron and timezone are metadata for schedule providers. The inline runner only
+ * runs schedules when its `run(...)` method is called.
+ */
 export function defineSchedule<
   Name extends string,
   Payload extends StandardSchema,
@@ -349,6 +584,9 @@ export function defineSchedule<
   };
 }
 
+/**
+ * Validate and parse a schedule payload with the schedule's Standard Schema.
+ */
 export async function parseSchedulePayload<S extends SchedulePayloadDef>(
   schedule: S,
   payload: unknown,
@@ -358,6 +596,9 @@ export async function parseSchedulePayload<S extends SchedulePayloadDef>(
   })) as InferSchedulePayload<S>;
 }
 
+/**
+ * Run one schedule directly with an explicit context.
+ */
 export async function runSchedule<
   Ctx,
   S extends ScheduleDef<string, StandardSchema, Ctx>,
@@ -376,6 +617,9 @@ export async function runSchedule<
   });
 }
 
+/**
+ * Create a local/test schedule runner that executes handlers inline.
+ */
 export function createInlineScheduleRunner<Ctx>(
   options: InlineScheduleRunnerOptions<Ctx> = {},
 ): InlineScheduleRunner<Ctx> {
@@ -424,6 +668,9 @@ export function createInlineScheduleRunner<Ctx>(
   };
 }
 
+/**
+ * Create schedule helper methods bound to an application context type.
+ */
 export function createScheduleHandlers<Ctx>(): ScheduleHandlers<Ctx> {
   return {
     defineSchedule<Name extends string, Payload extends StandardSchema>(

package/src/server/health.ts

@@ -7,15 +7,21 @@ import type { AnyPorts } from "../ports";
 import type { HttpRequestLike, HttpResponseLike } from "./types";
 
 /**
- * Health check result
+ * Health check result returned by health handlers.
  */
 export interface HealthCheckResult {
+  /**
+   * Whether the app is healthy.
+   */
   ok: boolean;
+  /**
+   * Optional per-dependency health details.
+   */
   details?: Record<string, { ok: boolean; message?: string }>;
 }
 
 /**
- * Health check configuration
+ * Health check configuration.
  */
 export interface HealthConfig<Ports> {
   /** Enable health endpoint (default: false) */
@@ -31,13 +37,16 @@ export interface HealthConfig<Ports> {
 }
 
 /**
- * Application environment type
+ * Application environment.
  */
 export type AppEnvironment = "development" | "production" | "test";
 
 /**
- * Create a health check handler
- * Returns a function that can be called with an HttpRequestLike to get an HttpResponseLike
+ * Create a framework-neutral health check handler.
+ *
+ * The returned handler reports 200 when healthy and 503 when unhealthy. Thrown
+ * health check errors include details in development/test and use a generic
+ * message in production.
  */
 export function createHealthHandler<Ports extends AnyPorts>(
   ports: Ports,

package/src/server/hooks/auth.ts

@@ -7,15 +7,32 @@ import type { HttpRequestLike, HttpResponse, ServerHook } from "../types";
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Authentication mode for one matched contract.
+ */
 export type AuthHookMode = "public" | "optional" | "required";
+
+/**
+ * Input accepted when resolving auth mode from contract metadata or options.
+ *
+ * `true` maps to `"required"`; `false`, `null`, and `undefined` map to
+ * `"public"`.
+ */
 export type AuthHookModeInput = AuthHookMode | boolean | null | undefined;
 
+/**
+ * Minimal context shape required when `createAuthHooks(...)` reads
+ * `ctx.ports.auth`.
+ */
 export type CtxWithAuthPort = {
   ports: {
     auth: AuthPort;
   };
 };
 
+/**
+ * Arguments passed to auth hook callbacks.
+ */
 export type AuthHookArgs<Ctx> = {
   req: HttpRequestLike;
   ctx: Ctx;
@@ -28,20 +45,48 @@ export type AuthHookArgs<Ctx> = {
   body: unknown;
 };
 
+/**
+ * Arguments passed to the auth `assign` callback.
+ */
 export type AuthHookAssignArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
   session: Session | null;
 };
 
+/**
+ * Arguments passed to the auth `unauthorized` callback.
+ */
 export type AuthHookUnauthorizedArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
   session: Session | null;
 };
 
+/**
+ * Options for `createAuthHooks(...)`.
+ */
 export type AuthHooksOptions<Ctx, Session> = {
+  /**
+   * Hook name used in diagnostics.
+   */
   name?: string;
+  /**
+   * Resolve whether the current contract is public, optional-auth, or required-auth.
+   */
   mode?: (args: AuthHookArgs<Ctx>) => MaybePromise<AuthHookModeInput>;
+  /**
+   * Custom session lookup. Required when context does not expose
+   * `ctx.ports.auth`.
+   */
   getSession?: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
+  /**
+   * Decide whether a resolved session counts as authenticated.
+   */
   isAuthenticated?: (session: Session | null) => boolean;
+  /**
+   * Return an updated context with auth/session fields attached.
+   */
   assign?: (args: AuthHookAssignArgs<Ctx, Session>) => MaybePromise<Ctx>;
+  /**
+   * Return a custom unauthorized response for required-auth routes.
+   */
   unauthorized?: (
     args: AuthHookUnauthorizedArgs<Ctx, Session>,
   ) => MaybePromise<HttpResponse>;
@@ -79,6 +124,19 @@ function defaultIsAuthenticated<Session>(session: Session | null): boolean {
   return session !== null;
 }
 
+/**
+ * Create metadata-driven authentication hooks.
+ *
+ * By default the hook reads `contract.metadata.auth`: `"required"` or `true`
+ * requires an authenticated session, `"optional"` attaches a session when one
+ * exists, and missing/false metadata treats the route as public. The hook
+ * identifies a user; business authorization still belongs in policies or use
+ * cases.
+ *
+ * @param options - Optional auth mode, session lookup, context assignment, and
+ * unauthorized response customization.
+ * @returns A server hook that runs before route handlers.
+ */
 export function createAuthHooks<Ctx extends CtxWithAuthPort>(
   options?: AuthHooksOptions<Ctx, InferAuthSession<Ctx["ports"]["auth"]>>,
 ): ServerHook<Ctx, Ctx["ports"]>;

package/src/server/hooks/cors.ts

@@ -4,10 +4,25 @@
 
 import type { HttpRequestLike, ServerHook } from "../types";
 
+/**
+ * CORS configuration for `createCorsHooks(...)`.
+ */
 export interface CorsConfig {
+  /**
+   * Allowed origins. Use `"*"` to allow any origin.
+   */
   origins?: string[] | "*";
+  /**
+   * Allowed HTTP methods.
+   */
   methods?: string[];
+  /**
+   * Allowed request headers.
+   */
   headers?: string[];
+  /**
+   * Whether credentialed requests are allowed.
+   */
   credentials?: boolean;
 }
 
@@ -28,6 +43,12 @@ function appendVaryOrigin(headers: Record<string, string>): void {
   headers[varyKey] = current ? `${current}, Origin` : "Origin";
 }
 
+/**
+ * Apply CORS response headers to a mutable header record.
+ *
+ * When credentials are enabled with wildcard origins, the request origin is
+ * reflected and `Vary: Origin` is appended.
+ */
 export function applyCorsHeaders(
   headers: Record<string, string>,
   req: HttpRequestLike,
@@ -62,6 +83,12 @@ export function applyCorsHeaders(
   }
 }
 
+/**
+ * Create CORS hooks for preflight and regular responses.
+ *
+ * `OPTIONS` requests short-circuit with a 204 response. All other responses are
+ * decorated in `beforeSend`.
+ */
 export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
   return {
     name: "cors",

package/src/server/hooks/errors.ts

@@ -7,30 +7,39 @@ import type { AppEnvironment } from "../health";
 import { getRequestIdFromContext } from "./utils";
 
 /**
- * Re-export AppEnvironment for convenience
+ * Re-export `AppEnvironment` for convenience.
  */
 export type { AppEnvironment } from "../health";
 
 /**
- * Error mapping result
+ * Framework-neutral response produced by an error mapper.
  */
 export interface ErrorMappingResult {
+  /**
+   * HTTP status code.
+   */
   status: number;
+  /**
+   * Response body.
+   */
   body: unknown;
+  /**
+   * Response headers.
+   */
   headers?: Record<string, string>;
 }
 
 /**
- * Error mapping configuration
+ * Error mapping configuration.
  */
 export interface ErrorMappingConfig<Ctx> {
-  /** Custom error mapper function */
+  /** Custom error mapper function. */
   mapErrorToResponse?: (err: unknown, ctx: Ctx) => ErrorMappingResult;
 
-  /** Include stack traces in error responses (default: true in dev/test, false in production) */
+  /** Include stack traces in error responses. Defaults to true in dev/test. */
   includeStackInResponse?: boolean;
 
-  /** Application environment */
+  /** Application environment. */
   env?: AppEnvironment;
 }
 

package/src/server/hooks/index.ts

@@ -36,6 +36,9 @@ export {
   type RateLimitOptions,
 } from "./rate-limit";
 
+/**
+ * Flatten hook arrays into a single hook list.
+ */
 export function composeHooks<Ctx, Ports extends AnyPorts = AnyPorts>(
   ...hooks: (ServerHook<Ctx, Ports> | readonly ServerHook<Ctx, Ports>[])[]
 ): ServerHook<Ctx, Ports>[] {