lambder 7.3.1 → 8.1.1

package/dist/api/LambderApiSignature.js

@@ -2,56 +2,35 @@ import { z } from "zod";
 import { toGuardEntries } from "./LambderApiGuards.js";
 import { API_SIGNATURE_HEX_LENGTH, EXTENSIBLE_ENUM_META_KEY } from "../shared/wire/LambderApiSignature.js";
 import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+import { canonicalJson } from "../shared/util/canonicalJson.js";
 /*
  * The digest of an endpoint's client-facing shape, computed once, by the
  * generator, through Lambder.apiSignatures(). Nothing digests at request
- * time: the server and the client both carry the generated map and the
- * pipeline compares entries, so the one computation has nothing to agree
- * with but itself. See LambderApiSignatureMap.
+ * time: server and client both carry the generated map and the pipeline
+ * compares entries, so there is no second computation to disagree with.
+ * See LambderApiSignatureMap.
  */
-/**
- * JSON with object keys sorted at every level, so two descriptions of the
- * same shape hash the same whatever order they were built in. Arrays keep
- * their order: a tuple's positions and an enum's values are part of the
- * shape. Undefined entries are dropped, as JSON.stringify would drop them.
- */
-const canonicalJson = (value) => JSON.stringify(sortKeys(value));
-const sortKeys = (value) => {
-    if (Array.isArray(value))
-        return value.map(sortKeys);
-    if (value === null || typeof value !== "object")
-        return value;
-    const source = value;
-    const sorted = {};
-    for (const key of Object.keys(source).sort()) {
-        if (source[key] !== undefined)
-            sorted[key] = sortKeys(source[key]);
-    }
-    return sorted;
-};
 /**
  * Three edits to every node zod emits, before it is hashed.
  *
  * The `default` keyword goes. Its value is server behaviour, not shape: a
- * client never sends it, and its compiled types do not carry it. And for a
- * function default (`.default(() => new Date())`, `.prefault`, `.catch`)
- * zod writes whatever the function returned at conversion time, a clock
- * reading or a random value, which would give the endpoint a different
- * digest on every computation and a generated map that never matches the
- * server. Nothing distinguishes such a default from a constant one once zod
- * has evaluated it, so every default goes, and the one thing about a default
- * a client can see, that the field may be omitted, stays through `required`.
+ * client never sends it. For a function default (`.default(() => new
+ * Date())`, `.prefault`, `.catch`) zod writes whatever the function returned
+ * at conversion time, a clock reading or a random value, so the digest would
+ * differ on every computation and the generated map would never match the
+ * server. Once evaluated, such a default looks like a constant one, so every
+ * default goes; what a client can see of it, that the field may be omitted,
+ * stays through `required`.
  *
- * `required` is sorted. It is a set, and the order fields are declared in is
- * not shape either; left as emitted, reordering two fields forced a reload.
+ * `required` is sorted: it is a set, and declaration order is not shape.
+ * Left as emitted, reordering two fields would force a reload.
  *
- * An enum marked with extensibleEnum() loses its values in an output. Its
- * clients tolerate a value they do not know, so a response carrying one they
- * were not built with, or no longer carrying one they were, changes nothing
- * they can see; the node still says it holds a string. In an input the values
- * stay, since a value dropped from the list is a request an older client may
- * still send and the server now refuses. The mark itself goes in both, so
- * marking an enum changes no input's digest.
+ * An enum marked with extensibleEnum() loses its values in an output: its
+ * clients tolerate unknown values, so adding or removing one changes nothing
+ * they can see, and the node still says it holds a string. In an input the
+ * values stay, since a value dropped from the list is one an older client
+ * may still send and the server would refuse. The mark itself goes in both,
+ * so marking an enum changes no input's digest.
  */
 const keepShapeOnly = (node, io) => {
     delete node.default;
@@ -76,18 +55,16 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  * input and output schemas as JSON Schema, every guard it declares with the
  * schema that guard validates (the guardInput the client sends separately,
  * or the apiInput slice of the payload), and whether it demands an
- * idempotency key. Anything else about the endpoint (its rate limits, a
- * guard's parameter, the handler) changes nothing for a client and is left
- * out, so changing it never forces a reload.
+ * idempotency key. Anything else (rate limits, a guard's parameter, the
+ * handler) changes nothing for a client and is left out, so changing it never
+ * forces a reload.
  *
- * The description is hashed as built, descriptions and titles included: a
- * schema is what the server says it is, and a client built against a
- * different one reloads once, with one exception the schema declares itself:
- * the values of an extensibleEnum() in an output (see keepShapeOnly). What
- * must hold for the digest to mean anything is that a schema is built from
- * static values: one that reads the clock, a random source or the environment
- * at construction digests differently in the generator's process and on the
- * server.
+ * Schemas are hashed as built, descriptions and titles included, so a client
+ * built against a different one reloads once. The exception is an output
+ * extensibleEnum()'s values (see keepShapeOnly). Schemas must be built from
+ * static values: one that reads the clock, a random source or the
+ * environment at construction digests differently in the generator's process
+ * and on the server.
  */
 export const apiSignatureOf = async (definition, guards) => {
     const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {

package/dist/api/LambderApiValidationRefusal.d.ts

@@ -5,13 +5,12 @@ import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
  * response. The API's own schema and every preflight slice (a guard's input,
  * a rate-limit key's fields) throw this when a value fails to parse, and the
  * pipeline renders it in one place: through the app's input validation
- * handler when it set one, otherwise as the standard 422 body. The engines
- * therefore never build a response and never see a resolver, which is what
- * lets them run outside a Lambda.
+ * handler when set, otherwise as the standard 422 body. The engines never
+ * build a response or see a resolver, which lets them run outside a Lambda.
  *
- * A LambderApiRefusal, so every catch that maps refusals already handles it;
- * the brand tells the pipeline to route it through the validation handler
- * instead of the refusal envelope.
+ * It is a LambderApiRefusal, so every catch that maps refusals handles it;
+ * the brand routes it through the validation handler instead of the refusal
+ * envelope.
  */
 export declare class LambderApiValidationRefusal extends LambderApiRefusal {
     /** Brand for detection across duplicate lambder installs, like LambderApiRefusal's. */
@@ -26,7 +25,8 @@ export declare const isLambderApiValidationRefusal: (err: unknown) => err is Lam
  * a guardInput value from the raw guardInputs map). Runs before the API's
  * own validation; a failure throws the same LambderApiValidationRefusal the
  * API's schema throws, so the pipeline answers every rejected input alike.
- * Shared by the guards engine and the rate-limit engine, and living here
- * beside the error it throws rather than in one of the two.
+ * Shared by the guards and rate-limit engines, so it lives beside the error
+ * it throws. Parsed asynchronously, so a slice with an async refinement (a
+ * lookup, say) validates instead of making zod throw on every call.
  */
-export declare const parsePreflightSlice: (input: z.ZodType, value: unknown) => unknown;
+export declare const parsePreflightSlice: (input: z.ZodType, value: unknown) => Promise<unknown>;

package/dist/api/LambderApiValidationRefusal.js

@@ -4,13 +4,12 @@ import { LambderApiRefusal, isLambderApiRefusal } from "../shared/wire/LambderAp
  * response. The API's own schema and every preflight slice (a guard's input,
  * a rate-limit key's fields) throw this when a value fails to parse, and the
  * pipeline renders it in one place: through the app's input validation
- * handler when it set one, otherwise as the standard 422 body. The engines
- * therefore never build a response and never see a resolver, which is what
- * lets them run outside a Lambda.
+ * handler when set, otherwise as the standard 422 body. The engines never
+ * build a response or see a resolver, which lets them run outside a Lambda.
  *
- * A LambderApiRefusal, so every catch that maps refusals already handles it;
- * the brand tells the pipeline to route it through the validation handler
- * instead of the refusal envelope.
+ * It is a LambderApiRefusal, so every catch that maps refusals handles it;
+ * the brand routes it through the validation handler instead of the refusal
+ * envelope.
  */
 export class LambderApiValidationRefusal extends LambderApiRefusal {
     /** Brand for detection across duplicate lambder installs, like LambderApiRefusal's. */
@@ -29,11 +28,12 @@ export const isLambderApiValidationRefusal = (err) => isLambderApiRefusal(err) &
  * a guardInput value from the raw guardInputs map). Runs before the API's
  * own validation; a failure throws the same LambderApiValidationRefusal the
  * API's schema throws, so the pipeline answers every rejected input alike.
- * Shared by the guards engine and the rate-limit engine, and living here
- * beside the error it throws rather than in one of the two.
+ * Shared by the guards and rate-limit engines, so it lives beside the error
+ * it throws. Parsed asynchronously, so a slice with an async refinement (a
+ * lookup, say) validates instead of making zod throw on every call.
  */
-export const parsePreflightSlice = (input, value) => {
-    const parsed = input.safeParse(value);
+export const parsePreflightSlice = async (input, value) => {
+    const parsed = await input.safeParseAsync(value);
     if (!parsed.success)
         throw new LambderApiValidationRefusal(parsed.error);
     return parsed.data;

package/dist/build/ContractTypePrinter.d.ts

@@ -0,0 +1,85 @@
+import type ts from "typescript";
+/** How the printed module is punctuated. */
+export type ContractPrintStyle = {
+    quote: "'" | "\"";
+    semicolon: "" | ";";
+};
+/** The contract as text: each entry by name, and the named types the entries refer to. */
+export type PrintedContract = {
+    entries: {
+        name: string;
+        text: string;
+    }[];
+    declarations: {
+        name: string;
+        text: string;
+    }[];
+    /** Where the contract holds something with no plain form, and what it is. */
+    failures: string[];
+};
+export declare class ContractTypePrinter {
+    private readonly ts;
+    private readonly program;
+    private readonly checker;
+    private readonly style;
+    private readonly failures;
+    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    private readonly declarations;
+    /** Names a declaration may not take: the default library's, and the contract's own. */
+    private readonly takenNames;
+    /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
+    private readonly inProgress;
+    /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
+    private readonly exactOptionalProperties;
+    constructor(ts: typeof import("typescript"), program: ts.Program, checker: ts.TypeChecker, style: ContractPrintStyle, contractName: string);
+    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    printContract(contract: ts.Type): PrintedContract;
+    /**
+     * `label value`, with a union too long for one line starting on the next
+     * line, one member per line: what a property, an index signature and a
+     * declaration all print through.
+     */
+    labeledValue(label: string, value: string): string;
+    private print;
+    /** A union, an intersection or an object: printed in place, or as a reference to a declaration of its own. */
+    private printComposite;
+    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
+    private declaredNameOf;
+    /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
+    private nameOf;
+    /**
+     * A name for a type that refers to itself and has none of its own: what it
+     * instantiates followed by its arguments (a JSON mapping of a Tree is
+     * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     */
+    private recursiveNameOf;
+    private printStructure;
+    private printUnion;
+    private printUnionOf;
+    private printIntersection;
+    private printObject;
+    private printMembers;
+    /**
+     * An optional member's type as its source wrote it. Under
+     * exactOptionalPropertyTypes the compiler adds its own "missing"
+     * undefined, a different type from the `undefined` a source writes;
+     * printed as `| undefined` it would let the member be undefined, which
+     * the source does not.
+     */
+    private printOptionalMember;
+    private printTuple;
+    private printTemplateLiteral;
+    /** Why a property cannot be printed as a plain member, or undefined when it can. */
+    private unprintableProperty;
+    /** An object type printed member by member: not an array, a tuple, a function or a default library interface. */
+    private isPlainObject;
+    private isCallable;
+    private isDefaultLibraryInterface;
+    /** Declared in the default library, even where a package augments it (as @types/node does some globals). */
+    private isDefaultLibrary;
+    private wrapped;
+    keyOf(name: string): string;
+    private quoted;
+    private takeName;
+    private fail;
+}