@open-artifact/whiteboard-core 0.1.0 → 0.2.1
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/package.json +4 -3
- package/src/codec.d.ts +2 -4
- package/src/json.d.ts +2 -56
- package/src/json.js +2 -221
- package/src/sync/doc-hash.d.ts +1 -13
- package/src/sync/doc-hash.js +1 -67
- package/src/sync/engine.d.ts +1 -228
- package/src/sync/engine.js +1 -1091
- package/src/sync/index.d.ts +3 -1
- package/src/sync/index.js +3 -1
- package/src/sync/live-board.d.ts +2 -1
- package/src/sync/transport.d.ts +1 -88
- package/src/sync/transport.js +1 -35
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@open-artifact/whiteboard-core",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "The Whiteboard artifact model: element schema and normalization, the document codec, geometry, arrows, hand-drawn ink, history, view context and the live sync engine.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
"NOTICE"
|
|
17
17
|
],
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@open-artifact/
|
|
20
|
-
"@open-artifact/
|
|
19
|
+
"@open-artifact/live-store": "0.2.1",
|
|
20
|
+
"@open-artifact/protocol": "0.2.1",
|
|
21
|
+
"@open-artifact/wasm-wb-geom": "0.2.1"
|
|
21
22
|
},
|
|
22
23
|
"license": "Apache-2.0",
|
|
23
24
|
"author": {
|
package/src/codec.d.ts
CHANGED
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
* One document per element lets people edit different elements at once
|
|
14
14
|
* without conflicts; the order list lives in one small document.
|
|
15
15
|
*/
|
|
16
|
+
import type { DocumentMap, DocumentValue } from '@open-artifact/live-store/engine';
|
|
16
17
|
import { type Board, type BoardElement, type BoardInk, type ElementId, type StoredElement } from './schema.ts';
|
|
17
18
|
/** The meta document: title and drawing order. */
|
|
18
19
|
export declare const BOARD_META_PATH = "board/meta";
|
|
@@ -32,10 +33,7 @@ export declare const MAX_SYNC_RECORD_BYTES = 204800;
|
|
|
32
33
|
export declare const MAX_SYNC_RECORD_DEPTH = 8;
|
|
33
34
|
/** Largest whole board the page keeps syncing. */
|
|
34
35
|
export declare const MAX_SYNC_BOARD_BYTES = 2097152;
|
|
35
|
-
|
|
36
|
-
export type DocumentValue = Record<string, unknown>;
|
|
37
|
-
/** Documents by path. */
|
|
38
|
-
export type DocumentMap = ReadonlyMap<string, DocumentValue>;
|
|
36
|
+
export type { DocumentMap, DocumentValue };
|
|
39
37
|
/** The meta document. */
|
|
40
38
|
export interface BoardMetaRecord {
|
|
41
39
|
v: number;
|
package/src/json.d.ts
CHANGED
|
@@ -1,56 +1,2 @@
|
|
|
1
|
-
/**
|
|
2
|
-
*
|
|
3
|
-
* comparison, JSON merge patches (RFC 7396), depth and byte measures.
|
|
4
|
-
*
|
|
5
|
-
* A merge patch sets fields it names, recurses into objects, and deletes a
|
|
6
|
-
* field whose patch value is `null`. Arrays are replaced whole.
|
|
7
|
-
*/
|
|
8
|
-
/** A JSON value. */
|
|
9
|
-
export type Json = null | boolean | number | string | Json[] | {
|
|
10
|
-
[key: string]: Json;
|
|
11
|
-
};
|
|
12
|
-
/** A JSON object. */
|
|
13
|
-
export type JsonObject = {
|
|
14
|
-
[key: string]: Json;
|
|
15
|
-
};
|
|
16
|
-
/** A JSON merge patch: like the object, with `null` meaning "delete". */
|
|
17
|
-
export type MergePatch = {
|
|
18
|
-
[key: string]: Json | undefined;
|
|
19
|
-
};
|
|
20
|
-
/** True for a plain object (not an array, not null). */
|
|
21
|
-
export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
|
|
22
|
-
/** JSON text with object keys sorted (cached per object). */
|
|
23
|
-
export declare function stableStringify(value: unknown): string;
|
|
24
|
-
/** True when two values are the same JSON, ignoring key order. */
|
|
25
|
-
export declare function canonicalValuesEqual(a: unknown, b: unknown): boolean;
|
|
26
|
-
/** Deep merge of `patch` into `base` (no deletes; `undefined` is skipped). */
|
|
27
|
-
export declare function deepMerge<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>): T;
|
|
28
|
-
/**
|
|
29
|
-
* Merges two partial records when they do not conflict in shape (an object
|
|
30
|
-
* field never meets a non-object); `null` when they do.
|
|
31
|
-
*/
|
|
32
|
-
export declare function mergeCompatibleRecords(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> | null;
|
|
33
|
-
/**
|
|
34
|
-
* The merge patch that turns `from` into `to`, or `null` when they are equal.
|
|
35
|
-
* With `from` undefined the patch is `to` itself.
|
|
36
|
-
*/
|
|
37
|
-
export declare function createJsonMergePatch(from: Record<string, unknown> | undefined, to: Record<string, unknown>): MergePatch | null;
|
|
38
|
-
/** Applies a merge patch to a record (a missing record starts empty). */
|
|
39
|
-
export declare function applyJsonMergePatch(target: Record<string, unknown> | undefined, patch: Record<string, unknown>): Record<string, unknown>;
|
|
40
|
-
/** Composes two merge patches into one with the same effect (`a` then `b`). */
|
|
41
|
-
export declare function composeMergePatches(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown>;
|
|
42
|
-
/** The patch with every `null` (delete) removed: what the patch *sets*. */
|
|
43
|
-
export declare function removeNullMergePatchFields<T extends Record<string, unknown>>(patch: T): T;
|
|
44
|
-
/** How many `null` deletes a patch carries. */
|
|
45
|
-
export declare function countMergePatchTombstones(patch: Record<string, unknown>): number;
|
|
46
|
-
/** True when applying `patch` to `target` changes nothing. */
|
|
47
|
-
export declare function isMergePatchSubset(patch: Record<string, unknown>, target: Record<string, unknown> | undefined): boolean;
|
|
48
|
-
/** Nesting depth of a JSON value (a scalar is 0); stops counting at `limit`. */
|
|
49
|
-
export declare function jsonValueDepth(value: unknown, limit?: number): number;
|
|
50
|
-
/**
|
|
51
|
-
* Bytes of a value's JSON as a server that escapes `<`, `>`, `&` (as
|
|
52
|
-
* `<`…, +5 bytes each) and U+2028/2029 (+3 bytes) would store it.
|
|
53
|
-
*/
|
|
54
|
-
export declare function escapedJsonByteLength(value: unknown): number;
|
|
55
|
-
/** A deep copy of a JSON value. */
|
|
56
|
-
export declare function cloneJson<T>(value: T): T;
|
|
1
|
+
/** The JSON helpers live in the shared live store. */
|
|
2
|
+
export * from '@open-artifact/live-store/json';
|
package/src/json.js
CHANGED
|
@@ -1,221 +1,2 @@
|
|
|
1
|
-
/**
|
|
2
|
-
*
|
|
3
|
-
* comparison, JSON merge patches (RFC 7396), depth and byte measures.
|
|
4
|
-
*
|
|
5
|
-
* A merge patch sets fields it names, recurses into objects, and deletes a
|
|
6
|
-
* field whose patch value is `null`. Arrays are replaced whole.
|
|
7
|
-
*/
|
|
8
|
-
const PROTO_KEY = '__proto__';
|
|
9
|
-
/** True for a plain object (not an array, not null). */
|
|
10
|
-
export function isPlainRecord(value) {
|
|
11
|
-
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
12
|
-
}
|
|
13
|
-
const stableJsonCache = new WeakMap();
|
|
14
|
-
function sortKeys(_key, value) {
|
|
15
|
-
if (!isPlainRecord(value))
|
|
16
|
-
return value;
|
|
17
|
-
const sorted = {};
|
|
18
|
-
for (const key of Object.keys(value).sort())
|
|
19
|
-
sorted[key] = value[key];
|
|
20
|
-
return sorted;
|
|
21
|
-
}
|
|
22
|
-
/** JSON text with object keys sorted (cached per object). */
|
|
23
|
-
export function stableStringify(value) {
|
|
24
|
-
if (typeof value === 'object' && value !== null) {
|
|
25
|
-
const cached = stableJsonCache.get(value);
|
|
26
|
-
if (cached !== undefined)
|
|
27
|
-
return cached;
|
|
28
|
-
const json = JSON.stringify(value, sortKeys) ?? 'undefined';
|
|
29
|
-
stableJsonCache.set(value, json);
|
|
30
|
-
return json;
|
|
31
|
-
}
|
|
32
|
-
return JSON.stringify(value, sortKeys) ?? 'undefined';
|
|
33
|
-
}
|
|
34
|
-
/** True when two values are the same JSON, ignoring key order. */
|
|
35
|
-
export function canonicalValuesEqual(a, b) {
|
|
36
|
-
if (a === b)
|
|
37
|
-
return true;
|
|
38
|
-
if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
|
|
39
|
-
return false;
|
|
40
|
-
return stableStringify(a) === stableStringify(b);
|
|
41
|
-
}
|
|
42
|
-
/** Deep merge of `patch` into `base` (no deletes; `undefined` is skipped). */
|
|
43
|
-
export function deepMerge(base, patch) {
|
|
44
|
-
const merged = { ...base };
|
|
45
|
-
for (const key of Object.keys(patch)) {
|
|
46
|
-
const value = patch[key];
|
|
47
|
-
if (value === undefined || key === PROTO_KEY)
|
|
48
|
-
continue;
|
|
49
|
-
const current = merged[key];
|
|
50
|
-
merged[key] = isPlainRecord(current) && isPlainRecord(value) ? deepMerge(current, value) : value;
|
|
51
|
-
}
|
|
52
|
-
return merged;
|
|
53
|
-
}
|
|
54
|
-
/**
|
|
55
|
-
* Merges two partial records when they do not conflict in shape (an object
|
|
56
|
-
* field never meets a non-object); `null` when they do.
|
|
57
|
-
*/
|
|
58
|
-
export function mergeCompatibleRecords(a, b) {
|
|
59
|
-
const merged = { ...a };
|
|
60
|
-
for (const key of Object.keys(b)) {
|
|
61
|
-
const value = b[key];
|
|
62
|
-
if (value === undefined || key === PROTO_KEY)
|
|
63
|
-
continue;
|
|
64
|
-
const current = merged[key];
|
|
65
|
-
if (isPlainRecord(value) && current !== undefined) {
|
|
66
|
-
if (!isPlainRecord(current))
|
|
67
|
-
return null;
|
|
68
|
-
const inner = mergeCompatibleRecords(current, value);
|
|
69
|
-
if (inner === null)
|
|
70
|
-
return null;
|
|
71
|
-
merged[key] = inner;
|
|
72
|
-
}
|
|
73
|
-
else
|
|
74
|
-
merged[key] = value;
|
|
75
|
-
}
|
|
76
|
-
return merged;
|
|
77
|
-
}
|
|
78
|
-
/**
|
|
79
|
-
* The merge patch that turns `from` into `to`, or `null` when they are equal.
|
|
80
|
-
* With `from` undefined the patch is `to` itself.
|
|
81
|
-
*/
|
|
82
|
-
export function createJsonMergePatch(from, to) {
|
|
83
|
-
if (from === to)
|
|
84
|
-
return null;
|
|
85
|
-
if (from === undefined)
|
|
86
|
-
return to;
|
|
87
|
-
let patch = null;
|
|
88
|
-
for (const key of Object.keys(to)) {
|
|
89
|
-
if (key === PROTO_KEY)
|
|
90
|
-
continue;
|
|
91
|
-
const next = to[key];
|
|
92
|
-
const previous = from[key];
|
|
93
|
-
if (next === undefined) {
|
|
94
|
-
if (previous !== undefined)
|
|
95
|
-
(patch ??= {})[key] = null;
|
|
96
|
-
continue;
|
|
97
|
-
}
|
|
98
|
-
if (previous === next)
|
|
99
|
-
continue;
|
|
100
|
-
if (isPlainRecord(previous) && isPlainRecord(next)) {
|
|
101
|
-
const inner = createJsonMergePatch(previous, next);
|
|
102
|
-
if (inner !== null)
|
|
103
|
-
(patch ??= {})[key] = inner;
|
|
104
|
-
}
|
|
105
|
-
else if (previous === undefined || !canonicalValuesEqual(previous, next))
|
|
106
|
-
(patch ??= {})[key] = next;
|
|
107
|
-
}
|
|
108
|
-
for (const key of Object.keys(from)) {
|
|
109
|
-
if (from[key] !== undefined && to[key] === undefined)
|
|
110
|
-
(patch ??= {})[key] = null;
|
|
111
|
-
}
|
|
112
|
-
return patch;
|
|
113
|
-
}
|
|
114
|
-
/** Applies a merge patch to a record (a missing record starts empty). */
|
|
115
|
-
export function applyJsonMergePatch(target, patch) {
|
|
116
|
-
const result = { ...(target ?? {}) };
|
|
117
|
-
for (const key of Object.keys(patch)) {
|
|
118
|
-
if (key === PROTO_KEY)
|
|
119
|
-
continue;
|
|
120
|
-
const value = patch[key];
|
|
121
|
-
if (value === undefined)
|
|
122
|
-
continue;
|
|
123
|
-
if (value === null)
|
|
124
|
-
delete result[key];
|
|
125
|
-
else if (isPlainRecord(value))
|
|
126
|
-
result[key] = applyJsonMergePatch(isPlainRecord(result[key]) ? result[key] : undefined, value);
|
|
127
|
-
else
|
|
128
|
-
result[key] = value;
|
|
129
|
-
}
|
|
130
|
-
return result;
|
|
131
|
-
}
|
|
132
|
-
/** Composes two merge patches into one with the same effect (`a` then `b`). */
|
|
133
|
-
export function composeMergePatches(a, b) {
|
|
134
|
-
const result = { ...a };
|
|
135
|
-
for (const key of Object.keys(b)) {
|
|
136
|
-
if (key === PROTO_KEY)
|
|
137
|
-
continue;
|
|
138
|
-
const value = b[key];
|
|
139
|
-
if (value === undefined)
|
|
140
|
-
continue;
|
|
141
|
-
const previous = result[key];
|
|
142
|
-
result[key] = isPlainRecord(value) && isPlainRecord(previous) ? composeMergePatches(previous, value) : value;
|
|
143
|
-
}
|
|
144
|
-
return result;
|
|
145
|
-
}
|
|
146
|
-
/** The patch with every `null` (delete) removed: what the patch *sets*. */
|
|
147
|
-
export function removeNullMergePatchFields(patch) {
|
|
148
|
-
let result;
|
|
149
|
-
for (const key of Object.keys(patch)) {
|
|
150
|
-
const value = patch[key];
|
|
151
|
-
let next = value;
|
|
152
|
-
if (value === null || value === undefined || key === PROTO_KEY)
|
|
153
|
-
next = undefined;
|
|
154
|
-
else if (isPlainRecord(value))
|
|
155
|
-
next = removeNullMergePatchFields(value);
|
|
156
|
-
if (next !== value) {
|
|
157
|
-
result ??= { ...patch };
|
|
158
|
-
if (next === undefined)
|
|
159
|
-
delete result[key];
|
|
160
|
-
else
|
|
161
|
-
result[key] = next;
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
|
-
return (result ?? patch);
|
|
165
|
-
}
|
|
166
|
-
/** How many `null` deletes a patch carries. */
|
|
167
|
-
export function countMergePatchTombstones(patch) {
|
|
168
|
-
let count = 0;
|
|
169
|
-
for (const value of Object.values(patch)) {
|
|
170
|
-
if (value === null)
|
|
171
|
-
count += 1;
|
|
172
|
-
else if (isPlainRecord(value))
|
|
173
|
-
count += countMergePatchTombstones(value);
|
|
174
|
-
}
|
|
175
|
-
return count;
|
|
176
|
-
}
|
|
177
|
-
/** True when applying `patch` to `target` changes nothing. */
|
|
178
|
-
export function isMergePatchSubset(patch, target) {
|
|
179
|
-
for (const key of Object.keys(patch)) {
|
|
180
|
-
const value = patch[key];
|
|
181
|
-
if (value === undefined)
|
|
182
|
-
continue;
|
|
183
|
-
const current = target?.[key];
|
|
184
|
-
if (value === null) {
|
|
185
|
-
if (current !== undefined)
|
|
186
|
-
return false;
|
|
187
|
-
}
|
|
188
|
-
else if (isPlainRecord(value)) {
|
|
189
|
-
if (!isPlainRecord(current) || !isMergePatchSubset(value, current))
|
|
190
|
-
return false;
|
|
191
|
-
}
|
|
192
|
-
else if (!canonicalValuesEqual(value, current))
|
|
193
|
-
return false;
|
|
194
|
-
}
|
|
195
|
-
return true;
|
|
196
|
-
}
|
|
197
|
-
/** Nesting depth of a JSON value (a scalar is 0); stops counting at `limit`. */
|
|
198
|
-
export function jsonValueDepth(value, limit = 64) {
|
|
199
|
-
if (typeof value !== 'object' || value === null)
|
|
200
|
-
return 0;
|
|
201
|
-
let depth = 0;
|
|
202
|
-
for (const child of Array.isArray(value) ? value : Object.values(value)) {
|
|
203
|
-
depth = Math.max(depth, jsonValueDepth(child, limit - 1));
|
|
204
|
-
if (depth >= limit)
|
|
205
|
-
break;
|
|
206
|
-
}
|
|
207
|
-
return depth + 1;
|
|
208
|
-
}
|
|
209
|
-
/**
|
|
210
|
-
* Bytes of a value's JSON as a server that escapes `<`, `>`, `&` (as
|
|
211
|
-
* `<`…, +5 bytes each) and U+2028/2029 (+3 bytes) would store it.
|
|
212
|
-
*/
|
|
213
|
-
export function escapedJsonByteLength(value) {
|
|
214
|
-
const json = JSON.stringify(value) ?? '';
|
|
215
|
-
const extra = 5 * (json.match(/[<>&]/g)?.length ?? 0) + 3 * (json.match(/[\u2028\u2029]/g)?.length ?? 0);
|
|
216
|
-
return new TextEncoder().encode(json).length + extra;
|
|
217
|
-
}
|
|
218
|
-
/** A deep copy of a JSON value. */
|
|
219
|
-
export function cloneJson(value) {
|
|
220
|
-
return value === undefined ? value : JSON.parse(JSON.stringify(value));
|
|
221
|
-
}
|
|
1
|
+
/** The JSON helpers live in the shared live store. */
|
|
2
|
+
export * from '@open-artifact/live-store/json';
|
package/src/sync/doc-hash.d.ts
CHANGED
|
@@ -1,13 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* A document's hash, the way the store names a version of it: the SHA-256
|
|
3
|
-
* (lowercase hex) of its data as compact JSON (`JSON.stringify`), UTF-8.
|
|
4
|
-
* The server's `docSha256` and the agent's tools give the same value, so a
|
|
5
|
-
* page can make a write conditional (`ifMatch`) on the document it read.
|
|
6
|
-
*
|
|
7
|
-
* Plain TypeScript, synchronous: a board shared on a LAN address is served
|
|
8
|
-
* over http, where browsers leave out `crypto.subtle`.
|
|
9
|
-
*/
|
|
10
|
-
/** SHA-256 of bytes, lowercase hex. */
|
|
11
|
-
export declare function sha256Hex(bytes: Uint8Array): string;
|
|
12
|
-
/** The store's hash of a document's data (for a write's `ifMatch`). */
|
|
13
|
-
export declare function documentSha256(data: unknown): string;
|
|
1
|
+
export * from '@open-artifact/live-store/doc-hash';
|
package/src/sync/doc-hash.js
CHANGED
|
@@ -1,67 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* A document's hash, the way the store names a version of it: the SHA-256
|
|
3
|
-
* (lowercase hex) of its data as compact JSON (`JSON.stringify`), UTF-8.
|
|
4
|
-
* The server's `docSha256` and the agent's tools give the same value, so a
|
|
5
|
-
* page can make a write conditional (`ifMatch`) on the document it read.
|
|
6
|
-
*
|
|
7
|
-
* Plain TypeScript, synchronous: a board shared on a LAN address is served
|
|
8
|
-
* over http, where browsers leave out `crypto.subtle`.
|
|
9
|
-
*/
|
|
10
|
-
const K = new Uint32Array([
|
|
11
|
-
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
|
|
12
|
-
0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
|
|
13
|
-
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
|
|
14
|
-
0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
|
|
15
|
-
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
|
|
16
|
-
0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
|
|
17
|
-
]);
|
|
18
|
-
const rotr = (x, n) => (x >>> n) | (x << (32 - n));
|
|
19
|
-
/** SHA-256 of bytes, lowercase hex. */
|
|
20
|
-
export function sha256Hex(bytes) {
|
|
21
|
-
const bitLength = bytes.length * 8;
|
|
22
|
-
const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
|
|
23
|
-
padded.set(bytes);
|
|
24
|
-
padded[bytes.length] = 0x80;
|
|
25
|
-
const view = new DataView(padded.buffer);
|
|
26
|
-
view.setUint32(padded.length - 8, Math.floor(bitLength / 0x1_0000_0000));
|
|
27
|
-
view.setUint32(padded.length - 4, bitLength >>> 0);
|
|
28
|
-
const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
|
|
29
|
-
const w = new Uint32Array(64);
|
|
30
|
-
for (let offset = 0; offset < padded.length; offset += 64) {
|
|
31
|
-
for (let i = 0; i < 16; i++)
|
|
32
|
-
w[i] = view.getUint32(offset + i * 4);
|
|
33
|
-
for (let i = 16; i < 64; i++) {
|
|
34
|
-
const a = w[i - 15];
|
|
35
|
-
const b = w[i - 2];
|
|
36
|
-
const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
|
|
37
|
-
const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
|
|
38
|
-
w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
|
|
39
|
-
}
|
|
40
|
-
let [a, b, c, d, e, f, g, hh] = h;
|
|
41
|
-
for (let i = 0; i < 64; i++) {
|
|
42
|
-
const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
|
|
43
|
-
const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
|
|
44
|
-
hh = g;
|
|
45
|
-
g = f;
|
|
46
|
-
f = e;
|
|
47
|
-
e = (d + t1) >>> 0;
|
|
48
|
-
d = c;
|
|
49
|
-
c = b;
|
|
50
|
-
b = a;
|
|
51
|
-
a = (t1 + t2) >>> 0;
|
|
52
|
-
}
|
|
53
|
-
h[0] = h[0] + a;
|
|
54
|
-
h[1] = h[1] + b;
|
|
55
|
-
h[2] = h[2] + c;
|
|
56
|
-
h[3] = h[3] + d;
|
|
57
|
-
h[4] = h[4] + e;
|
|
58
|
-
h[5] = h[5] + f;
|
|
59
|
-
h[6] = h[6] + g;
|
|
60
|
-
h[7] = h[7] + hh;
|
|
61
|
-
}
|
|
62
|
-
return Array.from(h, (word) => word.toString(16).padStart(8, '0')).join('');
|
|
63
|
-
}
|
|
64
|
-
/** The store's hash of a document's data (for a write's `ifMatch`). */
|
|
65
|
-
export function documentSha256(data) {
|
|
66
|
-
return sha256Hex(new TextEncoder().encode(JSON.stringify(data)));
|
|
67
|
-
}
|
|
1
|
+
export * from '@open-artifact/live-store/doc-hash';
|
package/src/sync/engine.d.ts
CHANGED
|
@@ -1,228 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* The live sync engine: keeps a value (a board) in step with a document
|
|
3
|
-
* store, one document per element plus a few board records.
|
|
4
|
-
*
|
|
5
|
-
* Model, per document path:
|
|
6
|
-
* - `server`: the last value the store reported (by listing, a change event,
|
|
7
|
-
* or our own acknowledged write);
|
|
8
|
-
* - `acked`: our writes acknowledged in the last few seconds, re-applied over
|
|
9
|
-
* `server` so a late event about an older write does not flash old data;
|
|
10
|
-
* - `inflight`: the change being written;
|
|
11
|
-
* - `pending`: the change waiting to be written (debounced, merged).
|
|
12
|
-
*
|
|
13
|
-
* What the viewer sees is `server ⊕ acked ⊕ inflight ⊕ pending`. Changes are
|
|
14
|
-
* JSON merge patches computed against the document as it was before them, so
|
|
15
|
-
* two people editing different fields of one element both win; the same
|
|
16
|
-
* field: the last write wins.
|
|
17
|
-
*
|
|
18
|
-
* Local edits are applied at once ({@link LiveStore.commit}), split into
|
|
19
|
-
* documents on the next tick, and written after {@link LIVE_EDIT_DEBOUNCE_MS}
|
|
20
|
-
* of quiet (at most {@link LIVE_EDIT_MAX_WAIT_MS} after the first edit). Failed
|
|
21
|
-
* writes are retried with backoff; a document the store refuses (too large,
|
|
22
|
-
* invalid) is parked and the rest keep syncing. Losing write access stops
|
|
23
|
-
* syncing and keeps the edits on screen.
|
|
24
|
-
*
|
|
25
|
-
* Saved copy: with a {@link LiveCache}, the engine keeps the documents the
|
|
26
|
-
* store confirmed on the device. When the store does not answer within
|
|
27
|
-
* {@link LIVE_SNAPSHOT_TIMEOUT_MS}, or loading fails for a reason other than
|
|
28
|
-
* access, the saved copy is shown (`cached`): people can keep editing, and
|
|
29
|
-
* their edits wait until the store answers, then sync over what it holds.
|
|
30
|
-
*
|
|
31
|
-
* The engine is framework-agnostic: {@link LiveStore.getSnapshot} and
|
|
32
|
-
* {@link LiveStore.subscribe} fit React's `useSyncExternalStore` or a Zustand
|
|
33
|
-
* store.
|
|
34
|
-
*/
|
|
35
|
-
import type { DocumentMap, DocumentValue, OrderCarry } from '../codec.ts';
|
|
36
|
-
import { type SyncDocument, type SyncErrorCode, type SyncTimers, type SyncTransport } from './transport.ts';
|
|
37
|
-
/** Quiet time after the last edit of a document before it is written. */
|
|
38
|
-
export declare const LIVE_EDIT_DEBOUNCE_MS = 350;
|
|
39
|
-
/** Longest a document waits after its first unsent edit. */
|
|
40
|
-
export declare const LIVE_EDIT_MAX_WAIT_MS = 1500;
|
|
41
|
-
/** After this long loading, the saved copy shows (when there is one), else the status says it is still loading. */
|
|
42
|
-
export declare const LIVE_SNAPSHOT_TIMEOUT_MS = 10000;
|
|
43
|
-
/** After this long loading, the load counts as failed and is retried. */
|
|
44
|
-
export declare const LIVE_EXTENDED_LOAD_TIMEOUT_MS = 35000;
|
|
45
|
-
/** Delays between load retries; the last one repeats. */
|
|
46
|
-
export declare const LIVE_RECONNECT_BACKOFF_MS: readonly number[];
|
|
47
|
-
/** How long an acknowledged write is re-applied over store events. */
|
|
48
|
-
export declare const ACKNOWLEDGED_WRITE_GRACE_MS = 5000;
|
|
49
|
-
/** A write that has not settled after this long is retried. */
|
|
50
|
-
export declare const STUCK_WRITE_TIMEOUT_MS = 60000;
|
|
51
|
-
/** A patch deleting more fields than this is sent as a whole document instead. */
|
|
52
|
-
export declare const MAX_MERGE_PATCH_TOMBSTONES = 64;
|
|
53
|
-
/** The first retry after a failed write waits a random time in this range. */
|
|
54
|
-
export declare const INITIAL_WRITE_RETRY_JITTER_MS: readonly [number, number];
|
|
55
|
-
/** Later retries: `min(MAX, BASE · 2^(failures − 2))`. */
|
|
56
|
-
export declare const WRITE_RETRY_BASE_MS = 2000;
|
|
57
|
-
export declare const WRITE_RETRY_MAX_MS = 30000;
|
|
58
|
-
/** Retries when the store says it is overloaded: `min(MAX, BASE · 2^(failures − 1))`. */
|
|
59
|
-
export declare const BACKPRESSURE_RETRY_BASE_MS = 1000;
|
|
60
|
-
export declare const BACKPRESSURE_RETRY_MAX_MS = 8000;
|
|
61
|
-
/** Overload lasting this long shows as an error. */
|
|
62
|
-
export declare const BACKPRESSURE_ERROR_AFTER_MS = 30000;
|
|
63
|
-
/** Shortest timer the engine sets. */
|
|
64
|
-
export declare const MIN_SYNC_TIMER_DELAY_MS = 16;
|
|
65
|
-
/** Acknowledged writes kept per document, at most. */
|
|
66
|
-
export declare const MAX_UNCOALESCED_ACKNOWLEDGED_WRITES = 8;
|
|
67
|
-
/** Write calls in flight at once, at most. */
|
|
68
|
-
export declare const MAX_CONCURRENT_LIVE_WRITES = 25;
|
|
69
|
-
/** Documents per write call, at most (the store allows 500). */
|
|
70
|
-
export declare const MAX_WRITES_PER_BATCH = 100;
|
|
71
|
-
/** Approximate bytes per write call, at most (one larger document still goes alone). */
|
|
72
|
-
export declare const MAX_BATCH_BYTES = 1048576;
|
|
73
|
-
/** Quiet time before the saved copy is updated after the store's documents change. */
|
|
74
|
-
export declare const LIVE_CACHE_WRITE_DELAY_MS = 2000;
|
|
75
|
-
/** How a value maps to documents. The board codec is adapted in `live-board.ts`. */
|
|
76
|
-
export interface LiveCodec<T> {
|
|
77
|
-
/** Collections the value lives in, in write order (elements before `board`). */
|
|
78
|
-
readonly collections: readonly string[];
|
|
79
|
-
/** The document that lists the order; written after its collection's documents. */
|
|
80
|
-
readonly metaPath: string;
|
|
81
|
-
/** Splits a value into documents; `previous` lends identity and records the value does not carry. */
|
|
82
|
-
decompose(value: T, previous: DocumentMap | undefined, carry: OrderCarry | undefined): Map<string, DocumentValue>;
|
|
83
|
-
/** Builds the value from documents. */
|
|
84
|
-
compose(documents: DocumentMap): {
|
|
85
|
-
value: T;
|
|
86
|
-
carry?: OrderCarry;
|
|
87
|
-
};
|
|
88
|
-
/** Documents always written whole. */
|
|
89
|
-
replaceOnly(path: string): boolean;
|
|
90
|
-
/** Why a document may not be written (too large…), or `undefined`. */
|
|
91
|
-
refuse(path: string, value: unknown, boardBytes: number): string | undefined;
|
|
92
|
-
/** Keeps unchanged parts of `previous` in `next` (identity); returns `previous` when equal. */
|
|
93
|
-
share?(previous: T, next: T): T;
|
|
94
|
-
}
|
|
95
|
-
/**
|
|
96
|
-
* Whether the first snapshot has arrived: `loading`, `cached` (the store
|
|
97
|
-
* has not answered; the saved copy is shown and loading goes on), `live`
|
|
98
|
-
* or `failed`.
|
|
99
|
-
*/
|
|
100
|
-
export type LiveLoadState = 'loading' | 'cached' | 'live' | 'failed';
|
|
101
|
-
/**
|
|
102
|
-
* The sync status: `loading`, `cached` (showing the saved copy while the
|
|
103
|
-
* store is out of reach), `ready` (all synced), `dirty` (edits waiting),
|
|
104
|
-
* `saving` (writes in flight), `offline` (the store is unreachable;
|
|
105
|
-
* retrying), `error` (load failed, access lost or a document parked) or
|
|
106
|
-
* `readonly`.
|
|
107
|
-
*/
|
|
108
|
-
export type LiveStatus = 'loading' | 'cached' | 'ready' | 'dirty' | 'saving' | 'offline' | 'error' | 'readonly';
|
|
109
|
-
/** The last failure. */
|
|
110
|
-
export interface LiveSyncError {
|
|
111
|
-
code: SyncErrorCode | 'refused';
|
|
112
|
-
message: string;
|
|
113
|
-
path?: string;
|
|
114
|
-
}
|
|
115
|
-
/** A one-time message for a toast (a new `id` means a new notice). */
|
|
116
|
-
export interface LiveNotice {
|
|
117
|
-
id: number;
|
|
118
|
-
message: string;
|
|
119
|
-
}
|
|
120
|
-
/** Everything the UI reads. The object is replaced only when something changed. */
|
|
121
|
-
export interface LiveSnapshot<T> {
|
|
122
|
-
readonly value: T;
|
|
123
|
-
readonly loadState: LiveLoadState;
|
|
124
|
-
readonly status: LiveStatus;
|
|
125
|
-
/** Status text in English (the UI may localize from `status` and the counts). */
|
|
126
|
-
readonly message: string;
|
|
127
|
-
/** A second line for the status (what to do). */
|
|
128
|
-
readonly hint?: string;
|
|
129
|
-
/** Clicking the status may help ({@link LiveStore.retry}). */
|
|
130
|
-
readonly retryable: boolean;
|
|
131
|
-
readonly readOnly: boolean;
|
|
132
|
-
/** Documents with unsent or in-flight changes. */
|
|
133
|
-
readonly pending: number;
|
|
134
|
-
/** Write calls in flight. */
|
|
135
|
-
readonly flights: number;
|
|
136
|
-
/** Why a document the codec refused cannot be stored (while it stays unsent). */
|
|
137
|
-
readonly refusal?: string;
|
|
138
|
-
readonly notice?: LiveNotice;
|
|
139
|
-
readonly lastSyncedAt?: number;
|
|
140
|
-
readonly lastError?: LiveSyncError;
|
|
141
|
-
}
|
|
142
|
-
/** What a change notification says. */
|
|
143
|
-
export interface LiveChange<T> {
|
|
144
|
-
/** The value changed because of someone else's edit (or a reload). */
|
|
145
|
-
readonly remote: boolean;
|
|
146
|
-
/** The value changed (otherwise only the status did). */
|
|
147
|
-
readonly valueChanged: boolean;
|
|
148
|
-
/** The value before the change. */
|
|
149
|
-
readonly previous: T;
|
|
150
|
-
}
|
|
151
|
-
/**
|
|
152
|
-
* The saved copy on this device: the documents the store last confirmed.
|
|
153
|
-
* Both calls are synchronous and may fail quietly (storage full or off).
|
|
154
|
-
*/
|
|
155
|
-
export interface LiveCache {
|
|
156
|
-
/** The saved documents, or `undefined` when there is no saved copy. */
|
|
157
|
-
read(): SyncDocument[] | undefined;
|
|
158
|
-
/** Replaces the saved copy. */
|
|
159
|
-
write(documents: SyncDocument[]): void;
|
|
160
|
-
}
|
|
161
|
-
/** Options of {@link createLiveStore}. */
|
|
162
|
-
export interface LiveStoreOptions<T> {
|
|
163
|
-
transport: SyncTransport;
|
|
164
|
-
/** Keeps a saved copy to show when the store is out of reach. */
|
|
165
|
-
cache?: LiveCache;
|
|
166
|
-
codec: LiveCodec<T>;
|
|
167
|
-
/** The value shown until the first snapshot arrives. */
|
|
168
|
-
initial: T;
|
|
169
|
-
/** Viewers never write. */
|
|
170
|
-
readOnly?: boolean;
|
|
171
|
-
timers?: SyncTimers;
|
|
172
|
-
/** Formats the "synced at" time of the ready message. */
|
|
173
|
-
formatTime?: (epochMs: number) => string;
|
|
174
|
-
}
|
|
175
|
-
/** A live, synced value. */
|
|
176
|
-
export interface LiveStore<T> {
|
|
177
|
-
/** The current snapshot (same object until something changes). */
|
|
178
|
-
getSnapshot(): LiveSnapshot<T>;
|
|
179
|
-
/** The current value. */
|
|
180
|
-
value(): T;
|
|
181
|
-
/** Listens to changes; returns an unsubscribe function. */
|
|
182
|
-
subscribe(listener: (change: LiveChange<T>) => void): () => void;
|
|
183
|
-
/** Applies a local edit; `false` when editing is not possible (loading, read-only, stopped). */
|
|
184
|
-
commit(next: T): boolean;
|
|
185
|
-
/** True when {@link LiveStore.commit} would be accepted. */
|
|
186
|
-
canEdit(): boolean;
|
|
187
|
-
/** Writes everything now; resolves when nothing more can be sent. */
|
|
188
|
-
flush(): Promise<void>;
|
|
189
|
-
/** Retries a failed load, parked documents and backed-off writes now. */
|
|
190
|
-
retry(): void;
|
|
191
|
-
/** Switches viewer mode. */
|
|
192
|
-
setReadOnly(readOnly: boolean): void;
|
|
193
|
-
/** Bytes of every document, as the store counts them. */
|
|
194
|
-
documentBytes(): number;
|
|
195
|
-
/** Stops syncing (call {@link LiveStore.flush} first to send pending edits). */
|
|
196
|
-
dispose(): void;
|
|
197
|
-
}
|
|
198
|
-
/** Status and notice texts (English defaults). */
|
|
199
|
-
export declare const LIVE_MESSAGES: {
|
|
200
|
-
readonly loading: "Loading the latest content…";
|
|
201
|
-
readonly loadingSlow: "Still loading the latest content…";
|
|
202
|
-
readonly loadFailed: "The latest content failed to load. Click to retry.";
|
|
203
|
-
readonly cached: "Showing your saved copy. Reconnecting…";
|
|
204
|
-
readonly cachedEdits: "Showing your saved copy. Your changes will sync when you’re back online.";
|
|
205
|
-
readonly cachedReadOnly: "Showing a saved copy. Reconnecting…";
|
|
206
|
-
readonly readOnly: "Read-only. You’re seeing live changes.";
|
|
207
|
-
readonly accessEnded: "Live sync ended for this view. Reload to continue.";
|
|
208
|
-
readonly parkedSuffix: "Other changes keep syncing.";
|
|
209
|
-
readonly refusedHint: "Shorten it to resume syncing this item.";
|
|
210
|
-
readonly retryHint: "Click to retry.";
|
|
211
|
-
readonly unreachableNow: "The store is unreachable. Retrying now. Your edits are kept on this screen.";
|
|
212
|
-
readonly unreachableLater: "The store is unreachable. Retrying shortly; click to retry now. Your edits are kept on this screen.";
|
|
213
|
-
readonly busy: "The store is busy. Your edits are kept on this screen and will sync when it recovers.";
|
|
214
|
-
readonly saving: "Syncing…";
|
|
215
|
-
readonly syncedHint: "Edits sync as you go; if two people change the same thing, the last change wins.";
|
|
216
|
-
readonly itemGone: "An item you were editing was deleted by someone else.";
|
|
217
|
-
readonly cannotStore: (why: string) => string;
|
|
218
|
-
readonly waiting: (count: number) => string;
|
|
219
|
-
readonly syncedAt: (time: string) => string;
|
|
220
|
-
readonly synced: "Synced.";
|
|
221
|
-
};
|
|
222
|
-
/**
|
|
223
|
-
* Drops the parts of a patch that recurse into an object field the store now
|
|
224
|
-
* holds as a non-object: merging them would build a half object.
|
|
225
|
-
*/
|
|
226
|
-
export declare function dropShapeConflicts(patch: Record<string, unknown>, server: Record<string, unknown> | undefined): Record<string, unknown>;
|
|
227
|
-
/** Creates a live store; loading starts at once. */
|
|
228
|
-
export declare function createLiveStore<T>(options: LiveStoreOptions<T>): LiveStore<T>;
|
|
1
|
+
export * from '@open-artifact/live-store/engine';
|