@anthonyalayo/zod 0.0.0-stage → 4.7.1

package/src/v4/core/json-schema.ts

@@ -0,0 +1,148 @@
+export type Schema =
+  | ObjectSchema
+  | ArraySchema
+  | StringSchema
+  | NumberSchema
+  | IntegerSchema
+  | BooleanSchema
+  | NullSchema;
+
+// export type JsonType = "object" | "array" | "string" | "number" | "boolean" | "null" | "integer";
+
+// export interface JSONSchema {
+//   type?: string ;
+//   $id?: string ;
+//   id?: string ;
+//   $schema?: string ;
+//   $ref?: string ;
+//   $anchor?: string ;
+//   $defs?: { [key: string]: JSONSchema } ;
+//   definitions?: { [key: string]: JSONSchema } ;
+//   $comment?: string ;
+//   title?: string ;
+//   description?: string ;
+//   default?: unknown ;
+//   examples?: unknown[] ;
+//   readOnly?: boolean ;
+//   writeOnly?: boolean ;
+//   deprecated?: boolean ;
+//   allOf?: JSONSchema[] ;
+//   anyOf?: JSONSchema[] ;
+//   oneOf?: JSONSchema[] ;
+//   not?: JSONSchema ;
+//   if?: JSONSchema ;
+//   then?: JSONSchema ;
+//   else?: JSONSchema ;
+//   enum?: Array<string | number | boolean | null> ;
+//   const?: string | number | boolean | null ;
+//   [k: string]: unknown;
+
+//   /** A special key used as an intermediate representation of extends-style relationships. Omitted as a $ref with additional properties. */
+//   // _ref?: JSONSchema;
+//   _prefault?: unknown ;
+// }
+
+export type _JSONSchema = boolean | JSONSchema;
+export type SchemaType = "object" | "array" | "string" | "number" | "boolean" | "null" | "integer";
+export type JSONSchema = {
+  [k: string]: unknown;
+  $schema?:
+    | "https://json-schema.org/draft/2020-12/schema"
+    | "http://json-schema.org/draft-07/schema#"
+    | "http://json-schema.org/draft-04/schema#";
+  $id?: string;
+  $anchor?: string;
+  $ref?: string;
+  $dynamicRef?: string;
+  $dynamicAnchor?: string;
+  $vocabulary?: Record<string, boolean>;
+  $comment?: string;
+  $defs?: Record<string, JSONSchema>;
+  type?: SchemaType | SchemaType[];
+  additionalItems?: _JSONSchema;
+  unevaluatedItems?: _JSONSchema;
+  prefixItems?: _JSONSchema[];
+  items?: _JSONSchema | _JSONSchema[];
+  contains?: _JSONSchema;
+  additionalProperties?: _JSONSchema;
+  unevaluatedProperties?: _JSONSchema;
+  properties?: Record<string, _JSONSchema>;
+  patternProperties?: Record<string, _JSONSchema>;
+  dependentSchemas?: Record<string, _JSONSchema>;
+  propertyNames?: _JSONSchema;
+  if?: _JSONSchema;
+  then?: _JSONSchema;
+  else?: _JSONSchema;
+  allOf?: JSONSchema[];
+  anyOf?: JSONSchema[];
+  oneOf?: JSONSchema[];
+  not?: _JSONSchema;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: number | boolean;
+  minimum?: number;
+  exclusiveMinimum?: number | boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxContains?: number;
+  minContains?: number;
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  dependentRequired?: Record<string, string[]>;
+  enum?: Array<string | number | boolean | null>;
+  const?: string | number | boolean | null;
+
+  // metadata
+  id?: string;
+  title?: string;
+  description?: string;
+  default?: unknown;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  nullable?: boolean;
+  examples?: unknown[];
+  format?: string;
+  contentMediaType?: string;
+  contentEncoding?: string;
+  contentSchema?: JSONSchema;
+
+  // internal
+  _prefault?: unknown;
+};
+
+// for backwards compatibility
+export type BaseSchema = JSONSchema;
+
+export interface ObjectSchema extends JSONSchema {
+  type: "object";
+}
+
+export interface ArraySchema extends JSONSchema {
+  type: "array";
+}
+
+export interface StringSchema extends JSONSchema {
+  type: "string";
+}
+
+export interface NumberSchema extends JSONSchema {
+  type: "number";
+}
+
+export interface IntegerSchema extends JSONSchema {
+  type: "integer";
+}
+
+export interface BooleanSchema extends JSONSchema {
+  type: "boolean";
+}
+
+export interface NullSchema extends JSONSchema {
+  type: "null";
+}

package/src/v4/core/memoizer.ts

@@ -0,0 +1,404 @@
+import type * as errors from "./errors.js";
+import type { $ZodMemoizer, $ZodType, $ZodTypeDef, ParseContextInternal, ParsePayload } from "./schemas.js";
+import * as util from "./util.js";
+
+export class $ZodCyclicError extends Error {
+  constructor() {
+    super(`Cannot parse a reference cycle that closes through a transform`);
+    this.name = "ZodCyclicError";
+  }
+}
+
+interface Entry {
+  value: unknown;
+  /** `null` during the visit's synchronous part, so a hit then is an ancestor; a `Link` while async work is left; then what `record` returns. */
+  issues: unknown[] | Link | null;
+}
+
+/** A visit in an async parse, carried on the context because a continuation keeps the one it was given. */
+interface Link {
+  up: Link | undefined;
+  /** Settles once the entry has its issues. */
+  done: Promise<unknown> | undefined;
+  /** The parents of the visits waiting on this one. */
+  waiters: Set<Link> | undefined;
+}
+
+interface State {
+  /** Weak throughout because `attach` caches a bucket on the schema instance, which outlives the parse. */
+  buckets: WeakMap<$ZodType, WeakMap<object, Entry>>;
+  /** The same for a pass with checks skipped, whose results a checked pass must never reuse. */
+  unchecked: WeakMap<$ZodType, WeakMap<object, Entry>> | undefined;
+  /** Nodes a back-edge resolved to before they finished. */
+  backEdges: WeakSet<object> | undefined;
+}
+
+/** Keyed off the context object every schema in one parse call already shares. */
+const STATE = "~memo";
+type WithState = { [STATE]?: State; "~link"?: Link };
+
+const NO_ISSUES: unknown[] = [];
+
+// a value a cycle can close through
+function isRef(value: unknown): value is object {
+  return value !== null && typeof value === "object";
+}
+
+// the issues from `start` on (an encode runs a node's own checks first), each by reference beside its path length since receivers only prepend, or copied while pathless
+function record(issues: errors.$ZodRawIssue[], start: number): unknown[] {
+  if (issues.length <= start) return NO_ISSUES;
+  const out: unknown[] = [];
+  for (let i = start; i < issues.length; i++) {
+    const iss = issues[i]!;
+    out.push(iss.path ? iss : { ...iss }, iss.path?.length);
+  }
+  return out;
+}
+
+// a fresh copy per hand-out, its path cut back to the recorded length
+function replay(rec: unknown[], into: errors.$ZodRawIssue[]): void {
+  for (let i = 0; i < rec.length; i += 2) {
+    const iss = rec[i] as errors.$ZodRawIssue;
+    into.push(iss.path ? { ...iss, path: iss.path.slice(iss.path.length - (rec[i + 1] as number)) } : { ...iss });
+  }
+}
+
+// whether `target` can't finish until `from` does: it is above `from`, or above a visit waiting on something that is
+function blockedOn(from: Link | undefined, target: Link): boolean {
+  // a wait this visit already has adds no edge, so it can't close a loop
+  if (from && target.waiters?.has(from)) return false;
+  const seen = new Set<Link>();
+  const pending = [from];
+  while (pending.length) {
+    for (let link = pending.pop(); link && !seen.has(link); link = link.up) {
+      if (link === target) return true;
+      seen.add(link);
+      if (link.waiters) for (const waiter of link.waiters) pending.push(waiter);
+    }
+  }
+  return false;
+}
+
+// out of line so the sync path captures nothing more
+function waitFor(hit: Entry, link: Link, up: Link | undefined, payload: ParsePayload): Promise<ParsePayload> {
+  if (up) {
+    link.waiters ??= new Set();
+    link.waiters.add(up);
+  }
+  return link.done!.then(() => {
+    replay(hit.issues as unknown[], payload.issues);
+    return payload;
+  });
+}
+
+const recursive: WeakMap<object, boolean> = /*@__PURE__*/ new WeakMap();
+
+/** What the walk established, in order of certainty: ordered so the strongest answer among children wins. */
+const NONE = 0;
+const ASSUMED = 1;
+const PROVEN = 2;
+type Answer = typeof NONE | typeof ASSUMED | typeof PROVEN;
+
+/** Whether this schema's subtree contains a cycle, so one parse can re-enter it. */
+function isRecursive(inst: $ZodType, stack: Set<object>, resolve: boolean): Answer {
+  const cached = recursive.get(inst);
+  if (cached !== undefined) return cached ? PROVEN : NONE;
+  // Relative to the walk in progress, so not cached.
+  if (stack.has(inst)) return PROVEN;
+  stack.add(inst);
+
+  let result: Answer = NONE;
+  const check = (child: any) => {
+    if (result !== PROVEN && child?._zod) {
+      const answer = isRecursive(child, stack, resolve);
+      if (answer > result) result = answer;
+    }
+  };
+
+  // `Reflect.ownKeys` rather than `Object.keys`, so a cycle through a declared symbol key is still seen
+  const shape = (sh: object, spread: boolean): Answer => {
+    let answer: Answer = NONE;
+    for (const key of Reflect.ownKeys(sh)) {
+      const desc = Object.getOwnPropertyDescriptor(sh, key);
+      // a Proxy can list a key it has no descriptor for, which nothing can parse
+      if (!desc) continue;
+      // an object resolves its shape by spread, so a key it does not enumerate is never parsed; `z.properties` reads every own key and so keeps them all
+      if (spread && !desc.enumerable) continue;
+      // resolving runs user code, and a factory mints a fresh subtree per read, so an edge the walk can't follow counts as a cycle
+      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve) : NONE;
+      if (child > answer) answer = child;
+    }
+    return answer;
+  };
+
+  const merge = (answer: Answer) => {
+    if (answer > result) result = answer;
+  };
+
+  const def = inst._zod.def as any;
+  const kind = def.type as $ZodTypeDef["type"];
+  switch (kind) {
+    case "object": {
+      const raw = util.rawShape(def);
+      // a def with no raw shape answers `shape` from an accessor of its own, and running that can mint a whole fresh subtree
+      merge(raw ? shape(raw, true) : ASSUMED);
+      check(def.catchall);
+      break;
+    }
+    case "array":
+      check(def.element);
+      break;
+    case "tuple":
+      for (const el of def.items) check(el);
+      check(def.rest);
+      break;
+    case "record":
+    case "map":
+      check(def.keyType);
+      check(def.valueType);
+      break;
+    case "set":
+      check(def.valueType);
+      break;
+    case "union":
+      for (const el of def.options) check(el);
+      break;
+    case "intersection":
+      check(def.left);
+      check(def.right);
+      break;
+    case "optional":
+    case "nullable":
+    case "default":
+    case "prefault":
+    case "catch":
+    case "readonly":
+    case "nonoptional":
+    case "promise":
+    case "success":
+      check(def.innerType);
+      break;
+    case "pipe":
+      check(def.in);
+      check(def.out);
+      break;
+    case "function":
+      check(def.input);
+      check(def.output);
+      break;
+    // `$ZodLazy` caches its inner on the def, so a resolved edge is followed exactly
+    case "lazy": {
+      const inner = def._cachedInner ?? (resolve ? (inst as any)._zod.innerType : undefined);
+      // walked with resolution off: one hop sees past the deferral, and a lazy that yields only another unresolved lazy is generative, so it stops there
+      merge(inner ? isRecursive(inner, stack, false) : ASSUMED);
+      break;
+    }
+    // a leaf by choice: `parts` are regex fragments, not data positions
+    case "template_literal":
+    // leaves
+    case "string":
+    case "number":
+    case "int":
+    case "boolean":
+    case "bigint":
+    case "symbol":
+    case "undefined":
+    case "null":
+    case "void":
+    case "never":
+    case "any":
+    case "unknown":
+    case "date":
+    case "nan":
+    case "enum":
+    case "literal":
+    case "file":
+    case "transform":
+    case "custom":
+      break;
+    default: {
+      // a new built-in kind becomes a compile error here
+      kind satisfies never;
+      // a user-defined kind can still hold children, and only its author knows where, so fall back to scanning the def — skipping accessors, since reading one can run user code
+      for (const key in def) {
+        const desc = Object.getOwnPropertyDescriptor(def, key);
+        if (!desc || desc.get) continue;
+        const value = desc.value;
+        if (!value || typeof value !== "object") continue;
+        if (value._zod) check(value);
+        else if (Array.isArray(value)) for (const el of value) check(el);
+      }
+    }
+  }
+
+  stack.delete(inst);
+  return settle(inst, result);
+}
+
+/** An assumed answer must not outlive the resolution that settles it, so only a certain one is cached. */
+function settle(inst: $ZodType, answer: Answer): Answer {
+  if (answer !== ASSUMED) recursive.set(inst, answer === PROVEN);
+  return answer;
+}
+
+/**
+ * Whether one parse can re-enter this schema, i.e. its subtree contains a cycle.
+ * Exported for `z.compile`, which refuses to compile such a schema: cycle
+ * breaking is driven from here off state keyed on the parse context, and a
+ * generated fast path has no context to key on.
+ */
+export function isRecursiveSchema(inst: $ZodType): boolean {
+  // z.compile never parses, so nothing would ever resolve a lazy for it; it runs once and already treats a throw here as recursive
+  return isRecursive(inst, new Set(), true) !== NONE;
+}
+
+function bucketFor(buckets: State["buckets"], inst: $ZodType): WeakMap<object, Entry> {
+  let bucket = buckets.get(inst);
+  if (!bucket) {
+    bucket = new WeakMap();
+    buckets.set(inst, bucket);
+  }
+  return bucket;
+}
+
+// Set immediately before delegating to core and cleared immediately after, so `alloc` registers only for a visit this module is driving.
+let handoff: WeakMap<object, Entry> | undefined;
+
+// Allocated but unfinished entries. `alloc` and the matching pop both happen in the synchronous part of a parse, so they nest even when children are async, and one stack serves every schema.
+const open: Entry[] = [];
+
+const memo: $ZodMemoizer = {
+  alloc(_inst, payload, empty) {
+    const bucket = handoff;
+    if (!bucket) return empty;
+    handoff = undefined;
+    const entry: Entry = { value: empty, issues: null };
+    bucket.set(payload.value as object, entry);
+    open.push(entry);
+    return empty;
+  },
+
+  guard(inst) {
+    inst._zod.deferred ??= [];
+    inst._zod.deferred.push(() => {
+      const base = inst._zod.parse;
+      const wrapped = (payload: ParsePayload, ctx: ParseContextInternal): util.MaybeAsync<ParsePayload> => {
+        // The value is a placeholder a back-edge is still waiting on, so the cycle closes through this transform. Its output can't exist in time to bind.
+        if (ctx.direction !== "backward" && isBackEdge(ctx, payload.value)) throw new $ZodCyclicError();
+        return base(payload, ctx);
+      };
+      inst._zod.parse = wrapped;
+      if (inst._zod.run === base) inst._zod.run = wrapped;
+    });
+  },
+
+  attach(inst) {
+    let isRecursiveInst: boolean | undefined;
+    let rechecked = false;
+    // a recursive schema is re-entered many times per pass and its bucket never changes
+    let lastBuckets: State["buckets"] | undefined;
+    let lastBucket: WeakMap<object, Entry> | undefined;
+
+    // Wraps `parse` in a deferred so it sees the container's final parse. Core's own deferred copies `parse` into `run` when there are no checks, and it ran first, so `run` is patched to match; with checks, `run` reads `parse` dynamically.
+    inst._zod.deferred ??= [];
+    inst._zod.deferred.push(() => {
+      const base = inst._zod.parse;
+
+      const wrapped = (payload: ParsePayload, ctx: ParseContextInternal): util.MaybeAsync<ParsePayload> => {
+        if (isRecursiveInst === undefined) {
+          const walked = isRecursive(inst, new Set(), false);
+          if (walked === NONE) {
+            // Nothing here can ever fire, so take it back out.
+            inst._zod.parse = base;
+            if (inst._zod.run === wrapped) inst._zod.run = base;
+            return base(payload, ctx);
+          }
+          // this parse resolves the deferred edges on its own path, so ask once more before latching
+          if (walked === PROVEN || rechecked) isRecursiveInst = true;
+          else rechecked = true;
+        }
+
+        const input = payload.value;
+        if (!isRef(input)) return base(payload, ctx);
+
+        let state = (ctx as WithState)[STATE];
+        if (!state) {
+          state = { buckets: new WeakMap(), unchecked: undefined, backEdges: undefined };
+          (ctx as WithState)[STATE] = state;
+        }
+
+        // an encode's check-free first pass shares the state through its spread context, so it keeps buckets of its own
+        if (ctx.skipChecks) state.unchecked ??= new WeakMap();
+        const buckets = ctx.skipChecks ? state.unchecked! : state.buckets;
+        // keyed on the pass, since an async visit hands its children a context of their own that must not outlive the parse
+        if (lastBuckets !== buckets) {
+          lastBuckets = buckets;
+          lastBucket = bucketFor(buckets, inst);
+        }
+        const bucket = lastBucket!;
+
+        const hit = bucket.get(input);
+        if (hit) {
+          payload.value = hit.value;
+          const issues = hit.issues;
+          if (Array.isArray(issues)) {
+            replay(issues, payload.issues);
+          } else if (issues && !blockedOn((ctx as WithState)["~link"], issues)) {
+            // a concurrent visit holds the entry and may discard its issues, so reuse them only once it finishes
+            return waitFor(hit, issues, (ctx as WithState)["~link"], payload);
+          } else {
+            // still being parsed by a visit that needs this one: its own checks cover it, so skip them here
+            payload.memo = true;
+            state.backEdges ??= new WeakSet();
+            state.backEdges.add(hit.value as object);
+          }
+          return payload;
+        }
+
+        let link: Link | undefined;
+        if (ctx.async) {
+          link = { up: (ctx as WithState)["~link"], done: undefined, waiters: undefined };
+          // a literal key, since a computed one here cost 3x
+          ctx = { ...ctx, "~link": link } as ParseContextInternal;
+        }
+
+        handoff = bucket;
+        const depth = open.length;
+        const start = payload.issues.length;
+        const result = base(payload, ctx);
+        handoff = undefined;
+        // A container that rejected its input outright allocated nothing.
+        const entry = open.length > depth ? open.pop()! : undefined;
+
+        // Both paths written out so the sync one allocates no closure. It runs once per node, and capturing here cost more than everything else combined.
+        if (result instanceof Promise) {
+          const done = result.then((r) => {
+            if (entry) entry.issues = record(r.issues, start);
+            return r;
+          });
+          if (entry && link) {
+            link.done = done;
+            entry.issues = link;
+          }
+          return done;
+        }
+        if (entry) entry.issues = record(result.issues, start);
+        return result;
+      };
+
+      inst._zod.parse = wrapped;
+      if (inst._zod.run === base) inst._zod.run = wrapped;
+    });
+  },
+};
+
+/** The memoizer that gives containers cycle support. `zod` installs it by default; `zod/mini` opts in with `config({ memoizer: memoizer() })`. */
+export function memoizer(): $ZodMemoizer {
+  return memo;
+}
+
+/** Whether this value is a node a back-edge resolved to before it finished. */
+export function isBackEdge(ctx: object, value: unknown): boolean {
+  const backEdges = (ctx as WithState)[STATE]?.backEdges;
+  return backEdges !== undefined && isRef(value) && backEdges.has(value);
+}