@drzl/validation-core 3.16.4 → 3.17.0

package/dist/index.cjs

@@ -36,11 +36,15 @@ __export(index_exports, {
   COLUMN_FORMATS: () => COLUMN_FORMATS,
   DEFAULT_IMPORT_EXTENSION: () => DEFAULT_IMPORT_EXTENSION,
   DEFAULT_MODE_PREFIX: () => DEFAULT_MODE_PREFIX,
+  DEFAULT_NESTED_DEPTH: () => DEFAULT_NESTED_DEPTH,
   DEFAULT_SCHEMA_SUFFIX: () => DEFAULT_SCHEMA_SUFFIX,
   DEFAULT_TYPE_SUFFIX: () => DEFAULT_TYPE_SUFFIX,
   IMPORT_EXTENSIONS: () => IMPORT_EXTENSIONS,
+  MAX_NESTED_DEPTH: () => MAX_NESTED_DEPTH,
   NAME_MODES: () => NAME_MODES,
+  NESTED_PREFIX: () => NESTED_PREFIX,
   applyTableCase: () => applyTableCase,
+  buildNestedPlan: () => buildNestedPlan,
   describeSet: () => describeSet,
   formatCode: () => formatCode,
   importSpecifier: () => importSpecifier,
@@ -49,6 +53,10 @@ __export(index_exports, {
   isIntegerColumn: () => isIntegerColumn,
   moduleFileName: () => moduleFileName,
   moduleSpecifier: () => moduleSpecifier,
+  nestedArmNotes: () => nestedArmNotes,
+  nestedNodeColumns: () => nestedNodeColumns,
+  nestedSchemaName: () => nestedSchemaName,
+  nestedTypeName: () => nestedTypeName,
   nonFiniteAccepted: () => nonFiniteAccepted,
   parseCheck: () => parseCheck,
   parsesToADate: () => parsesToADate,
@@ -56,6 +64,7 @@ __export(index_exports, {
   renderDuplicateFinder: () => renderDuplicateFinder,
   resolveAffix: () => resolveAffix,
   resolveConfiguredImport: () => resolveConfiguredImport,
+  resolveNestedDepth: () => resolveNestedDepth,
   schemaName: () => schemaName,
   selectColumns: () => selectColumns,
   typeName: () => typeName,
@@ -448,6 +457,90 @@ function validateAffix(affix, schemaSuffix) {
   return issues;
 }
 
+// src/nested.ts
+var NESTED_PREFIX = "Nested";
+function nestedSchemaName(mode, tsName, affix) {
+  return NESTED_PREFIX + schemaName(mode, tsName, affix);
+}
+function nestedTypeName(mode, tsName, affix) {
+  return NESTED_PREFIX + typeName(mode, tsName, affix);
+}
+var DEFAULT_NESTED_DEPTH = 1;
+var MAX_NESTED_DEPTH = 3;
+function resolveNestedDepth(depth, warn) {
+  if (depth === void 0) return DEFAULT_NESTED_DEPTH;
+  if (!Number.isFinite(depth)) return DEFAULT_NESTED_DEPTH;
+  const whole = Math.trunc(depth);
+  const clamped = Math.min(Math.max(whole, 1), MAX_NESTED_DEPTH);
+  if (clamped !== depth && warn) {
+    warn(
+      `[drzl] nestedDepth ${depth} is outside 1..${MAX_NESTED_DEPTH} and was read as ${clamped}.`
+    );
+  }
+  return clamped;
+}
+var KINDS_BY_MODE = {
+  insert: /* @__PURE__ */ new Set(["many", "manyToMany"]),
+  select: /* @__PURE__ */ new Set(["one", "many", "manyToMany"])
+};
+var KIND_ORDER = { many: 0, manyToMany: 1, one: 2 };
+function omittedColumnsFor(parent, child) {
+  const back = (child.foreignKeys ?? []).filter((fk) => fk.foreignTable === parent.name);
+  if (back.length === 1) return { omitted: [...back[0].columns] };
+  if (back.length === 0) return { omitted: [] };
+  const named = back.map((fk) => fk.columns.join("+")).join(", ");
+  return {
+    omitted: [],
+    note: `${child.tsName} has ${back.length} foreign keys to ${parent.name} (${named}), so which one this relation uses is not stated. None were omitted: supply them yourself.`
+  };
+}
+function buildNestedPlan(root, tables, relations, mode, depth) {
+  const node = buildNode(root, [], tables, relations, mode, depth);
+  return node.arms.length ? node : void 0;
+}
+function buildNode(table, omitted, tables, relations, mode, depth) {
+  if (depth <= 0) return { table, omitted, arms: [] };
+  const byDbName = new Map(tables.map((t) => [t.name, t]));
+  const allowed = KINDS_BY_MODE[mode];
+  const columnNames = new Set(table.columns.map((c) => c.name));
+  const taken = /* @__PURE__ */ new Set();
+  const arms = [];
+  const candidates = relations.filter((r) => r.from === table.name && allowed.has(r.kind)).sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]);
+  for (const rel of candidates) {
+    const child = byDbName.get(rel.to);
+    if (!child) continue;
+    const key = child.tsName;
+    if (columnNames.has(key)) continue;
+    if (taken.has(key)) continue;
+    taken.add(key);
+    const { omitted: childOmitted, note } = rel.kind === "many" && mode === "insert" ? omittedColumnsFor(table, child) : { omitted: [], note: void 0 };
+    arms.push({
+      key,
+      kind: rel.kind,
+      via: rel.via,
+      single: rel.kind === "one",
+      note,
+      child: buildNode(child, childOmitted, tables, relations, mode, depth - 1)
+    });
+  }
+  return { table, omitted, arms };
+}
+function nestedArmNotes(arm) {
+  const out = [];
+  if (arm.kind === "manyToMany") {
+    out.push(
+      `Through ${arm.via ?? "a join table"}. The join row is not described: its columns are the two foreign keys, and the two ends of this payload supply both.`
+    );
+  }
+  if (arm.note) out.push(arm.note);
+  return out;
+}
+function nestedNodeColumns(columnsForMode, node) {
+  if (!node.omitted.length) return [...columnsForMode];
+  const drop = new Set(node.omitted);
+  return columnsForMode.filter((c) => !drop.has(c.name));
+}
+
 // src/duplicates.ts
 function usableKeys(table) {
   return (table.unique ?? []).filter((k) => k.columns.length > 0);
@@ -632,11 +725,15 @@ async function formatCode(code, filePath, fmt) {
   COLUMN_FORMATS,
   DEFAULT_IMPORT_EXTENSION,
   DEFAULT_MODE_PREFIX,
+  DEFAULT_NESTED_DEPTH,
   DEFAULT_SCHEMA_SUFFIX,
   DEFAULT_TYPE_SUFFIX,
   IMPORT_EXTENSIONS,
+  MAX_NESTED_DEPTH,
   NAME_MODES,
+  NESTED_PREFIX,
   applyTableCase,
+  buildNestedPlan,
   describeSet,
   formatCode,
   importSpecifier,
@@ -645,6 +742,10 @@ async function formatCode(code, filePath, fmt) {
   isIntegerColumn,
   moduleFileName,
   moduleSpecifier,
+  nestedArmNotes,
+  nestedNodeColumns,
+  nestedSchemaName,
+  nestedTypeName,
   nonFiniteAccepted,
   parseCheck,
   parsesToADate,
@@ -652,6 +753,7 @@ async function formatCode(code, filePath, fmt) {
   renderDuplicateFinder,
   resolveAffix,
   resolveConfiguredImport,
+  resolveNestedDepth,
   schemaName,
   selectColumns,
   typeName,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Table as Table$1, Column, Analysis } from '@drzl/analyzer';
+import { Relation, Table as Table$1, Column, Analysis } from '@drzl/analyzer';
 
 /**
  * One place that decides what a generated module is called, on disk and in an import.
@@ -284,6 +284,127 @@ declare function parseCheck(expression: string | undefined, name?: string): Pars
  */
 declare function describeSet(set: ColumnSet): string;
 
+/**
+ * What a relations-aware nested schema describes, decided once for all four generators.
+ *
+ * A caller who inserts a parent and its children in one payload, `{ ...user, posts: [...] }`, has
+ * nothing to validate it against. Every first-party Drizzle validator emits columns only: measured
+ * at drizzle-orm 1.0.0-rc.4 and at the 0.4x `drizzle-zod`/`drizzle-valibot`/`drizzle-typebox`/
+ * `drizzle-arktype` packages, `createInsertSchema(users)` yields exactly `['id', 'name']` and never
+ * a `posts` key, in every mode and every library. Handing the relations object in as the second
+ * argument does not change that either: it lands in the refine slot and is dropped, because its
+ * keys are not column names. Handing it in first throws inside `getColumns`.
+ *
+ * And the payload is not merely unvalidated, it is silently discarded. `db.insert(users).values({
+ * name: 'a', posts: [{ title: 't' }] })` emits `insert into "users" ("id", "name") values
+ * (default, $1)` on both majors: the relation key is dropped, no error is raised, and the children
+ * are simply never written.
+ *
+ * This module states the *shape* of such a payload from the analysis. It renders nothing: each
+ * generator walks the plan and emits it in its own library, so the four cannot disagree about
+ * which relations appear or which columns a child carries.
+ */
+
+/**
+ * Which modes get a nested variant.
+ *
+ * `update` is deliberately absent, and it is the one decision here that is a refusal rather than a
+ * design. A nested update payload has no single meaning: `{ name: 'x', posts: [...] }` could mean
+ * replace every child, upsert them, or patch the ones that match, and choosing needs an operation
+ * vocabulary (Prisma spells it `create` / `connect` / `set` / `deleteMany`) that neither DRZL nor
+ * Drizzle has. Worse, it could not be acted on even if the meaning were fixed: `updateColumns`
+ * drops the primary key, so a child inside an update payload carries nothing that identifies which
+ * row it patches. A schema whose meaning the tool emitting it cannot state is worse than no schema.
+ */
+type NestedMode = 'insert' | 'select';
+/** Prefix in front of the ordinary resolved name, so affixes keep working underneath it. */
+declare const NESTED_PREFIX = "Nested";
+/** e.g. `NestedInsertusersSchema`. */
+declare function nestedSchemaName(mode: NestedMode, tsName: string, affix: ResolvedAffix): string;
+/** e.g. `NestedInsertusersInput`. */
+declare function nestedTypeName(mode: NestedMode, tsName: string, affix: ResolvedAffix): string;
+/**
+ * How many levels of children a nested schema describes, when nothing says.
+ *
+ * One, because one is what the payload in the plan item is: a parent and its children. Deeper is
+ * available and is not the default, because the output grows multiplicatively in this number and
+ * generated code ships in the consumer's bundle.
+ */
+declare const DEFAULT_NESTED_DEPTH = 1;
+/**
+ * The most levels `nestedDepth` will honour.
+ *
+ * Not a taste limit. Nesting is expanded inline rather than by reference, so a schema whose tables
+ * average R relations emits R^depth child shapes per root table, and both directions of a
+ * many-to-many count. At 3 that is already an eightfold expansion of every column list in the
+ * schema; past it the emitted file stops being something a person can open.
+ */
+declare const MAX_NESTED_DEPTH = 3;
+/** Clamp a configured depth into the range that is actually emitted, saying so if it moved. */
+declare function resolveNestedDepth(depth: number | undefined, warn?: (msg: string) => void): number;
+/** One relation as it appears in a payload. */
+interface NestedArm {
+    /** The key the payload uses. The child table's Drizzle export name, since nothing else names it. */
+    key: string;
+    kind: Relation['kind'];
+    /** Join table of a many-to-many, carried only so the emitted comment can name it. */
+    via?: string;
+    /** `true` when the value is one object rather than an array of them. Only a `one` relation. */
+    single: boolean;
+    /** The child payload, itself possibly carrying relations. */
+    child: NestedNode;
+    /**
+     * Something true about this arm that the shape alone does not say, emitted as a comment beside
+     * it. Absent when there is nothing to say.
+     */
+    note?: string;
+}
+/** One object in a nested payload: a table, minus what the enclosing parent supplies. */
+interface NestedNode {
+    table: Table$1;
+    /**
+     * Columns dropped from this object because the row that encloses it supplies them.
+     *
+     * Always empty at the root and always empty in `select`, where every column of the row really is
+     * returned. On `insert` it holds the child's foreign key to its parent; see `armFor`.
+     */
+    omitted: string[];
+    arms: NestedArm[];
+}
+/**
+ * The nested payload for one table, expanded `depth` levels.
+ *
+ * Recursion is bounded rather than expressed. All four libraries can state a cyclic schema, and
+ * each does it differently: zod through a property getter, valibot through `v.lazy`, ArkType only
+ * inside a `scope` (a plain forward reference throws `Cannot access 'Post' before initialization`
+ * at module load), TypeBox only inside a `Type.Module` (a bare `Type.Ref` constructs happily and
+ * then throws `Unable to dereference schema with $id` the first time anything checks a value).
+ * Every one of those was run.
+ *
+ * None is used. Expanding inline to a fixed depth needs no recursion API, so no emitted module can
+ * throw on import from an unresolvable reference, no zod or valibot schema needs the explicit type
+ * annotation a self-referential one demands from TypeScript, and the four outputs stay structurally
+ * identical instead of diverging into four different recursion mechanisms. A cycle in the relations
+ * simply stops at the depth: `users -> posts -> users` at depth 1 emits the posts and no more.
+ */
+declare function buildNestedPlan(root: Table$1, tables: readonly Table$1[], relations: readonly Relation[], mode: NestedMode, depth: number): NestedNode | undefined;
+/**
+ * The comment lines that go above an arm, without their `//`.
+ *
+ * Shared so the four generators say the same thing about the same relation, and returned unmarked
+ * because each of them indents its object literal differently.
+ */
+declare function nestedArmNotes(arm: NestedArm): string[];
+/**
+ * Which columns a node contributes, given the mode's column list for its table.
+ *
+ * The list is passed in rather than derived, so this cannot drift from `insertColumns` and
+ * `selectColumns` and so `validation-core`'s entry point stays free of a cycle back into itself.
+ */
+declare function nestedNodeColumns<T extends {
+    name: string;
+}>(columnsForMode: readonly T[], node: NestedNode): T[];
+
 /**
  * A duplicate finder for a batch of rows, emitted beside the schemas.
  *
@@ -403,6 +524,29 @@ interface ValidationGenerateOptions {
      */
     affix?: AffixOptions;
     coerceDates?: 'input' | 'all' | 'none';
+    /**
+     * Also emit `NestedInsert<Table>` and `NestedSelect<Table>`: the table's own schema plus one key
+     * per relation, so `{ ...user, posts: [...] }` can be validated whole.
+     *
+     * Nothing in the Drizzle validator ecosystem describes this payload. Measured across both majors
+     * and all four libraries, `createInsertSchema(users)` emits column keys only, and
+     * `db.insert(users).values({ name, posts: [...] })` drops the `posts` key without a word rather
+     * than refusing it, so the children are silently never written.
+     *
+     * Off by default, like every other option that adds bytes to the consumer's bundle. See
+     * `NestedMode` in `@drzl/validation-core` for why there is no nested update schema, and
+     * `KINDS_BY_MODE` for why a `one` relation appears on select and not on insert.
+     */
+    nestedSchemas?: boolean;
+    /**
+     * How many levels of children a nested schema describes. Defaults to 1, capped at
+     * `MAX_NESTED_DEPTH`.
+     *
+     * Nesting is expanded inline rather than by reference, so this multiplies the emitted size: a
+     * schema whose tables average R relations emits R^depth child shapes per root table. It is also
+     * what terminates a cycle, since `users -> posts -> users` simply stops here.
+     */
+    nestedDepth?: number;
     emit?: {
         select?: boolean;
         insert?: boolean;
@@ -411,6 +555,13 @@ interface ValidationGenerateOptions {
 }
 interface ValidationRenderer<TOptions extends ValidationGenerateOptions = ValidationGenerateOptions> {
     readonly library: ValidationLibrary;
+    /**
+     * One table's schemas, without the nested variants even under `nestedSchemas`.
+     *
+     * Structural rather than an omission: relations live on the `Analysis` and this is handed a
+     * `Table`, so there is nothing here to read them from. `typedJson` is absent for the same
+     * reason. Nothing but the generators' own tests calls this; `generate` is the path that emits.
+     */
     renderTable(table: Table, opts?: TOptions): string;
     renderIndex?(analysis: Analysis, opts?: TOptions): string;
     generate(opts: TOptions): Promise<string[]>;
@@ -629,4 +780,4 @@ declare function selectColumns(table: Table): Column[];
  */
 declare function formatCode(code: string, filePath: string, fmt?: FormatOptions): Promise<any>;
 
-export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, NAME_MODES, type NameMode, type ParsedCheck, type ResolvedAffix, type RowCheck, type Table, type TableCase, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveConfiguredImport, schemaName, selectColumns, typeName, updateColumns, validateAffix };
+export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, MAX_NESTED_DEPTH, NAME_MODES, NESTED_PREFIX, type NameMode, type NestedArm, type NestedMode, type NestedNode, type ParsedCheck, type ResolvedAffix, type RowCheck, type Table, type TableCase, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, buildNestedPlan, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveConfiguredImport, resolveNestedDepth, schemaName, selectColumns, typeName, updateColumns, validateAffix };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Table as Table$1, Column, Analysis } from '@drzl/analyzer';
+import { Relation, Table as Table$1, Column, Analysis } from '@drzl/analyzer';
 
 /**
  * One place that decides what a generated module is called, on disk and in an import.
@@ -284,6 +284,127 @@ declare function parseCheck(expression: string | undefined, name?: string): Pars
  */
 declare function describeSet(set: ColumnSet): string;
 
+/**
+ * What a relations-aware nested schema describes, decided once for all four generators.
+ *
+ * A caller who inserts a parent and its children in one payload, `{ ...user, posts: [...] }`, has
+ * nothing to validate it against. Every first-party Drizzle validator emits columns only: measured
+ * at drizzle-orm 1.0.0-rc.4 and at the 0.4x `drizzle-zod`/`drizzle-valibot`/`drizzle-typebox`/
+ * `drizzle-arktype` packages, `createInsertSchema(users)` yields exactly `['id', 'name']` and never
+ * a `posts` key, in every mode and every library. Handing the relations object in as the second
+ * argument does not change that either: it lands in the refine slot and is dropped, because its
+ * keys are not column names. Handing it in first throws inside `getColumns`.
+ *
+ * And the payload is not merely unvalidated, it is silently discarded. `db.insert(users).values({
+ * name: 'a', posts: [{ title: 't' }] })` emits `insert into "users" ("id", "name") values
+ * (default, $1)` on both majors: the relation key is dropped, no error is raised, and the children
+ * are simply never written.
+ *
+ * This module states the *shape* of such a payload from the analysis. It renders nothing: each
+ * generator walks the plan and emits it in its own library, so the four cannot disagree about
+ * which relations appear or which columns a child carries.
+ */
+
+/**
+ * Which modes get a nested variant.
+ *
+ * `update` is deliberately absent, and it is the one decision here that is a refusal rather than a
+ * design. A nested update payload has no single meaning: `{ name: 'x', posts: [...] }` could mean
+ * replace every child, upsert them, or patch the ones that match, and choosing needs an operation
+ * vocabulary (Prisma spells it `create` / `connect` / `set` / `deleteMany`) that neither DRZL nor
+ * Drizzle has. Worse, it could not be acted on even if the meaning were fixed: `updateColumns`
+ * drops the primary key, so a child inside an update payload carries nothing that identifies which
+ * row it patches. A schema whose meaning the tool emitting it cannot state is worse than no schema.
+ */
+type NestedMode = 'insert' | 'select';
+/** Prefix in front of the ordinary resolved name, so affixes keep working underneath it. */
+declare const NESTED_PREFIX = "Nested";
+/** e.g. `NestedInsertusersSchema`. */
+declare function nestedSchemaName(mode: NestedMode, tsName: string, affix: ResolvedAffix): string;
+/** e.g. `NestedInsertusersInput`. */
+declare function nestedTypeName(mode: NestedMode, tsName: string, affix: ResolvedAffix): string;
+/**
+ * How many levels of children a nested schema describes, when nothing says.
+ *
+ * One, because one is what the payload in the plan item is: a parent and its children. Deeper is
+ * available and is not the default, because the output grows multiplicatively in this number and
+ * generated code ships in the consumer's bundle.
+ */
+declare const DEFAULT_NESTED_DEPTH = 1;
+/**
+ * The most levels `nestedDepth` will honour.
+ *
+ * Not a taste limit. Nesting is expanded inline rather than by reference, so a schema whose tables
+ * average R relations emits R^depth child shapes per root table, and both directions of a
+ * many-to-many count. At 3 that is already an eightfold expansion of every column list in the
+ * schema; past it the emitted file stops being something a person can open.
+ */
+declare const MAX_NESTED_DEPTH = 3;
+/** Clamp a configured depth into the range that is actually emitted, saying so if it moved. */
+declare function resolveNestedDepth(depth: number | undefined, warn?: (msg: string) => void): number;
+/** One relation as it appears in a payload. */
+interface NestedArm {
+    /** The key the payload uses. The child table's Drizzle export name, since nothing else names it. */
+    key: string;
+    kind: Relation['kind'];
+    /** Join table of a many-to-many, carried only so the emitted comment can name it. */
+    via?: string;
+    /** `true` when the value is one object rather than an array of them. Only a `one` relation. */
+    single: boolean;
+    /** The child payload, itself possibly carrying relations. */
+    child: NestedNode;
+    /**
+     * Something true about this arm that the shape alone does not say, emitted as a comment beside
+     * it. Absent when there is nothing to say.
+     */
+    note?: string;
+}
+/** One object in a nested payload: a table, minus what the enclosing parent supplies. */
+interface NestedNode {
+    table: Table$1;
+    /**
+     * Columns dropped from this object because the row that encloses it supplies them.
+     *
+     * Always empty at the root and always empty in `select`, where every column of the row really is
+     * returned. On `insert` it holds the child's foreign key to its parent; see `armFor`.
+     */
+    omitted: string[];
+    arms: NestedArm[];
+}
+/**
+ * The nested payload for one table, expanded `depth` levels.
+ *
+ * Recursion is bounded rather than expressed. All four libraries can state a cyclic schema, and
+ * each does it differently: zod through a property getter, valibot through `v.lazy`, ArkType only
+ * inside a `scope` (a plain forward reference throws `Cannot access 'Post' before initialization`
+ * at module load), TypeBox only inside a `Type.Module` (a bare `Type.Ref` constructs happily and
+ * then throws `Unable to dereference schema with $id` the first time anything checks a value).
+ * Every one of those was run.
+ *
+ * None is used. Expanding inline to a fixed depth needs no recursion API, so no emitted module can
+ * throw on import from an unresolvable reference, no zod or valibot schema needs the explicit type
+ * annotation a self-referential one demands from TypeScript, and the four outputs stay structurally
+ * identical instead of diverging into four different recursion mechanisms. A cycle in the relations
+ * simply stops at the depth: `users -> posts -> users` at depth 1 emits the posts and no more.
+ */
+declare function buildNestedPlan(root: Table$1, tables: readonly Table$1[], relations: readonly Relation[], mode: NestedMode, depth: number): NestedNode | undefined;
+/**
+ * The comment lines that go above an arm, without their `//`.
+ *
+ * Shared so the four generators say the same thing about the same relation, and returned unmarked
+ * because each of them indents its object literal differently.
+ */
+declare function nestedArmNotes(arm: NestedArm): string[];
+/**
+ * Which columns a node contributes, given the mode's column list for its table.
+ *
+ * The list is passed in rather than derived, so this cannot drift from `insertColumns` and
+ * `selectColumns` and so `validation-core`'s entry point stays free of a cycle back into itself.
+ */
+declare function nestedNodeColumns<T extends {
+    name: string;
+}>(columnsForMode: readonly T[], node: NestedNode): T[];
+
 /**
  * A duplicate finder for a batch of rows, emitted beside the schemas.
  *
@@ -403,6 +524,29 @@ interface ValidationGenerateOptions {
      */
     affix?: AffixOptions;
     coerceDates?: 'input' | 'all' | 'none';
+    /**
+     * Also emit `NestedInsert<Table>` and `NestedSelect<Table>`: the table's own schema plus one key
+     * per relation, so `{ ...user, posts: [...] }` can be validated whole.
+     *
+     * Nothing in the Drizzle validator ecosystem describes this payload. Measured across both majors
+     * and all four libraries, `createInsertSchema(users)` emits column keys only, and
+     * `db.insert(users).values({ name, posts: [...] })` drops the `posts` key without a word rather
+     * than refusing it, so the children are silently never written.
+     *
+     * Off by default, like every other option that adds bytes to the consumer's bundle. See
+     * `NestedMode` in `@drzl/validation-core` for why there is no nested update schema, and
+     * `KINDS_BY_MODE` for why a `one` relation appears on select and not on insert.
+     */
+    nestedSchemas?: boolean;
+    /**
+     * How many levels of children a nested schema describes. Defaults to 1, capped at
+     * `MAX_NESTED_DEPTH`.
+     *
+     * Nesting is expanded inline rather than by reference, so this multiplies the emitted size: a
+     * schema whose tables average R relations emits R^depth child shapes per root table. It is also
+     * what terminates a cycle, since `users -> posts -> users` simply stops here.
+     */
+    nestedDepth?: number;
     emit?: {
         select?: boolean;
         insert?: boolean;
@@ -411,6 +555,13 @@ interface ValidationGenerateOptions {
 }
 interface ValidationRenderer<TOptions extends ValidationGenerateOptions = ValidationGenerateOptions> {
     readonly library: ValidationLibrary;
+    /**
+     * One table's schemas, without the nested variants even under `nestedSchemas`.
+     *
+     * Structural rather than an omission: relations live on the `Analysis` and this is handed a
+     * `Table`, so there is nothing here to read them from. `typedJson` is absent for the same
+     * reason. Nothing but the generators' own tests calls this; `generate` is the path that emits.
+     */
     renderTable(table: Table, opts?: TOptions): string;
     renderIndex?(analysis: Analysis, opts?: TOptions): string;
     generate(opts: TOptions): Promise<string[]>;
@@ -629,4 +780,4 @@ declare function selectColumns(table: Table): Column[];
  */
 declare function formatCode(code: string, filePath: string, fmt?: FormatOptions): Promise<any>;
 
-export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, NAME_MODES, type NameMode, type ParsedCheck, type ResolvedAffix, type RowCheck, type Table, type TableCase, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveConfiguredImport, schemaName, selectColumns, typeName, updateColumns, validateAffix };
+export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, MAX_NESTED_DEPTH, NAME_MODES, NESTED_PREFIX, type NameMode, type NestedArm, type NestedMode, type NestedNode, type ParsedCheck, type ResolvedAffix, type RowCheck, type Table, type TableCase, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, buildNestedPlan, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveConfiguredImport, resolveNestedDepth, schemaName, selectColumns, typeName, updateColumns, validateAffix };

package/dist/index.js

@@ -384,6 +384,90 @@ function validateAffix(affix, schemaSuffix) {
   return issues;
 }
 
+// src/nested.ts
+var NESTED_PREFIX = "Nested";
+function nestedSchemaName(mode, tsName, affix) {
+  return NESTED_PREFIX + schemaName(mode, tsName, affix);
+}
+function nestedTypeName(mode, tsName, affix) {
+  return NESTED_PREFIX + typeName(mode, tsName, affix);
+}
+var DEFAULT_NESTED_DEPTH = 1;
+var MAX_NESTED_DEPTH = 3;
+function resolveNestedDepth(depth, warn) {
+  if (depth === void 0) return DEFAULT_NESTED_DEPTH;
+  if (!Number.isFinite(depth)) return DEFAULT_NESTED_DEPTH;
+  const whole = Math.trunc(depth);
+  const clamped = Math.min(Math.max(whole, 1), MAX_NESTED_DEPTH);
+  if (clamped !== depth && warn) {
+    warn(
+      `[drzl] nestedDepth ${depth} is outside 1..${MAX_NESTED_DEPTH} and was read as ${clamped}.`
+    );
+  }
+  return clamped;
+}
+var KINDS_BY_MODE = {
+  insert: /* @__PURE__ */ new Set(["many", "manyToMany"]),
+  select: /* @__PURE__ */ new Set(["one", "many", "manyToMany"])
+};
+var KIND_ORDER = { many: 0, manyToMany: 1, one: 2 };
+function omittedColumnsFor(parent, child) {
+  const back = (child.foreignKeys ?? []).filter((fk) => fk.foreignTable === parent.name);
+  if (back.length === 1) return { omitted: [...back[0].columns] };
+  if (back.length === 0) return { omitted: [] };
+  const named = back.map((fk) => fk.columns.join("+")).join(", ");
+  return {
+    omitted: [],
+    note: `${child.tsName} has ${back.length} foreign keys to ${parent.name} (${named}), so which one this relation uses is not stated. None were omitted: supply them yourself.`
+  };
+}
+function buildNestedPlan(root, tables, relations, mode, depth) {
+  const node = buildNode(root, [], tables, relations, mode, depth);
+  return node.arms.length ? node : void 0;
+}
+function buildNode(table, omitted, tables, relations, mode, depth) {
+  if (depth <= 0) return { table, omitted, arms: [] };
+  const byDbName = new Map(tables.map((t) => [t.name, t]));
+  const allowed = KINDS_BY_MODE[mode];
+  const columnNames = new Set(table.columns.map((c) => c.name));
+  const taken = /* @__PURE__ */ new Set();
+  const arms = [];
+  const candidates = relations.filter((r) => r.from === table.name && allowed.has(r.kind)).sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]);
+  for (const rel of candidates) {
+    const child = byDbName.get(rel.to);
+    if (!child) continue;
+    const key = child.tsName;
+    if (columnNames.has(key)) continue;
+    if (taken.has(key)) continue;
+    taken.add(key);
+    const { omitted: childOmitted, note } = rel.kind === "many" && mode === "insert" ? omittedColumnsFor(table, child) : { omitted: [], note: void 0 };
+    arms.push({
+      key,
+      kind: rel.kind,
+      via: rel.via,
+      single: rel.kind === "one",
+      note,
+      child: buildNode(child, childOmitted, tables, relations, mode, depth - 1)
+    });
+  }
+  return { table, omitted, arms };
+}
+function nestedArmNotes(arm) {
+  const out = [];
+  if (arm.kind === "manyToMany") {
+    out.push(
+      `Through ${arm.via ?? "a join table"}. The join row is not described: its columns are the two foreign keys, and the two ends of this payload supply both.`
+    );
+  }
+  if (arm.note) out.push(arm.note);
+  return out;
+}
+function nestedNodeColumns(columnsForMode, node) {
+  if (!node.omitted.length) return [...columnsForMode];
+  const drop = new Set(node.omitted);
+  return columnsForMode.filter((c) => !drop.has(c.name));
+}
+
 // src/duplicates.ts
 function usableKeys(table) {
   return (table.unique ?? []).filter((k) => k.columns.length > 0);
@@ -567,11 +651,15 @@ export {
   COLUMN_FORMATS,
   DEFAULT_IMPORT_EXTENSION,
   DEFAULT_MODE_PREFIX,
+  DEFAULT_NESTED_DEPTH,
   DEFAULT_SCHEMA_SUFFIX,
   DEFAULT_TYPE_SUFFIX,
   IMPORT_EXTENSIONS,
+  MAX_NESTED_DEPTH,
   NAME_MODES,
+  NESTED_PREFIX,
   applyTableCase,
+  buildNestedPlan,
   describeSet,
   formatCode,
   importSpecifier,
@@ -580,6 +668,10 @@ export {
   isIntegerColumn,
   moduleFileName,
   moduleSpecifier,
+  nestedArmNotes,
+  nestedNodeColumns,
+  nestedSchemaName,
+  nestedTypeName,
   nonFiniteAccepted,
   parseCheck,
   parsesToADate,
@@ -587,6 +679,7 @@ export {
   renderDuplicateFinder,
   resolveAffix,
   resolveConfiguredImport,
+  resolveNestedDepth,
   schemaName,
   selectColumns,
   typeName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drzl/validation-core",
-  "version": "3.16.4",
+  "version": "3.17.0",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@drzl/analyzer": "^1.17.4"
+    "@drzl/analyzer": "^1.17.7"
   },
   "peerDependencies": {
     "prettier": ">=3"