@bendyline/docblocks 2.0.0 → 2.1.0

package/dist/document/document-session.js

@@ -1,749 +0,0 @@
-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