Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import type { TaskData, TaskResult } from "@triliumnext/commons";
import { afterEach, beforeEach, describe, expect, it, type MockInstance, vi } from "vitest";
import TaskContext from "./task_context.js";
import ws from "./ws.js";
// task_context's only runtime side effect is ws.sendMessageToAllClients, which we
// spy on so we can assert the WebSocket messages it emits without a real server.
let sendMessageToAllClients: MockInstance;
const importData: TaskData<"importNotes"> = { safeImport: true };
const importResult: TaskResult<"importNotes"> = { importedNoteId: "abc123" };
describe("TaskContext", () => {
beforeEach(() => {
sendMessageToAllClients = vi
.spyOn(ws, "sendMessageToAllClients")
.mockImplementation(() => {});
});
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
});
describe("construction", () => {
it("emits an initial progress message on creation with the task metadata", () => {
new TaskContext("ctor-1", "importNotes", importData);
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
expect(sendMessageToAllClients).toHaveBeenCalledWith({
type: "taskProgressCount",
taskId: "ctor-1",
taskType: "importNotes",
data: importData,
// progressCount starts at -1 and is incremented immediately on construction.
progressCount: 0
});
});
it("exposes the provided data and a default noteDeletionHandlerTriggered flag", () => {
const ctx = new TaskContext("ctor-2", "importNotes", importData);
expect(ctx.data).toBe(importData);
expect(ctx.noteDeletionHandlerTriggered).toBe(false);
});
it("does not emit any message for the reserved no-progress-reporting task id", () => {
new TaskContext("no-progress-reporting", "importNotes", importData);
expect(sendMessageToAllClients).not.toHaveBeenCalled();
});
});
describe("increaseProgressCount", () => {
it("throttles progress messages to at most once per 300ms window", () => {
vi.useFakeTimers();
// lastSentCountTs starts at 0, so the constructor's first send only fires
// when the clock is already >= 300ms past the epoch (always true with the
// real wall clock); anchor the fake clock past that boundary to match.
vi.setSystemTime(1_000);
// Construction sends the first message (progressCount 0).
const ctx = new TaskContext("throttle-1", "importNotes", importData);
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
// Still inside the 300ms window since the last send: increments are coalesced.
vi.setSystemTime(1_100);
ctx.increaseProgressCount();
vi.setSystemTime(1_299);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
// Crossing the window boundary flushes a message carrying the accumulated count.
vi.setSystemTime(1_300);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenCalledTimes(2);
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(
expect.objectContaining({
type: "taskProgressCount",
taskId: "throttle-1",
// 0 (ctor) + 3 increments = 3.
progressCount: 3
})
);
});
it("never sends progress messages for the reserved no-progress-reporting id", () => {
vi.useFakeTimers();
vi.setSystemTime(0);
const ctx = new TaskContext("no-progress-reporting", "importNotes", importData);
vi.setSystemTime(10_000);
ctx.increaseProgressCount();
ctx.increaseProgressCount();
expect(sendMessageToAllClients).not.toHaveBeenCalled();
});
it("includes the total once set, and omits it until then", () => {
vi.useFakeTimers();
vi.setSystemTime(1_000);
const ctx = new TaskContext("total-1", "importNotes", importData);
// The constructor's first message has no total yet.
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.not.objectContaining({ totalCount: expect.anything() }));
ctx.setTotalCount(10);
vi.setSystemTime(1_300);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.objectContaining({ progressCount: 1, totalCount: 10 }));
});
});
describe("setPhase", () => {
it("tags subsequent progress messages with the phase and flushes the next one immediately", () => {
vi.useFakeTimers();
vi.setSystemTime(1_000);
const ctx = new TaskContext("phase-1", "importNotes", importData);
// The constructor's first message carries no phase.
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.not.objectContaining({ phase: expect.anything() }));
// setPhase resets the throttle, so the very next increment sends even within the 300ms window.
ctx.setPhase("extracting");
vi.setSystemTime(1_100);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.objectContaining({ phase: "extracting" }));
ctx.setPhase("processing");
vi.setSystemTime(1_200);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.objectContaining({ phase: "processing" }));
});
});
describe("reportPhase and clearPhase", () => {
it("pushes the phase immediately and drops it from the next flushed count", () => {
vi.useFakeTimers();
vi.setSystemTime(1_000);
const ctx = new TaskContext("phase-2", "importNotes", importData);
ctx.setTotalCount(10);
sendMessageToAllClients.mockClear();
// reportPhase must not wait for the next unit of work — its whole point is signalling a
// stall (e.g. Graph throttling) while no counts are flowing, so it sends even inside the
// 300ms coalescing window and without an increment.
vi.setSystemTime(1_100);
ctx.reportPhase("throttled");
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.objectContaining({ phase: "throttled", progressCount: 0, totalCount: 10 }));
// clearPhase alone sends nothing, but forces the next increment out immediately (still
// inside the window) — one message carrying the corrected label and count together.
vi.setSystemTime(1_200);
ctx.clearPhase();
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenCalledTimes(2);
expect(sendMessageToAllClients).toHaveBeenLastCalledWith(expect.not.objectContaining({ phase: expect.anything() }));
// With no phase set, clearPhase is inert — it must not defeat the coalescing window.
ctx.clearPhase();
vi.setSystemTime(1_300);
ctx.increaseProgressCount();
expect(sendMessageToAllClients).toHaveBeenCalledTimes(2);
});
it("stays silent for the reserved no-progress-reporting id", () => {
const ctx = new TaskContext("no-progress-reporting", "importNotes", importData);
ctx.reportPhase("throttled");
expect(sendMessageToAllClients).not.toHaveBeenCalled();
});
});
describe("reportError", () => {
it("broadcasts a taskError message with the failure text and task metadata", () => {
const ctx = new TaskContext("err-1", "importNotes", importData);
sendMessageToAllClients.mockClear();
ctx.reportError("something broke");
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
expect(sendMessageToAllClients).toHaveBeenCalledWith({
type: "taskError",
taskId: "err-1",
taskType: "importNotes",
data: importData,
message: "something broke"
});
});
});
describe("taskSucceeded", () => {
it("broadcasts a taskSucceeded message carrying the result payload", () => {
const ctx = new TaskContext("ok-1", "importNotes", importData);
sendMessageToAllClients.mockClear();
ctx.taskSucceeded(importResult);
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
expect(sendMessageToAllClients).toHaveBeenCalledWith({
type: "taskSucceeded",
taskId: "ok-1",
taskType: "importNotes",
data: importData,
result: importResult
});
});
});
describe("scheduled erases", () => {
it("accumulates deleteIds across a task group and hands them over exactly once", () => {
const context = TaskContext.getInstance("erase-batch-1", "deleteNotes", null);
expect(context.takeScheduledErases()).toEqual([]);
context.scheduleErase("del-1");
context.scheduleErase("del-2");
expect(context.takeScheduledErases()).toEqual([ "del-1", "del-2" ]);
// Taking them clears the list, so a later request of the same group re-erases nothing.
expect(context.takeScheduledErases()).toEqual([]);
});
});
describe("getInstance", () => {
it("creates a single cached context per task id and reuses it on later lookups", () => {
const first = TaskContext.getInstance("singleton-1", "importNotes", { safeImport: true });
// Creating the instance emits its initial progress message.
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
// A second lookup with the same id returns the cached instance without
// constructing a new one (no additional initial-progress message), and
// the originally cached data is preserved (the new data arg is ignored).
const second = TaskContext.getInstance("singleton-1", "importNotes", { safeImport: false });
expect(second).toBe(first);
expect(second.data).toEqual({ safeImport: true });
expect(sendMessageToAllClients).toHaveBeenCalledTimes(1);
// A different id yields a distinct instance with its own initial message.
const other = TaskContext.getInstance("singleton-2", "importNotes", { safeImport: true });
expect(other).not.toBe(first);
expect(sendMessageToAllClients).toHaveBeenCalledTimes(2);
});
});
});