@web-ts-toolkit/json-frame 0.40.0 → 0.41.0

package/index.js

@@ -30,6 +30,7 @@ var index_exports = {};
 __export(index_exports, {
   AmbiguousOrientError: () => AmbiguousOrientError,
   ExportKeyCollisionError: () => ExportKeyCollisionError,
+  JSON_FRAME_MAX_DEPTH: () => JSON_FRAME_MAX_DEPTH,
   JsonFrameError: () => JsonFrameError,
   JsonFrameOptionError: () => JsonFrameOptionError,
   JsonFrameParseError: () => JsonFrameParseError,
@@ -40,7 +41,38 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
+var DIAGNOSTIC_KEY_LIMIT = 5;
 var freezeCopy = (values) => Object.freeze([...values]);
+var summarizeDiagnosticValue = (value) => {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze({ kind: "array", length: value.length });
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    return Object.freeze({
+      kind: "object",
+      keyCount: keys.length,
+      keys: freezeCopy(keys.slice(0, DIAGNOSTIC_KEY_LIMIT)),
+      truncated: keys.length > DIAGNOSTIC_KEY_LIMIT
+    });
+  }
+  if (typeof value === "undefined") {
+    return Object.freeze({ kind: "undefined" });
+  }
+  if (typeof value === "symbol") {
+    return Object.freeze({ kind: "symbol" });
+  }
+  if (typeof value === "bigint") {
+    return Object.freeze({ kind: "bigint" });
+  }
+  if (typeof value === "function") {
+    return Object.freeze({ kind: "function" });
+  }
+  return Object.freeze({ kind: "object", keyCount: 0, keys: freezeCopy([]), truncated: false });
+};
 var JsonFrameError = class extends Error {
   constructor(message, context = {}) {
     super(message);
@@ -50,7 +82,9 @@ var JsonFrameError = class extends Error {
     this.path = context.path;
     this.row = context.row;
     this.column = context.column;
-    this.value = context.value;
+    if ("value" in context) {
+      this.value = summarizeDiagnosticValue(context.value);
+    }
   }
 };
 var JsonFrameParseError = class extends JsonFrameError {
@@ -99,25 +133,494 @@ var ExportKeyCollisionError = class extends JsonFrameError {
   }
 };
 
+// src/frame/column.ts
+var INT32_MIN = -2147483648;
+var INT32_MAX = 2147483647;
+var freezeArray = (values) => Object.freeze([...values]);
+var freezeColumnInfo = (info) => Object.freeze({ ...info });
+var DATETIME_PATTERN = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})(?:[T ](?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.(?<fraction>\d{1,9}))?)?$/;
+var columnOperationCounters = {
+  materializeColumnCalls: 0,
+  materializedCells: 0,
+  scalarReads: 0,
+  rebuiltCells: 0,
+  nullableChecks: 0
+};
+var hasCategoricalMetadata = (field) => field.constraints?.enum !== void 0 || field.ordered === true || field.extDtype === "category";
+var mapTableSchemaFieldType = (field) => {
+  if (hasCategoricalMetadata(field)) {
+    return "categorical";
+  }
+  switch (field.type) {
+    case "boolean":
+      return "boolean";
+    case "integer":
+    case "year":
+      return "integer";
+    case "number":
+      return "float";
+    case "date":
+    case "datetime":
+      return "datetime";
+    case "string":
+      return "string";
+    case "any":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+};
+var inferColumnType = (values) => {
+  let nullable = false;
+  let sawBoolean = false;
+  let sawString = false;
+  let sawInteger = false;
+  let sawFloat = false;
+  let sawStructured = false;
+  for (const value of values) {
+    if (value === null) {
+      nullable = true;
+      continue;
+    }
+    if (typeof value === "boolean") {
+      sawBoolean = true;
+      continue;
+    }
+    if (typeof value === "string") {
+      sawString = true;
+      continue;
+    }
+    if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        sawInteger = true;
+      } else {
+        sawFloat = true;
+      }
+      continue;
+    }
+    sawStructured = true;
+  }
+  const nonNullKinds = [sawBoolean, sawString, sawInteger || sawFloat, sawStructured].filter(Boolean).length;
+  if (nonNullKinds === 0) {
+    return freezeColumnInfo({ type: "unknown", nullable });
+  }
+  if (sawStructured || nonNullKinds > 1 || sawBoolean && (sawString || sawInteger || sawFloat)) {
+    return freezeColumnInfo({ type: "mixed", nullable });
+  }
+  if (sawString) {
+    return freezeColumnInfo({ type: "string", nullable });
+  }
+  if (sawBoolean) {
+    return freezeColumnInfo({ type: "boolean", nullable });
+  }
+  if (sawFloat) {
+    return freezeColumnInfo({ type: "float", nullable });
+  }
+  return freezeColumnInfo({ type: "integer", nullable });
+};
+var isPandasNaiveIsoDatetime = (value) => {
+  const match = DATETIME_PATTERN.exec(value);
+  if (match?.groups === void 0) {
+    return false;
+  }
+  const year = Number(match.groups.year);
+  const month = Number(match.groups.month);
+  const day = Number(match.groups.day);
+  const hour = match.groups.hour === void 0 ? 0 : Number(match.groups.hour);
+  const minute = match.groups.minute === void 0 ? 0 : Number(match.groups.minute);
+  const second = match.groups.second === void 0 ? 0 : Number(match.groups.second);
+  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) {
+    return false;
+  }
+  const normalized = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+  return normalized.getUTCFullYear() === year && normalized.getUTCMonth() === month - 1 && normalized.getUTCDate() === day && normalized.getUTCHours() === hour && normalized.getUTCMinutes() === minute && normalized.getUTCSeconds() === second;
+};
+var isScalarCategory = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+var isJsonContainer = (value) => {
+  if (Array.isArray(value)) {
+    return true;
+  }
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+var isColumnValueCompatible = (type, value) => {
+  if (value === null) {
+    return true;
+  }
+  switch (type) {
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "float":
+      return typeof value === "number";
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "datetime":
+      return typeof value === "string" && isPandasNaiveIsoDatetime(value);
+    case "categorical":
+      return isScalarCategory(value);
+    case "mixed":
+    case "unknown":
+      return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isJsonContainer(value);
+    default: {
+      const exhaustive = type;
+      return exhaustive;
+    }
+  }
+};
+var getColumnCellPath = (orient, column, columnIndex, rowIndex, rowLabel) => {
+  switch (orient) {
+    case "records":
+      return `$[${rowIndex}][${JSON.stringify(column)}]`;
+    case "values":
+      return `$[${rowIndex}][${columnIndex}]`;
+    case "split":
+      return `$.data[${rowIndex}][${columnIndex}]`;
+    case "table":
+      return `$.data[${rowIndex}][${JSON.stringify(column)}]`;
+    case "index":
+      return `$[${JSON.stringify(String(rowLabel))}][${JSON.stringify(column)}]`;
+    case "columns":
+      return `$[${JSON.stringify(column)}][${JSON.stringify(String(rowLabel))}]`;
+    default:
+      return `$.data[${rowIndex}][${JSON.stringify(column)}]`;
+  }
+};
+var validateColumnValuesForType = ({
+  column,
+  columnIndex,
+  values,
+  type,
+  orient,
+  index
+}) => {
+  for (let rowIndex = 0; rowIndex < values.length; rowIndex += 1) {
+    const value = values[rowIndex];
+    if (isColumnValueCompatible(type, value)) {
+      continue;
+    }
+    throw new JsonFrameValidationError("Column cells are incompatible with the declared logical type.", {
+      ...orient === void 0 ? {} : { orient },
+      path: getColumnCellPath(orient, column, columnIndex, rowIndex, index?.[rowIndex]),
+      row: rowIndex,
+      column,
+      value
+    });
+  }
+};
+var packColumn = (values, info, packThreshold) => {
+  if (packThreshold === 0 || values.length < packThreshold || info.nullable) {
+    return freezeArray(values);
+  }
+  if (info.type === "integer") {
+    const packed = new Int32Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+      const value = values[index];
+      if (typeof value !== "number" || !Number.isInteger(value) || value < INT32_MIN || value > INT32_MAX) {
+        return freezeArray(values);
+      }
+      packed[index] = value;
+    }
+    return packed;
+  }
+  if (info.type === "float") {
+    const packed = new Float64Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+      const value = values[index];
+      if (typeof value !== "number") {
+        return freezeArray(values);
+      }
+      packed[index] = value;
+    }
+    return packed;
+  }
+  return freezeArray(values);
+};
+var hasNullValue = (values) => {
+  columnOperationCounters.nullableChecks += values.length;
+  for (const value of values) {
+    if (value === null) {
+      return true;
+    }
+  }
+  return false;
+};
+var validateExplicitColumnTypes = (columns, columnTypes) => {
+  if (columnTypes === void 0) {
+    return;
+  }
+  const knownColumns = new Set(columns);
+  for (const column of Object.keys(columnTypes)) {
+    if (!knownColumns.has(column)) {
+      throw new JsonFrameOptionError(
+        "`options.columnTypes` keys must match parsed column names.",
+        `columnTypes.${column}`,
+        columnTypes[column]
+      );
+    }
+  }
+};
+var resolveSchemaTypeByColumn = (frame) => {
+  if (frame.tableSchema === void 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const schemaTypes = /* @__PURE__ */ new Map();
+  for (const field of frame.tableSchema.fields) {
+    if (frame.columns.includes(field.name)) {
+      schemaTypes.set(field.name, mapTableSchemaFieldType(field));
+    }
+  }
+  return schemaTypes;
+};
+var materializeColumn = (column) => {
+  columnOperationCounters.materializeColumnCalls += 1;
+  columnOperationCounters.materializedCells += column.length;
+  return Array.isArray(column) ? freezeArray(column) : freezeArray(Array.from(column));
+};
+var getStoredColumnValue = (column, position) => {
+  columnOperationCounters.scalarReads += 1;
+  return column[position];
+};
+var rebuildStoredColumn = (column, positions) => {
+  const rebuilt = new Array(positions.length);
+  for (let index = 0; index < positions.length; index += 1) {
+    rebuilt[index] = getStoredColumnValue(column, positions[index]);
+  }
+  columnOperationCounters.rebuiltCells += positions.length;
+  return rebuilt;
+};
+var materializeFrameData = (columns, data) => {
+  const materialized = /* @__PURE__ */ new Map();
+  for (const column of columns) {
+    const stored = data.get(column);
+    if (stored === void 0) {
+      throw new JsonFrameValidationError("Stored frame data is missing a declared column.", {
+        path: "$",
+        column
+      });
+    }
+    materialized.set(column, materializeColumn(stored));
+  }
+  return materialized;
+};
+var buildFrameState = (frame, options) => {
+  validateExplicitColumnTypes(frame.columns, options.columnTypes);
+  const schemaTypes = resolveSchemaTypeByColumn(frame);
+  const data = /* @__PURE__ */ new Map();
+  const columnInfo = /* @__PURE__ */ new Map();
+  for (let columnIndex = 0; columnIndex < frame.columns.length; columnIndex += 1) {
+    const column = frame.columns[columnIndex];
+    const values = frame.data.get(column);
+    if (values === void 0) {
+      throw new JsonFrameValidationError("Parsed frame data is missing a declared column.", {
+        orient: frame.orient,
+        column
+      });
+    }
+    const inferred = inferColumnType(values);
+    const resolvedType = schemaTypes.get(column) ?? options.columnTypes?.[column] ?? inferred.type;
+    if (schemaTypes.has(column) === false && options.columnTypes?.[column] !== void 0) {
+      validateColumnValuesForType({
+        column,
+        columnIndex,
+        values,
+        type: resolvedType,
+        orient: frame.orient,
+        index: frame.index
+      });
+    }
+    const info = freezeColumnInfo({ type: resolvedType, nullable: inferred.nullable });
+    columnInfo.set(column, info);
+    data.set(column, packColumn(values, info, options.packThreshold));
+  }
+  return {
+    columns: freezeArray(frame.columns),
+    index: freezeArray(frame.index),
+    indexKind: frame.indexKind,
+    data,
+    columnInfo,
+    ...frame.tableSchema === void 0 ? {} : { tableSchema: frame.tableSchema },
+    ...frame.tableIndexField === void 0 ? {} : { tableIndexField: frame.tableIndexField }
+  };
+};
+var createFrameStateFromRebuiltData = (frame, options) => {
+  const data = /* @__PURE__ */ new Map();
+  const columnInfo = /* @__PURE__ */ new Map();
+  for (const column of frame.columns) {
+    const values = frame.data.get(column);
+    if (values === void 0) {
+      throw new JsonFrameValidationError("Rebuilt frame data is missing a declared column.", {
+        path: "$",
+        column
+      });
+    }
+    const sourceInfo = frame.columnInfo.get(column);
+    if (sourceInfo === void 0) {
+      throw new JsonFrameValidationError("Rebuilt frame metadata is missing a declared column.", {
+        path: "$",
+        column
+      });
+    }
+    const info = freezeColumnInfo({
+      type: sourceInfo.type,
+      nullable: sourceInfo.nullable && hasNullValue(values)
+    });
+    columnInfo.set(column, info);
+    data.set(column, packColumn(values, info, options.packThreshold));
+  }
+  return {
+    columns: freezeArray(frame.columns),
+    index: freezeArray(frame.index),
+    indexKind: frame.indexKind,
+    data,
+    columnInfo,
+    ...frame.tableSchema === void 0 ? {} : { tableSchema: frame.tableSchema },
+    ...frame.tableIndexField === void 0 ? {} : { tableIndexField: frame.tableIndexField }
+  };
+};
+var createFrameState = (frame, options) => buildFrameState(frame, options);
+
+// src/json.ts
+var JSON_FRAME_MAX_DEPTH = 1e3;
+var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var rootPath = (path) => ({ type: "root", path });
+var isPlainObject = (value) => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+var pathToString = (path) => {
+  const segments = [];
+  let current = path;
+  while (current !== void 0 && current.type !== "root") {
+    segments.push(current);
+    current = current.parent;
+  }
+  let formatted = current?.type === "root" ? current.path : "$";
+  for (let index = segments.length - 1; index >= 0; index -= 1) {
+    const segment = segments[index];
+    if (segment.type === "index") {
+      formatted += `[${segment.index}]`;
+    } else if (segment.type === "property") {
+      formatted += IDENTIFIER_PATTERN.test(segment.key) ? `.${segment.key}` : `[${JSON.stringify(segment.key)}]`;
+    }
+  }
+  return formatted;
+};
+var childIndexPath = (parent, index) => ({ parent, type: "index", index });
+var childPropertyPath = (parent, key) => ({ parent, type: "property", key });
+var throwValidation = (message, path, value, orient) => {
+  throw new JsonFrameValidationError(message, {
+    ...orient === void 0 ? {} : { orient },
+    path: pathToString(path),
+    value
+  });
+};
+var cloneScalar = (value, path, orient) => {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throwValidation("Numbers must be finite JSON values.", path, value, orient);
+    }
+    return value;
+  }
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throwValidation("Input must contain only JSON-compatible values.", path, value, orient);
+  }
+  return void 0;
+};
+var createFrame = (source, path, depth, ancestors, orient) => {
+  const scalar = cloneScalar(source, path, orient);
+  if (scalar !== void 0) {
+    return { value: scalar };
+  }
+  if (depth > JSON_FRAME_MAX_DEPTH) {
+    throwValidation(
+      `JSON input exceeds the maximum supported nesting depth of ${JSON_FRAME_MAX_DEPTH}.`,
+      path,
+      source,
+      orient
+    );
+  }
+  if (Array.isArray(source)) {
+    if (ancestors.has(source)) {
+      throwValidation("Input contains a cyclic array.", path, source, orient);
+    }
+    const target2 = [];
+    ancestors.add(source);
+    return { value: target2, frame: { kind: "array", source, target: target2, path, depth, index: 0 } };
+  }
+  if (!isPlainObject(source)) {
+    throwValidation("Input objects must be plain JSON objects or arrays.", path, source, orient);
+  }
+  const objectSource = source;
+  if (ancestors.has(objectSource)) {
+    throwValidation("Input contains a cyclic object.", path, objectSource, orient);
+  }
+  const target = /* @__PURE__ */ Object.create(null);
+  ancestors.add(objectSource);
+  return {
+    value: target,
+    frame: { kind: "object", source: objectSource, target, keys: Object.keys(objectSource), path, depth, index: 0 }
+  };
+};
+var cloneJsonCompatible = (value, orient, path = "$") => {
+  const ancestors = /* @__PURE__ */ new Set();
+  const root = createFrame(value, rootPath(path), 0, ancestors, orient);
+  const stack = root.frame === void 0 ? [] : [root.frame];
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame.kind === "array") {
+      if (frame.index >= frame.source.length) {
+        ancestors.delete(frame.source);
+        stack.pop();
+        continue;
+      }
+      const index = frame.index;
+      frame.index += 1;
+      const childPath2 = childIndexPath(frame.path, index);
+      if (!(index in frame.source)) {
+        throwValidation("Sparse arrays are not valid JSON input.", childPath2, frame.source, orient);
+      }
+      const child2 = createFrame(frame.source[index], childPath2, frame.depth + 1, ancestors, orient);
+      frame.target.push(child2.value);
+      if (child2.frame !== void 0) {
+        stack.push(child2.frame);
+      }
+      continue;
+    }
+    if (frame.index >= frame.keys.length) {
+      ancestors.delete(frame.source);
+      stack.pop();
+      continue;
+    }
+    const key = frame.keys[frame.index];
+    frame.index += 1;
+    const childPath = childPropertyPath(frame.path, key);
+    const child = createFrame(frame.source[key], childPath, frame.depth + 1, ancestors, orient);
+    frame.target[key] = child.value;
+    if (child.frame !== void 0) {
+      stack.push(child.frame);
+    }
+  }
+  return root.value;
+};
+
 // src/export/payload.ts
 var createRecord = () => /* @__PURE__ */ Object.create(null);
-var cloneJsonValue = (value) => {
-  if (Array.isArray(value)) {
-    return value.map((entry) => cloneJsonValue(entry));
-  }
-  if (value !== null && typeof value === "object") {
-    const cloned = createRecord();
-    for (const [key, entryValue] of Object.entries(value)) {
-      cloned[key] = cloneJsonValue(entryValue);
-    }
-    return cloned;
-  }
-  return value;
-};
-var cloneSchemaField = (field, name = field.name) => {
+var appendPath = (path, key) => `${path}[${JSON.stringify(key)}]`;
+var cloneSchemaField = (field, name = field.name, path = "$.schema.fields[]") => {
   const cloned = createRecord();
   for (const [key, value] of Object.entries(field)) {
-    cloned[key] = key === "name" ? name : value === void 0 ? void 0 : cloneJsonValue(value);
+    cloned[key] = key === "name" ? name : value === void 0 ? void 0 : cloneJsonCompatible(value, "table", appendPath(path, key));
   }
   return cloned;
 };
@@ -128,10 +631,12 @@ var cloneSchema = (schema, fields, primaryKey) => {
       if (key === "fields" || key === "primaryKey") {
         continue;
       }
-      cloned[key] = value === void 0 ? void 0 : cloneJsonValue(value);
+      cloned[key] = value === void 0 ? void 0 : cloneJsonCompatible(value, "table", appendPath("$.schema", key));
     }
   }
-  cloned.fields = fields.map((field) => cloneSchemaField(field));
+  cloned.fields = fields.map(
+    (field, index) => cloneSchemaField(field, field.name, `$.schema.fields[${index}]`)
+  );
   if (primaryKey !== void 0) {
     cloned.primaryKey = [...primaryKey];
   }
@@ -145,8 +650,9 @@ var mapColumnTypeToSchemaField = (name, info) => {
       case "float":
         return "number";
       case "string":
-      case "categorical":
         return "string";
+      case "categorical":
+        return "any";
       case "boolean":
         return "boolean";
       case "datetime":
@@ -232,6 +738,22 @@ var resolveIndexFieldName = (state, options) => {
   }
   return indexField;
 };
+var assertUniqueTableIndexLabels = (index, indexField) => {
+  const seen = /* @__PURE__ */ new Map();
+  for (let rowIndex = 0; rowIndex < index.length; rowIndex += 1) {
+    const label = index[rowIndex];
+    if (seen.has(label)) {
+      throw new JsonFrameValidationError("Cannot export duplicate index labels as a table primary key.", {
+        orient: "table",
+        path: `$.data[${rowIndex}][${JSON.stringify(indexField)}]`,
+        row: rowIndex,
+        column: indexField,
+        value: label
+      });
+    }
+    seen.set(label, rowIndex);
+  }
+};
 var resolveIndexKeys = (state, orient) => {
   const seenKeys = /* @__PURE__ */ new Map();
   const keys = [];
@@ -301,19 +823,32 @@ var exportSplit = (state, materialized) => ({
 });
 var exportTable = (state, materialized, columnInfo, options) => {
   const indexField = resolveIndexFieldName(state, options);
+  if (indexField !== void 0) {
+    assertUniqueTableIndexLabels(state.index, indexField);
+  }
   const indexTemplate = getIndexFieldTemplate(state);
   const dataTemplates = getDataFieldTemplates(state);
   const fields = [];
   if (indexField !== void 0) {
     fields.push(
-      indexTemplate === void 0 ? { name: indexField, type: inferIndexFieldType(state.index) } : cloneSchemaField(indexTemplate, indexField)
+      indexTemplate === void 0 ? { name: indexField, type: inferIndexFieldType(state.index) } : cloneSchemaField(indexTemplate, indexField, "$.schema.fields[0]")
     );
   }
   for (let columnIndex = 0; columnIndex < state.columns.length; columnIndex += 1) {
     const column = state.columns[columnIndex];
     const template = dataTemplates[columnIndex];
+    if (template === void 0) {
+      validateColumnValuesForType({
+        column,
+        columnIndex,
+        values: materialized.get(column) ?? [],
+        type: columnInfo.get(column).type,
+        orient: "table",
+        index: state.index
+      });
+    }
     fields.push(
-      template === void 0 ? mapColumnTypeToSchemaField(column, columnInfo.get(column)) : cloneSchemaField(template, column)
+      template === void 0 ? mapColumnTypeToSchemaField(column, columnInfo.get(column)) : cloneSchemaField(template, column, `$.schema.fields[${fields.length}]`)
     );
   }
   const data = [];
@@ -333,185 +868,6 @@ var exportTable = (state, materialized, columnInfo, options) => {
   };
 };
 
-// src/frame/column.ts
-var INT32_MIN = -2147483648;
-var INT32_MAX = 2147483647;
-var freezeArray = (values) => Object.freeze([...values]);
-var freezeColumnInfo = (info) => Object.freeze({ ...info });
-var hasCategoricalMetadata = (field) => field.constraints?.enum !== void 0 || field.ordered === true || field.extDtype === "category";
-var mapTableSchemaFieldType = (field) => {
-  if (hasCategoricalMetadata(field)) {
-    return "categorical";
-  }
-  switch (field.type) {
-    case "boolean":
-      return "boolean";
-    case "integer":
-    case "year":
-      return "integer";
-    case "number":
-      return "float";
-    case "date":
-    case "datetime":
-      return "datetime";
-    case "string":
-      return "string";
-    case "any":
-      return "unknown";
-    default:
-      return "unknown";
-  }
-};
-var inferColumnType = (values) => {
-  let nullable = false;
-  let sawBoolean = false;
-  let sawString = false;
-  let sawInteger = false;
-  let sawFloat = false;
-  let sawStructured = false;
-  for (const value of values) {
-    if (value === null) {
-      nullable = true;
-      continue;
-    }
-    if (typeof value === "boolean") {
-      sawBoolean = true;
-      continue;
-    }
-    if (typeof value === "string") {
-      sawString = true;
-      continue;
-    }
-    if (typeof value === "number") {
-      if (Number.isInteger(value)) {
-        sawInteger = true;
-      } else {
-        sawFloat = true;
-      }
-      continue;
-    }
-    sawStructured = true;
-  }
-  const nonNullKinds = [sawBoolean, sawString, sawInteger || sawFloat, sawStructured].filter(Boolean).length;
-  if (nonNullKinds === 0) {
-    return freezeColumnInfo({ type: "unknown", nullable });
-  }
-  if (sawStructured || nonNullKinds > 1 || sawBoolean && (sawString || sawInteger || sawFloat)) {
-    return freezeColumnInfo({ type: "mixed", nullable });
-  }
-  if (sawString) {
-    return freezeColumnInfo({ type: "string", nullable });
-  }
-  if (sawBoolean) {
-    return freezeColumnInfo({ type: "boolean", nullable });
-  }
-  if (sawFloat) {
-    return freezeColumnInfo({ type: "float", nullable });
-  }
-  return freezeColumnInfo({ type: "integer", nullable });
-};
-var packColumn = (values, info, packThreshold) => {
-  if (packThreshold === 0 || values.length < packThreshold || info.nullable) {
-    return freezeArray(values);
-  }
-  if (info.type === "integer") {
-    const packed = new Int32Array(values.length);
-    for (let index = 0; index < values.length; index += 1) {
-      const value = values[index];
-      if (typeof value !== "number" || !Number.isInteger(value) || value < INT32_MIN || value > INT32_MAX) {
-        return freezeArray(values);
-      }
-      packed[index] = value;
-    }
-    return packed;
-  }
-  if (info.type === "float") {
-    const packed = new Float64Array(values.length);
-    for (let index = 0; index < values.length; index += 1) {
-      const value = values[index];
-      if (typeof value !== "number") {
-        return freezeArray(values);
-      }
-      packed[index] = value;
-    }
-    return packed;
-  }
-  return freezeArray(values);
-};
-var validateExplicitColumnTypes = (columns, columnTypes) => {
-  if (columnTypes === void 0) {
-    return;
-  }
-  const knownColumns = new Set(columns);
-  for (const column of Object.keys(columnTypes)) {
-    if (!knownColumns.has(column)) {
-      throw new JsonFrameOptionError(
-        "`options.columnTypes` keys must match parsed column names.",
-        `columnTypes.${column}`,
-        columnTypes[column]
-      );
-    }
-  }
-};
-var resolveSchemaTypeByColumn = (frame) => {
-  if (frame.tableSchema === void 0) {
-    return /* @__PURE__ */ new Map();
-  }
-  const schemaTypes = /* @__PURE__ */ new Map();
-  for (const field of frame.tableSchema.fields) {
-    if (frame.columns.includes(field.name)) {
-      schemaTypes.set(field.name, mapTableSchemaFieldType(field));
-    }
-  }
-  return schemaTypes;
-};
-var materializeColumn = (column) => Array.isArray(column) ? freezeArray(column) : freezeArray(Array.from(column));
-var materializeFrameData = (columns, data) => {
-  const materialized = /* @__PURE__ */ new Map();
-  for (const column of columns) {
-    const stored = data.get(column);
-    if (stored === void 0) {
-      throw new JsonFrameValidationError("Stored frame data is missing a declared column.", {
-        path: "$",
-        column
-      });
-    }
-    materialized.set(column, materializeColumn(stored));
-  }
-  return materialized;
-};
-var buildFrameState = (frame, options) => {
-  validateExplicitColumnTypes(frame.columns, options.columnTypes);
-  const schemaTypes = resolveSchemaTypeByColumn(frame);
-  const data = /* @__PURE__ */ new Map();
-  const columnInfo = /* @__PURE__ */ new Map();
-  for (const column of frame.columns) {
-    const values = frame.data.get(column);
-    if (values === void 0) {
-      throw new JsonFrameValidationError("Parsed frame data is missing a declared column.", {
-        orient: frame.orient,
-        column
-      });
-    }
-    const inferred = inferColumnType(values);
-    const resolvedType = schemaTypes.get(column) ?? options.columnTypes?.[column] ?? inferred.type;
-    const info = freezeColumnInfo({ type: resolvedType, nullable: inferred.nullable });
-    columnInfo.set(column, info);
-    data.set(column, packColumn(values, info, options.packThreshold));
-  }
-  return {
-    columns: freezeArray(frame.columns),
-    index: freezeArray(frame.index),
-    indexKind: frame.indexKind,
-    data,
-    columnInfo,
-    ...frame.tableSchema === void 0 ? {} : { tableSchema: frame.tableSchema },
-    ...frame.tableIndexField === void 0 ? {} : { tableIndexField: frame.tableIndexField }
-  };
-};
-var createFrameStateFromData = (frame, options) => buildFrameState(frame, options);
-var createFrameState = (frame, options) => buildFrameState(frame, options);
-
 // src/frame/DataFrame.ts
 var hasOwn = Object.prototype.hasOwnProperty;
 var frameStateByInstance = /* @__PURE__ */ new WeakMap();
@@ -531,7 +887,7 @@ var cloneSchema2 = (schema, fields, primaryKey) => {
   }
   return Object.freeze(cloned);
 };
-var _state, _packThreshold, _DataFrame_instances, assertRowPosition_fn, materializedData_fn, createRow_fn, columnTypeOverrides_fn, rebuild_fn, selectSchema_fn, renameSchema_fn, resetIndexSchema_fn;
+var _state, _packThreshold, _DataFrame_instances, assertRowPosition_fn, materializedData_fn, createRow_fn, columnInfoOverrides_fn, rebuild_fn, selectSchema_fn, renameSchema_fn, resetIndexSchema_fn;
 var DataFrame = class {
   constructor(state, packThreshold) {
     __privateAdd(this, _DataFrame_instances);
@@ -593,18 +949,22 @@ var DataFrame = class {
   }
   row(position) {
     __privateMethod(this, _DataFrame_instances, assertRowPosition_fn).call(this, position);
-    return __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this), position);
+    return __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, position);
   }
   rows() {
-    const materialized = __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this);
-    const rows = __privateGet(this, _state).index.map((_, position) => __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, materialized, position));
+    const rows = __privateGet(this, _state).index.map((_, position) => __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, position));
     return freezeArray2(rows);
   }
   filter(predicate) {
-    const materialized = __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this);
+    if (typeof predicate !== "function") {
+      throw new JsonFrameValidationError("`filter` predicate must be a function.", {
+        path: "$.predicate",
+        value: predicate
+      });
+    }
     const keptPositions = [];
     for (let position = 0; position < this.length; position += 1) {
-      if (predicate(__privateMethod(this, _DataFrame_instances, createRow_fn).call(this, materialized, position), __privateGet(this, _state).index[position], position)) {
+      if (predicate(__privateMethod(this, _DataFrame_instances, createRow_fn).call(this, position), __privateGet(this, _state).index[position], position)) {
         keptPositions.push(position);
       }
     }
@@ -621,11 +981,16 @@ var DataFrame = class {
     });
   }
   sort(compare) {
-    const materialized = __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this);
+    if (typeof compare !== "function") {
+      throw new JsonFrameValidationError("`sort` compare must be a function.", {
+        path: "$.compare",
+        value: compare
+      });
+    }
     const ordering = __privateGet(this, _state).index.map((indexLabel, position) => ({
       indexLabel,
       position,
-      row: __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, materialized, position)
+      row: __privateMethod(this, _DataFrame_instances, createRow_fn).call(this, position)
     }));
     ordering.sort((left, right) => {
       const result = compare(left.row, right.row, left.indexLabel, right.indexLabel, left.position, right.position);
@@ -673,7 +1038,26 @@ var DataFrame = class {
     });
   }
   rename(mapping) {
-    const nextColumns = __privateGet(this, _state).columns.map((column) => hasOwn.call(mapping, column) ? mapping[column] : column);
+    if (mapping === null || typeof mapping !== "object" || Array.isArray(mapping)) {
+      throw new JsonFrameValidationError("`rename` mapping must be a non-array object.", {
+        path: "$.mapping",
+        value: mapping
+      });
+    }
+    const nextColumns = __privateGet(this, _state).columns.map((column) => {
+      if (!hasOwn.call(mapping, column)) {
+        return column;
+      }
+      const renamedColumn = mapping[column];
+      if (typeof renamedColumn !== "string") {
+        throw new JsonFrameValidationError("`rename` mapping values must be strings for existing columns.", {
+          path: `$.mapping[${JSON.stringify(column)}]`,
+          column,
+          value: renamedColumn
+        });
+      }
+      return renamedColumn;
+    });
     const seen = /* @__PURE__ */ new Set();
     for (let position = 0; position < nextColumns.length; position += 1) {
       const column = nextColumns[position];
@@ -719,19 +1103,35 @@ assertRowPosition_fn = function(position) {
 materializedData_fn = function() {
   return materializeFrameData(__privateGet(this, _state).columns, __privateGet(this, _state).data);
 };
-createRow_fn = function(materialized, position) {
+createRow_fn = function(position) {
   const row = /* @__PURE__ */ Object.create(null);
   for (const column of __privateGet(this, _state).columns) {
-    row[column] = materialized.get(column)[position];
+    const stored = __privateGet(this, _state).data.get(column);
+    if (stored === void 0) {
+      throw new JsonFrameValidationError("Stored frame data is missing a declared column.", {
+        path: "$",
+        column
+      });
+    }
+    row[column] = getStoredColumnValue(stored, position);
   }
   return Object.freeze(row);
 };
-columnTypeOverrides_fn = function(columns, sourceColumns) {
-  return Object.freeze(
-    Object.fromEntries(
-      columns.map((column, position) => [column, __privateGet(this, _state).columnInfo.get(sourceColumns[position]).type])
-    )
-  );
+columnInfoOverrides_fn = function(columns, sourceColumns) {
+  const columnInfo = /* @__PURE__ */ new Map();
+  for (let position = 0; position < columns.length; position += 1) {
+    const column = columns[position];
+    const sourceColumn = sourceColumns[position];
+    const sourceInfo = __privateGet(this, _state).columnInfo.get(sourceColumn);
+    if (sourceInfo === void 0) {
+      throw new JsonFrameValidationError("Stored frame metadata is missing a declared column.", {
+        path: "$",
+        column: sourceColumn
+      });
+    }
+    columnInfo.set(column, sourceInfo);
+  }
+  return columnInfo;
 };
 rebuild_fn = function({
   columns,
@@ -741,31 +1141,31 @@ rebuild_fn = function({
   indexKind,
   schema
 }) {
-  const materialized = __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this);
   const nextData = /* @__PURE__ */ new Map();
+  const nextColumnInfo = __privateMethod(this, _DataFrame_instances, columnInfoOverrides_fn).call(this, columns, sourceColumns);
   for (let columnIndex = 0; columnIndex < columns.length; columnIndex += 1) {
     const column = columns[columnIndex];
-    const sourceColumn = materialized.get(sourceColumns[columnIndex]);
-    if (sourceColumn === void 0) {
+    const sourceStoredColumn = __privateGet(this, _state).data.get(sourceColumns[columnIndex]);
+    if (sourceStoredColumn === void 0) {
       throw new JsonFrameValidationError("Stored frame data is missing a declared column.", {
         path: "$",
         column
       });
     }
-    nextData.set(column, freezeArray2(positions.map((position) => sourceColumn[position])));
+    nextData.set(column, rebuildStoredColumn(sourceStoredColumn, positions));
   }
-  const state = createFrameStateFromData(
+  const state = createFrameStateFromRebuiltData(
     {
       columns,
       index,
       indexKind,
       data: nextData,
+      columnInfo: nextColumnInfo,
       ...schema.tableSchema === void 0 ? {} : { tableSchema: schema.tableSchema },
       ...schema.tableIndexField === void 0 ? {} : { tableIndexField: schema.tableIndexField }
     },
     {
-      packThreshold: __privateGet(this, _packThreshold),
-      columnTypes: __privateMethod(this, _DataFrame_instances, columnTypeOverrides_fn).call(this, columns, sourceColumns)
+      packThreshold: __privateGet(this, _packThreshold)
     }
   );
   return createDataFrame(state, __privateGet(this, _packThreshold));
@@ -933,11 +1333,11 @@ var normalizeFromOrientOptions = (options) => {
 
 // src/parse/parse.ts
 var hasOwn2 = Object.prototype.hasOwnProperty;
-var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var IDENTIFIER_PATTERN2 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 var freezeArray3 = (values) => Object.freeze([...values]);
-var appendPropertyPath = (path, key) => IDENTIFIER_PATTERN.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+var appendPropertyPath = (path, key) => IDENTIFIER_PATTERN2.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
 var appendIndexPath = (path, index) => `${path}[${index}]`;
-var isPlainObject = (value) => {
+var isPlainObject2 = (value) => {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return false;
   }
@@ -957,6 +1357,18 @@ var assertSupportedIndexLabel = (value, orient, path) => {
     value
   });
 };
+var assertUniqueTablePrimaryKeyLabel = (seen, label, row, column, path) => {
+  if (seen.has(label)) {
+    throw new JsonFrameValidationError("Table primary-key values must be unique.", {
+      orient: "table",
+      path,
+      row,
+      column,
+      value: label
+    });
+  }
+  seen.set(label, row);
+};
 var assertUniqueStringColumns = (values, orient, path) => {
   const columns = [];
   const seen = /* @__PURE__ */ new Set();
@@ -1014,52 +1426,6 @@ var finalizeFrame = ({
     ...tableIndexField === void 0 ? {} : { tableIndexField }
   };
 };
-var validateJsonCompatible = (value, path = "$", stack = /* @__PURE__ */ new Set()) => {
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return value;
-  }
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) {
-      throw new JsonFrameValidationError("Numbers must be finite JSON values.", { path, value });
-    }
-    return value;
-  }
-  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
-    throw new JsonFrameValidationError("Input must contain only JSON-compatible values.", { path, value });
-  }
-  if (Array.isArray(value)) {
-    if (stack.has(value)) {
-      throw new JsonFrameValidationError("Input contains a cyclic array.", { path, value });
-    }
-    stack.add(value);
-    const normalized2 = [];
-    for (let index = 0; index < value.length; index += 1) {
-      if (!(index in value)) {
-        stack.delete(value);
-        throw new JsonFrameValidationError("Sparse arrays are not valid JSON input.", {
-          path: appendIndexPath(path, index),
-          value
-        });
-      }
-      normalized2.push(validateJsonCompatible(value[index], appendIndexPath(path, index), stack));
-    }
-    stack.delete(value);
-    return normalized2;
-  }
-  if (!isPlainObject(value)) {
-    throw new JsonFrameValidationError("Input objects must be plain JSON objects or arrays.", { path, value });
-  }
-  if (stack.has(value)) {
-    throw new JsonFrameValidationError("Input contains a cyclic object.", { path, value });
-  }
-  stack.add(value);
-  const normalized = /* @__PURE__ */ Object.create(null);
-  for (const [key, entryValue] of Object.entries(value)) {
-    normalized[key] = validateJsonCompatible(entryValue, appendPropertyPath(path, key), stack);
-  }
-  stack.delete(value);
-  return normalized;
-};
 var detectOrient = (value) => {
   if (Array.isArray(value)) {
     if (value.length === 0) {
@@ -1071,7 +1437,7 @@ var detectOrient = (value) => {
     if (value.every((entry) => Array.isArray(entry))) {
       return "values";
     }
-    if (value.every((entry) => isPlainObject(entry))) {
+    if (value.every((entry) => isPlainObject2(entry))) {
       return "records";
     }
     throw new JsonFrameValidationError("Auto detection requires a non-empty array of row objects or row arrays.", {
@@ -1079,20 +1445,20 @@ var detectOrient = (value) => {
       value
     });
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("Auto detection requires a JSON array or object payload.", {
       path: "$",
       value
     });
   }
-  if (isPlainObject(value.schema) && Array.isArray(value.data)) {
+  if (isPlainObject2(value.schema) && Array.isArray(value.data)) {
     return "table";
   }
   if (Array.isArray(value.columns) && Array.isArray(value.data) && (value.index === void 0 || Array.isArray(value.index))) {
     return "split";
   }
   const keys = Object.keys(value);
-  if (keys.length === 0 || keys.every((key) => isPlainObject(value[key]))) {
+  if (keys.length === 0 || keys.every((key) => isPlainObject2(value[key]))) {
     throw new AmbiguousOrientError("Auto detection cannot distinguish between index and columns payloads.", [
       "index",
       "columns"
@@ -1114,7 +1480,7 @@ var parseRecords = (value, orient) => {
   for (let rowIndex = 0; rowIndex < value.length; rowIndex += 1) {
     const row = value[rowIndex];
     const rowPath = appendIndexPath("$", rowIndex);
-    if (!isPlainObject(row)) {
+    if (!isPlainObject2(row)) {
       throw new JsonFrameValidationError("`records` rows must be JSON objects.", {
         orient,
         path: rowPath,
@@ -1143,7 +1509,7 @@ var parseRecords = (value, orient) => {
   });
 };
 var parseIndex = (value, orient) => {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("`index` payloads must be objects keyed by index label.", {
       orient,
       path: "$",
@@ -1158,7 +1524,7 @@ var parseIndex = (value, orient) => {
     const indexLabel = index[rowIndex];
     const row = value[indexLabel];
     const rowPath = appendPropertyPath("$", indexLabel);
-    if (!isPlainObject(row)) {
+    if (!isPlainObject2(row)) {
       throw new JsonFrameValidationError("`index` payload rows must be JSON objects.", {
         orient,
         path: rowPath,
@@ -1186,7 +1552,7 @@ var parseIndex = (value, orient) => {
   });
 };
 var parseColumns = (value, orient) => {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("`columns` payloads must be objects keyed by column label.", {
       orient,
       path: "$",
@@ -1208,7 +1574,7 @@ var parseColumns = (value, orient) => {
   for (const column of columns) {
     const columnValue = value[column];
     const columnPath = appendPropertyPath("$", column);
-    if (!isPlainObject(columnValue)) {
+    if (!isPlainObject2(columnValue)) {
       throw new JsonFrameValidationError("`columns` payload values must be objects keyed by index label.", {
         orient,
         path: columnPath,
@@ -1287,7 +1653,7 @@ var parseValues = (value, options, orient) => {
   });
 };
 var parseSplit = (value, orient) => {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("`split` payloads must be objects.", { orient, path: "$", value });
   }
   if (!Array.isArray(value.columns)) {
@@ -1362,7 +1728,7 @@ var parseSplit = (value, orient) => {
   });
 };
 var cloneConstraints = (value, orient, path) => {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("Table Schema field constraints must be an object when present.", {
       orient,
       path,
@@ -1404,7 +1770,7 @@ var cloneConstraints = (value, orient, path) => {
 var cloneTableField = (value, index) => {
   const orient = "table";
   const path = appendIndexPath("$.schema.fields", index);
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("Table Schema fields must be objects.", {
       orient,
       path,
@@ -1451,7 +1817,7 @@ var cloneTableField = (value, index) => {
 };
 var cloneTableSchema = (value) => {
   const orient = "table";
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("`table.schema` must be an object.", {
       orient,
       path: "$.schema",
@@ -1527,7 +1893,7 @@ var cloneTableSchema = (value) => {
   return Object.freeze(cloned);
 };
 var parseTable = (value, orient) => {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     throw new JsonFrameValidationError("`table` payloads must be objects.", { orient, path: "$", value });
   }
   const schema = cloneTableSchema(value.schema);
@@ -1552,10 +1918,11 @@ var parseTable = (value, orient) => {
   const fieldNames = new Set(schema.fields.map((field) => field.name));
   const index = [];
   const indexKind = primaryKey === void 0 ? "synthetic" : "source";
+  const seenPrimaryKeyLabels = /* @__PURE__ */ new Map();
   for (let rowIndex = 0; rowIndex < value.data.length; rowIndex += 1) {
     const row = value.data[rowIndex];
     const rowPath = appendIndexPath("$.data", rowIndex);
-    if (!isPlainObject(row)) {
+    if (!isPlainObject2(row)) {
       throw new JsonFrameValidationError("`table.data` rows must be objects.", {
         orient,
         path: rowPath,
@@ -1585,9 +1952,10 @@ var parseTable = (value, orient) => {
         value: row
       });
     } else {
-      index.push(
-        assertSupportedIndexLabel(row[primaryKey], orient, appendPropertyPath(rowPath, primaryKey))
-      );
+      const primaryKeyPath = appendPropertyPath(rowPath, primaryKey);
+      const indexLabel = assertSupportedIndexLabel(row[primaryKey], orient, primaryKeyPath);
+      assertUniqueTablePrimaryKeyLabel(seenPrimaryKeyLabels, indexLabel, rowIndex, primaryKey, primaryKeyPath);
+      index.push(indexLabel);
     }
     for (const column of columns) {
       data.get(column).push(hasOwn2.call(row, column) ? row[column] : null);
@@ -1617,7 +1985,7 @@ var parseInput = (input, options) => {
       throw error;
     }
   })();
-  const jsonValue = validateJsonCompatible(parsedValue);
+  const jsonValue = cloneJsonCompatible(parsedValue);
   const orient = options.orient === "auto" ? detectOrient(jsonValue) : options.orient;
   switch (orient) {
     case "records":
@@ -1649,6 +2017,7 @@ function fromOrient(input, options) {
 0 && (module.exports = {
   AmbiguousOrientError,
   ExportKeyCollisionError,
+  JSON_FRAME_MAX_DEPTH,
   JsonFrameError,
   JsonFrameOptionError,
   JsonFrameParseError,