lambder 7.2.2 → 7.2.3

package/CHANGELOG.md

@@ -9,6 +9,22 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [7.2.3] - 2026-09-19
+
+### Added
+
+- **`extensibleEnum(schema)`**, exported from both entries: marks an enum
+  whose readers tolerate values they were not built with, and the signature
+  digest leaves its values out wherever it is output. A list that grows with
+  the product (roles, permissions, statuses) and rides in a widely returned
+  payload changed the signature of every endpoint returning it, so one new
+  permission reloaded every open tab. With the mark, the list growing or
+  shrinking reloads only the clients of endpoints that take it as input,
+  where its values still count because a removed value is a request the
+  server now refuses. The schema's type and validation are unchanged; the
+  mark is zod metadata, read from zod's shared registry. An unmarked enum
+  digests exactly as before, so upgrading changes no signature.
+
 ## [7.2.2] - 2026-09-18
 
 ### Added

package/dist/api/LambderApiSignature.d.ts

@@ -24,9 +24,11 @@ export type LambderApiSignatureEntry = {
  *
  * 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. 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.
+ * 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.
  */
 export declare const apiSignatureOf: (definition: LambderApiDefinition, guards: Record<string, LambderApiGuard<any, any, any>> | undefined) => Promise<string>;

package/dist/api/LambderApiSignature.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { toGuardEntries } from "./LambderApiGuards.js";
-import { API_SIGNATURE_HEX_LENGTH } from "../shared/wire/LambderApiSignature.js";
+import { API_SIGNATURE_HEX_LENGTH, EXTENSIBLE_ENUM_META_KEY } from "../shared/wire/LambderApiSignature.js";
 import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
 /*
  * The digest of an endpoint's client-facing shape, computed once, by the
@@ -30,7 +30,7 @@ const sortKeys = (value) => {
     return sorted;
 };
 /**
- * Two edits to every node zod emits, before it is hashed.
+ * 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
@@ -44,11 +44,24 @@ const sortKeys = (value) => {
  *
  * `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.
+ *
+ * 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.
  */
-const keepShapeOnly = (node) => {
+const keepShapeOnly = (node, io) => {
     delete node.default;
     if (Array.isArray(node.required))
         node.required.sort();
+    if (node[EXTENSIBLE_ENUM_META_KEY] === true) {
+        delete node[EXTENSIBLE_ENUM_META_KEY];
+        if (io === "output")
+            delete node.enum;
+    }
 };
 /**
  * A schema as JSON Schema, as zod emits it minus what keepShapeOnly removes.
@@ -56,7 +69,7 @@ const keepShapeOnly = (node) => {
  * becomes `{}` rather than throwing, because a digest has to exist for every
  * endpoint; what the digest cannot see is documented with it.
  */
-const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema) }) : null;
+const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema, io) }) : null;
 const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasOwnProperty.call(guards, name) ? guards[name] : undefined;
 /**
  * The digest of an endpoint's client-facing shape: its name and mode, its
@@ -69,10 +82,12 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  *
  * 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. 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.
+ * 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.
  */
 export const apiSignatureOf = async (definition, guards) => {
     const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {

package/dist/client.d.ts

@@ -15,7 +15,7 @@ export type { LambderApiTransport, LambderApiTransportRequest, LambderTransportF
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";

package/dist/client.js

@@ -14,8 +14,9 @@ export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFail
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
-// The per-endpoint signature map a build ships with, how a caller reads it, and the reload-loop window.
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+// The per-endpoint signature map a build ships with, how a caller reads it, the
+// mark a shared schema sets on an enum its readers let grow, and the reload-loop window.
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderAp
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
 export type { LambderApiSignatureEntry } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";

package/dist/index.js

@@ -18,7 +18,7 @@ export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
 // Per-endpoint signatures: what a client build ships with, digested from the server's own registrations.
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";

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

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 /**
  * The per-endpoint signatures a client carries, generated from the server's
  * own registrations (Lambder.apiSignatures()) and shipped with the client
@@ -44,3 +45,39 @@ export declare const lookupApiSignature: (signatures: LambderApiSignatureMap, ap
  * run instead of saying so.
  */
 export declare const readApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string>;
+/**
+ * The metadata key extensibleEnum() sets and the digest reads. Namespaced,
+ * because zod writes metadata into the JSON Schema it emits, so the key shows
+ * up in any schema an app converts for itself, where OpenAPI's own
+ * `x-extensible-enum` means something else (the values, in place of `enum`).
+ */
+export declare const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
+/**
+ * Marks an enum whose clients tolerate a value they were not built with, so
+ * its list of values stays out of the signature of every endpoint that
+ * returns it. Adding a role, a status or a locale to a list that rides in a
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @example
+ * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));
+ */
+export declare const extensibleEnum: <TSchema extends z.ZodEnum>(schema: TSchema) => TSchema;

package/dist/shared/wire/LambderApiSignature.js

@@ -43,3 +43,39 @@ export const readApiSignature = async (signatures, apiName) => {
     }
     return signature;
 };
+/**
+ * The metadata key extensibleEnum() sets and the digest reads. Namespaced,
+ * because zod writes metadata into the JSON Schema it emits, so the key shows
+ * up in any schema an app converts for itself, where OpenAPI's own
+ * `x-extensible-enum` means something else (the values, in place of `enum`).
+ */
+export const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
+/**
+ * Marks an enum whose clients tolerate a value they were not built with, so
+ * its list of values stays out of the signature of every endpoint that
+ * returns it. Adding a role, a status or a locale to a list that rides in a
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @example
+ * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));
+ */
+export const extensibleEnum = (schema) => schema.meta({ [EXTENSIBLE_ENUM_META_KEY]: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.2.2",
+  "version": "7.2.3",
   "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": [