@visual-json/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +158 -0
  2. package/dist/index.d.mts +132 -0
  3. package/dist/index.d.ts +132 -0
  4. package/dist/index.js +827 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/index.mjs +775 -0
  7. package/dist/index.mjs.map +1 -0
  8. package/package.json +32 -0
package/README.md ADDED
@@ -0,0 +1,158 @@
1
+ # @visual-json/core
2
+
3
+ Headless core for [visual-json](https://github.com/vercel-labs/visual-json) — the visual JSON editor. Schema-aware, embeddable, extensible.
4
+
5
+ This package is framework-agnostic — it provides the data layer without any UI dependencies.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @visual-json/core
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { fromJson, toJson, setValue, addProperty } from "@visual-json/core";
17
+
18
+ // Convert a JSON value into an editable tree
19
+ const tree = fromJson({ name: "my-app", version: "1.0.0" });
20
+
21
+ // Mutate immutably — returns a new tree with structural sharing
22
+ const updated = setValue(tree, tree.root.children[0].id, "new-app");
23
+
24
+ // Convert back to plain JSON
25
+ const json = toJson(updated.root);
26
+ ```
27
+
28
+ ## API
29
+
30
+ ### Tree
31
+
32
+ <table>
33
+ <thead>
34
+ <tr>
35
+ <th>Export</th>
36
+ <th>Description</th>
37
+ </tr>
38
+ </thead>
39
+ <tbody>
40
+ <tr>
41
+ <td><code>fromJson(value)</code></td>
42
+ <td>Parse a <code>JsonValue</code> into a <code>TreeState</code></td>
43
+ </tr>
44
+ <tr>
45
+ <td><code>toJson(node)</code></td>
46
+ <td>Serialize a <code>TreeNode</code> back to a <code>JsonValue</code></td>
47
+ </tr>
48
+ <tr>
49
+ <td><code>findNode(state, id)</code></td>
50
+ <td>Look up a node by ID</td>
51
+ </tr>
52
+ <tr>
53
+ <td><code>findNodeByPath(state, path)</code></td>
54
+ <td>Look up a node by JSON path</td>
55
+ </tr>
56
+ </tbody>
57
+ </table>
58
+
59
+ ### Operations
60
+
61
+ All operations return a new `TreeState` with structural sharing.
62
+
63
+ <table>
64
+ <thead>
65
+ <tr>
66
+ <th>Export</th>
67
+ <th>Description</th>
68
+ </tr>
69
+ </thead>
70
+ <tbody>
71
+ <tr>
72
+ <td><code>setValue(state, nodeId, value)</code></td>
73
+ <td>Set a node's value</td>
74
+ </tr>
75
+ <tr>
76
+ <td><code>setKey(state, nodeId, newKey)</code></td>
77
+ <td>Rename an object key</td>
78
+ </tr>
79
+ <tr>
80
+ <td><code>addProperty(state, parentId, key, value)</code></td>
81
+ <td>Add a child to an object or array</td>
82
+ </tr>
83
+ <tr>
84
+ <td><code>removeNode(state, nodeId)</code></td>
85
+ <td>Remove a node</td>
86
+ </tr>
87
+ <tr>
88
+ <td><code>moveNode(state, nodeId, newParentId, index?)</code></td>
89
+ <td>Move a node to a new parent</td>
90
+ </tr>
91
+ <tr>
92
+ <td><code>reorderChildren(state, parentId, from, to)</code></td>
93
+ <td>Reorder children within a parent</td>
94
+ </tr>
95
+ <tr>
96
+ <td><code>changeType(state, nodeId, newType)</code></td>
97
+ <td>Convert a node to a different type</td>
98
+ </tr>
99
+ <tr>
100
+ <td><code>duplicateNode(state, nodeId)</code></td>
101
+ <td>Duplicate a node as a sibling</td>
102
+ </tr>
103
+ </tbody>
104
+ </table>
105
+
106
+ ### Schema
107
+
108
+ <table>
109
+ <thead>
110
+ <tr>
111
+ <th>Export</th>
112
+ <th>Description</th>
113
+ </tr>
114
+ </thead>
115
+ <tbody>
116
+ <tr>
117
+ <td><code>resolveSchema(value, filename)</code></td>
118
+ <td>Auto-detect and fetch a JSON Schema for a file</td>
119
+ </tr>
120
+ <tr>
121
+ <td><code>getPropertySchema(schema, path)</code></td>
122
+ <td>Get the schema for a specific path</td>
123
+ </tr>
124
+ <tr>
125
+ <td><code>validateNode(node, schema)</code></td>
126
+ <td>Validate a node against a schema</td>
127
+ </tr>
128
+ </tbody>
129
+ </table>
130
+
131
+ ### Search & Diff
132
+
133
+ <table>
134
+ <thead>
135
+ <tr>
136
+ <th>Export</th>
137
+ <th>Description</th>
138
+ </tr>
139
+ </thead>
140
+ <tbody>
141
+ <tr>
142
+ <td><code>searchNodes(state, query)</code></td>
143
+ <td>Full-text search across keys and values</td>
144
+ </tr>
145
+ <tr>
146
+ <td><code>computeDiff(a, b)</code></td>
147
+ <td>Compute a structural diff between two JSON values</td>
148
+ </tr>
149
+ <tr>
150
+ <td><code>History</code></td>
151
+ <td>Undo/redo stack for <code>TreeState</code></td>
152
+ </tr>
153
+ </tbody>
154
+ </table>
155
+
156
+ ## License
157
+
158
+ Apache-2.0
package/dist/index.d.mts ADDED
@@ -0,0 +1,132 @@
1
+ type JsonPrimitive = string | number | boolean | null;
2
+ type JsonArray = JsonValue[];
3
+ type JsonObject = {
4
+ [key: string]: JsonValue;
5
+ };
6
+ type JsonValue = JsonPrimitive | JsonArray | JsonObject;
7
+ type NodeType = "string" | "number" | "boolean" | "null" | "object" | "array";
8
+ interface TreeNode {
9
+ id: string;
10
+ key: string;
11
+ path: string;
12
+ type: NodeType;
13
+ value: JsonPrimitive | undefined;
14
+ children: TreeNode[];
15
+ parentId: string | null;
16
+ }
17
+ interface TreeState {
18
+ root: TreeNode;
19
+ nodesById: Map<string, TreeNode>;
20
+ }
21
+ interface JsonSchemaProperty {
22
+ type?: string | string[];
23
+ description?: string;
24
+ enum?: JsonValue[];
25
+ default?: JsonValue;
26
+ const?: JsonValue;
27
+ properties?: Record<string, JsonSchemaProperty>;
28
+ items?: JsonSchemaProperty | JsonSchemaProperty[];
29
+ additionalItems?: JsonSchemaProperty | boolean;
30
+ additionalProperties?: JsonSchemaProperty | boolean;
31
+ patternProperties?: Record<string, JsonSchemaProperty>;
32
+ required?: string[];
33
+ $ref?: string;
34
+ allOf?: JsonSchemaProperty[];
35
+ anyOf?: JsonSchemaProperty[];
36
+ oneOf?: JsonSchemaProperty[];
37
+ not?: JsonSchemaProperty;
38
+ if?: JsonSchemaProperty;
39
+ then?: JsonSchemaProperty;
40
+ else?: JsonSchemaProperty;
41
+ definitions?: Record<string, JsonSchemaProperty>;
42
+ $defs?: Record<string, JsonSchemaProperty>;
43
+ minimum?: number;
44
+ maximum?: number;
45
+ exclusiveMinimum?: number | boolean;
46
+ exclusiveMaximum?: number | boolean;
47
+ multipleOf?: number;
48
+ minLength?: number;
49
+ maxLength?: number;
50
+ pattern?: string;
51
+ format?: string;
52
+ minItems?: number;
53
+ maxItems?: number;
54
+ uniqueItems?: boolean;
55
+ minProperties?: number;
56
+ maxProperties?: number;
57
+ deprecated?: boolean;
58
+ readOnly?: boolean;
59
+ writeOnly?: boolean;
60
+ examples?: JsonValue[];
61
+ title?: string;
62
+ }
63
+ interface JsonSchema extends JsonSchemaProperty {
64
+ $schema?: string;
65
+ }
66
+
67
+ declare function generateId(): string;
68
+ declare function resetIdCounter(): void;
69
+ declare function getNodeType(value: JsonValue): NodeType;
70
+ declare function buildSubtree(key: string, value: JsonValue, parentPath: string, parentId: string | null, nodesById: Map<string, TreeNode>): TreeNode;
71
+ declare function fromJson(value: JsonValue): TreeState;
72
+ declare function toJson(node: TreeNode): JsonValue;
73
+ declare function findNode(state: TreeState, nodeId: string): TreeNode | undefined;
74
+ declare function findNodeByPath(state: TreeState, path: string): TreeNode | undefined;
75
+
76
+ declare function setValue(state: TreeState, nodeId: string, value: JsonValue): TreeState;
77
+ declare function setKey(state: TreeState, nodeId: string, newKey: string): TreeState;
78
+ declare function addProperty(state: TreeState, parentId: string, key: string, value: JsonValue): TreeState;
79
+ declare function removeNode(state: TreeState, nodeId: string): TreeState;
80
+ declare function moveNode(state: TreeState, nodeId: string, newParentId: string, index?: number): TreeState;
81
+ declare function reorderChildren(state: TreeState, parentId: string, fromIndex: number, toIndex: number): TreeState;
82
+ declare function changeType(state: TreeState, nodeId: string, newType: NodeType): TreeState;
83
+ declare function duplicateNode(state: TreeState, nodeId: string): TreeState;
84
+
85
+ declare class History {
86
+ private stack;
87
+ private cursor;
88
+ push(state: TreeState): void;
89
+ undo(): TreeState | null;
90
+ redo(): TreeState | null;
91
+ get canUndo(): boolean;
92
+ get canRedo(): boolean;
93
+ get current(): TreeState | null;
94
+ }
95
+
96
+ declare function resolveSchema(json: JsonValue, filename?: string): Promise<JsonSchema | null>;
97
+ /**
98
+ * Resolve `$ref` pointers and merge `allOf` within a schema.
99
+ * `visited` tracks refs to prevent infinite cycles.
100
+ */
101
+ declare function resolveRef(prop: JsonSchemaProperty, root: JsonSchemaProperty, visited?: Set<string>): JsonSchemaProperty;
102
+ declare function getPropertySchema(schema: JsonSchema | JsonSchemaProperty, path: string, rootSchema?: JsonSchemaProperty): JsonSchemaProperty | undefined;
103
+ declare function clearSchemaCache(): void;
104
+
105
+ interface ValidationResult {
106
+ valid: boolean;
107
+ errors: string[];
108
+ }
109
+ declare function validateNode(node: TreeNode, schema: JsonSchemaProperty | undefined): ValidationResult;
110
+
111
+ interface SearchMatch {
112
+ nodeId: string;
113
+ field: "key" | "value";
114
+ }
115
+ declare function searchNodes(tree: TreeState, query: string): SearchMatch[];
116
+ /**
117
+ * Collect all ancestor node IDs for each matched node so the tree
118
+ * can auto-expand paths to search results.
119
+ */
120
+ declare function getAncestorIds(tree: TreeState, nodeIds: string[]): Set<string>;
121
+
122
+ type DiffType = "added" | "removed" | "changed";
123
+ interface DiffEntry {
124
+ path: string;
125
+ type: DiffType;
126
+ oldValue?: JsonValue;
127
+ newValue?: JsonValue;
128
+ }
129
+ declare function computeDiff(original: JsonValue, current: JsonValue, path?: string): DiffEntry[];
130
+ declare function getDiffPaths(entries: DiffEntry[]): Map<string, DiffType>;
131
+
132
+ export { type DiffEntry, type DiffType, History, type JsonArray, type JsonObject, type JsonPrimitive, type JsonSchema, type JsonSchemaProperty, type JsonValue, type NodeType, type SearchMatch, type TreeNode, type TreeState, type ValidationResult, addProperty, buildSubtree, changeType, clearSchemaCache, computeDiff, duplicateNode, findNode, findNodeByPath, fromJson, generateId, getAncestorIds, getDiffPaths, getNodeType, getPropertySchema, moveNode, removeNode, reorderChildren, resetIdCounter, resolveRef, resolveSchema, searchNodes, setKey, setValue, toJson, validateNode };
package/dist/index.d.ts ADDED
@@ -0,0 +1,132 @@
1
+ type JsonPrimitive = string | number | boolean | null;
2
+ type JsonArray = JsonValue[];
3
+ type JsonObject = {
4
+ [key: string]: JsonValue;
5
+ };
6
+ type JsonValue = JsonPrimitive | JsonArray | JsonObject;
7
+ type NodeType = "string" | "number" | "boolean" | "null" | "object" | "array";
8
+ interface TreeNode {
9
+ id: string;
10
+ key: string;
11
+ path: string;
12
+ type: NodeType;
13
+ value: JsonPrimitive | undefined;
14
+ children: TreeNode[];
15
+ parentId: string | null;
16
+ }
17
+ interface TreeState {
18
+ root: TreeNode;
19
+ nodesById: Map<string, TreeNode>;
20
+ }
21
+ interface JsonSchemaProperty {
22
+ type?: string | string[];
23
+ description?: string;
24
+ enum?: JsonValue[];
25
+ default?: JsonValue;
26
+ const?: JsonValue;
27
+ properties?: Record<string, JsonSchemaProperty>;
28
+ items?: JsonSchemaProperty | JsonSchemaProperty[];
29
+ additionalItems?: JsonSchemaProperty | boolean;
30
+ additionalProperties?: JsonSchemaProperty | boolean;
31
+ patternProperties?: Record<string, JsonSchemaProperty>;
32
+ required?: string[];
33
+ $ref?: string;
34
+ allOf?: JsonSchemaProperty[];
35
+ anyOf?: JsonSchemaProperty[];
36
+ oneOf?: JsonSchemaProperty[];
37
+ not?: JsonSchemaProperty;
38
+ if?: JsonSchemaProperty;
39
+ then?: JsonSchemaProperty;
40
+ else?: JsonSchemaProperty;
41
+ definitions?: Record<string, JsonSchemaProperty>;
42
+ $defs?: Record<string, JsonSchemaProperty>;
43
+ minimum?: number;
44
+ maximum?: number;
45
+ exclusiveMinimum?: number | boolean;
46
+ exclusiveMaximum?: number | boolean;
47
+ multipleOf?: number;
48
+ minLength?: number;
49
+ maxLength?: number;
50
+ pattern?: string;
51
+ format?: string;
52
+ minItems?: number;
53
+ maxItems?: number;
54
+ uniqueItems?: boolean;
55
+ minProperties?: number;
56
+ maxProperties?: number;
57
+ deprecated?: boolean;
58
+ readOnly?: boolean;
59
+ writeOnly?: boolean;
60
+ examples?: JsonValue[];
61
+ title?: string;
62
+ }
63
+ interface JsonSchema extends JsonSchemaProperty {
64
+ $schema?: string;
65
+ }
66
+
67
+ declare function generateId(): string;
68
+ declare function resetIdCounter(): void;
69
+ declare function getNodeType(value: JsonValue): NodeType;
70
+ declare function buildSubtree(key: string, value: JsonValue, parentPath: string, parentId: string | null, nodesById: Map<string, TreeNode>): TreeNode;
71
+ declare function fromJson(value: JsonValue): TreeState;
72
+ declare function toJson(node: TreeNode): JsonValue;
73
+ declare function findNode(state: TreeState, nodeId: string): TreeNode | undefined;
74
+ declare function findNodeByPath(state: TreeState, path: string): TreeNode | undefined;
75
+
76
+ declare function setValue(state: TreeState, nodeId: string, value: JsonValue): TreeState;
77
+ declare function setKey(state: TreeState, nodeId: string, newKey: string): TreeState;
78
+ declare function addProperty(state: TreeState, parentId: string, key: string, value: JsonValue): TreeState;
79
+ declare function removeNode(state: TreeState, nodeId: string): TreeState;
80
+ declare function moveNode(state: TreeState, nodeId: string, newParentId: string, index?: number): TreeState;
81
+ declare function reorderChildren(state: TreeState, parentId: string, fromIndex: number, toIndex: number): TreeState;
82
+ declare function changeType(state: TreeState, nodeId: string, newType: NodeType): TreeState;
83
+ declare function duplicateNode(state: TreeState, nodeId: string): TreeState;
84
+
85
+ declare class History {
86
+ private stack;
87
+ private cursor;
88
+ push(state: TreeState): void;
89
+ undo(): TreeState | null;
90
+ redo(): TreeState | null;
91
+ get canUndo(): boolean;
92
+ get canRedo(): boolean;
93
+ get current(): TreeState | null;
94
+ }
95
+
96
+ declare function resolveSchema(json: JsonValue, filename?: string): Promise<JsonSchema | null>;
97
+ /**
98
+ * Resolve `$ref` pointers and merge `allOf` within a schema.
99
+ * `visited` tracks refs to prevent infinite cycles.
100
+ */
101
+ declare function resolveRef(prop: JsonSchemaProperty, root: JsonSchemaProperty, visited?: Set<string>): JsonSchemaProperty;
102
+ declare function getPropertySchema(schema: JsonSchema | JsonSchemaProperty, path: string, rootSchema?: JsonSchemaProperty): JsonSchemaProperty | undefined;
103
+ declare function clearSchemaCache(): void;
104
+
105
+ interface ValidationResult {
106
+ valid: boolean;
107
+ errors: string[];
108
+ }
109
+ declare function validateNode(node: TreeNode, schema: JsonSchemaProperty | undefined): ValidationResult;
110
+
111
+ interface SearchMatch {
112
+ nodeId: string;
113
+ field: "key" | "value";
114
+ }
115
+ declare function searchNodes(tree: TreeState, query: string): SearchMatch[];
116
+ /**
117
+ * Collect all ancestor node IDs for each matched node so the tree
118
+ * can auto-expand paths to search results.
119
+ */
120
+ declare function getAncestorIds(tree: TreeState, nodeIds: string[]): Set<string>;
121
+
122
+ type DiffType = "added" | "removed" | "changed";
123
+ interface DiffEntry {
124
+ path: string;
125
+ type: DiffType;
126
+ oldValue?: JsonValue;
127
+ newValue?: JsonValue;
128
+ }
129
+ declare function computeDiff(original: JsonValue, current: JsonValue, path?: string): DiffEntry[];
130
+ declare function getDiffPaths(entries: DiffEntry[]): Map<string, DiffType>;
131
+
132
+ export { type DiffEntry, type DiffType, History, type JsonArray, type JsonObject, type JsonPrimitive, type JsonSchema, type JsonSchemaProperty, type JsonValue, type NodeType, type SearchMatch, type TreeNode, type TreeState, type ValidationResult, addProperty, buildSubtree, changeType, clearSchemaCache, computeDiff, duplicateNode, findNode, findNodeByPath, fromJson, generateId, getAncestorIds, getDiffPaths, getNodeType, getPropertySchema, moveNode, removeNode, reorderChildren, resetIdCounter, resolveRef, resolveSchema, searchNodes, setKey, setValue, toJson, validateNode };