@loro-dev/json-patch 0.0.0-stage → 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.
- package/README.md +314 -2
- package/dist/diff.cjs +1666 -0
- package/dist/diff.d.cts +126 -0
- package/dist/diff.d.ts +126 -0
- package/dist/diff.js +1463 -0
- package/dist/index.cjs +1124 -0
- package/dist/index.d.cts +74 -0
- package/dist/index.d.ts +74 -0
- package/dist/index.js +1097 -0
- package/dist/loro.cjs +2722 -0
- package/dist/loro.d.cts +115 -0
- package/dist/loro.d.ts +115 -0
- package/dist/loro.js +2710 -0
- package/package.json +70 -3
package/README.md
CHANGED
|
@@ -1,3 +1,315 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@loro-dev/json-patch`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Deterministic JSON Patch state engine (`diff`, `apply`, `compact`), dual binary MessagePack / canonical JSON wire codecs, and optional `LoroDoc` bridge (`@loro-dev/json-patch/loro`) for **Loro Repo** (`0.1.0`).
|
|
4
|
+
|
|
5
|
+
> **Companion packages**
|
|
6
|
+
> - [`@loro-dev/loro-repo-client`](https://www.npmjs.com/package/@loro-dev/loro-repo-client) — TypeScript IPC client SDK exchanging `JsonPatch` / `JsonValue` with `@loro-dev/loro-repo-engine`.
|
|
7
|
+
> - [`@loro-dev/loro-repo-engine`](https://www.npmjs.com/package/@loro-dev/loro-repo-engine) — Prebuilt Rust Node-API engine & CLI.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
1. [Entrypoints & Installation](#1-entrypoints--installation)
|
|
14
|
+
2. [Lossless `JsonValue` Data Model & All 5 `JsonOp` Variants](#2-lossless-jsonvalue-data-model--all-5-jsonop-variants)
|
|
15
|
+
3. [Applying Patches with Structural Sharing (`apply` & `applyOp`)](#3-applying-patches-with-structural-sharing-apply--applyop)
|
|
16
|
+
4. [Diffing (`diff`), Keyed List LIS `move`s (`keyExtractors`) & Tree Diffs (`treeSpecs`)](#4-diffing-diff-keyed-list-lis-moves-keyextractors--tree-diffs-treespecs)
|
|
17
|
+
5. [Compacting Patch Streams (`compact`)](#5-compacting-patch-streams-compact)
|
|
18
|
+
6. [Wire Codecs (`encodeJson` / `decodeJson` & `encodeMsgpack` / `decodeMsgpack`)](#6-wire-codecs-encodejson--decodejson--encodemsgpack--decodemsgpack)
|
|
19
|
+
7. [Loro CRDT Bridge (`@loro-dev/json-patch/loro`)](#7-loro-crdt-bridge-loro-devjson-patchloro)
|
|
20
|
+
8. [Error Classes & Diagnostic Kinds (`ApplyError`, `DecodeError`, `LoroApplyError`)](#8-error-classes--diagnostic-kinds-applyerror-decodeerror-loroapplyerror)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. Entrypoints & Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pnpm add @loro-dev/json-patch
|
|
28
|
+
# Optional — ONLY if you call `@loro-dev/json-patch/loro` directly on `LoroDoc` instances:
|
|
29
|
+
pnpm add loro-crdt
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
| Import Path | Runtime Requirements | Peer / Deps | Purpose |
|
|
33
|
+
| :--- | :--- | :--- | :--- |
|
|
34
|
+
| **`@loro-dev/json-patch`** | Any browser, Electron Renderer, Web Worker, Node.js | `@msgpack/msgpack` (**zero WASM, zero `node:*`, zero `Buffer`**) | Pure-JS `diff`, `apply`, `applyOp`, `compact`, `encodeJson`/`decodeJson`, `encodeMsgpack`/`decodeMsgpack`, `valuesEqual`, `numbersEqual`. |
|
|
35
|
+
| **`@loro-dev/json-patch/loro`** | Node.js / bundlers with `loro-crdt` WASM | Optional peer `loro-crdt >=1.17.0` | `LoroSchema`, `containerKind`, `LoroValueKind`, `applyJsonPatchToLoro`, `applyJsonPatchAt`, `loroToJson`, `diffLoroJson`. |
|
|
36
|
+
|
|
37
|
+
> **Do Electron Renderers or Workers using `@loro-dev/loro-repo-client` need `loro-crdt`?**
|
|
38
|
+
> **No.** `@loro-dev/loro-repo-engine` executes all Loro CRDT operations natively in Rust. Frontends only import `@loro-dev/json-patch` (zero WASM) + `@loro-dev/loro-repo-client/browser`.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 2. Lossless `JsonValue` Data Model & All 5 `JsonOp` Variants
|
|
43
|
+
|
|
44
|
+
### `JsonValue` Rules
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
export type JsonValue =
|
|
48
|
+
| null
|
|
49
|
+
| boolean
|
|
50
|
+
| number
|
|
51
|
+
| bigint
|
|
52
|
+
| string
|
|
53
|
+
| Uint8Array
|
|
54
|
+
| readonly JsonValue[]
|
|
55
|
+
| { readonly [key: string]: JsonValue };
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Strict validation rules shared bit-for-bit with Rust `loro-json-patch`:
|
|
59
|
+
- **Finite numbers only**: `NaN`, `Infinity`, and `-Infinity` are forbidden (`InvalidValue` / `NonFiniteFloat`). `-0` is normalized to `+0`.
|
|
60
|
+
- **Exact 64-bit `bigint`**: Supported anywhere in `[-(2n**63n), (2n**64n) - 1n]` (`i64::MIN..=u64::MAX`), preserving integers outside `Number.MIN_SAFE_INTEGER..Number.MAX_SAFE_INTEGER`.
|
|
61
|
+
- **Valid UTF-16 strings**: Unpaired UTF-16 surrogates (e.g. `"\ud800"`) are rejected (`InvalidValue`).
|
|
62
|
+
- **Binary blobs (`Uint8Array`)**: First-class primitive leaf values (not plain objects or arrays).
|
|
63
|
+
- **Plain objects only**: Class instances, `Date`, `Map`, `Set`, and `undefined` values are rejected. Safe against `__proto__` pollution (`setOwnProp`).
|
|
64
|
+
|
|
65
|
+
### All 5 `JsonOp` Operations (`path: readonly (string | number)[]`)
|
|
66
|
+
|
|
67
|
+
Every path segment is either an object property name (`string`) or a non-negative integer array index (`number`). `[]` targets the document root.
|
|
68
|
+
|
|
69
|
+
| Op | Exact Type Shape | Exact Semantics |
|
|
70
|
+
| :--- | :--- | :--- |
|
|
71
|
+
| **`set`** | `{ op: "set", path, value }` | Sets object key, replaces existing array element (`0 <= idx < len`), or replaces root (`path: []`). Intermediate keys along `path` must already exist (`MissingPath` otherwise). |
|
|
72
|
+
| **`unset`** | `{ op: "unset", path }` | Removes an object property (`path` must be non-empty and end with a string key; missing leaf key is a no-op, missing parent throws `MissingPath`). |
|
|
73
|
+
| **`arr_splice`** | `{ op: "arr_splice", path, at, del, items }` | Removes `del` elements starting at index `at` (`0 <= at`, `at + del <= arr.length`) in the target array and inserts `items` in place. |
|
|
74
|
+
| **`move`** | `{ op: "move", from, to }` | Atomically removes the value at `from` and inserts it at `to`. For array moves, `to` is indexed **after removal at `from`** (`takeAt`, then `insertAt`). Cross-container object <-> array moves are also supported in pure JS `apply`. |
|
|
75
|
+
| **`str_splice`** | `{ op: "str_splice", path, at, del, ins }` | Splices text at `path` using **UTF-16 code-unit offsets** (`at`, `del`), inserting `ins`. Rejects splitting a surrogate pair (`InvalidUtf16Boundary`)! |
|
|
76
|
+
|
|
77
|
+
#### UTF-16 Offset Example for `str_splice`
|
|
78
|
+
|
|
79
|
+
Both JavaScript strings and Loro's wire/patch contract measure `str_splice.at` and `str_splice.del` in **UTF-16 code units** (matching `String.prototype.length` / `.slice()`):
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// "Hi 🚀!" has length 6 in UTF-16 code units: "H"(0) "i"(1) " "(2) "🚀"(3 and 4) "!"(5)
|
|
83
|
+
const s = "Hi 🚀!";
|
|
84
|
+
// Splicing at `at: 4` would split the rocket emoji surrogate pair -> throws ApplyError("InvalidUtf16Boundary")!
|
|
85
|
+
// Valid splice replacing "🚀" with "✨":
|
|
86
|
+
const next = apply({ msg: s }, [
|
|
87
|
+
{ op: "str_splice", path: ["msg"], at: 3, del: 2, ins: "✨" },
|
|
88
|
+
]);
|
|
89
|
+
// next => { msg: "Hi ✨!" }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 3. Applying Patches with Structural Sharing (`apply` & `applyOp`)
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import { apply, applyOp } from "@loro-dev/json-patch";
|
|
98
|
+
|
|
99
|
+
const doc0 = {
|
|
100
|
+
header: { title: "Draft" },
|
|
101
|
+
unchanged: { bigTree: [1, 2, 3] },
|
|
102
|
+
};
|
|
103
|
+
|
|
104
|
+
const doc1 = apply(doc0, [
|
|
105
|
+
{ op: "set", path: ["header", "title"], value: "Final" },
|
|
106
|
+
]);
|
|
107
|
+
|
|
108
|
+
// Copy-on-write guarantees:
|
|
109
|
+
console.log(doc0.header.title); // "Draft" (input never mutated)
|
|
110
|
+
console.log(doc1.unchanged === doc0.unchanged); // true! Untouched subtrees keep `===` identity for React.memo!
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- **Atomic batch ownership**: `apply(state, patch)` allocates each modified ancestor container at most once across a multi-op patch, while preserving `===` identity on untouched subtrees and moved subtrees.
|
|
114
|
+
- **No-op elision**: Setting a path to a deeply equal value (`valuesEqual`) returns the original reference unchanged.
|
|
115
|
+
|
|
116
|
+
Structural sharing does not imply total `O(ops × depth)` runtime: copying wide containers, shifting array elements, scanning strings, validating inserted values, and checking deep equality also cost time. Benchmark representative document sizes and edit patterns; retaining references to many old snapshots also retains their shared subtrees in memory.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 4. Diffing (`diff`), Keyed List LIS `move`s (`keyExtractors`) & Tree Diffs (`treeSpecs`)
|
|
121
|
+
|
|
122
|
+
### Standard Diffing (`diff(before, after)`)
|
|
123
|
+
|
|
124
|
+
- Strings emit compact `str_splice` when the shared UTF-16 prefix/suffix saves MessagePack bytes compared to `set`.
|
|
125
|
+
- Unkeyed arrays find common prefix/suffix, align matching middle windows, and emit minimal `arr_splice` ops (or element-wise nested diffs when equal-length windows share no identical items).
|
|
126
|
+
|
|
127
|
+
`diff()` is schema-independent: its output transforms plain JSON with `apply()`, but is not guaranteed to be accepted by `RepoClient.applyDocPatch` or strict `applyJsonPatchToLoro`. Those APIs also enforce container types. Use `set` for atomic scalar strings and whole atomic objects, and reserve `str_splice` for `LoroText` fields. Key extractors control array identity; they do not make string diffs schema-aware.
|
|
128
|
+
|
|
129
|
+
### Keyed List Diffing with Longest Increasing Subsequence `move`s (`keyExtractors`)
|
|
130
|
+
|
|
131
|
+
When diffing ordered lists of objects carrying a stable identity field (such as `"id"` or Loro's synthetic `"$cid"` on `LODY_SESSION_DOC_SCHEMA`'s `mq` queue), pass `options.keyExtractors` so `diff` emits minimal `O(K log K)` LIS **`move`** operations plus nested field diffs instead of destructive `arr_splice` replacements:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
import { ANY_REST_SEG, ANY_SEG, diff } from "@loro-dev/json-patch";
|
|
135
|
+
|
|
136
|
+
const oldState = {
|
|
137
|
+
mq: [
|
|
138
|
+
{ $cid: "cid:1", task: "alpha", done: false },
|
|
139
|
+
{ $cid: "cid:2", task: "beta", done: false },
|
|
140
|
+
{ $cid: "cid:3", task: "gamma", done: false },
|
|
141
|
+
],
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
const newState = {
|
|
145
|
+
mq: [
|
|
146
|
+
{ $cid: "cid:3", task: "gamma (edited)", done: true },
|
|
147
|
+
{ $cid: "cid:1", task: "alpha", done: false },
|
|
148
|
+
{ $cid: "cid:2", task: "beta", done: false },
|
|
149
|
+
],
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
const ops = diff(oldState, newState, {
|
|
153
|
+
keyExtractors: [
|
|
154
|
+
// Accepts a property name string (`"$cid"`, `"id"`) OR `(item) => string | undefined`:
|
|
155
|
+
{ path: ["mq"], extractor: "$cid" },
|
|
156
|
+
// Supports glob patterns too:
|
|
157
|
+
{ path: ["workspaces", ANY_SEG, "tabs"], extractor: (item) => (item as { id?: string }).id },
|
|
158
|
+
],
|
|
159
|
+
});
|
|
160
|
+
// Produces:
|
|
161
|
+
// [
|
|
162
|
+
// { op: "move", from: ["mq", 2], to: ["mq", 0] },
|
|
163
|
+
// { op: "set", path: ["mq", 0, "done"], value: true },
|
|
164
|
+
// { op: "str_splice", path: ["mq", 0, "task"], at: 5, del: 0, ins: " (edited)" },
|
|
165
|
+
// ]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
> **Tip for `LoroMovableList` + `"$cid"`**: Sending `{ op: "move", ... }` plus field-level `set` ops preserves each item's `LoroMap` container identity (`$cid`), whereas replacing `["mq", 0]` wholesale would allocate a new `LoroMap`. If any array has duplicate or missing keys, `keyExtractors` safely falls back to `diffUnkeyedArray`.
|
|
169
|
+
|
|
170
|
+
The example's `str_splice` is valid for the plain JSON `oldState`. For Lody's persisted `mq[*].task` schema, send `{ op: "set", path: ["mq", 0, "task"], value: "gamma (edited)" }` instead, because `task` is an atomic string. Passing the generated splice unchanged to that room produces `invalid_patch`. Generate schema-aware writes directly, or normalize diffs against your schema while preserving operation order and index changes.
|
|
171
|
+
|
|
172
|
+
### Hierarchical Tree Diffing (`treeSpecs`)
|
|
173
|
+
|
|
174
|
+
For nested tree arrays supporting cross-parent reparenting and reordering:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
const ops = diff(oldTreeDoc, newTreeDoc, {
|
|
178
|
+
treeSpecs: [
|
|
179
|
+
{ rootPath: ["outline"], idField: "id", childrenField: "children" },
|
|
180
|
+
],
|
|
181
|
+
});
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Emits preorder parent-shell insertions, cross-branch `move` ops, dead subtree prunings, sibling LIS moves, and non-`childrenField` property diffs.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 5. Compacting Patch Streams (`compact`)
|
|
189
|
+
|
|
190
|
+
When batching many sequential edits before sending over IPC or flushing to React:
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
import { compact } from "@loro-dev/json-patch";
|
|
194
|
+
|
|
195
|
+
const raw = [
|
|
196
|
+
{ op: "set", path: ["draft", "text"], value: "Hi" },
|
|
197
|
+
{ op: "str_splice", path: ["draft", "text"], at: 2, del: 0, ins: " there" },
|
|
198
|
+
{ op: "str_splice", path: ["draft", "text"], at: 8, del: 0, ins: "!" },
|
|
199
|
+
{ op: "set", path: ["count"], value: 1 },
|
|
200
|
+
{ op: "set", path: ["count"], value: 2 },
|
|
201
|
+
];
|
|
202
|
+
|
|
203
|
+
const minimal = compact(raw);
|
|
204
|
+
// [
|
|
205
|
+
// { op: "set", path: ["draft", "text"], value: "Hi there!" },
|
|
206
|
+
// { op: "set", path: ["count"], value: 2 },
|
|
207
|
+
// ]
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Exact algebraic rules enforced in `O(M)`:
|
|
211
|
+
- Merges adjacent/overlapping `str_splice`s on the same untouched path.
|
|
212
|
+
- Folds `set` + `str_splice` / `arr_splice` on the same path into a single `set`.
|
|
213
|
+
- Folds consecutive `set` / `unset` pairs on the same path.
|
|
214
|
+
- Folds root `set([])` + subsequent ops into a single root `set([])` snapshot (stopping cleanly at any non-applicable barrier).
|
|
215
|
+
- Preserves ordering across conflicting ancestor/descendant touches and `move` barriers.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## 6. Wire Codecs (`encodeJson` / `decodeJson` & `encodeMsgpack` / `decodeMsgpack`)
|
|
220
|
+
|
|
221
|
+
### 1. Canonical Lossless JSON Codec (`encodeJson`, `decodeJson`)
|
|
222
|
+
|
|
223
|
+
Preserves `Uint8Array`, `bigint` (`i64..u64`), and exact object key escaping across standard `JSON.parse` boundaries:
|
|
224
|
+
|
|
225
|
+
- **`bytesMode: "tagged"` (default)**:
|
|
226
|
+
- Encodes `Uint8Array` as `{"$bytes":"<strict-rfc4648-base64>"}`.
|
|
227
|
+
- Escapes user objects whose *only* key is `"$bytes"` or `"$esc"` inside `{"$esc":{...}}` so user data never collides with binary tags.
|
|
228
|
+
- **`bytesMode: "reject"`**:
|
|
229
|
+
- Throws `DecodeError("BytesRejected")` if a `Uint8Array` is encountered during encoding.
|
|
230
|
+
- **BigInt fidelity**: Parsed integers inside `MIN_SAFE_INTEGER..MAX_SAFE_INTEGER` become `number`; larger integers in `i64::MIN..=u64::MAX` become exact `bigint`. Sorted object keys ensure deterministic output.
|
|
231
|
+
|
|
232
|
+
### 2. Compact Binary MessagePack Codec (`encodeMsgpack`, `decodeMsgpack`)
|
|
233
|
+
|
|
234
|
+
Encodes each op as a compact tuple (`[opCode, ...]` with sorted map keys and minimal integer widths, **zero custom MessagePack extensions**), bit-for-bit identical to Rust `loro-json-patch`:
|
|
235
|
+
|
|
236
|
+
| Op code | Op | Wire tuple |
|
|
237
|
+
| :--- | :--- | :--- |
|
|
238
|
+
| `1` | `set` | `[1, path, value]` |
|
|
239
|
+
| `2` | `unset` | `[2, path]` |
|
|
240
|
+
| `3` | `arr_splice` | `[3, path, at, del, items]` |
|
|
241
|
+
| `4` | `move` | `[4, from, to]` |
|
|
242
|
+
| `5` | `str_splice` | `[5, path, at, del, ins]` |
|
|
243
|
+
|
|
244
|
+
Also exports `encodeMsgpackValue(value)` / `decodeMsgpackValue(bytes)` for encoding single values. Native `bin` bytes decode to `Uint8Array`, 64-bit integers outside JS safe range decode to `bigint`, and any custom MessagePack extension (`0xc7..0xc9`, `0xd4..0xd8`) or trailing bytes throw `DecodeError`.
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 7. Loro CRDT Bridge (`@loro-dev/json-patch/loro`)
|
|
249
|
+
|
|
250
|
+
When working directly with in-memory `LoroDoc` instances (unit tests, raw snapshot inspection, offline fixtures), `@loro-dev/json-patch/loro` reproduces the Rust engine's exact schema and container semantics:
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
import { LoroDoc } from "loro-crdt";
|
|
254
|
+
import { ANY_SEG } from "@loro-dev/json-patch";
|
|
255
|
+
import {
|
|
256
|
+
LoroSchema,
|
|
257
|
+
LoroValueKind,
|
|
258
|
+
applyJsonPatchToLoro,
|
|
259
|
+
applyJsonPatchAt,
|
|
260
|
+
containerKind,
|
|
261
|
+
diffLoroJson,
|
|
262
|
+
loroToJson,
|
|
263
|
+
} from "@loro-dev/json-patch/loro";
|
|
264
|
+
|
|
265
|
+
const schema = new LoroSchema({
|
|
266
|
+
roots: { session: "Map", history: "List", mq: "MovableList" },
|
|
267
|
+
rules: [
|
|
268
|
+
{ pattern: ["history", ANY_SEG, "text"], kind: containerKind("Text") },
|
|
269
|
+
{ pattern: ["mq", ANY_SEG, "project"], kind: LoroValueKind },
|
|
270
|
+
],
|
|
271
|
+
defaultObject: containerKind("Map"),
|
|
272
|
+
defaultArray: containerKind("List"),
|
|
273
|
+
defaultString: LoroValueKind, // Scalar strings stay primitive LoroValue strings!
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
const doc = new LoroDoc();
|
|
277
|
+
const f0 = doc.frontiers();
|
|
278
|
+
|
|
279
|
+
const res = applyJsonPatchToLoro(
|
|
280
|
+
doc,
|
|
281
|
+
[
|
|
282
|
+
{ op: "set", path: ["session"], value: { id: "s1", status: "running" } },
|
|
283
|
+
{ op: "set", path: ["history"], value: [{ id: "m1", text: "Hi" }] },
|
|
284
|
+
{ op: "str_splice", path: ["history", 0, "text"], at: 2, del: 0, ins: "!" },
|
|
285
|
+
],
|
|
286
|
+
{ schema, mode: "strict" },
|
|
287
|
+
);
|
|
288
|
+
// res => { changed: true, createdTreeIds: [] }
|
|
289
|
+
|
|
290
|
+
doc.commit();
|
|
291
|
+
|
|
292
|
+
const snapshot = loroToJson(doc, schema);
|
|
293
|
+
// => { session: { id: "s1", status: "running" }, history: [{ id: "m1", text: "Hi!" }], mq: [] }
|
|
294
|
+
|
|
295
|
+
const deltaOps = diffLoroJson(doc, f0, doc.frontiers(), schema);
|
|
296
|
+
|
|
297
|
+
// Rebase a concurrent patch against an older `baseFrontiers`:
|
|
298
|
+
applyJsonPatchAt(doc, f0, [{ op: "set", path: ["session", "reviewed"], value: true }], { schema });
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### Schema & Helper Methods
|
|
302
|
+
|
|
303
|
+
- **`LoroSchema`**: Immutable builder methods `.root(name, containerType)`, `.rule(pattern, kind)`, `.withDefaultObject(kind)`, `.withDefaultArray(kind)`, `.withDefaultString(kind)`, plus `LoroSchema.discover(doc)`.
|
|
304
|
+
- **Container types**: `"Map" | "List" | "MovableList" | "Text" | "Tree" | "Counter"`.
|
|
305
|
+
- **Tree ID mapping**: When inserting items into a `"Tree"` container, `applyJsonPatchToLoro` returns `{ changed, createdTreeIds: [{ specifiedId?, assignedId }] }`.
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## 8. Error Classes & Diagnostic Kinds (`ApplyError`, `DecodeError`, `LoroApplyError`)
|
|
310
|
+
|
|
311
|
+
| Error Class | Fields | `kind` Union Values |
|
|
312
|
+
| :--- | :--- | :--- |
|
|
313
|
+
| **`ApplyError`** | `kind`, `opIndex` | `"InvalidPath" \| "MissingPath" \| "IndexOutOfBounds" \| "TypeMismatch" \| "InvalidUtf16Boundary" \| "InvalidValue"` |
|
|
314
|
+
| **`DecodeError`** | `kind`, `opCode?` | `"UnknownOp" \| "UnknownOpName" \| "InvalidFormat" \| "InvalidPath" \| "NonFiniteFloat" \| "UnsupportedExtension" \| "InvalidBase64" \| "BytesRejected" \| "Json" \| "MessagePack"` |
|
|
315
|
+
| **`LoroApplyError`** | `kind`, `opIndex?` | `"SchemaViolation" \| "Patch" \| "Value" \| "Loro" \| "PeerIdConflict"` |
|