@pikku/core 0.12.143 → 0.12.145

package/dist/wirings/credential/validate-credential-definitions.js

@@ -1,3 +1,10 @@
+/**
+ * Merges the credential declarations the inspector found into meta keyed by name.
+ * A name declared more than once must agree on type and schema.
+ *
+ * @throws Error when two declarations of one name disagree on `type` or schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export function validateAndBuildCredentialDefinitionsMeta(definitions, schemaLookup) {
     const meta = {};
     for (const def of definitions) {

package/dist/wirings/flag/cached-flag-source.d.ts

@@ -1,5 +1,6 @@
 import type { FeatureFlagSource } from '../../services/feature-flag-service.js';
 import type { DeclaredFlag, FlagConfigSnapshot } from './flag.types.js';
+/** Tuning for a {@link CachedFlagSource}. */
 export interface CachedFlagSourceOptions {
     /**
      * How long a snapshot is served before it is refreshed, in milliseconds.

package/dist/wirings/flag/flag.types.d.ts

@@ -33,13 +33,16 @@ export type CoreFeatureFlag = {
  * like a scope id invites exactly the confusion this exists to prevent.
  */
 export type CoreFeatureFlags = Record<string, CoreFeatureFlag>;
+/** A feature flag declaration as recorded in generated meta. */
 export type FeatureFlagDefinitionMeta = {
     name: string;
     description?: string;
     anyOf?: string[];
     sourceFile?: string;
 };
+/** Feature flag declarations as the inspector found them. */
 export type FeatureFlagDefinitions = FeatureFlagDefinitionMeta[];
+/** Feature flag declarations collected by the CLI, keyed by name. */
 export type FeatureFlagDefinitionsMeta = Record<string, FeatureFlagDefinitionMeta>;
 /** A declared flag, ready to sync into a flag store. */
 export type DeclaredFlag = {

package/dist/wirings/gateway/gateway-runner.d.ts

@@ -1,6 +1,29 @@
 import type { CoreGateway, GatewayAdapter } from './gateway.types.js';
+/**
+ * Resolves a gateway's adapter, calling a factory adapter with the singleton services once and
+ * caching the promise per gateway config.
+ * @internal
+ */
 export declare const resolveGatewayAdapter: (config: CoreGateway, services: CoreSingletonServices) => Promise<GatewayAdapter>;
 import type { CoreSingletonServices } from '../../types/core.types.js';
+/**
+ * Wires a messaging gateway (Slack, WhatsApp, a web chat, ...) so each inbound message runs `func`
+ * with the adapter-normalised message.
+ *
+ * - `webhook` registers `POST <route>` (and `GET <route>` for adapters with `verifyWebhook`,
+ *   answering the platform's challenge; a failed challenge is a 401).
+ * - `websocket` registers a channel at `route`; replies go back over the socket.
+ * - `listener` registers no route; `GatewayService.start()` opens the adapter outward.
+ *
+ * The routes themselves are unauthenticated, so verify the platform's signature in the gateway's
+ * `middleware`. That middleware runs before the function gate and may establish the session the
+ * handler's `auth` then checks. A non-empty `text`, `richContent` or `attachments` return value is
+ * sent back to the sender through the adapter.
+ *
+ * @param config - The gateway's name, transport, adapter and handler.
+ * @throws Error when `type` is unknown, or `route` is missing for `webhook`/`websocket`.
+ * @example snippet: gatewayWebsocket
+ */
 export declare const wireGateway: (config: CoreGateway) => void;
 /** The returned callback is what a GatewayService passes to `adapter.init()`. */
 export declare const createListenerMessageHandler: (name: string, config: CoreGateway, singletonServices: CoreSingletonServices) => ((rawData: unknown) => Promise<void>);

package/dist/wirings/gateway/gateway-runner.js

@@ -50,6 +50,11 @@ const registerGatewayHandler = (config) => {
  * middleware group.
  */
 const gatewayInheritedMiddleware = (config) => pikkuState(null, 'gateway', 'meta')[config.name]?.middleware;
+/**
+ * Resolves a gateway's adapter, calling a factory adapter with the singleton services once and
+ * caching the promise per gateway config.
+ * @internal
+ */
 export const resolveGatewayAdapter = (config, services) => {
     let resolved = resolvedAdapters.get(config);
     if (!resolved) {
@@ -61,6 +66,24 @@ export const resolveGatewayAdapter = (config, services) => {
     }
     return resolved;
 };
+/**
+ * Wires a messaging gateway (Slack, WhatsApp, a web chat, ...) so each inbound message runs `func`
+ * with the adapter-normalised message.
+ *
+ * - `webhook` registers `POST <route>` (and `GET <route>` for adapters with `verifyWebhook`,
+ *   answering the platform's challenge; a failed challenge is a 401).
+ * - `websocket` registers a channel at `route`; replies go back over the socket.
+ * - `listener` registers no route; `GatewayService.start()` opens the adapter outward.
+ *
+ * The routes themselves are unauthenticated, so verify the platform's signature in the gateway's
+ * `middleware`. That middleware runs before the function gate and may establish the session the
+ * handler's `auth` then checks. A non-empty `text`, `richContent` or `attachments` return value is
+ * sent back to the sender through the adapter.
+ *
+ * @param config - The gateway's name, transport, adapter and handler.
+ * @throws Error when `type` is unknown, or `route` is missing for `webhook`/`websocket`.
+ * @example snippet: gatewayWebsocket
+ */
 export const wireGateway = (config) => {
     pikkuState(null, 'gateway', 'gateways').set(config.name, config);
     switch (config.type) {

package/dist/wirings/gateway/gateway.types.d.ts

@@ -68,6 +68,7 @@ export interface GatewayAdapter {
     /** Receives the GET query params, or the POST body when called from the POST handler. */
     verifyWebhook?(data: unknown, request?: PikkuHTTPRequest): WebhookVerificationResult | Promise<WebhookVerificationResult>;
 }
+/** Builds a gateway adapter from the singleton services, for an adapter that needs a token or client. Called once per gateway. */
 export type GatewayAdapterFactory = (services: CoreSingletonServices) => GatewayAdapter | Promise<GatewayAdapter>;
 export interface PikkuGateway {
     gatewayName: string;
@@ -77,6 +78,7 @@ export interface PikkuGateway {
 }
 /** 'webhook' the platform POSTs to us, 'websocket' the client connects to us, 'listener' no route at all. */
 export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
+/** The configuration `wireGateway` takes: transport, route, adapter, handler and middleware. */
 export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
     /** Unique across the project. It is how the gateway is addressed in `pikku meta` and in logs. */
     name: string;
@@ -105,4 +107,5 @@ export type GatewayMeta = CommonWireMeta & {
     auth?: boolean;
     gateway: true;
 };
+/** Inspector-generated metadata for every wired gateway, keyed by name. */
 export type GatewaysMeta = Record<string, GatewayMeta>;

package/dist/wirings/gateway/local-gateway-service.d.ts

@@ -0,0 +1,10 @@
+import type { GatewayService } from '../../services/gateway-service.js';
+/**
+ * In-process `GatewayService` that starts every `listener` gateway's adapter and closes them on `stop()`.
+ * Assumes a single process: running it in several would open each listener more than once.
+ */
+export declare class LocalGatewayService implements GatewayService {
+    private activeAdapters;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/{services → wirings/gateway}/local-gateway-service.js

@@ -1,6 +1,10 @@
-import { pikkuState, getSingletonServices } from '../pikku-state.js';
-import { createListenerMessageHandler, resolveGatewayAdapter, } from '../wirings/gateway/gateway-runner.js';
+import { pikkuState, getSingletonServices } from '../../pikku-state.js';
+import { createListenerMessageHandler, resolveGatewayAdapter, } from './gateway-runner.js';
 // knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
+/**
+ * In-process `GatewayService` that starts every `listener` gateway's adapter and closes them on `stop()`.
+ * Assumes a single process: running it in several would open each listener more than once.
+ */
 export class LocalGatewayService {
     activeAdapters = new Map();
     async start() {

package/dist/wirings/http/http-routes.d.ts

@@ -1,6 +1,27 @@
 import type { HTTPRouteMap, HTTPRouteContract, HTTPRoutesGroupConfig, WireHTTPRoutesConfig } from './http.types.js';
+/**
+ * Declares a group of HTTP routes without wiring them, so the group can be composed and typed as a contract.
+ *
+ * Accepts either a bare route map or a config with `basePath`, `auth`, `tags`
+ * and `middleware` that apply to every route in it. Nested groups concatenate
+ * `basePath`s, tags and middleware; a route's own `auth` wins over the group's.
+ * Pass the result to {@link wireHTTPRoutes} to register it.
+ *
+ * @example snippet: wireHttp
+ */
 export declare function defineHTTPRoutes<T extends HTTPRouteMap>(routes: T): HTTPRouteContract<T>;
 export declare function defineHTTPRoutes<T extends HTTPRouteMap>(config: HTTPRoutesGroupConfig & {
     routes: T;
 }): HTTPRouteContract<T>;
+/**
+ * Wires a map (or array) of routes and route groups in one call.
+ *
+ * Each route is registered through {@link wireHTTP} with its group's `basePath`
+ * prefixed to its path, the group's middleware run before its own, and the
+ * group's `auth` applied when the route sets none.
+ *
+ * @param config - Group options plus `routes`: a map of routes, groups from {@link defineHTTPRoutes}, or nested maps.
+ *
+ * @example snippet: httpRoutesWiring
+ */
 export declare const wireHTTPRoutes: (config: WireHTTPRoutesConfig) => void;

package/dist/wirings/http/http-routes.js

@@ -7,6 +7,17 @@ export function defineHTTPRoutes(configOrRoutes) {
     }
     return { routes: configOrRoutes };
 }
+/**
+ * Wires a map (or array) of routes and route groups in one call.
+ *
+ * Each route is registered through {@link wireHTTP} with its group's `basePath`
+ * prefixed to its path, the group's middleware run before its own, and the
+ * group's `auth` applied when the route sets none.
+ *
+ * @param config - Group options plus `routes`: a map of routes, groups from {@link defineHTTPRoutes}, or nested maps.
+ *
+ * @example snippet: httpRoutesWiring
+ */
 export const wireHTTPRoutes = (config) => {
     const { routes, ...groupConfig } = config;
     if (Array.isArray(routes)) {

package/dist/wirings/http/http-runner.d.ts

@@ -2,9 +2,80 @@ import type { CoreHTTPFunctionWiring, RunHTTPWiringOptions, PikkuHTTP, PikkuHTTP
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../middleware/middleware.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
+/**
+ * Adds middleware that runs before every HTTP route whose path matches `pattern`.
+ *
+ * `'*'` matches every route, and is also what an unmatched `OPTIONS` request
+ * runs, so CORS middleware belongs there. Calling it again for the same pattern
+ * appends rather than replaces. Group middleware runs before a route's own
+ * `middleware` and before the permissions on its function.
+ *
+ * @param pattern - `'*'`, or a route prefix such as `'/orders'`.
+ * @param middleware - The middleware to add, in the order it should run.
+ * @param packageName - The addon package that owns the group; `null` for the app.
+ * @returns The `middleware` passed in, so a group can be declared and exported in one statement.
+ *
+ * @example snippet: httpMiddleware
+ */
 export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(pattern: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
+/**
+ * Wires a pikku function to one HTTP method and route.
+ *
+ * A route requires a session unless it sets `auth: false`, and an open route
+ * can only point at a sessionless function. Every `:param` in `route` must be a
+ * key of the function's input, which is checked at compile time. On a request
+ * the route's `headers` schema is validated first, then middleware, then the
+ * function's permissions, then the function itself; its return value is sent as
+ * JSON unless `returnsJSON` is `false` or it returns a `Response`.
+ *
+ * Registration needs the metadata `pikku` generates for the route. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param httpWiring - The method, route, function and options for this route.
+ *
+ * @example snippet: httpSingleRoute
+ */
 export declare const wireHTTP: <In, Out, Route extends string, PikkuFunction extends CorePikkuFunction<In, Out> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out> = CorePikkuFunctionSessionless<In, Out>, PikkuPermissionGroup extends CorePikkuPermission<In> = CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware>(httpWiring: CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>) => void;
+/**
+ * Bundles a request and response into the `http` part of a wire, or `undefined` when neither is given.
+ * @internal
+ */
 export declare const createHTTPWire: (request: PikkuHTTPRequest | undefined, response: PikkuHTTPResponse | undefined) => PikkuHTTP | undefined;
+/**
+ * Runs a web `Request` through the wired HTTP routes and returns a web `Response`.
+ *
+ * The entry point for fetch-based runtimes (Cloudflare Workers, Bun, Deno,
+ * Next.js route handlers). It uses the singleton services set by
+ * `setSingletonServices` / `pikkuState`, so they must be created first. Errors
+ * become JSON error responses rather than rejections, unless `bubbleErrors` is set.
+ *
+ * @param request - The incoming request. Its body is capped at `maxBodySize`
+ *   bytes (default {@link DEFAULT_MAX_BODY_SIZE}); a larger body is answered with 413.
+ * @param params - Options for this request; see {@link RunHTTPWiringOptions}.
+ * @returns The response, including a 404 for an unmatched route and a 204 for an unmatched `OPTIONS`.
+ */
 export declare const fetch: <In, Out>(request: Request, params?: RunHTTPWiringOptions) => Promise<Response>;
+/** Like {@link fetch}, but returns the {@link PikkuFetchHTTPResponse} so a host can read or adjust it before converting it to a web `Response`. */
 export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest, params?: RunHTTPWiringOptions) => Promise<PikkuFetchHTTPResponse>;
+/**
+ * Matches a request to a wired route, runs it, and writes the result into `response`.
+ *
+ * The lower-level form of {@link fetch} for adapters that bring their own
+ * request and response objects (Express, Fastify, uWS). A web `Request` is
+ * wrapped with the `maxBodySize` limit. The trace ID is taken from `traceId`,
+ * then the `x-request-id` header, then `generateRequestId`, and is returned to
+ * the client as `errorId` on failures.
+ *
+ * Errors are written to `response`: a 4xx keeps its message and payload, while a
+ * 5xx or an unknown error hides its message unless `exposeErrors` is set outside
+ * production. `exposeErrors` defaults to on outside production and is always off
+ * in production.
+ *
+ * @param request - A web `Request` or an adapter's {@link PikkuHTTPRequest}.
+ * @param response - Where the status, headers and body are written.
+ * @param options - See {@link RunHTTPWiringOptions}.
+ * @returns The function's return value, or `undefined` when the request failed or matched nothing.
+ * @throws The original error when `bubbleErrors` is set, after the error response has been written.
+ * @throws {Error} When `skipUserSession` is set on a route that requires auth.
+ */
 export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, exposeErrors, generateRequestId, traceId: externalTraceId, maxBodySize, }?: RunHTTPWiringOptions) => Promise<Out | void>;

package/dist/wirings/http/http-runner.js

@@ -1,7 +1,7 @@
 import { NotFoundError } from '../../errors/errors.js';
 import { createWeakUID, isSerializable } from '../../utils.js';
 import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
-import { PikkuSessionService } from '../../services/user-session-service.js';
+import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { getErrorResponse } from '../../errors/error-handler.js';
 import { handleHTTPError } from '../../handle-error.js';
 import { isProduction } from '../../env.js';
@@ -27,6 +27,21 @@ function extractHeadersFromRequest(request, headerKeys) {
     }
     return headers;
 }
+/**
+ * Adds middleware that runs before every HTTP route whose path matches `pattern`.
+ *
+ * `'*'` matches every route, and is also what an unmatched `OPTIONS` request
+ * runs, so CORS middleware belongs there. Calling it again for the same pattern
+ * appends rather than replaces. Group middleware runs before a route's own
+ * `middleware` and before the permissions on its function.
+ *
+ * @param pattern - `'*'`, or a route prefix such as `'/orders'`.
+ * @param middleware - The middleware to add, in the order it should run.
+ * @param packageName - The addon package that owns the group; `null` for the app.
+ * @returns The `middleware` passed in, so a group can be declared and exported in one statement.
+ *
+ * @example snippet: httpMiddleware
+ */
 export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
     const httpGroups = pikkuState(packageName, 'middleware', 'httpGroup');
     const existing = httpGroups[pattern];
@@ -35,6 +50,23 @@ export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
         : middleware;
     return middleware;
 };
+/**
+ * Wires a pikku function to one HTTP method and route.
+ *
+ * A route requires a session unless it sets `auth: false`, and an open route
+ * can only point at a sessionless function. Every `:param` in `route` must be a
+ * key of the function's input, which is checked at compile time. On a request
+ * the route's `headers` schema is validated first, then middleware, then the
+ * function's permissions, then the function itself; its return value is sent as
+ * JSON unless `returnsJSON` is `false` or it returns a `Response`.
+ *
+ * Registration needs the metadata `pikku` generates for the route. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param httpWiring - The method, route, function and options for this route.
+ *
+ * @example snippet: httpSingleRoute
+ */
 export const wireHTTP = (httpWiring) => {
     const httpMeta = pikkuState(null, 'http', 'meta');
     const routeMeta = httpMeta[httpWiring.method][httpWiring.route];
@@ -69,6 +101,10 @@ const getMatchingRoute = (requestType, requestPath) => {
         };
     }
 };
+/**
+ * Bundles a request and response into the `http` part of a wire, or `undefined` when neither is given.
+ * @internal
+ */
 export const createHTTPWire = (request, response) => {
     let http = undefined;
     if (request || response) {
@@ -173,10 +209,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         traceId: requestId,
         http,
         channel,
-        session: userSession.get(),
-        setSession: (s) => userSession.setInitial(s),
-        getSession: () => userSession.get(),
-        hasSessionChanged: () => userSession.sessionChanged,
+        ...createMiddlewareSessionWireProps(userSession),
     };
     const statusBeforeRoute = http?.response?.statusCode;
     try {
@@ -233,16 +266,51 @@ const executeRoute = async (services, matchedRoute, http, options) => {
     }
     return { result };
 };
+/**
+ * Runs a web `Request` through the wired HTTP routes and returns a web `Response`.
+ *
+ * The entry point for fetch-based runtimes (Cloudflare Workers, Bun, Deno,
+ * Next.js route handlers). It uses the singleton services set by
+ * `setSingletonServices` / `pikkuState`, so they must be created first. Errors
+ * become JSON error responses rather than rejections, unless `bubbleErrors` is set.
+ *
+ * @param request - The incoming request. Its body is capped at `maxBodySize`
+ *   bytes (default {@link DEFAULT_MAX_BODY_SIZE}); a larger body is answered with 413.
+ * @param params - Options for this request; see {@link RunHTTPWiringOptions}.
+ * @returns The response, including a 404 for an unmatched route and a 204 for an unmatched `OPTIONS`.
+ */
 export const fetch = async (request, params = {}) => {
     const pikkuResponse = new PikkuFetchHTTPResponse();
     await fetchData(request, pikkuResponse, params);
     return pikkuResponse.toResponse();
 };
+/** Like {@link fetch}, but returns the {@link PikkuFetchHTTPResponse} so a host can read or adjust it before converting it to a web `Response`. */
 export const pikkuFetch = async (request, params = {}) => {
     const pikkuResponse = new PikkuFetchHTTPResponse();
     await fetchData(request, pikkuResponse, params);
     return pikkuResponse;
 };
+/**
+ * Matches a request to a wired route, runs it, and writes the result into `response`.
+ *
+ * The lower-level form of {@link fetch} for adapters that bring their own
+ * request and response objects (Express, Fastify, uWS). A web `Request` is
+ * wrapped with the `maxBodySize` limit. The trace ID is taken from `traceId`,
+ * then the `x-request-id` header, then `generateRequestId`, and is returned to
+ * the client as `errorId` on failures.
+ *
+ * Errors are written to `response`: a 4xx keeps its message and payload, while a
+ * 5xx or an unknown error hides its message unless `exposeErrors` is set outside
+ * production. `exposeErrors` defaults to on outside production and is always off
+ * in production.
+ *
+ * @param request - A web `Request` or an adapter's {@link PikkuHTTPRequest}.
+ * @param response - Where the status, headers and body are written.
+ * @param options - See {@link RunHTTPWiringOptions}.
+ * @returns The function's return value, or `undefined` when the request failed or matched nothing.
+ * @throws The original error when `bubbleErrors` is set, after the error response has been written.
+ * @throws {Error} When `skipUserSession` is set on a route that requires auth.
+ */
 export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, maxBodySize, } = {}) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();

package/dist/wirings/http/http.types.d.ts

@@ -4,12 +4,24 @@ import type { CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePikkuFunctionConfig } from '../../function/functions.types.js';
 type ExtractHTTPWiringParams<S extends string> = S extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractHTTPWiringParams<`/${Rest}`> : S extends `${string}:${infer Param}` ? Param : never;
+/** Resolves to `unknown` when every `:param` in a route is a key of `In`, and to a descriptive error tuple otherwise, so a mismatch fails to compile. */
 export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPWiringParams<HTTPWiring> extends keyof In ? unknown : [
     'Error: HTTPWiring parameters',
     ExtractHTTPWiringParams<HTTPWiring>,
     'not in',
     keyof In
 ];
+/**
+ * Per-request options for {@link fetch} and {@link fetchData}.
+ *
+ * - `skipUserSession` – do not resolve a session; throws for a route that requires auth.
+ * - `respondWith404` – write a 404 for an unmatched route (default `true`); `false` lets the host fall through to its own handlers.
+ * - `logWarningsForStatusCodes` – error statuses to log as warnings.
+ * - `coerceDataFromSchema` – coerce query and path strings to the schema's types (default `true`).
+ * - `bubbleErrors` – rethrow after writing the error response.
+ * - `exposeErrors` – include messages and stacks of 5xx errors; ignored in production.
+ * - `generateRequestId` – produce a trace ID when neither `traceId` nor `x-request-id` is present.
+ */
 export type RunHTTPWiringOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -23,8 +35,10 @@ export type RunHTTPWiringOptions = Partial<{
     /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
     maxBodySize: number;
 }>;
+/** The HTTP methods a route can be wired to, in lower case. */
 export type HTTPMethod = 'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options';
 export type HTTPHeadersSchema = StandardSchemaV1<Record<string, string | string[] | undefined>>;
+/** Options shared by a single route and a route in a group. */
 export type HTTPRouteBaseConfig = {
     /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
     contentType?: 'xml' | 'json';
@@ -62,12 +76,14 @@ export interface PikkuHTTPAuthInfo {
     resource?: URL;
     extra?: Record<string, unknown>;
 }
+/** The HTTP part of a wire: the request and response a function was invoked with, when it was invoked over HTTP. */
 export interface PikkuHTTP<In = unknown> {
     request?: PikkuHTTPRequest<In>;
     response?: PikkuHTTPResponse;
     /** Verified token claims, when the transport was handed them. */
     authInfo?: PikkuHTTPAuthInfo;
 }
+/** A parsed query string. Depending on the adapter's parser a value may be a string, an array, or a nested object. */
 export type PikkuQuery<T = Record<string, string | undefined>> = Record<string, string | T | null | Array<T | null>>;
 /**
  * The keys every HTTP wiring takes, whatever it is wired to. The three that
@@ -132,6 +148,7 @@ type HTTPWiringMethod<In> = {
     query?: Array<keyof In>;
     sse?: undefined;
 };
+/** The configuration {@link wireHTTP} takes. The generated `wireHTTP` in an app narrows the function, permission and middleware types to the app's own. */
 export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPWiringShared<R, PikkuMiddleware> & HTTPWiringAuth<In, Out, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware> & HTTPWiringMethod<In>;
 export type HTTPFunctionMetaInputTypes = {
     params?: string;
@@ -159,7 +176,14 @@ export type HTTPWiringMeta = CommonWireMeta & {
     sse?: true;
     groupBasePath?: string;
 };
+/** Generated metadata for every wired route, keyed by method and then route. */
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>;
+/**
+ * The request interface every runtime adapter implements, so functions and middleware read requests the same way on every host.
+ *
+ * `data()` merges path params, query and body into the function's input.
+ * `params()` is empty until a route has matched.
+ */
 export interface PikkuHTTPRequest<In = unknown> {
     method(): HTTPMethod;
     path(): string;
@@ -173,6 +197,7 @@ export interface PikkuHTTPRequest<In = unknown> {
     setParams(params: Record<string, string | string[] | undefined>): void;
     query(): PikkuQuery;
 }
+/** The response interface every runtime adapter implements. Methods return `this` so calls can be chained; the optional members exist only on adapters that support streaming. */
 export interface PikkuHTTPResponse<Out = unknown> {
     readonly statusCode: number;
     status(code: number): this;
@@ -205,9 +230,11 @@ export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<an
     auth?: boolean;
     middleware?: PikkuMiddleware[];
 };
+/** A map of named routes, route groups and nested maps, as accepted by {@link defineHTTPRoutes} and {@link wireHTTPRoutes}. Keys are labels only and never form part of a path. */
 export type HTTPRouteMap = {
     [key: string]: HTTPRouteConfig | HTTPRouteMap | HTTPRouteContract;
 };
+/** A route group returned by {@link defineHTTPRoutes}: group options plus its routes, with the route map's type preserved. */
 export type HTTPRouteContract<T extends HTTPRouteMap = HTTPRouteMap> = HTTPRoutesGroupConfig & {
     routes: T;
 };

package/dist/wirings/http/index.d.ts

@@ -1,5 +1,6 @@
 export { PikkuFetchHTTPRequest, DEFAULT_MAX_BODY_SIZE, } from './pikku-fetch-http-request.js';
 export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
+export { mergeRequestData } from './merge-request-data.js';
 export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';

package/dist/wirings/http/index.js

@@ -1,5 +1,6 @@
 export { PikkuFetchHTTPRequest, DEFAULT_MAX_BODY_SIZE, } from './pikku-fetch-http-request.js';
 export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
+export { mergeRequestData } from './merge-request-data.js';
 export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';

package/dist/wirings/http/log-http-routes.d.ts

@@ -1,2 +1,3 @@
 import type { Logger } from '../../services/index.js';
+/** Logs every wired HTTP route at info level, typically once at startup. */
 export declare const logRoutes: (logger: Logger) => void;

package/dist/wirings/http/log-http-routes.js

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+/** Logs every wired HTTP route at info level, typically once at startup. */
 export const logRoutes = (logger) => {
     const routesByType = pikkuState(null, 'http', 'routes');
     if (routesByType.size === 0) {

package/dist/wirings/http/merge-request-data.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Merges route params, query and body into the single input object a Pikku
+ * function receives. Earlier parts win; a key present in more than one part
+ * must carry an equivalent value (`'1'` and `1`, `'true'` and `true`), or the
+ * request is rejected. Prototype-polluting keys are dropped.
+ *
+ * Every HTTP runtime calls this from `PikkuHTTPRequest.data()`, so the merge
+ * and the conflict rule are identical wherever a function is served.
+ *
+ * @throws UnprocessableContentError when two parts disagree on a key.
+ */
+export declare const mergeRequestData: <In = unknown>(...parts: Array<Readonly<Record<string, unknown>>>) => In;

package/dist/wirings/http/merge-request-data.js

@@ -0,0 +1,42 @@
+import { UnprocessableContentError } from '../../errors/errors.js';
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Merges route params, query and body into the single input object a Pikku
+ * function receives. Earlier parts win; a key present in more than one part
+ * must carry an equivalent value (`'1'` and `1`, `'true'` and `true`), or the
+ * request is rejected. Prototype-polluting keys are dropped.
+ *
+ * Every HTTP runtime calls this from `PikkuHTTPRequest.data()`, so the merge
+ * and the conflict rule are identical wherever a function is served.
+ *
+ * @throws UnprocessableContentError when two parts disagree on a key.
+ */
+export const mergeRequestData = (...parts) => {
+    const merged = {};
+    for (const part of parts) {
+        for (const [key, value] of Object.entries(part)) {
+            if (FORBIDDEN_KEYS.has(key)) {
+                continue;
+            }
+            if (!Object.hasOwn(merged, key)) {
+                merged[key] = value;
+            }
+            else if (!valuesAreEquivalent(merged[key], value)) {
+                throw new UnprocessableContentError(`Conflicting values for key "${key}": "${String(merged[key])}" vs "${String(value)}"`);
+            }
+        }
+    }
+    return merged;
+};
+const valuesAreEquivalent = (a, b) => coerce(a) === coerce(b);
+const coerce = (value) => {
+    if (typeof value === 'string') {
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        const num = Number(value);
+        return isNaN(num) ? value : num;
+    }
+    return value;
+};

package/dist/wirings/http/pikku-fetch-http-request.d.ts

@@ -1,4 +1,5 @@
 import type { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js';
+/** The request body limit, in bytes (10 MiB), applied when a web `Request` is wrapped and no `maxBodySize` is given. A larger body is refused with a 413 before it is fully read. */
 export declare const DEFAULT_MAX_BODY_SIZE: number;
 export type PikkuFetchHTTPRequestOptions = Partial<{
     /** Maximum request body size in bytes. Defaults to {@link DEFAULT_MAX_BODY_SIZE}. */

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -1,6 +1,8 @@
 import { parse as parseQuery } from 'picoquery';
 import { parseCookie } from 'cookie';
 import { PayloadTooLargeError, UnprocessableContentError, } from '../../errors/errors.js';
+import { mergeRequestData } from './merge-request-data.js';
+/** The request body limit, in bytes (10 MiB), applied when a web `Request` is wrapped and no `maxBodySize` is given. A larger body is refused with a 413 before it is fully read. */
 export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**
  * @group RequestResponse
@@ -135,22 +137,7 @@ export class PikkuFetchHTTPRequest {
     }
     async data() {
         const body = await this.body();
-        const parts = [this.params(), this.query(), body];
-        const merged = {};
-        for (const part of parts) {
-            for (const [key, value] of Object.entries(part)) {
-                if (key === '__proto__' ||
-                    key === 'constructor' ||
-                    key === 'prototype') {
-                    continue;
-                }
-                if (key in merged && !valuesAreEquivalent(merged[key], value)) {
-                    throw new UnprocessableContentError(`Conflicting values for key "${key}": "${merged[key]}" vs "${value}"`);
-                }
-                merged[key] ??= value;
-            }
-        }
-        return merged;
+        return mergeRequestData(this.params(), this.query(), body);
     }
     async body() {
         const noBodyMethods = ['get', 'head', 'options', 'delete'];
@@ -202,19 +189,3 @@ export class PikkuFetchHTTPRequest {
         return body;
     }
 }
-function valuesAreEquivalent(a, b) {
-    return coerce(a) === coerce(b);
-}
-function coerce(value) {
-    if (typeof value === 'boolean' || typeof value === 'number')
-        return value;
-    if (typeof value === 'string') {
-        if (value === 'true')
-            return true;
-        if (value === 'false')
-            return false;
-        const num = Number(value);
-        return isNaN(num) ? value : num;
-    }
-    return value;
-}