Skip to content

Build your personal knowledge base with Trilium Notes

22.3 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import SpacedUpdate from "./spaced_update";

// Mock logError which is a global in Trilium
vi.stubGlobal("logError", vi.fn());

describe("SpacedUpdate", () => {
    beforeEach(() => {
        vi.useFakeTimers();
    });

    afterEach(() => {
        vi.useRealTimers();
    });

    it("should only call updater once per interval even with multiple pending callbacks", async () => {
        const updater = vi.fn(async () => {
            // Simulate a slow network request - this is where the race condition occurs
            await new Promise((resolve) => setTimeout(resolve, 100));
        });

        const spacedUpdate = new SpacedUpdate(updater, 50);

        // Simulate rapid typing - each keystroke calls scheduleUpdate()
        // This queues multiple setTimeout callbacks due to recursive scheduleUpdate() calls
        for (let i = 0; i < 10; i++) {
            spacedUpdate.scheduleUpdate();
            // Small delay between keystrokes
            await vi.advanceTimersByTimeAsync(5);
        }

        // Advance time past the update interval to trigger the update
        await vi.advanceTimersByTimeAsync(100);

        // Let the "network request" complete and any pending callbacks run
        await vi.advanceTimersByTimeAsync(200);

        // The updater should have been called only ONCE, not multiple times
        // With the bug, multiple pending setTimeout callbacks would all pass the time check
        // during the async updater call and trigger multiple concurrent requests
        expect(updater).toHaveBeenCalledTimes(1);
    });

    it("should call updater again if changes occur during the update", async () => {
        const updater = vi.fn(async () => {
            await new Promise((resolve) => setTimeout(resolve, 50));
        });

        const spacedUpdate = new SpacedUpdate(updater, 30);

        // First update
        spacedUpdate.scheduleUpdate();
        await vi.advanceTimersByTimeAsync(40);

        // Schedule another update while the first one is in progress
        spacedUpdate.scheduleUpdate();

        // Let first update complete
        await vi.advanceTimersByTimeAsync(60);

        // Advance past the interval again for the second update
        await vi.advanceTimersByTimeAsync(100);

        // Should have been called twice - once for each distinct change period
        expect(updater).toHaveBeenCalledTimes(2);
    });

    it("should restore changed flag on error so retry can happen", async () => {
        const updater = vi.fn()
            .mockRejectedValueOnce(new Error("Network error"))
            .mockResolvedValue(undefined);

        const spacedUpdate = new SpacedUpdate(updater, 50);

        spacedUpdate.scheduleUpdate();

        // Advance to trigger first update (which will fail)
        await vi.advanceTimersByTimeAsync(60);

        // The error should have restored the changed flag, so scheduling again should work
        spacedUpdate.scheduleUpdate();
        await vi.advanceTimersByTimeAsync(60);

        expect(updater).toHaveBeenCalledTimes(2);
    });

    describe("updateNowIfNecessary", () => {
        it("calls updater and emits saving/saved states when there are pending changes", async () => {
            const states: string[] = [];
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50, (s) => states.push(s));

            // Mark as changed without triggering the timer-based update.
            spacedUpdate.scheduleUpdate();

            await spacedUpdate.updateNowIfNecessary();

            expect(updater).toHaveBeenCalledTimes(1);
            expect(states).toEqual(["unsaved", "saving", "saved"]);
        });

        it("does nothing when there are no pending changes", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            await spacedUpdate.updateNowIfNecessary();

            expect(updater).not.toHaveBeenCalled();
        });

        it("also saves the changes made while it saves", async () => {
            let finishFirstSave = () => {};
            const updater = vi.fn()
                .mockImplementationOnce(() => new Promise<void>((resolve) => {
                    finishFirstSave = resolve;
                }))
                .mockResolvedValue(undefined);
            const spacedUpdate = new SpacedUpdate(updater, 50);

            spacedUpdate.scheduleUpdate();
            const flushed = spacedUpdate.updateNowIfNecessary();
            spacedUpdate.scheduleUpdate();
            finishFirstSave();
            await flushed;

            expect(updater).toHaveBeenCalledTimes(2);
            expect(spacedUpdate.hasUnsavedChanges()).toBe(false);
        });

        it("re-marks changed, emits error and rethrows when the updater fails", async () => {
            const states: string[] = [];
            let shouldFail = true;
            const updater = vi.fn(async () => {
                if (shouldFail) {
                    throw new Error("boom");
                }
            });
            const spacedUpdate = new SpacedUpdate(updater, 50, (s) => states.push(s));

            spacedUpdate.scheduleUpdate();

            await expect(spacedUpdate.updateNowIfNecessary()).rejects.toThrow("boom");
            expect(states).toEqual(["unsaved", "saving", "error"]);

            // changed flag restored -> a subsequent successful flush runs the updater again
            shouldFail = false;
            await spacedUpdate.updateNowIfNecessary();
            expect(updater).toHaveBeenCalledTimes(2);
        });
    });

    describe("isAllSavedAndTriggerUpdate", () => {
        it("returns false and flushes pending changes when there are changes", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            spacedUpdate.scheduleUpdate();

            expect(spacedUpdate.isAllSavedAndTriggerUpdate()).toBe(false);

            await vi.runAllTimersAsync();
            expect(updater).toHaveBeenCalledTimes(1);
        });

        it("returns true when nothing is pending", () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            expect(spacedUpdate.isAllSavedAndTriggerUpdate()).toBe(true);
            expect(updater).not.toHaveBeenCalled();
        });

        it("returns the pre-flush saved state synchronously and kicks off the un-awaited flush", () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            spacedUpdate.scheduleUpdate(); // pending change

            // `allSaved` is computed from `changed` BEFORE the (un-awaited) updateNowIfNecessary()
            // flush runs, so the call returns false for a pending change and never throws.
            let result: boolean;
            expect(() => {
                result = spacedUpdate.isAllSavedAndTriggerUpdate();
            }).not.toThrow();
            expect(result!).toBe(false);

            // The flush was started synchronously (updater invoked) rather than awaited.
            expect(updater).toHaveBeenCalledTimes(1);
        });

        it("restores the changed flag when an update fails so a later flush retries", async () => {
            const states: string[] = [];
            let shouldFail = true;
            const updater = vi.fn(async () => {
                if (shouldFail) {
                    throw new Error("flush boom");
                }
            });
            const spacedUpdate = new SpacedUpdate(updater, 50, (s) => states.push(s));

            spacedUpdate.scheduleUpdate();

            // Await the flush directly (the same code path isAllSavedAndTriggerUpdate fires
            // and forgets) so the rejection is observed here instead of floating.
            await expect(spacedUpdate.updateNowIfNecessary()).rejects.toThrow("flush boom");
            expect(states).toContain("error");

            // The catch restored `changed`, so a subsequent flush retries the updater and saves.
            shouldFail = false;
            await spacedUpdate.updateNowIfNecessary();
            expect(updater).toHaveBeenCalledTimes(2);
            expect(states).toContain("saved");
        });
    });

    describe("resetUpdateTimer / setUpdateInterval", () => {
        it("resetUpdateTimer defers the update past the new last-updated time", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            spacedUpdate.scheduleUpdate();
            // Keep resetting the timer so the interval never elapses.
            await vi.advanceTimersByTimeAsync(40);
            spacedUpdate.resetUpdateTimer();
            await vi.advanceTimersByTimeAsync(40);
            spacedUpdate.resetUpdateTimer();
            await vi.advanceTimersByTimeAsync(40);

            // Still within the interval since the last reset -> no update yet.
            expect(updater).not.toHaveBeenCalled();

            // Now let the interval fully elapse.
            await vi.advanceTimersByTimeAsync(60);
            expect(updater).toHaveBeenCalledTimes(1);
        });

        it("setUpdateInterval changes how long before the update fires", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            spacedUpdate.setUpdateInterval(500);
            spacedUpdate.scheduleUpdate();

            // Past the old interval but not the new one.
            await vi.advanceTimersByTimeAsync(100);
            expect(updater).not.toHaveBeenCalled();

            await vi.advanceTimersByTimeAsync(500);
            expect(updater).toHaveBeenCalledTimes(1);
        });

        it("waits for changes made during a save to pause before saving them", async () => {
            const updater = vi.fn(async () => {
                await new Promise((resolve) => setTimeout(resolve, 100));
            });
            const spacedUpdate = new SpacedUpdate(updater, 50);
            const type = () => {
                spacedUpdate.resetUpdateTimer();
                spacedUpdate.scheduleUpdate();
            };

            // The first save starts at 50 ms and runs until 150 ms.
            type();
            await vi.advanceTimersByTimeAsync(60);
            expect(updater).toHaveBeenCalledTimes(1);

            // Typing continues through the save and after it, until 300 ms.
            for (let i = 0; i < 12; i++) {
                type();
                await vi.advanceTimersByTimeAsync(20);
            }
            expect(updater).toHaveBeenCalledTimes(1);

            await vi.advanceTimersByTimeAsync(60);
            expect(updater).toHaveBeenCalledTimes(2);
        });

        it("saves a change within ten intervals, however often the timer is reset", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            for (let i = 0; i < 30; i++) {
                spacedUpdate.resetUpdateTimer();
                spacedUpdate.scheduleUpdate();
                await vi.advanceTimersByTimeAsync(20);
            }

            expect(updater).toHaveBeenCalledTimes(1);
        });
    });

    describe("keyed bindings (prepare/commit)", () => {
        function setupKeyedHarness() {
            // Stand-in for a reused editor: holds whichever note's content was last loaded.
            const editor = { content: "A content" };
            const commits: { key: string; data: string }[] = [];
            const makeBinding = (key: string) => ({
                key,
                prepare: () => editor.content,
                commit: async (data: string) => {
                    commits.push({ key, data });
                }
            });
            return { editor, commits, makeBinding };
        }

        it("commits a pending change under the binding that scheduled it, even after rebinding", async () => {
            const { editor, commits, makeBinding } = setupKeyedHarness();
            const spacedUpdate = new SpacedUpdate<string>(makeBinding("A"), 50);

            // A change is pending against A when the consumer rebinds to B; the snapshot is
            // taken with A's binding before the swap, so it can never be saved under B.
            spacedUpdate.scheduleUpdate();
            const b = makeBinding("B");
            spacedUpdate.rebind(b.key, b.prepare, b.commit);
            editor.content = "B content"; // B's content arrives only after the rebind

            await vi.runAllTimersAsync();
            expect(commits).toEqual([{ key: "A", data: "A content" }]);

            // A change made after the rebind saves under the new binding.
            spacedUpdate.scheduleUpdate();
            await vi.runAllTimersAsync();
            expect(commits).toEqual([
                { key: "A", data: "A content" },
                { key: "B", data: "B content" }
            ]);
        });

        it("reads a pending change at once when a save is asked for while another one runs", async () => {
            const editor = { content: "first" };
            const commits: string[] = [];
            let finishFirstCommit = () => {};
            const firstCommitDone = new Promise<void>((resolve) => {
                finishFirstCommit = resolve;
            });
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => editor.content,
                commit: async (data) => {
                    commits.push(data);
                    if (commits.length === 1) await firstCommitDone;
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            const firstSave = spacedUpdate.updateNowIfNecessary();
            editor.content = "second";
            spacedUpdate.scheduleUpdate();
            const secondSave = spacedUpdate.updateNowIfNecessary();
            // The editor goes away right after asking, as an unmounted one does.
            editor.content = "gone";

            // Unsaved until the commit that holds the change lands.
            expect(spacedUpdate.hasUnsavedChanges()).toBe(true);
            finishFirstCommit();
            await firstSave;
            await secondSave;
            expect(commits).toEqual([ "first", "second" ]);
            expect(spacedUpdate.hasUnsavedChanges()).toBe(false);
        });

        it("retries a failed commit with the frozen snapshot, not the live state", async () => {
            const editor = { content: "typed into A" };
            const commits: string[] = [];
            let failuresLeft = 1;
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => editor.content,
                commit: async (data) => {
                    if (failuresLeft > 0) {
                        failuresLeft--;
                        throw new Error("offline");
                    }
                    commits.push(data);
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            await vi.advanceTimersByTimeAsync(60); // first attempt fails

            // The live state moves on (e.g. another note's content is loaded into the editor),
            // but the retry must persist the snapshot taken when the change was flushed.
            editor.content = "now showing B";
            await vi.advanceTimersByTimeAsync(200); // backoff retry fires

            expect(commits).toEqual(["typed into A"]);
        });

        it("supersedes a queued failed snapshot with a newer one for the same key", async () => {
            const editor = { content: "v1" };
            const commits: string[] = [];
            let failuresLeft = 1;
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => editor.content,
                commit: async (data) => {
                    if (failuresLeft > 0) {
                        failuresLeft--;
                        throw new Error("offline");
                    }
                    commits.push(data);
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            await vi.advanceTimersByTimeAsync(60); // "v1" fails and stays queued

            editor.content = "v2";
            spacedUpdate.scheduleUpdate();
            await vi.advanceTimersByTimeAsync(300);

            // The newer snapshot replaced the queued one: a single save with the latest data,
            // not a stale "v1" overwriting "v2".
            expect(commits).toEqual(["v2"]);
        });

        it("does not report all-saved while an asynchronous snapshot from rebind is still being captured", async () => {
            let resolvePrepare: (value: string) => void = () => {};
            const commits: { key: string; data: string }[] = [];
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => new Promise<string>((resolve) => {
                    resolvePrepare = resolve;
                }),
                commit: async (data) => {
                    commits.push({ key: "A", data });
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            spacedUpdate.rebind("B", () => "B content", async (data) => {
                commits.push({ key: "B", data });
            });

            // The old binding's snapshot is still being captured, so nothing may be
            // reported as saved yet (relevant for the beforeunload warning).
            expect(spacedUpdate.isAllSavedAndTriggerUpdate()).toBe(false);

            resolvePrepare("typed into A");
            await spacedUpdate.updateNowIfNecessary();

            expect(commits).toEqual([{ key: "A", data: "typed into A" }]);
        });

        it("schedules a retry when an asynchronous snapshot rejects, so the change is not stranded", async () => {
            let rejectPrepare: (e: Error) => void = () => {};
            const commits: { key: string; data: string }[] = [];
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => new Promise<string>((_, reject) => {
                    rejectPrepare = reject;
                }),
                commit: async (data) => {
                    commits.push({ key: "A", data });
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            spacedUpdate.rebind("B", () => "B content", async (data) => {
                commits.push({ key: "B", data });
            });

            // The debounce timer fires while the snapshot is still being captured and goes idle.
            await vi.advanceTimersByTimeAsync(60);
            expect(commits).toEqual([]);

            // The capture fails: the restored change must be retried (under the current
            // binding), not stranded until the next keystroke.
            rejectPrepare(new Error("editor crashed"));
            await vi.advanceTimersByTimeAsync(100);

            expect(commits).toEqual([{ key: "B", data: "B content" }]);
        });

        it("keeps growing the retry backoff while a commit keeps failing, even if a sibling key succeeds", async () => {
            const failingAttempts: number[] = [];
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => "A content",
                commit: async () => {
                    failingAttempts.push(Date.now());
                    throw new Error("offline");
                }
            }, 50);

            // First attempt fails at ~50ms and schedules a retry.
            spacedUpdate.scheduleUpdate();
            await vi.advanceTimersByTimeAsync(60);
            expect(failingAttempts).toHaveLength(1);

            // A change for another note succeeds within the same retry pass.
            spacedUpdate.rebind("B", () => "B content", async () => {});
            spacedUpdate.scheduleUpdate();

            await vi.advanceTimersByTimeAsync(1000);

            // The sibling success must not reset the failing key's backoff: the gaps
            // between consecutive failing attempts keep doubling.
            expect(failingAttempts.length).toBeGreaterThanOrEqual(3);
            const gaps = failingAttempts.slice(1).map((t, i) => t - failingAttempts[i]);
            for (let i = 1; i < gaps.length; i++) {
                expect(gaps[i]).toBeGreaterThan(gaps[i - 1]);
            }
        });

        it("supports an asynchronous prepare", async () => {
            const commits: string[] = [];
            const spacedUpdate = new SpacedUpdate<string>({
                key: "A",
                prepare: () => Promise.resolve("async snapshot"),
                commit: async (data) => {
                    commits.push(data);
                }
            }, 50);

            spacedUpdate.scheduleUpdate();
            await spacedUpdate.updateNowIfNecessary();

            expect(commits).toEqual(["async snapshot"]);
        });
    });

    describe("allowUpdateWithoutChange", () => {
        it("suppresses scheduleUpdate while the callback runs and re-enables it afterwards", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            await spacedUpdate.allowUpdateWithoutChange(async () => {
                // scheduleUpdate is a no-op while change is forbidden.
                spacedUpdate.scheduleUpdate();
            });

            await vi.runAllTimersAsync();
            expect(updater).not.toHaveBeenCalled();

            // After the callback, scheduling works again.
            spacedUpdate.scheduleUpdate();
            await vi.runAllTimersAsync();
            expect(updater).toHaveBeenCalledTimes(1);
        });

        it("re-enables scheduling even when the callback throws", async () => {
            const updater = vi.fn(async () => {});
            const spacedUpdate = new SpacedUpdate(updater, 50);

            await expect(
                spacedUpdate.allowUpdateWithoutChange(async () => {
                    throw new Error("callback failed");
                })
            ).rejects.toThrow("callback failed");

            // changeForbidden was reset in finally -> scheduling works.
            spacedUpdate.scheduleUpdate();
            await vi.runAllTimersAsync();
            expect(updater).toHaveBeenCalledTimes(1);
        });
    });
});