@web-ts-toolkit/json-frame 0.43.0 → 0.48.0

package/index.mjs

@@ -8,7 +8,8 @@ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // src/errors.ts
-var DIAGNOSTIC_KEY_LIMIT = 5;
+var JSON_FRAME_DIAGNOSTIC_KEY_LIMIT = 5;
+var JSON_FRAME_DIAGNOSTIC_KEY_TEXT_BUDGET = 200;
 var freezeCopy = (values) => Object.freeze([...values]);
 var summarizeDiagnosticValue = (value) => {
   if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
@@ -19,11 +20,27 @@ var summarizeDiagnosticValue = (value) => {
   }
   if (typeof value === "object") {
     const keys = Object.keys(value);
+    const head = keys.slice(0, JSON_FRAME_DIAGNOSTIC_KEY_LIMIT);
+    const preview = [];
+    let remaining = JSON_FRAME_DIAGNOSTIC_KEY_TEXT_BUDGET;
+    let textTruncated = false;
+    for (const key of head) {
+      if (key.length <= remaining) {
+        preview.push(key);
+        remaining -= key.length;
+      } else {
+        if (remaining > 0) {
+          preview.push(key.slice(0, remaining));
+        }
+        textTruncated = true;
+        break;
+      }
+    }
     return Object.freeze({
       kind: "object",
       keyCount: keys.length,
-      keys: freezeCopy(keys.slice(0, DIAGNOSTIC_KEY_LIMIT)),
-      truncated: keys.length > DIAGNOSTIC_KEY_LIMIT
+      keys: freezeCopy(preview),
+      truncated: keys.length > JSON_FRAME_DIAGNOSTIC_KEY_LIMIT || textTruncated
     });
   }
   if (typeof value === "undefined") {
@@ -106,6 +123,7 @@ 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 DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 var columnOperationCounters = {
   materializeColumnCalls: 0,
   materializedCells: 0,
@@ -199,8 +217,9 @@ var isPandasNaiveIsoDatetime = (value) => {
   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;
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = month === 2 && leapYear ? 29 : DAYS_IN_MONTH[month - 1];
+  return day >= 1 && day <= daysInMonth;
 };
 var isScalarCategory = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 var isJsonContainer = (value) => {
@@ -279,6 +298,28 @@ var validateColumnValuesForType = ({
     });
   }
 };
+var validateStoredColumnValuesForType = ({
+  column,
+  columnIndex,
+  stored,
+  type,
+  orient,
+  index
+}) => {
+  for (let rowIndex = 0; rowIndex < stored.length; rowIndex += 1) {
+    const value = stored[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);
@@ -290,6 +331,9 @@ var packColumn = (values, info, packThreshold) => {
       if (typeof value !== "number" || !Number.isInteger(value) || value < INT32_MIN || value > INT32_MAX) {
         return freezeArray(values);
       }
+      if (Object.is(value, -0)) {
+        return freezeArray(values);
+      }
       packed[index] = value;
     }
     return packed;
@@ -336,18 +380,14 @@ var resolveSchemaTypeByColumn = (frame) => {
     return /* @__PURE__ */ new Map();
   }
   const schemaTypes = /* @__PURE__ */ new Map();
+  const columnNames = new Set(frame.columns);
   for (const field of frame.tableSchema.fields) {
-    if (frame.columns.includes(field.name)) {
+    if (columnNames.has(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];
@@ -360,20 +400,6 @@ var rebuildStoredColumn = (column, positions) => {
   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);
@@ -389,8 +415,9 @@ var buildFrameState = (frame, options) => {
       });
     }
     const inferred = inferColumnType(values);
-    const resolvedType = schemaTypes.get(column) ?? options.columnTypes?.[column] ?? inferred.type;
-    if (schemaTypes.has(column) === false && options.columnTypes?.[column] !== void 0) {
+    const explicitType = options.columnTypes !== void 0 && Object.prototype.hasOwnProperty.call(options.columnTypes, column) ? options.columnTypes[column] : void 0;
+    const resolvedType = schemaTypes.get(column) ?? explicitType ?? inferred.type;
+    if (schemaTypes.has(column) === false && explicitType !== void 0) {
       validateColumnValuesForType({
         column,
         columnIndex,
@@ -489,6 +516,16 @@ var throwValidation = (message, path, value, orient) => {
     value
   });
 };
+var createNodeBudget = (maxNodes, orient) => {
+  let remaining = maxNodes;
+  return (value, path) => {
+    if (remaining === void 0) return;
+    if (remaining === 0) {
+      throwValidation(`JSON traversal exceeds maxNodes budget of ${maxNodes}.`, path, value, orient);
+    }
+    remaining -= 1;
+  };
+};
 var cloneScalar = (value, path, orient) => {
   if (value === null || typeof value === "string" || typeof value === "boolean") {
     return value;
@@ -504,7 +541,8 @@ var cloneScalar = (value, path, orient) => {
   }
   return void 0;
 };
-var createFrame = (source, path, depth, ancestors, orient) => {
+var createFrame = (source, path, depth, ancestors, orient, charge) => {
+  charge(source, path);
   const scalar = cloneScalar(source, path, orient);
   if (scalar !== void 0) {
     return { value: scalar };
@@ -539,9 +577,80 @@ var createFrame = (source, path, depth, ancestors, orient) => {
     frame: { kind: "object", source: objectSource, target, keys: Object.keys(objectSource), path, depth, index: 0 }
   };
 };
-var cloneJsonCompatible = (value, orient, path = "$") => {
+var createValidateFrame = (source, path, depth, ancestors, orient, charge) => {
+  charge(source, path);
+  const scalar = cloneScalar(source, path, orient);
+  if (scalar !== void 0) {
+    return void 0;
+  }
+  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);
+    }
+    ancestors.add(source);
+    return { kind: "array", source, 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);
+  }
+  ancestors.add(objectSource);
+  return { kind: "object", source: objectSource, keys: Object.keys(objectSource), path, depth, index: 0 };
+};
+var assertJsonCompatible = (value, orient, path = "$", maxNodes) => {
   const ancestors = /* @__PURE__ */ new Set();
-  const root = createFrame(value, rootPath(path), 0, ancestors, orient);
+  const charge = createNodeBudget(maxNodes, orient);
+  const root = createValidateFrame(value, rootPath(path), 0, ancestors, orient, charge);
+  const stack = root === void 0 ? [] : [root];
+  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 = createValidateFrame(frame.source[index], childPath2, frame.depth + 1, ancestors, orient, charge);
+      if (child2 !== void 0) {
+        stack.push(child2);
+      }
+      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 = createValidateFrame(frame.source[key], childPath, frame.depth + 1, ancestors, orient, charge);
+    if (child !== void 0) {
+      stack.push(child);
+    }
+  }
+};
+var cloneJsonCompatible = (value, orient, path = "$", maxNodes) => {
+  const ancestors = /* @__PURE__ */ new Set();
+  const charge = createNodeBudget(maxNodes, orient);
+  const root = createFrame(value, rootPath(path), 0, ancestors, orient, charge);
   const stack = root.frame === void 0 ? [] : [root.frame];
   while (stack.length > 0) {
     const frame = stack[stack.length - 1];
@@ -557,7 +666,7 @@ var cloneJsonCompatible = (value, orient, path = "$") => {
       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);
+      const child2 = createFrame(frame.source[index], childPath2, frame.depth + 1, ancestors, orient, charge);
       frame.target.push(child2.value);
       if (child2.frame !== void 0) {
         stack.push(child2.frame);
@@ -572,7 +681,7 @@ var cloneJsonCompatible = (value, orient, path = "$") => {
     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);
+    const child = createFrame(frame.source[key], childPath, frame.depth + 1, ancestors, orient, charge);
     frame.target[key] = child.value;
     if (child.frame !== void 0) {
       stack.push(child.frame);
@@ -581,6 +690,142 @@ var cloneJsonCompatible = (value, orient, path = "$") => {
   return root.value;
 };
 
+// src/options.ts
+var RESOLVED_ORIENTS = [
+  "records",
+  "index",
+  "columns",
+  "values",
+  "split",
+  "table"
+];
+var ORIENTS = ["auto", ...RESOLVED_ORIENTS];
+var COLUMN_TYPES = [
+  "integer",
+  "float",
+  "string",
+  "boolean",
+  "datetime",
+  "categorical",
+  "mixed",
+  "unknown"
+];
+var DEFAULT_PACK_THRESHOLD = 256;
+var validateMaxNodes = (maxNodes) => {
+  if (maxNodes === void 0) return void 0;
+  if (typeof maxNodes !== "number" || !Number.isSafeInteger(maxNodes) || maxNodes <= 0) {
+    throw new JsonFrameOptionError("`options.maxNodes` must be a positive safe integer.", "maxNodes", maxNodes);
+  }
+  return maxNodes;
+};
+var normalizeToTableOptions = (options, method = "toTable") => {
+  if (options === void 0) return {};
+  if (Array.isArray(options) || typeof options !== "object" || options === null) {
+    throw new JsonFrameOptionError(`\`${method}\` options must be an object when provided.`, "options", options);
+  }
+  const indexField = options.indexField;
+  if (indexField !== void 0 && typeof indexField !== "string") {
+    throw new JsonFrameOptionError(
+      `\`${method}\` options.indexField must be a string when provided.`,
+      "indexField",
+      indexField
+    );
+  }
+  return indexField === void 0 ? {} : { indexField };
+};
+var normalizeToJSONStringOptions = (options) => {
+  const tableOptions = normalizeToTableOptions(options, "toJSONString");
+  const maxNodes = validateMaxNodes(options?.maxNodes);
+  return { ...tableOptions, ...maxNodes === void 0 ? {} : { maxNodes } };
+};
+var isOrient = (value) => typeof value === "string" && ORIENTS.includes(value);
+var isColumnType = (value) => typeof value === "string" && COLUMN_TYPES.includes(value);
+var normalizeFromOrientOptions = (options) => {
+  if (options == null) {
+    return {
+      orient: "auto",
+      packThreshold: DEFAULT_PACK_THRESHOLD
+    };
+  }
+  if (Array.isArray(options) || typeof options !== "object") {
+    throw new JsonFrameOptionError("`fromOrient` options must be an object when provided.", "options", options);
+  }
+  const orient = options.orient ?? "auto";
+  if (!isOrient(orient)) {
+    throw new JsonFrameOptionError(
+      "`options.orient` must be one of auto, records, index, columns, values, split, or table.",
+      "orient",
+      orient
+    );
+  }
+  const maxNodes = validateMaxNodes(options.maxNodes);
+  const packThreshold = options.packThreshold ?? DEFAULT_PACK_THRESHOLD;
+  if (!Number.isFinite(packThreshold) || !Number.isInteger(packThreshold) || packThreshold < 0) {
+    throw new JsonFrameOptionError(
+      "`options.packThreshold` must be a finite non-negative integer.",
+      "packThreshold",
+      packThreshold
+    );
+  }
+  let columns;
+  if (options.columns !== void 0) {
+    if (!Array.isArray(options.columns)) {
+      throw new JsonFrameOptionError("`options.columns` must be an array of strings.", "columns", options.columns);
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const validated = [];
+    const source = options.columns;
+    for (let position = 0; position < source.length; position += 1) {
+      if (!Object.prototype.hasOwnProperty.call(source, position)) {
+        throw new JsonFrameOptionError(
+          "`options.columns` must not contain holes; every position must be a string label.",
+          "columns",
+          source
+        );
+      }
+      const column = source[position];
+      if (typeof column !== "string") {
+        throw new JsonFrameOptionError("`options.columns` must contain only strings.", "columns", column);
+      }
+      if (seen.has(column)) {
+        throw new JsonFrameOptionError("`options.columns` must not contain duplicates.", "columns", column);
+      }
+      seen.add(column);
+      validated.push(column);
+    }
+    columns = validated;
+  }
+  let columnTypes;
+  if (options.columnTypes !== void 0) {
+    if (Array.isArray(options.columnTypes) || typeof options.columnTypes !== "object" || options.columnTypes === null) {
+      throw new JsonFrameOptionError(
+        "`options.columnTypes` must be an object keyed by column name.",
+        "columnTypes",
+        options.columnTypes
+      );
+    }
+    const normalized = /* @__PURE__ */ Object.create(null);
+    for (const [column, type] of Object.entries(options.columnTypes)) {
+      if (!isColumnType(type)) {
+        throw new JsonFrameOptionError(
+          "`options.columnTypes` values must be valid JSON Frame logical column types.",
+          `columnTypes.${column}`,
+          type
+        );
+      }
+      normalized[column] = type;
+    }
+    columnTypes = Object.freeze(normalized);
+  }
+  return {
+    orient,
+    packThreshold,
+    ...maxNodes === void 0 ? {} : { maxNodes },
+    ...columns === void 0 ? {} : { columns: Object.freeze([...columns]) },
+    ...columnTypes === void 0 ? {} : { columnTypes }
+  };
+};
+
 // src/export/payload.ts
 var createRecord = () => /* @__PURE__ */ Object.create(null);
 var appendPath = (path, key) => `${path}[${JSON.stringify(key)}]`;
@@ -672,30 +917,46 @@ var getIndexFieldTemplate = (state) => {
   if (state.tableSchema === void 0 || state.tableIndexField === void 0) {
     return void 0;
   }
-  return state.tableSchema.fields.find((field) => field.name === state.tableIndexField);
+  const fields = state.tableSchema.fields;
+  if (new Set(fields.map((field) => field.name)).size === fields.length) {
+    return fields.find((field) => field.name === state.tableIndexField);
+  }
+  if (fields.length === state.columns.length + 1 && fields[0].name === state.tableIndexField) {
+    return fields[0];
+  }
+  return fields.find((field) => field.name === state.tableIndexField);
 };
 var getDataFieldTemplates = (state) => {
   if (state.tableSchema === void 0) {
     return [];
   }
-  const fieldsByName = new Map(state.tableSchema.fields.map((field) => [field.name, field]));
-  return state.columns.map((column) => fieldsByName.get(column)).filter((field) => field !== void 0);
-};
-var resolveIndexFieldName = (state, options) => {
-  if (options !== void 0 && (Array.isArray(options) || typeof options !== "object" || options === null)) {
-    throw new JsonFrameOptionError("`toTable` options must be an object when provided.", "options", options);
+  const fields = state.tableSchema.fields;
+  if (new Set(fields.map((field) => field.name)).size === fields.length) {
+    const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+    return state.columns.map((column) => fieldsByName.get(column)).filter((field) => field !== void 0);
   }
-  if (options?.indexField !== void 0 && typeof options.indexField !== "string") {
-    throw new JsonFrameOptionError(
-      "`toTable` options.indexField must be a string when provided.",
-      "indexField",
-      options.indexField
-    );
+  let dataSlice;
+  if (state.tableIndexField !== void 0 && fields.length === state.columns.length + 1 && fields[0].name === state.tableIndexField) {
+    dataSlice = fields.slice(1);
+  } else if (state.tableIndexField !== void 0) {
+    const indexPosition = fields.findIndex((field) => field.name === state.tableIndexField);
+    dataSlice = indexPosition === -1 ? fields : [...fields.slice(0, indexPosition), ...fields.slice(indexPosition + 1)];
+  } else {
+    dataSlice = fields;
   }
+  const dataByName = new Map(dataSlice.map((field) => [field.name, field]));
+  const ordered = state.columns.map((column) => dataByName.get(column)).filter((field) => field !== void 0);
+  if (ordered.length === state.columns.length) {
+    return ordered;
+  }
+  return dataSlice.length === state.columns.length ? [...dataSlice] : ordered;
+};
+var resolveIndexFieldName = (state, options) => {
+  const normalized = normalizeToTableOptions(options);
   if (state.indexKind === "synthetic") {
     return void 0;
   }
-  const indexField = options?.indexField ?? state.tableIndexField ?? "index";
+  const indexField = normalized.indexField ?? state.tableIndexField ?? "index";
   if (state.columns.includes(indexField)) {
     throw new JsonFrameValidationError("Table export index field name must not collide with a data column.", {
       path: "$.schema.fields",
@@ -740,55 +1001,73 @@ var resolveIndexKeys = (state, orient) => {
   }
   return keys;
 };
-var exportRecords = (state, materialized) => {
+var getStoredColumn = (state, column) => {
+  const stored = state.data.get(column);
+  if (stored === void 0) {
+    throw new JsonFrameValidationError("Stored frame data is missing a declared column.", {
+      path: "$",
+      column
+    });
+  }
+  return stored;
+};
+var resolveStoredColumns = (state) => state.columns.map((column) => getStoredColumn(state, column));
+var exportRecords = (state) => {
+  const storedColumns = resolveStoredColumns(state);
   const rows = [];
   for (let rowIndex = 0; rowIndex < state.index.length; rowIndex += 1) {
     const row = createRecord();
-    for (const column of state.columns) {
-      row[column] = materialized.get(column)[rowIndex];
+    for (let columnIndex = 0; columnIndex < state.columns.length; columnIndex += 1) {
+      row[state.columns[columnIndex]] = getStoredColumnValue(storedColumns[columnIndex], rowIndex);
     }
     rows.push(row);
   }
   return rows;
 };
-var exportIndex = (state, materialized) => {
+var exportIndex = (state) => {
   const keys = resolveIndexKeys(state, "index");
+  const storedColumns = resolveStoredColumns(state);
   const rows = createRecord();
   for (let rowIndex = 0; rowIndex < state.index.length; rowIndex += 1) {
     const row = createRecord();
-    for (const column of state.columns) {
-      row[column] = materialized.get(column)[rowIndex];
+    for (let columnIndex = 0; columnIndex < state.columns.length; columnIndex += 1) {
+      row[state.columns[columnIndex]] = getStoredColumnValue(storedColumns[columnIndex], rowIndex);
     }
     rows[keys[rowIndex]] = row;
   }
   return rows;
 };
-var exportColumns = (state, materialized) => {
+var exportColumns = (state) => {
   const keys = resolveIndexKeys(state, "columns");
   const columns = createRecord();
   for (const column of state.columns) {
+    const stored = getStoredColumn(state, column);
     const values = createRecord();
-    const entries = materialized.get(column);
     for (let rowIndex = 0; rowIndex < state.index.length; rowIndex += 1) {
-      values[keys[rowIndex]] = entries[rowIndex];
+      values[keys[rowIndex]] = getStoredColumnValue(stored, rowIndex);
     }
     columns[column] = values;
   }
   return columns;
 };
-var exportValues = (state, materialized) => {
+var exportValues = (state) => {
+  const storedColumns = resolveStoredColumns(state);
   const rows = [];
   for (let rowIndex = 0; rowIndex < state.index.length; rowIndex += 1) {
-    rows.push(state.columns.map((column) => materialized.get(column)[rowIndex]));
+    const row = new Array(storedColumns.length);
+    for (let columnIndex = 0; columnIndex < storedColumns.length; columnIndex += 1) {
+      row[columnIndex] = getStoredColumnValue(storedColumns[columnIndex], rowIndex);
+    }
+    rows.push(row);
   }
   return rows;
 };
-var exportSplit = (state, materialized) => ({
+var exportSplit = (state) => ({
   columns: [...state.columns],
   index: [...state.index],
-  data: exportValues(state, materialized)
+  data: exportValues(state)
 });
-var exportTable = (state, materialized, columnInfo, options) => {
+var exportTable = (state, columnInfo, options) => {
   const indexField = resolveIndexFieldName(state, options);
   if (indexField !== void 0) {
     assertUniqueTableIndexLabels(state.index, indexField);
@@ -801,14 +1080,15 @@ var exportTable = (state, materialized, columnInfo, options) => {
       indexTemplate === void 0 ? { name: indexField, type: inferIndexFieldType(state.index) } : cloneSchemaField(indexTemplate, indexField, "$.schema.fields[0]")
     );
   }
+  const storedColumns = resolveStoredColumns(state);
   for (let columnIndex = 0; columnIndex < state.columns.length; columnIndex += 1) {
     const column = state.columns[columnIndex];
     const template = dataTemplates[columnIndex];
     if (template === void 0) {
-      validateColumnValuesForType({
+      validateStoredColumnValuesForType({
         column,
         columnIndex,
-        values: materialized.get(column) ?? [],
+        stored: storedColumns[columnIndex],
         type: columnInfo.get(column).type,
         orient: "table",
         index: state.index
@@ -824,8 +1104,8 @@ var exportTable = (state, materialized, columnInfo, options) => {
     if (indexField !== void 0) {
       row[indexField] = state.index[rowIndex];
     }
-    for (const column of state.columns) {
-      row[column] = materialized.get(column)[rowIndex];
+    for (let columnIndex = 0; columnIndex < state.columns.length; columnIndex += 1) {
+      row[state.columns[columnIndex]] = getStoredColumnValue(storedColumns[columnIndex], rowIndex);
     }
     data.push(row);
   }
@@ -854,7 +1134,57 @@ var cloneSchema2 = (schema, fields, primaryKey) => {
   }
   return Object.freeze(cloned);
 };
-var _state, _packThreshold, _DataFrame_instances, assertRowPosition_fn, materializedData_fn, createRow_fn, columnInfoOverrides_fn, rebuild_fn, selectSchema_fn, renameSchema_fn, resetIndexSchema_fn;
+var partitionSchemaFields = (state) => {
+  const empty = {
+    indexTemplate: void 0,
+    dataByColumn: /* @__PURE__ */ new Map(),
+    dataInColumnOrder: []
+  };
+  if (state.tableSchema === void 0) {
+    return empty;
+  }
+  const fields = state.tableSchema.fields;
+  if (state.tableIndexField === void 0) {
+    const byName = new Map(fields.map((field) => [field.name, field]));
+    const ordered2 = state.columns.map((column) => byName.get(column)).filter((field) => field !== void 0);
+    return {
+      indexTemplate: void 0,
+      dataByColumn: new Map(ordered2.map((field, index) => [state.columns[index], field])),
+      dataInColumnOrder: ordered2
+    };
+  }
+  const names = fields.map((field) => field.name);
+  const unique = new Set(names).size === names.length;
+  if (unique) {
+    const byName = new Map(fields.map((field) => [field.name, field]));
+    const indexTemplate2 = byName.get(state.tableIndexField);
+    const ordered2 = state.columns.map((column) => byName.get(column)).filter((field) => field !== void 0);
+    return {
+      indexTemplate: indexTemplate2,
+      dataByColumn: new Map(ordered2.map((field, index) => [state.columns[index], field])),
+      dataInColumnOrder: ordered2
+    };
+  }
+  let indexTemplate;
+  let dataSlice;
+  if (fields.length === state.columns.length + 1 && fields[0].name === state.tableIndexField) {
+    indexTemplate = fields[0];
+    dataSlice = fields.slice(1);
+  } else {
+    const indexPosition = fields.findIndex((field) => field.name === state.tableIndexField);
+    indexTemplate = indexPosition === -1 ? void 0 : fields[indexPosition];
+    dataSlice = indexPosition === -1 ? fields : [...fields.slice(0, indexPosition), ...fields.slice(indexPosition + 1)];
+  }
+  const dataByName = new Map(dataSlice.map((field) => [field.name, field]));
+  const ordered = state.columns.map((column) => dataByName.get(column)).filter((field) => field !== void 0);
+  const dataInColumnOrder = ordered.length === state.columns.length ? ordered : dataSlice.length === state.columns.length ? [...dataSlice] : ordered;
+  return {
+    indexTemplate,
+    dataByColumn: new Map(dataInColumnOrder.map((field, index) => [state.columns[index], field])),
+    dataInColumnOrder
+  };
+};
+var _state, _packThreshold, _DataFrame_instances, assertRowPosition_fn, createRow_fn, columnInfoOverrides_fn, rebuild_fn, selectSchema_fn, renameSchema_fn, resetIndexSchema_fn;
 var DataFrame = class {
   constructor(state, packThreshold) {
     __privateAdd(this, _DataFrame_instances);
@@ -877,42 +1207,82 @@ var DataFrame = class {
     return __privateGet(this, _state).index.length;
   }
   toRecords() {
-    return exportRecords(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this));
+    return exportRecords(__privateGet(this, _state));
   }
   toIndex() {
-    return exportIndex(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this));
+    return exportIndex(__privateGet(this, _state));
   }
   toColumns() {
-    return exportColumns(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this));
+    return exportColumns(__privateGet(this, _state));
   }
   toValues() {
-    return exportValues(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this));
+    return exportValues(__privateGet(this, _state));
   }
   toSplit() {
-    return exportSplit(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this));
+    return exportSplit(__privateGet(this, _state));
   }
   toTable(options) {
-    return exportTable(__privateGet(this, _state), __privateMethod(this, _DataFrame_instances, materializedData_fn).call(this), __privateGet(this, _state).columnInfo, options);
-  }
+    return exportTable(__privateGet(this, _state), __privateGet(this, _state).columnInfo, options);
+  }
+  /**
+   * Serialize the selected orient after validating the complete exported
+   * payload with the shared bounded traversal.
+   *
+   * Depth is measured from the exported payload root, including orient
+   * wrappers (`split`/`table` nest cells one level deeper than
+   * `records`/`values`/`index`/`columns`). A cell accepted at ingestion may be
+   * rejected here when a deeper output layout pushes it past
+   * `JSON_FRAME_MAX_DEPTH`. Cycles, over-depth containers, sparse arrays, and
+   * non-JSON values introduced through caller-mutable nested cells fail with
+   * path-bearing `JsonFrameValidationError` carrying the selected orient.
+   *
+   * Validation performs one full traversal without cloning, then native
+   * serialization performs a second pass. Repeated references are visited per
+   * occurrence (detached semantics), so both passes expand aliases exactly as
+   * `JSON.stringify()` does. Optional maxNodes bounds validation occurrences
+   * (root, wrappers, metadata and scalars included), independently per call;
+   * no default quota or inherited ingestion budget applies. It does not bound
+   * payload construction, key allocation, bytes, or native hooks. Validation
+   * reads own enumerable properties and array elements, invoking
+   * caller-installed getters/`Proxy` traps, and native serialization may
+   * additionally invoke `toJSON` hooks. Hooks are caller responsibility; the
+   * package does not sandbox arbitrary JavaScript.
+   */
   toJSONString(orient, options) {
+    const normalized = normalizeToJSONStringOptions(options);
+    let payload;
     switch (orient) {
-      case "records":
-        return JSON.stringify(this.toRecords());
-      case "index":
-        return JSON.stringify(this.toIndex());
-      case "columns":
-        return JSON.stringify(this.toColumns());
-      case "values":
-        return JSON.stringify(this.toValues());
-      case "split":
-        return JSON.stringify(this.toSplit());
-      case "table":
-        return JSON.stringify(this.toTable(options));
+      case "records": {
+        payload = this.toRecords();
+        break;
+      }
+      case "index": {
+        payload = this.toIndex();
+        break;
+      }
+      case "columns": {
+        payload = this.toColumns();
+        break;
+      }
+      case "values": {
+        payload = this.toValues();
+        break;
+      }
+      case "split": {
+        payload = this.toSplit();
+        break;
+      }
+      case "table": {
+        payload = this.toTable(normalized);
+        break;
+      }
       default: {
         const exhaustive = orient;
         throw new JsonFrameValidationError("Unsupported export orient.", { value: exhaustive });
       }
     }
+    assertJsonCompatible(payload, orient, "$", normalized.maxNodes);
+    return JSON.stringify(payload);
   }
   row(position) {
     __privateMethod(this, _DataFrame_instances, assertRowPosition_fn).call(this, position);
@@ -1037,7 +1407,7 @@ var DataFrame = class {
       }
       seen.add(column);
     }
-    const renamedSchema = __privateMethod(this, _DataFrame_instances, renameSchema_fn).call(this, mapping);
+    const renamedSchema = __privateMethod(this, _DataFrame_instances, renameSchema_fn).call(this, mapping, nextColumns);
     return __privateMethod(this, _DataFrame_instances, rebuild_fn).call(this, {
       columns: nextColumns,
       sourceColumns: __privateGet(this, _state).columns,
@@ -1067,9 +1437,6 @@ assertRowPosition_fn = function(position) {
     throw new RangeError(`Row position must be an integer in [0, ${this.length}).`);
   }
 };
-materializedData_fn = function() {
-  return materializeFrameData(__privateGet(this, _state).columns, __privateGet(this, _state).data);
-};
 createRow_fn = function(position) {
   const row = /* @__PURE__ */ Object.create(null);
   for (const column of __privateGet(this, _state).columns) {
@@ -1141,16 +1508,13 @@ selectSchema_fn = function(columns) {
   if (__privateGet(this, _state).tableSchema === void 0) {
     return {};
   }
-  const fieldByName = new Map(__privateGet(this, _state).tableSchema.fields.map((field) => [field.name, field]));
+  const { indexTemplate, dataByColumn } = partitionSchemaFields(__privateGet(this, _state));
   const fields = [];
-  if (__privateGet(this, _state).tableIndexField !== void 0) {
-    const indexField = fieldByName.get(__privateGet(this, _state).tableIndexField);
-    if (indexField !== void 0) {
-      fields.push(cloneField(indexField));
-    }
+  if (__privateGet(this, _state).tableIndexField !== void 0 && indexTemplate !== void 0) {
+    fields.push(cloneField(indexTemplate));
   }
   for (const column of columns) {
-    const field = fieldByName.get(column);
+    const field = dataByColumn.get(column);
     if (field !== void 0) {
       fields.push(cloneField(field));
     }
@@ -1160,15 +1524,36 @@ selectSchema_fn = function(columns) {
     ...__privateGet(this, _state).tableIndexField === void 0 ? {} : { tableIndexField: __privateGet(this, _state).tableIndexField }
   };
 };
-renameSchema_fn = function(mapping) {
+renameSchema_fn = function(mapping, nextColumns) {
   if (__privateGet(this, _state).tableSchema === void 0) {
     return {};
   }
-  const fields = __privateGet(this, _state).tableSchema.fields.map((field) => {
-    if (!__privateGet(this, _state).columns.includes(field.name)) {
-      return cloneField(field);
+  const names = __privateGet(this, _state).tableSchema.fields.map((field) => field.name);
+  const collidesWithIndex = __privateGet(this, _state).tableIndexField !== void 0 && nextColumns.includes(__privateGet(this, _state).tableIndexField);
+  if (new Set(names).size === names.length && !collidesWithIndex) {
+    const columnNames = new Set(__privateGet(this, _state).columns);
+    const fields2 = __privateGet(this, _state).tableSchema.fields.map((field) => {
+      if (!columnNames.has(field.name)) {
+        return cloneField(field);
+      }
+      return cloneField(field, hasOwn.call(mapping, field.name) ? mapping[field.name] : field.name);
+    });
+    return {
+      tableSchema: cloneSchema2(__privateGet(this, _state).tableSchema, fields2, __privateGet(this, _state).tableSchema.primaryKey),
+      ...__privateGet(this, _state).tableIndexField === void 0 ? {} : { tableIndexField: __privateGet(this, _state).tableIndexField }
+    };
+  }
+  const { indexTemplate, dataInColumnOrder } = partitionSchemaFields(__privateGet(this, _state));
+  const fields = [];
+  if (__privateGet(this, _state).tableIndexField !== void 0 && indexTemplate !== void 0) {
+    fields.push(cloneField(indexTemplate));
+  }
+  __privateGet(this, _state).columns.forEach((column, position) => {
+    const template = dataInColumnOrder[position];
+    if (template === void 0) {
+      return;
     }
-    return cloneField(field, hasOwn.call(mapping, field.name) ? mapping[field.name] : field.name);
+    fields.push(cloneField(template, hasOwn.call(mapping, column) ? mapping[column] : column));
   });
   return {
     tableSchema: cloneSchema2(__privateGet(this, _state).tableSchema, fields, __privateGet(this, _state).tableSchema.primaryKey),
@@ -1187,7 +1572,8 @@ resetIndexSchema_fn = function() {
       )
     };
   }
-  const fields = __privateGet(this, _state).tableSchema.fields.filter((field) => field.name !== __privateGet(this, _state).tableIndexField).map((field) => cloneField(field));
+  const { dataInColumnOrder } = partitionSchemaFields(__privateGet(this, _state));
+  const fields = dataInColumnOrder.length === __privateGet(this, _state).columns.length ? dataInColumnOrder.map((field) => cloneField(field)) : __privateGet(this, _state).tableSchema.fields.filter((field) => field.name !== __privateGet(this, _state).tableIndexField).map((field) => cloneField(field));
   return {
     tableSchema: cloneSchema2(__privateGet(this, _state).tableSchema, fields)
   };
@@ -1199,105 +1585,6 @@ var InternalDataFrame = class extends DataFrame {
 };
 var createDataFrame = (state, packThreshold) => new InternalDataFrame(state, packThreshold);
 
-// src/options.ts
-var RESOLVED_ORIENTS = [
-  "records",
-  "index",
-  "columns",
-  "values",
-  "split",
-  "table"
-];
-var ORIENTS = ["auto", ...RESOLVED_ORIENTS];
-var COLUMN_TYPES = [
-  "integer",
-  "float",
-  "string",
-  "boolean",
-  "datetime",
-  "categorical",
-  "mixed",
-  "unknown"
-];
-var DEFAULT_PACK_THRESHOLD = 256;
-var isOrient = (value) => typeof value === "string" && ORIENTS.includes(value);
-var isColumnType = (value) => typeof value === "string" && COLUMN_TYPES.includes(value);
-var normalizeFromOrientOptions = (options) => {
-  if (options == null) {
-    return {
-      orient: "auto",
-      packThreshold: DEFAULT_PACK_THRESHOLD
-    };
-  }
-  if (Array.isArray(options) || typeof options !== "object") {
-    throw new JsonFrameOptionError("`fromOrient` options must be an object when provided.", "options", options);
-  }
-  const orient = options.orient ?? "auto";
-  if (!isOrient(orient)) {
-    throw new JsonFrameOptionError(
-      "`options.orient` must be one of auto, records, index, columns, values, split, or table.",
-      "orient",
-      orient
-    );
-  }
-  const packThreshold = options.packThreshold ?? DEFAULT_PACK_THRESHOLD;
-  if (!Number.isFinite(packThreshold) || !Number.isInteger(packThreshold) || packThreshold < 0) {
-    throw new JsonFrameOptionError(
-      "`options.packThreshold` must be a finite non-negative integer.",
-      "packThreshold",
-      packThreshold
-    );
-  }
-  let columns;
-  if (options.columns !== void 0) {
-    if (!Array.isArray(options.columns)) {
-      throw new JsonFrameOptionError("`options.columns` must be an array of strings.", "columns", options.columns);
-    }
-    const seen = /* @__PURE__ */ new Set();
-    columns = options.columns.map((column) => {
-      if (typeof column !== "string") {
-        throw new JsonFrameOptionError("`options.columns` must contain only strings.", "columns", column);
-      }
-      if (seen.has(column)) {
-        throw new JsonFrameOptionError("`options.columns` must not contain duplicates.", "columns", column);
-      }
-      seen.add(column);
-      return column;
-    });
-  }
-  let columnTypes;
-  if (options.columnTypes !== void 0) {
-    if (Array.isArray(options.columnTypes) || typeof options.columnTypes !== "object" || options.columnTypes === null) {
-      throw new JsonFrameOptionError(
-        "`options.columnTypes` must be an object keyed by column name.",
-        "columnTypes",
-        options.columnTypes
-      );
-    }
-    const entries = Object.entries(options.columnTypes);
-    columnTypes = Object.freeze(
-      Object.fromEntries(
-        entries.map(([column, type]) => {
-          if (!isColumnType(type)) {
-            throw new JsonFrameOptionError(
-              "`options.columnTypes` values must be valid JSON Frame logical column types.",
-              `columnTypes.${column}`,
-              type
-            );
-          }
-          return [column, type];
-        })
-      )
-    );
-  }
-  return {
-    orient,
-    packThreshold,
-    ...columns === void 0 ? {} : { columns: Object.freeze([...columns]) },
-    ...columnTypes === void 0 ? {} : { columnTypes }
-  };
-};
-
 // src/parse/parse.ts
 var hasOwn2 = Object.prototype.hasOwnProperty;
 var IDENTIFIER_PATTERN2 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -1639,6 +1926,13 @@ var parseSplit = (value, orient) => {
   }
   const columns = assertUniqueStringColumns(value.columns, orient, "$.columns");
   const data = initializeData(columns);
+  if (value.index !== void 0 && !Array.isArray(value.index)) {
+    throw new JsonFrameValidationError("`split.index` must be an array of index labels when present.", {
+      orient,
+      path: "$.index",
+      value: value.index
+    });
+  }
   const index = [];
   const indexKind = Array.isArray(value.index) ? "source" : "synthetic";
   if (Array.isArray(value.index)) {
@@ -1952,7 +2246,12 @@ var parseInput = (input, options) => {
       throw error;
     }
   })();
-  const jsonValue = cloneJsonCompatible(parsedValue);
+  const jsonValue = cloneJsonCompatible(
+    parsedValue,
+    options.orient === "auto" ? void 0 : options.orient,
+    "$",
+    options.maxNodes
+  );
   const orient = options.orient === "auto" ? detectOrient(jsonValue) : options.orient;
   switch (orient) {
     case "records":