@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
package/dist/files/index.d.ts
CHANGED
package/dist/files/index.js
CHANGED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The upload outbox (ADR 014 §3.4): the list of files still to send to the host (`onBeforePersist`), kept NEXT TO the
|
|
3
|
+
* asset store — never inside the Loro document. The local copy of the bytes is the payload, the outbox only says what is
|
|
4
|
+
* waiting, so an upload interrupted by a closed tab resumes when the document is opened again.
|
|
5
|
+
*
|
|
6
|
+
* An outbox is scoped to ONE document. `createPersistedEditor` plugs an `IndexedDBOutbox`
|
|
7
|
+
* (`persistence/outbox.js`); a non-persisted editor uses the in-memory one below. An integrator can pass any object with
|
|
8
|
+
* this interface as `files.outbox`.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* @typedef {Object} OutboxEntry
|
|
12
|
+
* @property {string} hash `sha256-<hex>` id of the file
|
|
13
|
+
* @property {number} attempts how many times its upload was started
|
|
14
|
+
* @property {'pending' | 'error'} state `pending`: to send (or interrupted); `error`: the last attempt failed (retried on demand only)
|
|
15
|
+
* @property {number} updatedAt epoch ms
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* @typedef {Object} Outbox
|
|
19
|
+
* @property {() => Promise<OutboxEntry[]>} list
|
|
20
|
+
* @property {(entry: OutboxEntry) => Promise<void>} put insert or replace the entry of `entry.hash`
|
|
21
|
+
* @property {(hash: string) => Promise<void>} delete
|
|
22
|
+
* @property {() => Promise<void>} [clear] optional: forget every entry of the document
|
|
23
|
+
*/
|
|
24
|
+
/**
|
|
25
|
+
* In-memory {@link Outbox} (lost with the page, like a non-persisted document).
|
|
26
|
+
* @implements {Outbox}
|
|
27
|
+
*/
|
|
28
|
+
export class MemoryOutbox implements Outbox {
|
|
29
|
+
/** @returns {Promise<OutboxEntry[]>} */
|
|
30
|
+
list(): Promise<OutboxEntry[]>;
|
|
31
|
+
/** @param {OutboxEntry} entry */
|
|
32
|
+
put(entry: OutboxEntry): Promise<void>;
|
|
33
|
+
/** @param {string} hash */
|
|
34
|
+
delete(hash: string): Promise<void>;
|
|
35
|
+
clear(): Promise<void>;
|
|
36
|
+
/** Number of entries (handy in tests / diagnostics). */
|
|
37
|
+
get size(): number;
|
|
38
|
+
#private;
|
|
39
|
+
}
|
|
40
|
+
export type OutboxEntry = {
|
|
41
|
+
/**
|
|
42
|
+
* `sha256-<hex>` id of the file
|
|
43
|
+
*/
|
|
44
|
+
hash: string;
|
|
45
|
+
/**
|
|
46
|
+
* how many times its upload was started
|
|
47
|
+
*/
|
|
48
|
+
attempts: number;
|
|
49
|
+
/**
|
|
50
|
+
* `pending`: to send (or interrupted); `error`: the last attempt failed (retried on demand only)
|
|
51
|
+
*/
|
|
52
|
+
state: "pending" | "error";
|
|
53
|
+
/**
|
|
54
|
+
* epoch ms
|
|
55
|
+
*/
|
|
56
|
+
updatedAt: number;
|
|
57
|
+
};
|
|
58
|
+
export type Outbox = {
|
|
59
|
+
list: () => Promise<OutboxEntry[]>;
|
|
60
|
+
/**
|
|
61
|
+
* insert or replace the entry of `entry.hash`
|
|
62
|
+
*/
|
|
63
|
+
put: (entry: OutboxEntry) => Promise<void>;
|
|
64
|
+
delete: (hash: string) => Promise<void>;
|
|
65
|
+
/**
|
|
66
|
+
* optional: forget every entry of the document
|
|
67
|
+
*/
|
|
68
|
+
clear?: (() => Promise<void>) | undefined;
|
|
69
|
+
};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The upload outbox (ADR 014 §3.4): the list of files still to send to the host (`onBeforePersist`), kept NEXT TO the
|
|
3
|
+
* asset store — never inside the Loro document. The local copy of the bytes is the payload, the outbox only says what is
|
|
4
|
+
* waiting, so an upload interrupted by a closed tab resumes when the document is opened again.
|
|
5
|
+
*
|
|
6
|
+
* An outbox is scoped to ONE document. `createPersistedEditor` plugs an `IndexedDBOutbox`
|
|
7
|
+
* (`persistence/outbox.js`); a non-persisted editor uses the in-memory one below. An integrator can pass any object with
|
|
8
|
+
* this interface as `files.outbox`.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* @typedef {Object} OutboxEntry
|
|
13
|
+
* @property {string} hash `sha256-<hex>` id of the file
|
|
14
|
+
* @property {number} attempts how many times its upload was started
|
|
15
|
+
* @property {'pending' | 'error'} state `pending`: to send (or interrupted); `error`: the last attempt failed (retried on demand only)
|
|
16
|
+
* @property {number} updatedAt epoch ms
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* @typedef {Object} Outbox
|
|
21
|
+
* @property {() => Promise<OutboxEntry[]>} list
|
|
22
|
+
* @property {(entry: OutboxEntry) => Promise<void>} put insert or replace the entry of `entry.hash`
|
|
23
|
+
* @property {(hash: string) => Promise<void>} delete
|
|
24
|
+
* @property {() => Promise<void>} [clear] optional: forget every entry of the document
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* In-memory {@link Outbox} (lost with the page, like a non-persisted document).
|
|
29
|
+
* @implements {Outbox}
|
|
30
|
+
*/
|
|
31
|
+
export class MemoryOutbox {
|
|
32
|
+
/** @type {Map<string, OutboxEntry>} */
|
|
33
|
+
#entries = new Map();
|
|
34
|
+
|
|
35
|
+
/** @returns {Promise<OutboxEntry[]>} */
|
|
36
|
+
async list() { return [...this.#entries.values()].map((e) => ({ ...e })); }
|
|
37
|
+
|
|
38
|
+
/** @param {OutboxEntry} entry */
|
|
39
|
+
async put(entry) { this.#entries.set(entry.hash, { ...entry }); }
|
|
40
|
+
|
|
41
|
+
/** @param {string} hash */
|
|
42
|
+
async delete(hash) { this.#entries.delete(hash); }
|
|
43
|
+
|
|
44
|
+
async clear() { this.#entries.clear(); }
|
|
45
|
+
|
|
46
|
+
/** Number of entries (handy in tests / diagnostics). */
|
|
47
|
+
get size() { return this.#entries.size; }
|
|
48
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/** @param {number} bytes @returns {string} */
|
|
2
|
+
export function formatBytes(bytes: number): string;
|
|
3
|
+
/**
|
|
4
|
+
* @param {FileReason['code']} code @param {string} [message] defaults to the standard sentence of the code
|
|
5
|
+
* @returns {FileReason}
|
|
6
|
+
*/
|
|
7
|
+
export function reasonOf(code: FileReason["code"], message?: string): FileReason;
|
|
8
|
+
/** @param {number} size @param {number} limit @returns {FileReason} */
|
|
9
|
+
export function tooLarge(size: number, limit: number): FileReason;
|
|
10
|
+
/**
|
|
11
|
+
* A reason read back from a document (untrusted: a document may come from anywhere): only a known code and a bounded
|
|
12
|
+
* string survive. `null` when `value` is not a reason.
|
|
13
|
+
* @param {unknown} value @returns {FileReason | null}
|
|
14
|
+
*/
|
|
15
|
+
export function normalizeReason(value: unknown): FileReason | null;
|
|
16
|
+
/** The reason to show for a status that carries none. @param {string} status @returns {FileReason | null} */
|
|
17
|
+
export function defaultReason(status: string): FileReason | null;
|
|
18
|
+
/**
|
|
19
|
+
* Status / reason model of a media block (ADR 014 lot 2). Pure helpers, no document access.
|
|
20
|
+
*
|
|
21
|
+
* `status` is what the block stores (and what a document export writes):
|
|
22
|
+
* - `ready` the file is stored (and, with a host, uploaded);
|
|
23
|
+
* - `pending` the bytes are being stored / uploaded (`block.progress` tells how far while an upload runs);
|
|
24
|
+
* - `error` the upload failed or was cancelled — the local copy is kept, `block.retry()` runs it again;
|
|
25
|
+
* - `missing` no source has the bytes (a copy without them, a corrupt embedded file…);
|
|
26
|
+
* - `rejected` the file was refused (`files.maxFileSize`); no ref, the block only says why.
|
|
27
|
+
* A block saved `pending` that no upload is running for, with neither local bytes nor a host `url` (a document opened on
|
|
28
|
+
* another device before the upload ended), is shown as `missing` with the reason `interrupted` (see `MediaBlock#isMissing`).
|
|
29
|
+
*
|
|
30
|
+
* `reason` explains `error`, `rejected` and `missing`: `{ code, message }` where `code` is stable (one of {@link REASON_CODES})
|
|
31
|
+
* and `message` a readable English sentence an interface can display as is.
|
|
32
|
+
*/
|
|
33
|
+
/**
|
|
34
|
+
* @typedef {'ready' | 'pending' | 'error' | 'missing' | 'rejected'} FileStatus
|
|
35
|
+
*/
|
|
36
|
+
/**
|
|
37
|
+
* @typedef {Object} FileReason
|
|
38
|
+
* @property {'too-large' | 'upload-failed' | 'cancelled' | 'interrupted' | 'unavailable' | 'not-embedded' | 'corrupt'} code
|
|
39
|
+
* @property {string} message readable, English
|
|
40
|
+
*/
|
|
41
|
+
/** The stable codes of {@link FileReason}. */
|
|
42
|
+
export const REASON_CODES: Readonly<{
|
|
43
|
+
'too-large': "The file is too large.";
|
|
44
|
+
'upload-failed': "The upload failed.";
|
|
45
|
+
cancelled: "The upload was cancelled.";
|
|
46
|
+
interrupted: "The upload was interrupted before it finished: the file is not available on this device.";
|
|
47
|
+
unavailable: "The file is not available.";
|
|
48
|
+
'not-embedded': "The file was not included in the copy (too large or not loaded yet).";
|
|
49
|
+
corrupt: "The file does not match its fingerprint and was ignored.";
|
|
50
|
+
}>;
|
|
51
|
+
/** Thrown by `Files#ingest` / `Files#persist` for a file the options refuse (`maxFileSize`). */
|
|
52
|
+
export class FileRejectedError extends Error {
|
|
53
|
+
/** @param {FileReason} reason */
|
|
54
|
+
constructor(reason: FileReason);
|
|
55
|
+
/** @type {FileReason} */
|
|
56
|
+
reason: FileReason;
|
|
57
|
+
}
|
|
58
|
+
export type FileStatus = "ready" | "pending" | "error" | "missing" | "rejected";
|
|
59
|
+
export type FileReason = {
|
|
60
|
+
code: "too-large" | "upload-failed" | "cancelled" | "interrupted" | "unavailable" | "not-embedded" | "corrupt";
|
|
61
|
+
/**
|
|
62
|
+
* readable, English
|
|
63
|
+
*/
|
|
64
|
+
message: string;
|
|
65
|
+
};
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Status / reason model of a media block (ADR 014 lot 2). Pure helpers, no document access.
|
|
3
|
+
*
|
|
4
|
+
* `status` is what the block stores (and what a document export writes):
|
|
5
|
+
* - `ready` the file is stored (and, with a host, uploaded);
|
|
6
|
+
* - `pending` the bytes are being stored / uploaded (`block.progress` tells how far while an upload runs);
|
|
7
|
+
* - `error` the upload failed or was cancelled — the local copy is kept, `block.retry()` runs it again;
|
|
8
|
+
* - `missing` no source has the bytes (a copy without them, a corrupt embedded file…);
|
|
9
|
+
* - `rejected` the file was refused (`files.maxFileSize`); no ref, the block only says why.
|
|
10
|
+
* A block saved `pending` that no upload is running for, with neither local bytes nor a host `url` (a document opened on
|
|
11
|
+
* another device before the upload ended), is shown as `missing` with the reason `interrupted` (see `MediaBlock#isMissing`).
|
|
12
|
+
*
|
|
13
|
+
* `reason` explains `error`, `rejected` and `missing`: `{ code, message }` where `code` is stable (one of {@link REASON_CODES})
|
|
14
|
+
* and `message` a readable English sentence an interface can display as is.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* @typedef {'ready' | 'pending' | 'error' | 'missing' | 'rejected'} FileStatus
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @typedef {Object} FileReason
|
|
23
|
+
* @property {'too-large' | 'upload-failed' | 'cancelled' | 'interrupted' | 'unavailable' | 'not-embedded' | 'corrupt'} code
|
|
24
|
+
* @property {string} message readable, English
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** The stable codes of {@link FileReason}. */
|
|
28
|
+
export const REASON_CODES = Object.freeze({
|
|
29
|
+
'too-large': 'The file is too large.',
|
|
30
|
+
'upload-failed': 'The upload failed.',
|
|
31
|
+
'cancelled': 'The upload was cancelled.',
|
|
32
|
+
'interrupted': 'The upload was interrupted before it finished: the file is not available on this device.',
|
|
33
|
+
'unavailable': 'The file is not available.',
|
|
34
|
+
'not-embedded': 'The file was not included in the copy (too large or not loaded yet).',
|
|
35
|
+
'corrupt': 'The file does not match its fingerprint and was ignored.',
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
/** @param {number} bytes @returns {string} */
|
|
39
|
+
export function formatBytes(bytes) {
|
|
40
|
+
if (bytes >= 1048576) return (bytes / 1048576).toFixed(1).replace(/\.0$/, '') + ' MB';
|
|
41
|
+
if (bytes >= 1024) return (bytes / 1024).toFixed(1).replace(/\.0$/, '') + ' KB';
|
|
42
|
+
return bytes + ' B';
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* @param {FileReason['code']} code @param {string} [message] defaults to the standard sentence of the code
|
|
47
|
+
* @returns {FileReason}
|
|
48
|
+
*/
|
|
49
|
+
export function reasonOf(code, message) {
|
|
50
|
+
return { code, message: message || REASON_CODES[code] };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** @param {number} size @param {number} limit @returns {FileReason} */
|
|
54
|
+
export function tooLarge(size, limit) {
|
|
55
|
+
return reasonOf('too-large', `The file is too large (${formatBytes(size)}); the limit is ${formatBytes(limit)}.`);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* A reason read back from a document (untrusted: a document may come from anywhere): only a known code and a bounded
|
|
60
|
+
* string survive. `null` when `value` is not a reason.
|
|
61
|
+
* @param {unknown} value @returns {FileReason | null}
|
|
62
|
+
*/
|
|
63
|
+
export function normalizeReason(value) {
|
|
64
|
+
if (!value || typeof value !== 'object') return null;
|
|
65
|
+
const { code, message } = /** @type {any} */ (value);
|
|
66
|
+
if (typeof code !== 'string' || !Object.hasOwn(REASON_CODES, code)) return null;
|
|
67
|
+
return reasonOf(/** @type {FileReason['code']} */ (code), typeof message === 'string' && message ? message.slice(0, 300) : undefined);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The reason to show for a status that carries none. @param {string} status @returns {FileReason | null} */
|
|
71
|
+
export function defaultReason(status) {
|
|
72
|
+
if (status === 'error') return reasonOf('upload-failed');
|
|
73
|
+
if (status === 'rejected') return reasonOf('too-large');
|
|
74
|
+
if (status === 'missing') return reasonOf('unavailable');
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Thrown by `Files#ingest` / `Files#persist` for a file the options refuse (`maxFileSize`). */
|
|
79
|
+
export class FileRejectedError extends Error {
|
|
80
|
+
/** @param {FileReason} reason */
|
|
81
|
+
constructor(reason) {
|
|
82
|
+
super(reason.message);
|
|
83
|
+
this.name = 'FileRejectedError';
|
|
84
|
+
/** @type {FileReason} */
|
|
85
|
+
this.reason = reason;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Asset storage (ADR 014 §3.3): where the BYTES of the files live, outside the Loro document. The document only holds
|
|
3
|
+
* references (`nabu-asset:sha256-<hex>`) and a small metadata index (`assetIndex`).
|
|
4
|
+
*
|
|
5
|
+
* `MemoryAssetStore` is the default of a non-persisted editor (lost with the page, like its document). The persisted
|
|
6
|
+
* editor uses `IndexedDBAssetStore` (`persistence/asset-store.js`); an integrator can pass any object with this
|
|
7
|
+
* interface as `files.store`.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* What a store keeps next to the bytes.
|
|
11
|
+
* @typedef {Object} AssetMeta
|
|
12
|
+
* @property {string} mime
|
|
13
|
+
* @property {string} name
|
|
14
|
+
* @property {number} size byte length
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* @typedef {Object} AssetStore
|
|
18
|
+
* @property {(hash: string) => Promise<boolean>} has
|
|
19
|
+
* @property {(hash: string) => Promise<Blob | null>} get
|
|
20
|
+
* @property {(hash: string, blob: Blob, meta: AssetMeta) => Promise<void>} put
|
|
21
|
+
* @property {(hash: string) => Promise<void>} delete
|
|
22
|
+
* @property {() => AsyncIterable<string>} keys
|
|
23
|
+
* @property {(hash: string) => Promise<AssetMeta | null>} [stat] optional: the metadata stored with `put`
|
|
24
|
+
* @property {(docId: string, hashes: Iterable<string>) => Promise<void>} [setDocRefs] optional, with the three below: which files
|
|
25
|
+
* each document references. Only a store that offers them lets a compaction / `clearPersistence()` DELETE bytes (a file is
|
|
26
|
+
* deleted only when no document references it any more); without them Nabu never deletes bytes from this store.
|
|
27
|
+
* @property {(docId: string) => Promise<Set<string>>} [getDocRefs]
|
|
28
|
+
* @property {(docId: string) => Promise<void>} [clearDocRefs]
|
|
29
|
+
* @property {() => Promise<Set<string>>} [referencedHashes] every file referenced by at least one document
|
|
30
|
+
* @property {(hash: string) => Promise<number | null>} [savedAt] optional: epoch ms when the file was last stored or re-added; with
|
|
31
|
+
* `touch`, lets a release keep a recent file (`files.releaseGraceMs`). Without it, a release skips every file (grace on).
|
|
32
|
+
* @property {(hash: string) => Promise<void>} [touch] optional: refresh `savedAt` (called when a file already stored is added again)
|
|
33
|
+
*/
|
|
34
|
+
/**
|
|
35
|
+
* In-memory {@link AssetStore}. Keys are `sha256-<hex>` hashes.
|
|
36
|
+
* @implements {AssetStore}
|
|
37
|
+
*/
|
|
38
|
+
export class MemoryAssetStore implements AssetStore {
|
|
39
|
+
/** @param {string} hash */
|
|
40
|
+
has(hash: string): Promise<boolean>;
|
|
41
|
+
/** @param {string} hash @returns {Promise<Blob | null>} */
|
|
42
|
+
get(hash: string): Promise<Blob | null>;
|
|
43
|
+
/** @param {string} hash @param {Blob} blob @param {AssetMeta} meta */
|
|
44
|
+
put(hash: string, blob: Blob, meta: AssetMeta): Promise<void>;
|
|
45
|
+
/** @param {string} hash */
|
|
46
|
+
delete(hash: string): Promise<void>;
|
|
47
|
+
/** @returns {AsyncGenerator<string>} */
|
|
48
|
+
keys(): AsyncGenerator<string>;
|
|
49
|
+
/** @param {string} hash @returns {Promise<AssetMeta | null>} */
|
|
50
|
+
stat(hash: string): Promise<AssetMeta | null>;
|
|
51
|
+
/** Number of files stored (handy in tests / diagnostics). */
|
|
52
|
+
get size(): number;
|
|
53
|
+
#private;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* What a store keeps next to the bytes.
|
|
57
|
+
*/
|
|
58
|
+
export type AssetMeta = {
|
|
59
|
+
mime: string;
|
|
60
|
+
name: string;
|
|
61
|
+
/**
|
|
62
|
+
* byte length
|
|
63
|
+
*/
|
|
64
|
+
size: number;
|
|
65
|
+
};
|
|
66
|
+
export type AssetStore = {
|
|
67
|
+
has: (hash: string) => Promise<boolean>;
|
|
68
|
+
get: (hash: string) => Promise<Blob | null>;
|
|
69
|
+
put: (hash: string, blob: Blob, meta: AssetMeta) => Promise<void>;
|
|
70
|
+
delete: (hash: string) => Promise<void>;
|
|
71
|
+
keys: () => AsyncIterable<string>;
|
|
72
|
+
/**
|
|
73
|
+
* optional: the metadata stored with `put`
|
|
74
|
+
*/
|
|
75
|
+
stat?: ((hash: string) => Promise<AssetMeta | null>) | undefined;
|
|
76
|
+
/**
|
|
77
|
+
* optional, with the three below: which files
|
|
78
|
+
* each document references. Only a store that offers them lets a compaction / `clearPersistence()` DELETE bytes (a file is
|
|
79
|
+
* deleted only when no document references it any more); without them Nabu never deletes bytes from this store.
|
|
80
|
+
*/
|
|
81
|
+
setDocRefs?: ((docId: string, hashes: Iterable<string>) => Promise<void>) | undefined;
|
|
82
|
+
getDocRefs?: ((docId: string) => Promise<Set<string>>) | undefined;
|
|
83
|
+
clearDocRefs?: ((docId: string) => Promise<void>) | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* every file referenced by at least one document
|
|
86
|
+
*/
|
|
87
|
+
referencedHashes?: (() => Promise<Set<string>>) | undefined;
|
|
88
|
+
/**
|
|
89
|
+
* optional: epoch ms when the file was last stored or re-added; with
|
|
90
|
+
* `touch`, lets a release keep a recent file (`files.releaseGraceMs`). Without it, a release skips every file (grace on).
|
|
91
|
+
*/
|
|
92
|
+
savedAt?: ((hash: string) => Promise<number | null>) | undefined;
|
|
93
|
+
/**
|
|
94
|
+
* optional: refresh `savedAt` (called when a file already stored is added again)
|
|
95
|
+
*/
|
|
96
|
+
touch?: ((hash: string) => Promise<void>) | undefined;
|
|
97
|
+
};
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Asset storage (ADR 014 §3.3): where the BYTES of the files live, outside the Loro document. The document only holds
|
|
3
|
+
* references (`nabu-asset:sha256-<hex>`) and a small metadata index (`assetIndex`).
|
|
4
|
+
*
|
|
5
|
+
* `MemoryAssetStore` is the default of a non-persisted editor (lost with the page, like its document). The persisted
|
|
6
|
+
* editor uses `IndexedDBAssetStore` (`persistence/asset-store.js`); an integrator can pass any object with this
|
|
7
|
+
* interface as `files.store`.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* What a store keeps next to the bytes.
|
|
12
|
+
* @typedef {Object} AssetMeta
|
|
13
|
+
* @property {string} mime
|
|
14
|
+
* @property {string} name
|
|
15
|
+
* @property {number} size byte length
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @typedef {Object} AssetStore
|
|
20
|
+
* @property {(hash: string) => Promise<boolean>} has
|
|
21
|
+
* @property {(hash: string) => Promise<Blob | null>} get
|
|
22
|
+
* @property {(hash: string, blob: Blob, meta: AssetMeta) => Promise<void>} put
|
|
23
|
+
* @property {(hash: string) => Promise<void>} delete
|
|
24
|
+
* @property {() => AsyncIterable<string>} keys
|
|
25
|
+
* @property {(hash: string) => Promise<AssetMeta | null>} [stat] optional: the metadata stored with `put`
|
|
26
|
+
* @property {(docId: string, hashes: Iterable<string>) => Promise<void>} [setDocRefs] optional, with the three below: which files
|
|
27
|
+
* each document references. Only a store that offers them lets a compaction / `clearPersistence()` DELETE bytes (a file is
|
|
28
|
+
* deleted only when no document references it any more); without them Nabu never deletes bytes from this store.
|
|
29
|
+
* @property {(docId: string) => Promise<Set<string>>} [getDocRefs]
|
|
30
|
+
* @property {(docId: string) => Promise<void>} [clearDocRefs]
|
|
31
|
+
* @property {() => Promise<Set<string>>} [referencedHashes] every file referenced by at least one document
|
|
32
|
+
* @property {(hash: string) => Promise<number | null>} [savedAt] optional: epoch ms when the file was last stored or re-added; with
|
|
33
|
+
* `touch`, lets a release keep a recent file (`files.releaseGraceMs`). Without it, a release skips every file (grace on).
|
|
34
|
+
* @property {(hash: string) => Promise<void>} [touch] optional: refresh `savedAt` (called when a file already stored is added again)
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* In-memory {@link AssetStore}. Keys are `sha256-<hex>` hashes.
|
|
39
|
+
* @implements {AssetStore}
|
|
40
|
+
*/
|
|
41
|
+
export class MemoryAssetStore {
|
|
42
|
+
/** @type {Map<string, { blob: Blob, meta: AssetMeta }>} */
|
|
43
|
+
#entries = new Map();
|
|
44
|
+
|
|
45
|
+
/** @param {string} hash */
|
|
46
|
+
async has(hash) { return this.#entries.has(hash); }
|
|
47
|
+
|
|
48
|
+
/** @param {string} hash @returns {Promise<Blob | null>} */
|
|
49
|
+
async get(hash) { return this.#entries.get(hash)?.blob ?? null; }
|
|
50
|
+
|
|
51
|
+
/** @param {string} hash @param {Blob} blob @param {AssetMeta} meta */
|
|
52
|
+
async put(hash, blob, meta) { this.#entries.set(hash, { blob, meta: { ...meta } }); }
|
|
53
|
+
|
|
54
|
+
/** @param {string} hash */
|
|
55
|
+
async delete(hash) { this.#entries.delete(hash); }
|
|
56
|
+
|
|
57
|
+
/** @returns {AsyncGenerator<string>} */
|
|
58
|
+
async *keys() { for (const key of [...this.#entries.keys()]) yield key; }
|
|
59
|
+
|
|
60
|
+
/** @param {string} hash @returns {Promise<AssetMeta | null>} */
|
|
61
|
+
async stat(hash) { const e = this.#entries.get(hash); return e ? { ...e.meta } : null; }
|
|
62
|
+
|
|
63
|
+
/** Number of files stored (handy in tests / diagnostics). */
|
|
64
|
+
get size() { return this.#entries.size; }
|
|
65
|
+
}
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The resolved `files.autoRetry` option: `false` disables the automatic retries, an object tunes them, anything else is the default.
|
|
3
|
+
* @param {unknown} option @returns {Required<AutoRetryConfig> | null}
|
|
4
|
+
*/
|
|
5
|
+
export function resolveAutoRetry(option: unknown): Required<AutoRetryConfig> | null;
|
|
6
|
+
/** @import { Outbox, OutboxEntry } from './outbox.js' */
|
|
7
|
+
/** @import { FileReason } from './status.js' */
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {Object} AutoRetryConfig How a persisted editor retries, by itself, the uploads it finds waiting when it is opened (P-97).
|
|
10
|
+
* @property {number} [initialDelay] ms before the second attempt (default 2000); each next one waits twice as long
|
|
11
|
+
* @property {number} [maxDelay] longest wait between two attempts (default 60000)
|
|
12
|
+
* @property {number} [maxAttempts] attempts per file and per session, the one at open included (default 8); the `online` event grants a new series
|
|
13
|
+
*/
|
|
14
|
+
export const DEFAULT_AUTO_RETRY: Readonly<{
|
|
15
|
+
initialDelay: 2000;
|
|
16
|
+
maxDelay: 60000;
|
|
17
|
+
maxAttempts: 8;
|
|
18
|
+
}>;
|
|
19
|
+
/**
|
|
20
|
+
* What the upload queue needs from {@link import('./files.svelte.js').Files} (kept as an interface so this module does not
|
|
21
|
+
* reach into it).
|
|
22
|
+
* @typedef {Object} UploadHost
|
|
23
|
+
* @property {import('../blocks/nabu.svelte.js').Nabu} nabu
|
|
24
|
+
* @property {import('./store.js').AssetStore} store
|
|
25
|
+
* @property {import('loro-crdt').LoroMap} index the document's `assetIndex`
|
|
26
|
+
* @property {() => import('./files.svelte.js').FilesConfig} config
|
|
27
|
+
* @property {(write: () => void) => Promise<void>} silent run Loro writes as a silent commit (not an undo step)
|
|
28
|
+
* @property {(hash: string) => Promise<void>} settled resolves when the bytes of `hash` arriving with a paste are stored
|
|
29
|
+
* @property {() => void} forgetMissing forget the "no source has it" verdicts (the index changed)
|
|
30
|
+
* @property {<T>(promise: Promise<T>) => Promise<T>} track register a background job (see `Files#whenIdle`)
|
|
31
|
+
*/
|
|
32
|
+
/**
|
|
33
|
+
* @typedef {Object} Job
|
|
34
|
+
* @property {string} hash
|
|
35
|
+
* @property {AbortController} controller
|
|
36
|
+
* @property {'cancel' | 'released' | null} cause why the controller was aborted
|
|
37
|
+
* @property {boolean} referenced a live block has referenced this file since the job started (a job nobody references
|
|
38
|
+
* yet, e.g. started by `Files#persist`, is not aborted by the "last block deleted" rule)
|
|
39
|
+
* @property {Promise<boolean>} promise resolves `true` when the upload succeeded
|
|
40
|
+
*/
|
|
41
|
+
/**
|
|
42
|
+
* The upload side of {@link import('./files.svelte.js').Files} (ADR 014 lot 2): with a host (`files.onBeforePersist`) a file is
|
|
43
|
+
* stored locally first, then sent in the background. The queue is DRIVEN BY THE DOCUMENT, not by calls:
|
|
44
|
+
*
|
|
45
|
+
* - a block whose status is `pending`, with a `nabu-asset:sha256-…` ref, local bytes, no host `url` and no running upload
|
|
46
|
+
* → the upload starts (this is also how an upload RESUMES when a document is opened again, and how an undo that brings a
|
|
47
|
+
* deleted block back restarts it);
|
|
48
|
+
* - an upload whose file no live block references any more is aborted (`AbortController` → the `signal` given to the host);
|
|
49
|
+
* - success: `assetIndex[hash].url = <ref returned by the host>` and the blocks become `ready`, in a silent commit; the
|
|
50
|
+
* block's ref NEVER changes. Failure: the blocks become `error` (local copy kept). {@link Uploads#retry} / {@link Uploads#cancel}
|
|
51
|
+
* are the explicit controls.
|
|
52
|
+
*
|
|
53
|
+
* The outbox ({@link Outbox}) remembers what is waiting (and how many attempts were made) next to the local store, so it
|
|
54
|
+
* survives a closed tab; it is a record, the document statuses plus the local bytes are what the queue acts on.
|
|
55
|
+
*
|
|
56
|
+
* Retry on open (P-97): the files the outbox lists when the document is opened (an upload interrupted, or one that had failed) are
|
|
57
|
+
* sent again BY THEMSELVES, in the background: a failed `error` file at once, then, whenever an attempt fails, after 2 s, 4 s, 8 s…
|
|
58
|
+
* (at most 60 s), `maxAttempts` times per session; the browser's `online` event starts a fresh series. A cancelled upload (the user's
|
|
59
|
+
* choice) is not retried, nor are the failures of the current session (the block's `retry()` is for those). See {@link AutoRetryConfig}.
|
|
60
|
+
*/
|
|
61
|
+
export class Uploads {
|
|
62
|
+
/** @param {UploadHost} host */
|
|
63
|
+
constructor(host: UploadHost);
|
|
64
|
+
/** @type {Outbox} */
|
|
65
|
+
outbox: Outbox;
|
|
66
|
+
/** Stop the automatic retries (timers, `online` listener). The queue itself keeps working. */
|
|
67
|
+
dispose(): void;
|
|
68
|
+
/** Resolves once the outbox was read and the first pass (resume) ran. @returns {Promise<void>} */
|
|
69
|
+
ready(): Promise<void>;
|
|
70
|
+
/** Progress (0–1) of the running upload of `hash`, `null` when none runs. Reactive. @param {string} hash @returns {number | null} */
|
|
71
|
+
progress(hash: string): number | null;
|
|
72
|
+
/** Whether any upload is running (not reactive). @returns {boolean} */
|
|
73
|
+
busy(): boolean;
|
|
74
|
+
/** Whether an upload of `hash` is running. Reactive. @param {string} hash @returns {boolean} */
|
|
75
|
+
isUploading(hash: string): boolean;
|
|
76
|
+
/** @param {string} hash @returns {string | null} the host location recorded in the index */
|
|
77
|
+
hostedUrl(hash: string): string | null;
|
|
78
|
+
/** Whether a file with this hash still has to be sent to the host. @param {string} hash @returns {boolean} */
|
|
79
|
+
needsUpload(hash: string): boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Called for every committed change of the document. Only what can concern an upload triggers a pass: a media ref /
|
|
82
|
+
* status written, or (while an upload runs) a node deleted. Typing never does.
|
|
83
|
+
* @param {any} event a Loro event batch
|
|
84
|
+
*/
|
|
85
|
+
onDocEvent(event: any): void;
|
|
86
|
+
/** Run a pass soon (coalesced). */
|
|
87
|
+
schedule(): void;
|
|
88
|
+
/**
|
|
89
|
+
* Look at the document and act: abort the uploads nobody references, start those that are due. Passes never overlap.
|
|
90
|
+
* @returns {Promise<void>}
|
|
91
|
+
*/
|
|
92
|
+
reconcile(): Promise<void>;
|
|
93
|
+
/**
|
|
94
|
+
* Send a file that is already in the local store to the host, now (`Files#persist`). No-op without a host or when it is
|
|
95
|
+
* already hosted. @param {string} hash @returns {Promise<boolean>}
|
|
96
|
+
*/
|
|
97
|
+
upload(hash: string): Promise<boolean>;
|
|
98
|
+
/**
|
|
99
|
+
* Run the upload of a file again from its local copy (the blocks that were `error` become `pending`).
|
|
100
|
+
* @param {string} hash @returns {Promise<boolean>} `true` when the file ended up at the host
|
|
101
|
+
*/
|
|
102
|
+
retry(hash: string): Promise<boolean>;
|
|
103
|
+
/**
|
|
104
|
+
* Abort the running upload of a file (its `signal` fires). The blocks become `error` with the reason `cancelled`; the
|
|
105
|
+
* local copy stays, {@link Uploads#retry} sends it again.
|
|
106
|
+
* @param {string} hash @returns {boolean} whether an upload was running
|
|
107
|
+
*/
|
|
108
|
+
cancel(hash: string): boolean;
|
|
109
|
+
#private;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* How a persisted editor retries, by itself, the uploads it finds waiting when it is opened (P-97).
|
|
113
|
+
*/
|
|
114
|
+
export type AutoRetryConfig = {
|
|
115
|
+
/**
|
|
116
|
+
* ms before the second attempt (default 2000); each next one waits twice as long
|
|
117
|
+
*/
|
|
118
|
+
initialDelay?: number | undefined;
|
|
119
|
+
/**
|
|
120
|
+
* longest wait between two attempts (default 60000)
|
|
121
|
+
*/
|
|
122
|
+
maxDelay?: number | undefined;
|
|
123
|
+
/**
|
|
124
|
+
* attempts per file and per session, the one at open included (default 8); the `online` event grants a new series
|
|
125
|
+
*/
|
|
126
|
+
maxAttempts?: number | undefined;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* What the upload queue needs from {@link import ('./files.svelte.js').Files} (kept as an interface so this module does not
|
|
130
|
+
* reach into it).
|
|
131
|
+
*/
|
|
132
|
+
export type UploadHost = {
|
|
133
|
+
nabu: import("../blocks/nabu.svelte.js").Nabu;
|
|
134
|
+
store: import("./store.js").AssetStore;
|
|
135
|
+
/**
|
|
136
|
+
* the document's `assetIndex`
|
|
137
|
+
*/
|
|
138
|
+
index: import("loro-crdt").LoroMap;
|
|
139
|
+
config: () => import("./files.svelte.js").FilesConfig;
|
|
140
|
+
/**
|
|
141
|
+
* run Loro writes as a silent commit (not an undo step)
|
|
142
|
+
*/
|
|
143
|
+
silent: (write: () => void) => Promise<void>;
|
|
144
|
+
/**
|
|
145
|
+
* resolves when the bytes of `hash` arriving with a paste are stored
|
|
146
|
+
*/
|
|
147
|
+
settled: (hash: string) => Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* forget the "no source has it" verdicts (the index changed)
|
|
150
|
+
*/
|
|
151
|
+
forgetMissing: () => void;
|
|
152
|
+
/**
|
|
153
|
+
* register a background job (see `Files#whenIdle`)
|
|
154
|
+
*/
|
|
155
|
+
track: <T>(promise: Promise<T>) => Promise<T>;
|
|
156
|
+
};
|
|
157
|
+
export type Job = {
|
|
158
|
+
hash: string;
|
|
159
|
+
controller: AbortController;
|
|
160
|
+
/**
|
|
161
|
+
* why the controller was aborted
|
|
162
|
+
*/
|
|
163
|
+
cause: "cancel" | "released" | null;
|
|
164
|
+
/**
|
|
165
|
+
* a live block has referenced this file since the job started (a job nobody references
|
|
166
|
+
* yet, e.g. started by `Files#persist`, is not aborted by the "last block deleted" rule)
|
|
167
|
+
*/
|
|
168
|
+
referenced: boolean;
|
|
169
|
+
/**
|
|
170
|
+
* resolves `true` when the upload succeeded
|
|
171
|
+
*/
|
|
172
|
+
promise: Promise<boolean>;
|
|
173
|
+
};
|
|
174
|
+
import type { Outbox } from './outbox.js';
|