@blamejs/core 0.8.43 → 0.8.50

package/lib/safe-schema.js

@@ -1,34 +1,87 @@
 "use strict";
 /**
- * safe-schema — declarative input validation, Zod-shaped surface.
+ * @module b.safeSchema
+ * @featured true
+ * @nav    Validation
+ * @title  Safe Schema
  *
- * Built for: request-body validation, config validation, API payload
- * validation, anywhere operators have an `unknown` shape they need
- * to confirm before reading. Vendor-free; built on framework
- * primitives. No JIT, no codegen, no chained-Promise weirdness.
+ * @intro
+ *   Declarative input validation with a Zod-shaped chained-method
+ *   surface. Built for request-body validation, config validation,
+ *   API payload validation, anywhere operators have an `unknown`
+ *   shape they need to confirm before reading. Vendor-free; built
+ *   on framework primitives. No JIT, no codegen, no chained-Promise
+ *   weirdness.
  *
- * Public API:
- *   var s = b.safeSchema;
+ *   Schemas are immutable — every chained check returns a new
+ *   schema; the original is untouched. `parse(input)` throws
+ *   `SafeSchemaError` carrying a full per-field issues array;
+ *   `safeParse(input)` never throws and returns `{ ok, value?,
+ *   errors? }` (operator-friendly at HTTP boundaries).
  *
- *   var schema = s.object({
- *     email: s.string().email(),
- *     age:   s.number().int().min(0).max(120),
- *     tags:  s.array(s.string()).max(10),
- *     metadata: s.object({}).passthrough().optional(),
- *   });
+ *   Security guarantees: prototype-pollution defense — `__proto__`
+ *   / `constructor` / `prototype` keys are rejected at object-shape
+ *   construction AND at parse-time on object + record inputs (mirrors
+ *   `b.safeJson`'s POISONED_KEYS). Per-format defensive length caps
+ *   (email 254, url 8 KiB, uuid 50, datetime 100 chars …) bound input
+ *   BEFORE the regex engine runs, so a hostile payload can't ReDoS
+ *   `.email()` / `.url()` / `.datetime()`. All format regexes are
+ *   static module-level constants — no string→regex parsing on the
+ *   validation path. `.refine()` predicates that throw turn into a
+ *   regular validation issue rather than crashing the request.
+ *
+ *   Coercion is deliberately not shipped (`.coerce` is a footgun:
+ *   "0" → 0 vs "0" → "0" ambiguity, truthy/falsy edge cases).
+ *   Operators do explicit `s.preprocess(fn, schema)` instead.
+ *
+ *   Relationship to `b.forms.validate`: forms.validate carries
+ *   HTML-spec concerns (checkbox coercion, select option allowlist)
+ *   that don't belong on the general-purpose validator, so the two
+ *   surfaces stay distinct rather than one wrapping the other.
  *
- *   var result = schema.parse(input);     // throws SafeSchemaError
- *   var safe   = schema.safeParse(input); // → { ok, value?, errors? }
+ *   Surface (every schema has these chained methods unless noted):
  *
- *   // Errors carry per-field paths:
- *   //   [{ path: ["age"], code: "number/too-large", message: "must be ≤ 120" }]
+ *     Type constructors:
+ *       string()      .min, .max, .length, .regex, .email, .url, .uuid,
+ *                     .datetime (ISO-8601), .date (YYYY-MM-DD),
+ *                     .ip, .ipv4, .ipv6, .nonempty, .startsWith,
+ *                     .endsWith, .includes, .cuid, .ulid, .base64,
+ *                     .trim, .toLowerCase, .toUpperCase
+ *       number()      .int, .min, .max, .gt, .lt, .positive, .negative,
+ *                     .nonnegative, .nonpositive, .finite, .safe,
+ *                     .multipleOf
+ *       boolean()
+ *       literal(v)
+ *       enum_([...]) | oneOf([...])
+ *       null_(), undefined_(), any(), unknown()
+ *
+ *     Composites:
+ *       object({...})  .strict, .passthrough, .pick, .omit, .extend,
+ *                      .partial, .required
+ *       array(item)    .min, .max, .length, .nonempty
+ *       tuple([...])   .rest(item)
+ *       union([...])   first matching option wins
+ *       discriminatedUnion(key, [...])    tagged-union dispatch
+ *       record(value) | record(key, value)
+ *       lazy(() => schema)                 deferred (recursion)
+ *       preprocess(fn, schema)             pre-validation transform
+ *
+ *     Modifiers (any schema):
+ *       .optional(), .nullable(), .default(v|fn), .catch(v|fn),
+ *       .refine(fn, opts), .transform(fn), .pipe(next)
+ *
+ *   Deliberately not shipped (with structural reason): z.bigint /
+ *   z.date / z.map / z.set (no JSON representation), z.nativeEnum
+ *   / z.never / z.void / z.function (TypeScript-specific), z.coerce
+ *   (security foot-gun — use s.preprocess), z.intersection
+ *   (use .extend() for object schemas), z.brand (compile-time tag,
+ *   no runtime effect), per-schema errorMap (chain .refine() with
+ *   custom message instead).
  *
  * Design choices:
  *   - Schemas are immutable. Chaining returns a new schema with one
  *     additional check; the original is untouched. Cheap because
  *     checks are concat'd into a small array, not deep-copied.
- *   - parse() throws SafeSchemaError carrying the full issues array;
- *     safeParse() never throws (operator-friendly for HTTP boundaries).
  *   - .optional() means "may be undefined"; .nullable() means "may be
  *     null"; .default(v) means "if undefined, substitute v";
  *     .catch(v) means "on ANY validation failure, substitute v".
@@ -37,76 +90,10 @@
  *   - Objects are STRICT by default: unknown keys produce an issue.
  *     Use .passthrough() to retain unknown keys, .strict() to flip
  *     back if a parent .passthrough() set the mode.
- *
- * Surface (every schema has these chained methods unless noted):
- *
- *   Type constructors:
- *     string()      .min, .max, .length, .regex, .email, .url, .uuid,
- *                   .datetime (ISO-8601), .date (YYYY-MM-DD),
- *                   .ip, .ipv4, .ipv6, .nonempty, .startsWith, .endsWith,
- *                   .includes
- *     number()      .int, .min, .max, .gt, .lt, .positive, .negative,
- *                   .nonnegative, .nonpositive, .finite, .multipleOf
- *     boolean()
- *     literal(v)
- *     enum_([...]) | oneOf([...])
- *     null_(), undefined_(), any(), unknown()
- *
- *   Composites:
- *     object({ ... })   .strict, .passthrough, .pick, .omit, .extend,
- *                       .partial, .required (inverse of partial)
- *     array(item)       .min, .max, .length, .nonempty
- *     tuple([...])      .rest(item) for variadic tails
- *     union([...])      first matching wins
- *     discriminatedUnion(key, [...])  faster + clearer-errors variant
- *                                     for tagged unions
- *     record(value) | record(key, value)
- *     lazy(() => schema)              defer construction; for recursion
- *     preprocess(fn, schema)          run fn before validation
- *
- *   Modifiers (any schema):
- *     .optional()       value may be undefined
- *     .nullable()       value may be null
- *     .default(v|fn)    undefined → v (implies optional). Function form
- *                       is called per-parse for fresh values.
- *     .catch(v|fn)      any failure → v (escape hatch for operator
- *                       defaults; suppresses the error info, so use
- *                       sparingly)
- *     .refine(fn, opts) custom predicate — returns false to fail
- *     .transform(fn)    map the validated value to a new shape
- *     .pipe(next)       feed validated output through `next` schema
- *                       for a second round of validation
- *
- * Security guarantees:
- *   - Prototype-pollution defense: __proto__ / constructor / prototype
- *     keys are rejected at construction (object shape) and parse time
- *     (object + record input). Mirrors safe-json.js's POISONED_KEYS.
- *   - No code injection surface: regexes are static module-level
- *     constants; no string→regex parsing on the validation path; no
- *     eval/Function. Operator-supplied refine/transform fns are
- *     plain JS functions, not strings.
- *   - Predicate throws are caught: a refine() function throwing turns
- *     into a regular validation issue, not an unhandled exception.
  *   - Sync-only: no async refinements; operators await at the boundary.
  *
- * Deliberately not shipped (with structural reason):
- *   - z.bigint / z.date / z.map / z.set — no JSON representation; HTTP
- *     boundaries don't carry these. Use s.string().datetime() for
- *     ISO-8601 strings.
- *   - z.nativeEnum / z.never / z.void / z.function — TypeScript-specific.
- *   - z.coerce — loose-coercion is a security foot-gun (truthy/falsy
- *     ambiguity, "0" → 0 vs "0" → "0"). Operators do explicit
- *     s.preprocess(fn, schema) instead.
- *   - z.intersection — for object schemas use .extend(); intersections
- *     of unrelated schemas are structurally ambiguous.
- *   - z.brand — TypeScript compile-time tag with no runtime effect.
- *   - per-schema errorMap — operators chain .refine() with custom message.
- *
- * Relationship to forms.validate:
- *   forms.validate (HTML form spec validation) is a separate surface.
- *   Form specs carry HTML-specific concerns (checkbox coercion, select
- *   option allowlist) that don't belong on the general-purpose validator,
- *   so the two stay distinct rather than one wrapping the other.
+ * @card
+ *   Declarative input validation with a Zod-shaped chained-method surface.
  */
 
 var C = require("./constants");
@@ -129,6 +116,35 @@ var DATETIME_MAX_LEN = 100;   // ISO-8601 with offset + fractional seconds tops
 var CUID_MAX_LEN     = 50;    // CUID v1/v2 is 25 chars
 var ULID_MAX_LEN     = 50;    // ULID is exactly 26 chars
 
+/**
+ * @primitive b.safeSchema.SafeSchemaError
+ * @signature b.safeSchema.SafeSchemaError
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.string, b.safeSchema.object
+ *
+ * Error class thrown by every `b.safeSchema` primitive on
+ * construction-time misuse (bad shape / bad enum / bad union /
+ * poisoned key) and by `schema.parse(...)` on validation failure.
+ * Built via `b.framework.defineClass` and marked `alwaysPermanent`
+ * so it never round-trips through retry or transient-error logic.
+ * The thrown instance carries `.issues` — the full per-field
+ * issues array (`{ path, code, message }[]`) — so HTTP middleware
+ * can surface every failure in one 400 response.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   try {
+ *     s.string().min(3).parse("ab");
+ *   } catch (e) {
+ *     e instanceof s.SafeSchemaError;
+ *     // → true
+ *     e.issues[0].code;
+ *     // → "string/too-short"
+ *   }
+ */
 var SafeSchemaError = defineClass("SafeSchemaError", { alwaysPermanent: true });
 
 // Prototype-pollution defense — these key names are rejected in object
@@ -360,6 +376,43 @@ function _withCheck(schema, spec, check) {
 
 // ---- string ----
 
+/**
+ * @primitive b.safeSchema.string
+ * @signature b.safeSchema.string()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.number, b.safeSchema.object
+ *
+ * Construct a string-typed schema. Chain `.min`, `.max`, `.length`,
+ * `.regex`, `.email`, `.url`, `.uuid`, `.datetime`, `.date`, `.ipv4`,
+ * `.ipv6`, `.ip`, `.cuid`, `.ulid`, `.base64`, `.startsWith`,
+ * `.endsWith`, `.includes`, `.nonempty`, `.trim`, `.toLowerCase`,
+ * `.toUpperCase` to add checks and coercions. Each chained call
+ * returns a new immutable schema.
+ *
+ * The named-format methods (`.email` / `.url` / `.uuid` / etc.)
+ * apply a defensive length cap BEFORE running the regex so a
+ * hostile payload cannot drive the regex engine with an arbitrarily
+ * long string.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var name = s.string().min(1).max(80);
+ *   name.parse("alice");
+ *   // → "alice"
+ *
+ *   var email = s.string().trim().toLowerCase().email();
+ *   email.parse("  Alice@Example.COM  ");
+ *   // → "alice@example.com"
+ *
+ *   var safe = s.string().min(3).safeParse("ab");
+ *   safe.ok;
+ *   // → false
+ *   safe.errors[0].code;
+ *   // → "string/too-short"
+ */
 function string() {
   var spec = {
     kind: "string",
@@ -554,6 +607,37 @@ function _stringMethods(schema, spec) {
 
 // ---- number ----
 
+/**
+ * @primitive b.safeSchema.number
+ * @signature b.safeSchema.number()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.string, b.safeSchema.literal
+ *
+ * Construct a number-typed schema. Rejects `NaN` at the type check.
+ * Chain `.int`, `.min`, `.max`, `.gt`, `.lt`, `.positive`,
+ * `.negative`, `.nonnegative`, `.nonpositive`, `.finite`, `.safe`,
+ * `.multipleOf` to bound the value. `.safe()` enforces the
+ * `Number.isSafeInteger` range — important for IDs that round-trip
+ * through JSON (no BigInt support) and need to survive without
+ * precision loss.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var age = s.number().int().min(0).max(150);
+ *   age.parse(30);
+ *   // → 30
+ *
+ *   try { age.parse(200); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "number/too-large"
+ *
+ *   var price = s.number().finite().multipleOf(0.01);
+ *   price.parse(19.99);
+ *   // → 19.99
+ */
 function number() {
   var spec = {
     kind: "number",
@@ -630,6 +714,29 @@ function _numberMethods(schema, spec) {
 
 // ---- boolean ----
 
+/**
+ * @primitive b.safeSchema.boolean
+ * @signature b.safeSchema.boolean()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.literal, b.safeSchema.preprocess
+ *
+ * Construct a boolean-typed schema. Strict `typeof === "boolean"`
+ * check — does not coerce truthy/falsy values. To accept the strings
+ * `"true"` / `"false"` from query parameters, wrap in
+ * `s.preprocess(fn, s.boolean())`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   s.boolean().parse(true);
+ *   // → true
+ *
+ *   try { s.boolean().parse("true"); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "type"
+ */
 function boolean() {
   return _baseSchema({
     kind: "boolean",
@@ -642,6 +749,29 @@ function boolean() {
 
 // ---- literal ----
 
+/**
+ * @primitive b.safeSchema.literal
+ * @signature b.safeSchema.literal(expected)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.enum_, b.safeSchema.discriminatedUnion
+ *
+ * Construct a schema that accepts exactly one specific value
+ * (compared via `===`). Useful as the discriminator on tagged
+ * unions — see `s.discriminatedUnion`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var version = s.literal("v1");
+ *   version.parse("v1");
+ *   // → "v1"
+ *
+ *   try { version.parse("v2"); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "literal"
+ */
 function literal(expected) {
   return _baseSchema({
     kind: "literal",
@@ -656,6 +786,36 @@ function literal(expected) {
 
 // ---- enum / oneOf ----
 
+/**
+ * @primitive b.safeSchema.enum_
+ * @signature b.safeSchema.enum_(values)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.literal, b.safeSchema.union
+ *
+ * Construct a schema that accepts any value from the given
+ * non-empty array (compared via `Set.has`). Also exported as
+ * `b.safeSchema.oneOf` because `enum` is a reserved word in some
+ * tooling. Throws `SafeSchemaError` (`safe-schema/bad-enum`) when
+ * `values` is not a non-empty array.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var role = s.enum_(["admin", "editor", "viewer"]);
+ *   role.parse("editor");
+ *   // → "editor"
+ *
+ *   try { role.parse("guest"); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "enum"
+ *
+ *   // oneOf is the same primitive under a friendlier name.
+ *   var same = s.oneOf(["a", "b"]);
+ *   same.parse("a");
+ *   // → "a"
+ */
 function enum_(values) {
   if (!Array.isArray(values) || values.length === 0) {
     throw new SafeSchemaError("safe-schema/bad-enum",
@@ -676,6 +836,29 @@ function enum_(values) {
 
 // ---- null / undefined / any / unknown ----
 
+/**
+ * @primitive b.safeSchema.null_
+ * @signature b.safeSchema.null_()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.undefined_, b.safeSchema.any
+ *
+ * Construct a schema that accepts only `null`. Trailing-underscore
+ * name because `null` is a reserved word. Useful inside unions
+ * (e.g. `s.union([s.string(), s.null_()])`), though
+ * `s.string().nullable()` is the more common idiom.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   s.null_().parse(null);
+ *   // → null
+ *
+ *   try { s.null_().parse(0); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "type"
+ */
 function null_() {
   return _baseSchema({
     kind: "null",
@@ -687,6 +870,28 @@ function null_() {
   });
 }
 
+/**
+ * @primitive b.safeSchema.undefined_
+ * @signature b.safeSchema.undefined_()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.null_, b.safeSchema.any
+ *
+ * Construct a schema that accepts only `undefined`. Trailing-
+ * underscore name because `undefined` shadows poorly. The schema is
+ * implicitly `optional` — `parse(undefined)` succeeds.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   s.undefined_().parse(undefined);
+ *   // → undefined
+ *
+ *   try { s.undefined_().parse(null); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "type"
+ */
 function undefined_() {
   return _baseSchema({
     kind: "undefined",
@@ -697,6 +902,28 @@ function undefined_() {
   });
 }
 
+/**
+ * @primitive b.safeSchema.any
+ * @signature b.safeSchema.any()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.unknown, b.safeSchema.preprocess
+ *
+ * Construct a schema that accepts any value, including `null` and
+ * `undefined`. Useful as a placeholder while iterating on a schema
+ * shape, or inside `s.record(s.any())` when the operator wants the
+ * keys validated but not the values.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   s.any().parse({ anything: "goes" });
+ *   // → { anything: "goes" }
+ *
+ *   s.any().parse(null);
+ *   // → null
+ */
 function any() {
   return _baseSchema({
     kind: "any",
@@ -706,10 +933,73 @@ function any() {
   });
 }
 
+/**
+ * @primitive b.safeSchema.unknown
+ * @signature b.safeSchema.unknown()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.any
+ *
+ * Alias for `b.safeSchema.any`. Some operators prefer the spelling
+ * `unknown` to signal "we accept anything but expect downstream
+ * code to narrow the type". Behavior is identical.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   s.unknown().parse({ raw: 1 });
+ *   // → { raw: 1 }
+ */
 function unknown() { return any(); }
 
 // ---- object ----
 
+/**
+ * @primitive b.safeSchema.object
+ * @signature b.safeSchema.object(shape)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.record, b.safeSchema.discriminatedUnion
+ *
+ * Construct an object schema from a `{ key: schema }` shape map.
+ * Strict by default — unknown keys produce an `object/unknown-key`
+ * issue. Chain `.passthrough()` to retain extras, `.strict()` to
+ * flip back, `.pick`, `.omit`, `.extend`, `.partial`, `.required`
+ * to derive related shapes.
+ *
+ * Prototype-pollution defense — `__proto__` / `constructor` /
+ * `prototype` keys are rejected at shape-construction time AND at
+ * parse time regardless of mode (`.passthrough()` does NOT permit
+ * them). Throws `SafeSchemaError`
+ * (`safe-schema/poisoned-shape-key` / `safe-schema/bad-shape`) on
+ * invalid input.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var user = s.object({
+ *     email: s.string().email(),
+ *     age:   s.number().int().min(0).max(150),
+ *   });
+ *
+ *   user.parse({ email: "alice@example.com", age: 30 });
+ *   // → { email: "alice@example.com", age: 30 }
+ *
+ *   // Unknown keys rejected by default.
+ *   try { user.parse({ email: "a@b.com", age: 30, extra: 1 }); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "object/unknown-key"
+ *
+ *   // Prototype-pollution attempt rejected even with passthrough.
+ *   var loose = user.passthrough();
+ *   var report = loose.safeParse({ email: "a@b.com", age: 30, __proto__: { admin: true } });
+ *   report.ok;
+ *   // → false
+ *   report.errors[0].code;
+ *   // → "object/poisoned-key"
+ */
 function object(shape) {
   if (shape == null || typeof shape !== "object") {
     throw new SafeSchemaError("safe-schema/bad-shape",
@@ -861,6 +1151,33 @@ function _objectWithMode(shape, keys, mode) {
 
 // ---- array ----
 
+/**
+ * @primitive b.safeSchema.array
+ * @signature b.safeSchema.array(itemSchema)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.tuple, b.safeSchema.record
+ *
+ * Construct an array schema where every element is validated
+ * against `itemSchema`. Chain `.min`, `.max`, `.length`, `.nonempty`
+ * to bound the length. Issues from individual items carry their
+ * index in the path (e.g. `[3]`). Throws `SafeSchemaError`
+ * (`safe-schema/bad-item`) when the item argument is not a schema.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var tags = s.array(s.string().min(1)).max(10);
+ *   tags.parse(["alpha", "beta"]);
+ *   // → ["alpha", "beta"]
+ *
+ *   var report = tags.safeParse(["ok", "", "also-ok"]);
+ *   report.ok;
+ *   // → false
+ *   report.errors[0].path;
+ *   // → [1]
+ */
 function array(itemSchema) {
   if (!itemSchema || typeof itemSchema._run !== "function") {
     throw new SafeSchemaError("safe-schema/bad-item",
@@ -917,6 +1234,32 @@ function _arrayMethods(schema, spec) {
 
 // ---- tuple ----
 
+/**
+ * @primitive b.safeSchema.tuple
+ * @signature b.safeSchema.tuple(items)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.array, b.safeSchema.union
+ *
+ * Construct a fixed-length heterogeneous array schema. `items` is
+ * a non-empty array of schemas, one per slot. Chain `.rest(item)`
+ * to allow a variadic tail (common for `[verb, ...args]` /
+ * `[event, payload, ...metadata]` shapes). Throws
+ * `SafeSchemaError` (`safe-schema/bad-tuple`) on invalid input.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var pair = s.tuple([s.string(), s.number()]);
+ *   pair.parse(["count", 42]);
+ *   // → ["count", 42]
+ *
+ *   // Variadic tail via .rest()
+ *   var event = s.tuple([s.string()]).rest(s.number());
+ *   event.parse(["sum", 1, 2, 3]);
+ *   // → ["sum", 1, 2, 3]
+ */
 function tuple(items) {
   if (!Array.isArray(items) || items.length === 0) {
     throw new SafeSchemaError("safe-schema/bad-tuple",
@@ -983,6 +1326,35 @@ function _tupleWithRest(items, restSchema) {
 
 // ---- union ----
 
+/**
+ * @primitive b.safeSchema.union
+ * @signature b.safeSchema.union(options)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.discriminatedUnion, b.safeSchema.enum_
+ *
+ * Construct a schema that accepts a value matching ANY of the
+ * given option schemas. First match wins. When no option matches,
+ * issues from every branch are collected in the failure for deep
+ * diagnostics, plus a parent-level `union` issue summarizing the
+ * miss. For tagged-variant shapes prefer
+ * `s.discriminatedUnion` — it dispatches in O(1) on the tag and
+ * produces clearer error messages.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var idOrName = s.union([s.number().int().positive(), s.string().min(1)]);
+ *   idOrName.parse(42);
+ *   // → 42
+ *   idOrName.parse("alice");
+ *   // → "alice"
+ *
+ *   try { idOrName.parse(true); }
+ *   catch (e) { e.issues[0].code; }
+ *   // → "union"
+ */
 function union(options) {
   if (!Array.isArray(options) || options.length === 0) {
     throw new SafeSchemaError("safe-schema/bad-union",
@@ -1020,6 +1392,34 @@ function union(options) {
 // record(value)               — string keys, schema-typed values
 // record(keySchema, value)    — both keys and values are schema-validated
 
+/**
+ * @primitive b.safeSchema.record
+ * @signature b.safeSchema.record(a, b)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.object, b.safeSchema.array
+ *
+ * Construct a schema for an object whose KEYS are arbitrary strings
+ * and whose VALUES match a given schema. Two call shapes:
+ * `record(valueSchema)` accepts any string key;
+ * `record(keySchema, valueSchema)` validates both keys and values.
+ * Prototype-pollution defense — `__proto__` / `constructor` /
+ * `prototype` keys are rejected at parse time, mirroring `s.object`.
+ * Throws `SafeSchemaError` on invalid arguments.
+ *
+ * @example
+ *   var bjs = require("blamejs");
+ *   var s = bjs.safeSchema;
+ *
+ *   var counts = s.record(s.number().int().nonnegative());
+ *   counts.parse({ apples: 3, pears: 0 });
+ *   // → { apples: 3, pears: 0 }
+ *
+ *   // Validate keys too: only ULIDs allowed.
+ *   var byId = s.record(s.string().ulid(), s.string());
+ *   byId.parse({ "01HF5Z6Q9P8R7S4T3V2W1X0Y9Z": "alice" });
+ *   // → { "01HF5Z6Q9P8R7S4T3V2W1X0Y9Z": "alice" }
+ */
 function record(a, b) {
   var keySchema, valueSchema;
   if (b === undefined) {
@@ -1093,6 +1493,41 @@ function record(a, b) {
 // literal schema. Mismatched discriminator fails fast with a clear
 // "expected one of [...]" message rather than burying the operator in
 // per-branch issues.
+/**
+ * @primitive b.safeSchema.discriminatedUnion
+ * @signature b.safeSchema.discriminatedUnion(discriminator, options)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.union, b.safeSchema.literal
+ *
+ * Construct a tagged-union schema. `discriminator` names a key
+ * present on every option as a `s.literal(...)` schema; the
+ * validator dispatches in O(1) on that key's value rather than
+ * trying every option in turn (faster + clearer error messages
+ * than `s.union`). Every option must be an object schema whose
+ * shape carries a literal at the discriminator key. The
+ * discriminator name itself cannot be `__proto__` /
+ * `constructor` / `prototype`. Throws `SafeSchemaError` on
+ * invalid input.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var event = s.discriminatedUnion("kind", [
+ *     s.object({ kind: s.literal("created"), at: s.string().datetime() }),
+ *     s.object({ kind: s.literal("deleted"), reason: s.string() }),
+ *   ]);
+ *
+ *   event.parse({ kind: "created", at: "2026-01-01T00:00:00Z" });
+ *   // → { kind: "created", at: "2026-01-01T00:00:00Z" }
+ *
+ *   var report = event.safeParse({ kind: "unknown" });
+ *   report.ok;
+ *   // → false
+ *   report.errors[0].code;
+ *   // → "discriminated-union/no-match"
+ */
 function discriminatedUnion(discriminator, options) {
   if (typeof discriminator !== "string" || discriminator.length === 0) {
     throw new SafeSchemaError("safe-schema/bad-discriminator",
@@ -1155,6 +1590,42 @@ function discriminatedUnion(discriminator, options) {
 //
 // fn errors propagate as a 'preprocess' issue at the parent path; they
 // don't crash the validate call.
+/**
+ * @primitive b.safeSchema.preprocess
+ * @signature b.safeSchema.preprocess(fn, inner)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.string, b.safeSchema.number
+ *
+ * Wrap a schema with a transform that runs BEFORE validation.
+ * Common at HTTP boundaries where query strings arrive as strings
+ * but the operator wants a number / boolean schema downstream.
+ * Errors thrown by `fn` propagate as a `preprocess` issue at the
+ * parent path rather than crashing the parse. Throws
+ * `SafeSchemaError` (`safe-schema/bad-preprocess`) when args are
+ * the wrong shape.
+ *
+ * Prefer `s.preprocess` over a hypothetical `.coerce` because
+ * coercion ambiguity (`"0" → 0` vs `"0" → "0"`) is a security
+ * foot-gun; `s.preprocess` makes the conversion explicit at the
+ * call site.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var port = s.preprocess(
+ *     function (v) { return Number(v); },
+ *     s.number().int().min(1).max(65535)
+ *   );
+ *
+ *   port.parse("8080");
+ *   // → 8080
+ *
+ *   var report = port.safeParse("not-a-port");
+ *   report.ok;
+ *   // → false
+ */
 function preprocess(fn, inner) {
   if (typeof fn !== "function") {
     throw new SafeSchemaError("safe-schema/bad-preprocess",
@@ -1192,6 +1663,34 @@ function preprocess(fn, inner) {
 //
 // The function is called lazily and cached per-call site; cycles in the
 // returned schema are fine.
+/**
+ * @primitive b.safeSchema.lazy
+ * @signature b.safeSchema.lazy(getter)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.object, b.safeSchema.array
+ *
+ * Defer schema construction until first parse, enabling recursive
+ * shapes (comment threads, file-tree nodes, AST nodes). `getter` is
+ * a no-arg function that returns the schema; it's called once on
+ * the first parse and cached. The returned schema can reference
+ * its enclosing variable, breaking the chicken-and-egg cycle.
+ * Throws `SafeSchemaError` (`safe-schema/bad-lazy`) when `getter`
+ * is not a function.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var commentSchema = s.object({
+ *     id:       s.string(),
+ *     replies:  s.array(s.lazy(function () { return commentSchema; })),
+ *   });
+ *
+ *   var input = { id: "a", replies: [{ id: "b", replies: [] }] };
+ *   commentSchema.parse(input);
+ *   // → { id: "a", replies: [{ id: "b", replies: [] }] }
+ */
 function lazy(getter) {
   if (typeof getter !== "function") {
     throw new SafeSchemaError("safe-schema/bad-lazy",
@@ -1215,7 +1714,52 @@ function lazy(getter) {
 
 // ---- top-level modifier helpers ----
 
+/**
+ * @primitive b.safeSchema.optional
+ * @signature b.safeSchema.optional(inner)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.nullable
+ *
+ * Composition-style alias for `inner.optional()`. Returns a schema
+ * that accepts `undefined` in addition to whatever `inner` accepts.
+ * Equivalent to chaining `.optional()` on the schema; provided for
+ * operators who prefer composition over chaining (e.g. mapping over
+ * a list of schemas).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var maybeName = s.optional(s.string().min(1));
+ *   maybeName.parse(undefined);
+ *   // → undefined
+ *   maybeName.parse("alice");
+ *   // → "alice"
+ */
 function optional(inner) { return inner.optional(); }
+
+/**
+ * @primitive b.safeSchema.nullable
+ * @signature b.safeSchema.nullable(inner)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeSchema.optional
+ *
+ * Composition-style alias for `inner.nullable()`. Returns a schema
+ * that accepts `null` in addition to whatever `inner` accepts.
+ * Compose with `s.optional` for "may be undefined OR null".
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var s = b.safeSchema;
+ *
+ *   var maybeAge = s.nullable(s.number().int().min(0));
+ *   maybeAge.parse(null);
+ *   // → null
+ *   maybeAge.parse(30);
+ *   // → 30
+ */
 function nullable(inner) { return inner.nullable(); }
 
 module.exports = {