lambder 11.1.1 → 13.0.1

package/dist/api/LambderApiGuards.d.ts

@@ -72,9 +72,11 @@ export type LambderGuardRefusals<TRefusals extends readonly string[] = readonly
  *
  * Orthogonally, a guard may also:
  *
- * - declare `session: true`: the guard needs ctx.session, so it is only
- *   declarable on addSessionApi (compile error and startup assert on public
- *   APIs) and its handler receives the session-typed context.
+ * - declare `session: true`: the guard needs ctx.session, so it makes every
+ *   endpoint declaring it a session endpoint (the session is read before the
+ *   guards run, a call without one is answered sessionExpired, and the
+ *   endpoint's handler receives the session-typed context), and it receives
+ *   the session-typed context itself.
  * - take a PARAMETER: annotate a 3rd handler argument
  *   (`(ctx, payload, param: YourType) => ...`) and APIs pass the value in
  *   their declaration: `guards: { yourGuard: paramValue }`. The value is
@@ -272,19 +274,16 @@ export type LambderGuardMetaMap<TGuards> = {
     [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
 };
 /**
- * Guard names an API may declare: every guard the instance holds, session
- * guards only on session APIs. Whether the API's input carries the fields an
- * apiInput guard reads is asked of the names it declared, once that input is
- * known, by LambderGuardNamesInputLacks.
+ * Guard names an API may declare: every guard the instance holds, a session
+ * guard included, which makes the API a session one (LambderApiModeOf).
+ * Whether the API's input carries the fields an apiInput guard reads is
+ * asked of the names it declared, once that input is known, by
+ * LambderGuardNamesInputLacks.
  */
-export type LambderAllowedGuardNames<TGuards, TIncludeSession extends boolean = true> = {
-    [K in keyof TGuards]: TGuards[K] extends {
-        session: true;
-    } ? (TIncludeSession extends true ? K : never) : K;
-}[keyof TGuards] & string;
+export type LambderAllowedGuardNames<TGuards> = keyof TGuards & string;
 /**
  * The apiInput guards among `TNames` whose fields the API's payload does not
- * carry. addApi and addSessionApi ask this once the API's input is known, of
+ * carry. defineApi asks this once the API's input is known, of
  * the names its guards option holds; see LambderPayloadSliceCheck.
  *
  * The payload is compared whole, not member by member: a bare `TPayload
@@ -298,14 +297,14 @@ export type LambderGuardNamesInputLacks<TGuards, TNames, TPayload> = {
     } ? ([TPayload] extends [R] ? never : K) : never;
 }[TNames & keyof TGuards] & string;
 /** The allowed guard names whose handler takes no param (usable in the string/array forms). */
-export type LambderParamlessGuardNames<TGuards, TIncludeSession extends boolean> = {
-    [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+export type LambderParamlessGuardNames<TGuards> = {
+    [K in LambderAllowedGuardNames<TGuards> & keyof TGuards]: TGuards[K] extends {
         param: undefined;
     } ? K & string : never;
-}[LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards];
+}[LambderAllowedGuardNames<TGuards> & keyof TGuards];
 /** The map form's full shape: every declarable guard name, each carrying its own param type. */
-type LambderGuardsMap<TGuards, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+type LambderGuardsMap<TGuards> = {
+    readonly [K in LambderAllowedGuardNames<TGuards> & keyof TGuards]?: TGuards[K] extends {
         param: undefined;
     } ? true : TGuards[K] extends {
         param: infer P;
@@ -324,10 +323,10 @@ type LambderGuardsMap<TGuards, TIncludeSession extends boolean> = {
  * compiler builds it once per instance rather than once per API; see
  * LambderPayloadSliceCheck for why, and for where the input is asked.
  */
-export type LambderGuardsOption<TGuards, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TIncludeSession> | readonly [
-    LambderParamlessGuardNames<TGuards, TIncludeSession>,
-    ...LambderParamlessGuardNames<TGuards, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards, TIncludeSession>>;
+export type LambderGuardsOption<TGuards> = LambderParamlessGuardNames<TGuards> | readonly [
+    LambderParamlessGuardNames<TGuards>,
+    ...LambderParamlessGuardNames<TGuards>[]
+] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards>>;
 /**
  * The typed ctx.guardData an API's handler sees: declared guards that return
  * a value, keyed by name. Check-only (void) guards never appear.

package/dist/api/LambderApiGuards.js

@@ -101,7 +101,7 @@ export class LambderApiGuardsEngine {
                 throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
             }
             if (guardDef.session && mode !== "session") {
-                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
+                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true) but is registered as public. An endpoint declaring a session guard is a session endpoint.`);
             }
         }
     }

package/dist/api/LambderApiRateLimits.d.ts

@@ -116,7 +116,7 @@ export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
     /** Your limiter instance (LambderDdbRateLimiter, LambderMemoryRateLimiter, or your own); its table and keyPrefix apply as configured on it. */
     limiter: LambderRateLimiter;
-    /** Named policies referenced (typed) from addApi/addSessionApi. */
+    /** Named policies referenced (typed) from defineApi. */
     policies: TPolicies;
     /**
      * Let the request through when the limiter itself fails (the table is
@@ -144,23 +144,23 @@ export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderA
  * without one, and a union holding undefined for a policy typed as the
  * general LambderApiRateLimitPolicyConfig, where only registration can tell.
  */
-type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
+export type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
 /**
- * Policy names an API may reference: session-keyed policies only on session
- * APIs, and never a policy without `per`, whose key only the code that
- * charges it knows. A policy whose type does not settle its `per` is allowed
- * here and checked at registration. Whether the API's input carries the
- * fields an apiInput-keyed policy reads is asked of the names it declared,
- * once that input is known, by LambderPolicyNamesInputLacks.
+ * Policy names an API may reference: never a policy without `per`, whose key
+ * only the code that charges it knows. A policy whose type does not settle
+ * its `per` is allowed here and checked at registration. A session-keyed
+ * policy is allowed here too, and refused of an API none of whose guards
+ * needs a session by LambderPublicSessionPolicyCheck, once its guards are
+ * known. Whether the API's input carries the fields an apiInput-keyed policy
+ * reads is asked of the names it declared, once that input is known, by
+ * LambderPolicyNamesInputLacks.
  */
-export type LambderAllowedPolicyNames<TPolicies, TIncludeSession extends boolean> = {
-    [K in keyof TPolicies]: [
-        LambderPolicyPerOf<TPolicies[K]>
-    ] extends [undefined] ? never : [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? (TIncludeSession extends true ? K : never) : K;
+export type LambderAllowedPolicyNames<TPolicies> = {
+    [K in keyof TPolicies]: [LambderPolicyPerOf<TPolicies[K]>] extends [undefined] ? never : K;
 }[keyof TPolicies] & string;
 /**
  * The apiInput-keyed policies among `TNames` whose key fields the API's
- * payload does not carry. addApi and addSessionApi ask this once the API's
+ * payload does not carry. defineApi asks this once the API's
  * input is known, of the names its rateLimit option holds; see
  * LambderPayloadSliceCheck.
  *
@@ -235,8 +235,8 @@ type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
     budget: "perPolicy";
 } ? Pick<LambderRateLimitOverride, "refusal"> : LambderRateLimitOverride;
 /** The map form's full shape: every referable policy name, each carrying its own override. */
-type LambderRateLimitMap<TPolicies, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedPolicyNames<TPolicies, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
+type LambderRateLimitMap<TPolicies> = {
+    readonly [K in LambderAllowedPolicyNames<TPolicies> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
 };
 /**
  * The per-API `rateLimit` option: one policy name, a non-empty ordered list
@@ -251,10 +251,10 @@ type LambderRateLimitMap<TPolicies, TIncludeSession extends boolean> = {
  * It depends on the instance alone, never on the API's input, as
  * LambderGuardsOption does; see LambderPayloadSliceCheck.
  */
-export type LambderRateLimitOption<TPolicies, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TIncludeSession> | readonly [
-    LambderAllowedPolicyNames<TPolicies, TIncludeSession>,
-    ...LambderAllowedPolicyNames<TPolicies, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies, TIncludeSession>>;
+export type LambderRateLimitOption<TPolicies> = LambderAllowedPolicyNames<TPolicies> | readonly [
+    LambderAllowedPolicyNames<TPolicies>,
+    ...LambderAllowedPolicyNames<TPolicies>[]
+] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies>>;
 /**
  * When in a call a policy is checked.
  *

package/dist/api/LambderApiRateLimits.js

@@ -209,7 +209,7 @@ export class LambderApiRateLimitsEngine {
                 throw new Error(`Lambder: API "${apiName}" references rate-limit policy "${name}", which declares no per: its key is the one a handler passes to ctx.rateLimit("${name}", key), so the request alone cannot be counted against it.`);
             }
             if (policy.per === "session" && mode !== "session") {
-                throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);
+                throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which counts per session, and none of its guards needs a session.`);
             }
             if (override)
                 assertWindowLimits(`API "${apiName}" override of rate-limit policy "${name}"`, override);

package/dist/api/LambderApiRefusals.d.ts

@@ -3,6 +3,7 @@ import type { LambderJsonOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderRefusalStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
 import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderNoRepeatedNames } from "../shared/util/LambderNamedMaps.js";
 /**
  * One code of an app's refusal vocabulary: the schema of the data it carries,
  * when it carries data, and how every refusal with the code leaves the
@@ -69,6 +70,27 @@ export type LambderRefusalVocabularyChecks<TVocabulary> = {
         readonly "lambder: a refusal code may not start with lambder/, the prefix of the framework's own codes": never;
     } : LambderNoExtraKeys<TVocabulary[TCode], LambderRefusalDeclaration> & LambderRefusalDataCheck<TVocabulary[TCode]>;
 };
+/**
+ * The vocabulary as declareRefusals() takes it: one map of codes, or a list of
+ * them, so each part of an app declares its own codes beside its APIs. A
+ * code two maps declare is refused.
+ */
+export type LambderRefusalVocabularyOption = LambderNamedMapsOption<LambderRefusalVocabulary>;
+/** The one vocabulary a declareRefusals() option declares: a list's maps merged, a lone map as it is. */
+export type LambderMergedRefusalVocabulary<TOption> = LambderMergedNamedMaps<TOption> extends infer TMerged extends LambderRefusalVocabulary ? TMerged : never;
+/** A declareRefusals() option checked code by code, in each map of a list, and a list declaring no code twice. */
+export type LambderRefusalVocabularyOptionChecks<TOption> = TOption extends readonly unknown[] ? {
+    [TIndex in keyof TOption]: LambderRefusalVocabularyChecks<TOption[TIndex]>;
+} & LambderNoRepeatedNames<TOption> : LambderRefusalVocabularyChecks<TOption>;
+/**
+ * A declareRefusals() option as the one vocabulary it declares, checked
+ * (see readRefusalVocabulary) and keyed. `declarer` names the init in the
+ * errors.
+ */
+export declare const declaredRefusalVocabulary: (option: LambderRefusalVocabularyOption, declarer: string) => {
+    refusals: LambderRefusalVocabulary;
+    vocabulary: Map<string, LambderRefusalDeclaration>;
+};
 /** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
 export declare const allowedRefusalOf: (declaration: LambderRefusalDeclaration) => LambderApiAllowedRefusal;
 /**

package/dist/api/LambderApiRefusals.js

@@ -1,5 +1,18 @@
 import { LambderApiRefusal, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
+import { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
+/**
+ * A declareRefusals() option as the one vocabulary it declares, checked
+ * (see readRefusalVocabulary) and keyed. `declarer` names the init in the
+ * errors.
+ */
+export const declaredRefusalVocabulary = (option, declarer) => {
+    if (option === null || typeof option !== "object") {
+        throw new Error(`${declarer}: declareRefusals() takes the vocabulary, an object of codes or a list of them.`);
+    }
+    const refusals = mergeNamedMaps(option, "refusal code", "declareRefusals()");
+    return { refusals, vocabulary: readRefusalVocabulary(refusals) };
+};
 /** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
 export const allowedRefusalOf = (declaration) => {
     const leaves = {

package/dist/api/LambderApiRequest.d.ts

@@ -18,7 +18,15 @@ export declare const lowercaseHeaderNames: (headers: Record<string, string | und
  * transport request, and from here on nothing in the pipeline knows which.
  */
 export type LambderApiRequest = {
+    /** The endpoint called: `group.action`, read off the path the call was posted to (`{apiPath}/{group}/{action}`). */
     apiName: string;
+    /**
+     * Set on a call posted to apiPath itself with the endpoint named in the
+     * body, the way callers did before endpoints had paths: such a caller is a
+     * page loaded from an older build, and it is answered that its version
+     * expired, which reloads it.
+     */
+    retiredPath?: true;
     /** The caller's apiVersion, informational; null when it sent none. */
     version: string | null;
     /** The signature the caller carries for this endpoint (see LambderApiSignatureMap), for the signature gate; null when it sent none. */
@@ -79,13 +87,14 @@ export type LambderApiRequestInfo = {
  */
 export declare const isApiCallContentType: (lowercasedHeaders: Record<string, string | undefined>) => boolean;
 /**
- * Reads the posted envelope into a request. Null when the body carries no
- * apiName, which is how the server tells an API call from a route with a
- * JSON body. Everything is taken as posted: a malformed idempotencyKey or
- * guardInputs value is the engines' to refuse, with the client-facing
- * message they already give.
+ * Reads the posted envelope of a call to `apiName` into a request; the name
+ * comes from where the call was posted, never from the body. Everything is
+ * taken as posted: a malformed idempotencyKey or guardInputs value is the
+ * engines' to refuse, with the client-facing message they already give.
  */
-export declare const readApiEnvelope: (post: Record<string, unknown> | null | undefined, info: LambderApiRequestInfo) => LambderApiRequest | null;
+export declare const readApiEnvelope: (post: Record<string, unknown> | null | undefined, info: LambderApiRequestInfo, apiName: string, flags?: {
+    retiredPath?: true;
+}) => LambderApiRequest;
 /** Outcome of restoring a compressed request payload; the message is client-facing. */
 export type LambderRestorePayloadResult = {
     ok: true;

package/dist/api/LambderApiRequest.js

@@ -43,20 +43,19 @@ export const lowercaseHeaderNames = (headers) => {
  */
 export const isApiCallContentType = (lowercasedHeaders) => (lowercasedHeaders["content-type"] ?? "").split(";")[0].trim().toLowerCase() === "application/json";
 /**
- * Reads the posted envelope into a request. Null when the body carries no
- * apiName, which is how the server tells an API call from a route with a
- * JSON body. Everything is taken as posted: a malformed idempotencyKey or
- * guardInputs value is the engines' to refuse, with the client-facing
- * message they already give.
+ * Reads the posted envelope of a call to `apiName` into a request; the name
+ * comes from where the call was posted, never from the body. Everything is
+ * taken as posted: a malformed idempotencyKey or guardInputs value is the
+ * engines' to refuse, with the client-facing message they already give.
  */
-export const readApiEnvelope = (post, info) => {
-    if (!post || typeof post.apiName !== "string" || !post.apiName)
-        return null;
+export const readApiEnvelope = (post, info, apiName, flags = {}) => {
+    post ??= {};
     const hasGzip = post[COMPRESSED_PAYLOAD_GZ_FIELD] !== undefined;
     const hasBrotli = post[COMPRESSED_PAYLOAD_BR_FIELD] !== undefined;
     const guardInputs = post.guardInputs;
     return {
-        apiName: post.apiName,
+        apiName,
+        ...(flags.retiredPath ? { retiredPath: true } : {}),
         version: typeof post.version === "string" ? post.version : null,
         signature: typeof post.signature === "string" ? post.signature : null,
         token: typeof post.token === "string" ? post.token : "",

package/dist/build/generateApiFiles.d.ts

@@ -0,0 +1,60 @@
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderApiContractFileOptions } from "./writeApiContract.js";
+import { type LambderApiSignatureFileOptions } from "./writeApiSignatures.js";
+import { type LambderApiOptionsFileOptions } from "./writeApiOptions.js";
+import { type LambderApiGuardParamsFileOptions } from "./writeApiGuardParams.js";
+/** What a file's writer takes beyond where the instance is, which the app gives once for all its files. */
+type LambderAppFile<TOptions> = Omit<TOptions, "module" | "exportName" | "tsconfig" | "check">;
+/** One app: where its instance is, and which files it is written to. Each file is optional. */
+export type LambderApiFilesApp = {
+    /** The module that exports the instance, usually the server's entry: a path relative to the working directory, or a file URL. */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default". */
+    exportName?: string;
+    /** The tsconfig.json the module compiles under, which the contract is read through. Default: the nearest one at or above the module. */
+    tsconfig?: string;
+    /** The contract a client compiles against, as plain types (writeApiContract). */
+    contract?: LambderAppFile<LambderApiContractFileOptions>;
+    /** The signature file both sides ship (writeApiSignatures). */
+    signatures?: LambderAppFile<LambderApiSignatureFileOptions>;
+    /** The declared options as plain data, for a mock and tests (writeApiOptions). */
+    options?: LambderAppFile<LambderApiOptionsFileOptions>;
+    /** One file per guard whose parameters a browser needs (writeApiGuardParams). */
+    guardParams?: readonly LambderAppFile<LambderApiGuardParamsFileOptions>[];
+};
+/** The files generateApiFiles writes: every app's, by a name the output lines use. */
+export type LambderApiFilesConfig = {
+    apps: Record<string, LambderApiFilesApp>;
+};
+export type LambderApiFilesResult = {
+    /** False when a check found a file stale, or a writer failed. */
+    ok: boolean;
+    /** What happened, per app and file, as lines to print. */
+    lines: string[];
+};
+/**
+ * Writes every file the config names, or with `check` writes nothing and
+ * answers whether each one on disk is current. Paths are relative to the
+ * working directory, as each writer takes them.
+ *
+ * ```ts
+ * import { generateApiFiles } from "lambder/build";
+ *
+ * const result = await generateApiFiles({
+ *     apps: {
+ *         server: {
+ *             module: "backend/index.ts",
+ *             exportName: "lambder",
+ *             contract: { file: "shared/generated/apiContract.generated.ts" },
+ *             signatures: { file: "shared/generated/apiSignatures.generated.ts" },
+ *         },
+ *     },
+ * }, { check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ */
+export declare const generateApiFiles: (config: LambderApiFilesConfig, options?: {
+    check?: boolean;
+}) => Promise<LambderApiFilesResult>;
+export {};

package/dist/build/generateApiFiles.js

@@ -0,0 +1,85 @@
+import { writeApiContract } from "./writeApiContract.js";
+import { writeApiSignatures } from "./writeApiSignatures.js";
+import { writeApiOptions } from "./writeApiOptions.js";
+import { writeApiGuardParams } from "./writeApiGuardParams.js";
+const APP_KEYS = ["module", "exportName", "tsconfig", "contract", "signatures", "options", "guardParams"];
+const FILE_KINDS = ["contract", "signatures", "options", "guardParams"];
+/** A config that names apps, each with its module and at least one file, and no key the generator does not read. */
+function assertConfig(config) {
+    const apps = config?.apps;
+    if (apps === null || typeof apps !== "object" || Array.isArray(apps) || Object.keys(apps).length === 0) {
+        throw new Error("generateApiFiles: the config names no apps. Give `apps`, one entry per Lambder instance: { module, exportName, and the files it is written to }.");
+    }
+    for (const [name, app] of Object.entries(apps)) {
+        if (app === null || typeof app !== "object")
+            throw new Error(`generateApiFiles: the app "${name}" is not an object.`);
+        const unknownKeys = Object.keys(app).filter((key) => !APP_KEYS.includes(key));
+        if (unknownKeys.length)
+            throw new Error(`generateApiFiles: the app "${name}" has ${unknownKeys.map((key) => `"${key}"`).join(", ")}, which the generator does not read (it reads ${APP_KEYS.join(", ")}).`);
+        if (!app.module)
+            throw new Error(`generateApiFiles: the app "${name}" names no module to read its instance from.`);
+        if (!FILE_KINDS.some((kind) => app[kind] !== undefined)) {
+            throw new Error(`generateApiFiles: the app "${name}" is written to no file; give it a contract, signatures, options or guardParams.`);
+        }
+    }
+}
+/** A writer's run as lines: its own on success or a stale check, the reason when it threw. */
+const settle = async (label, write) => {
+    try {
+        return await write();
+    }
+    catch (err) {
+        const reasons = [];
+        for (let cause = err; cause instanceof Error && reasons.length < 4; cause = cause.cause)
+            reasons.push(cause.message);
+        return { ok: false, lines: [`✗ ${label} failed: ${reasons.join(": ") || String(err)}`] };
+    }
+};
+/**
+ * Writes every file the config names, or with `check` writes nothing and
+ * answers whether each one on disk is current. Paths are relative to the
+ * working directory, as each writer takes them.
+ *
+ * ```ts
+ * import { generateApiFiles } from "lambder/build";
+ *
+ * const result = await generateApiFiles({
+ *     apps: {
+ *         server: {
+ *             module: "backend/index.ts",
+ *             exportName: "lambder",
+ *             contract: { file: "shared/generated/apiContract.generated.ts" },
+ *             signatures: { file: "shared/generated/apiSignatures.generated.ts" },
+ *         },
+ *     },
+ * }, { check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ */
+export const generateApiFiles = async (config, options = {}) => {
+    assertConfig(config);
+    const check = options.check ?? false;
+    const apps = Object.entries(config.apps);
+    const runs = [];
+    // The contracts first: they compile the app's sources and run none of
+    // them, so a module that fails to load still gets its contract checked.
+    for (const [name, app] of apps) {
+        if (!app.contract)
+            continue;
+        runs.push(await settle(`${name}: the contract`, () => writeApiContract({ ...app.contract, module: app.module, exportName: app.exportName, tsconfig: app.tsconfig, check })));
+    }
+    // Then what is read off the instance itself, which importing the module
+    // builds once for all three.
+    for (const [name, app] of apps) {
+        const instance = { module: app.module, exportName: app.exportName, check };
+        if (app.signatures)
+            runs.push(await settle(`${name}: the signatures`, () => writeApiSignatures({ ...app.signatures, ...instance })));
+        if (app.options)
+            runs.push(await settle(`${name}: the options`, () => writeApiOptions({ ...app.options, ...instance })));
+        for (const guardFile of app.guardParams ?? []) {
+            runs.push(await settle(`${name}: the "${guardFile.guard}" guard parameters`, () => writeApiGuardParams({ ...guardFile, ...instance })));
+        }
+    }
+    return { ok: runs.every((run) => run.ok), lines: runs.flatMap((run) => run.lines) };
+};

package/dist/build/generatedTables.d.ts

@@ -2,7 +2,8 @@ import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEnt
 import { type LambderModuleLocation } from "./moduleLocation.js";
 /** What the generators read the options from: a Lambder instance, or anything else that reports them the same way. */
 export type LambderApiOptionsSource = {
-    apiOptionEntries(): LambderApiOptionEntries;
+    /** Asynchronous, since a Lambder instance loads its lazy groups before it can report every endpoint. */
+    apiOptionEntries(): Promise<LambderApiOptionEntries> | LambderApiOptionEntries;
 };
 /** Which names of one table moved: entries that changed, entries the file did not have, entries the file had and the instance no longer reports. */
 export type LambderNameChanges = {

package/dist/build/generatedTables.js

@@ -16,7 +16,7 @@ export const loadApiOptionEntries = async (location, generator) => {
     if (typeof source?.apiOptionEntries !== "function") {
         throw new Error(`${moduleUrl} has no export "${exportName}" that reports API options: name the export holding the instance in exportName`);
     }
-    return source.apiOptionEntries();
+    return await source.apiOptionEntries();
 };
 /** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
 export const readGeneratedTable = (contents, exportName) => {

package/dist/build.d.ts

@@ -5,7 +5,8 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources. Node-only and imported by nothing else
+ * from the server's sources; and generateApiFiles, every one of them for
+ * every app a script names, in one call. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
@@ -17,4 +18,6 @@ export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
 export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
 export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
+export { generateApiFiles } from "./build/generateApiFiles.js";
+export type { LambderApiFilesConfig, LambderApiFilesApp, LambderApiFilesResult } from "./build/generateApiFiles.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -5,10 +5,12 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources. Node-only and imported by nothing else
+ * from the server's sources; and generateApiFiles, every one of them for
+ * every app a script names, in one call. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export { writeApiOptions } from "./build/writeApiOptions.js";
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+export { generateApiFiles } from "./build/generateApiFiles.js";

package/dist/client/LambderCaller.d.ts

@@ -5,6 +5,7 @@ import { type LambderApiOutcome, type LambderValidationError } from '../shared/w
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from '../shared/wire/LambderCallOptions.js';
 import { type LambderApiTransport } from '../shared/transport/LambderApiTransport.js';
 import { type LambderApiSignatureMap } from '../shared/wire/LambderApiSignatureMap.js';
+import { type LambderContractActionOf, type LambderContractGroupsOf, type LambderContractNamesInGroup } from '../shared/wire/LambderApiGroupCalls.js';
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
 export type { LambderProvidedGuardInputs, LambderGuardInputsProvider } from '../shared/wire/LambderCallOptions.js';
 /** A handler told that something happened, with nothing to hand it. */
@@ -110,40 +111,23 @@ type LambderCallerBaseOptions<TMessage extends LambderUncheckedRefusalMessage =
 /** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
 export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions<LambderContractAnyRefusalMessage<TContract>> & LambderGuardInputsProviderOption<TContract, TProvided>;
 /**
+ * The caller itself, before the groups: what LambderCaller is, less the
+ * endpoints it reaches by group (LambderCallerGroupCalls), which the
+ * constructor adds.
+ *
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
  */
-export default class LambderCaller<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> {
-    private apiPath;
-    private apiVersion?;
-    private apiSignatures?;
-    private timeoutMs?;
+declare class LambderCallerCore<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> {
+    #private;
     /** The calls currently in flight, in the order they started. */
     fetchTrackerList: FetchTracker[];
     /** Whether any call is in flight. Derived from the list, so the two cannot drift apart. */
     get isLoading(): boolean;
-    private versionExpiredHandler?;
-    private sessionExpiredHandler?;
-    private refusalHandler?;
-    private notAuthorizedHandler?;
-    private errorHandler?;
-    private apiInputValidationErrorHandler?;
-    private logListHandler?;
-    private fetchStartedHandler?;
-    private fetchEndedHandler?;
-    private guardInputsProvider?;
-    private sessionTokenCookieKey;
-    private sessionCsrfCookieKey;
-    private sessionCookieDomain?;
-    private requestCompression;
-    private transport;
     constructor(options: LambderCallerOptions<TContract, TProvidedGuards>);
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
     /** Replaces how calls reach the server: a mock runtime, an in-process handler, a decorated transport. */
     setTransport(transport: LambderApiTransport): this;
-    private clearSessionCookies;
-    /** One call, one outcome. Never throws; every failure path resolves to { ok: false }. */
-    private dispatch;
     /**
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to undefined. Never throws. A
@@ -164,3 +148,32 @@ export default class LambderCaller<TContract extends LambderApiContractShape = a
      */
     api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TApiName>>>): Promise<LambderContractOutputOf<TContract, TApiName> | undefined>;
 }
+/**
+ * One endpoint as a caller hands it out on its group: called, it is `api`
+ * for that endpoint (the output, or undefined on a failure); `.outcome` is
+ * `apiOutcome` (the full outcome, never throwing).
+ */
+export type LambderCallerEndpoint<TContract, TName extends keyof TContract & string, TProvidedGuards extends string> = {
+    (...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TName>>>): Promise<LambderContractOutputOf<TContract, TName> | undefined>;
+    outcome(...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TName>>>): Promise<LambderApiOutcome<LambderContractOutputOf<TContract, TName>, LambderContractRefusalMessage<TContract, TName>>>;
+};
+/** Every endpoint of a contract, by group: `caller.orders.place(input)`. */
+export type LambderCallerGroupCalls<TContract, TProvidedGuards extends string> = {
+    readonly [TGroup in LambderContractGroupsOf<TContract>]: {
+        readonly [TName in LambderContractNamesInGroup<TContract, TGroup> as LambderContractActionOf<TName>]: LambderCallerEndpoint<TContract, TName, TProvidedGuards>;
+    };
+};
+/**
+ * A typed client of a Lambder app: `caller.orders.place(input)` for the
+ * endpoint `orders.place`, `caller.orders.place.outcome(input)` for its full
+ * outcome, and `caller.api("orders.place", input)` for code that has the
+ * name as a value.
+ */
+type LambderCaller<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> = LambderCallerCore<TContract, TProvidedGuards> & LambderCallerGroupCalls<TContract, TProvidedGuards>;
+/** The caller's own members, without the groups: what a wrapper of a caller (the test visitor) types its `api` and `apiOutcome` by. */
+export type LambderCallerMembers<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> = LambderCallerCore<TContract, TProvidedGuards>;
+declare const LambderCaller: {
+    new <TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never>(options: LambderCallerOptions<TContract, TProvidedGuards>): LambderCaller<TContract, TProvidedGuards>;
+    readonly prototype: LambderCallerCore<any, any>;
+};
+export default LambderCaller;