@jsonup/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Cocova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @jsonup/core
+
+`jsonup` 生态系统的核心 JSON 解析器、状态管理器和文档构建器。
+
+## 特性
+
+- **纯 TypeScript**：框架无关，可在浏览器和 Node.js 环境中运行。
+- **身份树 (Identity Tree)**：自动跟踪和维护更新前后的节点身份，允许 UI 状态（如展开/折叠）在 JSON 数据改变时保持持久化。
+- **路径解析**：内置支持路径解析和 JSON 树搜索。
+- **惰性求值 (Lazy Evaluation)**：专为高性能设计，即使面对海量 JSON 结构也能从容应对。
+
+## 安装
+
+```bash
+npm install @jsonup/core
+# 或
+pnpm add @jsonup/core
+# 或
+yarn add @jsonup/core
+```
+
+## 基础用法
+
+```ts
+import { createDocument } from "@jsonup/core";
+
+const data = {
+  hello: "world",
+  items: [1, 2, 3],
+};
+
+const doc = createDocument(data, {
+  defaultExpandedRoot: true,
+});
+
+console.log(doc.nodes); // 准备好被渲染的扁平 JSON 节点列表
+```
+
+## 许可证
+
+## 许可证
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,316 @@
+import { Decimal } from "decimal.js";
+
+//#region src/type.d.ts
+/**
+ * 表示 JSON 基本数据类型的联合类型，包含 string、number、boolean、null 和 Decimal
+ */
+type JsonPrimitive = string | number | boolean | null | Decimal;
+/**
+ * 表示任意合法的 JSON 值类型，可以是基本类型、对象或数组
+ */
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * 表示 JSON 输入的基本数据类型的联合类型，包含 string、number、bigint、boolean、null 和 Decimal
+ */
+type JsonInputPrimitive = string | number | bigint | boolean | null | Decimal;
+/**
+ * 表示任意合法的 JSON 输入值类型，可以是基本类型、对象或数组
+ */
+type JsonInputValue = JsonInputPrimitive | JsonInputObject | JsonInputArray;
+/**
+ * 表示 JSON 对象，键为字符串，值为 JsonValue
+ */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+/**
+ * 表示 JSON 数组，元素为 JsonValue
+ */
+type JsonArray = JsonValue[];
+/**
+ * 表示 JSON 输入对象，键为字符串，值为 JsonInputValue
+ */
+interface JsonInputObject {
+  [key: string]: JsonInputValue;
+}
+/**
+ * 表示 JSON 输入数组，元素为 JsonInputValue
+ */
+type JsonInputArray = JsonInputValue[];
+/**
+ * 表示 JSON 文档的根类型，可以是对象 JSON 或数组 JSON
+ */
+type JsonDocumentType = 'object-json' | 'array-json';
+/**
+ * 表示 JSON 节点的唯一标识符类型
+ */
+type JsonNodeId = string;
+/**
+ * 表示 JSON 节点的类型枚举
+ */
+type JsonNodeType = 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
+/**
+ * 表示 JSON 树中的单个节点，包含节点的所有元数据和状态信息
+ */
+interface JsonNode {
+  /** 节点的唯一标识符 */
+  id: JsonNodeId;
+  /** 节点在父对象中的键名，如果父节点是数组或是根节点则可能为 undefined */
+  key?: string;
+  /** 节点的值，如果是容器类型（对象/数组）则为 undefined */
+  value?: JsonValue;
+  /** 子节点的数量 */
+  children: number;
+  /** 父节点的标识符，如果是根节点则为 null */
+  parent: JsonNodeId | null;
+  /** 节点在树中的深度（根节点为 0） */
+  depth: number;
+  /** 节点的数据类型 */
+  type: JsonNodeType;
+  /** 节点在文档中的路径（例如："[0].name"） */
+  path: string;
+  /** 节点是否可以展开（即是否为包含子元素的容器节点） */
+  expandable: boolean;
+  /** 节点在文档中前序遍历的顺序索引 */
+  order: number;
+  /** 节点当前是否处于展开状态 */
+  expanded: boolean;
+  /** 节点是否为叶子节点（即非容器节点） */
+  leaf: boolean;
+  /** 以当前节点为根的子树的节点总数（包含自身） */
+  size: number;
+  /** 当前节点的所有后代节点数量 */
+  descendants: number;
+}
+/**
+ * 表示 JSON 文档的动态状态，例如节点的展开状态
+ */
+interface JsonDocumentState {
+  /** 当前处于展开状态的所有节点路径的集合 */
+  expandedPaths: Set<string>;
+  /** 当前可见的节点列表（父节点折叠时，子节点不可见） */
+  visibleNodes: JsonNode[];
+  /** 切换指定节点的展开/折叠状态 */
+  toggleExpanded: (id: JsonNodeId, expanded?: boolean) => JsonDocument;
+}
+/**
+ * 表示完整的 JSON 文档实例，包含原始数据、节点列表、状态以及操作方法
+ */
+interface JsonDocument {
+  /** 文档的根类型 */
+  type: JsonDocumentType;
+  /** 文档的原始 JSON 数据 */
+  raw: JsonObject | JsonArray;
+  /** 文档中所有节点的扁平列表 */
+  nodes: JsonNode[];
+  /** 文档的当前状态 */
+  state: JsonDocumentState;
+  /** 当前可见的所有节点列表 */
+  readonly visibleNodes: JsonNode[];
+  /** 切换指定节点的展开/折叠状态，并返回更新后的文档实例 */
+  toggleExpanded: (id: JsonNodeId, expanded?: boolean) => JsonDocument;
+  /** 将文档格式化为 JSON 字符串 */
+  stringify: (space?: number) => string;
+  /** 根据节点标识符获取对应的节点 */
+  getNode: (id: JsonNodeId) => JsonNode | undefined;
+  /** 根据节点标识符获取其父节点 */
+  getParent: (id: JsonNodeId) => JsonNode | undefined;
+  /** 根据节点标识符获取其直接子节点列表 */
+  getChildren: (id: JsonNodeId) => JsonNode[];
+  /** 根据节点标识符获取其所有后代节点列表 */
+  getDescendants: (id: JsonNodeId) => JsonNode[];
+  /** 根据节点标识符获取其在文档中的路径 */
+  getPath: (id: JsonNodeId) => string | undefined;
+  /** 根据路径查找对应的节点 */
+  findByPath: (path: string) => JsonNode | undefined;
+  /** 根据查询字符串搜索节点 */
+  search: (query: string) => JsonNode[];
+}
+/**
+ * 表示 JSON 节点的标识树，用于在重新生成文档时保持节点标识的稳定性
+ */
+interface JsonNodeIdentity {
+  /** 节点的唯一标识符 */
+  id: JsonNodeId;
+  /** 子节点的标识树记录，对应对象键或数组索引 */
+  children?: Record<string, JsonNodeIdentity> | JsonNodeIdentity[];
+}
+/**
+ * 创建 JSON 文档时可用的配置选项
+ */
+interface CreateDocumentOptions {
+  /**
+   * 是否默认展开根节点。对于对象来说是顶层，对于数组来说是第一层元素
+   * @default true
+   */
+  defaultExpandedRoot?: boolean;
+  /**
+   * 是否默认展开所有节点
+   * @default false
+   */
+  defaultExpandedAll?: boolean;
+  /**
+   * 默认展开到指定层级。使用 `true` 表示展开所有层级
+   * @default undefined
+   */
+  defaultExpandedDepth?: number | true;
+  /**
+   * 默认展开的路径列表
+   * @default undefined
+   */
+  expandedPaths?: Iterable<string>;
+  /**
+   * 标识树，用于状态恢复
+   * @default undefined
+   */
+  identityTree?: JsonNodeIdentity;
+  /**
+   * 是否克隆原始输入数据以防止内部状态突变
+   * @default false
+   */
+  cloneRaw?: boolean;
+}
+/**
+ * 表示可接受的 JSON 输入类型
+ */
+type JsonInput = string | JsonInputObject | JsonInputArray;
+//#endregion
+//#region src/document.d.ts
+/**
+ * 创建并初始化一个 JSON 文档实例。
+ * 将原始输入数据转换为包含树形结构信息、节点标识和交互状态的文档对象。
+ *
+ * @param input - 原始的 JSON 输入或现有的 JSON 文档实例
+ * @param options - 创建文档时的配置选项
+ * @returns 初始化后的完整 JSON 文档实例
+ */
+declare function createDocument(input: JsonInput | JsonDocument, options?: CreateDocumentOptions): JsonDocument;
+/**
+ * 获取 JSON 文档的标识树（Identity Tree）。
+ * 标识树用于在重新生成文档时保持节点的唯一标识，从而维持状态（如展开/折叠状态）的一致性。
+ *
+ * @param document - 目标 JSON 文档实例
+ * @returns 对应的节点标识树
+ * @throws 当文档中缺少标识树时抛出错误
+ */
+declare function getDocumentIdentityTree(document: JsonDocument): JsonNodeIdentity;
+/**
+ * 将 JSON 文档序列化为 JSON 字符串。
+ * 会自动处理 Decimal 类型的数值。
+ *
+ * @param document - 要序列化的 JSON 文档实例
+ * @param space - 用于缩进的空格数，默认为 2
+ * @returns 序列化后的 JSON 字符串
+ */
+declare function stringify(document: JsonDocument, space?: number): string;
+/**
+ * 判断给定的值是否为有效的 JSON 文档实例。
+ *
+ * @param value - 要检查的值
+ * @returns 如果是有效的 JsonDocument 返回 true，否则返回 false
+ */
+declare function isJsonDocument(value: JsonInput | JsonDocument): value is JsonDocument;
+//#endregion
+//#region src/identity.d.ts
+/**
+ * 生成唯一的 JSON 节点标识符。
+ *
+ * @returns 长度为 28 的随机唯一字符串
+ */
+declare function createJsonNodeId(): JsonNodeId;
+//#endregion
+//#region src/normalize.d.ts
+/**
+ * 将给定的值深度转换为合法的 JsonValue，支持 bigint 和 Decimal 转换。
+ *
+ * @param value - 要转换的任意值
+ * @returns 规范化后的 JsonValue
+ * @throws 当值无法被 JSON 序列化时抛出错误
+ */
+declare function toJsonValue(value: unknown): JsonValue;
+/**
+ * 判断给定的 JsonValue 是否为容器类型（对象或数组）。
+ *
+ * @param value - 要判断的 JsonValue
+ * @returns 如果是对象或数组则返回 true
+ */
+declare function isContainerValue(value: JsonValue): value is JsonObject | JsonArray;
+/**
+ * 判断给定的 JsonValue 是否为普通 JSON 对象。
+ *
+ * @param value - 要判断的 JsonValue
+ * @returns 如果是普通对象则返回 true
+ */
+declare function isJsonObject(value: JsonValue): value is JsonObject;
+//#endregion
+//#region src/query.d.ts
+/**
+ * 根据节点标识符获取对应的节点实例。
+ *
+ * @param document - JSON 文档实例
+ * @param id - 节点标识符
+ * @returns 如果找到对应节点则返回，否则返回 undefined
+ */
+declare function getNode(document: JsonDocument, id: JsonNodeId): JsonNode | undefined;
+/**
+ * 根据节点标识符获取其父节点。
+ *
+ * @param document - JSON 文档实例
+ * @param id - 节点标识符
+ * @returns 如果存在父节点则返回，否则返回 undefined（如根节点或未找到）
+ */
+declare function getParent(document: JsonDocument, id: JsonNodeId): JsonNode | undefined;
+/**
+ * 根据节点标识符获取其所有的直接子节点。
+ *
+ * @param document - JSON 文档实例
+ * @param id - 节点标识符
+ * @returns 子节点列表数组
+ */
+declare function getChildren(document: JsonDocument, id: JsonNodeId): JsonNode[];
+/**
+ * 根据节点标识符获取其所有的后代节点（按前序遍历顺序）。
+ *
+ * @param document - JSON 文档实例
+ * @param id - 节点标识符
+ * @returns 所有后代节点的数组
+ */
+declare function getDescendants(document: JsonDocument, id: JsonNodeId): JsonNode[];
+/**
+ * 根据节点标识符获取该节点在文档中的路径。
+ *
+ * @param document - JSON 文档实例
+ * @param id - 节点标识符
+ * @returns 节点的路径字符串，未找到时返回 undefined
+ */
+declare function getPath(document: JsonDocument, id: JsonNodeId): string | undefined;
+/**
+ * 根据路径字符串精确查找对应的节点。
+ *
+ * @param document - JSON 文档实例
+ * @param path - 节点路径字符串
+ * @returns 找到的节点实例，未找到时返回 undefined
+ */
+declare function findByPath(document: JsonDocument, path: string): JsonNode | undefined;
+/**
+ * 根据查询字符串在文档中模糊搜索匹配的节点。
+ * 匹配范围包括：节点的键名、路径、类型名称以及叶子节点的值。
+ * 搜索忽略大小写。
+ *
+ * @param document - JSON 文档实例
+ * @param query - 查询字符串
+ * @returns 匹配到的节点列表
+ */
+declare function search(document: JsonDocument, query: string): JsonNode[];
+//#endregion
+//#region src/state.d.ts
+/**
+ * 根据所有节点列表和它们的展开状态，计算出当前可见的节点列表。
+ * 折叠状态下的子节点会被跳过。
+ *
+ * @param nodes - 文档中所有节点的列表（按前序遍历顺序）
+ * @returns 当前可见节点的列表
+ */
+declare function getVisibleNodes(nodes: JsonNode[]): JsonNode[];
+//#endregion
+export { type CreateDocumentOptions, type JsonArray, type JsonDocument, type JsonDocumentState, type JsonDocumentType, type JsonInput, type JsonInputArray, type JsonInputObject, type JsonInputPrimitive, type JsonInputValue, type JsonNode, type JsonNodeId, type JsonNodeIdentity, type JsonNodeType, type JsonObject, type JsonPrimitive, type JsonValue, createDocument, createJsonNodeId, findByPath, getChildren, getDescendants, getDocumentIdentityTree, getNode, getParent, getPath, getVisibleNodes, isContainerValue, isJsonDocument, isJsonObject, search, stringify, toJsonValue };

package/dist/index.mjs

@@ -0,0 +1,617 @@
+import { Decimal } from "decimal.js";
+import { nanoid } from "nanoid";
+//#region src/identity.ts
+/**
+* 内部用于在 JSON 文档实例上挂载标识树的 Symbol 键。
+*/
+const DOCUMENT_IDENTITY = Symbol.for("@jsonup/document-identity");
+/**
+* 生成唯一的 JSON 节点标识符。
+*
+* @returns 长度为 28 的随机唯一字符串
+*/
+function createJsonNodeId() {
+	return nanoid(28);
+}
+//#endregion
+//#region src/normalize.ts
+const DECIMAL_MARKER = "__jsonupDecimal__";
+/**
+* 将输入解析并规范化为 JSON 根对象或数组。
+* 如果输入是字符串，将安全地解析 JSON 字符串（大数将转换为 Decimal 类型）。
+*
+* @param input - JSON 字符串、对象或数组
+* @returns 规范化后的 JsonObject 或 JsonArray
+* @throws 当解析结果不是对象或数组时抛出错误
+*/
+function toJsonRoot(input) {
+	const value = toJsonValue(typeof input === "string" ? parseJsonWithDecimal(input) : input);
+	if (!isContainerValue(value)) throw new TypeError("JSON root must be an object or array.");
+	return value;
+}
+/**
+* 将给定的值深度转换为合法的 JsonValue，支持 bigint 和 Decimal 转换。
+*
+* @param value - 要转换的任意值
+* @returns 规范化后的 JsonValue
+* @throws 当值无法被 JSON 序列化时抛出错误
+*/
+function toJsonValue(value) {
+	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "bigint") return new Decimal(value.toString());
+	if (Decimal.isDecimal(value)) return value;
+	if (Array.isArray(value)) return value.map((item) => toJsonValue(item));
+	if (isPlainObject(value)) {
+		const decimalValue = getDecimalMarkerValue(value);
+		if (decimalValue !== void 0) return new Decimal(decimalValue);
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = toJsonValue(item);
+		return result;
+	}
+	throw new TypeError("Value must be JSON serializable.");
+}
+/**
+* 判断给定的 JsonValue 是否为容器类型（对象或数组）。
+*
+* @param value - 要判断的 JsonValue
+* @returns 如果是对象或数组则返回 true
+*/
+function isContainerValue(value) {
+	return value !== null && typeof value === "object" && !Decimal.isDecimal(value);
+}
+/**
+* 判断给定的 JsonValue 是否为普通 JSON 对象。
+*
+* @param value - 要判断的 JsonValue
+* @returns 如果是普通对象则返回 true
+*/
+function isJsonObject(value) {
+	return value !== null && !Array.isArray(value) && typeof value === "object" && !Decimal.isDecimal(value);
+}
+function isPlainObject(value) {
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+function parseJsonWithDecimal(input) {
+	return JSON.parse(rewriteUnsafeJsonNumbers(input));
+}
+function rewriteUnsafeJsonNumbers(input) {
+	let output = "";
+	let index = 0;
+	let inString = false;
+	let escaping = false;
+	while (index < input.length) {
+		const char = input[index];
+		if (inString) {
+			output += char;
+			if (escaping) escaping = false;
+			else if (char === "\\") escaping = true;
+			else if (char === "\"") inString = false;
+			index += 1;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			output += char;
+			index += 1;
+			continue;
+		}
+		if (char === "-" || isDigit(char)) {
+			const numberToken = readJsonNumber(input, index);
+			if (numberToken) {
+				output += shouldParseAsDecimal(numberToken) ? `{"${DECIMAL_MARKER}":"${numberToken}"}` : numberToken;
+				index += numberToken.length;
+				continue;
+			}
+		}
+		output += char;
+		index += 1;
+	}
+	return output;
+}
+function readJsonNumber(input, start) {
+	let index = start;
+	if (input[index] === "-") index += 1;
+	if (input[index] === "0") index += 1;
+	else if (isDigitOneToNine(input[index])) {
+		index += 1;
+		while (isDigit(input[index])) index += 1;
+	} else return;
+	if (input[index] === ".") {
+		index += 1;
+		if (!isDigit(input[index])) return;
+		while (isDigit(input[index])) index += 1;
+	}
+	if (input[index] === "e" || input[index] === "E") {
+		index += 1;
+		if (input[index] === "+" || input[index] === "-") index += 1;
+		if (!isDigit(input[index])) return;
+		while (isDigit(input[index])) index += 1;
+	}
+	return input.slice(start, index);
+}
+function shouldParseAsDecimal(numberToken) {
+	if (/[.e]/i.test(numberToken)) return true;
+	const decimal = new Decimal(numberToken);
+	return !decimal.isInteger() || decimal.abs().greaterThan(Number.MAX_SAFE_INTEGER);
+}
+function getDecimalMarkerValue(value) {
+	if (Object.keys(value).length !== 1) return;
+	const decimalValue = value[DECIMAL_MARKER];
+	return typeof decimalValue === "string" ? decimalValue : void 0;
+}
+function isDigit(value) {
+	return value !== void 0 && value >= "0" && value <= "9";
+}
+function isDigitOneToNine(value) {
+	return value !== void 0 && value >= "1" && value <= "9";
+}
+//#endregion
+//#region src/path.ts
+/**
+* 构建子节点的路径字符串。
+*
+* @param parentPath - 父节点的路径
+* @param childKey - 子节点的键或索引
+* @param parentIsArray - 父节点是否为数组
+* @returns 子节点的完整路径
+*/
+function buildChildPath(parentPath, childKey, parentIsArray) {
+	if (parentIsArray) {
+		const segment = `[${childKey}]`;
+		return parentPath ? `${parentPath}${segment}` : segment;
+	}
+	return parentPath ? `${parentPath}.${childKey}` : childKey;
+}
+//#endregion
+//#region src/query.ts
+/**
+* 根据节点标识符获取对应的节点实例。
+*
+* @param document - JSON 文档实例
+* @param id - 节点标识符
+* @returns 如果找到对应节点则返回，否则返回 undefined
+*/
+function getNode(document, id) {
+	return document.nodes.find((node) => node.id === id);
+}
+/**
+* 根据节点标识符获取其父节点。
+*
+* @param document - JSON 文档实例
+* @param id - 节点标识符
+* @returns 如果存在父节点则返回，否则返回 undefined（如根节点或未找到）
+*/
+function getParent(document, id) {
+	const node = getNode(document, id);
+	if (!node || node.parent === null) return;
+	return getNode(document, node.parent);
+}
+/**
+* 根据节点标识符获取其所有的直接子节点。
+*
+* @param document - JSON 文档实例
+* @param id - 节点标识符
+* @returns 子节点列表数组
+*/
+function getChildren(document, id) {
+	return document.nodes.filter((node) => node.parent === id);
+}
+/**
+* 根据节点标识符获取其所有的后代节点（按前序遍历顺序）。
+*
+* @param document - JSON 文档实例
+* @param id - 节点标识符
+* @returns 所有后代节点的数组
+*/
+function getDescendants(document, id) {
+	const startIndex = document.nodes.findIndex((node) => node.id === id);
+	if (startIndex === -1) return [];
+	const current = document.nodes[startIndex];
+	const descendants = [];
+	for (let index = startIndex + 1; index < document.nodes.length; index += 1) {
+		const candidate = document.nodes[index];
+		if (candidate.depth <= current.depth) break;
+		descendants.push(candidate);
+	}
+	return descendants;
+}
+/**
+* 根据节点标识符获取该节点在文档中的路径。
+*
+* @param document - JSON 文档实例
+* @param id - 节点标识符
+* @returns 节点的路径字符串，未找到时返回 undefined
+*/
+function getPath(document, id) {
+	return getNode(document, id)?.path;
+}
+/**
+* 根据路径字符串精确查找对应的节点。
+*
+* @param document - JSON 文档实例
+* @param path - 节点路径字符串
+* @returns 找到的节点实例，未找到时返回 undefined
+*/
+function findByPath(document, path) {
+	return document.nodes.find((node) => node.path === path);
+}
+/**
+* 根据查询字符串在文档中模糊搜索匹配的节点。
+* 匹配范围包括：节点的键名、路径、类型名称以及叶子节点的值。
+* 搜索忽略大小写。
+*
+* @param document - JSON 文档实例
+* @param query - 查询字符串
+* @returns 匹配到的节点列表
+*/
+function search(document, query) {
+	const normalized = query.trim().toLowerCase();
+	if (!normalized) return [...document.nodes];
+	return document.nodes.filter((node) => {
+		return [
+			node.key,
+			node.path,
+			node.type,
+			node.leaf ? stringifyLeafValue(node.value) : void 0
+		].some((segment) => segment?.toLowerCase().includes(normalized) === true);
+	});
+}
+function stringifyLeafValue(value) {
+	if (value === void 0 || value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value === void 0 ? void 0 : String(value);
+	return JSON.stringify(value);
+}
+//#endregion
+//#region src/state.ts
+/**
+* 创建 JSON 文档的内部状态对象，用于管理展开路径和可见节点。
+*
+* @param document - JSON 文档实例
+* @param expandedPaths - 初始展开的节点路径集合
+* @returns 初始化后的内部状态对象
+*/
+function createDocumentState(document, expandedPaths = []) {
+	const state = {
+		expandedPaths: new Set(expandedPaths),
+		visibleNodes: [],
+		toggleExpanded(id, expanded) {
+			const node = getNode(document, id);
+			if (!node?.expandable) return document;
+			const nextExpanded = expanded ?? !node.expanded;
+			if (node.expanded === nextExpanded) return document;
+			node.expanded = nextExpanded;
+			if (nextExpanded) state.expandedPaths.add(node.path);
+			else state.expandedPaths.delete(node.path);
+			state.syncVisibleNodes(document.nodes);
+			return document;
+		},
+		syncVisibleNodes(nodes) {
+			state.visibleNodes = getVisibleNodes(nodes);
+			return state.visibleNodes;
+		}
+	};
+	return state;
+}
+/**
+* 根据所有节点列表和它们的展开状态，计算出当前可见的节点列表。
+* 折叠状态下的子节点会被跳过。
+*
+* @param nodes - 文档中所有节点的列表（按前序遍历顺序）
+* @returns 当前可见节点的列表
+*/
+function getVisibleNodes(nodes) {
+	const visibleNodes = [];
+	for (let index = 0; index < nodes.length; index += 1) {
+		const node = nodes[index];
+		visibleNodes.push(node);
+		if (node.expandable && !node.expanded) index += node.descendants;
+	}
+	return visibleNodes;
+}
+//#endregion
+//#region src/document.ts
+/**
+* 创建并初始化一个 JSON 文档实例。
+* 将原始输入数据转换为包含树形结构信息、节点标识和交互状态的文档对象。
+*
+* @param input - 原始的 JSON 输入或现有的 JSON 文档实例
+* @param options - 创建文档时的配置选项
+* @returns 初始化后的完整 JSON 文档实例
+*/
+function createDocument(input, options = {}) {
+	const normalizedInput = isJsonDocument(input) ? input.raw : toJsonRoot(input);
+	const resolvedOptions = resolveCreateDocumentOptions(input, options);
+	const raw = resolvedOptions.cloneRaw === false ? normalizedInput : structuredClone(normalizedInput);
+	const identityTree = createIdentityTree(raw, resolvedOptions.identityTree);
+	const state = {
+		nextOrder: 0,
+		expandedPaths: new Set(resolvedOptions.expandedPaths),
+		hasExplicitExpandedPaths: resolvedOptions.hasExplicitExpandedPaths,
+		defaultExpandedAll: resolvedOptions.defaultExpandedAll,
+		defaultExpandedDepth: resolvedOptions.defaultExpandedDepth
+	};
+	const nodes = [];
+	walkValue(raw, identityTree, {
+		depth: 0,
+		key: void 0,
+		parent: null,
+		path: "",
+		nodes,
+		state
+	});
+	const document = {
+		type: Array.isArray(raw) ? "array-json" : "object-json",
+		raw,
+		nodes,
+		state: void 0
+	};
+	const documentState = createDocumentState(document, state.expandedPaths);
+	Object.defineProperty(document, DOCUMENT_IDENTITY, {
+		value: identityTree,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	Object.defineProperty(document, "state", {
+		value: documentState,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+	Object.defineProperties(document, {
+		visibleNodes: {
+			get() {
+				return documentState.visibleNodes;
+			},
+			enumerable: false,
+			configurable: false
+		},
+		toggleExpanded: {
+			value(id, expanded) {
+				return documentState.toggleExpanded(id, expanded);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		stringify: {
+			value(space = 2) {
+				return stringify(document, space);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		getNode: {
+			value(id) {
+				return getNode(document, id);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		getParent: {
+			value(id) {
+				return getParent(document, id);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		getChildren: {
+			value(id) {
+				return getChildren(document, id);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		getDescendants: {
+			value(id) {
+				return getDescendants(document, id);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		getPath: {
+			value(id) {
+				return getPath(document, id);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		findByPath: {
+			value(path) {
+				return findByPath(document, path);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		},
+		search: {
+			value(query) {
+				return search(document, query);
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		}
+	});
+	documentState.syncVisibleNodes(document.nodes);
+	return document;
+}
+/**
+* 获取 JSON 文档的标识树（Identity Tree）。
+* 标识树用于在重新生成文档时保持节点的唯一标识，从而维持状态（如展开/折叠状态）的一致性。
+*
+* @param document - 目标 JSON 文档实例
+* @returns 对应的节点标识树
+* @throws 当文档中缺少标识树时抛出错误
+*/
+function getDocumentIdentityTree(document) {
+	const identityTree = document[DOCUMENT_IDENTITY];
+	if (!identityTree) throw new Error("Document identity tree is missing.");
+	return identityTree;
+}
+/**
+* 将 JSON 文档序列化为 JSON 字符串。
+* 会自动处理 Decimal 类型的数值。
+*
+* @param document - 要序列化的 JSON 文档实例
+* @param space - 用于缩进的空格数，默认为 2
+* @returns 序列化后的 JSON 字符串
+*/
+function stringify(document, space = 2) {
+	return JSON.stringify(document.raw, (_key, value) => Decimal.isDecimal(value) ? value.toString() : value, space);
+}
+/**
+* 判断给定的值是否为有效的 JSON 文档实例。
+*
+* @param value - 要检查的值
+* @returns 如果是有效的 JsonDocument 返回 true，否则返回 false
+*/
+function isJsonDocument(value) {
+	return typeof value === "object" && value !== null && "raw" in value && "nodes" in value && "state" in value && "type" in value;
+}
+function walkValue(value, identity, context) {
+	const { depth, key, parent, path, nodes, state } = context;
+	const type = getNodeType(value);
+	const container = isContainerValue(value);
+	const childrenEntries = container ? getContainerEntries(value, identity) : [];
+	const children = childrenEntries.length;
+	const expandable = container && children > 0;
+	const expanded = shouldExpandNode(path, depth, expandable, state);
+	const node = {
+		id: identity.id,
+		key,
+		value: container ? void 0 : value,
+		children,
+		parent,
+		depth,
+		type,
+		path,
+		expandable,
+		order: state.nextOrder,
+		expanded,
+		leaf: !container,
+		size: 1,
+		descendants: 0
+	};
+	if (expanded) state.expandedPaths.add(path);
+	nodes.push(node);
+	state.nextOrder += 1;
+	let subtreeSize = 1;
+	let hasExpandedDescendant = false;
+	for (const [childKey, childValue, childIdentity] of childrenEntries) {
+		const childResult = walkValue(childValue, childIdentity, {
+			depth: depth + 1,
+			key: childKey,
+			parent: identity.id,
+			path: buildChildPath(path, childKey, Array.isArray(value)),
+			nodes,
+			state
+		});
+		subtreeSize += childResult.size;
+		if (childResult.expanded) hasExpandedDescendant = true;
+	}
+	if (hasExpandedDescendant && expandable && !node.expanded) {
+		node.expanded = true;
+		state.expandedPaths.add(path);
+	}
+	node.size = subtreeSize;
+	node.descendants = subtreeSize - 1;
+	return {
+		size: subtreeSize,
+		expanded: node.expanded
+	};
+}
+function createIdentityTree(value, existing) {
+	const id = existing?.id ?? createJsonNodeId();
+	if (Array.isArray(value)) {
+		const existingChildren = Array.isArray(existing?.children) ? existing.children : [];
+		return {
+			id,
+			children: value.map((item, index) => createIdentityTree(item, existingChildren[index]))
+		};
+	}
+	if (isJsonObject(value)) {
+		const existingChildren = isIdentityRecord(existing?.children) ? existing.children : {};
+		const children = {};
+		for (const [key, item] of Object.entries(value)) children[key] = createIdentityTree(item, existingChildren[key]);
+		return {
+			id,
+			children
+		};
+	}
+	return { id };
+}
+function resolveCreateDocumentOptions(input, options) {
+	const defaultExpandedRoot = options.defaultExpandedRoot ?? true;
+	let defaultExpandedDepth = options.defaultExpandedDepth;
+	if (defaultExpandedDepth === void 0 && defaultExpandedRoot && !options.defaultExpandedAll) {
+		const raw = isJsonDocument(input) ? input.raw : input;
+		defaultExpandedDepth = Array.isArray(raw) ? 1 : 0;
+	}
+	const defaultExpandedAll = options.defaultExpandedAll ?? false;
+	const cloneRaw = options.cloneRaw ?? false;
+	const identityTree = options.identityTree ?? (isJsonDocument(input) ? getDocumentIdentityTree(input) : void 0);
+	const previousExpandedPaths = isJsonDocument(input) ? Array.from(input.state.expandedPaths) : void 0;
+	const hasExplicitExpandedPaths = options.expandedPaths !== void 0 || defaultExpandedDepth === void 0 && !defaultExpandedAll && previousExpandedPaths !== void 0;
+	return {
+		hasExplicitExpandedPaths,
+		expandedPaths: options.expandedPaths !== void 0 ? new Set(options.expandedPaths) : hasExplicitExpandedPaths ? new Set(previousExpandedPaths) : /* @__PURE__ */ new Set(),
+		defaultExpandedAll,
+		defaultExpandedDepth,
+		identityTree,
+		cloneRaw
+	};
+}
+function shouldExpandNode(path, depth, expandable, state) {
+	if (!expandable) return false;
+	if (state.hasExplicitExpandedPaths && state.expandedPaths.has(path)) return true;
+	if (state.defaultExpandedDepth !== void 0) return state.defaultExpandedDepth === true ? true : depth <= state.defaultExpandedDepth;
+	return state.defaultExpandedAll;
+}
+function getContainerEntries(value, identity) {
+	if (Array.isArray(value)) {
+		const children = Array.isArray(identity.children) ? identity.children : [];
+		return value.map((item, index) => {
+			const childIdentity = children[index];
+			if (!childIdentity) throw new Error("Array identity tree is out of sync.");
+			return [
+				String(index),
+				item,
+				childIdentity
+			];
+		});
+	}
+	if (!isIdentityRecord(identity.children)) throw new Error("Object identity tree is out of sync.");
+	const children = identity.children;
+	return Object.entries(value).map(([key, item]) => {
+		const childIdentity = children[key];
+		if (!childIdentity) throw new Error(`Object identity tree is missing key "${key}".`);
+		return [
+			key,
+			item,
+			childIdentity
+		];
+	});
+}
+function getNodeType(value) {
+	if (value === null) return "null";
+	if (Decimal.isDecimal(value)) return "number";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "object") return "object";
+	switch (typeof value) {
+		case "string": return "string";
+		case "number": return "number";
+		case "boolean": return "boolean";
+		default: throw new TypeError("Unsupported JSON value type.");
+	}
+}
+function isIdentityRecord(children) {
+	return children !== void 0 && !Array.isArray(children);
+}
+//#endregion
+export { createDocument, createJsonNodeId, findByPath, getChildren, getDescendants, getDocumentIdentityTree, getNode, getParent, getPath, getVisibleNodes, isContainerValue, isJsonDocument, isJsonObject, search, stringify, toJsonValue };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jsonup/core",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "The core JSON parser, state manager, and document builder for the jsonup ecosystem.",
+  "author": {
+    "name": "Michael Cocova",
+    "email": "michael.cocova@gmail.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/michaelcocova/jsonup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelcocova/jsonup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/michaelcocova/jsonup/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "decimal.js": "10.6.0",
+    "nanoid": "5.1.15"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  }
+}