lambder 11.1.1 → 13.0.1

package/dist/core/LambderResponseBuilder.js

@@ -1,3 +1,4 @@
+import { outcomeOfEnvelope } from "../shared/wire/LambderCallOutcome.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { plainRefusalEnvelope } from "../api/LambderApiEnvelope.js";
 /**
@@ -145,7 +146,10 @@ export default class LambderResponseBuilder {
      * request accumulated unless the config names its own.
      */
     apiRefusal(config, options) {
-        return this.json(plainRefusalEnvelope(this.apiVersion, config, "res.apiRefusal()", this.ctx?.logList), options);
+        const envelope = plainRefusalEnvelope(this.apiVersion, config, "res.apiRefusal()", this.ctx?.logList);
+        const response = this.json(envelope, options);
+        response.callOutcome = outcomeOfEnvelope(envelope, response.statusCode);
+        return response;
     }
     ;
 }

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";
@@ -20,7 +24,7 @@ export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
 export type { LambderHandlerTransportOptions } from "./invoke/lambderHandlerTransport.js";
-export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
+export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_PARENT_REQUEST_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
 export type { LambderSynthesizedRequest, LambderLambdaHttpResult, LambderInvokeSession } from "./invoke/LambderLambdaEvent.js";
 export { LambderApiPipeline } from "./api/LambderApiPipeline.js";
 export type { LambderApiPipelineOptions, LambderApiSessionsConfig, LambderApiInputRefusal, LambderApiRunResult, LambderApiExec } from "./api/LambderApiPipeline.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";
@@ -96,7 +100,7 @@ export { refuseUnacceptedUpload } from "./shared/wire/LambderUploadRefusal.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
 export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
-export type { LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export type { LambderCreatedSession, LambderSessionDataOptions, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/wire/LambderCompressionOption.js";
 export type { LambderCompressionOption, LambderCompressionSettings, LambderCompressionSettingsBase, LambderEncoding, } from "./shared/wire/LambderCompressionOption.js";
 export { compressText, restoreBytes, restoreText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "./shared/wire/LambderCompressionCodec.js";
@@ -130,7 +134,7 @@ export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
 export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderGuardNamesInputLacks, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
 export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
-export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
+export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderRefusalVocabularyOption, LambderMergedRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
 export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderPolicyNamesInputLacks, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
@@ -140,12 +144,14 @@ 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";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
-export type { LambderContextOptions } from "./core/LambderContext.js";
+export type { LambderContextOptions, LambderOriginProof } from "./core/LambderContext.js";
+export type { LambderCallSummary, LambderCallSummaryOption } from "./core/LambderCallSummary.js";
+export type { LambderCallOutcome, LambderCallOutcomeHint } from "./shared/wire/LambderCallOutcome.js";
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
 export type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/wire/LambderRequestPayload.js";
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.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)
@@ -15,7 +17,7 @@ export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
 export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
 export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
-export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
+export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_PARENT_REQUEST_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
 // The API core: the request, answer, envelope and pipeline both the server and the mock runtime run
 export { LambderApiPipeline } from "./api/LambderApiPipeline.js";
 export { readApiEnvelope, restoreCompressedPayload } from "./api/LambderApiRequest.js";

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;