lambder 11.0.1 → 12.0.1

package/dist/core/LambderCreateOptions.d.ts

@@ -173,7 +173,7 @@ export type LambderGuardsMap<TSessionData = any> = Record<string, LambderApiGuar
 export type LambderRateLimitPoliciesMap = Record<string, LambderApiRateLimitPolicyConfig<LambderRenderContext>>;
 /** The `rateLimits` option of create(): the engine's config, with `policies` as one map or a list of maps. */
 export type LambderCreateRateLimitsOption = Omit<LambderApiRateLimitsConfig<LambderRateLimitPoliciesMap>, "policies"> & {
-    /** Named policies referenced (typed) from addApi/addSessionApi: one map, or a list of maps merged in order. */
+    /** Named policies referenced (typed) from defineApi: one map, or a list of maps merged in order. */
     policies: LambderNamedMapsOption<LambderRateLimitPoliciesMap>;
 };
 /** The options as the instance holds them: the guards and the rate-limit policies merged into one map each. */
@@ -276,7 +276,7 @@ export type LambderCreateOptions<TSessionData = any> = {
     trustedHostHeaders?: readonly string[];
     /** CORS: true allows any origin; or pass a LambderCorsConfig. Default: off. */
     cors?: boolean | LambderCorsConfig;
-    /** Sessions over a store of your choosing; required for addSessionApi/addSessionRoute. */
+    /** Sessions over a store of your choosing; required for a guard that needs a session, and for addSessionRoute. */
     session?: LambderSessionOptions<TSessionData>;
     /**
      * Declarative per-API rate limiting: your limiter plus named policies APIs
@@ -318,58 +318,50 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     requireRefusalCodes?: boolean;
     /**
-     * Make an authorization declaration part of registering a session API:
-     * every addSessionApi must declare `guards`, at the type level (a missing
-     * `guards` is a compile error) and at registration (a plain-JS caller
-     * throws). An API whose session is the whole authorization (the
-     * signed-in user's own account) declares a named no-op session guard, so
-     * every opt-out is explicit and one grep lists them all. Needs a guards
-     * map to pick from. Default: false.
-     */
-    requireSessionApiGuards?: boolean;
-    /**
-     * The same for public APIs: every addApi must declare `guards`, at the
-     * type level and at registration.
+     * Make an authorization declaration part of declaring an endpoint: every
+     * defineApi must declare `guards`, at the type level (a missing `guards`
+     * is a compile error) and at registration (a plain-JS caller throws).
      *
-     * Public APIs are open by default, which is the right default, so this is
-     * off unless an app decides otherwise. Turned on, a public endpoint's
-     * openness becomes a written decision rather than an omission: the ones
-     * anybody may call declare a named no-op guard carrying the reason, and
-     * the ones that authorize their caller some other way (a signature, a
-     * device secret, a one-shot token) name where that happens. One grep over
-     * the guard names then lists every public door and why it is open. Needs
-     * a guards map to pick from. Default: false.
+     * An endpoint is open by default, which is the right default, so this is
+     * off unless an app decides otherwise. Turned on, every endpoint's
+     * authorization becomes a written decision rather than an omission: one
+     * anybody may call declares a named no-op guard carrying the reason, one
+     * whose session is the whole authorization (the signed-in user's own
+     * account) a named no-op session guard, and one that authorizes its
+     * caller some other way (a signature, a device secret, a one-shot token)
+     * names where that happens. One grep over the guard names then lists
+     * every door and why it opens. Needs a guards map to pick from. Default:
+     * false.
      */
-    requirePublicApiGuards?: boolean;
+    requireApiGuards?: boolean;
     /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
     idempotency?: LambderApiIdempotencyConfig;
     /** Crash reporting on every path, and who may read a crash in the answer. See LambderCrashOptions. */
     crashes?: LambderCrashOptions;
 };
 /**
- * What the `guards` field asks for when an API on a require*ApiGuards
+ * What the `guards` field asks for when an API on a requireApiGuards
  * instance declares none. With nothing to infer from, the inference parameter
  * defaults to `never`, and "Property 'guards' is missing ... but required in
  * type { guards: never }" would read as though nothing could be written
  * there; the property name says what is wanted.
  */
 type LambderGuardsDeclarationRequired = {
-    readonly "lambder: this instance requires every API of this kind to declare guards. Name the guard that authorizes this API, or the named no-op guard that records why anyone may call it.": never;
+    readonly "lambder: this instance requires every API to declare guards. Name the guard that authorizes this API, or the named no-op guard that records why it needs nothing more.": never;
 };
 /**
- * What addSessionApi and addSessionRoute need of the instance they are called
- * on. Nothing satisfies it without the session option, so registering a
- * session API on an instance that has no sessions is a compile error rather
- * than only the registration-time throw.
+ * What addSessionRoute needs of the instance it is called on. Nothing
+ * satisfies it without the session option, so registering a session route
+ * on an instance that has no sessions is a compile error rather than only a
+ * throw when it is first requested.
  */
 type LambderSessionOptionRequired = {
-    readonly "lambder: sessions are not configured on this instance. Pass the session option to create() before registering a session API or a session route.": never;
+    readonly "lambder: sessions are not configured on this instance. Pass the session option to create() before registering a session route.": never;
 };
 /**
- * Intersected into what addSessionApi and addSessionRoute take, so an
- * instance created without the session option refuses the registration at
- * the call site. `unknown` once sessions are configured, which intersects
- * away to nothing.
+ * Intersected into what addSessionRoute takes, so an instance created
+ * without the session option refuses the registration at the call site.
+ * `unknown` once sessions are configured, which intersects away to nothing.
  */
 export type LambderSessionEnabledInstance<TSessionsEnabled extends boolean> = TSessionsEnabled extends true ? unknown : LambderSessionOptionRequired;
 /**
@@ -412,11 +404,8 @@ type LambderRateLimitSliceCheck<TLacking> = [TLacking] extends [never] ? unknown
 };
 /**
  * The `guards` field of an API's options: optional by default, required once
- * create() received the require*ApiGuards flag for that kind of API, so that
- * an authorization declaration cannot be forgotten at the type level.
- *
- * One type for both kinds: the requirement is the same shape either way, and
- * only which flag switches it on differs.
+ * create() received requireApiGuards, so that an authorization declaration
+ * cannot be forgotten at the type level.
  */
 export type LambderRequirableGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
     /** Named guards, run in declared order before input validation (after it for a guard declared runAt: "afterInputValidation"): a name, a non-empty list of names, or a non-empty { name: param } map for parameterized guards. Required on this instance: an API that needs no authorization declares a named no-op guard, so every opt-out is explicit and one grep lists them all. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */

package/dist/core/LambderCreateOptions.js

@@ -53,8 +53,7 @@ export const assertCreateOptions = (options) => {
     if (options.requireRefusalCodes && !vocabulary) {
         throw new Error("Lambder: requireRefusalCodes needs a refusals vocabulary to name codes from; declare one with initLambder().declareRefusals().");
     }
-    if ((options.requireSessionApiGuards || options.requirePublicApiGuards) && !options.guards) {
-        const requireFlag = options.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
-        throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);
+    if (options.requireApiGuards && !options.guards) {
+        throw new Error("Lambder: requireApiGuards needs a guards map at creation for APIs to declare from.");
     }
 };

package/dist/core/LambderPublicFiles.d.ts

@@ -13,7 +13,14 @@ export type LambderPublicFilesOptions = {
      * mapper. Return null/undefined to skip. Default: the file path as it is.
      */
     path?: (ctx: LambderRenderContext, filePath: string) => string | null | undefined;
-    /** Cache-Control for served files; the function receives the relative file path. Default: "public, max-age=3600". */
+    /**
+     * Cache-Control for served files that do not match immutablePattern; the
+     * function receives the relative file path. Default: "no-cache". Such a
+     * file keeps its name when its bytes change (a service worker, a web
+     * manifest, a favicon), so a shared cache holding it for a while serves
+     * the old copy after a deploy; revalidating instead costs a 304, since
+     * every GET or HEAD 200 carries an ETag.
+     */
     cacheControl?: string | ((ctx: LambderRenderContext, relativePath: string) => string);
     /** Relative paths matching this get immutableCacheControl. Default: content-hashed names in a bundler's output folder (assets/, static/, _next/static/). Set false to disable. */
     immutablePattern?: RegExp | false;

package/dist/core/LambderPublicFiles.js

@@ -29,7 +29,7 @@ const EXACT_BUNDLER_HASH = "-(?=[\\w-]{0,7}[a-z])(?:(?=[\\w-]{0,7}[A-Z])(?=[\\w-
 const LONG_BUNDLER_HASH = "[-.](?=\\w*[A-Za-z])(?=\\w*\\d)\\w{8,}";
 const DEFAULT_IMMUTABLE_PATTERN = new RegExp(`(?:^|/)_next/static/|(?:^|/)(?:assets|static)/(?:[^/]+/)*[^/]*(?:${EXACT_BUNDLER_HASH}|${LONG_BUNDLER_HASH})(?:\\.chunk)?\\.[A-Za-z0-9]+$`);
 const DEFAULT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
-const DEFAULT_CACHE_CONTROL = "public, max-age=3600";
+const DEFAULT_CACHE_CONTROL = "no-cache";
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered

package/dist/index.d.ts

@@ -2,8 +2,12 @@ import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export type { LambderCreatedHook } from './core/Lambder.js';
+export type { LambderAppTypes, LambderPlainAppTypes, LambderApiDeclaration, LambderApiDeclarations, LambderApiGroup, LambderLazyApiGroup, LambderRegistrableApiGroup, LambderApiModeOf, LambderEntryOf, LambderContractOfGroups, } from './api/LambderApiDeclarations.js';
+export { apiCallPath, apiNameOfCallPath, splitApiName, isGroupName, isActionName, LAMBDER_API_NAME_SEGMENT, LAMBDER_CALLER_MEMBER_NAMES, LAMBDER_RESERVED_GROUP_NAMES, LAMBDER_RESERVED_ACTION_NAMES, } from './shared/wire/LambderApiNames.js';
+export type { LambderReservedGroupName, LambderReservedActionName } from './shared/wire/LambderApiNames.js';
+export type { LambderContractGroupsOf, LambderContractNamesInGroup, LambderContractActionOf } from './shared/wire/LambderApiGroupCalls.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderLogListHandler } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderLogListHandler, LambderCallerEndpoint, LambderCallerGroupCalls, LambderCallerMembers } from "./client/LambderCaller.js";
 export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 export { lambderFetchTransport } from "./client/lambderFetchTransport.js";
@@ -46,7 +50,7 @@ export { checkedRefusal } from "./api/LambderApiRefusals.js";
 export { LambderInvokeError, isLambderInvokeError } from "./invoke/LambderInvokeOutcome.js";
 export type { LambderInvokeOutcome, LambderInvokeFailure, LambderInvokeValidationFailure, LambderInvokeCrashFailure, LambderInvokePayloadTooLargeFailure, LambderInvokeEnvelopeFailure, LambderInvokeDeliveryFailure, LambderInvokeFailureReason, LambderInvokeFunctionError, } from "./invoke/LambderInvokeOutcome.js";
 export { default as LambderInvokeCaller, LAMBDER_INVOKE_MAX_EVENT_BYTES, } from "./invoke/LambderInvokeCaller.js";
-export type { LambderInvokeCallerOptions, LambderInvokeCallOptions, LambderInvokeFailureHandler, LambderInvokeLogListHandler, LambderInvokeTransport, LambderInvokeTransportResult, LambderInvokeRequestInit, LambderInvokeEventInit, } from "./invoke/LambderInvokeCaller.js";
+export type { LambderInvokeCallerOptions, LambderInvokeCallOptions, LambderInvokeFailureHandler, LambderInvokeCallCheck, LambderInvokeLogListHandler, LambderInvokeTransport, LambderInvokeTransportResult, LambderInvokeRequestInit, LambderInvokeEventInit, LambderInvokeEndpoint, LambderInvokeGroupCalls, } from "./invoke/LambderInvokeCaller.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
 export { LambderApiRefusal, isLambderApiRefusal, isLambderRefusalCode, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
@@ -140,7 +144,7 @@ export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiSuccessEnvelope, LambderApiRefusalEnvelope, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderContractRefusalsOf, LambderContractRefusalMessage, LambderContractRefusals, LambderContractAnyRefusalMessage, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiSuccessEnvelope, LambderApiRefusalEnvelope, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderContractEntry, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderContractRefusalsOf, LambderContractRefusalMessage, LambderContractRefusals, LambderContractAnyRefusalMessage, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
+// How an endpoint is named, and where a call to it goes.
+export { apiCallPath, apiNameOfCallPath, splitApiName, isGroupName, isActionName, LAMBDER_API_NAME_SEGMENT, LAMBDER_CALLER_MEMBER_NAMES, LAMBDER_RESERVED_GROUP_NAMES, LAMBDER_RESERVED_ACTION_NAMES, } from './shared/wire/LambderApiNames.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
 export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 // Transports: how a caller reaches a server (fetch in production, a handler in-process for tests, a cookie jar over either)

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -20,6 +20,7 @@
  * LambderInvokeCaller.localTransport runs a callee's handler in-process for
  * tests.
  */
+import { type LambderContractActionOf, type LambderContractGroupsOf, type LambderContractNamesInGroup } from "../shared/wire/LambderApiGroupCalls.js";
 import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
 import { type LambderInvokeFailure, type LambderInvokeOutcome } from "./LambderInvokeOutcome.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
@@ -52,6 +53,10 @@ export type LambderInvokeTransport = (event: APIGatewayProxyEventV2, options: {
 }) => Promise<LambderInvokeTransportResult>;
 /** The onLogList option: each answer's logList, success or failure, when it has entries. */
 export type LambderInvokeLogListHandler = (apiName: string, logList: unknown[]) => void | Promise<void>;
+/** The beforeCall option: every call, by its endpoint name or `METHOD path`, before anything is built or sent. */
+export type LambderInvokeCallCheck = (name: string, info: {
+    functionName: string;
+}) => void;
 /** The onFailure option: every failed call, once, awaited before api() throws or apiOutcome() returns. */
 export type LambderInvokeFailureHandler = (failure: LambderInvokeFailure, info: {
     apiName: string;
@@ -119,6 +124,15 @@ type LambderInvokeCallerBaseOptions = {
      * apiOutcome() never throws.
      */
     onFailure?: LambderInvokeFailureHandler;
+    /**
+     * Run before every call, api(), apiOutcome(), a group's call and
+     * request() alike, before anything is built or sent: the place for a
+     * rule the calling code must keep, such as never calling out while a
+     * database transaction is open. What it throws is thrown to the caller,
+     * from apiOutcome() too, and is no failure of the callee: nothing was
+     * sent, so onFailure is not told.
+     */
+    beforeCall?: LambderInvokeCallCheck;
     /** The session token cookie's name, when a session is carried and the callee uses a non-default `tokenCookieKey`. The CSRF value rides in the envelope's `token` field, which has no name to configure. */
     sessionTokenCookieKey?: string;
     /** Replaces the Lambda SDK. */
@@ -159,26 +173,15 @@ export type LambderInvokeEventInit = {
     sessionTokenCookieKey?: string;
 };
 /**
+ * The invoke caller itself, before the groups: what LambderInvokeCaller is,
+ * less the callee's endpoints by group (LambderInvokeGroupCalls), which the
+ * constructor adds.
+ *
  * @typeParam TContract - The callee's API contract (`typeof lambder.ApiContract`, imported type-only), for typed names, payloads, results and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
  */
-export default class LambderInvokeCaller<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> {
-    private readonly functionName;
-    private readonly apiPath;
-    private readonly apiVersion?;
-    private readonly apiSignatures?;
-    private readonly host;
-    private readonly requestCompression;
-    private readonly maxResponsePayloadBytes;
-    private readonly timeoutMs?;
-    private readonly onLogList?;
-    private readonly onFailure?;
-    private readonly guardInputsProvider?;
-    private readonly sessionTokenCookieKey;
-    private readonly transport;
-    private readonly clientConfig;
-    private client;
-    private sdk;
+declare class LambderInvokeCallerCore<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> {
+    #private;
     constructor(options: LambderInvokeCallerOptions<TContract, TProvidedGuards>);
     /**
      * The event api() would send for this call, with a plain payload. For
@@ -195,19 +198,6 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
      * completion regardless, but timeoutMs still frees the caller.
      */
     static localTransport(handler: (event: APIGatewayProxyEventV2, context: Context) => Promise<unknown>, context?: Partial<Context>): LambderInvokeTransport;
-    private loadSdk;
-    private invokeThroughSdk;
-    /** Delivers one event, serialized exactly once; an event over the invoke cap, a rejected transport, or one that answered after the call was given up on, is a failure. */
-    private deliverEvent;
-    /** Builds the failure and its error, reports it once, and hands it back. */
-    private failureOutcome;
-    private surfaceLogs;
-    /**
-     * One call, one outcome. Never throws; api() is what throws. A key scope
-     * is told how the attempt ended, as it is on LambderCaller.
-     */
-    private dispatch;
-    private dispatchAttempt;
     /**
      * Full-fidelity call: resolves to a discriminated LambderInvokeOutcome
      * instead of throwing, for sites that degrade gracefully. The output type
@@ -231,4 +221,31 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
      */
     request(init: LambderInvokeRequestInit): Promise<LambderLambdaHttpResult>;
 }
-export {};
+/**
+ * One endpoint of the callee as the invoke caller hands it out on its group:
+ * called, it is `api` for that endpoint (the output, or a thrown
+ * LambderInvokeError); `.outcome` is `apiOutcome` (the outcome, never
+ * throwing).
+ */
+export type LambderInvokeEndpoint<TContract, TName extends keyof TContract & string, TProvidedGuards extends string> = {
+    (...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderContractOutputOf<TContract, TName>>;
+    outcome(...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderInvokeOutcome<LambderContractOutputOf<TContract, TName>, LambderContractRefusalMessage<TContract, TName>>>;
+};
+/** Every endpoint of the callee's contract, by group: `caller.email.send(input)`. */
+export type LambderInvokeGroupCalls<TContract, TProvidedGuards extends string> = {
+    readonly [TGroup in LambderContractGroupsOf<TContract>]: {
+        readonly [TName in LambderContractNamesInGroup<TContract, TGroup> as LambderContractActionOf<TName>]: LambderInvokeEndpoint<TContract, TName, TProvidedGuards>;
+    };
+};
+/**
+ * A typed client of another Lambder function, over a direct Lambda invoke:
+ * `caller.email.send(input)` for the callee's endpoint `email.send`,
+ * `.outcome(input)` for its outcome, and `caller.api("email.send", input)`
+ * for code that has the name as a value.
+ */
+type LambderInvokeCaller<TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never> = LambderInvokeCallerCore<TContract, TProvidedGuards> & LambderInvokeGroupCalls<TContract, TProvidedGuards>;
+declare const LambderInvokeCaller: Omit<typeof LambderInvokeCallerCore, "prototype"> & {
+    new <TContract extends LambderApiContractShape = any, TProvidedGuards extends string = never>(options: LambderInvokeCallerOptions<TContract, TProvidedGuards>): LambderInvokeCaller<TContract, TProvidedGuards>;
+    readonly prototype: LambderInvokeCallerCore<any, any>;
+};
+export default LambderInvokeCaller;