@beignet/core 0.0.1 → 0.0.3

package/src/server/http.ts

@@ -6,9 +6,24 @@ import type {
 } 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.
@@ -17,20 +32,56 @@ 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<
@@ -38,44 +89,170 @@ type InferSchemaOrFallback<
   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;
 
-  // inferred from contract schemas
+  /**
+   * 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>;
 
+/**
+ * Arguments passed to a route-scoped hook after request parsing and context
+ * creation.
+ */
+export type RouteHookArgs<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = HandlerArgs<Ctx, C>;
+
+/**
+ * Hook that runs only for the route or route group where it is attached.
+ *
+ * Route hooks are for scoped policy and context enrichment such as
+ * authentication, tenant resolution, feature gates, and idempotency. They add
+ * fields to the handler context instead of replacing the app context.
+ */
+export interface RouteHook<
+  Ctx,
+  AddedCtx extends object = Record<string, never>,
+> {
+  /**
+   * Optional name used in diagnostics and devtools.
+   */
+  name?: string;
+  /**
+   * Resolve additional context for this route or throw to stop handling.
+   */
+  resolve: (args: RouteHookArgs<Ctx>) => MaybePromise<AddedCtx | undefined>;
+}
+
+/**
+ * Builder for route-scoped hooks.
+ */
+export type RouteHookBuilder<Ctx> = {
+  /**
+   * Assign a diagnostic name to the hook.
+   */
+  name: (name: string) => RouteHookNamedBuilder<Ctx>;
+  /**
+   * Define the hook resolver.
+   */
+  resolve: <AddedCtx extends object>(
+    resolve: RouteHook<Ctx, AddedCtx>["resolve"],
+  ) => RouteHook<Ctx, AddedCtx>;
+};
+
+/**
+ * Named builder for route-scoped hooks.
+ */
+export type RouteHookNamedBuilder<Ctx> = {
+  /**
+   * Define the hook resolver.
+   */
+  resolve: <AddedCtx extends object>(
+    resolve: RouteHook<Ctx, AddedCtx>["resolve"],
+  ) => RouteHook<Ctx, AddedCtx>;
+};
+
+/**
+ * Define a route-scoped hook.
+ *
+ * Route hooks enrich handler context for one route or route group. They should
+ * throw application/framework errors for denials instead of returning HTTP
+ * responses directly.
+ */
+export function defineRouteHook<Ctx>(): RouteHookBuilder<Ctx> {
+  return {
+    name: (name) => ({
+      resolve: (resolve) => ({
+        name,
+        resolve,
+      }),
+    }),
+    resolve: (resolve) => ({
+      resolve,
+    }),
+  };
+}
+
+/**
+ * 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,
@@ -86,6 +263,12 @@ export type OnRequestHook<
   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
@@ -94,6 +277,9 @@ export type BeforeHandleResult<Ctx> =
       response?: HttpResponse;
     };
 
+/**
+ * Hook that runs after request parsing/context creation and before the handler.
+ */
 export type BeforeHandleHook<
   Ctx,
   C extends HttpContractConfig = HttpContractConfig,
@@ -107,6 +293,12 @@ export type BeforeHandleHook<
   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,
@@ -122,6 +314,12 @@ export type BeforeSendHook<
   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,
@@ -138,6 +336,9 @@ export type AfterSendHook<
   durationMs: number;
 }) => MaybePromise<void>;
 
+/**
+ * Hook notified when the framework catches an error while handling a request.
+ */
 export type ServerCaughtErrorHook<
   Ctx,
   C extends HttpContractConfig = HttpContractConfig,
@@ -152,6 +353,12 @@ export type ServerCaughtErrorHook<
   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,
@@ -166,22 +373,63 @@ export type ServerUnhandledErrorMapper<
   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,

package/src/server/index.ts

@@ -5,30 +5,48 @@
  * Shared by Beignet server adapters.
  */
 
-// Re-export types from dependencies for convenience
+/**
+ * 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,
+  defineRoute,
   defineRouteGroup,
   defineRoutes,
 } from "./server";

package/src/server/openapi.ts

@@ -8,7 +8,7 @@ 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) */
@@ -28,8 +28,10 @@ export interface OpenAPIConfig {
 }
 
 /**
- * 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: readonly HttpContractConfig[],

package/src/server/providers/loadProviderConfig.ts

@@ -30,6 +30,12 @@ async function parseStandardSchema<
   }
 }
 
+/**
+ * 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<
   Ports extends AnyPorts,
   Schema extends StandardSchemaV1<unknown, unknown>,
@@ -69,4 +75,7 @@ export async function loadProviderConfig<
   }
 }
 
+/**
+ * Parse provider config with Standard Schema and normalize validation errors.
+ */
 export { parseStandardSchema };