@bendyline/docblocks 1.1.2 → 2.0.0

package/dist/document/document-session.js

@@ -0,0 +1,749 @@
+import { isFileSystemMoveStateError } from '../filesystem/move-error.js';
+const DEFAULT_AUTO_SAVE_RETRY_DELAYS_MS = [1000, 3000, 10000];
+/**
+ * Raised by a commit target when optimistic external-change verification
+ * fails. The session converts it into durable conflict state.
+ */
+export class DocumentCommitConflictError extends Error {
+    constructor(message, externalContent, externalVersion = null) {
+        super(message);
+        this.name = 'DocumentCommitConflictError';
+        this.externalContent = externalContent;
+        this.externalVersion = externalVersion;
+    }
+}
+export class DocumentSessionConflictError extends Error {
+    constructor(conflict) {
+        super('The document changed outside DocBlocks while local edits were pending.');
+        this.name = 'DocumentSessionConflictError';
+        this.conflict = conflict;
+    }
+}
+/**
+ * A revisioned, serialized persistence boundary for one active document.
+ *
+ * Invariants:
+ * - only drain() calls target.commit();
+ * - at most one commit is in flight;
+ * - revisions never decrease, including across target transitions;
+ * - destructive operations wait for an in-flight commit and run last;
+ * - a target is never changed by a React effect cleanup.
+ */
+export class DocumentSession {
+    constructor(options = {}) {
+        this.listeners = new Set();
+        this.target = null;
+        this.content = '';
+        this.persistedContent = null;
+        this.revision = 0;
+        this.persistedRevision = 0;
+        this.savingRevision = null;
+        this.savingContent = null;
+        this.generation = 0;
+        this.externalSequence = -1;
+        this.lifecycle = 'open';
+        this.frozen = false;
+        this.error = null;
+        this.conflict = null;
+        this.autoSaveTimer = null;
+        this.autoSaveRetryAttempt = 0;
+        this.drainPromise = null;
+        this.haltDrain = false;
+        this.operationTail = Promise.resolve();
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        };
+        this.getSnapshot = () => this.snapshot;
+        this.autoSaveDelayMs = Math.max(0, options.autoSaveDelayMs ?? 500);
+        this.autoSaveEnabled = options.autoSaveEnabled ?? true;
+        this.autoSaveRetryDelaysMs = normalizeRetryDelays(options.autoSaveRetryDelaysMs ?? DEFAULT_AUTO_SAVE_RETRY_DELAYS_MS);
+        this.recoveryJournal = options.recoveryJournal ?? null;
+        this.snapshot = this.createSnapshot();
+    }
+    /** Enable or disable automatic persistence without weakening explicit or lifecycle flushes. */
+    setAutoSaveEnabled(enabled) {
+        if (this.autoSaveEnabled === enabled)
+            return;
+        this.autoSaveEnabled = enabled;
+        if (!enabled) {
+            this.clearAutoSaveTimer();
+            return;
+        }
+        if (this.target &&
+            this.lifecycle === 'open' &&
+            !this.frozen &&
+            !this.conflict &&
+            this.persistedRevision < this.revision) {
+            this.scheduleAutoSave();
+        }
+    }
+    /**
+     * Record a complete local snapshot and schedule its persistence.
+     * Returns the assigned monotonic revision.
+     */
+    edit(content, scope) {
+        if (!this.target || this.lifecycle !== 'open' || this.frozen) {
+            throw new Error('Cannot edit a document session that is not open.');
+        }
+        if (scope.targetKey !== this.target.key || scope.generation !== this.generation) {
+            throw new Error('Cannot apply an edit from an obsolete document instance.');
+        }
+        if (content === this.content)
+            return this.revision;
+        this.content = content;
+        this.revision += 1;
+        this.error = null;
+        this.autoSaveRetryAttempt = 0;
+        if (this.conflict) {
+            this.conflict = {
+                ...this.conflict,
+                localContent: content,
+                localRevision: this.revision,
+            };
+        }
+        this.writeRecoverySnapshot();
+        if (!this.conflict)
+            this.scheduleAutoSave();
+        this.emit();
+        return this.revision;
+    }
+    /**
+     * Persist the revision current when flush() is called. A later edit may
+     * advance the session again, but commits remain strictly serialized.
+     */
+    async flush(reason = 'manual') {
+        this.clearAutoSaveTimer();
+        if (!this.target)
+            return this.snapshot;
+        if (this.conflict)
+            throw new DocumentSessionConflictError(this.conflict);
+        const requiredRevision = this.revision;
+        while (this.target && this.persistedRevision < requiredRevision) {
+            if (this.conflict)
+                throw new DocumentSessionConflictError(this.conflict);
+            if (this.haltDrain) {
+                throw new Error('Document persistence was cancelled before the requested revision saved.');
+            }
+            try {
+                await this.ensureDrain(reason);
+            }
+            catch (error) {
+                if (this.conflict)
+                    throw new DocumentSessionConflictError(this.conflict);
+                throw error;
+            }
+        }
+        if (this.conflict)
+            throw new DocumentSessionConflictError(this.conflict);
+        if (this.persistedRevision < requiredRevision) {
+            throw new Error('The document target closed before the requested revision saved.');
+        }
+        return this.snapshot;
+    }
+    /**
+     * Flush the old document, then replace it with a new clean baseline.
+     * UI state should change only after this promise resolves.
+     */
+    transitionTo(target, content) {
+        return this.enqueueOperation(() => this.performTransition(async () => ({ target, content })).then((snapshot) => {
+            if (!snapshot)
+                throw new Error('A fixed document transition cannot be cancelled.');
+            return snapshot;
+        }));
+    }
+    /**
+     * Freeze and flush the current document before reading the next one. The
+     * loader may return null when a navigation request was superseded, leaving
+     * the current target active and clean.
+     */
+    transitionWithLoad(load) {
+        return this.enqueueOperation(() => this.performTransition(load));
+    }
+    /**
+     * Flush the current path, run the storage move, and only then swap the
+     * commit target. No edit can enter between those steps.
+     */
+    retarget(nextTarget, moveStorage) {
+        return this.enqueueOperation(async () => {
+            this.assertNotPreparingClose();
+            if (!this.target)
+                throw new Error('Cannot retarget a session without a document.');
+            this.lifecycle = 'transitioning';
+            this.frozen = true;
+            this.emit();
+            try {
+                this.haltDrain = false;
+                await this.flush('transition');
+                await moveStorage();
+                this.generation += 1;
+                this.externalSequence = -1;
+                this.target = nextTarget;
+                this.error = null;
+                this.conflict = null;
+                this.lifecycle = 'open';
+                this.frozen = false;
+                this.emit();
+                return this.snapshot;
+            }
+            catch (error) {
+                if (isFileSystemMoveStateError(error)) {
+                    if (error.documentLocation === 'destination') {
+                        this.generation += 1;
+                        this.externalSequence = -1;
+                        this.target = nextTarget;
+                    }
+                    this.haltDrain = true;
+                    this.error = error;
+                    this.lifecycle = 'open';
+                    // The provider could not establish one authoritative compound move.
+                    // Keep editing frozen until navigation/recovery chooses a real path.
+                    this.frozen = true;
+                    this.emit();
+                    throw error;
+                }
+                this.lifecycle = 'open';
+                this.frozen = false;
+                this.emit();
+                throw error;
+            }
+        });
+    }
+    /**
+     * Cancel queued writes, wait for an already-running write, then delete.
+     * The deletion is therefore the final storage operation for this target.
+     */
+    delete(deleteStorage) {
+        return this.enqueueOperation(async () => {
+            this.assertNotPreparingClose();
+            this.lifecycle = 'transitioning';
+            this.frozen = true;
+            this.haltDrain = true;
+            this.clearAutoSaveTimer();
+            this.emit();
+            await this.awaitActiveDrain();
+            try {
+                await deleteStorage();
+            }
+            catch (error) {
+                this.haltDrain = false;
+                this.lifecycle = 'open';
+                this.frozen = false;
+                if (this.target && this.persistedRevision < this.revision && !this.conflict) {
+                    this.scheduleAutoSave();
+                }
+                this.emit();
+                throw error;
+            }
+            this.discardRecoverySnapshot();
+            this.detach();
+            return this.snapshot;
+        });
+    }
+    /**
+     * Discard queued changes and detach without mutating storage. This is used
+     * for explicitly abandoned sessions, never as an implicit effect cleanup.
+     */
+    cancel() {
+        return this.enqueueOperation(async () => {
+            this.lifecycle = 'transitioning';
+            this.frozen = true;
+            this.haltDrain = true;
+            this.clearAutoSaveTimer();
+            this.emit();
+            await this.awaitActiveDrain();
+            this.discardRecoverySnapshot();
+            this.detach();
+            return this.snapshot;
+        });
+    }
+    /**
+     * Observe a filesystem/host change captured for targetKey. Clean sessions
+     * adopt it. Dirty or saving sessions preserve local text and enter conflict.
+     */
+    observeExternal(change) {
+        if (!this.target || change.targetKey !== this.target.key || this.lifecycle === 'closed') {
+            return 'ignored';
+        }
+        if (change.sequence !== undefined) {
+            if (!Number.isSafeInteger(change.sequence) || change.sequence <= this.externalSequence) {
+                return 'ignored';
+            }
+            this.externalSequence = change.sequence;
+        }
+        // While conflicted, a current observation equal to the latest local
+        // snapshot proves that revision durable without requiring another write.
+        // Never acknowledge while a commit is still running; its eventual result
+        // remains authoritative for the serialized drain.
+        if (this.conflict &&
+            change.content === this.content &&
+            this.savingRevision === null &&
+            this.lifecycle === 'open') {
+            this.clearAutoSaveTimer();
+            this.autoSaveRetryAttempt = 0;
+            this.persistedRevision = this.revision;
+            this.persistedContent = this.content;
+            this.haltDrain = false;
+            this.error = null;
+            this.conflict = null;
+            this.discardRecoverySnapshot();
+            this.emit();
+            return 'applied';
+        }
+        // Once a conflict exists, every later accepted observation refreshes its
+        // external branch before ordinary duplicate suppression. In particular,
+        // A -> local C -> external B -> external A must offer A, not stale B, when
+        // the user chooses Reload external.
+        if (this.conflict) {
+            const externalVersion = change.version ?? null;
+            if (this.conflict.localContent === this.content &&
+                this.conflict.localRevision === this.revision &&
+                this.conflict.externalContent === change.content &&
+                this.conflict.externalVersion === externalVersion) {
+                return 'ignored';
+            }
+            this.clearAutoSaveTimer();
+            this.haltDrain = true;
+            this.conflict = {
+                targetKey: change.targetKey,
+                localContent: this.content,
+                localRevision: this.revision,
+                externalContent: change.content,
+                externalVersion,
+            };
+            this.error = null;
+            this.writeRecoverySnapshot();
+            this.emit();
+            return 'conflict';
+        }
+        if (change.content === this.content ||
+            change.content === this.persistedContent ||
+            (this.savingRevision !== null && change.content === this.savingContent)) {
+            return 'ignored';
+        }
+        const isClean = this.persistedRevision === this.revision &&
+            this.savingRevision === null &&
+            this.error === null &&
+            this.conflict === null;
+        if (isClean && change.content !== null) {
+            this.content = change.content;
+            this.revision += 1;
+            this.persistedRevision = this.revision;
+            this.persistedContent = change.content;
+            this.generation += 1;
+            this.discardRecoverySnapshot();
+            this.emit();
+            return 'applied';
+        }
+        this.clearAutoSaveTimer();
+        this.haltDrain = true;
+        this.conflict = {
+            targetKey: change.targetKey,
+            localContent: this.content,
+            localRevision: this.revision,
+            externalContent: change.content,
+            externalVersion: change.version ?? null,
+        };
+        this.error = null;
+        this.writeRecoverySnapshot();
+        this.emit();
+        return 'conflict';
+    }
+    resolveConflict(strategy) {
+        return this.enqueueOperation(async () => {
+            if (!this.conflict)
+                return this.snapshot;
+            this.clearAutoSaveTimer();
+            this.haltDrain = true;
+            await this.awaitActiveDrain();
+            // A watcher may refresh or converge the conflict while an in-flight
+            // commit settles. Resolve the branch that is current now, never the
+            // snapshot captured before the await.
+            const currentConflict = this.conflict;
+            if (!currentConflict)
+                return this.snapshot;
+            if (strategy === 'use-external') {
+                this.discardRecoverySnapshot();
+                this.generation += 1;
+                this.revision += 1;
+                this.conflict = null;
+                this.error = null;
+                this.haltDrain = false;
+                if (currentConflict.externalContent === null) {
+                    this.target = null;
+                    this.content = '';
+                    this.persistedContent = null;
+                    this.persistedRevision = this.revision;
+                    this.lifecycle = 'closed';
+                    this.frozen = true;
+                }
+                else {
+                    this.content = currentConflict.externalContent;
+                    this.persistedContent = currentConflict.externalContent;
+                    this.persistedRevision = this.revision;
+                    this.lifecycle = 'open';
+                    this.frozen = false;
+                }
+                this.emit();
+                return this.snapshot;
+            }
+            // Keep the local branch, but make the observed external snapshot the
+            // optimistic baseline for the next conditional commit.
+            this.persistedContent = currentConflict.externalContent;
+            // A clean external deletion/conflict has no unsaved local revision.
+            // Keeping local still requires a fresh commit that recreates/overwrites
+            // the target, so make that intent explicit with a new revision.
+            this.revision += 1;
+            this.conflict = null;
+            this.error = null;
+            this.haltDrain = false;
+            this.lifecycle = 'open';
+            this.frozen = false;
+            this.writeRecoverySnapshot();
+            this.emit();
+            return this.flush('conflict');
+        });
+    }
+    /**
+     * Freeze edits and flush through the latest revision. A successful call
+     * remains frozen until cancelClose(); the owning host may now destroy it.
+     */
+    prepareClose() {
+        return this.enqueueOperation(async () => {
+            if (this.lifecycle === 'closing')
+                return this.snapshot;
+            this.lifecycle = 'closing';
+            this.frozen = true;
+            this.haltDrain = false;
+            this.emit();
+            try {
+                await this.flush('close');
+                return this.snapshot;
+            }
+            catch (error) {
+                this.lifecycle = 'open';
+                this.frozen = false;
+                this.emit();
+                throw error;
+            }
+        });
+    }
+    /** Resume editing when a host cancels a prepared close. */
+    cancelClose() {
+        if (this.lifecycle !== 'closing')
+            return;
+        this.lifecycle = 'open';
+        this.frozen = false;
+        this.haltDrain = false;
+        if (this.target && this.persistedRevision < this.revision && !this.conflict) {
+            this.scheduleAutoSave();
+        }
+        this.emit();
+    }
+    async performTransition(load) {
+        this.assertNotPreparingClose();
+        this.lifecycle = 'transitioning';
+        this.frozen = true;
+        this.emit();
+        try {
+            this.haltDrain = false;
+            await this.flush('transition');
+            this.clearAutoSaveTimer();
+            const next = await load();
+            if (!next) {
+                this.lifecycle = 'open';
+                this.frozen = false;
+                this.emit();
+                return null;
+            }
+            this.generation += 1;
+            this.externalSequence = -1;
+            this.target = next.target;
+            this.content = next.content;
+            this.revision += 1;
+            this.persistedRevision = this.revision;
+            this.persistedContent = next.target ? next.content : null;
+            this.savingRevision = null;
+            this.savingContent = null;
+            this.error = null;
+            this.conflict = null;
+            this.haltDrain = false;
+            this.lifecycle = 'open';
+            this.frozen = false;
+            const recoveryState = this.restoreRecoverySnapshot();
+            if (recoveryState === 'dirty')
+                this.scheduleAutoSave();
+            this.emit();
+            return this.snapshot;
+        }
+        catch (error) {
+            this.lifecycle = 'open';
+            this.frozen = false;
+            this.emit();
+            throw error;
+        }
+    }
+    scheduleAutoSave(delayMs = this.autoSaveDelayMs) {
+        this.clearAutoSaveTimer();
+        if (!this.autoSaveEnabled)
+            return;
+        this.autoSaveTimer = setTimeout(() => {
+            this.autoSaveTimer = null;
+            const target = this.target;
+            const generation = this.generation;
+            void this.flush('autosave').then(() => {
+                this.autoSaveRetryAttempt = 0;
+            }, () => {
+                // Preserve honest error/conflict state while making ordinary I/O
+                // failures recoverable. A newer edit already owns a fresh debounce
+                // timer, and lifecycle operations cancel this retry path.
+                if (this.autoSaveTimer !== null ||
+                    !target ||
+                    target !== this.target ||
+                    generation !== this.generation ||
+                    this.lifecycle !== 'open' ||
+                    this.frozen ||
+                    this.haltDrain ||
+                    this.conflict ||
+                    this.persistedRevision >= this.revision) {
+                    return;
+                }
+                const retryDelay = this.autoSaveRetryDelaysMs[this.autoSaveRetryAttempt];
+                if (retryDelay === undefined)
+                    return;
+                this.autoSaveRetryAttempt += 1;
+                this.scheduleAutoSave(retryDelay);
+            });
+        }, delayMs);
+    }
+    clearAutoSaveTimer() {
+        if (this.autoSaveTimer === null)
+            return;
+        clearTimeout(this.autoSaveTimer);
+        this.autoSaveTimer = null;
+    }
+    ensureDrain(reason) {
+        if (this.drainPromise)
+            return this.drainPromise;
+        const running = this.drain(reason);
+        this.drainPromise = running;
+        const clear = () => {
+            if (this.drainPromise === running)
+                this.drainPromise = null;
+        };
+        void running.then(clear, clear);
+        return running;
+    }
+    async drain(reason) {
+        while (this.target &&
+            !this.haltDrain &&
+            !this.conflict &&
+            this.persistedRevision < this.revision) {
+            const target = this.target;
+            const generation = this.generation;
+            const saveRevision = this.revision;
+            const saveContent = this.content;
+            const previousPersistedRevision = this.persistedRevision;
+            const previousPersistedContent = this.persistedContent;
+            this.savingRevision = saveRevision;
+            this.savingContent = saveContent;
+            this.error = null;
+            this.emit();
+            try {
+                await target.commit({
+                    targetKey: target.key,
+                    content: saveContent,
+                    revision: saveRevision,
+                    persistedRevision: previousPersistedRevision,
+                    persistedContent: previousPersistedContent,
+                    reason,
+                });
+            }
+            catch (error) {
+                this.savingRevision = null;
+                this.savingContent = null;
+                if (error instanceof DocumentCommitConflictError) {
+                    this.haltDrain = true;
+                    this.conflict = {
+                        targetKey: target.key,
+                        localContent: this.content,
+                        localRevision: this.revision,
+                        externalContent: error.externalContent,
+                        externalVersion: error.externalVersion,
+                    };
+                    this.error = null;
+                }
+                else {
+                    this.error = toError(error);
+                }
+                this.emit();
+                throw error;
+            }
+            if (generation !== this.generation || target !== this.target)
+                return;
+            this.persistedRevision = Math.max(this.persistedRevision, saveRevision);
+            this.persistedContent = saveContent;
+            this.autoSaveRetryAttempt = 0;
+            this.savingRevision = null;
+            this.savingContent = null;
+            this.error = null;
+            const activeConflict = this.getSnapshot().conflict;
+            if (activeConflict?.externalContent === saveContent && this.content === saveContent) {
+                // An observation that matched the in-flight local snapshot could not
+                // be acknowledged until the commit settled. Its successful return now
+                // proves both branches converged on the same durable revision.
+                this.conflict = null;
+                this.haltDrain = false;
+            }
+            this.recoveryJournal?.acknowledge({
+                targetKey: target.key,
+                generation,
+                persistedRevision: this.persistedRevision,
+            });
+            this.emit();
+        }
+    }
+    async awaitActiveDrain() {
+        const active = this.drainPromise;
+        if (!active)
+            return;
+        try {
+            await active;
+        }
+        catch {
+            // A destructive cancellation still waits for the operation to settle,
+            // but a failed obsolete write must not prevent the requested deletion.
+        }
+    }
+    /**
+     * Rehydrate a synchronous crash snapshot after the durable baseline has
+     * been read. A matching baseline is safe to resume as dirty; a changed
+     * baseline becomes an explicit conflict and is never auto-overwritten.
+     */
+    restoreRecoverySnapshot() {
+        if (!this.target || !this.recoveryJournal)
+            return 'none';
+        const recovered = this.recoveryJournal.lookup(this.target.key);
+        if (!recovered)
+            return 'none';
+        if (recovered.content === this.content) {
+            this.recoveryJournal.acknowledge({
+                targetKey: recovered.targetKey,
+                generation: recovered.generation,
+                persistedRevision: recovered.revision,
+            });
+            return 'none';
+        }
+        const externalContent = this.content;
+        this.generation = Math.max(this.generation, recovered.generation) + 1;
+        this.revision = Math.max(this.revision, recovered.revision) + 1;
+        this.content = recovered.content;
+        if (recovered.persistedContent === externalContent) {
+            this.writeRecoverySnapshot();
+            return 'dirty';
+        }
+        // Preserve the journal's prior baseline so a second crash continues to
+        // reopen as a conflict until the user explicitly chooses a branch.
+        this.persistedContent = recovered.persistedContent;
+        this.haltDrain = true;
+        this.conflict = {
+            targetKey: this.target.key,
+            localContent: recovered.content,
+            localRevision: this.revision,
+            externalContent,
+            externalVersion: null,
+        };
+        this.writeRecoverySnapshot();
+        return 'conflict';
+    }
+    writeRecoverySnapshot() {
+        if (!this.target || !this.recoveryJournal)
+            return;
+        if (this.persistedRevision >= this.revision && !this.conflict)
+            return;
+        this.recoveryJournal.write({
+            targetKey: this.target.key,
+            generation: this.generation,
+            revision: this.revision,
+            content: this.content,
+            persistedContent: this.persistedContent,
+        });
+    }
+    discardRecoverySnapshot() {
+        if (!this.target)
+            return;
+        this.recoveryJournal?.discard(this.target.key);
+    }
+    detach() {
+        this.clearAutoSaveTimer();
+        this.autoSaveRetryAttempt = 0;
+        this.generation += 1;
+        this.externalSequence = -1;
+        this.target = null;
+        this.persistedContent = null;
+        this.savingRevision = null;
+        this.savingContent = null;
+        this.error = null;
+        this.conflict = null;
+        this.haltDrain = false;
+        this.lifecycle = 'closed';
+        this.frozen = true;
+        this.emit();
+    }
+    assertNotPreparingClose() {
+        if (this.lifecycle === 'closing') {
+            throw new Error('The document is already prepared for close.');
+        }
+    }
+    enqueueOperation(operation) {
+        const run = this.operationTail.then(operation, operation);
+        this.operationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    createSnapshot() {
+        return Object.freeze({
+            targetKey: this.target?.key ?? null,
+            content: this.content,
+            revision: this.revision,
+            persistedRevision: this.persistedRevision,
+            persistedContent: this.persistedContent,
+            savingRevision: this.savingRevision,
+            generation: this.generation,
+            status: this.computeStatus(),
+            lifecycle: this.lifecycle,
+            frozen: this.frozen,
+            error: this.error,
+            conflict: this.conflict,
+        });
+    }
+    computeStatus() {
+        if (this.lifecycle === 'closed')
+            return 'closed';
+        if (!this.target)
+            return 'idle';
+        if (this.conflict)
+            return 'conflict';
+        if (this.error)
+            return 'error';
+        if (this.savingRevision !== null)
+            return 'saving';
+        return this.persistedRevision < this.revision ? 'dirty' : 'saved';
+    }
+    emit() {
+        this.snapshot = this.createSnapshot();
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function normalizeRetryDelays(delays) {
+    return delays.map((delay) => {
+        if (!Number.isFinite(delay) || delay < 0) {
+            throw new TypeError('Autosave retry delays must be finite, non-negative numbers.');
+        }
+        return Math.floor(delay);
+    });
+}
+//# sourceMappingURL=document-session.js.map