lambder 11.1.1 → 12.0.1

package/dist/shared/wire/LambderApiGroupCalls.js

@@ -0,0 +1,68 @@
+import { isActionName, isGroupName } from "./LambderApiNames.js";
+/**
+ * The caller, answering for each group a contract could name besides its
+ * own members. A member the caller has (a method, a field) is always the
+ * caller's; a name that could be a group (see isGroupName: an identifier no
+ * caller member has) is one; anything else a runtime or a framework asks of
+ * an object (then, toJSON, a symbol, `__v_isRef`) is what the caller itself
+ * answers, so a caller is never mistaken for a promise, a ref or a
+ * serializable record.
+ *
+ * A caller keeps its state in #private fields, which no property name
+ * reaches, so a group may take any name its public members leave free. Such
+ * a field is readable only on the caller itself, never through this proxy,
+ * so a member is read and a method run on the caller; a method that returns
+ * the caller (setTransport) hands back the proxy, groups and all.
+ *
+ * A group answers the same way one level down: an ordinary object's own
+ * members (toString, valueOf, hasOwnProperty) are an ordinary object's, so
+ * converting a group to a string or asking it what it holds calls no
+ * endpoint; any other name that could be an action (see isActionName) is
+ * one. A group is read-only, like the type that describes it.
+ */
+export const withApiGroupCalls = (caller, call, outcome) => {
+    const methods = new WeakMap();
+    const methodOnCaller = (method) => {
+        let bound = methods.get(method);
+        if (!bound) {
+            bound = (...args) => {
+                const result = Reflect.apply(method, caller, args);
+                return result === caller ? withGroups : result;
+            };
+            methods.set(method, bound);
+        }
+        return bound;
+    };
+    const groups = new Map();
+    const groupOf = (group) => {
+        let calls = groups.get(group);
+        if (!calls) {
+            const actions = new Map();
+            calls = new Proxy(Object.freeze({}), {
+                get: (target, action) => {
+                    if (typeof action !== "string" || action in target || !isActionName(action))
+                        return Reflect.get(target, action);
+                    let endpoint = actions.get(action);
+                    if (!endpoint) {
+                        const apiName = `${group}.${action}`;
+                        endpoint = Object.freeze(Object.assign((...args) => call(apiName, args), { outcome: (...args) => outcome(apiName, args) }));
+                        actions.set(action, endpoint);
+                    }
+                    return endpoint;
+                },
+            });
+            groups.set(group, calls);
+        }
+        return calls;
+    };
+    const withGroups = new Proxy(caller, {
+        get: (target, property) => {
+            if (typeof property === "string" && !(property in target) && isGroupName(property))
+                return groupOf(property);
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" && property !== "constructor" ? methodOnCaller(value) : value;
+        },
+        set: (target, property, value) => Reflect.set(target, property, value, target),
+    });
+    return withGroups;
+};

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

@@ -0,0 +1,55 @@
+/**
+ * How an endpoint is named and where it is called. An endpoint belongs to a
+ * group, and its name is the two joined by a dot: `orders.place`. Both are
+ * identifiers, so the name is also a path: a call posts to
+ * `{apiPath}/{group}/{action}`, which a gateway, a CDN and a log can meter,
+ * limit and read per endpoint without opening the body.
+ *
+ * The group is also a property of every Lambder caller
+ * (`caller.orders.place(input)`), so a group may not be named like anything a
+ * caller already has.
+ */
+/** A group's or an action's name: a letter, then letters, digits or underscores. */
+export declare const LAMBDER_API_NAME_SEGMENT: RegExp;
+/**
+ * Every public member of the three callers a group becomes a property of
+ * (LambderCaller, LambderInvokeCaller, LambderTestVisitor), since a caller
+ * looks a group up only after its own members. Their state is #private,
+ * which no property name reaches, so only these can stand in a group's way.
+ * A test holds this to the callers' public members, in their types and at
+ * runtime, both ways.
+ */
+export declare const LAMBDER_CALLER_MEMBER_NAMES: readonly ["api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request", "setSessionCookieKey", "setTransport", "signIn"];
+/**
+ * Names no group may take: the callers' members, and what a JavaScript
+ * runtime, a promise check, a serializer or a framework asks of any object.
+ */
+export declare const LAMBDER_RESERVED_GROUP_NAMES: readonly ["api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request", "setSessionCookieKey", "setTransport", "signIn", "constructor", "then", "catch", "finally", "toJSON", "toString", "valueOf", "toLocaleString", "prototype", "inspect", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable"];
+/** A name no group may take; see LAMBDER_RESERVED_GROUP_NAMES. */
+export type LambderReservedGroupName = typeof LAMBDER_RESERVED_GROUP_NAMES[number];
+/**
+ * Names no action may take: what a runtime, a promise check or a serializer
+ * asks of a group or of the function a caller hands out for an action, and
+ * the members every object has (toString, valueOf, hasOwnProperty), which a
+ * group keeps as its own.
+ */
+export declare const LAMBDER_RESERVED_ACTION_NAMES: readonly ["then", "catch", "finally", "toJSON", "constructor", "prototype", "outcome", "bind", "call", "apply", "length", "name", "arguments", "caller", "toString", "toLocaleString", "valueOf", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable"];
+/** A name no action may take; see LAMBDER_RESERVED_ACTION_NAMES. */
+export type LambderReservedActionName = typeof LAMBDER_RESERVED_ACTION_NAMES[number];
+/** Whether a name can be a group: an identifier segment, and not one a caller already answers for. */
+export declare const isGroupName: (name: string) => boolean;
+/** Whether a name can be an action of a group: an identifier segment, and not one a function already answers for. */
+export declare const isActionName: (name: string) => boolean;
+/** An endpoint's name split into its group and action, or null for a name that is not two segments. */
+export declare const splitApiName: (apiName: string) => {
+    group: string;
+    action: string;
+} | null;
+/** Where a call to the endpoint goes: `{apiPath}/{group}/{action}`. An apiPath may be absolute (another origin) or end with a slash. */
+export declare const apiCallPath: (apiPath: string, apiName: string) => string;
+/**
+ * The endpoint a request path calls, or null when the path is not a call
+ * under apiPath: exactly `{apiPath}/{group}/{action}`, with no query, no
+ * trailing slash and no further segment.
+ */
+export declare const apiNameOfCallPath: (apiPath: string, path: string) => string | null;

package/dist/shared/wire/LambderApiNames.js

@@ -0,0 +1,81 @@
+/**
+ * How an endpoint is named and where it is called. An endpoint belongs to a
+ * group, and its name is the two joined by a dot: `orders.place`. Both are
+ * identifiers, so the name is also a path: a call posts to
+ * `{apiPath}/{group}/{action}`, which a gateway, a CDN and a log can meter,
+ * limit and read per endpoint without opening the body.
+ *
+ * The group is also a property of every Lambder caller
+ * (`caller.orders.place(input)`), so a group may not be named like anything a
+ * caller already has.
+ */
+/** A group's or an action's name: a letter, then letters, digits or underscores. */
+export const LAMBDER_API_NAME_SEGMENT = /^[A-Za-z][A-Za-z0-9_]*$/;
+/**
+ * Every public member of the three callers a group becomes a property of
+ * (LambderCaller, LambderInvokeCaller, LambderTestVisitor), since a caller
+ * looks a group up only after its own members. Their state is #private,
+ * which no property name reaches, so only these can stand in a group's way.
+ * A test holds this to the callers' public members, in their types and at
+ * runtime, both ways.
+ */
+export const LAMBDER_CALLER_MEMBER_NAMES = [
+    "api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request",
+    "setSessionCookieKey", "setTransport", "signIn",
+];
+/**
+ * Names no group may take: the callers' members, and what a JavaScript
+ * runtime, a promise check, a serializer or a framework asks of any object.
+ */
+export const LAMBDER_RESERVED_GROUP_NAMES = [
+    ...LAMBDER_CALLER_MEMBER_NAMES,
+    "constructor", "then", "catch", "finally", "toJSON", "toString", "valueOf", "toLocaleString", "prototype", "inspect",
+    "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable",
+];
+/**
+ * Names no action may take: what a runtime, a promise check or a serializer
+ * asks of a group or of the function a caller hands out for an action, and
+ * the members every object has (toString, valueOf, hasOwnProperty), which a
+ * group keeps as its own.
+ */
+export const LAMBDER_RESERVED_ACTION_NAMES = [
+    "then", "catch", "finally", "toJSON", "constructor", "prototype", "outcome", "bind", "call", "apply", "length", "name",
+    "arguments", "caller", "toString", "toLocaleString", "valueOf", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable",
+];
+const RESERVED_GROUP_NAMES = new Set(LAMBDER_RESERVED_GROUP_NAMES);
+const RESERVED_ACTION_NAMES = new Set(LAMBDER_RESERVED_ACTION_NAMES);
+/** Whether a name can be a group: an identifier segment, and not one a caller already answers for. */
+export const isGroupName = (name) => LAMBDER_API_NAME_SEGMENT.test(name) && !RESERVED_GROUP_NAMES.has(name);
+/** Whether a name can be an action of a group: an identifier segment, and not one a function already answers for. */
+export const isActionName = (name) => LAMBDER_API_NAME_SEGMENT.test(name) && !RESERVED_ACTION_NAMES.has(name);
+/** An endpoint's name split into its group and action, or null for a name that is not two segments. */
+export const splitApiName = (apiName) => {
+    const dot = apiName.indexOf(".");
+    if (dot === -1)
+        return null;
+    const group = apiName.slice(0, dot);
+    const action = apiName.slice(dot + 1);
+    return LAMBDER_API_NAME_SEGMENT.test(group) && LAMBDER_API_NAME_SEGMENT.test(action) ? { group, action } : null;
+};
+/** Where a call to the endpoint goes: `{apiPath}/{group}/{action}`. An apiPath may be absolute (another origin) or end with a slash. */
+export const apiCallPath = (apiPath, apiName) => {
+    const parts = splitApiName(apiName);
+    if (!parts)
+        throw new Error(`Lambder: "${apiName}" is not an endpoint name. An endpoint is named group.action, both identifiers.`);
+    return `${apiPath.replace(/\/+$/, "")}/${parts.group}/${parts.action}`;
+};
+/**
+ * The endpoint a request path calls, or null when the path is not a call
+ * under apiPath: exactly `{apiPath}/{group}/{action}`, with no query, no
+ * trailing slash and no further segment.
+ */
+export const apiNameOfCallPath = (apiPath, path) => {
+    const base = apiPath.replace(/\/+$/, "");
+    if (!path.startsWith(`${base}/`))
+        return null;
+    const segments = path.slice(base.length + 1).split("/");
+    if (segments.length !== 2)
+        return null;
+    const [group, action] = segments;
+    return LAMBDER_API_NAME_SEGMENT.test(group) && LAMBDER_API_NAME_SEGMENT.test(action) ? `${group}.${action}` : null;
+};

package/dist/shared/wire/LambderUploadSchemas.js

@@ -5,9 +5,10 @@ import { z } from "zod";
  * posts to the ticket endpoint, and the ticket it answers.
  *
  * ```ts
- * .addSessionApi("documents.requestUpload", {
+ * requestUpload: defineApi({
  *     input: z.object({ folderId: z.uuid(), fileFacts: LambderUploadFileFactsSchema }),
  *     output: z.object({ ticket: LambderUploadTicketSchema, documentId: z.uuid() }),
+ *     guards: "signedIn",
  * }, ...)
  * ```
  *

package/dist/testing/LambderTestApp.d.ts

@@ -7,6 +7,7 @@ import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisitorOptions } from "./LambderTestVisitor.js";
 /**
@@ -51,7 +52,10 @@ export type LambderTestAppOptions = {
  * (`lambderTestApp<SessionData, ApiContractType>(lambder)`), so the tests type
  * their calls against plain members rather than the chained intersection.
  */
-export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any, any, any> & {
+export type LambderTestedInstance<TSessionData, TContract> = Pick<Lambder<any, any>, "apiPath" | "getHandler" | "getSessionController" | "getSessionManager" | typeof LAMBDER_BACKEND_SWAP | typeof LAMBDER_CRASH_WATCH> & {
+    readonly AppTypes: {
+        session: TSessionData;
+    };
     readonly ApiContract: TContract;
 };
 /**

package/dist/testing/LambderTestVisitor.d.ts

@@ -1,4 +1,4 @@
-import LambderCaller from "../client/LambderCaller.js";
+import LambderCaller, { type LambderCallerGroupCalls, type LambderCallerMembers } from "../client/LambderCaller.js";
 import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 import type { LambderHandler } from "../core/LambderCreateOptions.js";
 import { type LambderLambdaHttpResult } from "../invoke/LambderLambdaEvent.js";
@@ -84,7 +84,8 @@ export type LambderTestVisitorArgs<TOptions, TProvidedGuards extends string> = [
  *
  * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
  */
-export declare class LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+declare class LambderTestVisitorCore<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+    #private;
     readonly host: string;
     readonly clientIp: string;
     /**
@@ -95,7 +96,7 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      */
     readonly caller: LambderCaller<TContract, TProvidedGuards>;
     /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
-    readonly api: LambderCaller<TContract, TProvidedGuards>["api"];
+    readonly api: LambderCallerMembers<TContract, TProvidedGuards>["api"];
     /**
      * The full outcome, never throwing: LambderCaller.apiOutcome, through
      * this visitor. Pair it with assertApiSuccess / assertApiFailure.
@@ -105,11 +106,7 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      * 500"; here that error's `cause` is what the app actually threw, stack
      * included, so a failing test points at the line in the handler.
      */
-    readonly apiOutcome: LambderCaller<TContract, TProvidedGuards>["apiOutcome"];
-    private readonly wiring;
-    private readonly headers;
-    private readonly cookieJar;
-    private seenResetCount;
+    readonly apiOutcome: LambderCallerMembers<TContract, TProvidedGuards>["apiOutcome"];
     constructor(wiring: LambderTestVisitorWiring<TSessionData>, options: LambderTestVisitorOptions<TContract, TProvidedGuards> & {
         host: string;
         clientIp: string;
@@ -151,3 +148,14 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
         ttlSeconds?: number;
     }): Promise<LambderCreatedSession<TSessionData>>;
 }
+/**
+ * One simulated browser in front of a real Lambder app, with the app's
+ * endpoints by group as a caller has them: `visitor.orders.place(input)`,
+ * `visitor.orders.place.outcome(input)`.
+ */
+export type LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> = LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards> & LambderCallerGroupCalls<TContract, TProvidedGuards>;
+export declare const LambderTestVisitor: {
+    new <TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never>(...args: ConstructorParameters<typeof LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards>>): LambderTestVisitor<TContract, TSessionData, TProvidedGuards>;
+    readonly prototype: LambderTestVisitorCore<any, any, any>;
+};
+export {};

package/dist/testing/LambderTestVisitor.js

@@ -1,4 +1,5 @@
 import LambderCaller from "../client/LambderCaller.js";
+import { withApiGroupCalls } from "../shared/wire/LambderApiGroupCalls.js";
 import { lambderHandlerTransport } from "../invoke/lambderHandlerTransport.js";
 import { decodeLambdaHttpResult, localLambdaContext, synthesizeLambdaHttpEvent, } from "../invoke/LambderLambdaEvent.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
@@ -15,7 +16,7 @@ import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderReques
  *
  * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
  */
-export class LambderTestVisitor {
+class LambderTestVisitorCore {
     host;
     clientIp;
     /**
@@ -37,19 +38,19 @@ export class LambderTestVisitor {
      * included, so a failing test points at the line in the handler.
      */
     apiOutcome;
-    wiring;
-    headers;
-    cookieJar;
-    seenResetCount;
+    #wiring;
+    #headers;
+    #cookieJar;
+    #seenResetCount;
     constructor(wiring, options) {
-        this.wiring = wiring;
+        this.#wiring = wiring;
         this.host = options.host;
         this.clientIp = options.clientIp;
-        this.headers = options.headers ?? {};
-        this.cookieJar = new LambderCookieJar({ host: this.host });
-        this.seenResetCount = wiring.resetCount();
+        this.#headers = options.headers ?? {};
+        this.#cookieJar = new LambderCookieJar({ host: this.host });
+        this.#seenResetCount = wiring.resetCount();
         const handlerTransport = lambderHandlerTransport(wiring.handler, { host: this.host, clientIp: this.clientIp, eventFormat: wiring.eventFormat });
-        const withVisitorHeaders = (request) => handlerTransport({ ...request, headers: { ...this.headers, ...request.headers } });
+        const withVisitorHeaders = (request) => handlerTransport({ ...request, headers: { ...this.#headers, ...request.headers } });
         this.caller = new LambderCaller({
             apiPath: wiring.apiPath,
             apiVersion: options.apiVersion,
@@ -69,13 +70,19 @@ export class LambderTestVisitor {
         if (wiring.sessionCookieNames) {
             this.caller.setSessionCookieKey(wiring.sessionCookieNames.tokenCookieKey, wiring.sessionCookieNames.csrfCookieKey);
         }
-        this.api = this.caller.api.bind(this.caller);
-        this.apiOutcome = (async (...callArgs) => {
-            const { result: outcome, crash } = await wiring.watchCrash(() => this.caller.apiOutcome(...callArgs));
+        const caller = this.caller;
+        const apiOutcome = async (apiName, ...callArgs) => {
+            const { result: outcome, crash } = await wiring.watchCrash(() => caller.apiOutcome(apiName, ...callArgs));
             if (crash && !outcome.ok && "error" in outcome && outcome.error.cause === undefined)
                 outcome.error.cause = crash;
             return outcome;
-        });
+        };
+        this.api = ((apiName, ...callArgs) => caller.api(apiName, ...callArgs));
+        this.apiOutcome = apiOutcome;
+        // Each group of the contract, as on a caller, through this visitor's
+        // own two calls: visitor.orders.place.outcome(input) carries the crash
+        // cause as visitor.apiOutcome does.
+        return withApiGroupCalls(this, (apiName, args) => caller.api(apiName, ...args), (apiName, args) => apiOutcome(apiName, ...args));
     }
     /**
      * This visitor's cookies, to inspect or clear; every call and request
@@ -84,12 +91,12 @@ export class LambderTestVisitor {
      * emptied store would read as signed in until an answer said otherwise.
      */
     get jar() {
-        const resetCount = this.wiring.resetCount();
-        if (resetCount !== this.seenResetCount) {
-            this.cookieJar.clear();
-            this.seenResetCount = resetCount;
+        const resetCount = this.#wiring.resetCount();
+        if (resetCount !== this.#seenResetCount) {
+            this.#cookieJar.clear();
+            this.#seenResetCount = resetCount;
         }
-        return this.cookieJar;
+        return this.#cookieJar;
     }
     /**
      * One HTTP request to the app that is not an API call, answered by
@@ -117,12 +124,12 @@ export class LambderTestVisitor {
             path: pathname,
             query,
             host: this.host,
-            headers: { ...this.headers, ...init.headers },
+            headers: { ...this.#headers, ...init.headers },
             clientIp: this.clientIp,
             cookies: this.jar.cookiePairs(cookieScope),
             body: init.body,
-        }, { invoke: false, eventFormat: this.wiring.eventFormat });
-        const result = await decodeLambdaHttpResult(await this.wiring.handler(event, localLambdaContext("lambder-test")), DEFAULT_MAX_RESTORED_PAYLOAD_BYTES);
+        }, { invoke: false, eventFormat: this.#wiring.eventFormat });
+        const result = await decodeLambdaHttpResult(await this.#wiring.handler(event, localLambdaContext("lambder-test")), DEFAULT_MAX_RESTORED_PAYLOAD_BYTES);
         if (result.cookies.length)
             this.jar.storeSetCookies(result.cookies, cookieScope);
         return result;
@@ -140,11 +147,11 @@ export class LambderTestVisitor {
      * answer sessionExpired with nothing to say why.
      */
     async signIn(sessionKey, data, options = {}) {
-        if (!this.wiring.sessionCookieNames)
+        if (!this.#wiring.sessionCookieNames)
             throw new Error("LambderTestVisitor: signIn() needs an app with sessions. Pass the session option to create().");
-        const { created, setCookies } = await this.wiring.issueSession(this.host, sessionKey, data, options.ttlSeconds);
+        const { created, setCookies } = await this.#wiring.issueSession(this.host, sessionKey, data, options.ttlSeconds);
         this.jar.storeSetCookies(setCookies, { host: this.host });
-        if (this.jar.get(this.wiring.sessionCookieNames.tokenCookieKey, { host: this.host, includeHttpOnly: true }) === undefined) {
+        if (this.jar.get(this.#wiring.sessionCookieNames.tokenCookieKey, { host: this.host, includeHttpOnly: true }) === undefined) {
             throw new Error(`LambderTestVisitor: the session cookie did not stick for host "${this.host}", the way a browser on that host would drop it. ` +
                 "The app most likely scopes its session cookie to a domain this host is not under: " +
                 "give the test app or this visitor a `host` the cookie domain covers.");
@@ -152,3 +159,4 @@ export class LambderTestVisitor {
         return created;
     }
 }
+export const LambderTestVisitor = LambderTestVisitorCore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "11.1.1",
+  "version": "12.0.1",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [