@web-ts-toolkit/json-frame 0.42.2 → 0.47.1

package/README.md

@@ -18,7 +18,7 @@ import { fromOrient } from '@web-ts-toolkit/json-frame';
 
 The package exports named values and types from the package root. There is no default export and no supported deep import path.
 
-`JSON_FRAME_MAX_DEPTH` is `1000`. JSON arrays and objects are counted from the parsed root at depth `0`; an array or object reached at depth `1000` is accepted, and one reached at depth `1001` fails with `JsonFrameValidationError` before package traversal can exhaust the JavaScript stack.
+`JSON_FRAME_MAX_DEPTH` is `1000`. JSON arrays and objects are counted from the validated root at depth `0`; an array or object reached at depth `1000` is accepted, and one reached at depth `1001` fails with `JsonFrameValidationError` before package traversal can exhaust the JavaScript stack. For `toJSONString()` the root is the complete exported payload including orient-specific wrappers: `split` and `table` nest cell values one level deeper than `records`, `values`, `index`, and `columns`. A nested cell accepted at ingestion may therefore be rejected when serialized in a deeper output layout.
 
 ## Quick Start
 
@@ -46,6 +46,48 @@ The returned `DataFrame` is immutable. `filter`, `sort`, `select`, `rename`, and
 
 The `TRow` generic is a compile-time row model only. It improves `row()`, `rows()`, `filter()`, and `sort()` types for JSON-compatible domain interfaces, but it does not validate an application schema at runtime; payload validation follows the selected orient contract.
 
+### Inferred Row Types
+
+Parsed `records` with omitted, `auto`, or explicit `records` orient infer known required fields precisely. Sparse, heterogeneous, and optional fields include `null`, matching missing-cell normalization. Those fields also remain optional: if no input row supplies a column, it is never created and reading it returns `undefined`. Use `!= null` to guard both. Heterogeneous row variants are flattened into one column shape; a discriminant does not prove another cell is present. Nested cell objects retain their own types and are not null-filled internally.
+
+Requiredness follows declared keys in every record variant, including names such as `toString`, `constructor`, and `valueOf`; inherited Object members do not supply cells. Numeric literal keys and their equivalent string spellings are combined before inferring cell types and requiredness: `1` and `'1'` describe one column named `'1'`, accessible with either `[1]` or `['1']`. Non-equivalent strings such as `'01'` remain distinct. Dense literals retain precise value unions; sparse or optional aliases require the same null-safe guards as other columns.
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+const dense = fromOrient([{ n: 1 }, { n: 2 }]);
+const formatted: string = dense.row(0).n.toFixed(); // number, no extra null guard
+
+const sparse = fromOrient([{ n: 1 }, {}]);
+const present = sparse.filter((row) => row.n != null && row.n.toFixed() === '1');
+// sparse.row(1).n is null at runtime; an undefined-only guard is insufficient.
+
+const members = fromOrient([{ toString: 'ok' }, {}] as const);
+const text = members.row(1).toString?.toUpperCase(); // undefined: the cell is null
+const numeric = fromOrient([{ 1: 1 }, { '1': 'x' }] as const);
+const cell: 1 | 'x' = numeric.row(0)[1]; // same column as numeric.row(0)['1']
+
+const values = fromOrient([[1]], { columns: ['n'] });
+// Values rows are objects, including with readonly tuple inputs and auto orient.
+const n = values.row(0).n;
+const valueText = typeof n === 'number' ? n.toFixed() : '';
+
+void [formatted, present, text, cell, valueText];
+```
+
+Values arrays, JSON strings, other layouts, broad dictionary records, and broadly typed orient options use conservative `JsonRow` inference rather than guessing column types. Supplying `fromOrient<MyRow>(...)` intentionally preserves your asserted domain model, including optional properties; ensure it describes actual normalized rows. It does not perform runtime application-schema validation.
+
+Open index domains keep that fallback, including `string`, `number`, and template patterns such as `` `metric_${string}` ``, `` `${number}` ``, or `` `${string}_metric` ``. Unions or intersections with known properties also fall back to `JsonRow` when an open index domain is present. A dictionary describes allowed names, not an infinite set of present columns: missing cells in existing columns become `null`, while columns absent from every row are not created. Use a scalar guard such as `typeof cell === 'number'` before numeric operations; an undefined-only guard is insufficient. The fallback conservatively widens even known fields to JSON values. Finite template-key unions such as `` `metric_${'a' | 'b'}` `` retain precise fields and declared optionality.
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+const rows: Record<`metric_${string}`, number>[] = [{ metric_n: 1 }, {}];
+const frame = fromOrient(rows); // DataFrame<JsonRow>
+frame.filter((row) => typeof row.metric_n === 'number' && row.metric_n.toFixed() === '1');
+// frame.row(1).metric_n is null; frame.row(0).metric_absent is undefined.
+```
+
 ## Supported Orients
 
 All six pandas DataFrame JSON orients are supported.
@@ -140,6 +182,7 @@ Other `fromOrient` options:
 - `columns`: required whenever the payload is `values`, including non-empty `values` arrays detected by `auto`
 - `columnTypes`: explicit logical types for non-table inputs
 - `packThreshold`: minimum length for internal numeric typed-array packing; `0` disables packing
+- `maxNodes`: optional positive safe integer limiting ingestion traversal occurrences; omitted means no quota (see below)
 
 ```ts
 import { AmbiguousOrientError, JsonFrameOptionError, fromOrient } from '@web-ts-toolkit/json-frame';
@@ -246,6 +289,32 @@ Transform behavior:
 
 Structural immutability is shallow. Frame-owned arrays, row records, exporter containers, table schema records, and internal maps are protected from direct mutation or are freshly allocated. Nested JSON object or array cell values are not deep-frozen or deep-cloned on every read/export; if caller code mutates one of those nested values after obtaining it from `row()`, `rows()`, or an exporter, another read of the same cell may observe that mutation.
 
+`toJSONString(orient, options?)` validates the complete selected output with the shared bounded traversal before native serialization. Cycles, over-depth containers, sparse arrays, and newly introduced non-JSON values (`undefined`, `bigint`, `symbol`, `function`, non-finite numbers, non-plain objects) fail with path-bearing `JsonFrameValidationError` carrying the selected orient instead of native `TypeError`/`RangeError` behavior. Valid nested JSON serializes unchanged and preserves shallow cell identity on subsequent reads.
+
+Validation is one traversal pass without cloning the payload, followed by native `JSON.stringify()`. Only the ancestor chain is tracked, so repeated references to the same acyclic container are visited once per occurrence and expand as stringification expands them. Optional `maxNodes` bounds validation visits; omission leaves breadth unlimited. Validation reads own enumerable properties and array elements, which invokes caller-installed getters and `Proxy` traps; native serialization may additionally invoke `toJSON` hooks, including non-enumerable ones invisible to validation. Hooks can change values between passes and are caller responsibility; the package does not sandbox arbitrary JavaScript.
+
+### Opt-In Traversal Budgets
+
+`fromOrient(input, { maxNodes })` and `frame.toJSONString(orient, { maxNodes })` accept a **positive safe integer**. Zero, negatives, fractions, non-finite/unsafe integers, `null`, and other nonnumbers throw `JsonFrameOptionError`. Options are validated for all six serialization orients; `indexField` must be a string when supplied and affects only table output. It can be combined with `maxNodes`.
+
+Each traversal counts its root as one node, then every property/array-element **value occurrence**, including scalars, `null`, and empty containers. Property names are not nodes. Repeated aliases count again on every path; ingestion still creates detached clones for each occurrence. Exact-budget traversal succeeds; attempting the next node throws path-bearing `JsonFrameValidationError` with the orient when known (auto ingestion detects orient after cloning). Serialization counts the **complete exported payload**, including orient wrappers, labels and table metadata, so different orients need different budgets. Counters reset per call. An ingestion budget is **not retained by the frame** or inherited by later exports or transforms; omitted options impose no default quota.
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+// Three nodes: root array, row object, number. JSON strings count after JSON.parse.
+const frame = fromOrient('[{"n":1}]', { orient: 'records', maxNodes: 3 });
+const records = frame.toJSONString('records', { maxNodes: 3 });
+// Split adds wrappers and labels: eight nodes for this one-cell frame.
+const split = frame.toJSONString('split', { maxNodes: 8 });
+const indexed = fromOrient({ r0: { n: 1 } }, { orient: 'index', maxNodes: 3 });
+const table = indexed.toJSONString('table', { indexField: 'row_id', maxNodes: 15 });
+
+void [records, split, table];
+```
+
+This is a traversal-expansion limit, **not a total resource limit**. It does not bound input/string bytes or the preceding native `JSON.parse()`, object-key enumeration/allocation (including diagnostic key counting), rectangular frame densification, export payload/schema construction before validation, native stringification/output bytes, caller hooks, or total process memory. Scalars may be arbitrarily large. Validation allocates traversal bookkeeping but no redundant full clone. The fixed depth/cycle/JSON-compatibility checks still apply independently. Object-returning exporters such as `toTable()` have no `maxNodes` option. Applications still need their own size and trust boundaries.
+
 ```ts
 import { fromOrient } from '@web-ts-toolkit/json-frame';
 
@@ -282,14 +351,17 @@ Type rules:
 - Table Schema metadata is preserved when `orient: 'table'` is used; pandas-authored field metadata remains caller/pandas responsibility.
 - Other orients infer the narrowest logical type by scanning the full column.
 - `options.columnTypes` supplies explicit logical types for non-table inputs. Declared types are validated against every non-null cell before packing; incompatible cells fail with `JsonFrameValidationError` carrying `path`, `row`, `column`, and `value` diagnostics.
+- Only own enumerable string keys in `columnTypes` are overrides; inherited properties are ignored. Ordinary and null-prototype dictionaries are supported and copied without mutating the caller. Names such as `constructor`, `toString`, `hasOwnProperty`, and `__proto__` remain valid columns with omitted, empty, partial, or explicit overrides. Use a computed key for an explicit `__proto__` override, for example `{ ['__proto__']: 'float' }`. Source Table Schema field types take precedence over overrides.
 - Explicit `integer`, `float`, `string`, and `boolean` require matching JSON scalar cells. `float` accepts integer JSON numbers because Table Schema `number` accepts both integer and fractional JSON numbers.
-- Explicit `datetime` accepts pandas-style timezone-naive ISO date/datetime strings such as `2024-01-02T03:04:05.000`, `2024-01-02 03:04:05`, or `2024-01-02`. Numeric epoch cells are rejected because generated Table Schema has no unit metadata and pandas reads numeric `datetime` cells as nanoseconds.
+- Explicit `datetime` accepts calendar-valid, timezone-naive ISO strings for four-digit years **0000–9999**, using proleptic Gregorian rules: leap years are divisible by 4 except centuries not divisible by 400. Thus `0000-02-29` and `2000-02-29` are valid, while `0100-02-29` and `1900-02-29` are not. The grammar is `YYYY-MM-DD`, optionally followed by `T` or one space and `HH:mm:ss`, optionally followed by a decimal point and 1–9 fractional-second digits. Hours must be 00–23 and minutes/seconds 00–59; timezone suffixes, leap seconds, signed/expanded years, and numeric epochs are rejected. Strings and their fractional precision are preserved exactly. Numeric epochs have no unit metadata in generated Table Schema and pandas reads numeric `datetime` cells as nanoseconds.
 - Explicit `categorical` accepts non-null scalar JSON cells (`string`, `number`, or `boolean`) and generated table output emits `type: 'any'` with `extDtype: 'category'` unless source Table Schema field metadata is being preserved.
 - Explicit `mixed` and `unknown` accept any JSON-compatible cell value.
 - `null` marks a column as nullable without forcing an otherwise numeric column to become `mixed`.
 - ISO-looking strings are preserved as strings unless table metadata or compatible explicit `columnTypes` says otherwise.
 - Values are never coerced to satisfy logical type metadata.
 
+Calendar validity does **not** guarantee pandas read-back across the full year range. Pandas dtype and time resolution impose separate limits. The prior JFB-07 investigation (pandas **3.0.3**, CPython **3.14.6**) recorded ISO emission of years `0000`, `0001`, and `0099` at microsecond resolution, but `read_json(..., orient='table')` failed outside nanosecond bounds. This is previously recorded evidence, not a new pandas experiment for the calendar fix; see [JFB-07 evidence](https://github.com/egose/web-ts-toolkit/blob/HEAD/docs/tasks/20260908-180959-json-frame-boundary-health-follow-up.md#task-jfb-07-resolve-datetime-year-range-semantics). Check the target pandas dtype/resolution when exchanging dates outside its read-back range.
+
 Packing rules:
 
 - typed-array packing is an internal optimization only
@@ -299,9 +371,9 @@ Packing rules:
 
 ## Round Trips And Index Provenance
 
-Round trips are semantic rather than byte-for-byte.
+Round trips are semantic rather than byte-for-byte, with the empty-dimension exceptions below.
 
-- column order and cell JSON values are preserved
+- column labels/order are retained where the layout carries them, subject to JavaScript enumeration of object keys; cell JSON values are preserved apart from native JSON text formatting (for example, `JSON.stringify(-0)` produces `0`)
 - `split` and `table` preserve row order exactly
 - `index` and `columns` row order follows JavaScript property enumeration for object keys; use `split` or `table` when exact order matters for integer-like labels
 - label-bearing orients preserve supported source index labels, subject to object-key stringification for `index`/`columns`
@@ -311,19 +383,58 @@ Round trips are semantic rather than byte-for-byte.
 - `toTable()` emits valid Table Schema, omits a synthetic index from table output, and rejects duplicate source index labels because emitted table primary keys must be unique
 - table primary-key equality uses JavaScript `Map`/SameValueZero semantics for supported string and finite-number labels, so numeric `1` and string `'1'` are distinct table labels even though object-key exporters reject them as stringification collisions
 - Table Schema metadata is cloned under the same `JSON_FRAME_MAX_DEPTH` policy used while parsing. `toTable()` and `toJSONString('table')` report over-depth metadata as `JsonFrameValidationError`.
+- `toJSONString()` depth is measured from the exported payload root including orient wrappers, not from the stored cell alone. A cell accepted at ingestion at the depth limit can be rejected in a deeper `split`/`table` layout while still serializing in a shallower `records`/`values`/`index`/`columns` layout.
+
+Source table index and data-field metadata retain their separate roles through `select`, `rename`, `resetIndex`, filtering and sorting, even when the source primary-key field is not first. Renaming a data column to the retained index-field name is supported, but table export then needs a unique `indexField` override (or a subsequent rename/resetIndex) to avoid duplicate emitted field names.
+
+### Empty-Dimension Fidelity
+
+Choose **`split` or `table`** when an empty report must carry its dimensions in the payload. The matrix gives the shape **after export and re-ingestion with the matching explicit orient**, for both object-returning exporters and `toJSONString()`. `R` is a positive row count and `C` a positive data-column count; the index field is not a data column. `values` results assume the caller separately supplies the original `columns`.
+
+| Orient    | Zero rows, declared columns (`0 × C`)                  | Rows, zero columns (`R × 0`)                                     | Fully empty (`0 × 0`)                    |
+| --------- | ------------------------------------------------------ | ---------------------------------------------------------------- | ---------------------------------------- |
+| `records` | `[]` → `0 × 0`; column labels lost                     | `R` empty objects → `R × 0`                                      | `[]` → `0 × 0`                           |
+| `index`   | `{}` → `0 × 0`; column labels lost                     | `R` index keys with empty objects → `R × 0`                      | `{}` → `0 × 0`                           |
+| `columns` | `C` column keys with empty objects → `0 × C`           | `{}` → `0 × 0`; rows and index labels lost                       | `{}` → `0 × 0`                           |
+| `values`  | `[]` + supplied columns → `0 × C`                      | `R` empty arrays + `columns: []` → `R × 0`                       | `[]` + `columns: []` → `0 × 0`           |
+| `split`   | `columns` retained, empty `index`/`data` → `0 × C`     | Empty `columns`, `R` index labels and empty row arrays → `R × 0` | Empty `columns`/`index`/`data` → `0 × 0` |
+| `table`   | Data fields retained in schema, empty `data` → `0 × C` | No data fields, `R` row objects → `R × 0`                        | No data fields, empty `data` → `0 × 0`   |
+
+- `values` never carries column labels; omitting `options.columns` throws even for `[]` or `[[], []]`. For empty arrays, also pass the explicit orient. `options.columns` is used only for `values`; it cannot restore lost columns in empty `records`/`index` payloads.
+- `records`/`values` regenerate a synthetic numeric index. `index`/`columns` re-ingest object keys as source string labels with JavaScript enumeration order. `columns` has nowhere to put row labels when there are no columns.
+- `split` always emits the current index array and re-ingests it as a **source** index, even if those labels were synthetic before export. It preserves gapped numeric labels after filtering.
+- `table` emits a source index as a schema field plus `primaryKey`, including on a fully empty frame. With zero data columns, its rows contain only that index field. A synthetic index is omitted: zero-column rows are `{}` and re-ingestion regenerates `0..R-1`, so gaps in a filtered synthetic index are lost. The normal uniqueness and index-field collision checks still apply.
+- Dimension fidelity is separate from metadata fidelity: only `table` carries logical types and retained field/schema metadata. For example, a zero-row numeric column round-tripped through `split`, `columns`, or `values` has no cells from which to infer its original type; supply appropriate non-table `columnTypes` if needed.
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+const report = fromOrient([{ a: 1 }, { a: 2 }], { orient: 'records' });
+const noRows = report.filter(() => false); // 0 rows, column a retained
+const noColumns = report.select(); // 2 rows, 0 columns
+
+const shaped = fromOrient(noRows.toSplit(), { orient: 'split' }); // 0 × 1
+const rowCount = fromOrient(noColumns.toTable(), { orient: 'table' }); // 2 × 0
+const lostRows = fromOrient(noColumns.toColumns(), { orient: 'columns' }); // 0 × 0
+const restoredColumns = fromOrient(noRows.toValues(), { orient: 'values', columns: noRows.columns });
+
+void [shaped, rowCount, lostRows, restoredColumns];
+```
 
 ## Errors
 
 Structured runtime errors are exported from the package root.
 
 - `JsonFrameParseError`: invalid JSON string input; original `SyntaxError` is available as `cause`
-- `JsonFrameOptionError`: invalid options such as bad `packThreshold` or missing `columns` for `values`
+- `JsonFrameOptionError`: invalid options such as bad `maxNodes`/`packThreshold` or missing `columns` for `values`
 - `JsonFrameValidationError`: payload shape, transform argument, or JSON-value validation failure
 - `AmbiguousOrientError`: `auto` mode cannot distinguish between multiple valid orients
 - `UnsupportedFeatureError`: supported contract deliberately excludes the requested pandas feature
 - `ExportKeyCollisionError`: object-key exporters would collapse distinct index labels to the same JSON key
 
-`JsonFrameError` instances expose `orient`, `path`, `row`, `column`, and `value` when relevant. Scalar JSON diagnostic values (`string`, finite or non-finite `number`, `boolean`, `null`) are retained directly. Arrays, objects, functions, symbols, bigints, undefined values, and cyclic containers are replaced with small frozen summaries, so retaining an error does not retain caller-owned payloads and `JSON.stringify(error)` does not invoke user serialization hooks.
+`JsonFrameError` instances expose `orient`, `path`, `row`, `column`, and `value` when relevant. Scalar JSON diagnostic values (`string`, finite or non-finite `number`, `boolean`, `null`) are retained directly and are intentionally not bounded by the container-preview budget below. Arrays, objects, functions, symbols, bigints, undefined values, and cyclic containers are replaced with small frozen summaries, so retaining an error does not retain caller-owned payloads and `JSON.stringify(error)` does not invoke user serialization hooks.
+
+Object summaries retain at most 5 keys and at most 200 characters of key-preview text in total. `truncated` is `true` when either the key count or the key-preview text was shortened; `keyCount` always reports the full own enumerable key count. `truncated: false` therefore means the `keys` preview is complete, not merely that the count fit. This bounds the retained/serialized summary preview, not the complete error size: scalar diagnostic strings, `path`, `column`, `option`, `key`, and `labels` fields can still be input-sized. Error construction never calls caller `toJSON` hooks, and counting keys uses `Object.keys()`, which collects all own enumerable string keys — construction is not constant-space even though the retained preview is bounded.
 
 Diagnostic summary shapes are:
 

package/index.d.mts

@@ -8,8 +8,10 @@ interface JsonObject {
 }
 /**
  * Any JSON-compatible value accepted by `fromOrient` payloads and exporters.
- * Arrays/objects may nest up to `JSON_FRAME_MAX_DEPTH` levels from the parsed
- * root value; deeper containers fail with `JsonFrameValidationError`.
+ * Arrays/objects may nest up to `JSON_FRAME_MAX_DEPTH` levels from the
+ * validated root value; deeper containers fail with `JsonFrameValidationError`.
+ * For serialization the root is the exported payload including orient
+ * wrappers, so a deeper output layout may reject a cell accepted at ingestion.
  */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 /**
@@ -102,8 +104,15 @@ interface TablePayload extends JsonObject {
  * `options.columnTypes`.
  *
  * Explicit non-table `columnTypes` are validated against non-null cells without
- * coercion. `datetime` accepts pandas-style timezone-naive ISO date/datetime
- * strings for generated Table Schema output, not numeric epoch values.
+ * coercion. `datetime` accepts calendar-valid, timezone-naive ISO strings for
+ * four-digit years 0000–9999 under proleptic Gregorian rules (0000 is a leap
+ * year). Grammar: `YYYY-MM-DD`, optionally followed by `T` or a space and
+ * `HH:mm:ss`, optionally with 1–9 fractional-second digits. Hours are 00–23;
+ * minutes/seconds are 00–59. Numeric epochs and timezone suffixes are rejected.
+ * Strings are preserved exactly. Calendar validity does not guarantee pandas
+ * read-back: dtype/resolution limits, including nanosecond bounds for table
+ * read-back, can exclude accepted years. Inferred ISO-looking strings stay
+ * `string` unless Table Schema or an explicit type says otherwise.
  * `categorical` accepts non-null scalar JSON values and exports as Table Schema
  * `type: 'any'` with `extDtype: 'category'` when no source field metadata is
  * available. `mixed` and `unknown` accept any JSON-compatible cell value.
@@ -132,19 +141,44 @@ interface FromOrientOptions {
     /**
      * Explicit logical column types applied after parsing when no Table Schema is
      * present. Non-null cells must already be compatible; values are never
-     * coerced to satisfy the declared logical type.
+     * coerced to satisfy the declared logical type. Only own enumerable string
+     * keys are overrides; inherited properties are ignored. Names such as
+     * `constructor` and `__proto__` are valid column labels.
      */
     readonly columnTypes?: Readonly<Partial<Record<ColumnLabel, ColumnType>>>;
     /** Packing threshold for typed-array storage. `0` disables packing. */
     readonly packThreshold?: number;
+    /**
+     * Optional positive safe integer limiting ingestion traversal occurrences.
+     * Counts the parsed root and every scalar/container value, including repeated
+     * aliases. Exact-budget inputs succeed; excess fails with a path-bearing
+     * JsonFrameValidationError. Omitted means no quota. Not retained by the frame
+     * for exports. Does not bound JSON.parse/input bytes, key allocation, frame
+     * densification, caller hooks, or total memory.
+     * @example fromOrient([{ n: 1 }], { orient: 'records', maxNodes: 3 })
+     */
+    readonly maxNodes?: number;
 }
 /** Options for `toTable()` and `toJSONString('table', ...)`. */
 interface ToTableOptions {
     /** Override the emitted table index field name when the default would collide. */
     readonly indexField?: string;
 }
-/** Additional options accepted by `toJSONString()`. */
-type ToJSONStringOptions = ToTableOptions;
+/** Options validated for every `toJSONString()` orient; indexField affects table only. */
+interface ToJSONStringOptions extends ToTableOptions {
+    /**
+     * Optional positive safe integer limiting the complete exported payload's
+     * validation traversal. Counts root, orient wrappers, table metadata and every
+     * scalar/container occurrence, revisiting aliases. Exact-budget succeeds;
+     * excess throws path-bearing JsonFrameValidationError with the selected orient.
+     * No default quota; resets per call, independently of ingestion maxNodes.
+     * Does not bound payload construction, key allocation, string bytes, native
+     * serialization hooks, or total memory. Validation does not clone cells.
+     * @example frame.toJSONString('records', { maxNodes: 3 })
+     * @example frame.toJSONString('table', { indexField: 'row_id', maxNodes: 100 })
+     */
+    readonly maxNodes?: number;
+}
 /**
  * Immutable column-major view over pandas-compatible tabular JSON.
  *
@@ -167,7 +201,26 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
     toSplit(): SplitPayload;
     /** Exports Table Schema JSON; source index labels must be unique primary-key values. */
     toTable(options?: ToTableOptions): TablePayload;
-    /** Serializes an exported orient, including table metadata, within `JSON_FRAME_MAX_DEPTH`. */
+    /**
+     * Serializes an exported orient within `JSON_FRAME_MAX_DEPTH`.
+     *
+     * Depth is measured from the exported payload root including orient
+     * wrappers; `split`/`table` nest cells one level deeper than
+     * `records`/`values`/`index`/`columns`, so an input accepted at its own
+     * depth limit may be rejected in a deeper output layout. The complete
+     * selected output is validated before native serialization: cycles,
+     * over-depth containers, sparse arrays, and non-JSON values introduced
+     * through caller-mutable nested cells fail with path-bearing
+     * `JsonFrameValidationError` carrying the selected orient. Validation is one
+     * traversal pass without cloning followed by native stringification; both
+     * passes expand repeated references per occurrence. Optional maxNodes limits
+     * validation visits, including root/wrappers/metadata, independently per call
+     * with no default quota or inherited ingestion budget. It does not bound
+     * payload construction, key allocation, bytes, or total memory.
+     * Property getters/`Proxy` traps run during traversal and `toJSON`
+     * hooks may run during stringification; hooks are caller responsibility and
+     * are not sandboxed.
+     */
     toJSONString(orient: ResolvedOrient, options?: ToJSONStringOptions): string;
     row(position: number): Readonly<TRow>;
     rows(): readonly Readonly<TRow>[];
@@ -178,6 +231,26 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
     resetIndex(): DataFrame<TRow>;
 }
 
+type RecordKeys<T> = T extends unknown ? Extract<keyof T, string | number> : never;
+type IndexRecordKeys<K extends PropertyKey> = K extends unknown ? Record<never, never> extends Record<K, never> ? K : never : never;
+type CanonicalRecord<T> = T extends unknown ? {
+    [K in keyof T as K extends string | number ? `${K}` : never]: T[K];
+} : never;
+type VariantRequiresKey<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? Pick<T, K> extends Required<Pick<T, K>> ? true : false : false : never;
+type RequiredRecordKeys<T> = {
+    [K in RecordKeys<T>]: false extends VariantRequiresKey<T, K> ? never : K;
+}[RecordKeys<T>];
+type RecordCell<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? Exclude<T[K], undefined> : never : never;
+type NormalizedRecord<T> = {
+    [K in RequiredRecordKeys<T>]: RecordCell<T, K>;
+} & {
+    [K in Exclude<RecordKeys<T>, RequiredRecordKeys<T>>]?: RecordCell<T, K> | null;
+};
+type FlattenedRecord<T> = {
+    [K in keyof NormalizedRecord<T>]: NormalizedRecord<T>[K];
+};
+type InferredRecord<T> = Extract<T, readonly unknown[]> extends never ? [RecordKeys<T>] extends [never] ? JsonRow : [IndexRecordKeys<RecordKeys<T>>] extends [never] ? FlattenedRecord<CanonicalRecord<T>> : JsonRow : JsonRow;
+type InferredRecordsFrame<T> = InferredRecord<T> extends infer TRow extends JsonCompatibleRow<TRow> ? DataFrame<TRow> : DataFrame<JsonRow>;
 /**
  * Parses pandas-compatible JSON into an immutable `DataFrame`.
  *
@@ -193,9 +266,32 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
  * preserved for those labels. JSON arrays/objects may nest up to
  * `JSON_FRAME_MAX_DEPTH` levels from the parsed root value. Explicit non-table
  * `columnTypes` are validated against non-null cells and never coerce values.
+ *
+ * Parsed records infer known required fields precisely. Fields missing from
+ * any record variant or declared optional include `null` for normalization;
+ * they remain optional because a column absent from every row is not created.
+ * This includes Object-member names such as `toString` and `constructor`:
+ * inherited members do not supply cells. Numeric literal keys and their string
+ * spellings (1 and '1') infer one string-named column with the combined cell
+ * types, accessible through either spelling. Open index domains (string,
+ * number, or template patterns such as `metric_${string}` and `${number}`)
+ * fall back to `JsonRow`, including unions/intersections with known fields.
+ * They do not promise every matching column is present; use scalar guards
+ * such as `typeof cell === 'number'` before numeric operations. Finite template
+ * key unions retain precise fields, including their optionality.
+ * Union variants are flattened, so discriminants do not imply cell presence.
+ * Normalization is shallow; nested cell types are preserved.
+ * Arrays (including readonly tuples) infer object-shaped `JsonRow` values,
+ * not array rows. Broad records/options and other layouts may also fall back
+ * to `JsonRow`. An explicit domain generic preserves the caller's row model;
+ * it is an assertion, not runtime schema validation.
  */
 declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: string, options?: FromOrientOptions): DataFrame<TRow>;
-declare function fromOrient<TRow extends JsonCompatibleRow<TRow>>(input: readonly TRow[], options?: FromOrientOptions & {
+declare function fromOrient<TRecords extends readonly object[]>(input: TRecords & readonly JsonCompatibleRow<TRecords[number]>[], options?: FromOrientOptions & {
+    readonly orient?: 'auto' | 'records';
+}): InferredRecordsFrame<TRecords[number]>;
+/** Explicit domain row assertion; does not infer or validate an application schema. */
+declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: readonly NoInfer<TRow>[], options?: FromOrientOptions & {
     readonly orient?: 'auto' | 'records';
 }): DataFrame<TRow>;
 declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: SplitPayload, options: FromOrientOptions & {
@@ -208,8 +304,15 @@ declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(inpu
 
 /**
  * Maximum supported nesting for JSON arrays/objects traversed by the package.
- * The parsed root is depth 0; an array/object at depth 1000 is accepted, while
- * an array/object at depth 1001 fails with `JsonFrameValidationError`.
+ * Depth is measured from the validated root at depth 0; an array/object at
+ * depth 1000 is accepted, while an array/object at depth 1001 fails with
+ * `JsonFrameValidationError`.
+ *
+ * The root is the parsed input for ingestion and the complete exported payload
+ * for serialization, including orient-specific wrappers. A nested cell accepted
+ * at ingestion may therefore be rejected when serialized in a deeper output
+ * layout (for example `split`/`table` wrap cells one level deeper than
+ * `records`/`values`/`index`/`columns`).
  */
 declare const JSON_FRAME_MAX_DEPTH = 1000;
 
@@ -220,7 +323,22 @@ type JsonFrameErrorContext = {
     readonly column?: string;
     readonly value?: unknown;
 };
-/** Bounded value stored on structured errors instead of caller-owned containers. */
+/**
+ * Bounded value stored on structured errors instead of caller-owned containers.
+ *
+ * Container summaries are bounded: object summaries retain at most 5 keys and
+ * at most 200 characters of key-preview text in total. `truncated` is `true`
+ * when either the key count or the key-preview text was shortened. `keyCount`
+ * always reports the full key count. Array summaries retain only `length`.
+ *
+ * Scalar diagnostics are intentionally not bounded by that preview budget:
+ * scalar `string`/`number`/`boolean`/`null` values, plus `orient`, `path`,
+ * `row`, `column`, `option`, `key`, and `labels` fields, can still be
+ * input-sized. Summaries are frozen, never retain caller containers, and never
+ * invoke user `toJSON` hooks. Counting keys uses `Object.keys()`, which visits
+ * every own key, so construction is not constant-space even though the retained
+ * preview is bounded.
+ */
 type JsonFrameDiagnosticValue = string | number | boolean | null | Readonly<{
     readonly kind: 'array';
     readonly length: number;

package/index.d.ts

@@ -8,8 +8,10 @@ interface JsonObject {
 }
 /**
  * Any JSON-compatible value accepted by `fromOrient` payloads and exporters.
- * Arrays/objects may nest up to `JSON_FRAME_MAX_DEPTH` levels from the parsed
- * root value; deeper containers fail with `JsonFrameValidationError`.
+ * Arrays/objects may nest up to `JSON_FRAME_MAX_DEPTH` levels from the
+ * validated root value; deeper containers fail with `JsonFrameValidationError`.
+ * For serialization the root is the exported payload including orient
+ * wrappers, so a deeper output layout may reject a cell accepted at ingestion.
  */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 /**
@@ -102,8 +104,15 @@ interface TablePayload extends JsonObject {
  * `options.columnTypes`.
  *
  * Explicit non-table `columnTypes` are validated against non-null cells without
- * coercion. `datetime` accepts pandas-style timezone-naive ISO date/datetime
- * strings for generated Table Schema output, not numeric epoch values.
+ * coercion. `datetime` accepts calendar-valid, timezone-naive ISO strings for
+ * four-digit years 0000–9999 under proleptic Gregorian rules (0000 is a leap
+ * year). Grammar: `YYYY-MM-DD`, optionally followed by `T` or a space and
+ * `HH:mm:ss`, optionally with 1–9 fractional-second digits. Hours are 00–23;
+ * minutes/seconds are 00–59. Numeric epochs and timezone suffixes are rejected.
+ * Strings are preserved exactly. Calendar validity does not guarantee pandas
+ * read-back: dtype/resolution limits, including nanosecond bounds for table
+ * read-back, can exclude accepted years. Inferred ISO-looking strings stay
+ * `string` unless Table Schema or an explicit type says otherwise.
  * `categorical` accepts non-null scalar JSON values and exports as Table Schema
  * `type: 'any'` with `extDtype: 'category'` when no source field metadata is
  * available. `mixed` and `unknown` accept any JSON-compatible cell value.
@@ -132,19 +141,44 @@ interface FromOrientOptions {
     /**
      * Explicit logical column types applied after parsing when no Table Schema is
      * present. Non-null cells must already be compatible; values are never
-     * coerced to satisfy the declared logical type.
+     * coerced to satisfy the declared logical type. Only own enumerable string
+     * keys are overrides; inherited properties are ignored. Names such as
+     * `constructor` and `__proto__` are valid column labels.
      */
     readonly columnTypes?: Readonly<Partial<Record<ColumnLabel, ColumnType>>>;
     /** Packing threshold for typed-array storage. `0` disables packing. */
     readonly packThreshold?: number;
+    /**
+     * Optional positive safe integer limiting ingestion traversal occurrences.
+     * Counts the parsed root and every scalar/container value, including repeated
+     * aliases. Exact-budget inputs succeed; excess fails with a path-bearing
+     * JsonFrameValidationError. Omitted means no quota. Not retained by the frame
+     * for exports. Does not bound JSON.parse/input bytes, key allocation, frame
+     * densification, caller hooks, or total memory.
+     * @example fromOrient([{ n: 1 }], { orient: 'records', maxNodes: 3 })
+     */
+    readonly maxNodes?: number;
 }
 /** Options for `toTable()` and `toJSONString('table', ...)`. */
 interface ToTableOptions {
     /** Override the emitted table index field name when the default would collide. */
     readonly indexField?: string;
 }
-/** Additional options accepted by `toJSONString()`. */
-type ToJSONStringOptions = ToTableOptions;
+/** Options validated for every `toJSONString()` orient; indexField affects table only. */
+interface ToJSONStringOptions extends ToTableOptions {
+    /**
+     * Optional positive safe integer limiting the complete exported payload's
+     * validation traversal. Counts root, orient wrappers, table metadata and every
+     * scalar/container occurrence, revisiting aliases. Exact-budget succeeds;
+     * excess throws path-bearing JsonFrameValidationError with the selected orient.
+     * No default quota; resets per call, independently of ingestion maxNodes.
+     * Does not bound payload construction, key allocation, string bytes, native
+     * serialization hooks, or total memory. Validation does not clone cells.
+     * @example frame.toJSONString('records', { maxNodes: 3 })
+     * @example frame.toJSONString('table', { indexField: 'row_id', maxNodes: 100 })
+     */
+    readonly maxNodes?: number;
+}
 /**
  * Immutable column-major view over pandas-compatible tabular JSON.
  *
@@ -167,7 +201,26 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
     toSplit(): SplitPayload;
     /** Exports Table Schema JSON; source index labels must be unique primary-key values. */
     toTable(options?: ToTableOptions): TablePayload;
-    /** Serializes an exported orient, including table metadata, within `JSON_FRAME_MAX_DEPTH`. */
+    /**
+     * Serializes an exported orient within `JSON_FRAME_MAX_DEPTH`.
+     *
+     * Depth is measured from the exported payload root including orient
+     * wrappers; `split`/`table` nest cells one level deeper than
+     * `records`/`values`/`index`/`columns`, so an input accepted at its own
+     * depth limit may be rejected in a deeper output layout. The complete
+     * selected output is validated before native serialization: cycles,
+     * over-depth containers, sparse arrays, and non-JSON values introduced
+     * through caller-mutable nested cells fail with path-bearing
+     * `JsonFrameValidationError` carrying the selected orient. Validation is one
+     * traversal pass without cloning followed by native stringification; both
+     * passes expand repeated references per occurrence. Optional maxNodes limits
+     * validation visits, including root/wrappers/metadata, independently per call
+     * with no default quota or inherited ingestion budget. It does not bound
+     * payload construction, key allocation, bytes, or total memory.
+     * Property getters/`Proxy` traps run during traversal and `toJSON`
+     * hooks may run during stringification; hooks are caller responsibility and
+     * are not sandboxed.
+     */
     toJSONString(orient: ResolvedOrient, options?: ToJSONStringOptions): string;
     row(position: number): Readonly<TRow>;
     rows(): readonly Readonly<TRow>[];
@@ -178,6 +231,26 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
     resetIndex(): DataFrame<TRow>;
 }
 
+type RecordKeys<T> = T extends unknown ? Extract<keyof T, string | number> : never;
+type IndexRecordKeys<K extends PropertyKey> = K extends unknown ? Record<never, never> extends Record<K, never> ? K : never : never;
+type CanonicalRecord<T> = T extends unknown ? {
+    [K in keyof T as K extends string | number ? `${K}` : never]: T[K];
+} : never;
+type VariantRequiresKey<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? Pick<T, K> extends Required<Pick<T, K>> ? true : false : false : never;
+type RequiredRecordKeys<T> = {
+    [K in RecordKeys<T>]: false extends VariantRequiresKey<T, K> ? never : K;
+}[RecordKeys<T>];
+type RecordCell<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? Exclude<T[K], undefined> : never : never;
+type NormalizedRecord<T> = {
+    [K in RequiredRecordKeys<T>]: RecordCell<T, K>;
+} & {
+    [K in Exclude<RecordKeys<T>, RequiredRecordKeys<T>>]?: RecordCell<T, K> | null;
+};
+type FlattenedRecord<T> = {
+    [K in keyof NormalizedRecord<T>]: NormalizedRecord<T>[K];
+};
+type InferredRecord<T> = Extract<T, readonly unknown[]> extends never ? [RecordKeys<T>] extends [never] ? JsonRow : [IndexRecordKeys<RecordKeys<T>>] extends [never] ? FlattenedRecord<CanonicalRecord<T>> : JsonRow : JsonRow;
+type InferredRecordsFrame<T> = InferredRecord<T> extends infer TRow extends JsonCompatibleRow<TRow> ? DataFrame<TRow> : DataFrame<JsonRow>;
 /**
  * Parses pandas-compatible JSON into an immutable `DataFrame`.
  *
@@ -193,9 +266,32 @@ interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
  * preserved for those labels. JSON arrays/objects may nest up to
  * `JSON_FRAME_MAX_DEPTH` levels from the parsed root value. Explicit non-table
  * `columnTypes` are validated against non-null cells and never coerce values.
+ *
+ * Parsed records infer known required fields precisely. Fields missing from
+ * any record variant or declared optional include `null` for normalization;
+ * they remain optional because a column absent from every row is not created.
+ * This includes Object-member names such as `toString` and `constructor`:
+ * inherited members do not supply cells. Numeric literal keys and their string
+ * spellings (1 and '1') infer one string-named column with the combined cell
+ * types, accessible through either spelling. Open index domains (string,
+ * number, or template patterns such as `metric_${string}` and `${number}`)
+ * fall back to `JsonRow`, including unions/intersections with known fields.
+ * They do not promise every matching column is present; use scalar guards
+ * such as `typeof cell === 'number'` before numeric operations. Finite template
+ * key unions retain precise fields, including their optionality.
+ * Union variants are flattened, so discriminants do not imply cell presence.
+ * Normalization is shallow; nested cell types are preserved.
+ * Arrays (including readonly tuples) infer object-shaped `JsonRow` values,
+ * not array rows. Broad records/options and other layouts may also fall back
+ * to `JsonRow`. An explicit domain generic preserves the caller's row model;
+ * it is an assertion, not runtime schema validation.
  */
 declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: string, options?: FromOrientOptions): DataFrame<TRow>;
-declare function fromOrient<TRow extends JsonCompatibleRow<TRow>>(input: readonly TRow[], options?: FromOrientOptions & {
+declare function fromOrient<TRecords extends readonly object[]>(input: TRecords & readonly JsonCompatibleRow<TRecords[number]>[], options?: FromOrientOptions & {
+    readonly orient?: 'auto' | 'records';
+}): InferredRecordsFrame<TRecords[number]>;
+/** Explicit domain row assertion; does not infer or validate an application schema. */
+declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: readonly NoInfer<TRow>[], options?: FromOrientOptions & {
     readonly orient?: 'auto' | 'records';
 }): DataFrame<TRow>;
 declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: SplitPayload, options: FromOrientOptions & {
@@ -208,8 +304,15 @@ declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(inpu
 
 /**
  * Maximum supported nesting for JSON arrays/objects traversed by the package.
- * The parsed root is depth 0; an array/object at depth 1000 is accepted, while
- * an array/object at depth 1001 fails with `JsonFrameValidationError`.
+ * Depth is measured from the validated root at depth 0; an array/object at
+ * depth 1000 is accepted, while an array/object at depth 1001 fails with
+ * `JsonFrameValidationError`.
+ *
+ * The root is the parsed input for ingestion and the complete exported payload
+ * for serialization, including orient-specific wrappers. A nested cell accepted
+ * at ingestion may therefore be rejected when serialized in a deeper output
+ * layout (for example `split`/`table` wrap cells one level deeper than
+ * `records`/`values`/`index`/`columns`).
  */
 declare const JSON_FRAME_MAX_DEPTH = 1000;
 
@@ -220,7 +323,22 @@ type JsonFrameErrorContext = {
     readonly column?: string;
     readonly value?: unknown;
 };
-/** Bounded value stored on structured errors instead of caller-owned containers. */
+/**
+ * Bounded value stored on structured errors instead of caller-owned containers.
+ *
+ * Container summaries are bounded: object summaries retain at most 5 keys and
+ * at most 200 characters of key-preview text in total. `truncated` is `true`
+ * when either the key count or the key-preview text was shortened. `keyCount`
+ * always reports the full key count. Array summaries retain only `length`.
+ *
+ * Scalar diagnostics are intentionally not bounded by that preview budget:
+ * scalar `string`/`number`/`boolean`/`null` values, plus `orient`, `path`,
+ * `row`, `column`, `option`, `key`, and `labels` fields, can still be
+ * input-sized. Summaries are frozen, never retain caller containers, and never
+ * invoke user `toJSON` hooks. Counting keys uses `Object.keys()`, which visits
+ * every own key, so construction is not constant-space even though the retained
+ * preview is bounded.
+ */
 type JsonFrameDiagnosticValue = string | number | boolean | null | Readonly<{
     readonly kind: 'array';
     readonly length: number;