@web-ts-toolkit/json-frame 0.34.3 → 0.36.0

package/README.md

@@ -1,3 +1,302 @@
 # `@web-ts-toolkit/json-frame`
 
-PLACEHOLDER
+Normalize pandas `DataFrame.to_json()` payloads into one immutable, column-major `DataFrame` API for TypeScript.
+
+`@web-ts-toolkit/json-frame` accepts a JSON string or parsed JSON value, ingests all six pandas DataFrame JSON orients, keeps row order and supported index labels intact, and exports back to every supported orient without adding runtime dependencies.
+
+## Installation
+
+```sh
+pnpm add @web-ts-toolkit/json-frame
+```
+
+Canonical import:
+
+```ts
+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.
+
+## Quick Start
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+type WeatherRow = {
+  city: string;
+  temp: number;
+};
+
+const frame = fromOrient<WeatherRow>('[{"city":"Paris","temp":21},{"city":"Rome","temp":30}]');
+const hottest = frame.sort((left, right) => right.temp - left.temp).row(0);
+const split = frame.toSplit();
+
+void [hottest, split];
+```
+
+`fromOrient(input, options?)` accepts:
+
+- a JSON string produced by pandas `DataFrame.to_json()`
+- a parsed JSON value with the same shape
+
+The returned `DataFrame` is immutable. `filter`, `sort`, `select`, `rename`, and `resetIndex` all return new frames.
+
+## Supported Orients
+
+All six pandas DataFrame JSON orients are supported.
+
+```ts
+import { fromOrient, type TablePayload } from '@web-ts-toolkit/json-frame';
+
+const recordsFrame = fromOrient([{ city: 'Paris', temp: 21 }], { orient: 'records' });
+
+const indexFrame = fromOrient(
+  {
+    row_1: { city: 'Paris', temp: 21 },
+  },
+  { orient: 'index' },
+);
+
+const columnsFrame = fromOrient(
+  {
+    city: { row_1: 'Paris' },
+    temp: { row_1: 21 },
+  },
+  { orient: 'columns' },
+);
+
+const valuesFrame = fromOrient([['Paris', 21]], {
+  orient: 'values',
+  columns: ['city', 'temp'],
+});
+
+const splitFrame = fromOrient(
+  {
+    columns: ['city', 'temp'],
+    index: ['row_1'],
+    data: [['Paris', 21]],
+  },
+  { orient: 'split' },
+);
+
+const tablePayload = {
+  schema: {
+    fields: [
+      { name: 'row_id', type: 'string' },
+      { name: 'city', type: 'string' },
+      { name: 'temp', type: 'integer' },
+    ],
+    primaryKey: ['row_id'],
+    pandas_version: '3.0.3',
+  },
+  data: [{ row_id: 'row_1', city: 'Paris', temp: 21 }],
+} satisfies TablePayload;
+
+const tableFrame = fromOrient(tablePayload, { orient: 'table' });
+
+void [recordsFrame, indexFrame, columnsFrame, valuesFrame, splitFrame, tableFrame];
+```
+
+Orient notes:
+
+- `records` and `values` do not carry source index labels. They receive a synthetic numeric index `0..n-1`.
+- `index`, `columns`, `split`, and `table` preserve supported source index labels.
+- `values` always requires `options.columns`, including empty input.
+- `index` and `columns` are distinct supported payloads, but auto-detection cannot safely distinguish them from nested-object structure alone.
+
+## Auto Detection And Options
+
+`options.orient` defaults to `auto`.
+
+Auto-detection recognizes only structurally unambiguous payloads:
+
+- `table`
+- `split`
+- non-empty `records`
+- non-empty `values`
+
+Pass an explicit orient for:
+
+- any `index` payload
+- any `columns` payload
+- empty arrays
+- empty objects
+- empty `values` payloads
+
+Other `fromOrient` options:
+
+- `columns`: required for `orient: 'values'`
+- `columnTypes`: explicit logical types for non-table inputs
+- `packThreshold`: minimum length for internal numeric typed-array packing; `0` disables packing
+
+```ts
+import { AmbiguousOrientError, JsonFrameOptionError, fromOrient } from '@web-ts-toolkit/json-frame';
+
+let candidates: readonly string[] = [];
+let option = '';
+
+try {
+  fromOrient({ row_1: { city: 'Paris', temp: 21 } });
+} catch (error) {
+  if (error instanceof AmbiguousOrientError) {
+    candidates = error.candidates;
+  }
+}
+
+try {
+  fromOrient([['Paris', 21]], { orient: 'values' });
+} catch (error) {
+  if (error instanceof JsonFrameOptionError) {
+    option = error.option;
+  }
+}
+
+void [candidates, option];
+```
+
+## Transforms And Exporters
+
+The `DataFrame` API is intentionally small and predictable.
+
+Read access:
+
+- `columns`
+- `index`
+- `columnInfo`
+- `length`
+- `row(position)`
+- `rows()`
+
+Transforms:
+
+- `filter(predicate)`
+- `sort(compare)`
+- `select(...columns)`
+- `rename(mapping)`
+- `resetIndex()`
+
+Exporters:
+
+- `toRecords()`
+- `toIndex()`
+- `toColumns()`
+- `toValues()`
+- `toSplit()`
+- `toTable(options?)`
+- `toJSONString(orient, options?)`
+
+```ts
+import { fromOrient } from '@web-ts-toolkit/json-frame';
+
+type WeatherRow = {
+  city: string;
+  temp: number | null;
+  coastal: boolean;
+};
+
+const frame = fromOrient<WeatherRow>(
+  [
+    { city: 'Paris', temp: 21.5, coastal: false },
+    { city: 'Tokyo', temp: 27.1, coastal: true },
+    { city: 'Oslo', temp: null, coastal: true },
+  ],
+  {
+    orient: 'records',
+    columnTypes: {
+      temp: 'float',
+      coastal: 'boolean',
+    },
+    packThreshold: 0,
+  },
+);
+
+const transformed = frame
+  .filter((row) => row.temp !== null)
+  .sort((left, right) => (right.temp ?? -1) - (left.temp ?? -1))
+  .rename({ temp: 'celsius' })
+  .select('city', 'celsius')
+  .resetIndex();
+
+const table = transformed.toTable();
+const json = transformed.toJSONString('records');
+
+void [table, json];
+```
+
+Transform behavior:
+
+- row order is preserved unless you call `sort`
+- `sort` is stable
+- filtering and sorting preserve index labels
+- `resetIndex()` is the only transform that replaces the current index with `0..n-1`
+- `rename` ignores keys that are not current columns and rejects duplicate results
+- exporters always return fresh JSON-compatible containers
+
+## Logical Types And Packing
+
+`columnInfo` exposes logical type metadata for each column.
+
+Supported logical types:
+
+- `integer`
+- `float`
+- `string`
+- `boolean`
+- `datetime`
+- `categorical`
+- `mixed`
+- `unknown`
+
+Type rules:
+
+- Table Schema metadata is authoritative when `orient: 'table'` is used.
+- Other orients infer the narrowest logical type by scanning the full column.
+- `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 explicit `columnTypes` says otherwise.
+
+Packing rules:
+
+- typed-array packing is an internal optimization only
+- packed and unpacked frames export the same JSON values
+- packing never changes logical type metadata
+- only non-null numeric columns at or above `packThreshold` are eligible
+
+## Round Trips And Index Provenance
+
+Round trips are semantic rather than byte-for-byte.
+
+- column order, row order, and cell JSON values are preserved
+- label-bearing orients preserve supported source index labels
+- `records` and `values` use a synthetic numeric index because the wire format does not carry labels
+- `toRecords()` and `toValues()` never invent an `_index` column
+- `toIndex()` and `toColumns()` stringify index labels as JSON object keys and throw if distinct labels would collide after stringification
+- `toTable()` emits valid Table Schema and omits a synthetic index from table output
+
+## 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`
+- `JsonFrameValidationError`: payload shape 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
+
+## Unsupported Pandas Features In The Initial Release
+
+- MultiIndex input or output
+- duplicate column labels
+- non-string column labels
+- pandas Series JSON shapes
+- JSON Lines, compression, file I/O, or streaming input
+- arbitrary pandas extension dtype reconstruction beyond supported Table Schema metadata
+- deep freezing of nested JSON object values
+
+## Runtime Requirements
+
+- package source and published runtime are isomorphic
+- no runtime dependencies
+- no peer dependencies
+- published entrypoints: CJS, ESM, `.d.ts`, and `.d.mts`

package/index.d.mts

@@ -1,2 +1,196 @@
+/** Scalar JSON values accepted by `fromOrient` payloads and exporters. */
+type JsonPrimitive = string | number | boolean | null;
+/** JSON arrays accepted by `fromOrient` payloads and returned by exporters. */
+type JsonArray = readonly JsonValue[];
+/** JSON objects accepted by `fromOrient` payloads and returned by exporters. */
+interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/** Any JSON-compatible value accepted by `fromOrient` payloads and exporters. */
+type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/** pandas orient names supported by `fromOrient`. */
+type ResolvedOrient = 'records' | 'index' | 'columns' | 'values' | 'split' | 'table';
+/** Orient selection for `fromOrient`. `auto` performs structural detection when possible. */
+type Orient = 'auto' | ResolvedOrient;
+/** Public column labels are unique strings in the initial release. */
+type ColumnLabel = string;
+/** Supported index labels preserved by parsed frames and label-bearing exporters. */
+type IndexLabel = string | number;
+/** Internal index provenance exposed by later frame APIs. */
+type IndexKind = 'source' | 'synthetic';
+/** Parsed payload for `orient='records'`. */
+type RecordsPayload = readonly JsonObject[];
+/** Parsed payload for `orient='index'`. */
+type IndexPayload = Readonly<Record<string, JsonObject>>;
+/** Parsed payload for `orient='columns'`. */
+type ColumnsPayload = Readonly<Record<string, JsonObject>>;
+/** Parsed payload for `orient='values'`. */
+type ValuesPayload = readonly JsonArray[];
+/** Parsed payload for `orient='split'`. */
+interface SplitPayload {
+    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 & {});
+/** Table Schema constraint metadata preserved when present. */
+interface TableSchemaConstraints {
+    /** 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;
+    readonly type: TableSchemaFieldType;
+    readonly format?: string;
+    readonly constraints?: TableSchemaConstraints;
+    readonly ordered?: boolean;
+    readonly extDtype?: string;
+    readonly tz?: string;
+    readonly freq?: string;
+};
+/** Table Schema metadata preserved for `orient='table'`. */
+type TableSchema = JsonMetadata & {
+    readonly fields: readonly TableSchemaField[];
+    readonly primaryKey?: readonly string[];
+    readonly pandas_version?: string;
+};
+/** Parsed payload for `orient='table'`. */
+interface TablePayload {
+    readonly schema: TableSchema;
+    readonly data: readonly JsonObject[];
+}
+/** Logical column types inferred or preserved by the frame. */
+type ColumnType = 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'categorical' | 'mixed' | 'unknown';
+/** Public logical type metadata for a stored column. */
+interface ColumnInfo {
+    /** Narrowest logical type inferred or preserved for the column. */
+    readonly type: ColumnType;
+    /** Whether any row in the column contains `null`. */
+    readonly nullable: boolean;
+}
+/**
+ * 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.
+ */
+interface FromOrientOptions {
+    /** Explicit orient, or `auto` to detect only structurally unambiguous shapes. */
+    readonly orient?: Orient;
+    /** Explicit column names used when parsing `orient='values'`. */
+    readonly columns?: readonly ColumnLabel[];
+    /** Explicit logical column types applied after parsing when no Table Schema is present. */
+    readonly columnTypes?: Readonly<Partial<Record<ColumnLabel, ColumnType>>>;
+    /** Packing threshold for typed-array storage. `0` disables packing. */
+    readonly packThreshold?: 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;
+/**
+ * Immutable column-major view over pandas-compatible tabular JSON.
+ *
+ * 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.
+ */
+interface DataFrame<TRow extends Record<string, JsonValue> = Record<string, JsonValue>> {
+    readonly columns: readonly string[];
+    readonly index: readonly IndexLabel[];
+    readonly columnInfo: ReadonlyMap<string, ColumnInfo>;
+    readonly length: number;
+    toRecords(): RecordsPayload;
+    toIndex(): IndexPayload;
+    toColumns(): ColumnsPayload;
+    toValues(): ValuesPayload;
+    toSplit(): SplitPayload;
+    toTable(options?: ToTableOptions): TablePayload;
+    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>>;
+    resetIndex(): DataFrame<TRow>;
+}
 
-export {  }
+/**
+ * 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.
+ */
+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 & {
+    readonly orient?: 'auto' | 'records';
+}): DataFrame<TRow>;
+declare function fromOrient<TRow extends Record<string, JsonValue> = Record<string, JsonValue>>(input: JsonValue, options?: FromOrientOptions): DataFrame<TRow>;
+
+type JsonFrameErrorContext = {
+    readonly orient?: Orient;
+    readonly path?: string;
+    readonly row?: number;
+    readonly column?: string;
+    readonly value?: unknown;
+};
+/** 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;
+    constructor(message: string, context?: JsonFrameErrorContext);
+}
+/** Raised when a JSON string cannot be parsed before orient validation begins. */
+declare class JsonFrameParseError extends JsonFrameError {
+    readonly cause: SyntaxError;
+    constructor(message: string, cause: SyntaxError);
+}
+/** Raised when caller-supplied options are invalid before payload traversal begins. */
+declare class JsonFrameOptionError extends JsonFrameError {
+    readonly option: string;
+    constructor(message: string, option: string, value: unknown);
+}
+/** Raised when an orient payload violates the documented JSON Frame contract. */
+declare class JsonFrameValidationError extends JsonFrameError {
+    readonly orient?: ResolvedOrient;
+    constructor(message: string, context?: JsonFrameErrorContext & {
+        readonly orient?: ResolvedOrient;
+    });
+}
+/** Raised when `auto` detection cannot distinguish between multiple valid orients. */
+declare class AmbiguousOrientError extends JsonFrameError {
+    readonly candidates: readonly ResolvedOrient[];
+    constructor(message: string, candidates: readonly ResolvedOrient[]);
+}
+/** Raised when a pandas shape or feature is explicitly outside the initial release scope. */
+declare class UnsupportedFeatureError extends JsonFrameError {
+    readonly feature: string;
+    readonly orient?: ResolvedOrient;
+    constructor(message: string, feature: string, context?: JsonFrameErrorContext & {
+        readonly orient?: ResolvedOrient;
+    });
+}
+/** Raised when object-key exporters would collapse distinct index labels to the same JSON key. */
+declare class ExportKeyCollisionError extends JsonFrameError {
+    readonly key: string;
+    readonly labels: readonly (string | number)[];
+    readonly orient: ResolvedOrient;
+    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 };