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

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 };

package/index.d.ts

@@ -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 };