@web-ts-toolkit/json-frame 0.40.1 → 0.42.0

package/index.d.ts

@@ -6,8 +6,29 @@ type JsonArray = readonly JsonValue[];
 interface JsonObject {
     readonly [key: string]: JsonValue;
 }
-/** Any JSON-compatible value accepted by `fromOrient` payloads and exporters. */
+/**
+ * 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`.
+ */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/**
+ * Recursive compile-time JSON compatibility check for domain row interfaces.
+ *
+ * This lets ordinary interfaces with known JSON-compatible properties be used
+ * as `DataFrame` row models without requiring a string index signature. It is
+ * only a TypeScript constraint; runtime validation still follows the selected
+ * orient and does not validate application schemas from `TRow`.
+ */
+type JsonCompatible<T> = T extends JsonPrimitive ? T : T extends (...args: never[]) => unknown ? never : T extends readonly (infer TItem)[] ? readonly JsonCompatible<TItem>[] : T extends object ? {
+    readonly [K in keyof T]: JsonCompatible<T[K]>;
+} : never;
+/** Object-shaped row model whose known properties are JSON-compatible. */
+type JsonCompatibleRow<TRow extends object> = {
+    readonly [K in keyof TRow]: JsonCompatible<TRow[K]>;
+};
+/** Default row shape used when callers do not provide a domain row model. */
+type JsonRow = Record<string, JsonValue>;
 /** pandas orient names supported by `fromOrient`. */
 type ResolvedOrient = 'records' | 'index' | 'columns' | 'values' | 'split' | 'table';
 /** Orient selection for `fromOrient`. `auto` performs structural detection when possible. */
@@ -20,27 +41,39 @@ type IndexLabel = string | number;
 type IndexKind = 'source' | 'synthetic';
 /** Parsed payload for `orient='records'`. */
 type RecordsPayload = readonly JsonObject[];
-/** Parsed payload for `orient='index'`. */
+/**
+ * Parsed payload for `orient='index'`.
+ *
+ * Row order follows JavaScript property enumeration for object keys, including
+ * numeric ordering of integer-like keys. Use `SplitPayload` or `TablePayload`
+ * when exact row order matters for integer-like index labels.
+ */
 type IndexPayload = Readonly<Record<string, JsonObject>>;
-/** Parsed payload for `orient='columns'`. */
+/**
+ * Parsed payload for `orient='columns'`.
+ *
+ * Row order follows JavaScript property enumeration for each column object's
+ * index keys, including numeric ordering of integer-like keys. Use
+ * `SplitPayload` or `TablePayload` when exact row order matters for
+ * integer-like index labels.
+ */
 type ColumnsPayload = Readonly<Record<string, JsonObject>>;
 /** Parsed payload for `orient='values'`. */
 type ValuesPayload = readonly JsonArray[];
 /** Parsed payload for `orient='split'`. */
-interface SplitPayload {
+interface SplitPayload extends JsonObject {
     readonly columns: readonly ColumnLabel[];
     readonly index: readonly IndexLabel[];
     readonly data: readonly JsonArray[];
 }
 /** Known Frictionless/Table Schema field types emitted by pandas. */
 type TableSchemaFieldType = 'any' | 'array' | 'boolean' | 'date' | 'datetime' | 'duration' | 'geojson' | 'integer' | 'number' | 'object' | 'string' | 'year' | 'yearmonth' | (string & {});
+type JsonMetadata = Readonly<Record<string, JsonValue>>;
 /** Table Schema constraint metadata preserved when present. */
-interface TableSchemaConstraints {
+type TableSchemaConstraints = JsonMetadata & {
     /** Enumerated allowed scalar values, commonly used for pandas categoricals. */
     readonly enum?: readonly JsonPrimitive[];
-    readonly [key: string]: JsonValue | undefined;
-}
-type JsonMetadata = Readonly<Record<string, JsonValue | undefined>>;
+};
 /** Table Schema field metadata preserved during table ingestion and export. */
 type TableSchemaField = JsonMetadata & {
     readonly name: string;
@@ -56,14 +89,25 @@ type TableSchemaField = JsonMetadata & {
 type TableSchema = JsonMetadata & {
     readonly fields: readonly TableSchemaField[];
     readonly primaryKey?: readonly string[];
+    /** Table Schema format version emitted by pandas, not the installed pandas package version. */
     readonly pandas_version?: string;
 };
 /** Parsed payload for `orient='table'`. */
-interface TablePayload {
+interface TablePayload extends JsonObject {
     readonly schema: TableSchema;
     readonly data: readonly JsonObject[];
 }
-/** Logical column types inferred or preserved by the frame. */
+/**
+ * Logical column types inferred, preserved from Table Schema, or supplied with
+ * `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.
+ * `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.
+ */
 type ColumnType = 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'categorical' | 'mixed' | 'unknown';
 /** Public logical type metadata for a stored column. */
 interface ColumnInfo {
@@ -75,16 +119,21 @@ interface ColumnInfo {
 /**
  * Options for `fromOrient`.
  *
- * `columns` is required only for explicit `values` input because that orient
- * carries no column labels. `columnTypes` supplies explicit logical metadata
- * for label-preserving orients that do not carry Table Schema field types.
+ * `columns` is required whenever the payload is `values`, including non-empty
+ * `values` arrays detected by `auto`, because that orient carries no column
+ * labels. `columnTypes` supplies explicit logical metadata for label-preserving
+ * orients that do not carry Table Schema field types.
  */
 interface FromOrientOptions {
     /** Explicit orient, or `auto` to detect only structurally unambiguous shapes. */
     readonly orient?: Orient;
-    /** Explicit column names used when parsing `orient='values'`. */
+    /** Explicit column names used whenever parsing a `values` payload. */
     readonly columns?: readonly ColumnLabel[];
-    /** Explicit logical column types applied after parsing when no Table Schema is present. */
+    /**
+     * 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.
+     */
     readonly columnTypes?: Readonly<Partial<Record<ColumnLabel, ColumnType>>>;
     /** Packing threshold for typed-array storage. `0` disables packing. */
     readonly packThreshold?: number;
@@ -101,9 +150,12 @@ type ToJSONStringOptions = ToTableOptions;
  *
  * Instances are created by `fromOrient()`. The generic row type improves row
  * and callback ergonomics only; runtime validation still follows the JSON
- * Frame contracts for the selected orient.
+ * Frame contracts for the selected orient. Immutability is structural and
+ * shallow: frame-owned arrays, records, and maps are protected, but nested JSON
+ * cell objects/arrays returned from rows or exporters may retain identity and
+ * remain caller-mutable.
  */
-interface DataFrame<TRow extends Record<string, JsonValue> = Record<string, JsonValue>> {
+interface DataFrame<TRow extends JsonCompatibleRow<TRow> = JsonRow> {
     readonly columns: readonly string[];
     readonly index: readonly IndexLabel[];
     readonly columnInfo: ReadonlyMap<string, ColumnInfo>;
@@ -113,31 +165,53 @@ interface DataFrame<TRow extends Record<string, JsonValue> = Record<string, Json
     toColumns(): ColumnsPayload;
     toValues(): ValuesPayload;
     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`. */
     toJSONString(orient: ResolvedOrient, options?: ToJSONStringOptions): string;
     row(position: number): Readonly<TRow>;
     rows(): readonly Readonly<TRow>[];
     filter(predicate: (row: Readonly<TRow>, index: IndexLabel, position: number) => boolean): DataFrame<TRow>;
     sort(compare: (left: Readonly<TRow>, right: Readonly<TRow>, leftIndex: IndexLabel, rightIndex: IndexLabel, leftPosition: number, rightPosition: number) => number): DataFrame<TRow>;
-    select(...columns: readonly string[]): DataFrame<Record<string, JsonValue>>;
-    rename(mapping: Readonly<Record<string, string>>): DataFrame<Record<string, JsonValue>>;
+    select(...columns: readonly string[]): DataFrame<JsonRow>;
+    rename(mapping: Readonly<Record<string, string>>): DataFrame<JsonRow>;
     resetIndex(): DataFrame<TRow>;
 }
 
 /**
  * Parses pandas-compatible JSON into an immutable `DataFrame`.
  *
- * `auto` detection recognizes only structurally unambiguous payloads. Pass an
- * explicit `options.orient` for `index`, `columns`, empty arrays, empty
- * objects, and all `values` payloads. The generic row type is for TypeScript
- * ergonomics and is not runtime-validated beyond the documented JSON-orient
- * contracts.
+ * `auto` detection recognizes only structurally unambiguous payloads, including
+ * non-empty `values` arrays. Every `values` payload still requires
+ * `options.columns` because that orient carries no column labels; empty
+ * `values` input also requires explicit `options.orient: 'values'`. Pass an
+ * explicit `options.orient` for `index`, `columns`, empty arrays, and empty
+ * objects. The generic row type is for TypeScript ergonomics and is not
+ * runtime-validated beyond the documented JSON-orient contracts. `index` and
+ * `columns` object-key payloads follow JavaScript property enumeration order
+ * for integer-like keys; use `split` or `table` when exact row order must be
+ * 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.
  */
-declare function fromOrient<TRow extends Record<string, JsonValue> = Record<string, JsonValue>>(input: string, options?: FromOrientOptions): DataFrame<TRow>;
-declare function fromOrient<TRow extends Record<string, JsonValue>>(input: readonly TRow[], options?: FromOrientOptions & {
+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 & {
     readonly orient?: 'auto' | 'records';
 }): DataFrame<TRow>;
-declare function fromOrient<TRow extends Record<string, JsonValue> = Record<string, JsonValue>>(input: JsonValue, options?: FromOrientOptions): DataFrame<TRow>;
+declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: SplitPayload, options: FromOrientOptions & {
+    readonly orient: 'split';
+}): DataFrame<TRow>;
+declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: TablePayload, options: FromOrientOptions & {
+    readonly orient: 'table';
+}): DataFrame<TRow>;
+declare function fromOrient<TRow extends JsonCompatibleRow<TRow> = JsonRow>(input: JsonValue, options?: FromOrientOptions): DataFrame<TRow>;
+
+/**
+ * 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`.
+ */
+declare const JSON_FRAME_MAX_DEPTH = 1000;
 
 type JsonFrameErrorContext = {
     readonly orient?: Orient;
@@ -146,13 +220,25 @@ type JsonFrameErrorContext = {
     readonly column?: string;
     readonly value?: unknown;
 };
+/** Bounded value stored on structured errors instead of caller-owned containers. */
+type JsonFrameDiagnosticValue = string | number | boolean | null | Readonly<{
+    readonly kind: 'array';
+    readonly length: number;
+}> | Readonly<{
+    readonly kind: 'object';
+    readonly keyCount: number;
+    readonly keys: readonly string[];
+    readonly truncated: boolean;
+}> | Readonly<{
+    readonly kind: 'undefined' | 'symbol' | 'bigint' | 'function';
+}>;
 /** Base class for all structured `@web-ts-toolkit/json-frame` runtime failures. */
 declare class JsonFrameError extends Error {
     readonly orient?: Orient;
     readonly path?: string;
     readonly row?: number;
     readonly column?: string;
-    readonly value?: unknown;
+    readonly value?: JsonFrameDiagnosticValue;
     constructor(message: string, context?: JsonFrameErrorContext);
 }
 /** Raised when a JSON string cannot be parsed before orient validation begins. */
@@ -193,4 +279,4 @@ declare class ExportKeyCollisionError extends JsonFrameError {
     constructor(message: string, orient: ResolvedOrient, key: string, labels: readonly (string | number)[]);
 }
 
-export { AmbiguousOrientError, type ColumnInfo, type ColumnLabel, type ColumnType, type ColumnsPayload, type DataFrame, ExportKeyCollisionError, type FromOrientOptions, type IndexKind, type IndexLabel, type IndexPayload, type JsonArray, JsonFrameError, JsonFrameOptionError, JsonFrameParseError, JsonFrameValidationError, type JsonObject, type JsonPrimitive, type JsonValue, type Orient, type RecordsPayload, type ResolvedOrient, type SplitPayload, type TablePayload, type TableSchema, type TableSchemaConstraints, type TableSchemaField, type TableSchemaFieldType, type ToJSONStringOptions, type ToTableOptions, UnsupportedFeatureError, type ValuesPayload, fromOrient };
+export { AmbiguousOrientError, type ColumnInfo, type ColumnLabel, type ColumnType, type ColumnsPayload, type DataFrame, ExportKeyCollisionError, type FromOrientOptions, type IndexKind, type IndexLabel, type IndexPayload, JSON_FRAME_MAX_DEPTH, type JsonArray, type JsonCompatible, type JsonCompatibleRow, type JsonFrameDiagnosticValue, JsonFrameError, JsonFrameOptionError, JsonFrameParseError, JsonFrameValidationError, type JsonObject, type JsonPrimitive, type JsonRow, type JsonValue, type Orient, type RecordsPayload, type ResolvedOrient, type SplitPayload, type TablePayload, type TableSchema, type TableSchemaConstraints, type TableSchemaField, type TableSchemaFieldType, type ToJSONStringOptions, type ToTableOptions, UnsupportedFeatureError, type ValuesPayload, fromOrient };