Skip to content

Build your personal knowledge base with Trilium Notes

14.2 KB
Raw Blame
import type { SaveState } from "../components/note_context";
import { getErrorMessage } from "./utils";

type Callback = () => Promise<void> | void;

export type StateCallback = (state: SaveState) => void;

type PrepareCallback<T> = () => T | Promise<T>;
type CommitCallback<T> = (data: T) => Promise<void> | void;

/**
 * Binds pending changes to the target they belong to (see #9614).
 *
 * A change scheduled while one binding is active is always *snapshotted* (via {@link SpacedUpdateBinding.prepare})
 * before the binding can be swapped to a different key, and the snapshot is committed together with the
 * `commit` closure that was current when it was taken. This makes it impossible for a pending change to be
 * persisted under a different target than the one it was made against, no matter when the save fires.
 */
export interface SpacedUpdateBinding<T> {
    /** Identity of the save target (e.g. a noteId). Pending changes never cross a key change. */
    key: string | null;
    /** Snapshots the live state that should be saved. May refuse by returning a value `commit` treats as a no-op. */
    prepare: PrepareCallback<T>;
    /** Persists a snapshot. Retries always reuse the closure that was current when the snapshot was taken. */
    commit: CommitCallback<T>;
}

interface PendingCommit<T> {
    data: T;
    commit: CommitCallback<T>;
}

const MAX_RETRY_DELAY = 60_000;
/** The longest that `resetUpdateTimer()` can postpone a pending change, in intervals. */
const MAX_POSTPONED_INTERVALS = 10;

export default class SpacedUpdate<T = void> {
    private bindingKey: string | null;
    private prepare: PrepareCallback<T>;
    private commit: CommitCallback<T>;
    private lastUpdated: number;
    private changed: boolean;
    /** When the oldest change that is not snapshotted yet was made. */
    private changedSince = 0;
    private updateInterval: number;
    private changeForbidden?: boolean;
    private stateCallback?: StateCallback;
    private lastState: SaveState = "saved";

    /**
     * Snapshots that have been taken but not successfully persisted yet, by binding key.
     * A newer snapshot for the same key supersedes the queued one. Entries survive failed
     * commits and are retried (with backoff) until they land — they are never dropped.
     */
    private pendingCommits = new Map<string | null, PendingCommit<T>>();
    /** Snapshots whose asynchronous `prepare` is still running — captured but not yet queued. */
    private pendingSnapshots = new Set<Promise<void>>();
    private drainPromise: Promise<void> | null = null;
    private debounceTimer?: ReturnType<typeof setTimeout>;
    private retryTimer?: ReturnType<typeof setTimeout>;
    private retryCount = 0;

    constructor(updaterOrBinding: Callback | SpacedUpdateBinding<T>, updateInterval = 1000, stateCallback?: StateCallback) {
        if (typeof updaterOrBinding === "function") {
            // Legacy single-callback mode: the updater reads live state and persists it in one
            // step, so there is nothing to snapshot and the binding key never changes.
            this.bindingKey = null;
            this.prepare = () => undefined as T;
            this.commit = () => updaterOrBinding();
        } else {
            this.bindingKey = updaterOrBinding.key;
            this.prepare = updaterOrBinding.prepare;
            this.commit = updaterOrBinding.commit;
        }

        this.lastUpdated = Date.now();
        this.changed = false;
        this.updateInterval = updateInterval;
        this.stateCallback = stateCallback;
    }

    scheduleUpdate() {
        if (!this.changeForbidden) {
            if (!this.changed) {
                this.changedSince = Date.now();
            }
            this.changed = true;
            this.onStateChanged("unsaved");
            this.armDebounceTimer();
        }
    }

    /**
     * Swaps the binding to a new target. If the key changes while a change is still pending,
     * the change is first snapshotted with the *previous* binding (and committed in the
     * background, addressed to the previous key), so it can never be saved under the new key.
     */
    rebind(key: string | null, prepare: PrepareCallback<T>, commit: CommitCallback<T>) {
        if (key !== this.bindingKey && this.changed) {
            const snapshotted = this.snapshotPending();
            const drainInBackground = () => {
                this.drain().catch(() => {
                    // Failures are logged in runDrain and retried; the snapshot stays addressed to the old key.
                });
            };

            if (snapshotted instanceof Promise) {
                // The old prepare() was already invoked synchronously, so swapping the binding
                // below cannot leak the pending change to the new key.
                snapshotted.then(drainInBackground, () => {});
            } else {
                drainInBackground();
            }
        }

        this.bindingKey = key;
        this.prepare = prepare;
        this.commit = commit;
    }

    /**
     * Flushes the pending change (if any) and waits until all queued snapshots are persisted, with
     * the changes made while they save. The pending change is read at once, also while another
     * save runs, so its source can go away.
     */
    async updateNowIfNecessary(): Promise<void> {
        do {
            if (this.drainPromise) {
                // The running save waits for an asynchronous snapshot and handles its failure.
                const snapshotted = this.snapshotPending();
                if (snapshotted instanceof Promise) {
                    snapshotted.catch(() => {});
                }
            }
            await this.drain();
        } while (this.changed);
    }

    /** Whether a change made under the current binding is not saved yet. */
    hasUnsavedChanges() {
        return this.changed || this.pendingCommits.has(this.bindingKey);
    }

    isAllSavedAndTriggerUpdate() {
        const allSaved = !this.changed
            && this.pendingCommits.size === 0
            && this.pendingSnapshots.size === 0
            && !this.drainPromise;

        this.updateNowIfNecessary().catch(() => {
            // Failures are logged in runDrain and retried.
        });

        return allSaved;
    }

    /**
     * Normally {@link scheduleUpdate()} would actually trigger the update only once per {@link updateInterval}. If the method is called 200 times within 20s, it will execute only 20 times.
     * Sometimes, if the updates are continuous this would cause a performance impact. Resetting the time ensures that the calls to the update have stopped before actually triggering an update.
     * A pending change is still saved at most {@link MAX_POSTPONED_INTERVALS} intervals after it
     * was made.
     */
    resetUpdateTimer() {
        this.lastUpdated = Date.now();
    }

    /**
     * Sets the update interval for the spaced update.
     * @param interval The update interval in milliseconds.
     */
    setUpdateInterval(interval: number) {
        this.updateInterval = interval;
    }

    onStateChanged(state: SaveState) {
        if (state === this.lastState) return;

        this.stateCallback?.(state);
        this.lastState = state;
    }

    async allowUpdateWithoutChange(callback: Callback) {
        this.changeForbidden = true;

        try {
            await callback();
        } finally {
            this.changeForbidden = false;
        }
    }

    /**
     * Single debounce timer replacing the old 0-ms self-rescheduling loop: armed with the time
     * remaining until the interval elapses, re-armed if {@link resetUpdateTimer} pushed it back.
     */
    private armDebounceTimer() {
        if (this.debounceTimer) {
            return;
        }

        const delay = Math.max(1, this.getTimeUntilDue());
        this.debounceTimer = setTimeout(() => {
            this.debounceTimer = undefined;

            if (!this.changed) {
                return;
            }

            if (this.getTimeUntilDue() <= 0) {
                this.drain().catch(() => {
                    // Failures are logged in runDrain and retried.
                });
            } else {
                this.armDebounceTimer();
            }
        }, delay);
    }

    /**
     * Milliseconds until the pending change is due: one interval after the last update or reset,
     * but no later than {@link MAX_POSTPONED_INTERVALS} intervals after the change.
     */
    private getTimeUntilDue() {
        const now = Date.now();
        return Math.min(
            this.updateInterval - (now - this.lastUpdated),
            this.updateInterval * MAX_POSTPONED_INTERVALS - (now - this.changedSince)
        );
    }

    /**
     * Snapshots the pending change with the *current* binding and queues it for commit.
     * Returns a promise only when `prepare` is asynchronous; in the synchronous case the
     * snapshot is queued before this method returns, so callers (notably the `beforeunload`
     * path) can rely on the commit starting synchronously within {@link drain}.
     */
    private snapshotPending(): void | Promise<void> {
        if (!this.changed) {
            return;
        }

        this.changed = false;
        this.lastUpdated = Date.now();

        const { bindingKey, commit } = this;
        const restoreOnError = (e: unknown): never => {
            this.changed = true;
            this.changedSince = Date.now();
            this.onStateChanged("error");
            // Said out loud, as a failed commit is. Every caller of this path swallows what is
            // rethrown, so a snapshot that cannot be taken would otherwise show as a failing save
            // indicator and nothing else — anywhere.
            logError(getErrorMessage(e));
            // The debounce timer may have already fired and gone idle while the snapshot was
            // being captured; schedule a retry so the restored change is not stranded until
            // the next scheduleUpdate() call. Going through the retry timer (rather than the
            // debounce timer) gives persistent prepare() failures exponential backoff.
            this.scheduleRetry();
            throw e;
        };

        let result: T | Promise<T>;
        try {
            result = this.prepare();
        } catch (e) {
            return restoreOnError(e);
        }

        if (result instanceof Promise) {
            // Track the in-flight snapshot so drain() and isAllSavedAndTriggerUpdate() don't
            // consider everything saved before the snapshot has been queued for commit.
            const snapshot: Promise<void> = result
                .then(
                    (data) => {
                        this.pendingCommits.set(bindingKey, { data, commit });
                    },
                    restoreOnError
                )
                .finally(() => {
                    this.pendingSnapshots.delete(snapshot);
                });
            this.pendingSnapshots.add(snapshot);
            return snapshot;
        }

        this.pendingCommits.set(bindingKey, { data: result, commit });
    }

    private drain(): Promise<void> {
        if (this.drainPromise) {
            return this.drainPromise;
        }

        if (!this.changed && this.pendingCommits.size === 0 && this.pendingSnapshots.size === 0) {
            return Promise.resolve();
        }

        this.drainPromise = this.runDrain().finally(() => {
            this.drainPromise = null;
        });

        return this.drainPromise;
    }

    private async runDrain(): Promise<void> {
        let isFirstPass = true;
        while (true) {
            // Wait for snapshots that were started elsewhere (e.g. by rebind) to be queued.
            // Their failures restore the `changed` flag and are handled by the fold below.
            while (this.pendingSnapshots.size > 0) {
                await Promise.allSettled([ ...this.pendingSnapshots ]);
            }

            // Fold any pending change into the queue first, so a queued snapshot and a newer
            // pending change for the same key result in a single save, not two. Changes made
            // after the first pass wait for the debounce timer.
            if (isFirstPass) {
                isFirstPass = false;
                const snapshotted = this.snapshotPending();
                if (snapshotted instanceof Promise) {
                    await snapshotted;
                }
            }

            if (this.pendingCommits.size === 0) {
                break;
            }

            this.onStateChanged("saving");

            let failed = false;
            let firstError: unknown;

            for (const key of [ ...this.pendingCommits.keys() ]) {
                const entry = this.pendingCommits.get(key);
                if (!entry) {
                    continue;
                }

                try {
                    await entry.commit(entry.data);

                    // Delete only if the entry was not superseded by a newer snapshot during the await.
                    if (this.pendingCommits.get(key) === entry) {
                        this.pendingCommits.delete(key);
                    }
                } catch (e) {
                    if (!failed) {
                        failed = true;
                        firstError = e;
                    }
                    logError(getErrorMessage(e));
                }
            }

            if (failed) {
                this.onStateChanged("error");
                this.scheduleRetry();
                throw firstError;
            }
        }

        // Reset the retry backoff only once everything has landed; resetting it on individual
        // successes would shorten the backoff of a still-failing sibling key.
        this.retryCount = 0;
        this.onStateChanged(this.changed ? "unsaved" : "saved");
        if (this.changed) {
            this.armDebounceTimer();
        }
    }

    private scheduleRetry() {
        if (this.retryTimer) {
            return;
        }

        const delay = Math.min(this.updateInterval * 2 ** this.retryCount, MAX_RETRY_DELAY);
        this.retryCount++;

        this.retryTimer = setTimeout(() => {
            this.retryTimer = undefined;
            this.drain().catch(() => {
                // Failures are logged in runDrain and will be retried again.
            });
        }, delay);
    }
}