@beignet/core 0.0.1 → 0.0.2

package/src/server/hooks/logging.ts

@@ -6,21 +6,51 @@ import type { HttpContractConfig } from "../../contracts";
 import type { HttpRequestLike, ServerHook } from "../types";
 import { getRequestIdFromContext } from "./utils";
 
+/**
+ * Minimal logger shape accepted by `createLoggingHooks(...)`.
+ */
 export interface Logger {
+  /**
+   * Log an informational event.
+   */
   info: (...args: unknown[]) => void;
+  /**
+   * Log an error event.
+   */
   error: (...args: unknown[]) => void;
+  /**
+   * Log a warning event.
+   */
   warn?: (...args: unknown[]) => void;
+  /**
+   * Log a debug event.
+   */
   debug?: (...args: unknown[]) => void;
 }
 
+/**
+ * Logging hook configuration.
+ */
 export interface LoggingConfig<Ctx> {
+  /**
+   * Logger used when custom lifecycle callbacks are not provided.
+   */
   logger?: Logger;
+  /**
+   * Response header name used to expose `ctx.requestId` when present.
+   */
   requestIdHeader?: string;
+  /**
+   * Custom request-start observer.
+   */
   onRequestStart?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
     contract?: HttpContractConfig;
   }) => void;
+  /**
+   * Custom request-end observer.
+   */
   onRequestEnd?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
@@ -31,6 +61,12 @@ export interface LoggingConfig<Ctx> {
   }) => void;
 }
 
+/**
+ * Create request logging hooks.
+ *
+ * Logging observer errors are intentionally ignored so logging cannot break
+ * request handling.
+ */
 export function createLoggingHooks<Ctx>(
   config: LoggingConfig<Ctx>,
 ): ServerHook<Ctx> {

package/src/server/hooks/rate-limit.ts

@@ -7,10 +7,16 @@ import { AppError, httpErrors } from "../../errors";
 import type { ActivityActor, RateLimitPort } from "../../ports";
 import type { HttpRequestLike, ServerHook } from "../types";
 
+/**
+ * Ports required by rate-limit hooks.
+ */
 export type RateLimitPorts = {
   rateLimit: RateLimitPort;
 };
 
+/**
+ * Minimal context shape required for user-scoped rate limits.
+ */
 export type CtxWithRateLimit = {
   ports: RateLimitPorts;
   actor?: ActivityActor;
@@ -18,16 +24,32 @@ export type CtxWithRateLimit = {
 
 type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
 
+/**
+ * Options for `createRateLimitHooks(...)`.
+ */
 export interface RateLimitOptions<Ctx> {
+  /**
+   * Build a rate-limit key after context exists.
+   *
+   * This is used for user-scoped limits and any late key strategy.
+   */
   key?: (args: {
     ctx: Ctx;
     req: HttpRequestLike;
     scope: RateLimitScope;
   }) => string;
+  /**
+   * Build a rate-limit key before request parsing and context creation.
+   *
+   * This is used for global and IP-scoped limits.
+   */
   earlyKey?: (args: {
     req: HttpRequestLike;
     scope: EarlyRateLimitScope;
   }) => string;
+  /**
+   * Resolve a client IP from the raw request.
+   */
   getClientIp?: (req: HttpRequestLike) => string | undefined;
 }
 
@@ -112,6 +134,17 @@ async function enforceRateLimit(
   );
 }
 
+/**
+ * Create metadata-driven rate-limit hooks.
+ *
+ * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
+ * in `onRequest` before context creation; user-scoped limits run in
+ * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
+ * framework `TooManyRequests` app error.
+ *
+ * @param options - Optional key builders and client-IP resolver.
+ * @returns A server hook backed by `ctx.ports.rateLimit`.
+ */
 export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   options: RateLimitOptions<Ctx> = {},
 ): ServerHook<Ctx, RateLimitPorts> {

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,91 @@ 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>;
 
+/**
+ * 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 +184,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 +198,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 +214,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 +235,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 +257,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 +274,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 +294,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,27 +5,44 @@
  * 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,

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 };