@lapis-notes/api 0.1.3 → 0.2.0

package/dist/file-manager.js

@@ -3,6 +3,7 @@ import { TFile } from "./storage/fs";
 import { joinPath } from "./storage/path";
 import { defaultLinkSettings, generateInternalLink, } from "./links";
 import { parseLinktext } from "./utils";
+import { mutateFileText, } from "./file-text-mutation";
 const FRONTMATTER_RETRY_ERROR = "__lapis_frontmatter_retry__";
 function linkOffsets(position) {
     if (!position || typeof position !== "object")
@@ -28,7 +29,9 @@ export class FileManager {
         return JSON.parse(JSON.stringify(frontmatter));
     }
     async readFrontmatterSeed(file, content) {
-        const cachedFrontmatter = (await this.app.metadataCache.getFileCacheAsync(file))?.frontmatter;
+        const cachedFrontmatter = content !== undefined && this.app.vault.supportsConditionalTextWrites
+            ? undefined
+            : (await this.app.metadataCache.getFileCacheAsync(file))?.frontmatter;
         if (cachedFrontmatter && typeof cachedFrontmatter === "object") {
             return this.cloneFrontmatter(cachedFrontmatter);
         }
@@ -151,6 +154,18 @@ export class FileManager {
     getNewFileParent(sourcePath, newFilePath) {
         return this.app.vault.getRoot();
     }
+    /** New-file intent; exclusive-capable hosts never fall back to overwrite. */
+    createFile(path, data, options) {
+        return this.app.fileEditingSessions.track(async () => {
+            await this.app.vault.load();
+            if (this.app.vault.adapter.getCapabilities?.()
+                .exclusiveCreate === true)
+                return this.app.vault.createExclusive(path, data, options);
+            return typeof data === "string"
+                ? this.app.vault.create(path, data, options)
+                : this.app.vault.createBinary(path, data, options);
+        });
+    }
     getAvailablePathForAttachment(filename, sourcePath) {
         const parent = this.getNewFileParent(sourcePath ?? "", filename);
         const extMatch = /(\.[^.]*)$/.exec(filename);
@@ -173,6 +188,14 @@ export class FileManager {
      * @public
      */
     async renameFile(file, newPath) {
+        const capturedPath = file.path;
+        await this.app.fileEditingSessions.guard(undefined, async () => {
+            if (file.path !== capturedPath)
+                throw new Error("Rename target changed during editor admission");
+            await this.renameProtectedFile(file, newPath);
+        });
+    }
+    async renameProtectedFile(file, newPath) {
         if (!(file instanceof TFile)) {
             return this.app.vault.rename(file, newPath);
         }
@@ -202,8 +225,13 @@ export class FileManager {
      * @param file
      * @public
      */
-    trashFile(file) {
-        return this.app.vault.trash(file, true);
+    async trashFile(file) {
+        const capturedPath = file.path;
+        await this.app.fileEditingSessions.guard(undefined, async () => {
+            if (file.path !== capturedPath)
+                throw new Error("Trash target changed during editor admission");
+            await this.app.vault.trash(file, true);
+        });
     }
     promptForDeletion(file) {
         return this.trashFile(file);
@@ -260,6 +288,20 @@ export class FileManager {
      * @public
      */
     processFrontMatter(file, fn, options) {
+        if (this.app.vault.supportsConditionalTextWrites) {
+            let matches = true;
+            return mutateFileText(this.app, file, async (snapshot) => {
+                const seed = await this.readFrontmatterSeed(file, snapshot);
+                matches =
+                    options?.expectedFrontmatter === undefined ||
+                        this.isFrontmatterEqual(seed, options.expectedFrontmatter);
+                const next = this.cloneFrontmatter(seed);
+                fn(next);
+                return this.isFrontmatterEqual(seed, next)
+                    ? snapshot
+                    : this.writeUpdatedFrontmatter(file, snapshot, next);
+            }, { ...options, validateBaseline: () => matches });
+        }
         const attempt = async () => {
             const snapshot = await this.app.vault.read(file);
             const seedFrontmatter = await this.readFrontmatterSeed(file, snapshot);

package/dist/file-state-store.d.ts

@@ -0,0 +1,5 @@
+import type { App } from "./context.svelte";
+/** Capture the acknowledged state while the owner loads, before edits begin. */
+export declare function readFileState(app: App, path: string, reset?: (text: string) => void | Promise<void>): Promise<string | null>;
+/** Register synchronously so shutdown cannot overtake initial read or write IO. */
+export declare function saveFileState(app: App, path: string, text: string): Promise<void>;

package/dist/file-state-store.js

@@ -0,0 +1,34 @@
+import { FileTextStateWriter } from "./file-text-state-writer";
+import { TFile } from "./storage/fs";
+import { normalizePath } from "./storage/path";
+const stores = new WeakMap();
+function writer(app, path, baseline, reset = () => { }) {
+    path = normalizePath(path).replace(/^\/+/, "");
+    let store = stores.get(app);
+    if (!store)
+        stores.set(app, (store = new Map()));
+    let entry = store.get(path);
+    if (!entry) {
+        const file = app.vault.getFileByPath(path) ??
+            new TFile(path, { ctime: 0, mtime: 0, size: 0 }, null);
+        entry = new FileTextStateWriter(app, file, baseline, reset, {
+            recoverOutsideQueue: true,
+        });
+        store.set(path, entry);
+    }
+    return entry;
+}
+/** Capture the acknowledged state while the owner loads, before edits begin. */
+export async function readFileState(app, path, reset) {
+    const state = app.vault.supportsConditionalTextWrites
+        ? writer(app, path, undefined, reset)
+        : undefined;
+    const adapter = app.vault.adapter;
+    const text = (await adapter.exists(path)) ? await adapter.read(path) : null;
+    state?.acceptBaseline(text);
+    return text;
+}
+/** Register synchronously so shutdown cannot overtake initial read or write IO. */
+export function saveFileState(app, path, text) {
+    return writer(app, path).set(text);
+}

package/dist/file-text-conflicts.d.ts

@@ -0,0 +1,25 @@
+export type FileTextResolution = "keep-local" | "use-external";
+/** A captured recovery decision; stale objects cannot resolve newer conflicts. */
+export interface FileTextConflict {
+    readonly id: string;
+    readonly path: string;
+    readonly baseline: string | null;
+    readonly local: string;
+    /** Undefined means the authoritative disk read failed; null means deletion. */
+    readonly external: string | null | undefined;
+    readonly readError?: string;
+    resolve(choice: FileTextResolution): Promise<void>;
+    /** Persist reviewed merge text against this exact disk snapshot. */
+    resolveMerged(contents: string): Promise<void>;
+    refresh(): Promise<void>;
+}
+/** App-owned text recovery, independent of the lifetime of individual views. */
+export declare class FileTextConflictRegistry {
+    #private;
+    get entries(): readonly FileTextConflict[];
+    subscribe(listener: (entries: readonly FileTextConflict[]) => void): () => void;
+    /** @internal Writer-owned publication; hosts consume entries and their actions. */
+    publish(conflict: FileTextConflict): void;
+    /** @internal Release only after persistence or an explicit discard succeeds. */
+    clear(id: string): void;
+}

package/dist/file-text-conflicts.js

@@ -0,0 +1,35 @@
+/** App-owned text recovery, independent of the lifetime of individual views. */
+export class FileTextConflictRegistry {
+    #entries = new Map();
+    #listeners = new Set();
+    get entries() {
+        return [...this.#entries.values()];
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.entries);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** @internal Writer-owned publication; hosts consume entries and their actions. */
+    publish(conflict) {
+        this.#entries.set(conflict.id, Object.freeze(conflict));
+        this.#notify();
+    }
+    /** @internal Release only after persistence or an explicit discard succeeds. */
+    clear(id) {
+        if (this.#entries.delete(id))
+            this.#notify();
+    }
+    #notify() {
+        for (const listener of this.#listeners) {
+            try {
+                listener(this.entries);
+            }
+            catch (error) {
+                console.error("Text conflict subscriber failed", error);
+            }
+        }
+    }
+}

package/dist/file-text-mutation.d.ts

@@ -0,0 +1,13 @@
+import type { App } from "./context.svelte";
+import type { TFile, DataWriteOptions } from "./storage/fs";
+export type FileTextMutationOptions = DataWriteOptions & {
+    /**
+     * A presentation-owned snapshot; omit to transform the authoritative latest
+     * text.
+     */
+    expectedText?: string | null;
+    onSaved?(text: string): void;
+    onReset?(text: string, expected: string | null): void;
+    validateBaseline?(): boolean;
+};
+export declare function mutateFileText(app: App, file: TFile, transform: (text: string) => Promise<string>, options?: FileTextMutationOptions): Promise<void>;

package/dist/file-text-mutation.js

@@ -0,0 +1,100 @@
+import { FileTextPersistence } from "./file-text-persistence";
+/** A retained one-shot draft; it has no view, timer or independent save path. */
+class TextMutation {
+    app;
+    file;
+    transform;
+    options;
+    #dirty = true;
+    #path;
+    #draft = "";
+    #persistence;
+    constructor(app, file, transform, options) {
+        this.app = app;
+        this.file = file;
+        this.transform = transform;
+        this.options = options;
+        this.#path = file.path;
+    }
+    get dirty() {
+        return this.#dirty || !!this.#persistence?.hasConflict;
+    }
+    native = {
+        hold: () => () => { },
+        savedText: () => this.#persistence?.baseline,
+    };
+    async flush() {
+        if (!this.dirty)
+            return;
+        if (this.file.path !== this.#path)
+            throw new Error("File mutation target changed");
+        if (!this.#persistence) {
+            const expected = this.options.expectedText;
+            // Keep the admitted transform if initial IO fails before a draft exists.
+            const baseline = expected === undefined
+                ? await this.app.vault.read(this.file)
+                : expected;
+            try {
+                this.#draft = await this.transform(baseline ?? "");
+                if (this.file.path !== this.#path)
+                    throw new Error("File mutation target changed");
+                if (this.#draft === baseline) {
+                    this.#dirty = false;
+                    return;
+                }
+                this.#persistence = new FileTextPersistence({
+                    vault: {
+                        read: (file) => this.app.vault.read(file),
+                        modifyIfUnchanged: (file, value, expected) => this.app.vault.modifyIfUnchanged(file, value, expected, this.options),
+                    },
+                    file: this.file,
+                    baseline,
+                    conflicts: this.app.fileEditingSessions.textConflicts,
+                    local: () => this.#draft,
+                    protect: () => ({
+                        release() { },
+                        saved: () => this.#saved(),
+                        reset: (text) => this.options.onReset?.(text, this.#persistence.baseline),
+                        resetSaved: (text) => {
+                            this.#draft = text;
+                            this.#dirty = false;
+                        },
+                    }),
+                    serialize: (run) => this.app.fileEditingSessions.recover(this, run),
+                });
+            }
+            catch (error) {
+                // Rejected transforms are invalid actions, rather than failed save drafts.
+                this.#dirty = false;
+                throw error;
+            }
+        }
+        if (this.options.validateBaseline?.() === false)
+            await this.#persistence.rejectPersistence();
+        try {
+            await this.#persistence.persist(this.#draft);
+        }
+        catch (error) {
+            if (!this.#persistence.hasConflict)
+                await this.#persistence.rejectPersistence(error);
+            throw error;
+        }
+        this.#saved();
+    }
+    #saved() {
+        this.#dirty = false;
+        this.options.onSaved?.(this.#draft);
+    }
+    async protect() {
+        // No user edits enter this captured one-shot draft after admission.
+        return () => { };
+    }
+}
+export function mutateFileText(app, file, transform, options = {}) {
+    const path = file.path;
+    return app.fileEditingSessions.mutate(path, () => {
+        if (file.path !== path)
+            throw new Error("File mutation target changed");
+        return new TextMutation(app, file, transform, options);
+    });
+}

package/dist/file-text-persistence.d.ts

@@ -0,0 +1,36 @@
+import type { TFile } from "./storage/fs";
+import type { Vault } from "./storage/vault.svelte";
+import type { FileTextConflictRegistry } from "./file-text-conflicts";
+/** A single recovery operation owns its protected document acknowledgement. */
+export type FileTextRecoveryLease = {
+    release(): void;
+    saved(): void;
+    reset(contents: string): void | Promise<void>;
+    resetSaved?(contents: string): void;
+};
+export type FileTextPersistenceOptions = {
+    vault: Pick<Vault, "read" | "modifyIfUnchanged">;
+    file: TFile;
+    baseline: string | null;
+    conflicts: FileTextConflictRegistry;
+    local(): string;
+    /** Acquire editing protection synchronously, before asynchronous admission. */
+    protect(): FileTextRecoveryLease | Promise<FileTextRecoveryLease>;
+    settle?(): Promise<void>;
+    serialize(run: () => Promise<void>): Promise<void>;
+    /** State restoration may itself write other owned files; revalidate afterward. */
+    recoverOutsideQueue?: boolean;
+};
+/** A single captured document's baseline and explicit text-conflict recovery. */
+export declare class FileTextPersistence {
+    #private;
+    private readonly options;
+    constructor(options: FileTextPersistenceOptions);
+    get hasConflict(): boolean;
+    get baseline(): string | null;
+    acceptBaseline(contents: string | null): void;
+    updateLocal(contents: string): void;
+    /** Retain a computed draft and authoritative disk snapshot before rejecting. */
+    rejectPersistence(error?: unknown): Promise<never>;
+    persist(contents: string): Promise<void>;
+}

package/dist/file-text-persistence.js

@@ -0,0 +1,234 @@
+function hasCode(error, code) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+/** A single captured document's baseline and explicit text-conflict recovery. */
+export class FileTextPersistence {
+    options;
+    #id = crypto.randomUUID();
+    #path;
+    #error;
+    #baseline;
+    #conflict;
+    constructor(options) {
+        this.options = options;
+        this.#path = options.file.path;
+        this.#baseline = options.baseline;
+        this.#error = Object.assign(new Error(`File changed on disk: ${this.#path}`), { code: "ECONFLICT" });
+    }
+    get hasConflict() {
+        return !!this.#conflict;
+    }
+    get baseline() {
+        return this.#baseline;
+    }
+    acceptBaseline(contents) {
+        if (!this.#conflict)
+            this.#baseline = contents;
+    }
+    updateLocal(contents) {
+        if (this.#conflict && this.#conflict.local !== contents)
+            this.#publish(this.#conflict.external, this.#conflict.readError);
+    }
+    /** Retain a computed draft and authoritative disk snapshot before rejecting. */
+    async rejectPersistence(error = this.#error) {
+        this.#assertTarget();
+        await this.#captureExternal();
+        throw error;
+    }
+    async persist(contents) {
+        this.#assertTarget();
+        if (this.#conflict) {
+            this.updateLocal(this.options.local());
+            throw this.#error;
+        }
+        try {
+            await this.options.vault.modifyIfUnchanged(this.options.file, contents, this.#baseline);
+            this.#baseline = contents;
+        }
+        catch (error) {
+            if (hasCode(error, "ECONFLICT")) {
+                await this.#captureExternal();
+                throw this.#error;
+            }
+            throw error;
+        }
+    }
+    #assertTarget() {
+        if (this.options.file.path !== this.#path)
+            throw new Error("File text persistence target changed");
+    }
+    #assertCurrent(conflict) {
+        this.#assertTarget();
+        if (this.#conflict !== conflict)
+            throw new Error("Conflict changed; review the latest versions");
+    }
+    async #read() {
+        this.#assertTarget();
+        try {
+            return await this.options.vault.read(this.options.file);
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    }
+    async #captureExternal() {
+        try {
+            this.#publish(await this.#read());
+        }
+        catch (error) {
+            this.#publish(undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    #publish(external, readError) {
+        const conflict = {
+            id: this.#id,
+            path: this.#path,
+            baseline: this.#baseline,
+            local: this.options.local(),
+            external,
+            ...(readError === undefined ? {} : { readError }),
+            resolve: (choice) => this.#recover(conflict, choice),
+            resolveMerged: (contents) => typeof contents === "string"
+                ? this.#recover(conflict, "keep-local", contents)
+                : Promise.reject(new Error("Merged file contents must be text")),
+            refresh: () => this.#recover(conflict),
+        };
+        this.#conflict = conflict;
+        this.options.conflicts.publish(conflict);
+    }
+    async #recover(conflict, choice, merged) {
+        this.#assertCurrent(conflict);
+        if (choice !== undefined &&
+            choice !== "keep-local" &&
+            choice !== "use-external")
+            throw new Error("Invalid text conflict resolution");
+        if (merged !== undefined && typeof merged !== "string")
+            throw new Error("Merged file contents must be text");
+        const lease = await this.options.protect();
+        try {
+            await this.options.settle?.();
+            if (this.options.recoverOutsideQueue && choice !== undefined) {
+                await this.#recoverState(conflict, choice, lease, merged);
+                return;
+            }
+            await this.options.serialize(async () => {
+                this.#assertCurrent(conflict);
+                if (choice === undefined) {
+                    await this.#captureExternal();
+                    return;
+                }
+                if (conflict.external === undefined)
+                    throw new Error("Read the disk version before resolving this conflict");
+                if (choice === "keep-local") {
+                    const contents = merged ?? this.options.local();
+                    try {
+                        await this.options.vault.modifyIfUnchanged(this.options.file, contents, conflict.external);
+                    }
+                    catch (error) {
+                        if (hasCode(error, "ECONFLICT")) {
+                            await this.#captureExternal();
+                            throw this.#error;
+                        }
+                        throw error;
+                    }
+                    const previousBaseline = this.#baseline;
+                    this.#baseline = contents;
+                    if (merged !== undefined) {
+                        try {
+                            await lease.reset(contents);
+                        }
+                        catch (error) {
+                            this.#baseline = previousBaseline;
+                            throw error;
+                        }
+                        lease.resetSaved?.(contents);
+                    }
+                    else
+                        lease.saved();
+                    this.#clear();
+                }
+                else {
+                    let external;
+                    try {
+                        external = await this.#read();
+                    }
+                    catch (error) {
+                        await this.#captureExternal();
+                        throw error;
+                    }
+                    if (external !== conflict.external) {
+                        this.#publish(external);
+                        throw this.#error;
+                    }
+                    const previousBaseline = this.#baseline;
+                    this.#baseline = external;
+                    try {
+                        await lease.reset(external ?? "");
+                    }
+                    catch (error) {
+                        this.#baseline = previousBaseline;
+                        throw error;
+                    }
+                    this.#clear();
+                    lease.resetSaved?.(external ?? "");
+                }
+            });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async #recoverState(conflict, choice, lease, merged) {
+        let selected = "";
+        await this.options.serialize(async () => {
+            this.#assertCurrent(conflict);
+            if (conflict.external === undefined)
+                throw new Error("Read the disk version before resolving this conflict");
+            const actual = await this.#read();
+            if (actual !== conflict.external) {
+                this.#publish(actual);
+                throw this.#error;
+            }
+            selected =
+                merged ??
+                    (choice === "keep-local" ? this.options.local() : (actual ?? ""));
+        });
+        // The owner lease remains held, but other owned files can use the queue.
+        await lease.reset(selected);
+        await this.options.serialize(async () => {
+            this.#assertCurrent(conflict);
+            if (choice === "keep-local") {
+                try {
+                    await this.options.vault.modifyIfUnchanged(this.options.file, selected, conflict.external);
+                }
+                catch (error) {
+                    if (hasCode(error, "ECONFLICT"))
+                        await this.#captureExternal();
+                    throw error;
+                }
+            }
+            else {
+                const actual = await this.#read();
+                if (actual !== conflict.external) {
+                    this.#publish(actual);
+                    throw this.#error;
+                }
+            }
+            this.#baseline = choice === "keep-local" ? selected : conflict.external;
+            this.#clear();
+            if (choice === "keep-local" && merged === undefined)
+                lease.saved();
+            else
+                lease.resetSaved?.(selected);
+        });
+    }
+    #clear() {
+        this.#conflict = undefined;
+        this.options.conflicts.clear(this.#id);
+    }
+}

package/dist/file-text-state-writer.d.ts

@@ -0,0 +1,34 @@
+import type { App } from "./context.svelte";
+import type { FileEditingSession } from "./file-editing-sessions";
+import type { TFile } from "./storage/fs";
+/**
+ * App-owned mutable text state using the same persistence contract as
+ * documents.
+ */
+export declare class FileTextStateWriter implements FileEditingSession {
+    #private;
+    private readonly app;
+    private readonly file;
+    private readonly reset;
+    private readonly options;
+    constructor(app: App, file: TFile, baseline: string | null | undefined, reset: (text: string) => void | Promise<void>, options?: {
+        recoverOutsideQueue?: boolean;
+    });
+    get dirty(): boolean;
+    readonly native: {
+        lifetime: "operation";
+        hold: () => () => void;
+        savedText: () => string | null | undefined;
+    };
+    acceptBaseline(contents: string | null): boolean;
+    assertEditable(): void;
+    set(contents: string): Promise<void>;
+    /** Calculate a logical change only after every earlier change is acknowledged. */
+    update(calculate: () => {
+        contents: string;
+        onSaved(): void;
+    } | undefined): Promise<void>;
+    flush(): Promise<void>;
+    protect(): Promise<() => void>;
+    dispose(): void;
+}