@lapis-notes/history 0.1.4 → 0.2.0

package/dist/repository/controllers/restore.js

@@ -0,0 +1,201 @@
+export class RestoreController {
+    #state = { open: false, busy: false };
+    #listeners = new Set();
+    #epoch = 0;
+    #closed = false;
+    service;
+    guard;
+    feedback;
+    persist;
+    constructor(service, guard, feedback, persist = async () => { }) {
+        this.service = service;
+        this.guard = guard;
+        this.feedback = feedback;
+        this.persist = persist;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return () => this.#listeners.delete(listener);
+    }
+    #set(patch) {
+        if (this.#closed)
+            return;
+        this.#state = { ...this.#state, ...patch };
+        for (const listener of this.#listeners)
+            listener(this.#state);
+    }
+    async prepare(checkpoint, path) {
+        if (this.#closed || this.#state.busy)
+            return;
+        const epoch = ++this.#epoch;
+        this.#set({
+            open: true,
+            busy: true,
+            preview: undefined,
+            request: undefined,
+            scope: "file",
+            recovery: false,
+            vault: undefined,
+            vaultRequest: undefined,
+        });
+        try {
+            const preview = await this.guard(path, () => this.service.preview(checkpoint, path));
+            if (epoch !== this.#epoch || this.#closed)
+                return;
+            if (preview.checkpoint !== checkpoint || preview.path !== path)
+                throw new Error("Restore preview does not match the selected version");
+            this.#set({
+                preview,
+                request: {
+                    request_id: crypto.randomUUID(),
+                    checkpoint,
+                    path,
+                    expected: preview.expected,
+                },
+            });
+            this.feedback.recovered();
+        }
+        catch (error) {
+            if (epoch === this.#epoch && !this.#closed) {
+                this.#set({ open: false });
+                this.feedback.report(error);
+            }
+        }
+        finally {
+            if (epoch === this.#epoch)
+                this.#set({ busy: false });
+        }
+    }
+    async prepareVault(checkpoint) {
+        if (this.#closed ||
+            this.#state.busy ||
+            !this.service.previewVault ||
+            !this.service.applyVault)
+            return;
+        const epoch = ++this.#epoch;
+        this.#set({
+            open: true,
+            busy: true,
+            scope: "vault",
+            recovery: false,
+            preview: undefined,
+            request: undefined,
+            vault: undefined,
+            vaultRequest: undefined,
+        });
+        try {
+            const vault = await this.guard(undefined, () => this.service.previewVault(checkpoint));
+            if (epoch !== this.#epoch || this.#closed)
+                return;
+            if (vault.checkpoint !== checkpoint)
+                throw new Error("Vault restore preview does not match the selected checkpoint");
+            this.#set({
+                vault,
+                vaultRequest: {
+                    request_id: crypto.randomUUID(),
+                    checkpoint,
+                    expected: vault.expected,
+                },
+            });
+            this.feedback.recovered();
+        }
+        catch (error) {
+            if (epoch === this.#epoch && !this.#closed) {
+                this.#set({ open: false });
+                this.feedback.report(error);
+            }
+        }
+        finally {
+            if (epoch === this.#epoch)
+                this.#set({ busy: false });
+        }
+    }
+    async apply() {
+        const request = this.#state.request;
+        const vaultRequest = this.#state.vaultRequest;
+        const action = vaultRequest && this.service.applyVault
+            ? () => this.service.applyVault(vaultRequest)
+            : request
+                ? () => this.service.apply(request)
+                : undefined;
+        if (!action || this.#closed || this.#state.busy)
+            return;
+        const epoch = this.#epoch;
+        this.#set({ busy: true });
+        try {
+            await this.persist(vaultRequest
+                ? { version: 1, scope: "vault", request: vaultRequest }
+                : { version: 1, scope: "file", request: request });
+            if (this.#closed || epoch !== this.#epoch)
+                return;
+            await this.guard(vaultRequest ? undefined : request.path, action);
+            await this.persist(undefined);
+            if (epoch === this.#epoch && !this.#closed) {
+                this.#set({ open: false });
+                this.feedback.recovered();
+            }
+        }
+        catch (error) {
+            if (epoch === this.#epoch && !this.#closed)
+                this.feedback.report(error);
+        }
+        finally {
+            if (epoch === this.#epoch)
+                this.#set({ busy: false });
+        }
+    }
+    recover(pending) {
+        if (this.#closed ||
+            this.#epoch !== 0 ||
+            this.#state.open ||
+            this.#state.busy)
+            return;
+        this.#set({
+            open: true,
+            busy: false,
+            recovery: true,
+            scope: pending.scope,
+            preview: undefined,
+            vault: undefined,
+            request: pending.scope === "file" ? pending.request : undefined,
+            vaultRequest: pending.scope === "vault" ? pending.request : undefined,
+        });
+    }
+    async keepCurrent() {
+        if (!this.#state.recovery ||
+            this.#state.busy ||
+            this.#closed ||
+            !this.service.keepCurrent)
+            return;
+        const epoch = this.#epoch;
+        this.#set({ busy: true });
+        try {
+            // A worker capture is also a barrier behind an unknown restore. Do not
+            // dismiss recovery while an older native command can still change files.
+            await this.guard(undefined, () => this.service.keepCurrent());
+            await this.persist(undefined);
+            if (!this.#closed && epoch === this.#epoch) {
+                this.#set({ open: false, recovery: false });
+                this.feedback.recovered();
+            }
+        }
+        catch (error) {
+            if (!this.#closed && epoch === this.#epoch)
+                this.feedback.report(error);
+        }
+        finally {
+            if (epoch === this.#epoch)
+                this.#set({ busy: false });
+        }
+    }
+    dismiss() {
+        if (!this.#state.busy)
+            this.#set({ open: false });
+    }
+    close() {
+        this.#closed = true;
+        this.#epoch++;
+        this.#listeners.clear();
+    }
+}

package/dist/repository/controllers/revision-comparison.d.ts

@@ -0,0 +1,20 @@
+import type { Handle } from "@lapismd/jj-history";
+import type { HistoryReader } from "./history-reader.js";
+import type { HistoryState } from "./history-state.js";
+type Scope = {
+    handle?: Handle;
+    state: HistoryState;
+    closed: boolean;
+};
+/** File replies are fenced independently from graph paging and metadata. */
+export declare class RevisionComparison {
+    #private;
+    readonly reader: HistoryReader;
+    readonly scope: () => Scope;
+    readonly publish: (patch: Partial<HistoryState>) => void;
+    constructor(reader: HistoryReader, scope: () => Scope, publish: (patch: Partial<HistoryState>) => void);
+    reset(): void;
+    paths(base: string, append: boolean): Promise<void>;
+    selectPath(path: string): Promise<void>;
+}
+export {};

package/dist/repository/controllers/revision-comparison.js

@@ -0,0 +1,89 @@
+import { check } from "./history-selection.js";
+/** File replies are fenced independently from graph paging and metadata. */
+export class RevisionComparison {
+    #comparison = 0;
+    #file = 0;
+    reader;
+    scope;
+    publish;
+    constructor(reader, scope, publish) {
+        this.reader = reader;
+        this.scope = scope;
+        this.publish = publish;
+    }
+    reset() {
+        this.#comparison++;
+        this.#file++;
+    }
+    async paths(base, append) {
+        const comparison = append ? this.#comparison : ++this.#comparison;
+        const handle = this.scope().handle, revision = this.scope().state.revision;
+        if (!handle || !revision)
+            return;
+        if (!append)
+            this.publish({
+                base,
+                paths: [],
+                pathsReady: false,
+                nextPath: null,
+                path: undefined,
+                diff: undefined,
+            });
+        const response = await this.reader.read(handle, {
+            kind: "diff_paths",
+            query: {
+                from: base,
+                to: revision.id,
+                path: "",
+                limit: 100,
+                anchor: append ? this.scope().state.nextPath : null,
+                direction: "forward",
+            },
+        });
+        if (comparison !== this.#comparison ||
+            handle !== this.scope().handle ||
+            revision.id !== this.scope().state.revision?.id ||
+            base !== this.scope().state.base ||
+            this.scope().closed)
+            return;
+        check(response.kind === "diff_paths" &&
+            response.data.from === base &&
+            response.data.to === revision.id);
+        const paths = [
+            ...(append ? this.scope().state.paths : []),
+            ...response.data.changes,
+        ].slice(0, 500);
+        this.publish({
+            paths,
+            nextPath: paths.length < 500 ? response.data.next : null,
+            pathsReady: true,
+        });
+    }
+    async selectPath(path) {
+        const comparison = this.#comparison, file = ++this.#file;
+        const handle = this.scope().handle, revision = this.scope().state.revision, base = this.scope().state.base;
+        if (!handle || !revision || !base)
+            return;
+        check(this.scope().state.paths.some((change) => change.path === path));
+        this.publish({ path, diff: undefined });
+        const response = await this.reader.read(handle, {
+            kind: "diff",
+            query: { from: base, to: revision.id, path, content: true },
+        });
+        if (comparison !== this.#comparison ||
+            file !== this.#file ||
+            handle !== this.scope().handle ||
+            revision.id !== this.scope().state.revision?.id ||
+            base !== this.scope().state.base ||
+            path !== this.scope().state.path ||
+            this.scope().closed)
+            return;
+        check(response.kind === "diff" &&
+            response.data.from === base &&
+            response.data.to === revision.id &&
+            response.data.path === path);
+        const change = response.data.changes.find((change) => change.path === path);
+        check(change);
+        this.publish({ diff: change });
+    }
+}

package/dist/repository/controllers/search-controller.d.ts

@@ -0,0 +1,19 @@
+import { type HistorySearchState, type HistorySearchService, type HistorySearchQuery } from "./search.js";
+/** Owns page lifetime and fixed-anchor continuation, separately from UI input. */
+export declare class HistorySearchController {
+    #private;
+    readonly service: HistorySearchService;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    constructor(service: HistorySearchService, feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    });
+    subscribe(listener: (state: HistorySearchState) => void): () => boolean;
+    search(query: HistorySearchQuery): Promise<void>;
+    more(): Promise<void>;
+    close(): void;
+    drained(): Promise<void>;
+}

package/dist/repository/controllers/search-controller.js

@@ -0,0 +1,105 @@
+import { initialSearchState, } from "./search.js";
+/** Owns page lifetime and fixed-anchor continuation, separately from UI input. */
+export class HistorySearchController {
+    service;
+    feedback;
+    #state = initialSearchState();
+    #listeners = new Set();
+    #epoch = 0;
+    #closed = false;
+    #query = { text: "" };
+    #tail = Promise.resolve();
+    constructor(service, feedback) {
+        this.service = service;
+        this.feedback = feedback;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return () => this.#listeners.delete(listener);
+    }
+    #set(patch) {
+        if (this.#closed)
+            return;
+        this.#state = { ...this.#state, ...patch };
+        for (const listener of this.#listeners)
+            listener(this.#state);
+    }
+    search(query) {
+        if (this.#closed)
+            return Promise.resolve();
+        this.#query = { ...query };
+        this.#set(initialSearchState());
+        return this.#run(false);
+    }
+    more() {
+        if (this.#closed || this.#state.busy || !this.#state.next)
+            return Promise.resolve();
+        return this.#run(true);
+    }
+    #run(append) {
+        const epoch = ++this.#epoch, query = { ...this.#query };
+        const previous = this.#tail;
+        this.#set({ busy: true, phase: "searching" });
+        const job = (async () => {
+            // An obsolete native page still drains. Avoid overlapping the one worker.
+            await previous;
+            if (this.#closed || epoch !== this.#epoch)
+                return;
+            let cursor = append ? this.#state.next : undefined;
+            let hits = append ? this.#state.hits : [];
+            let unindexed = append ? this.#state.unindexed : 0;
+            const before = hits.length;
+            const seen = new Set(hits.map(key));
+            try {
+                const cursors = new Set();
+                for (let n = 0; n < 32; n++) {
+                    const page = await this.service.page({ query, cursor });
+                    if (this.#closed || epoch !== this.#epoch)
+                        return;
+                    for (const hit of page.hits) {
+                        const identity = key(hit);
+                        if (!seen.has(identity)) {
+                            seen.add(identity);
+                            hits = [...hits, hit];
+                        }
+                    }
+                    unindexed += page.unindexed;
+                    this.#set({
+                        hits,
+                        unindexed,
+                        next: page.next,
+                        checkpoints: page.checkpoints,
+                        searched: true,
+                    });
+                    cursor = page.next;
+                    if (!cursor || hits.length >= before + 100)
+                        break;
+                    const identity = JSON.stringify(cursor);
+                    if (cursors.has(identity))
+                        throw new Error("History search returned a repeated cursor");
+                    cursors.add(identity);
+                }
+                this.feedback.recovered();
+            }
+            catch (error) {
+                if (!this.#closed && epoch === this.#epoch)
+                    this.feedback.report(error);
+            }
+            finally {
+                if (epoch === this.#epoch)
+                    this.#set({ busy: false, phase: "ready" });
+            }
+        })();
+        return (this.#tail = job);
+    }
+    close() {
+        this.#closed = true;
+        this.#epoch++;
+        this.#listeners.clear();
+    }
+    async drained() {
+        await this.#tail;
+    }
+}
+const key = (hit) => `${hit.revision.checkpoint.commit}/${hit.path ?? ""}`;

package/dist/repository/controllers/search-page.d.ts

@@ -0,0 +1,2 @@
+import type { HistorySearchPage } from "./search.js";
+export declare function searchPage(value: unknown): HistorySearchPage;

package/dist/repository/controllers/search-page.js

@@ -0,0 +1,39 @@
+const object = (value) => !!value && typeof value === "object";
+const id = (value, length) => typeof value === "string" && new RegExp(`^[0-9a-f]{${length}}$`).test(value);
+export function searchPage(value) {
+    if (!object(value) ||
+        !Array.isArray(value.hits) ||
+        value.hits.length > 9 ||
+        !Number.isSafeInteger(value.checkpoints) ||
+        !Number.isSafeInteger(value.unindexed))
+        throw new Error("Invalid history search response");
+    for (const hit of value.hits) {
+        const revision = object(hit) && hit.revision;
+        const checkpoint = object(revision) && revision.checkpoint;
+        if (!object(hit) ||
+            !object(revision) ||
+            !object(checkpoint) ||
+            !id(checkpoint.commit, 40) ||
+            !id(checkpoint.operation, 128) ||
+            !id(checkpoint.change_id, 32) ||
+            typeof checkpoint.description !== "string" ||
+            !Number.isSafeInteger(checkpoint.timestamp_millis) ||
+            typeof revision.author !== "string" ||
+            typeof revision.email !== "string" ||
+            typeof hit.excerpt !== "string" ||
+            (hit.path != null &&
+                (typeof hit.path !== "string" ||
+                    hit.path
+                        .split("/")
+                        .some((p) => ["", ".", "..", ".jj", ".git", ".lapis"].includes(p)))))
+            throw new Error("Invalid history search hit");
+    }
+    if (value.next != null &&
+        (!object(value.next) ||
+            !id(value.next.anchor, 40) ||
+            !Number.isSafeInteger(value.next.revision) ||
+            (value.next.after_path != null &&
+                typeof value.next.after_path !== "string")))
+        throw new Error("Invalid history search cursor");
+    return value;
+}

package/dist/repository/controllers/search.d.ts

@@ -0,0 +1,51 @@
+export type HistorySearchQuery = {
+    text: string;
+    path?: string;
+    author?: string;
+    from_millis?: number;
+    to_millis?: number;
+};
+export type HistorySearchCursor = {
+    anchor: string;
+    revision: number;
+    after_path?: string | null;
+};
+export type HistorySearchHit = {
+    revision: {
+        checkpoint: {
+            operation: string;
+            commit: string;
+            change_id: string;
+            description: string;
+            timestamp_millis: number;
+        };
+        author: string;
+        email: string;
+    };
+    path?: string | null;
+    line?: number | null;
+    excerpt: string;
+};
+export type HistorySearchPage = {
+    hits: HistorySearchHit[];
+    next?: HistorySearchCursor | null;
+    checkpoints: number;
+    unindexed: number;
+};
+export interface HistorySearchService {
+    indexed?: import("./indexed-search.js").IndexedHistoryService;
+    page(request: {
+        query: HistorySearchQuery;
+        cursor?: HistorySearchCursor | null;
+    }): Promise<HistorySearchPage>;
+}
+export type HistorySearchState = {
+    busy: boolean;
+    phase: "ready" | "searching";
+    searched: boolean;
+    hits: HistorySearchHit[];
+    next?: HistorySearchCursor | null;
+    checkpoints: number;
+    unindexed: number;
+};
+export declare const initialSearchState: () => HistorySearchState;

package/dist/repository/controllers/search.js

@@ -0,0 +1,8 @@
+export const initialSearchState = () => ({
+    busy: false,
+    phase: "ready",
+    searched: false,
+    hits: [],
+    checkpoints: 0,
+    unindexed: 0,
+});

package/dist/repository/controllers/services.d.ts

@@ -0,0 +1,7 @@
+import type { App } from "@lapis-notes/api";
+import type { RepositoryServices, RepositoryLeaveMode } from "./history-reader.js";
+export type RepositoryFactory = (app: App) => RepositoryServices;
+export declare function bindRepository(app: App, factory: RepositoryFactory): () => void;
+export declare function ownedRepository(app: App): RepositoryServices;
+export declare function prepareRepositoryLeave(app: App, mode: RepositoryLeaveMode): void;
+export declare function repositoryLeaveMode(app: App): RepositoryLeaveMode;

package/dist/repository/controllers/services.js

@@ -0,0 +1,24 @@
+const bindings = new WeakMap();
+const leaveModes = new WeakMap();
+export function bindRepository(app, factory) {
+    if (bindings.has(app))
+        throw new Error("Repository history is already bound");
+    const lease = { factory };
+    bindings.set(app, lease);
+    return () => {
+        if (bindings.get(app) === lease)
+            bindings.delete(app);
+    };
+}
+export function ownedRepository(app) {
+    const lease = bindings.get(app);
+    if (!lease)
+        throw new Error("Repository history is unavailable in this host");
+    return lease.factory(app);
+}
+export function prepareRepositoryLeave(app, mode) {
+    leaveModes.set(app, mode);
+}
+export function repositoryLeaveMode(app) {
+    return leaveModes.get(app) ?? "close";
+}

package/dist/repository/controllers/storage-controller.d.ts

@@ -0,0 +1,30 @@
+import type { StorageLocation, StorageService, StorageState } from "./storage.js";
+type Guard = <T>(action: () => Promise<T>) => Promise<T | undefined>;
+/** An advanced move is explicit and retains native recovery until reload. */
+export declare class StorageController {
+    #private;
+    readonly service: StorageService;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    readonly guard: Guard;
+    constructor(service: StorageService, feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    }, guard?: Guard);
+    subscribe(listener: (state: StorageState) => void): () => boolean;
+    subscribeActivity(listener: (state: {
+        busy: boolean;
+        phase: string;
+    }) => void): () => boolean;
+    refresh(): Promise<boolean>;
+    reveal(): Promise<boolean>;
+    change(location: StorageLocation): Promise<boolean>;
+    recover(): Promise<boolean>;
+    rollback(): Promise<boolean>;
+    reload(): Promise<boolean>;
+    close(): void;
+    drained(): Promise<void>;
+}
+export {};