@jsonup/operation 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,41 @@
+# @jsonup/operation
+
+供 `jsonup` 生态系统使用的不可变 JSON 树操作库。
+
+## 特性
+
+- **不可变更新**：安全地操作 JSON 文档，而无需修改原始对象。
+- **保持身份 (Identity Preservation)**：当节点被更新、插入、移动或删除时，内部的 `IdentityTree` 会被保留，确保 UI 状态不会发生跳动或重置。
+- **全面的 API**：支持更新值、插入元素、删除节点、跨父级移动节点以及重命名键。
+
+## 安装
+
+```bash
+npm install @jsonup/operation
+# 或
+pnpm add @jsonup/operation
+# 或
+yarn add @jsonup/operation
+```
+
+## 基础用法
+
+```ts
+import { createDocument } from "@jsonup/core";
+import { insert, remove, updateValue } from "@jsonup/operation";
+
+const doc = createDocument({ a: 1, b: 2 });
+
+// 更新值
+const nextDoc = updateValue(doc, "node-id-of-a", 42);
+
+// 插入新节点
+const docWithInsert = insert(doc, "node-id-of-root", { c: 3 });
+
+// 删除节点
+const docWithoutB = remove(doc, "node-id-of-b");
+```
+
+## 许可证
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,95 @@
+import { JsonDocument, JsonNodeId } from "@jsonup/core";
+
+//#region src/index.d.ts
+/**
+ * 对象节点插入输入的参数接口。
+ * 用于向 JSON 对象节点中插入新属性。
+ */
+interface ObjectInsertInput {
+  /**
+   * 插入属性的键名。
+   */
+  key: string;
+  /**
+   * 插入属性的值，可以是任何合法的 JSON 对应值，将会被转化为标准的 JsonValue。
+   */
+  value: unknown;
+}
+/**
+ * 数组节点插入输入的参数接口。
+ * 用于向 JSON 数组节点中插入新元素。
+ */
+interface ArrayInsertInput {
+  /**
+   * 插入元素的目标索引。如果未提供，默认插入到数组末尾。
+   */
+  index?: number;
+  /**
+   * 插入元素的值，可以是任何合法的 JSON 对应值，将会被转化为标准的 JsonValue。
+   */
+  value: unknown;
+}
+/**
+ * 插入操作的输入类型，可以是对象插入输入或数组插入输入。
+ */
+type InsertInput = ObjectInsertInput | ArrayInsertInput;
+/**
+ * 移动节点时的选项接口。
+ */
+interface MoveOptions {
+  /**
+   * 移动到对象节点时使用的新键名。如果未提供，将尝试使用原节点的键名。
+   */
+  key?: string;
+  /**
+   * 移动到数组节点时使用的目标索引。如果未提供，默认移动到数组末尾。
+   */
+  index?: number;
+}
+/**
+ * 更新 JSON 文档中指定节点的值。
+ * @param document 当前的 JSON 文档对象。
+ * @param id 需要更新的节点的唯一标识符 (JsonNodeId)。
+ * @param value 新的值，将会被转化为标准的 JsonValue。
+ * @returns 返回一个新的包含更新后内容的 JSON 文档。
+ * @throws 当指定的节点不存在，或者更新根节点时值不是对象或数组时抛出错误。
+ */
+declare function updateValue(document: JsonDocument, id: JsonNodeId, value: unknown): JsonDocument;
+/**
+ * 在 JSON 文档的指定父节点中插入新的子节点。
+ * @param document 当前的 JSON 文档对象。
+ * @param parentId 目标父节点的唯一标识符 (JsonNodeId)。
+ * @param input 插入的参数，包含键名/索引和值。
+ * @returns 返回一个新的包含插入节点后的 JSON 文档。
+ * @throws 当目标父节点不是对象或数组，或者在对象中键已存在，或输入类型不匹配时抛出错误。
+ */
+declare function insert(document: JsonDocument, parentId: JsonNodeId, input: InsertInput): JsonDocument;
+/**
+ * 从 JSON 文档中移除指定的节点。
+ * @param document 当前的 JSON 文档对象。
+ * @param id 需要移除的节点的唯一标识符 (JsonNodeId)。
+ * @returns 返回一个新的移除了指定节点后的 JSON 文档。
+ * @throws 当指定的节点不存在，或者尝试移除根节点时抛出错误。
+ */
+declare function remove(document: JsonDocument, id: JsonNodeId): JsonDocument;
+/**
+ * 重命名 JSON 文档中指定对象子节点的键名。
+ * @param document 当前的 JSON 文档对象。
+ * @param id 需要重命名键的节点的唯一标识符 (JsonNodeId)。
+ * @param nextKey 新的键名。
+ * @returns 返回一个新的重命名键后的 JSON 文档。
+ * @throws 当目标节点不是对象子节点，或者新键名已存在，或键名为空时抛出错误。
+ */
+declare function renameKey(document: JsonDocument, id: JsonNodeId, nextKey: string): JsonDocument;
+/**
+ * 将 JSON 文档中的指定节点移动到另一个父节点下。
+ * @param document 当前的 JSON 文档对象。
+ * @param id 需要移动的节点的唯一标识符 (JsonNodeId)。
+ * @param parentId 目标父节点的唯一标识符 (JsonNodeId)。
+ * @param options 移动时的额外选项，如移动到对象中的新键名，或移动到数组中的目标索引。
+ * @returns 返回一个新的包含移动节点后的 JSON 文档。
+ * @throws 当目标父节点不是对象或数组，尝试移动根节点，或者尝试将节点移动到其自身的子代中时抛出错误。
+ */
+declare function move(document: JsonDocument, id: JsonNodeId, parentId: JsonNodeId, options?: MoveOptions): JsonDocument;
+//#endregion
+export { ArrayInsertInput, InsertInput, MoveOptions, ObjectInsertInput, insert, move, remove, renameKey, updateValue };

package/dist/index.mjs

@@ -0,0 +1,309 @@
+import { createDocument, createJsonNodeId, getDocumentIdentityTree, getNode, isContainerValue, isJsonObject, toJsonValue } from "@jsonup/core";
+//#region src/index.ts
+/**
+* 更新 JSON 文档中指定节点的值。
+* @param document 当前的 JSON 文档对象。
+* @param id 需要更新的节点的唯一标识符 (JsonNodeId)。
+* @param value 新的值，将会被转化为标准的 JsonValue。
+* @returns 返回一个新的包含更新后内容的 JSON 文档。
+* @throws 当指定的节点不存在，或者更新根节点时值不是对象或数组时抛出错误。
+*/
+function updateValue(document, id, value) {
+	getRequiredNode(document, id);
+	const nextValue = toJsonValue(value);
+	let nextRaw = cloneJsonValue(document.raw);
+	let nextIdentityTree = cloneIdentityTree(getDocumentIdentityTree(document));
+	const location = findRequiredLocation(nextRaw, nextIdentityTree, id);
+	if (location.parentValue === null || location.parentIdentity === null) {
+		if (!isContainerValue(nextValue)) throw new TypeError("JSON root must be an object or array.");
+		nextRaw = nextValue;
+		nextIdentityTree = createIdentityTree(nextValue, location.identity.id);
+	} else {
+		assignChild(location.parentValue, location.key, nextValue);
+		replaceIdentityChild(location.parentIdentity, location.key, createIdentityTree(nextValue, location.identity.id));
+	}
+	return rebuildDocument(document, nextRaw, nextIdentityTree);
+}
+/**
+* 在 JSON 文档的指定父节点中插入新的子节点。
+* @param document 当前的 JSON 文档对象。
+* @param parentId 目标父节点的唯一标识符 (JsonNodeId)。
+* @param input 插入的参数，包含键名/索引和值。
+* @returns 返回一个新的包含插入节点后的 JSON 文档。
+* @throws 当目标父节点不是对象或数组，或者在对象中键已存在，或输入类型不匹配时抛出错误。
+*/
+function insert(document, parentId, input) {
+	const parent = getRequiredNode(document, parentId);
+	const nextRaw = cloneJsonValue(document.raw);
+	const nextIdentityTree = cloneIdentityTree(getDocumentIdentityTree(document));
+	const parentLocation = findRequiredLocation(nextRaw, nextIdentityTree, parentId);
+	const parentValue = parentLocation.value;
+	if (parent.type === "object") {
+		if (!isObjectInsertInput(input)) throw new TypeError("Object insert requires a key.");
+		if (!isJsonObject(parentValue)) throw new TypeError("Target parent is not an object.");
+		if (Object.hasOwn(parentValue, input.key)) throw new Error(`Key "${input.key}" already exists.`);
+		parentValue[input.key] = toJsonValue(input.value);
+		ensureObjectIdentityChildren(parentLocation.identity)[input.key] = createIdentityTree(parentValue[input.key]);
+		return rebuildDocument(document, nextRaw, nextIdentityTree);
+	}
+	if (parent.type === "array") {
+		if (isObjectInsertInput(input)) throw new TypeError("Array insert does not accept an object key.");
+		if (!Array.isArray(parentValue)) throw new TypeError("Target parent is not an array.");
+		const index = normalizeArrayIndex(input.index ?? parentValue.length, true);
+		const childValue = toJsonValue(input.value);
+		parentValue.splice(index, 0, childValue);
+		ensureArrayIdentityChildren(parentLocation.identity).splice(index, 0, createIdentityTree(childValue));
+		return rebuildDocument(document, nextRaw, nextIdentityTree);
+	}
+	throw new TypeError("Insert target must be an object or array node.");
+}
+/**
+* 从 JSON 文档中移除指定的节点。
+* @param document 当前的 JSON 文档对象。
+* @param id 需要移除的节点的唯一标识符 (JsonNodeId)。
+* @returns 返回一个新的移除了指定节点后的 JSON 文档。
+* @throws 当指定的节点不存在，或者尝试移除根节点时抛出错误。
+*/
+function remove(document, id) {
+	if (getRequiredNode(document, id).parent === null) throw new Error("Cannot remove the root node.");
+	const nextRaw = cloneJsonValue(document.raw);
+	const nextIdentityTree = cloneIdentityTree(getDocumentIdentityTree(document));
+	const location = findRequiredLocation(nextRaw, nextIdentityTree, id);
+	if (location.parentValue === null || location.parentIdentity === null) throw new Error("Cannot remove the root node.");
+	removeChild(location.parentValue, location.parentIdentity, location.key);
+	return rebuildDocument(document, nextRaw, nextIdentityTree);
+}
+/**
+* 重命名 JSON 文档中指定对象子节点的键名。
+* @param document 当前的 JSON 文档对象。
+* @param id 需要重命名键的节点的唯一标识符 (JsonNodeId)。
+* @param nextKey 新的键名。
+* @returns 返回一个新的重命名键后的 JSON 文档。
+* @throws 当目标节点不是对象子节点，或者新键名已存在，或键名为空时抛出错误。
+*/
+function renameKey(document, id, nextKey) {
+	const node = getRequiredNode(document, id);
+	if (getRequiredParent(document, id).type !== "object") throw new TypeError("Only object children can be renamed.");
+	if (!node.key) throw new Error("Target node does not have a key.");
+	if (!nextKey) throw new Error("Key must not be empty.");
+	const nextRaw = cloneJsonValue(document.raw);
+	const nextIdentityTree = cloneIdentityTree(getDocumentIdentityTree(document));
+	const location = findRequiredLocation(nextRaw, nextIdentityTree, id);
+	if (location.parentValue === null || location.parentIdentity === null) throw new Error("Cannot rename the root node.");
+	if (typeof location.key !== "string") throw new TypeError("Array items cannot be renamed.");
+	renameObjectChild(location.parentValue, location.parentIdentity, location.key, nextKey);
+	return rebuildDocument(document, nextRaw, nextIdentityTree);
+}
+/**
+* 将 JSON 文档中的指定节点移动到另一个父节点下。
+* @param document 当前的 JSON 文档对象。
+* @param id 需要移动的节点的唯一标识符 (JsonNodeId)。
+* @param parentId 目标父节点的唯一标识符 (JsonNodeId)。
+* @param options 移动时的额外选项，如移动到对象中的新键名，或移动到数组中的目标索引。
+* @returns 返回一个新的包含移动节点后的 JSON 文档。
+* @throws 当目标父节点不是对象或数组，尝试移动根节点，或者尝试将节点移动到其自身的子代中时抛出错误。
+*/
+function move(document, id, parentId, options = {}) {
+	const node = getRequiredNode(document, id);
+	const targetParent = getRequiredNode(document, parentId);
+	if (node.parent === null) throw new Error("Cannot move the root node.");
+	if (targetParent.type !== "object" && targetParent.type !== "array") throw new TypeError("Move target must be an object or array node.");
+	if (isSubPath(targetParent.path, node.path)) throw new Error("Cannot move a node into its own descendant.");
+	const nextRaw = cloneJsonValue(document.raw);
+	const nextIdentityTree = cloneIdentityTree(getDocumentIdentityTree(document));
+	const sourceLocation = findRequiredLocation(nextRaw, nextIdentityTree, id);
+	if (sourceLocation.parentValue === null || sourceLocation.parentIdentity === null) throw new Error("Cannot move the root node.");
+	const movedValue = cloneJsonValue(sourceLocation.value);
+	const movedIdentity = cloneIdentityTree(sourceLocation.identity);
+	removeChild(sourceLocation.parentValue, sourceLocation.parentIdentity, sourceLocation.key);
+	const targetLocation = findRequiredLocation(nextRaw, nextIdentityTree, parentId);
+	const targetValue = targetLocation.value;
+	if (targetParent.type === "object") {
+		if (!isJsonObject(targetValue)) throw new TypeError("Move target is not an object.");
+		const nextKey = options.key ?? (isArrayItemKey(node.key) ? void 0 : node.key);
+		if (!nextKey) throw new Error("Moving into an object requires a stable key.");
+		if (Object.hasOwn(targetValue, nextKey)) throw new Error(`Key "${nextKey}" already exists.`);
+		targetValue[nextKey] = movedValue;
+		ensureObjectIdentityChildren(targetLocation.identity)[nextKey] = movedIdentity;
+		return rebuildDocument(document, nextRaw, nextIdentityTree);
+	}
+	if (!Array.isArray(targetValue)) throw new TypeError("Move target is not an array.");
+	const index = normalizeArrayIndex(options.index ?? targetValue.length, true);
+	targetValue.splice(index, 0, movedValue);
+	ensureArrayIdentityChildren(targetLocation.identity).splice(index, 0, movedIdentity);
+	return rebuildDocument(document, nextRaw, nextIdentityTree);
+}
+function rebuildDocument(previous, nextRaw, nextIdentityTree) {
+	return createDocument(nextRaw, {
+		defaultExpandedRoot: false,
+		defaultExpandedAll: false,
+		expandedPaths: previous.state.expandedPaths,
+		identityTree: nextIdentityTree,
+		cloneRaw: false
+	});
+}
+function getRequiredNode(document, id) {
+	const node = getNode(document, id);
+	if (!node) throw new Error(`Node ${id} does not exist.`);
+	return node;
+}
+function getRequiredParent(document, id) {
+	const node = getRequiredNode(document, id);
+	if (node.parent === null) throw new Error("Root node does not have a parent.");
+	return getRequiredNode(document, node.parent);
+}
+function findRequiredLocation(raw, identity, targetId) {
+	const location = findLocationById(raw, identity, targetId);
+	if (!location) throw new Error(`Node ${targetId} does not exist.`);
+	return location;
+}
+function findLocationById(value, identity, targetId, parentValue = null, parentIdentity = null, key = null) {
+	if (identity.id === targetId) return {
+		value,
+		identity,
+		parentValue,
+		parentIdentity,
+		key
+	};
+	if (Array.isArray(value)) {
+		const children = ensureArrayIdentityChildren(identity);
+		for (const [index, item] of value.entries()) {
+			const childIdentity = children[index];
+			const found = findLocationById(item, childIdentity, targetId, value, identity, index);
+			if (found) return found;
+		}
+		return;
+	}
+	if (isJsonObject(value)) {
+		const children = ensureObjectIdentityChildren(identity);
+		for (const [childKey, item] of Object.entries(value)) {
+			const childIdentity = children[childKey];
+			const found = findLocationById(item, childIdentity, targetId, value, identity, childKey);
+			if (found) return found;
+		}
+	}
+}
+function assignChild(parentValue, key, value) {
+	if (typeof key === "number") {
+		if (!Array.isArray(parentValue)) throw new TypeError("Target parent is not an array.");
+		parentValue[key] = value;
+		return;
+	}
+	if (typeof key === "string") {
+		if (!isJsonObject(parentValue)) throw new TypeError("Target parent is not an object.");
+		parentValue[key] = value;
+		return;
+	}
+	throw new Error("Child key is missing.");
+}
+function replaceIdentityChild(parentIdentity, key, childIdentity) {
+	if (typeof key === "number") {
+		ensureArrayIdentityChildren(parentIdentity)[key] = childIdentity;
+		return;
+	}
+	if (typeof key === "string") {
+		ensureObjectIdentityChildren(parentIdentity)[key] = childIdentity;
+		return;
+	}
+	throw new Error("Child key is missing.");
+}
+function removeChild(parentValue, parentIdentity, key) {
+	if (typeof key === "number") {
+		if (!Array.isArray(parentValue)) throw new TypeError("Target parent is not an array.");
+		parentValue.splice(key, 1);
+		ensureArrayIdentityChildren(parentIdentity).splice(key, 1);
+		return;
+	}
+	if (typeof key === "string") {
+		if (!isJsonObject(parentValue)) throw new TypeError("Target parent is not an object.");
+		delete parentValue[key];
+		delete ensureObjectIdentityChildren(parentIdentity)[key];
+		return;
+	}
+	throw new Error("Child key is missing.");
+}
+function renameObjectChild(parentValue, parentIdentity, currentKey, nextKey) {
+	if (!isJsonObject(parentValue)) throw new TypeError("Target parent is not an object.");
+	if (currentKey !== nextKey && Object.hasOwn(parentValue, nextKey)) throw new Error(`Key "${nextKey}" already exists.`);
+	const objectEntries = Object.entries(parentValue);
+	const identityEntries = Object.entries(ensureObjectIdentityChildren(parentIdentity));
+	const nextObject = {};
+	const nextIdentityChildren = {};
+	for (const [key, value] of objectEntries) {
+		const outputKey = key === currentKey ? nextKey : key;
+		nextObject[outputKey] = value;
+	}
+	for (const [key, value] of identityEntries) {
+		const outputKey = key === currentKey ? nextKey : key;
+		nextIdentityChildren[outputKey] = value;
+	}
+	for (const key of Object.keys(parentValue)) delete parentValue[key];
+	for (const [key, value] of Object.entries(nextObject)) parentValue[key] = value;
+	parentIdentity.children = nextIdentityChildren;
+}
+function ensureObjectIdentityChildren(identity) {
+	if (identity.children === void 0) identity.children = {};
+	if (Array.isArray(identity.children)) throw new TypeError("Expected object identity children.");
+	return identity.children;
+}
+function ensureArrayIdentityChildren(identity) {
+	if (identity.children === void 0) identity.children = [];
+	if (!Array.isArray(identity.children)) throw new TypeError("Expected array identity children.");
+	return identity.children;
+}
+function normalizeArrayIndex(index, allowEnd) {
+	if (!Number.isInteger(index)) throw new TypeError("Array index must be an integer.");
+	if (index < 0) throw new RangeError("Array index must be greater than or equal to 0.");
+	return allowEnd ? index : Math.max(index, 0);
+}
+function createIdentityTree(value, existingId) {
+	if (Array.isArray(value)) return {
+		id: existingId ?? createJsonNodeId(),
+		children: value.map((item) => createIdentityTree(item))
+	};
+	if (isJsonObject(value)) {
+		const children = {};
+		for (const [key, item] of Object.entries(value)) children[key] = createIdentityTree(item);
+		return {
+			id: existingId ?? createJsonNodeId(),
+			children
+		};
+	}
+	return { id: existingId ?? createJsonNodeId() };
+}
+function isObjectInsertInput(input) {
+	return typeof input.key === "string";
+}
+function isArrayItemKey(key) {
+	return key !== void 0 && /^\d+$/.test(key);
+}
+function isSubPath(candidate, parentPath) {
+	if (!parentPath) return candidate.length > 0;
+	return candidate === parentPath || candidate.startsWith(`${parentPath}.`) || candidate.startsWith(`${parentPath}[`);
+}
+function cloneJsonValue(value) {
+	if (Array.isArray(value)) return value.map((item) => cloneJsonValue(item));
+	if (isJsonObject(value)) {
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = cloneJsonValue(item);
+		return result;
+	}
+	return value;
+}
+function cloneIdentityTree(identity) {
+	if (Array.isArray(identity.children)) return {
+		id: identity.id,
+		children: identity.children.map((child) => cloneIdentityTree(child))
+	};
+	if (identity.children) {
+		const children = {};
+		for (const [key, child] of Object.entries(identity.children)) children[key] = cloneIdentityTree(child);
+		return {
+			id: identity.id,
+			children
+		};
+	}
+	return { id: identity.id };
+}
+//#endregion
+export { insert, move, remove, renameKey, updateValue };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@jsonup/operation",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Immutable JSON tree operations 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": {
+    "@jsonup/core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  }
+}