@aionbuilders/nabu 0.1.0-beta.0 → 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/CHANGELOG.md +523 -0
- package/LICENSE +21 -0
- package/README.md +72 -341
- package/dist/behaviors/text/RichText.svelte +24 -4
- package/dist/behaviors/text/markdown-shortcuts.extension.d.ts +3 -0
- package/dist/behaviors/text/markdown-shortcuts.extension.js +35 -10
- package/dist/behaviors/text/markdown-syntax.d.ts +42 -0
- package/dist/behaviors/text/markdown-syntax.js +81 -0
- package/dist/behaviors/text/rich-text.extension.d.ts +3 -0
- package/dist/behaviors/text/rich-text.extension.js +95 -38
- package/dist/behaviors/text/text.behavior.svelte.d.ts +199 -48
- package/dist/behaviors/text/text.behavior.svelte.js +549 -83
- package/dist/behaviors/text/typography.extension.d.ts +2 -1
- package/dist/behaviors/text/typography.extension.js +3 -2
- package/dist/blocks/BlockList.svelte +48 -0
- package/dist/blocks/BlockList.svelte.d.ts +17 -0
- package/dist/blocks/Nabu.svelte +169 -25
- package/dist/blocks/Nabu.svelte.d.ts +13 -0
- package/dist/blocks/block.extension.d.ts +3 -0
- package/dist/blocks/block.extension.js +4 -7
- package/dist/blocks/block.svelte.d.ts +350 -86
- package/dist/blocks/block.svelte.js +370 -59
- package/dist/blocks/blockquote/Blockquote.svelte +1 -2
- package/dist/blocks/blockquote/blockquote.extension.d.ts +4 -1
- package/dist/blocks/blockquote/blockquote.extension.js +14 -5
- package/dist/blocks/blockquote/blockquote.svelte.d.ts +19 -11
- package/dist/blocks/blockquote/blockquote.svelte.js +58 -13
- package/dist/blocks/callout/Callout.svelte +6 -8
- package/dist/blocks/callout/callout.extension.d.ts +4 -1
- package/dist/blocks/callout/callout.extension.js +19 -3
- package/dist/blocks/callout/callout.svelte.d.ts +5 -3
- package/dist/blocks/callout/callout.svelte.js +11 -6
- package/dist/blocks/chunks.d.ts +49 -0
- package/dist/blocks/chunks.js +90 -0
- package/dist/blocks/code/Code.svelte +7 -8
- package/dist/blocks/code/code.extension.d.ts +4 -1
- package/dist/blocks/code/code.extension.js +22 -2
- package/dist/blocks/code/code.svelte.d.ts +9 -2
- package/dist/blocks/code/code.svelte.js +49 -25
- package/dist/blocks/container.utils.d.ts +85 -13
- package/dist/blocks/container.utils.js +338 -178
- package/dist/blocks/dialogue/Dialogue.svelte +8 -4
- package/dist/blocks/dialogue/dialogue.svelte.d.ts +33 -2
- package/dist/blocks/dialogue/dialogue.svelte.js +58 -4
- package/dist/blocks/dialogue/hooks/onBeforeInput.hook.d.ts +2 -2
- package/dist/blocks/dialogue/hooks/onBeforeInput.hook.js +6 -4
- package/dist/blocks/dialogue/index.d.ts +12 -1
- package/dist/blocks/dialogue/index.js +51 -35
- package/dist/blocks/divider/divider.extension.d.ts +23 -1
- package/dist/blocks/divider/divider.extension.js +85 -19
- package/dist/blocks/divider/divider.svelte.d.ts +7 -2
- package/dist/blocks/divider/divider.svelte.js +9 -4
- package/dist/blocks/file/File.svelte +13 -6
- package/dist/blocks/file/file.extension.d.ts +4 -1
- package/dist/blocks/file/file.extension.js +9 -1
- package/dist/blocks/file/file.svelte.d.ts +3 -3
- package/dist/blocks/file/file.svelte.js +20 -14
- package/dist/blocks/heading/Heading.svelte +1 -2
- package/dist/blocks/heading/heading.svelte.d.ts +23 -11
- package/dist/blocks/heading/heading.svelte.js +68 -13
- package/dist/blocks/heading/hooks/onBeforeInput.hook.js +7 -5
- package/dist/blocks/heading/index.d.ts +2 -2
- package/dist/blocks/heading/index.js +33 -8
- package/dist/blocks/image/Image.svelte +5 -2
- package/dist/blocks/image/image.extension.d.ts +4 -1
- package/dist/blocks/image/image.extension.js +9 -1
- package/dist/blocks/image/image.svelte.d.ts +17 -6
- package/dist/blocks/image/image.svelte.js +33 -11
- package/dist/blocks/index.d.ts +1 -1
- package/dist/blocks/index.js +1 -1
- package/dist/blocks/list/List.svelte +1 -0
- package/dist/blocks/list/ListItem.svelte +1 -0
- package/dist/blocks/list/convert.d.ts +20 -0
- package/dist/blocks/list/convert.js +92 -0
- package/dist/blocks/list/hooks/onBeforeInput.hook.js +49 -28
- package/dist/blocks/list/html-flat.d.ts +78 -0
- package/dist/blocks/list/html-flat.js +244 -0
- package/dist/blocks/list/indent.d.ts +86 -0
- package/dist/blocks/list/indent.js +205 -0
- package/dist/blocks/list/index.d.ts +6 -3
- package/dist/blocks/list/index.js +42 -31
- package/dist/blocks/list/list-item.svelte.d.ts +31 -17
- package/dist/blocks/list/list-item.svelte.js +99 -100
- package/dist/blocks/list/list.behavior.svelte.d.ts +4 -1
- package/dist/blocks/list/list.behavior.svelte.js +6 -1
- package/dist/blocks/list/list.svelte.d.ts +89 -18
- package/dist/blocks/list/list.svelte.js +129 -125
- package/dist/blocks/list/markdown.d.ts +149 -0
- package/dist/blocks/list/markdown.js +442 -0
- package/dist/blocks/list/normalize.d.ts +11 -0
- package/dist/blocks/list/normalize.js +396 -0
- package/dist/blocks/list/paste.d.ts +45 -0
- package/dist/blocks/list/paste.js +242 -0
- package/dist/blocks/list/step-back.d.ts +24 -0
- package/dist/blocks/list/step-back.js +87 -0
- package/dist/blocks/list/to-list.d.ts +7 -0
- package/dist/blocks/list/to-list.js +44 -0
- package/dist/blocks/list/todos-toggle.d.ts +20 -0
- package/dist/blocks/list/todos-toggle.js +48 -0
- package/dist/blocks/media/markdown.d.ts +12 -0
- package/dist/blocks/media/markdown.js +26 -0
- package/dist/blocks/media/media-block.svelte.d.ts +77 -2
- package/dist/blocks/media/media-block.svelte.js +124 -12
- package/dist/blocks/media/media.helpers.d.ts +6 -1
- package/dist/blocks/media/media.helpers.js +43 -6
- package/dist/blocks/megablock.svelte.d.ts +50 -19
- package/dist/blocks/megablock.svelte.js +114 -74
- package/dist/blocks/move.d.ts +23 -0
- package/dist/blocks/move.js +92 -0
- package/dist/blocks/nabu.svelte.d.ts +764 -71
- package/dist/blocks/nabu.svelte.js +1746 -189
- package/dist/blocks/paragraph/Paragraph.svelte +1 -2
- package/dist/blocks/paragraph/index.d.ts +2 -2
- package/dist/blocks/paragraph/index.js +35 -13
- package/dist/blocks/paragraph/paragraph.svelte.d.ts +46 -14
- package/dist/blocks/paragraph/paragraph.svelte.js +77 -16
- package/dist/blocks/paragraph/table.html.d.ts +9 -0
- package/dist/blocks/paragraph/table.html.js +111 -0
- package/dist/blocks/paragraph/table.markdown.d.ts +32 -0
- package/dist/blocks/paragraph/table.markdown.js +90 -0
- package/dist/blocks/region/Region.svelte +264 -0
- package/dist/blocks/region/Region.svelte.d.ts +11 -0
- package/dist/blocks/region/actions.d.ts +135 -0
- package/dist/blocks/region/actions.js +402 -0
- package/dist/blocks/region/close.d.ts +35 -0
- package/dist/blocks/region/close.js +130 -0
- package/dist/blocks/region/commands.d.ts +6 -0
- package/dist/blocks/region/commands.js +277 -0
- package/dist/blocks/region/create.d.ts +72 -0
- package/dist/blocks/region/create.js +208 -0
- package/dist/blocks/region/end-marker.d.ts +35 -0
- package/dist/blocks/region/end-marker.js +51 -0
- package/dist/blocks/region/facts.d.ts +69 -0
- package/dist/blocks/region/facts.js +152 -0
- package/dist/blocks/region/format.d.ts +91 -0
- package/dist/blocks/region/format.js +260 -0
- package/dist/blocks/region/index.d.ts +14 -0
- package/dist/blocks/region/index.js +14 -0
- package/dist/blocks/region/insert.d.ts +59 -0
- package/dist/blocks/region/insert.js +102 -0
- package/dist/blocks/region/messages.d.ts +254 -0
- package/dist/blocks/region/messages.js +131 -0
- package/dist/blocks/region/normalize.d.ts +7 -0
- package/dist/blocks/region/normalize.js +170 -0
- package/dist/blocks/region/region.extension.d.ts +58 -0
- package/dist/blocks/region/region.extension.js +119 -0
- package/dist/blocks/region/region.svelte.d.ts +221 -0
- package/dist/blocks/region/region.svelte.js +582 -0
- package/dist/blocks/region/regions.svelte.d.ts +141 -0
- package/dist/blocks/region/regions.svelte.js +276 -0
- package/dist/blocks/region/serialize.d.ts +57 -0
- package/dist/blocks/region/serialize.js +112 -0
- package/dist/blocks/region/types.d.ts +255 -0
- package/dist/blocks/region/types.js +204 -0
- package/dist/blocks/selection.svelte.d.ts +106 -8
- package/dist/blocks/selection.svelte.js +622 -74
- package/dist/blocks/subthread.d.ts +80 -0
- package/dist/blocks/subthread.js +167 -0
- package/dist/blocks/text-block.svelte.d.ts +34 -13
- package/dist/blocks/text-block.svelte.js +42 -8
- package/dist/blocks/toggle/Toggle.svelte +4 -15
- package/dist/blocks/toggle/markdown.d.ts +20 -0
- package/dist/blocks/toggle/markdown.js +112 -0
- package/dist/blocks/toggle/toggle.extension.d.ts +4 -1
- package/dist/blocks/toggle/toggle.extension.js +6 -0
- package/dist/blocks/toggle/toggle.svelte.d.ts +54 -7
- package/dist/blocks/toggle/toggle.svelte.js +134 -34
- package/dist/blocks/undo-selection.d.ts +175 -0
- package/dist/blocks/undo-selection.js +360 -0
- package/dist/blocks/video/Video.svelte +5 -2
- package/dist/blocks/video/video.extension.d.ts +4 -1
- package/dist/blocks/video/video.extension.js +9 -1
- package/dist/blocks/video/video.svelte.d.ts +6 -5
- package/dist/blocks/video/video.svelte.js +18 -9
- package/dist/extend.d.ts +55 -0
- package/dist/extend.js +88 -0
- package/dist/files/assets.clipboard.d.ts +77 -0
- package/dist/files/assets.clipboard.js +152 -0
- package/dist/files/files.svelte.d.ts +321 -19
- package/dist/files/files.svelte.js +847 -43
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +3 -1
- package/dist/files/outbox.d.ts +69 -0
- package/dist/files/outbox.js +48 -0
- package/dist/files/status.d.ts +65 -0
- package/dist/files/status.js +87 -0
- package/dist/files/store.d.ts +97 -0
- package/dist/files/store.js +65 -0
- package/dist/files/uploads.svelte.d.ts +174 -0
- package/dist/files/uploads.svelte.js +504 -0
- package/dist/index.d.ts +68 -9
- package/dist/index.js +117 -10
- package/dist/nabu-theme.css +21 -1
- package/dist/paste/html.paste.d.ts +74 -3
- package/dist/paste/html.paste.js +550 -86
- package/dist/paste/markdown-inline.d.ts +86 -0
- package/dist/paste/markdown-inline.js +528 -0
- package/dist/paste/markdown.paste.d.ts +2 -8
- package/dist/paste/markdown.paste.js +78 -94
- package/dist/paste/nabu.paste.d.ts +3 -0
- package/dist/paste/nabu.paste.js +29 -3
- package/dist/paste/plain-text.paste.d.ts +2 -2
- package/dist/paste/plain-text.paste.js +3 -3
- package/dist/persistence/asset-store.d.ts +51 -0
- package/dist/persistence/asset-store.js +103 -0
- package/dist/persistence/autosave.d.ts +53 -0
- package/dist/persistence/autosave.js +62 -0
- package/dist/persistence/compact.d.ts +162 -0
- package/dist/persistence/compact.js +141 -0
- package/dist/persistence/history.d.ts +77 -0
- package/dist/persistence/history.js +176 -0
- package/dist/persistence/indexeddb.d.ts +190 -4
- package/dist/persistence/indexeddb.js +333 -29
- package/dist/persistence/merge.d.ts +38 -0
- package/dist/persistence/merge.js +36 -0
- package/dist/persistence/outbox.d.ts +25 -0
- package/dist/persistence/outbox.js +40 -0
- package/dist/persistence/persistence.d.ts +70 -9
- package/dist/persistence/persistence.js +507 -35
- package/dist/persistence/recovery.d.ts +79 -0
- package/dist/persistence/recovery.js +79 -0
- package/dist/persistence/release.d.ts +34 -0
- package/dist/persistence/release.js +64 -0
- package/dist/persistence/state.svelte.d.ts +53 -0
- package/dist/persistence/state.svelte.js +48 -0
- package/dist/persistence/sync.d.ts +39 -0
- package/dist/persistence/sync.js +138 -0
- package/dist/persistence/tail.d.ts +42 -0
- package/dist/persistence/tail.js +103 -0
- package/dist/presets.d.ts +29 -26
- package/dist/presets.js +35 -13
- package/dist/themes/atelier.css +318 -0
- package/dist/ui/CommandChooser.svelte +153 -0
- package/dist/ui/CommandChooser.svelte.d.ts +13 -0
- package/dist/ui/CommandInvite.svelte +99 -0
- package/dist/ui/CommandInvite.svelte.d.ts +12 -0
- package/dist/ui/DragHandle.svelte +97 -21
- package/dist/ui/FloatingToolbar.svelte +75 -27
- package/dist/ui/FloatingToolbar.svelte.d.ts +10 -0
- package/dist/ui/SlashMenu.svelte +147 -15
- package/dist/ui/SlashMenu.svelte.d.ts +20 -0
- package/dist/ui/anchor.d.ts +112 -0
- package/dist/ui/anchor.js +136 -0
- package/dist/ui/index.d.ts +7 -1
- package/dist/ui/index.js +12 -1
- package/dist/ui/slash-menu.svelte.d.ts +79 -7
- package/dist/ui/slash-menu.svelte.js +85 -51
- package/dist/utils/command-confirm.svelte.d.ts +349 -0
- package/dist/utils/command-confirm.svelte.js +673 -0
- package/dist/utils/commands.d.ts +328 -0
- package/dist/utils/commands.js +416 -0
- package/dist/utils/dom-scope.d.ts +14 -0
- package/dist/utils/dom-scope.js +20 -0
- package/dist/utils/drop.d.ts +160 -0
- package/dist/utils/drop.js +305 -0
- package/dist/utils/extensions.d.ts +439 -45
- package/dist/utils/extensions.js +271 -29
- package/dist/utils/html.d.ts +44 -0
- package/dist/utils/html.js +183 -0
- package/dist/utils/index.d.ts +3 -0
- package/dist/utils/index.js +3 -0
- package/dist/utils/keys.d.ts +120 -0
- package/dist/utils/keys.js +248 -0
- package/dist/utils/links.d.ts +22 -0
- package/dist/utils/links.js +34 -0
- package/dist/utils/placeholders.d.ts +81 -3
- package/dist/utils/placeholders.js +73 -3
- package/dist/utils/selection.svelte.d.ts +47 -19
- package/dist/utils/selection.svelte.js +60 -10
- package/dist/utils/spellcheck.d.ts +9 -0
- package/dist/utils/spellcheck.js +17 -0
- package/dist/utils/tab.d.ts +31 -0
- package/dist/utils/tab.js +117 -0
- package/dist/utils/words.d.ts +7 -0
- package/dist/utils/words.js +62 -0
- package/dist/vite.d.ts +9 -3
- package/dist/vite.js +19 -8
- package/package.json +54 -20
- package/dist/blocks/variable.svelte.d.ts +0 -47
- package/dist/blocks/variable.svelte.js +0 -51
- package/dist/blocks/zone/TemplateEditor.svelte +0 -308
- package/dist/blocks/zone/TemplateEditor.svelte.d.ts +0 -11
- package/dist/blocks/zone/Zone.svelte +0 -272
- package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
- package/dist/blocks/zone/ZoneEditor.svelte +0 -289
- package/dist/blocks/zone/ZoneEditor.svelte.d.ts +0 -11
- package/dist/blocks/zone/ZoneTemplatesList.svelte +0 -188
- package/dist/blocks/zone/ZoneTemplatesList.svelte.d.ts +0 -11
- package/dist/blocks/zone/hooks/onBeforeInput.hook.d.ts +0 -3
- package/dist/blocks/zone/hooks/onBeforeInput.hook.js +0 -30
- package/dist/blocks/zone/index.d.ts +0 -2
- package/dist/blocks/zone/index.js +0 -2
- package/dist/blocks/zone/zone.extension.d.ts +0 -2
- package/dist/blocks/zone/zone.extension.js +0 -237
- package/dist/blocks/zone/zone.svelte.d.ts +0 -221
- package/dist/blocks/zone/zone.svelte.js +0 -608
- package/dist/overlays/context/Context.svelte +0 -182
- package/dist/overlays/context/Context.svelte.d.ts +0 -17
- package/dist/overlays/context/collect.d.ts +0 -17
- package/dist/overlays/context/collect.js +0 -33
- package/dist/overlays/context/context.extension.d.ts +0 -2
- package/dist/overlays/context/context.extension.js +0 -8
- package/dist/overlays/context/context.svelte.d.ts +0 -82
- package/dist/overlays/context/context.svelte.js +0 -159
- package/dist/overlays/context/index.d.ts +0 -3
- package/dist/overlays/context/index.js +0 -3
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
/** @import { Nabu } from '../blocks/nabu.svelte.js' */
|
|
2
|
+
/** @import { AssetStore } from '../files/store.js' */
|
|
3
|
+
/** @import { CompactOptions } from './history.js' */
|
|
4
|
+
/**
|
|
5
|
+
* @typedef {'busy' | 'detached' | 'pending-uploads' | 'unsaved-changes' | 'nothing-to-compact' | 'archive-failed' | 'verification-failed' | 'save-failed' | 'failed'} CompactRefusal
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
|
|
9
|
+
* @typedef {Object} CompactResult
|
|
10
|
+
* @property {boolean} compacted
|
|
11
|
+
* @property {CompactRefusal} [reason] why nothing was compacted
|
|
12
|
+
* @property {unknown} [error] the error behind `archive-failed` / `save-failed` / `failed`
|
|
13
|
+
* @property {number} [bytesBefore] size of the complete snapshot (what `onBeforeCompact` received)
|
|
14
|
+
* @property {number} [bytesAfter] size of the compacted snapshot that was saved
|
|
15
|
+
* @property {string[]} [released] files (`sha256-…`) no kept version references any more (removed from this document's index)
|
|
16
|
+
* @property {string[]} [deleted] the released files whose bytes were deleted from the store (no other document used them)
|
|
17
|
+
* @property {string[]} [skipped] released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
|
|
18
|
+
* this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
|
|
19
|
+
* @property {Uint8Array} [snapshot] the compacted (shallow) snapshot that was saved
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* The persisted editor's side of a compaction (see {@link runCompaction}).
|
|
23
|
+
* @typedef {Object} CompactContext
|
|
24
|
+
* @property {Nabu} nabu
|
|
25
|
+
* @property {AssetStore} store
|
|
26
|
+
* @property {boolean} compacting a compaction is running
|
|
27
|
+
* @property {() => { peer: `${number}`, counter: number }[] | undefined} base frontiers of the previous compaction made by this session, if any
|
|
28
|
+
* @property {() => boolean} isDirty whether the document has changes that were not saved yet
|
|
29
|
+
* @property {() => Promise<void>} flush save now
|
|
30
|
+
* @property {<T>(fn: () => Promise<T>) => Promise<T>} lock run `fn` with the saves held back (they queue behind it)
|
|
31
|
+
* @property {(snapshot: Uint8Array, frontiers: { peer: `${number}`, counter: number }[], key: string) => Promise<void>} commit
|
|
32
|
+
* write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
|
|
33
|
+
* @property {(doc: import('loro-crdt').LoroDoc) => string} versionKey
|
|
34
|
+
* @property {() => Promise<Set<string>>} candidates the files this document lists: its index plus the ones a previous release skipped
|
|
35
|
+
* @property {() => Set<string>} held files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
|
|
36
|
+
* @property {(hashes: Iterable<string>) => void} setHeld replace that set
|
|
37
|
+
* @property {() => Promise<void>} saveRefs write `docRefs` (index + held)
|
|
38
|
+
*/
|
|
39
|
+
/**
|
|
40
|
+
* Compact the history of a persisted document (ADR 014 §3.6). Every safeguard is here:
|
|
41
|
+
*
|
|
42
|
+
* 1. only when called (the caller decides: explicit `nabu.compact()` or `history: { mode: 'compact' }` at open);
|
|
43
|
+
* 2. REFUSES (`{ compacted: false, reason }`, no throw, nothing dropped) when a file upload is pending / running
|
|
44
|
+
* (`pending-uploads`: the local copy is the only copy), when the document has unsaved or uncommitted changes
|
|
45
|
+
* (`unsaved-changes`), when it is checked out to an old version (`detached`), or when another compaction runs (`busy`);
|
|
46
|
+
* 3. the kept version is chosen by {@link retentionFrontiers} (timestamps of the changes); nothing to drop = `nothing-to-compact`;
|
|
47
|
+
* 4. `onBeforeCompact(fullSnapshot)` is awaited BEFORE anything is changed or written; a throw / rejection ABORTS (`archive-failed`).
|
|
48
|
+
* The kept version is fixed at the same instant as that snapshot, so everything dropped is in the archive;
|
|
49
|
+
* 5. the compacted snapshot is a Loro SHALLOW snapshot at the kept version; it is checked (imported in a scratch document and
|
|
50
|
+
* compared with the live state) before being written, then saved; only then are files released;
|
|
51
|
+
* 6. files no kept version references are removed from the document's index and released ({@link releaseFiles}); bytes recently
|
|
52
|
+
* added (grace period, multi-tab safety) are skipped and reconsidered next time;
|
|
53
|
+
* 7. the undo stack is cleared (its steps could point at history that is gone / files that were released).
|
|
54
|
+
*
|
|
55
|
+
* The live in-memory document is NOT swapped (Loro cannot trim a document in place): it keeps its full history until the editor
|
|
56
|
+
* is opened again; from now on every save of this editor is a shallow snapshot at the kept version (see `persistence.js`).
|
|
57
|
+
* @param {CompactContext} ctx
|
|
58
|
+
* @param {CompactOptions} options
|
|
59
|
+
* @param {{ flush?: boolean }} [internal] `flush`: save pending changes first (used when opening, never an unsaved-changes refusal then)
|
|
60
|
+
* @returns {Promise<CompactResult>}
|
|
61
|
+
* @throws {TypeError} when `options` is invalid (`retain` is required)
|
|
62
|
+
*/
|
|
63
|
+
export function runCompaction(ctx: CompactContext, options: CompactOptions, { flush }?: {
|
|
64
|
+
flush?: boolean;
|
|
65
|
+
}): Promise<CompactResult>;
|
|
66
|
+
export type CompactRefusal = "busy" | "detached" | "pending-uploads" | "unsaved-changes" | "nothing-to-compact" | "archive-failed" | "verification-failed" | "save-failed" | "failed";
|
|
67
|
+
/**
|
|
68
|
+
* What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
|
|
69
|
+
*/
|
|
70
|
+
export type CompactResult = {
|
|
71
|
+
compacted: boolean;
|
|
72
|
+
/**
|
|
73
|
+
* why nothing was compacted
|
|
74
|
+
*/
|
|
75
|
+
reason?: CompactRefusal | undefined;
|
|
76
|
+
/**
|
|
77
|
+
* the error behind `archive-failed` / `save-failed` / `failed`
|
|
78
|
+
*/
|
|
79
|
+
error?: unknown;
|
|
80
|
+
/**
|
|
81
|
+
* size of the complete snapshot (what `onBeforeCompact` received)
|
|
82
|
+
*/
|
|
83
|
+
bytesBefore?: number | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* size of the compacted snapshot that was saved
|
|
86
|
+
*/
|
|
87
|
+
bytesAfter?: number | undefined;
|
|
88
|
+
/**
|
|
89
|
+
* files (`sha256-…`) no kept version references any more (removed from this document's index)
|
|
90
|
+
*/
|
|
91
|
+
released?: string[] | undefined;
|
|
92
|
+
/**
|
|
93
|
+
* the released files whose bytes were deleted from the store (no other document used them)
|
|
94
|
+
*/
|
|
95
|
+
deleted?: string[] | undefined;
|
|
96
|
+
/**
|
|
97
|
+
* released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
|
|
98
|
+
* this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
|
|
99
|
+
*/
|
|
100
|
+
skipped?: string[] | undefined;
|
|
101
|
+
/**
|
|
102
|
+
* the compacted (shallow) snapshot that was saved
|
|
103
|
+
*/
|
|
104
|
+
snapshot?: Uint8Array<ArrayBufferLike> | undefined;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* The persisted editor's side of a compaction (see {@link runCompaction}).
|
|
108
|
+
*/
|
|
109
|
+
export type CompactContext = {
|
|
110
|
+
nabu: Nabu;
|
|
111
|
+
store: AssetStore;
|
|
112
|
+
/**
|
|
113
|
+
* a compaction is running
|
|
114
|
+
*/
|
|
115
|
+
compacting: boolean;
|
|
116
|
+
/**
|
|
117
|
+
* frontiers of the previous compaction made by this session, if any
|
|
118
|
+
*/
|
|
119
|
+
base: () => {
|
|
120
|
+
peer: `${number}`;
|
|
121
|
+
counter: number;
|
|
122
|
+
}[] | undefined;
|
|
123
|
+
/**
|
|
124
|
+
* whether the document has changes that were not saved yet
|
|
125
|
+
*/
|
|
126
|
+
isDirty: () => boolean;
|
|
127
|
+
/**
|
|
128
|
+
* save now
|
|
129
|
+
*/
|
|
130
|
+
flush: () => Promise<void>;
|
|
131
|
+
/**
|
|
132
|
+
* run `fn` with the saves held back (they queue behind it)
|
|
133
|
+
*/
|
|
134
|
+
lock: <T>(fn: () => Promise<T>) => Promise<T>;
|
|
135
|
+
/**
|
|
136
|
+
* write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
|
|
137
|
+
*/
|
|
138
|
+
commit: (snapshot: Uint8Array, frontiers: {
|
|
139
|
+
peer: `${number}`;
|
|
140
|
+
counter: number;
|
|
141
|
+
}[], key: string) => Promise<void>;
|
|
142
|
+
versionKey: (doc: import("loro-crdt").LoroDoc) => string;
|
|
143
|
+
/**
|
|
144
|
+
* the files this document lists: its index plus the ones a previous release skipped
|
|
145
|
+
*/
|
|
146
|
+
candidates: () => Promise<Set<string>>;
|
|
147
|
+
/**
|
|
148
|
+
* files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
|
|
149
|
+
*/
|
|
150
|
+
held: () => Set<string>;
|
|
151
|
+
/**
|
|
152
|
+
* replace that set
|
|
153
|
+
*/
|
|
154
|
+
setHeld: (hashes: Iterable<string>) => void;
|
|
155
|
+
/**
|
|
156
|
+
* write `docRefs` (index + held)
|
|
157
|
+
*/
|
|
158
|
+
saveRefs: () => Promise<void>;
|
|
159
|
+
};
|
|
160
|
+
import type { CompactOptions } from './history.js';
|
|
161
|
+
import type { Nabu } from '../blocks/nabu.svelte.js';
|
|
162
|
+
import type { AssetStore } from '../files/store.js';
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { Files } from '../files/files.svelte.js';
|
|
2
|
+
import { parseRetain, retentionFrontiers, referencedHashes, snapshotMatches } from './history.js';
|
|
3
|
+
import { releaseFiles } from './release.js';
|
|
4
|
+
|
|
5
|
+
/** @import { Nabu } from '../blocks/nabu.svelte.js' */
|
|
6
|
+
/** @import { AssetStore } from '../files/store.js' */
|
|
7
|
+
/** @import { CompactOptions } from './history.js' */
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* @typedef {'busy' | 'detached' | 'pending-uploads' | 'unsaved-changes' | 'nothing-to-compact' | 'archive-failed' | 'verification-failed' | 'save-failed' | 'failed'} CompactRefusal
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
|
|
15
|
+
* @typedef {Object} CompactResult
|
|
16
|
+
* @property {boolean} compacted
|
|
17
|
+
* @property {CompactRefusal} [reason] why nothing was compacted
|
|
18
|
+
* @property {unknown} [error] the error behind `archive-failed` / `save-failed` / `failed`
|
|
19
|
+
* @property {number} [bytesBefore] size of the complete snapshot (what `onBeforeCompact` received)
|
|
20
|
+
* @property {number} [bytesAfter] size of the compacted snapshot that was saved
|
|
21
|
+
* @property {string[]} [released] files (`sha256-…`) no kept version references any more (removed from this document's index)
|
|
22
|
+
* @property {string[]} [deleted] the released files whose bytes were deleted from the store (no other document used them)
|
|
23
|
+
* @property {string[]} [skipped] released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
|
|
24
|
+
* this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
|
|
25
|
+
* @property {Uint8Array} [snapshot] the compacted (shallow) snapshot that was saved
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* The persisted editor's side of a compaction (see {@link runCompaction}).
|
|
30
|
+
* @typedef {Object} CompactContext
|
|
31
|
+
* @property {Nabu} nabu
|
|
32
|
+
* @property {AssetStore} store
|
|
33
|
+
* @property {boolean} compacting a compaction is running
|
|
34
|
+
* @property {() => { peer: `${number}`, counter: number }[] | undefined} base frontiers of the previous compaction made by this session, if any
|
|
35
|
+
* @property {() => boolean} isDirty whether the document has changes that were not saved yet
|
|
36
|
+
* @property {() => Promise<void>} flush save now
|
|
37
|
+
* @property {<T>(fn: () => Promise<T>) => Promise<T>} lock run `fn` with the saves held back (they queue behind it)
|
|
38
|
+
* @property {(snapshot: Uint8Array, frontiers: { peer: `${number}`, counter: number }[], key: string) => Promise<void>} commit
|
|
39
|
+
* write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
|
|
40
|
+
* @property {(doc: import('loro-crdt').LoroDoc) => string} versionKey
|
|
41
|
+
* @property {() => Promise<Set<string>>} candidates the files this document lists: its index plus the ones a previous release skipped
|
|
42
|
+
* @property {() => Set<string>} held files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
|
|
43
|
+
* @property {(hashes: Iterable<string>) => void} setHeld replace that set
|
|
44
|
+
* @property {() => Promise<void>} saveRefs write `docRefs` (index + held)
|
|
45
|
+
*/
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Compact the history of a persisted document (ADR 014 §3.6). Every safeguard is here:
|
|
49
|
+
*
|
|
50
|
+
* 1. only when called (the caller decides: explicit `nabu.compact()` or `history: { mode: 'compact' }` at open);
|
|
51
|
+
* 2. REFUSES (`{ compacted: false, reason }`, no throw, nothing dropped) when a file upload is pending / running
|
|
52
|
+
* (`pending-uploads`: the local copy is the only copy), when the document has unsaved or uncommitted changes
|
|
53
|
+
* (`unsaved-changes`), when it is checked out to an old version (`detached`), or when another compaction runs (`busy`);
|
|
54
|
+
* 3. the kept version is chosen by {@link retentionFrontiers} (timestamps of the changes); nothing to drop = `nothing-to-compact`;
|
|
55
|
+
* 4. `onBeforeCompact(fullSnapshot)` is awaited BEFORE anything is changed or written; a throw / rejection ABORTS (`archive-failed`).
|
|
56
|
+
* The kept version is fixed at the same instant as that snapshot, so everything dropped is in the archive;
|
|
57
|
+
* 5. the compacted snapshot is a Loro SHALLOW snapshot at the kept version; it is checked (imported in a scratch document and
|
|
58
|
+
* compared with the live state) before being written, then saved; only then are files released;
|
|
59
|
+
* 6. files no kept version references are removed from the document's index and released ({@link releaseFiles}); bytes recently
|
|
60
|
+
* added (grace period, multi-tab safety) are skipped and reconsidered next time;
|
|
61
|
+
* 7. the undo stack is cleared (its steps could point at history that is gone / files that were released).
|
|
62
|
+
*
|
|
63
|
+
* The live in-memory document is NOT swapped (Loro cannot trim a document in place): it keeps its full history until the editor
|
|
64
|
+
* is opened again; from now on every save of this editor is a shallow snapshot at the kept version (see `persistence.js`).
|
|
65
|
+
* @param {CompactContext} ctx
|
|
66
|
+
* @param {CompactOptions} options
|
|
67
|
+
* @param {{ flush?: boolean }} [internal] `flush`: save pending changes first (used when opening, never an unsaved-changes refusal then)
|
|
68
|
+
* @returns {Promise<CompactResult>}
|
|
69
|
+
* @throws {TypeError} when `options` is invalid (`retain` is required)
|
|
70
|
+
*/
|
|
71
|
+
export async function runCompaction(ctx, options, { flush = false } = {}) {
|
|
72
|
+
const retainMs = parseRetain(options?.retain);
|
|
73
|
+
const archive = options.onBeforeCompact;
|
|
74
|
+
if (archive !== undefined && typeof archive !== 'function') throw new TypeError('compact: "onBeforeCompact" must be a function');
|
|
75
|
+
const { nabu, store } = ctx;
|
|
76
|
+
const doc = nabu.doc;
|
|
77
|
+
/** @param {CompactRefusal} reason @param {unknown} [error] @returns {CompactResult} */
|
|
78
|
+
const refuse = (reason, error) => ({ compacted: false, reason, ...(error === undefined ? {} : { error }) });
|
|
79
|
+
|
|
80
|
+
if (ctx.compacting) return refuse('busy');
|
|
81
|
+
ctx.compacting = true;
|
|
82
|
+
try {
|
|
83
|
+
const files = Files.get(nabu);
|
|
84
|
+
await files.whenIdle(); // pastes / imports / migration in progress belong to what is compacted
|
|
85
|
+
if (await files.pendingUploads()) return refuse('pending-uploads'); // before the flush: a refusal writes nothing
|
|
86
|
+
if (flush) await ctx.flush();
|
|
87
|
+
if (await files.pendingUploads()) return refuse('pending-uploads');
|
|
88
|
+
|
|
89
|
+
// ── no await from here to the archive export: the kept version and the archived snapshot are the same instant ──
|
|
90
|
+
if (doc.isDetached()) return refuse('detached');
|
|
91
|
+
if (doc.getPendingTxnLength() > 0 || ctx.isDirty()) return refuse('unsaved-changes');
|
|
92
|
+
const frontiers = retentionFrontiers(doc, retainMs, Date.now(), ctx.base());
|
|
93
|
+
if (!frontiers) return refuse('nothing-to-compact');
|
|
94
|
+
const full = doc.export({ mode: 'snapshot' });
|
|
95
|
+
|
|
96
|
+
if (archive) {
|
|
97
|
+
try {
|
|
98
|
+
await archive(full);
|
|
99
|
+
} catch (error) {
|
|
100
|
+
nabu.warn(`history: compaction aborted, onBeforeCompact failed (nothing was dropped): ${error}`);
|
|
101
|
+
return refuse('archive-failed', error);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
return await ctx.lock(async () => {
|
|
106
|
+
// the document may have moved on while the archive was awaited: what happened after `frontiers` is kept as it is
|
|
107
|
+
if (doc.isDetached()) return refuse('detached');
|
|
108
|
+
if (await files.pendingUploads()) return refuse('pending-uploads');
|
|
109
|
+
try {
|
|
110
|
+
const used = referencedHashes(doc, frontiers);
|
|
111
|
+
const released = [...(await ctx.candidates())].filter((hash) => !used.has(hash));
|
|
112
|
+
const urls = files.hostUrls(released);
|
|
113
|
+
await files.releaseIndex(released);
|
|
114
|
+
const key = ctx.versionKey(doc);
|
|
115
|
+
const snapshot = doc.export({ mode: 'shallow-snapshot', frontiers });
|
|
116
|
+
if (!snapshotMatches(doc, snapshot)) {
|
|
117
|
+
nabu.warn('history: compaction aborted, the compacted snapshot does not restore the document (nothing was dropped)');
|
|
118
|
+
return refuse('verification-failed');
|
|
119
|
+
}
|
|
120
|
+
const previouslyHeld = ctx.held();
|
|
121
|
+
ctx.setHeld([]); // the release below must not find the document's own docRefs protecting these files
|
|
122
|
+
try {
|
|
123
|
+
await ctx.commit(snapshot, frontiers, key);
|
|
124
|
+
} catch (error) {
|
|
125
|
+
ctx.setHeld(previouslyHeld);
|
|
126
|
+
nabu.warn(`history: compaction aborted, the compacted snapshot could not be saved: ${error}`);
|
|
127
|
+
return refuse('save-failed', error);
|
|
128
|
+
}
|
|
129
|
+
nabu.undoManager.clear();
|
|
130
|
+
const { deleted, skipped } = await releaseFiles(nabu, store, released, urls);
|
|
131
|
+
if (skipped.length) { ctx.setHeld(skipped); await ctx.saveRefs().catch((error) => nabu.warn(`history: could not record the files kept for later: ${error}`)); }
|
|
132
|
+
return { compacted: true, bytesBefore: full.length, bytesAfter: snapshot.length, released, deleted, skipped, snapshot };
|
|
133
|
+
} catch (error) {
|
|
134
|
+
nabu.warn(`history: compaction failed (nothing was dropped): ${error}`);
|
|
135
|
+
return refuse('failed', error);
|
|
136
|
+
}
|
|
137
|
+
});
|
|
138
|
+
} finally {
|
|
139
|
+
ctx.compacting = false;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse `retain` into milliseconds. Strict: a finite number >= 0, or `<number><s|m|h|d|w>` (e.g. `'30d'`, `'1.5h'`).
|
|
3
|
+
* @param {unknown} value
|
|
4
|
+
* @returns {number}
|
|
5
|
+
* @throws {TypeError}
|
|
6
|
+
*/
|
|
7
|
+
export function parseRetain(value: unknown): number;
|
|
8
|
+
/**
|
|
9
|
+
* Normalize the `history` option of `createPersistedEditor`: `'full'` (default) or `{ mode: 'compact', retain, onBeforeCompact }`.
|
|
10
|
+
* @param {unknown} history
|
|
11
|
+
* @returns {HistoryConfig}
|
|
12
|
+
* @throws {TypeError} for anything else (a typo must not silently pick a mode)
|
|
13
|
+
*/
|
|
14
|
+
export function parseHistory(history: unknown): HistoryConfig;
|
|
15
|
+
/**
|
|
16
|
+
* The version a compaction keeps as the START of the remaining history (the frontiers handed to the shallow snapshot), or
|
|
17
|
+
* `null` when there is nothing to drop.
|
|
18
|
+
*
|
|
19
|
+
* - `retainMs === 0`: the current version (no past history survives, only the state and what happens next).
|
|
20
|
+
* - otherwise: the latest version made ONLY of changes older than `now - retainMs`. Changes are walked in causal order
|
|
21
|
+
* (Loro lamport order), the version is the longest prefix whose changes are all older than the cutoff. A change without a
|
|
22
|
+
* timestamp (written before timestamps were recorded) counts as old only if a LATER change with a known timestamp is itself
|
|
23
|
+
* old (it happened before it); an undated history is therefore never windowed away: only `retain: 0` compacts it.
|
|
24
|
+
* A margin of Loro's change-merge interval keeps a change that may have grown after its timestamp.
|
|
25
|
+
*
|
|
26
|
+
* `base` is the version the document was already compacted to (its shallow start or the last compaction of this session); a result
|
|
27
|
+
* that does not go strictly past it is `null`.
|
|
28
|
+
* @param {LoroDoc} doc
|
|
29
|
+
* @param {number} retainMs
|
|
30
|
+
* @param {number} [nowMs]
|
|
31
|
+
* @param {OpId[]} [base] frontiers of the previous compaction point, if any
|
|
32
|
+
* @returns {OpId[] | null}
|
|
33
|
+
*/
|
|
34
|
+
export function retentionFrontiers(doc: LoroDoc, retainMs: number, nowMs?: number, base?: OpId[]): OpId[] | null;
|
|
35
|
+
/**
|
|
36
|
+
* The files (`sha256-…` ids) a compaction to `frontiers` still needs: referenced by the CURRENT state, by the state AT `frontiers`
|
|
37
|
+
* (the oldest version still reachable) or by any operation after it. Anything else is referenced by no version that survives.
|
|
38
|
+
* Works on a scratch copy of `doc` (the live document is not touched; no `forkAt`, which Loro does not support on shallow
|
|
39
|
+
* documents). Generic: it only looks for `nabu-asset:sha256-…` strings.
|
|
40
|
+
* @param {LoroDoc} doc @param {OpId[]} frontiers
|
|
41
|
+
* @returns {Set<string>}
|
|
42
|
+
*/
|
|
43
|
+
export function referencedHashes(doc: LoroDoc, frontiers: OpId[]): Set<string>;
|
|
44
|
+
/**
|
|
45
|
+
* Check that `snapshot` (a shallow snapshot) restores exactly the current state of `doc`: it is imported into a scratch document
|
|
46
|
+
* and compared. A compaction that fails this check is aborted before anything is written.
|
|
47
|
+
* @param {LoroDoc} doc @param {Uint8Array} snapshot
|
|
48
|
+
* @returns {boolean}
|
|
49
|
+
*/
|
|
50
|
+
export function snapshotMatches(doc: LoroDoc, snapshot: Uint8Array): boolean;
|
|
51
|
+
export type OpId = {
|
|
52
|
+
peer: `${number}`;
|
|
53
|
+
counter: number;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* What an integrator may pass as `compact({ ... })` / `history: { mode: 'compact', ... }`.
|
|
57
|
+
*/
|
|
58
|
+
export type CompactOptions = {
|
|
59
|
+
/**
|
|
60
|
+
* how much PAST history survives: a duration in ms, or a string `<number><unit>` with unit
|
|
61
|
+
* `s`, `m`, `h`, `d` or `w` (`'30d'`, `'12h'`), or `0` = keep no past history. Required (there is no default that drops data).
|
|
62
|
+
*/
|
|
63
|
+
retain: number | string;
|
|
64
|
+
/**
|
|
65
|
+
* awaited with the COMPLETE snapshot (all the
|
|
66
|
+
* history) before anything is dropped; archive it. If it throws / rejects the compaction is ABORTED and nothing is lost.
|
|
67
|
+
*/
|
|
68
|
+
onBeforeCompact?: ((fullSnapshot: Uint8Array) => void | Promise<void>) | undefined;
|
|
69
|
+
};
|
|
70
|
+
export type HistoryConfig = {
|
|
71
|
+
mode: "full";
|
|
72
|
+
} | {
|
|
73
|
+
mode: "compact";
|
|
74
|
+
retain: number;
|
|
75
|
+
onBeforeCompact?: CompactOptions["onBeforeCompact"];
|
|
76
|
+
};
|
|
77
|
+
import { LoroDoc } from 'loro-crdt';
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { LoroDoc, VersionVector } from 'loro-crdt';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* History helpers of the persisted editor (ADR 014 §3.6, lot 3): parsing of the `history` option and of `retain`, the choice
|
|
5
|
+
* of the version a compaction keeps, and the scan of the files a kept history still references. Pure functions over Loro
|
|
6
|
+
* documents: nothing here knows a block type (the document is only searched for `nabu-asset:sha256-…` strings).
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* What an integrator may pass as `compact({ ... })` / `history: { mode: 'compact', ... }`.
|
|
11
|
+
* @typedef {Object} CompactOptions
|
|
12
|
+
* @property {number | string} retain how much PAST history survives: a duration in ms, or a string `<number><unit>` with unit
|
|
13
|
+
* `s`, `m`, `h`, `d` or `w` (`'30d'`, `'12h'`), or `0` = keep no past history. Required (there is no default that drops data).
|
|
14
|
+
* @property {(fullSnapshot: Uint8Array) => void | Promise<void>} [onBeforeCompact] awaited with the COMPLETE snapshot (all the
|
|
15
|
+
* history) before anything is dropped; archive it. If it throws / rejects the compaction is ABORTED and nothing is lost.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @typedef {{ mode: 'full' } | { mode: 'compact', retain: number, onBeforeCompact?: CompactOptions['onBeforeCompact'] }} HistoryConfig
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const UNITS = /** @type {Record<string, number>} */ ({ s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 });
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Parse `retain` into milliseconds. Strict: a finite number >= 0, or `<number><s|m|h|d|w>` (e.g. `'30d'`, `'1.5h'`).
|
|
26
|
+
* @param {unknown} value
|
|
27
|
+
* @returns {number}
|
|
28
|
+
* @throws {TypeError}
|
|
29
|
+
*/
|
|
30
|
+
export function parseRetain(value) {
|
|
31
|
+
if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
|
|
32
|
+
if (typeof value === 'string') {
|
|
33
|
+
const match = /^(\d+(?:\.\d+)?)(s|m|h|d|w)?$/.exec(value.trim());
|
|
34
|
+
if (match && match[2]) return Number(match[1]) * UNITS[match[2]];
|
|
35
|
+
if (match && Number(match[1]) === 0) return 0;
|
|
36
|
+
}
|
|
37
|
+
throw new TypeError(`history: invalid "retain" ${JSON.stringify(value)}: use a number of milliseconds, 0, or a string like '30d' / '12h' (units s, m, h, d, w)`);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Normalize the `history` option of `createPersistedEditor`: `'full'` (default) or `{ mode: 'compact', retain, onBeforeCompact }`.
|
|
42
|
+
* @param {unknown} history
|
|
43
|
+
* @returns {HistoryConfig}
|
|
44
|
+
* @throws {TypeError} for anything else (a typo must not silently pick a mode)
|
|
45
|
+
*/
|
|
46
|
+
export function parseHistory(history) {
|
|
47
|
+
if (history === undefined || history === null || history === 'full') return { mode: 'full' };
|
|
48
|
+
const config = /** @type {any} */ (history);
|
|
49
|
+
if (typeof history === 'object' && (config.mode === undefined || config.mode === 'full')) return { mode: 'full' };
|
|
50
|
+
if (typeof history === 'object' && config.mode === 'compact') {
|
|
51
|
+
if (config.onBeforeCompact !== undefined && typeof config.onBeforeCompact !== 'function') throw new TypeError('history: "onBeforeCompact" must be a function');
|
|
52
|
+
return { mode: 'compact', retain: parseRetain(config.retain), onBeforeCompact: config.onBeforeCompact };
|
|
53
|
+
}
|
|
54
|
+
throw new TypeError(`history: expected 'full' or { mode: 'compact', retain, onBeforeCompact }, got ${JSON.stringify(history)}`);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Loro merges consecutive commits closer than this (seconds) into ONE change, stamped with the first one's time. */
|
|
58
|
+
const CHANGE_MERGE_SECONDS = 1000;
|
|
59
|
+
|
|
60
|
+
/** @typedef {{ peer: `${number}`, counter: number }} OpId */
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Whether version `a` strictly contains version `b`.
|
|
64
|
+
* @param {LoroDoc} doc @param {OpId[]} a @param {OpId[]} b
|
|
65
|
+
*/
|
|
66
|
+
function isAfter(doc, a, b) {
|
|
67
|
+
return doc.frontiersToVV(a).compare(doc.frontiersToVV(b)) === 1;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The version a compaction keeps as the START of the remaining history (the frontiers handed to the shallow snapshot), or
|
|
72
|
+
* `null` when there is nothing to drop.
|
|
73
|
+
*
|
|
74
|
+
* - `retainMs === 0`: the current version (no past history survives, only the state and what happens next).
|
|
75
|
+
* - otherwise: the latest version made ONLY of changes older than `now - retainMs`. Changes are walked in causal order
|
|
76
|
+
* (Loro lamport order), the version is the longest prefix whose changes are all older than the cutoff. A change without a
|
|
77
|
+
* timestamp (written before timestamps were recorded) counts as old only if a LATER change with a known timestamp is itself
|
|
78
|
+
* old (it happened before it); an undated history is therefore never windowed away: only `retain: 0` compacts it.
|
|
79
|
+
* A margin of Loro's change-merge interval keeps a change that may have grown after its timestamp.
|
|
80
|
+
*
|
|
81
|
+
* `base` is the version the document was already compacted to (its shallow start or the last compaction of this session); a result
|
|
82
|
+
* that does not go strictly past it is `null`.
|
|
83
|
+
* @param {LoroDoc} doc
|
|
84
|
+
* @param {number} retainMs
|
|
85
|
+
* @param {number} [nowMs]
|
|
86
|
+
* @param {OpId[]} [base] frontiers of the previous compaction point, if any
|
|
87
|
+
* @returns {OpId[] | null}
|
|
88
|
+
*/
|
|
89
|
+
export function retentionFrontiers(doc, retainMs, nowMs = Date.now(), base) {
|
|
90
|
+
const latest = doc.oplogFrontiers();
|
|
91
|
+
if (!latest.length) return null;
|
|
92
|
+
/** @type {OpId[] | null} */
|
|
93
|
+
let target = null;
|
|
94
|
+
if (retainMs === 0) {
|
|
95
|
+
target = latest;
|
|
96
|
+
} else {
|
|
97
|
+
const cutoff = Math.floor((nowMs - retainMs) / 1000) - CHANGE_MERGE_SECONDS;
|
|
98
|
+
const changes = [...doc.getAllChanges().values()].flat();
|
|
99
|
+
changes.sort((a, b) => a.lamport - b.lamport || (a.peer < b.peer ? -1 : a.peer > b.peer ? 1 : 0));
|
|
100
|
+
// effective time of each change: its own, or the next known one (it happened before it)
|
|
101
|
+
const effective = new Array(changes.length);
|
|
102
|
+
let next = Infinity;
|
|
103
|
+
for (let i = changes.length - 1; i >= 0; i--) {
|
|
104
|
+
if (changes[i].timestamp > 0) next = changes[i].timestamp;
|
|
105
|
+
effective[i] = next;
|
|
106
|
+
}
|
|
107
|
+
let count = 0;
|
|
108
|
+
while (count < changes.length && effective[count] <= cutoff) count++;
|
|
109
|
+
if (count === 0) return null;
|
|
110
|
+
/** @type {Map<`${number}`, number>} */
|
|
111
|
+
const end = new Map();
|
|
112
|
+
for (const [peer, counter] of doc.shallowSinceVV().toJSON()) end.set(peer, counter); // never go before the shallow start
|
|
113
|
+
for (let i = 0; i < count; i++) {
|
|
114
|
+
const c = changes[i];
|
|
115
|
+
end.set(c.peer, Math.max(end.get(c.peer) ?? 0, c.counter + c.length));
|
|
116
|
+
}
|
|
117
|
+
target = doc.vvToFrontiers(new VersionVector(end));
|
|
118
|
+
}
|
|
119
|
+
if (!target?.length) return null;
|
|
120
|
+
const floor = base?.length ? base : doc.isShallow() ? doc.shallowSinceFrontiers() : null;
|
|
121
|
+
if (floor && !isAfter(doc, target, floor)) return null;
|
|
122
|
+
return target;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Hash ids referenced as `nabu-asset:sha256-<64 hex>` anywhere in `text`. @param {string} text @param {Set<string>} into */
|
|
126
|
+
function collectRefs(text, into) {
|
|
127
|
+
for (const match of text.matchAll(/nabu-asset:(sha256-[0-9a-f]{64})/g)) into.add(match[1]);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Canonical JSON (sorted keys, bytes as hex) used to compare two document states.
|
|
132
|
+
* @param {any} value @returns {string}
|
|
133
|
+
*/
|
|
134
|
+
function canonical(value) {
|
|
135
|
+
return JSON.stringify(value, (_key, v) => {
|
|
136
|
+
if (ArrayBuffer.isView(v)) return 'bytes:' + [...new Uint8Array(v.buffer, v.byteOffset, v.byteLength)].join(',');
|
|
137
|
+
if (v && typeof v === 'object' && !Array.isArray(v)) return Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]));
|
|
138
|
+
return v;
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* The files (`sha256-…` ids) a compaction to `frontiers` still needs: referenced by the CURRENT state, by the state AT `frontiers`
|
|
144
|
+
* (the oldest version still reachable) or by any operation after it. Anything else is referenced by no version that survives.
|
|
145
|
+
* Works on a scratch copy of `doc` (the live document is not touched; no `forkAt`, which Loro does not support on shallow
|
|
146
|
+
* documents). Generic: it only looks for `nabu-asset:sha256-…` strings.
|
|
147
|
+
* @param {LoroDoc} doc @param {OpId[]} frontiers
|
|
148
|
+
* @returns {Set<string>}
|
|
149
|
+
*/
|
|
150
|
+
export function referencedHashes(doc, frontiers) {
|
|
151
|
+
const scratch = new LoroDoc();
|
|
152
|
+
scratch.import(doc.export({ mode: 'snapshot' }));
|
|
153
|
+
/** @type {Set<string>} */
|
|
154
|
+
const found = new Set();
|
|
155
|
+
collectRefs(JSON.stringify(scratch.toJSON()), found); // current state
|
|
156
|
+
collectRefs(JSON.stringify(scratch.exportJsonUpdates(scratch.frontiersToVV(frontiers))), found); // every op after the kept version
|
|
157
|
+
scratch.checkout(frontiers);
|
|
158
|
+
collectRefs(JSON.stringify(scratch.toJSON()), found); // state at the kept version
|
|
159
|
+
return found;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Check that `snapshot` (a shallow snapshot) restores exactly the current state of `doc`: it is imported into a scratch document
|
|
164
|
+
* and compared. A compaction that fails this check is aborted before anything is written.
|
|
165
|
+
* @param {LoroDoc} doc @param {Uint8Array} snapshot
|
|
166
|
+
* @returns {boolean}
|
|
167
|
+
*/
|
|
168
|
+
export function snapshotMatches(doc, snapshot) {
|
|
169
|
+
try {
|
|
170
|
+
const scratch = new LoroDoc();
|
|
171
|
+
scratch.import(snapshot);
|
|
172
|
+
return canonical(scratch.toJSON()) === canonical(doc.toJSON());
|
|
173
|
+
} catch {
|
|
174
|
+
return false;
|
|
175
|
+
}
|
|
176
|
+
}
|