@estiva-app/protocol 0.46.1 → 0.48.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/src/index.ts CHANGED
@@ -47,7 +47,7 @@
47
47
  /** Bumped by hand with the version in package.json — `test/version.test.ts`
48
48
  * pins the two together. It exists so "the upgrade reached the app" can be
49
49
  * checked by grepping a built bundle rather than by trusting a lockfile. */
50
- export const PROTOCOL_VERSION = '0.46.1'
50
+ export const PROTOCOL_VERSION = '0.48.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -144,6 +144,9 @@ export {
144
144
  export {
145
145
  type PublishResult,
146
146
  type QueryResult,
147
+ type SearchMatch,
148
+ type RelayFileReads,
149
+ relayFileReadsOf,
147
150
  type RelayHeaders,
148
151
  type RelayOptions,
149
152
  type FetchLike,
@@ -221,6 +224,15 @@ export {
221
224
  documentText,
222
225
  } from './blocks.js'
223
226
 
227
+ export {
228
+ type MergeText,
229
+ type MergeAsk,
230
+ type TextMerge,
231
+ type BlockMerge,
232
+ mergeBlockDocuments,
233
+ mergeTexts,
234
+ } from './merge.js'
235
+
224
236
  export {
225
237
  type RenderInline,
226
238
  type RenderBlock,
@@ -259,16 +271,20 @@ export {
259
271
  } from './editor.js'
260
272
 
261
273
  export {
274
+ type AbsenceOptions,
262
275
  type BlockAnchor,
276
+ type DeletionEvent,
263
277
  type Part,
264
278
  type PartPointer,
265
279
  type PartSource,
266
280
  BLOCK_ANCHOR_TAG,
267
281
  PART_TAG,
282
+ absenceFilters,
268
283
  absenceOf,
269
284
  blockAnchorOf,
270
285
  partTag,
271
286
  partsOf,
287
+ readAbsence,
272
288
  resolveBlockAnchor,
273
289
  resolvePart,
274
290
  } from './anchors.js'
package/src/merge.ts ADDED
@@ -0,0 +1,381 @@
1
+ /**
2
+ * Merging two changes to one text — SPEC §13.3, conformance C41 and C42.
3
+ *
4
+ * When the relay refuses a text save with `conflict:` (§6.2), its app merges
5
+ * three texts: the **base**, the text its save named as `prev`; **theirs**, the
6
+ * text now current; and **mine**, the refused one. Every app merges by this
7
+ * rule, so two crossing saves give the same text whichever app was refused.
8
+ *
9
+ * Words are never lost: a block both sides changed differently, or one side
10
+ * deleted while the other edited, **asks**, and while anything asks nothing of
11
+ * mine is saved. Everything else merges quietly.
12
+ *
13
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/merging-two-changes-to-one-text-never-loses-words.md
14
+ */
15
+ import {
16
+ type Block,
17
+ type BlockDocument,
18
+ documentText,
19
+ parseBlockDocument,
20
+ serializeBlockDocument,
21
+ } from './blocks.js'
22
+ import type { InlineTextNode } from './content.js'
23
+
24
+ /** The content format a block document is tagged with (§13.4). */
25
+ const BLOCKS_FORMAT = 'estiva-blocks-1'
26
+
27
+ /** One of the three texts, with the `content-format` its event carried. */
28
+ export interface MergeText {
29
+ value: string
30
+ /** `'estiva-blocks-1'` for a block document; anything else, or none, is one block. */
31
+ format?: string
32
+ }
33
+
34
+ /**
35
+ * A block the merge cannot settle without its person.
36
+ *
37
+ * - `changed-by-both`: both sides changed its own content, differently.
38
+ * - `edited-and-deleted`: one side deleted it, or the block it sits under,
39
+ * and the other changed, added or moved it there.
40
+ *
41
+ * `block` is the block's id, or `null` when the text is not a block document
42
+ * and so is one block. `theirs` and `mine` are each side's version as plain
43
+ * text, absent on the side that deleted it; `theirsBlock` and `mineBlock` are
44
+ * the blocks themselves, for a change plain text does not show (a heading's
45
+ * level).
46
+ */
47
+ export interface MergeAsk {
48
+ block: string | null
49
+ why: 'changed-by-both' | 'edited-and-deleted'
50
+ base?: string
51
+ theirs?: string
52
+ mine?: string
53
+ baseBlock?: Block
54
+ theirsBlock?: Block
55
+ mineBlock?: Block
56
+ }
57
+
58
+ export type TextMerge = { merged: MergeText; asks?: undefined } | { merged?: undefined; asks: MergeAsk[] }
59
+
60
+ export type BlockMerge = { merged: BlockDocument; asks?: undefined } | { merged?: undefined; asks: MergeAsk[] }
61
+
62
+ const isInlineRun = (content: unknown): content is InlineTextNode[] =>
63
+ Array.isArray(content) && content.every((n) => typeof n === 'object' && n !== null && (n as { type?: unknown }).type === 'text')
64
+
65
+ /** A node whose content holds blocks: every one of them has an id. */
66
+ const childBlocksOf = (block: Block): Block[] | undefined =>
67
+ Array.isArray(block.content) && block.content.length > 0 && !isInlineRun(block.content) &&
68
+ block.content.every((child) => typeof (child as Block).id === 'string' && (child as Block).id !== '')
69
+ ? (block.content as Block[])
70
+ : undefined
71
+
72
+ interface Placed {
73
+ block: Block
74
+ /** The id of the block it sits under, or `null` at the top. */
75
+ parent: string | null
76
+ /** Its own content, as JSON: type, attrs and every node in it that is not itself a block. */
77
+ own: string
78
+ }
79
+
80
+ interface Indexed {
81
+ byId: Map<string, Placed>
82
+ /** Each parent's children in order; `null` is the document. */
83
+ children: Map<string | null, string[]>
84
+ /** Every id in document order. */
85
+ order: string[]
86
+ }
87
+
88
+ function ownContentOf(block: Block): string {
89
+ const { id: _id, content, ...rest } = block
90
+ const own: Record<string, unknown> = { ...rest }
91
+ // A block's children are blocks of their own: where they sit is a move,
92
+ // what they say is theirs. Everything else in it is this block's words.
93
+ // An empty content is no words: an emptied list has not been rewritten.
94
+ if (content !== undefined && !childBlocksOf(block) && !(Array.isArray(content) && content.length === 0)) own.content = content
95
+ return stableJson(own)
96
+ }
97
+
98
+ /** JSON with object keys sorted, so an editor's key order is not a change. */
99
+ function stableJson(value: unknown): string {
100
+ if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
101
+ if (value && typeof value === 'object') {
102
+ const entries = Object.entries(value as Record<string, unknown>)
103
+ .filter(([, v]) => v !== undefined)
104
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
105
+ return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`).join(',')}}`
106
+ }
107
+ return JSON.stringify(value)
108
+ }
109
+
110
+ function indexOf(doc: BlockDocument): Indexed {
111
+ const byId = new Map<string, Placed>()
112
+ const children = new Map<string | null, string[]>([[null, []]])
113
+ const order: string[] = []
114
+ const walk = (blocks: Block[], parent: string | null) => {
115
+ for (const block of blocks) {
116
+ byId.set(block.id, { block, parent, own: ownContentOf(block) })
117
+ children.get(parent)!.push(block.id)
118
+ order.push(block.id)
119
+ children.set(block.id, [])
120
+ const kids = childBlocksOf(block)
121
+ if (kids) walk(kids, block.id)
122
+ }
123
+ }
124
+ walk(doc.content, null)
125
+ return { byId, children, order }
126
+ }
127
+
128
+ /**
129
+ * The blocks one side moved, against the base.
130
+ *
131
+ * A block is moved when its parent changed, or when, among the blocks under
132
+ * that parent that both the base and this side hold, it is outside the longest
133
+ * run still in the base's order — on a tie, the run whose first difference
134
+ * comes earlier in the base. So a neighbour added or deleted moves nothing, and
135
+ * moving one block moves only that one.
136
+ */
137
+ function movedOn(base: Indexed, side: Indexed): Set<string> {
138
+ const moved = new Set<string>()
139
+ for (const [id, placed] of side.byId) {
140
+ const was = base.byId.get(id)
141
+ if (was && was.parent !== placed.parent) moved.add(id)
142
+ }
143
+ for (const [parent, ids] of side.children) {
144
+ const baseIds = base.children.get(parent)
145
+ if (!baseIds) continue
146
+ const basePos = new Map(baseIds.map((id, i) => [id, i]))
147
+ // Under this parent on both sides, in this side's order, as base positions.
148
+ const shared = ids.filter((id) => basePos.has(id))
149
+ const seq = shared.map((id) => basePos.get(id)!)
150
+ for (const i of outsideLongestRun(seq)) moved.add(shared[i])
151
+ }
152
+ return moved
153
+ }
154
+
155
+ /**
156
+ * The indexes of `seq` outside its longest increasing run, choosing among
157
+ * equally long runs the one smallest in the base's order at its first
158
+ * difference.
159
+ */
160
+ function outsideLongestRun(seq: number[]): number[] {
161
+ const n = seq.length
162
+ // longest[i]: the longest increasing run starting at i.
163
+ const longest = new Array<number>(n).fill(1)
164
+ for (let i = n - 1; i >= 0; i--) {
165
+ for (let j = i + 1; j < n; j++) {
166
+ if (seq[j] > seq[i] && longest[j] + 1 > longest[i]) longest[i] = longest[j] + 1
167
+ }
168
+ }
169
+ const best = Math.max(0, ...longest)
170
+ const kept = new Set<number>()
171
+ let from = 0
172
+ let floor = -1
173
+ for (let need = best; need > 0; need--) {
174
+ let pick = -1
175
+ for (let j = from; j < n; j++) {
176
+ if (seq[j] > floor && longest[j] >= need && (pick === -1 || seq[j] < seq[pick])) pick = j
177
+ }
178
+ kept.add(pick)
179
+ floor = seq[pick]
180
+ from = pick + 1
181
+ }
182
+ return seq.map((_, i) => i).filter((i) => !kept.has(i))
183
+ }
184
+
185
+ /** A block as plain text, its own words only (not the blocks inside it). */
186
+ function ownText(block: Block | undefined): string | undefined {
187
+ if (!block) return undefined
188
+ const kids = childBlocksOf(block)
189
+ const alone: Block = kids ? { ...block, content: undefined } : block
190
+ return documentText({ type: 'doc', content: [alone] })
191
+ }
192
+
193
+ /** A block with no blocks inside it, its own content kept: the merge places its children. */
194
+ function shellOf(block: Block): Block {
195
+ return childBlocksOf(block) ? { ...block, content: [] } : { ...block }
196
+ }
197
+
198
+ /**
199
+ * Merge two block documents that both started from `base` — §13.3's rule.
200
+ *
201
+ * Returns the merged document, keeping every block id the merge kept, or the
202
+ * blocks that ask. When anything asks, there is no merged document: nothing of
203
+ * mine is saved.
204
+ */
205
+ export function mergeBlockDocuments(base: BlockDocument, theirs: BlockDocument, mine: BlockDocument): BlockMerge {
206
+ const B = indexOf(base)
207
+ const T = indexOf(theirs)
208
+ const M = indexOf(mine)
209
+ const movedT = movedOn(B, T)
210
+ const movedM = movedOn(B, M)
211
+ const asks: MergeAsk[] = []
212
+ const ask = (id: string, why: MergeAsk['why']) => {
213
+ const b = B.byId.get(id)?.block
214
+ const t = T.byId.get(id)?.block
215
+ const m = M.byId.get(id)?.block
216
+ asks.push({
217
+ block: id,
218
+ why,
219
+ ...(b ? { base: ownText(b), baseBlock: b } : {}),
220
+ ...(t ? { theirs: ownText(t), theirsBlock: t } : {}),
221
+ ...(m ? { mine: ownText(m), mineBlock: m } : {}),
222
+ })
223
+ }
224
+
225
+ // What each kept block says, and the blocks the merge deletes.
226
+ const content = new Map<string, Block>()
227
+ const deleted = new Set<string>()
228
+ // In the base's order, so blocks that ask come in the order the text had.
229
+ const ids = new Set([...B.order, ...T.order, ...M.order])
230
+ for (const id of ids) {
231
+ const b = B.byId.get(id)
232
+ const t = T.byId.get(id)
233
+ const m = M.byId.get(id)
234
+ if (!b) {
235
+ // Added. Both adding one id is one block, kept once when they agree.
236
+ if (t && m && t.own !== m.own) ask(id, 'changed-by-both')
237
+ else content.set(id, shellOf((t ?? m)!.block))
238
+ continue
239
+ }
240
+ const changedT = !!t && t.own !== b.own
241
+ const changedM = !!m && m.own !== b.own
242
+ if (!t || !m) {
243
+ // Deleted on one side or both. Against an edit it asks; against a move
244
+ // or nothing, it is deleted: a move changes no words.
245
+ if ((!t && changedM) || (!m && changedT)) ask(id, 'edited-and-deleted')
246
+ else deleted.add(id)
247
+ continue
248
+ }
249
+ if (changedT && changedM && t.own !== m.own) {
250
+ ask(id, 'changed-by-both')
251
+ continue
252
+ }
253
+ content.set(id, shellOf(changedM && !changedT ? m.block : t.block))
254
+ }
255
+
256
+ // The order is theirs, less what the merge deletes.
257
+ const kids = new Map<string | null, string[]>()
258
+ const parentOf = new Map<string, string | null>()
259
+ for (const [parent, list] of T.children) {
260
+ if (parent !== null && !content.has(parent)) continue
261
+ kids.set(parent, list.filter((id) => content.has(id)))
262
+ for (const id of kids.get(parent)!) parentOf.set(id, parent)
263
+ }
264
+ for (const id of content.keys()) if (!kids.has(id)) kids.set(id, [])
265
+
266
+ // A block theirs kept under a parent the merge deletes: theirs added, moved
267
+ // or changed it there against mine's delete.
268
+ for (const [parent, list] of T.children) {
269
+ if (parent === null || content.has(parent) || !deleted.has(parent)) continue
270
+ for (const id of list) if (content.has(id) && touchedBy(id, B, T, movedT)) ask(id, 'edited-and-deleted')
271
+ }
272
+
273
+ const addedByTheirs = (id: string) => T.byId.has(id) && !B.byId.has(id) && !M.byId.has(id)
274
+
275
+ // Then each block mine moved or added, in mine's order, is taken out and
276
+ // placed after the nearest block before it in mine that the merge keeps
277
+ // (and after any blocks theirs added right behind that one), or first under
278
+ // its parent, after theirs' additions there.
279
+ for (const id of M.order) {
280
+ if (!content.has(id)) continue
281
+ const addedByMine = !B.byId.has(id) && !T.byId.has(id)
282
+ const mineMoved = movedM.has(id) && !movedT.has(id)
283
+ if (!addedByMine && !mineMoved) continue
284
+ const parent = M.byId.get(id)!.parent
285
+ if (parent !== null && !content.has(parent)) {
286
+ ask(id, 'edited-and-deleted')
287
+ continue
288
+ }
289
+ // Mine puts it under a block theirs has meanwhile put inside it: both
290
+ // moved, so theirs stands rather than a loop that holds neither.
291
+ let above: string | null | undefined = parent
292
+ while (above != null && above !== id) above = parentOf.get(above)
293
+ if (above === id) continue
294
+ if (parentOf.has(id)) {
295
+ const from = kids.get(parentOf.get(id)!)!
296
+ from.splice(from.indexOf(id), 1)
297
+ }
298
+ const under = kids.get(parent)!
299
+ const siblings = M.children.get(parent)!
300
+ let at = 0
301
+ for (let i = siblings.indexOf(id) - 1; i >= 0; i--) {
302
+ const before = under.indexOf(siblings[i])
303
+ if (before !== -1) {
304
+ at = before + 1
305
+ break
306
+ }
307
+ }
308
+ while (at < under.length && addedByTheirs(under[at])) at++
309
+ under.splice(at, 0, id)
310
+ parentOf.set(id, parent)
311
+ }
312
+
313
+ if (asks.length) return { asks: dedupe(asks) }
314
+
315
+ const placed = new Set<string>()
316
+ const build = (parent: string | null): Block[] =>
317
+ kids.get(parent)!.map((id) => {
318
+ placed.add(id)
319
+ const block = content.get(id)!
320
+ const inner = build(id)
321
+ return inner.length || wasParent(id, B, T, M) ? { ...block, content: inner } : block
322
+ })
323
+ const merged: BlockDocument = { ...theirs, content: build(null) }
324
+ // Never lose words: a block the merge kept but could not place asks.
325
+ for (const id of content.keys()) if (!placed.has(id)) ask(id, 'changed-by-both')
326
+ if (asks.length) return { asks: dedupe(asks) }
327
+ return { merged }
328
+ }
329
+
330
+ /** Whether a block's own content held blocks on any side: an emptied list stays a list. */
331
+ function wasParent(id: string, ...sides: Indexed[]): boolean {
332
+ return sides.some((side) => {
333
+ const block = side.byId.get(id)?.block
334
+ return !!block && !!childBlocksOf(block)
335
+ })
336
+ }
337
+
338
+ function touchedBy(id: string, base: Indexed, side: Indexed, moved: Set<string>): boolean {
339
+ const b = base.byId.get(id)
340
+ const s = side.byId.get(id)
341
+ return !b || moved.has(id) || (!!s && s.own !== b.own)
342
+ }
343
+
344
+ function dedupe(asks: MergeAsk[]): MergeAsk[] {
345
+ const seen = new Set<string | null>()
346
+ return asks.filter((a) => (seen.has(a.block) ? false : (seen.add(a.block), true)))
347
+ }
348
+
349
+ function asDocument(text: MergeText): BlockDocument | undefined {
350
+ if (text.format !== BLOCKS_FORMAT) return undefined
351
+ try {
352
+ return parseBlockDocument(text.value)
353
+ } catch {
354
+ return undefined
355
+ }
356
+ }
357
+
358
+ /**
359
+ * Merge three texts by §13.3's rule.
360
+ *
361
+ * When all three are block documents, block by block; otherwise the text is
362
+ * one block, so a change by both sides asks unless the two are equal. Mine
363
+ * unchanged from the base gives theirs, and theirs unchanged gives mine.
364
+ */
365
+ export function mergeTexts(base: MergeText, theirs: MergeText, mine: MergeText): TextMerge {
366
+ const same = (a: MergeText, b: MergeText) => a.value === b.value && (a.format ?? '') === (b.format ?? '')
367
+ if (same(mine, base) || same(mine, theirs)) return { merged: theirs }
368
+ if (same(theirs, base)) return { merged: mine }
369
+ const docs = [base, theirs, mine].map(asDocument)
370
+ if (docs.every((d) => d !== undefined)) {
371
+ const [b, t, m] = docs as BlockDocument[]
372
+ const result = mergeBlockDocuments(b, t, m)
373
+ if (result.asks) return result
374
+ return { merged: { value: serializeBlockDocument(result.merged), format: BLOCKS_FORMAT } }
375
+ }
376
+ const plain = (text: MergeText) => {
377
+ const doc = asDocument(text)
378
+ return doc ? documentText(doc) : text.value
379
+ }
380
+ return { asks: [{ block: null, why: 'changed-by-both', base: plain(base), theirs: plain(theirs), mine: plain(mine) }] }
381
+ }