lambder 7.3.1 → 8.1.1

package/dist/shared/wire/LambderApiRefusal.d.ts

@@ -3,9 +3,9 @@ export type LambderApiRefusalOptions = {
     /**
      * User-facing failure detail placed on the API envelope's `errorMessage`
      * field: a refusal message (`{ type: "warning", content: "..." }`, with
-     * an app's own `code`) or a plain string. Defaults to the error message
-     * string, so a bare `throw new LambderApiRefusal("...")` is still
-     * visible to the client.
+     * an app's own `code`) or a plain string, which becomes an "error"
+     * message with that content. Defaults to the error message, so a bare
+     * `throw new LambderApiRefusal("...")` is still visible to the client.
      */
     errorMessage?: LambderAppRefusalMessage | string;
     /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
@@ -26,18 +26,18 @@ export type LambderApiRefusalOptions = {
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers that have no access to the per-request resolver)
- * and the render pipeline maps it onto the structured API envelope
+ * hooks, or nested helpers with no access to the per-request resolver) and
+ * the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler. Refusals therefore never reach
- * crash logging, and clients receive a parseable response they can surface.
+ * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any
  * other error: global error handler, then the default 500.
  *
  * Isomorphic and dependency-free, so shared code (validators, permission
- * checks) may import and throw it from packages used by both server and
- * browser builds; in the browser it is just an Error.
+ * checks) used by both server and browser builds may throw it; in the
+ * browser it is just an Error.
  */
 export declare class LambderApiRefusal extends Error {
     /**
@@ -46,7 +46,8 @@ export declare class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     readonly isLambderApiRefusal = true;
-    readonly errorMessage?: LambderAppRefusalMessage | string;
+    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
+    readonly errorMessage: LambderAppRefusalMessage;
     readonly notAuthorized?: boolean;
     readonly sessionExpired?: boolean;
     readonly statusCode?: LambderHttpStatusCode;
@@ -59,11 +60,11 @@ export declare const isLambderApiRefusal: (err: unknown) => err is LambderApiRef
  * The standard shape refusals carry on the envelope's errorMessage field.
  * `code` is the refusal's machine-readable identity: clients branch and
  * translate on it and never string-match `content`, which stays the
- * human-readable fallback for codes a client does not know yet. Apps keep
- * their own typed code vocabulary; the framework's own refusals carry a
- * LambderRefusalCode. The caller's errorMessageHandler receives the object
- * as-is, typed as LambderAppRefusalMessage or a plain string; an app's own
- * vocabulary goes in `code`.
+ * human-readable fallback for codes a client does not know yet. The
+ * framework's own refusals carry a LambderRefusalCode; apps put their own
+ * typed vocabulary in `code`. The caller's errorMessageHandler receives the
+ * object as-is, typed as LambderAppRefusalMessage; a server that wrote a
+ * plain string reaches it as `{ type: "error", content }` (refusalMessageOf).
  */
 export type LambderRefusalMessage<TAppCode extends string = never> = {
     type: "warning" | "error" | "info";
@@ -71,14 +72,13 @@ export type LambderRefusalMessage<TAppCode extends string = never> = {
      * Machine-readable identity of the refusal: a LambderRefusalCode, plus
      * whatever vocabulary the reader names in TAppCode.
      *
-     * Parameterized rather than widened with `string & {}`, because a union
-     * with `string` in it does not narrow: inside a `switch(message.code)`
-     * the case was not assignable and the `default: never` assertion failed,
-     * which is exactly the exhaustiveness the codes exist for. A client that
-     * reads its own vocabulary declares it
-     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a switch
-     * that is checked; a value an app WRITES takes LambderAppRefusalMessage,
-     * where any code is welcome.
+     * Parameterized rather than widened with `string & {}`: a union with
+     * `string` in it does not narrow, so a `switch(message.code)` could not
+     * end in a `default: never` exhaustiveness check, which is what the codes
+     * exist for. A client that reads its own vocabulary declares it
+     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a checked
+     * switch; a value an app WRITES takes LambderAppRefusalMessage, where any
+     * code is welcome.
      */
     code?: LambderRefusalCode | TAppCode;
     title?: string;
@@ -86,12 +86,22 @@ export type LambderRefusalMessage<TAppCode extends string = never> = {
 };
 /**
  * The refusal shape an app authors: any code, with the framework's own still
- * autocompleting. What every option that takes a message from an app is
- * typed as (a rate-limit policy's errorMessage, the mock's failure
- * injection); LambderRefusalMessage itself defaults to the framework's codes
- * alone, so a reader's switch over it is exhaustive.
+ * autocompleting. Every option that takes a message from an app is typed as
+ * this (a rate-limit policy's errorMessage, the mock's failure injection);
+ * LambderRefusalMessage itself defaults to the framework's codes alone, so a
+ * reader's switch over it is exhaustive.
  */
 export type LambderAppRefusalMessage = LambderRefusalMessage<string & {}>;
+/**
+ * An errorMessage as the one shape a reader handles: a plain string becomes
+ * an "error" message with that content, and a value that is not a message
+ * at all becomes one describing it. The envelope writer applies it, so a
+ * Lambder server only ever sends the object. A reader applies it too,
+ * because what it reads is wire input no server vouches for: a hand-built
+ * mock answer (an MSW handler, a test double) or a proxy that wrote its own
+ * body can put anything there.
+ */
+export declare const refusalMessageOf: (message: unknown) => LambderAppRefusalMessage;
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -103,6 +113,8 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly rateLimited: "lambder/rate-limited";
     /** The original of an idempotent request is still processing (409). */
     readonly duplicateInFlight: "lambder/duplicate-in-flight";
+    /** The idempotencyKey was already used for a request with a different payload (409). */
+    readonly idempotencyKeyReused: "lambder/idempotency-key-reused";
     /** The idempotencyKey is malformed (400). */
     readonly invalidIdempotencyKey: "lambder/invalid-idempotency-key";
     /** No API is registered under the requested name. */
@@ -111,6 +123,12 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly invalidRequestPayload: "lambder/invalid-request-payload";
     /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
     readonly notMocked: "lambder/not-mocked";
+    /** An upload bucket would not sign a ticket for a file with no bytes. */
+    readonly uploadEmpty: "lambder/upload-empty";
+    /** An upload bucket would not sign a ticket for a content type the rule does not accept. */
+    readonly uploadTypeRejected: "lambder/upload-type-rejected";
+    /** An upload bucket would not sign a ticket for a file larger than the rule accepts. */
+    readonly uploadTooLarge: "lambder/upload-too-large";
 };
 export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {

package/dist/shared/wire/LambderApiRefusal.js

@@ -1,18 +1,18 @@
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers that have no access to the per-request resolver)
- * and the render pipeline maps it onto the structured API envelope
+ * hooks, or nested helpers with no access to the per-request resolver) and
+ * the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler. Refusals therefore never reach
- * crash logging, and clients receive a parseable response they can surface.
+ * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any
  * other error: global error handler, then the default 500.
  *
  * Isomorphic and dependency-free, so shared code (validators, permission
- * checks) may import and throw it from packages used by both server and
- * browser builds; in the browser it is just an Error.
+ * checks) used by both server and browser builds may throw it; in the
+ * browser it is just an Error.
  */
 export class LambderApiRefusal extends Error {
     /**
@@ -21,6 +21,7 @@ export class LambderApiRefusal extends Error {
      * across them while this marker does not. The pipeline checks the brand.
      */
     isLambderApiRefusal = true;
+    /** What the envelope's errorMessage carries: always a message object, a plain string given to the options made into one. */
     errorMessage;
     notAuthorized;
     sessionExpired;
@@ -29,7 +30,7 @@ export class LambderApiRefusal extends Error {
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = "LambderApiRefusal";
-        this.errorMessage = options.errorMessage ?? message;
+        this.errorMessage = refusalMessageOf(options.errorMessage ?? message);
         this.notAuthorized = options.notAuthorized;
         this.sessionExpired = options.sessionExpired;
         this.statusCode = options.statusCode;
@@ -38,6 +39,32 @@ export class LambderApiRefusal extends Error {
 }
 /** Brand-based type guard (see LambderApiRefusal.isLambderApiRefusal). */
 export const isLambderApiRefusal = (err) => err instanceof Error && err.isLambderApiRefusal === true;
+const REFUSAL_MESSAGE_TYPES = ["warning", "error", "info"];
+/**
+ * An errorMessage as the one shape a reader handles: a plain string becomes
+ * an "error" message with that content, and a value that is not a message
+ * at all becomes one describing it. The envelope writer applies it, so a
+ * Lambder server only ever sends the object. A reader applies it too,
+ * because what it reads is wire input no server vouches for: a hand-built
+ * mock answer (an MSW handler, a test double) or a proxy that wrote its own
+ * body can put anything there.
+ */
+export const refusalMessageOf = (message) => {
+    if (message !== null && typeof message === "object" && typeof message.content === "string") {
+        const candidate = message;
+        return REFUSAL_MESSAGE_TYPES.includes(candidate.type) ? candidate : { ...candidate, type: "error" };
+    }
+    if (typeof message === "string")
+        return { type: "error", content: message };
+    let content;
+    try {
+        content = JSON.stringify(message) ?? String(message);
+    }
+    catch {
+        content = String(message);
+    }
+    return { type: "error", content };
+};
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -49,6 +76,8 @@ export const LAMBDER_REFUSAL_CODES = {
     rateLimited: "lambder/rate-limited",
     /** The original of an idempotent request is still processing (409). */
     duplicateInFlight: "lambder/duplicate-in-flight",
+    /** The idempotencyKey was already used for a request with a different payload (409). */
+    idempotencyKeyReused: "lambder/idempotency-key-reused",
     /** The idempotencyKey is malformed (400). */
     invalidIdempotencyKey: "lambder/invalid-idempotency-key",
     /** No API is registered under the requested name. */
@@ -57,6 +86,12 @@ export const LAMBDER_REFUSAL_CODES = {
     invalidRequestPayload: "lambder/invalid-request-payload",
     /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
     notMocked: "lambder/not-mocked",
+    /** An upload bucket would not sign a ticket for a file with no bytes. */
+    uploadEmpty: "lambder/upload-empty",
+    /** An upload bucket would not sign a ticket for a content type the rule does not accept. */
+    uploadTypeRejected: "lambder/upload-type-rejected",
+    /** An upload bucket would not sign a ticket for a file larger than the rule accepts. */
+    uploadTooLarge: "lambder/upload-too-large",
 };
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid

package/dist/shared/wire/LambderApiSignature.d.ts

@@ -6,9 +6,8 @@ import type { z } from "zod";
  * the digest of its client-facing shape (apiSignatureOf, computed on the
  * server side). A caller given the map sends the value with every call, and
  * the server answers versionExpired when it differs from the digest of what
- * it serves now. So a client built against an endpoint that has since
- * changed reloads, while one whose endpoint is unchanged keeps working
- * across deploys.
+ * it serves, so a client reloads only when an endpoint it calls has changed
+ * and otherwise keeps working across deploys.
  *
  * Keys are hashed so the map lists no endpoint names: the names a client
  * calls are in its own code already, and the rest of the surface stays out
@@ -26,14 +25,12 @@ export declare const API_SIGNATURE_HEX_LENGTH = 16;
  * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
  * WebCrypto's digest is, and it is the only SHA-256 a browser has.
  *
- * Computed on the spot, every time, and nothing is kept. The digest that
- * actually describes an endpoint is the generator's, computed once at build
- * time; what is left here is one hash of a short name against a map already
- * in memory, which is nothing beside the request it belongs to. A cache of
- * it would have to be keyed by name, and on the server the name comes off
- * the wire before anything has checked that it is an endpoint at all, so it
- * would grow by an entry for every name a request cared to invent and never
- * shrink.
+ * Computed on the spot every time, with nothing kept. The digest that
+ * describes an endpoint is the generator's, computed once at build time;
+ * this is one hash of a short name, nothing beside the request it belongs
+ * to. A cache would be keyed by name, and on the server the name comes off
+ * the wire before anything checks that it is an endpoint, so the cache would
+ * gain an entry for every name a request cared to invent and never shrink.
  */
 export declare const apiNameKeyOf: (apiName: string) => Promise<string>;
 /** The map's signature for one endpoint, or null when the map holds none for it. */
@@ -59,23 +56,22 @@ export declare const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
  * widely returned payload (a session, a profile) then reloads only the
  * clients that send the list back, not every client that reads it.
  *
- * Where the enum is input its values still count: a value dropped from the
- * list is a request an older client may still send and the server now
- * refuses, so that endpoint's clients must reload. Everything else about the
- * schema is untouched: its type, its validation on both sides, and what it
- * is everywhere outside the digest.
+ * Where the enum is input its values still count: an older client may still
+ * send a value dropped from the list, which the server would refuse, so that
+ * endpoint's clients must reload. Everything else about the schema is
+ * untouched: its type, its validation on both sides, and what it is outside
+ * the digest.
  *
  * The mark is a promise the schema makes for its readers, and nothing checks
  * it. A client that switches over every value with no fallback, or indexes a
- * map by one, renders a value it does not know as nothing, or throws. Mark
- * only a list every reader handles that way on purpose.
+ * map by one, renders an unknown value as nothing, or throws. Mark only a
+ * list whose every reader handles an unknown value on purpose.
  *
  * It is zod metadata (`.meta()`), which zod keeps in one registry on
  * globalThis, so an enum marked in a shared package is read by the digest
- * even when the server resolves another copy of zod. A schema derived from a
- * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
- * carries no mark and counts in full, which costs a reload, never a missed
- * one.
+ * even when the server resolves another copy of zod. A schema rebuilt from a
+ * marked enum (`z.enum(marked.options)`, `.exclude()`) carries no mark and
+ * counts in full, which costs a reload, never a missed one.
  *
  * @example
  * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));

package/dist/shared/wire/LambderApiSignature.js

@@ -12,14 +12,12 @@ const API_NAME_KEY_PREFIX = "lambder-api-name:";
  * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
  * WebCrypto's digest is, and it is the only SHA-256 a browser has.
  *
- * Computed on the spot, every time, and nothing is kept. The digest that
- * actually describes an endpoint is the generator's, computed once at build
- * time; what is left here is one hash of a short name against a map already
- * in memory, which is nothing beside the request it belongs to. A cache of
- * it would have to be keyed by name, and on the server the name comes off
- * the wire before anything has checked that it is an endpoint at all, so it
- * would grow by an entry for every name a request cared to invent and never
- * shrink.
+ * Computed on the spot every time, with nothing kept. The digest that
+ * describes an endpoint is the generator's, computed once at build time;
+ * this is one hash of a short name, nothing beside the request it belongs
+ * to. A cache would be keyed by name, and on the server the name comes off
+ * the wire before anything checks that it is an endpoint, so the cache would
+ * gain an entry for every name a request cared to invent and never shrink.
  */
 export const apiNameKeyOf = async (apiName) => (await sha256HexOf(API_NAME_KEY_PREFIX + apiName)).slice(0, API_SIGNATURE_HEX_LENGTH);
 /** The map's signature for one endpoint, or null when the map holds none for it. */
@@ -57,23 +55,22 @@ export const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
  * widely returned payload (a session, a profile) then reloads only the
  * clients that send the list back, not every client that reads it.
  *
- * Where the enum is input its values still count: a value dropped from the
- * list is a request an older client may still send and the server now
- * refuses, so that endpoint's clients must reload. Everything else about the
- * schema is untouched: its type, its validation on both sides, and what it
- * is everywhere outside the digest.
+ * Where the enum is input its values still count: an older client may still
+ * send a value dropped from the list, which the server would refuse, so that
+ * endpoint's clients must reload. Everything else about the schema is
+ * untouched: its type, its validation on both sides, and what it is outside
+ * the digest.
  *
  * The mark is a promise the schema makes for its readers, and nothing checks
  * it. A client that switches over every value with no fallback, or indexes a
- * map by one, renders a value it does not know as nothing, or throws. Mark
- * only a list every reader handles that way on purpose.
+ * map by one, renders an unknown value as nothing, or throws. Mark only a
+ * list whose every reader handles an unknown value on purpose.
  *
  * It is zod metadata (`.meta()`), which zod keeps in one registry on
  * globalThis, so an enum marked in a shared package is read by the digest
- * even when the server resolves another copy of zod. A schema derived from a
- * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
- * carries no mark and counts in full, which costs a reload, never a missed
- * one.
+ * even when the server resolves another copy of zod. A schema rebuilt from a
+ * marked enum (`z.enum(marked.options)`, `.exclude()`) carries no mark and
+ * counts in full, which costs a reload, never a missed one.
  *
  * @example
  * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));

package/dist/shared/wire/LambderCallOptions.d.ts

@@ -1,14 +1,14 @@
 /**
- * The per-call options both callers take, the contract-driven typing of a
- * call's arguments, and the runtime merge of guard inputs, shared by the
- * browser caller (LambderCaller) and the server-side invoke caller
- * (LambderInvokeCaller). Both speak the same envelope to the same kind of
- * contract, so what an API demands of its caller (a guardInput-mode guard's
- * value, say) is decided here once and the two callers cannot drift on it.
- * Pure types and one dependency-free function, so the browser entry resolves
- * it.
+ * The per-call options, the contract-driven typing of a call's arguments, and
+ * the runtime merge of guard inputs, shared by the browser caller
+ * (LambderCaller) and the server-side invoke caller (LambderInvokeCaller).
+ * Both speak the same envelope to the same kind of contract, so what an API
+ * demands of its caller (a guardInput-mode guard's value, say) is decided
+ * here once and the two cannot drift. Pure types and one dependency-free
+ * function, so the browser entry resolves it.
  */
 import type { LambderContractIdempotencyOf } from "./LambderApiContract.js";
+import type { LambderIdempotencyKeyScope } from "./LambderIdempotencyKeyScope.js";
 type IsAny<T> = 0 extends (1 & T) ? true : false;
 /**
  * The options every call takes, whichever caller sends it. Each caller adds
@@ -40,19 +40,22 @@ export type LambderSharedCallOptions = {
     /**
      * Replay-protection key for APIs declared idempotent on the server.
      * Generate once per logical operation with
-     * LambderCaller.createIdempotencyKey() and send the same key on retries:
+     * createIdempotencyKey() and send the same key on retries:
      * duplicates of an in-flight request refuse, and repeats of a completed
      * one replay its stored response instead of re-executing. Must be
      * UNGUESSABLE random (it scopes the replay record for logged-out clients)
      * and at least 16 characters; the server refuses shorter keys with a 400.
      *
-     * The typed contract makes this REQUIRED for an API whose entry declares
-     * `idempotency`, the way it does for guardInput values: a server
-     * declaration that reads as protection and silently provides none (the
-     * server runs a keyless call, which dedupes nothing) is exactly what the
-     * typed caller is for.
+     * REQUIRED by the typed contract for an API that declares `idempotency`,
+     * since the server runs a keyless call unprotected.
+     *
+     * A key scope (createIdempotencyKeyScope()) is the easier
+     * form: it rotates once an answer settles the operation, so a retry after
+     * a dropped connection reuses the key and the next attempt (a corrected
+     * form after a refusal included) gets a new one. See
+     * LambderIdempotencyKeyScope for which answers settle it.
      */
-    idempotencyKey?: string;
+    idempotencyKey?: string | LambderIdempotencyKeyScope;
 };
 /** The payload type one API of a contract takes; `any` for an untyped caller or a name the contract does not know. */
 type LambderContractInputOf<TContract, TApiName> = IsAny<TContract> extends true ? any : TApiName extends keyof TContract ? TContract[TApiName] extends {
@@ -80,12 +83,12 @@ export type LambderProvidedGuardInputs<TContract, TProvided extends string> = Is
 };
 /**
  * Supplies guardInputs for every call from one place (the organization the
- * UI is on, a device token), keyed by guard name; per-call guardInputs
- * merge on top. Name the guards it covers in the caller's second type
- * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
- * APIs whose guardInput guards are all covered do not require the
- * options argument. May be async; a throw fails the call as an unknown
- * error before anything is sent.
+ * UI is on, a device token), keyed by guard name; per-call guardInputs merge
+ * on top. Name the guards it covers in the caller's second type parameter,
+ * `new LambderCaller<Contract, "orgPermission">`, and calls to APIs whose
+ * guardInput guards are all covered do not require the options argument.
+ * May be async; a throw fails the call as an unknown error before anything
+ * is sent.
  */
 export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
 /** Optional until the caller names provided guards: naming them without a provider would send nothing. */
@@ -117,11 +120,10 @@ type ContractGuardInputsField<TEntry, TProvided extends string> = [
  *
  * Read as "required unless it says false" rather than "required only when it
  * says true", so an entry whose option widened to `boolean` (declared through
- * a spread, or built in a helper) keeps the requirement instead of quietly
- * losing its compile-time half.
+ * a spread, or built in a helper) keeps the requirement at compile time.
  */
 type ContractIdempotencyKeyField<TContract, TApiName> = TApiName extends keyof TContract ? [LambderContractIdempotencyOf<TContract, TApiName>] extends [never] ? {} : [LambderContractIdempotencyOf<TContract, TApiName>] extends [false] ? {} : {
-    idempotencyKey: string;
+    idempotencyKey: string | LambderIdempotencyKeyScope;
 } : {};
 /**
  * What the contract adds to one call's options: the guardInputs field and the
@@ -131,41 +133,30 @@ type ContractCallFields<TContract, TApiName, TProvided extends string> = TApiNam
 /**
  * The options argument of one call: optional normally, REQUIRED when the
  * contract demands something of it, so forgetting a guard's value or an
- * idempotent API's key is a compile error at the call site rather than a 422
- * from the server or a replay that never happens. TOptions is the caller's own
- * per-call options type; the contract's fields are layered on top of it.
- *
- * `{} extends TFields` is the question "is every field the contract added
- * optional": an empty object is assignable to a type whose properties are all
- * optional and to nothing else.
+ * idempotent API's key is a compile error rather than a 422 or a replay that
+ * never happens. TOptions is the caller's own per-call options type.
+ * `{} extends TFields` asks "is every field the contract added optional".
  */
 type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
     guardInputs?: Record<string, unknown>;
 }> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? ContractCallFields<TContract, TApiName, TProvided> extends infer TFields ? {} extends TFields ? [options?: TOptions & TFields] : [options: TOptions & TFields] : never : [options?: TOptions];
 /**
  * Everything one call passes after the API name: the payload, then the
- * options, both decided by the contract.
- *
- * The payload is optional only when the API's input accepts undefined, so
- * `caller.api("getUser")` against `input: { id: string }` is a compile error
- * at the call site rather than a 422 from the server. Building it as one rest
- * tuple is what makes that possible: a plain optional parameter cannot be
- * made mandatory by a later type, and TypeScript has no per-argument
- * conditional otherwise.
- *
- * When the options argument is itself mandatory (an uncovered guardInput
- * guard, an idempotent API's key), the payload cannot stay optional in front
- * of it, since a tuple's required element may not follow an optional one.
- * Such a call passes its payload explicitly, `undefined` included.
+ * options, both decided by the contract. The payload is optional only when
+ * the API's input accepts undefined, so `caller.api("getUser")` against
+ * `input: { id: string }` fails to compile rather than drawing a 422. That
+ * needs one rest tuple, since TypeScript has no other per-argument
+ * conditional. When the options are mandatory, the payload cannot stay
+ * optional before them (a tuple's required element may not follow an
+ * optional one), so such a call passes it explicitly, `undefined` included.
  */
 export type LambderCallArgs<TContract, TApiName, TProvided extends string, TOptions extends {
     guardInputs?: Record<string, unknown>;
 }> = LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options: infer TRequired] ? [payload: LambderContractInputOf<TContract, TApiName>, options: TRequired] : LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options?: infer TOptional] ? undefined extends LambderContractInputOf<TContract, TApiName> ? [payload?: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : [payload: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : never;
 /**
  * Provider values underneath, per-call values on top; undefined when neither
- * side supplied any. Synchronous on purpose: a caller awaits its provider
- * only when it has one, so a call without a provider still issues its
- * request in the same tick it was made.
+ * side supplied any. Synchronous so a call without a provider still issues
+ * its request in the same tick it was made.
  */
 export declare const mergeGuardInputs: (provided: Record<string, unknown> | undefined, perCall: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
 export {};

package/dist/shared/wire/LambderCallOptions.js

@@ -1,17 +1,15 @@
 /**
- * The per-call options both callers take, the contract-driven typing of a
- * call's arguments, and the runtime merge of guard inputs, shared by the
- * browser caller (LambderCaller) and the server-side invoke caller
- * (LambderInvokeCaller). Both speak the same envelope to the same kind of
- * contract, so what an API demands of its caller (a guardInput-mode guard's
- * value, say) is decided here once and the two callers cannot drift on it.
- * Pure types and one dependency-free function, so the browser entry resolves
- * it.
+ * The per-call options, the contract-driven typing of a call's arguments, and
+ * the runtime merge of guard inputs, shared by the browser caller
+ * (LambderCaller) and the server-side invoke caller (LambderInvokeCaller).
+ * Both speak the same envelope to the same kind of contract, so what an API
+ * demands of its caller (a guardInput-mode guard's value, say) is decided
+ * here once and the two cannot drift. Pure types and one dependency-free
+ * function, so the browser entry resolves it.
  */
 /**
  * Provider values underneath, per-call values on top; undefined when neither
- * side supplied any. Synchronous on purpose: a caller awaits its provider
- * only when it has one, so a call without a provider still issues its
- * request in the same tick it was made.
+ * side supplied any. Synchronous so a call without a provider still issues
+ * its request in the same tick it was made.
  */
 export const mergeGuardInputs = (provided, perCall) => provided !== undefined || perCall !== undefined ? { ...provided, ...perCall } : undefined;