@beignet/core 0.0.1 → 0.0.2

package/dist/server/http.d.ts

@@ -1,8 +1,23 @@
 import type { HttpContractConfig, InferHeaderSchemaOutput, InferOutput, StandardSchema } from "../contracts";
 import type { AnyPorts } from "../ports";
+/**
+ * Framework-neutral request shape consumed by Beignet server adapters.
+ *
+ * Platform adapters should convert their native request into this shape before
+ * passing it to `server.api(...)` or a single route handler.
+ */
 export interface HttpRequestLike {
+    /**
+     * HTTP method as received from the platform.
+     */
     method: string;
+    /**
+     * Absolute request URL.
+     */
     url: string;
+    /**
+     * Request headers.
+     */
     headers: Headers;
     /**
      * The platform request when an adapter has one available.
@@ -11,45 +26,138 @@ export interface HttpRequestLike {
      * framework-agnostic methods below when possible.
      */
     raw?: Request;
+    /**
+     * Parse the request body as JSON.
+     */
     json(): Promise<unknown>;
+    /**
+     * Parse the request body as text.
+     */
     text(): Promise<string>;
+    /**
+     * Parse the request body as an array buffer when the platform supports it.
+     */
     arrayBuffer?(): Promise<ArrayBuffer>;
+    /**
+     * Parse the request body as a Blob when the platform supports it.
+     */
     blob?(): Promise<Blob>;
+    /**
+     * Parse the request body as form data when the platform supports it.
+     */
     formData?(): Promise<FormData>;
+    /**
+     * Clone the request when the platform supports replaying the body.
+     */
     clone?(): HttpRequestLike;
 }
+/**
+ * Framework-neutral response object returned by route handlers and hooks.
+ */
 export interface HttpResponseLike {
+    /**
+     * HTTP status code.
+     */
     status: number;
+    /**
+     * Response headers.
+     */
     headers?: Record<string, string>;
+    /**
+     * JSON-serializable body or an adapter-specific body value.
+     */
     body?: unknown;
 }
+/**
+ * Response accepted by Beignet handlers.
+ *
+ * Use `HttpResponseLike` for framework-neutral responses. Return a native
+ * `Response` only when the current adapter can pass it through unchanged.
+ */
 export type HttpResponse = HttpResponseLike | Response;
 type InferSchemaOrFallback<T extends StandardSchema | null, Fallback> = T extends StandardSchema ? InferOutput<T> : Fallback;
+/**
+ * Infer the handler path parameter type for a contract.
+ */
 export type InferPath<C extends HttpContractConfig> = InferSchemaOrFallback<C["pathParams"], Record<string, string>>;
+/**
+ * Infer the handler query parameter type for a contract.
+ */
 export type InferQuery<C extends HttpContractConfig> = InferSchemaOrFallback<C["query"], Record<string, string | string[]>>;
+/**
+ * Infer the handler request body type for a contract.
+ */
 export type InferBody<C extends HttpContractConfig> = InferSchemaOrFallback<C["body"], unknown>;
+/**
+ * Infer the merged request header type for a contract.
+ */
 export type InferHeaders<C extends HttpContractConfig> = InferHeaderSchemaOutput<Exclude<C["headers"], undefined>> extends undefined ? Record<string, string> : InferHeaderSchemaOutput<Exclude<C["headers"], undefined>>;
+/**
+ * Arguments passed to a route handler after request parsing and validation.
+ */
 export interface HandlerArgs<Ctx, C extends HttpContractConfig> {
+    /**
+     * Framework-neutral request.
+     */
     req: HttpRequestLike;
+    /**
+     * Application context returned by `createContext`.
+     */
     ctx: Ctx;
+    /**
+     * Matched contract config.
+     */
     contract: C;
+    /**
+     * Parsed path parameters.
+     */
     path: InferPath<C>;
+    /**
+     * Parsed query parameters.
+     */
     query: InferQuery<C>;
+    /**
+     * Parsed request headers.
+     */
     headers: InferHeaders<C>;
+    /**
+     * Parsed request body.
+     */
     body: InferBody<C>;
 }
+/**
+ * Route handler function for a contract.
+ */
 export type Handler<Ctx, C extends HttpContractConfig> = (args: HandlerArgs<Ctx, C>) => Promise<HttpResponse> | HttpResponse;
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Hook that runs after a route is matched but before request parsing and
+ * context creation.
+ *
+ * Returning a response short-circuits the rest of the request pipeline.
+ */
 export type OnRequestHook<Ports extends AnyPorts = AnyPorts, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
     ports: Ports;
     contract: C;
     params: Record<string, string>;
 }) => MaybePromise<HttpResponse | undefined>;
+/**
+ * Result from a `beforeHandle` hook.
+ *
+ * Returning a plain response short-circuits the handler. Returning an object can
+ * replace the context, short-circuit with a response, or do both.
+ */
 export type BeforeHandleResult<Ctx> = undefined | HttpResponse | {
     ctx?: Ctx;
     response?: HttpResponse;
 };
+/**
+ * Hook that runs after request parsing/context creation and before the handler.
+ */
 export type BeforeHandleHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
     ctx: Ctx;
@@ -59,6 +167,12 @@ export type BeforeHandleHook<Ctx, C extends HttpContractConfig = HttpContractCon
     headers: InferHeaders<C>;
     body: InferBody<C>;
 }) => MaybePromise<BeforeHandleResult<Ctx>>;
+/**
+ * Hook that runs before a framework-neutral response is returned.
+ *
+ * Return a response to replace or decorate the outgoing response. Hooks run in
+ * declaration order.
+ */
 export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -70,6 +184,12 @@ export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfi
     response: HttpResponseLike;
     error?: unknown;
 }) => MaybePromise<HttpResponseLike | undefined>;
+/**
+ * Hook that runs after the response has been prepared.
+ *
+ * This is for logging and observability. Errors thrown by `afterSend` hooks are
+ * ignored by the server pipeline.
+ */
 export type AfterSendHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -82,6 +202,9 @@ export type AfterSendHook<Ctx, C extends HttpContractConfig = HttpContractConfig
     error?: unknown;
     durationMs: number;
 }) => MaybePromise<void>;
+/**
+ * Hook notified when the framework catches an error while handling a request.
+ */
 export type ServerCaughtErrorHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     err: unknown;
     req: HttpRequestLike;
@@ -92,6 +215,12 @@ export type ServerCaughtErrorHook<Ctx, C extends HttpContractConfig = HttpContra
     headers?: InferHeaders<C>;
     body?: InferBody<C>;
 }) => MaybePromise<void>;
+/**
+ * Hook that may map an unexpected error to a custom response.
+ *
+ * Return `undefined` to let the server's default unhandled-error mapper create
+ * the response.
+ */
 export type ServerUnhandledErrorMapper<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     err: unknown;
     req: HttpRequestLike;
@@ -102,18 +231,59 @@ export type ServerUnhandledErrorMapper<Ctx, C extends HttpContractConfig = HttpC
     headers?: InferHeaders<C>;
     body?: InferBody<C>;
 }) => MaybePromise<HttpResponse | undefined>;
+/**
+ * Server lifecycle hook collection.
+ *
+ * Hooks run in the order they are registered. `onRequest` can short-circuit
+ * before context creation; `beforeHandle` can replace context or short-circuit;
+ * `beforeSend` can replace the outgoing response; `afterSend` observes the
+ * final response.
+ */
 export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
+    /**
+     * Optional name used in diagnostics and devtools.
+     */
     name?: string;
+    /**
+     * Runs after route matching and before body/query/header parsing.
+     */
     onRequest?: OnRequestHook<Ports>;
+    /**
+     * Runs after request parsing and context creation.
+     */
     beforeHandle?: BeforeHandleHook<Ctx>;
+    /**
+     * Runs before a framework-neutral response is returned.
+     */
     beforeSend?: BeforeSendHook<Ctx>;
+    /**
+     * Observes the final response after send preparation.
+     */
     afterSend?: AfterSendHook<Ctx>;
+    /**
+     * Observes framework-caught errors.
+     */
     onCaughtError?: ServerCaughtErrorHook<Ctx>;
+    /**
+     * Maps unexpected errors to responses.
+     */
     mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
 }
+/**
+ * Compiled route entry used by server internals and adapter helpers.
+ */
 export type ResolvedRoute<_Ctx, C extends HttpContractConfig> = {
+    /**
+     * Contract config for the route.
+     */
     contract: C;
+    /**
+     * Handler that receives the raw request and optional path params.
+     */
     handler: (req: HttpRequestLike, params?: Record<string, string>) => Promise<HttpResponse>;
+    /**
+     * Test whether the route matches an incoming method and pathname.
+     */
     match: (method: string, pathname: string) => {
         matched: true;
     } | {

package/dist/server/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -4,16 +4,34 @@
  * Framework-agnostic HTTP server runtime for Beignet.
  * Shared by Beignet server adapters.
  */
+/**
+ * Contract and schema types re-exported for server users.
+ */
 export type { HttpContractConfig, InferOutput, StandardSchema, StandardSchemaV1, } from "../contracts";
+/**
+ * Application error base class re-exported for server users.
+ */
 export { AppError } from "../errors";
+/**
+ * Any-ports helper type re-exported for server users.
+ */
 export type { AnyPorts } from "../ports";
+/**
+ * Provider type re-exported for server users.
+ */
 export type { ServiceProvider } from "../providers";
 export * from "./health";
 export * from "./hooks";
 export * from "./http";
 export * from "./openapi";
 export * from "./providers";
+/**
+ * Server configuration and route types.
+ */
 export type { CreateServerOptions, RouteDef, RouteGroup, ServerInstance, } from "./server";
+/**
+ * Server runtime helpers.
+ */
 export { contractsFromRoutes, createServer, defineRouteGroup, defineRoutes, } from "./server";
 export * from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC;;GAEG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B;;GAEG;AACH,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,UAAU,CAAC;AAClB;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}

package/dist/server/index.js

@@ -4,12 +4,18 @@
  * Framework-agnostic HTTP server runtime for Beignet.
  * Shared by Beignet server adapters.
  */
+/**
+ * Application error base class re-exported for server users.
+ */
 export { AppError } from "../errors";
 export * from "./health";
 export * from "./hooks";
 export * from "./http";
 export * from "./openapi";
 export * from "./providers";
+/**
+ * Server runtime helpers.
+ */
 export { contractsFromRoutes, createServer, defineRouteGroup, defineRoutes, } from "./server";
 export * from "./types";
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAO5B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAU5B;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,cAAc,SAAS,CAAC"}

package/dist/server/openapi.d.ts

@@ -6,7 +6,7 @@ import type { HttpContractConfig } from "../contracts";
 import type { AppEnvironment } from "./health";
 import type { HttpRequestLike, HttpResponseLike } from "./types";
 /**
- * OpenAPI configuration
+ * OpenAPI route handler configuration.
  */
 export interface OpenAPIConfig {
     /** Enable OpenAPI endpoint (default: false) */
@@ -25,8 +25,10 @@ export interface OpenAPIConfig {
     description?: string;
 }
 /**
- * Create an OpenAPI handler
- * Returns a function that can be called with an HttpRequestLike to get an HttpResponseLike
+ * Create a framework-neutral OpenAPI JSON handler.
+ *
+ * The OpenAPI document is generated lazily on the first request and then cached
+ * for the lifetime of the handler.
  */
 export declare function createOpenAPIHandler(contracts: readonly HttpContractConfig[], openapiConfig: OpenAPIConfig | undefined, _env: AppEnvironment): (req: HttpRequestLike) => Promise<HttpResponseLike>;
 //# sourceMappingURL=openapi.d.ts.map

package/dist/server/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,aAAa,EAAE,aAAa,GAAG,SAAS,EACxC,IAAI,EAAE,cAAc,GACnB,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAkCrD"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,aAAa,EAAE,aAAa,GAAG,SAAS,EACxC,IAAI,EAAE,cAAc,GACnB,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAkCrD"}

package/dist/server/openapi.js

@@ -3,8 +3,10 @@
  * OpenAPI helpers for the Beignet server runtime.
  */
 /**
- * Create an OpenAPI handler
- * Returns a function that can be called with an HttpRequestLike to get an HttpResponseLike
+ * Create a framework-neutral OpenAPI JSON handler.
+ *
+ * The OpenAPI document is generated lazily on the first request and then cached
+ * for the lifetime of the handler.
  */
 export function createOpenAPIHandler(contracts, openapiConfig, _env) {
     // Lazily generate OpenAPI spec on first request

package/dist/server/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAwC,EACxC,aAAwC,EACxC,IAAoB;IAEpB,gDAAgD;IAChD,IAAI,UAAU,GAAkB,IAAI,CAAC;IAErC,OAAO,KAAK,EAAE,IAAqB,EAA6B,EAAE;QAChE,8BAA8B;QAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,0CAA0C;gBAC1C,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;gBAC1D,UAAU,GAAG,kBAAkB,CAAC,SAAS,EAAE;oBACzC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,aAAa;oBAC5C,OAAO,EAAE,aAAa,EAAE,OAAO,IAAI,OAAO;oBAC1C,WAAW,EAAE,aAAa,EAAE,WAAW;iBACxC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,4BAA4B;gBAC5B,OAAO;oBACL,MAAM,EAAE,GAAG;oBACX,IAAI,EAAE;wBACJ,KAAK,EAAE,2BAA2B;wBAClC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;qBAClE;oBACD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;iBAChD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAwC,EACxC,aAAwC,EACxC,IAAoB;IAEpB,gDAAgD;IAChD,IAAI,UAAU,GAAkB,IAAI,CAAC;IAErC,OAAO,KAAK,EAAE,IAAqB,EAA6B,EAAE;QAChE,8BAA8B;QAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,0CAA0C;gBAC1C,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;gBAC1D,UAAU,GAAG,kBAAkB,CAAC,SAAS,EAAE;oBACzC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,aAAa;oBAC5C,OAAO,EAAE,aAAa,EAAE,OAAO,IAAI,OAAO;oBAC1C,WAAW,EAAE,aAAa,EAAE,WAAW;iBACxC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,4BAA4B;gBAC5B,OAAO;oBACL,MAAM,EAAE,GAAG;oBACX,IAAI,EAAE;wBACJ,KAAK,EAAE,2BAA2B;wBAClC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;qBAClE;oBACD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;iBAChD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/server/providers/loadProviderConfig.d.ts

@@ -2,6 +2,15 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { AnyPorts } from "../../ports";
 import type { ServiceProvider } from "../../providers";
 declare function parseStandardSchema<Schema extends StandardSchemaV1<unknown, unknown>>(schema: Schema, input: unknown): Promise<StandardSchemaV1.InferOutput<Schema>>;
+/**
+ * Load and validate config for a provider.
+ *
+ * Explicit overrides take precedence over env-derived config. When a provider
+ * declares `envPrefix`, matching env keys are stripped before validation.
+ */
 export declare function loadProviderConfig<Ports extends AnyPorts, Schema extends StandardSchemaV1<unknown, unknown>>(provider: ServiceProvider<Ports, Schema>, env: Record<string, string | undefined>, overrides: Record<string, unknown>): Promise<StandardSchemaV1.InferOutput<Schema> | undefined>;
+/**
+ * Parse provider config with Standard Schema and normalize validation errors.
+ */
 export { parseStandardSchema };
 //# sourceMappingURL=loadProviderConfig.d.ts.map

package/dist/server/providers/loadProviderConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadProviderConfig.d.ts","sourceRoot":"","sources":["../../../src/server/providers/loadProviderConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAO9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAOvD,iBAAe,mBAAmB,CAChC,MAAM,SAAS,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAEjD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAU/C;AAED,wBAAsB,kBAAkB,CACtC,KAAK,SAAS,QAAQ,EACtB,MAAM,SAAS,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAEjD,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,EACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CA8B3D;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"loadProviderConfig.d.ts","sourceRoot":"","sources":["../../../src/server/providers/loadProviderConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAO9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAOvD,iBAAe,mBAAmB,CAChC,MAAM,SAAS,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAEjD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAU/C;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,SAAS,QAAQ,EACtB,MAAM,SAAS,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAEjD,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,EACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CA8B3D;AAED;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/server/providers/loadProviderConfig.js

@@ -11,6 +11,12 @@ async function parseStandardSchema(schema, input) {
         throw error;
     }
 }
+/**
+ * Load and validate config for a provider.
+ *
+ * Explicit overrides take precedence over env-derived config. When a provider
+ * declares `envPrefix`, matching env keys are stripped before validation.
+ */
 export async function loadProviderConfig(provider, env, overrides) {
     const configDef = provider.config;
     if (!configDef)
@@ -38,5 +44,8 @@ export async function loadProviderConfig(provider, env, overrides) {
         throw new Error(`Failed to load config for provider "${provider.name}"${suffix}: ${error.message}${hint}`);
     }
 }
+/**
+ * Parse provider config with Standard Schema and normalize validation errors.
+ */
 export { parseStandardSchema };
 //# sourceMappingURL=loadProviderConfig.js.map

package/dist/server/providers/loadProviderConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadProviderConfig.js","sourceRoot":"","sources":["../../../src/server/providers/loadProviderConfig.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AASrD,KAAK,UAAU,mBAAmB,CAGhC,MAAc,EACd,KAAc;IAEd,IAAI,CAAC;QACH,OAAO,MAAM,wBAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,qBAAqB,EAAE,CAAC;YAC3C,MAAM,IAAI,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAItC,QAAwC,EACxC,GAAuC,EACvC,SAAkC;IAElC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAA+C,CAAC;IAC3E,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAEjC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,WAAW;QACvB,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC1B,CAAC,CAAC,SAAS;YACT,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YACrC,CAAC,CAAC,EAAE,CAAC;IAET,IAAI,CAAC;QACH,OAAO,MAAM,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,eAAe,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,SAAS;YACrB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CACvD;YACH,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,GAAG,SAAS;YACpB,CAAC,CAAC,KAAK,CAAC,MAAM;gBACZ,CAAC,CAAC,mCAAmC,SAAS,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACtE,CAAC,CAAC,sCAAsC,SAAS,GAAG;YACtD,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,uCAAuC,QAAQ,CAAC,IAAI,IAAI,MAAM,KAAM,KAAe,CAAC,OAAO,GAAG,IAAI,EAAE,CACrG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"loadProviderConfig.js","sourceRoot":"","sources":["../../../src/server/providers/loadProviderConfig.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AASrD,KAAK,UAAU,mBAAmB,CAGhC,MAAc,EACd,KAAc;IAEd,IAAI,CAAC;QACH,OAAO,MAAM,wBAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,qBAAqB,EAAE,CAAC;YAC3C,MAAM,IAAI,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAItC,QAAwC,EACxC,GAAuC,EACvC,SAAkC;IAElC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAA+C,CAAC;IAC3E,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAEjC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,WAAW;QACvB,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC1B,CAAC,CAAC,SAAS;YACT,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YACrC,CAAC,CAAC,EAAE,CAAC;IAET,IAAI,CAAC;QACH,OAAO,MAAM,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,eAAe,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,SAAS;YACrB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CACvD;YACH,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,GAAG,SAAS;YACpB,CAAC,CAAC,KAAK,CAAC,MAAM;gBACZ,CAAC,CAAC,mCAAmC,SAAS,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACtE,CAAC,CAAC,sCAAsC,SAAS,GAAG;YACtD,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,uCAAuC,QAAQ,CAAC,IAAI,IAAI,MAAM,KAAM,KAAe,CAAC,OAAO,GAAG,IAAI,EAAE,CACrG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/server/server.d.ts

@@ -5,16 +5,41 @@ import type { ProvidedPortsOfList, ServiceProvider } from "../providers";
 import type { ContractLike, ResolveContract } from "./contract-like";
 import type { Handler, HttpRequestLike, HttpResponse, ServerCaughtErrorHook, ServerHook, ServerUnhandledErrorMapper } from "./http";
 /**
- * Route definition
+ * Route registration for one contract.
+ *
+ * Route definitions connect a contract to the handler that implements it. Most
+ * apps keep these in `features/<feature>/routes.ts` and compose them with
+ * `defineRoutes(...)`.
  */
 export type RouteDef<Ctx, CLike extends ContractLike = ContractLike> = {
+    /**
+     * Contract builder or plain contract config for this route.
+     */
     contract: CLike;
+    /**
+     * Handler that implements the contract.
+     */
     handle: Handler<Ctx, ResolveContract<CLike>>;
 };
 declare const ROUTE_GROUP_KIND = "beignet.route-group";
+/**
+ * Named collection of related route registrations.
+ *
+ * Route groups are an organization helper only. `defineRoutes(...)` flattens
+ * them before server registration.
+ */
 export type RouteGroup<Ctx, Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[]> = {
+    /**
+     * Internal marker used by `defineRoutes(...)`.
+     */
     kind: typeof ROUTE_GROUP_KIND;
+    /**
+     * Human-readable group name.
+     */
     name: string;
+    /**
+     * Route definitions in this group.
+     */
     routes: Routes;
 };
 type RouteInput<Ctx> = RouteDef<Ctx, any> | RouteGroup<Ctx, readonly RouteDef<Ctx, any>[]>;
@@ -23,60 +48,134 @@ type FlattenRouteInputs<Inputs extends readonly unknown[]> = number extends Inpu
 type ContractsFromRouteList<Routes extends readonly RouteDef<any, any>[]> = {
     readonly [Index in keyof Routes]: Routes[Index] extends RouteDef<any, infer CLike> ? ResolveContract<CLike> : never;
 };
+/**
+ * Options for creating a Beignet server instance.
+ */
 export type CreateServerOptions<Ctx, Ports extends AnyPorts, Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[], Providers extends readonly ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts>[] = readonly []> = {
+    /**
+     * App-owned ports available to context creation, hooks, and handlers.
+     */
     ports: Ports;
+    /**
+     * Providers installed during server startup.
+     *
+     * Provider ports are merged into `ports` before request handling and are
+     * stopped in reverse setup order when `server.stop()` runs.
+     */
     providers?: Providers;
+    /**
+     * Runtime env used by providers. Defaults to `process.env`.
+     */
     providerEnv?: Record<string, string | undefined>;
+    /**
+     * Provider config overrides keyed by provider name.
+     */
     providerConfig?: Record<string, unknown>;
+    /**
+     * Create request context after a route is matched.
+     *
+     * The `ports` argument includes app ports plus ports provided during server
+     * startup.
+     */
     createContext: (args: {
         req: HttpRequestLike;
         ports: Ports & ProvidedPortsOfList<Providers>;
         contract?: HttpContractConfig;
     }) => Ctx | Promise<Ctx>;
+    /**
+     * Server hooks that wrap every registered route.
+     */
     hooks?: ServerHook<Ctx, Ports & ProvidedPortsOfList<Providers>>[];
+    /**
+     * Route list to register up front.
+     */
     routes?: Routes;
+    /**
+     * Global caught-error observer.
+     */
     onCaughtError?: ServerCaughtErrorHook<Ctx>;
+    /**
+     * Global mapper for unexpected errors not handled by app error catalogs.
+     */
     mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
 };
 interface RouteBuilder<Ctx, C extends HttpContractConfig> {
     handle: (fn: Handler<Ctx, C>) => (req: HttpRequestLike) => Promise<HttpResponse>;
 }
+/**
+ * Runtime server object returned by `createServer(...)`.
+ */
 export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
+    /**
+     * Catch-all request handler for platform adapters.
+     */
     api: (req: HttpRequestLike) => Promise<HttpResponse>;
+    /**
+     * Register and build a single route handler imperatively.
+     */
     route: <CLike extends ContractLike>(contractLike: CLike) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+    /**
+     * Contract configs registered through the `routes` option.
+     */
     contracts: readonly HttpContractConfig[];
+    /**
+     * Stop installed providers in reverse setup order.
+     */
     stop: () => Promise<void>;
+    /**
+     * Final app ports after provider setup.
+     */
     ports: Ports;
 }
+/**
+ * Create a Beignet server instance.
+ *
+ * The server owns route registration, provider setup/startup, request
+ * validation, hook execution, response validation, and framework error mapping.
+ * Use adapter packages such as `@beignet/next` to expose `server.api` to a
+ * specific runtime.
+ *
+ * @param options - Ports, providers, routes, hooks, context factory, and error
+ * mapping hooks for the server.
+ * @returns A started server instance with final ports and a catch-all handler.
+ */
 export declare function createServer<Ctx, Ports extends AnyPorts, Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[], Providers extends readonly ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts>[] = readonly []>(options: CreateServerOptions<Ctx, Ports, Routes, Providers>): Promise<ServerInstance<Ctx, Ports & ProvidedPortsOfList<Providers>>>;
 /**
- * Helper function to define routes with proper type inference.
- * Eliminates the need for type assertions when passing routes to createServer.
+ * Define and flatten route registrations with strong type inference.
+ *
+ * Pass route definitions and route groups here before `createServer(...)`.
+ * Group entries are flattened so downstream tooling receives one route list.
  *
  * @example
+ * ```ts
  * const routes = defineRoutes<AppContext>([
- *   { contract: myContract, handle: async ({ query }) => { ... } }
+ *   { contract: listPosts, handle: async ({ ctx }) => ctx.posts.list() },
  * ]);
+ * ```
  */
 export declare function defineRoutes<Ctx, const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[]>(routes: R): FlattenRouteInputs<R>;
 /**
- * Extract contract configs from a route list. Use this to drive OpenAPI from
- * the same route registration list that createServer receives.
+ * Extract contract configs from a route list.
+ *
+ * Use this to drive clients, OpenAPI, and docs from the same route list passed
+ * to `createServer(...)`.
  */
 export declare function contractsFromRoutes<const R extends readonly RouteDef<any, any>[]>(routes: R): ContractsFromRouteList<R>;
 /**
- * Helper function to group related route registrations.
+ * Define a named group of related route registrations.
  *
  * Route groups are flattened by defineRoutes, so createServer still receives
  * a regular route list while app code can keep feature route wiring colocated.
  *
  * @example
+ * ```ts
  * const todoRoutes = defineRouteGroup<AppContext>({
  *   name: "todos",
  *   routes: [
- *     { contract: listTodos, handle: async ({ ctx }) => { ... } }
+ *     { contract: listTodos, handle: async ({ ctx }) => ctx.todos.list() },
  *   ]
  * });
+ * ```
  */
 export declare function defineRouteGroup<Ctx, const R extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[]>(group: {
     name: string;