@mdbase-dev/connect 0.1.0-beta.111 → 0.1.0-beta.113

package/dist/record-session.js

@@ -0,0 +1,449 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+/**
+ * One open, editable record: debounced autosave, one write queue, own
+ * acknowledgements recognized by revision after each write settles,
+ * field-level conflict detection, and exact recovery of writes whose outcome
+ * is unknown. Share one session between every view of the same record.
+ */
+export class MdbaseRecordSession {
+    adapter;
+    record;
+    /** The local text `record` acknowledges; it differs from the record's body after server normalization. */
+    baseBody;
+    body;
+    patch = {};
+    remote = null;
+    problem = null;
+    deleted = false;
+    busy = false;
+    pending;
+    incoming = [];
+    seen = new Set();
+    listeners = new Set();
+    tail = Promise.resolve();
+    queued = 0;
+    inFlight;
+    timer;
+    lastEdit = 0;
+    idleMs;
+    current;
+    constructor(record, adapter, options = {}) {
+        this.adapter = adapter;
+        this.record = record;
+        this.baseBody = this.body = adapter.body(record);
+        this.seen.add(adapter.revision(record));
+        this.idleMs = options.autosave === false ? undefined : options.autosave?.idleMs ?? 1000;
+        this.current = this.compute();
+    }
+    get snapshot() {
+        return this.current;
+    }
+    getSnapshot = () => this.current;
+    /** Listeners run synchronously after every change, including each edit. */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => void this.listeners.delete(listener);
+    };
+    setBody(body) {
+        if (body === this.body)
+            return;
+        this.body = body;
+        this.edited();
+    }
+    patchFrontmatter(patch) {
+        this.patch = { ...this.patch, ...patch };
+        this.edited();
+    }
+    /**
+     * Offer a draft kept outside the session, such as a crash-recovery copy. It
+     * is never written by itself: call `autosave()` or `save()`. A draft whose
+     * base is unknown or has since changed is a conflict with the current record.
+     */
+    restore(draft) {
+        const current = this.adapter.body(this.record);
+        if (draft.body === current)
+            return;
+        this.body = draft.body;
+        if (draft.baseBody !== current)
+            this.remote = this.record;
+        this.emit();
+    }
+    /**
+     * Continue a write interrupted before this session existed, such as one
+     * found in durable storage after a reload. No new write is sent until it
+     * settles; with autosave, recovery is attempted after one idle interval.
+     */
+    resumeRecovery(requestId) {
+        if (this.pending || this.busy)
+            return;
+        this.pending = { requestId, sent: "restored" };
+        this.emit();
+        this.autosave();
+    }
+    /** Schedule an autosave one idle interval from now. */
+    autosave() {
+        this.lastEdit = Date.now();
+        this.schedule();
+    }
+    /**
+     * A record published by another view or cache. It may be stale, so a
+     * revision this session has already seen is ignored, and records arriving
+     * while a write is unsettled wait until that write's acknowledgement is known.
+     */
+    receive(record) {
+        if (this.seen.has(this.adapter.revision(record)))
+            return;
+        if (this.busy || this.pending) {
+            this.incoming.push(record);
+            return;
+        }
+        this.seen.add(this.adapter.revision(record));
+        this.classify(record);
+        this.emit();
+    }
+    /**
+     * Read the current record after any queued write and apply it. Unlike a
+     * publication this is never stale, so a revision seen before is still
+     * applied (revisions repeat when content is reverted).
+     */
+    refresh(options) {
+        return this.run(async () => {
+            const read = this.adapter.read;
+            if (!read || this.pending)
+                return connectSuccess(this.record);
+            const outcome = await read(this.record, options);
+            if (!outcome.ok) {
+                if (outcome.problem.code === "file_not_found")
+                    this.markDeleted();
+                return outcome;
+            }
+            this.seen.add(this.adapter.revision(outcome.value));
+            this.classify(outcome.value);
+            this.emit();
+            return connectSuccess(this.record);
+        });
+    }
+    /**
+     * Accept a record this application produced outside the session's writes,
+     * such as a rename's result. It is never a conflict: local changes made
+     * meanwhile are kept on top of it.
+     */
+    accept(record) {
+        this.seen.add(this.adapter.revision(record));
+        const body = this.adapter.body(record);
+        if (this.body === this.baseBody)
+            this.body = body;
+        this.baseBody = body;
+        const matter = this.adapter.frontmatter?.(record) ?? {};
+        for (const [key, value] of Object.entries(this.patch)) {
+            if (sameJson(matter[key], value))
+                delete this.patch[key];
+        }
+        this.record = record;
+        this.remote = null;
+        this.problem = null;
+        this.emit();
+    }
+    markDeleted() {
+        clearTimeout(this.timer);
+        this.deleted = true;
+        this.emit();
+    }
+    /**
+     * Write local changes now, or continue an interrupted write's exact
+     * recovery. Joins a save already in flight. Resolves with the accepted record.
+     */
+    save(options) {
+        clearTimeout(this.timer);
+        if (this.inFlight)
+            return this.inFlight;
+        const write = this.run(() => this.pending ? this.recoverPending(options) : this.write(options, true));
+        this.inFlight = write;
+        const settle = () => { if (this.inFlight === write)
+            this.inFlight = undefined; };
+        write.then(settle, settle);
+        return write;
+    }
+    /** Save until every local change is acknowledged, or report why it cannot be. */
+    async flush(options) {
+        for (;;) {
+            if (this.deleted)
+                return connectFailure(deletedProblem());
+            if (this.remote)
+                return connectFailure(conflictProblem());
+            if (!this.inFlight && !this.pending && !this.dirtyLocally())
+                return connectSuccess(this.record);
+            const saved = await this.save(options);
+            if (!saved.ok)
+                return saved;
+        }
+    }
+    /** Run another operation on this record (rename, delete, …) in the session's write queue. */
+    run(operation) {
+        // An idle queue starts synchronously, so a write is in flight before the caller's next edit.
+        const result = this.queued === 0 ? operation() : this.tail.then(operation);
+        this.queued += 1;
+        const done = () => { this.queued -= 1; };
+        this.tail = result.then(done, done);
+        return result;
+    }
+    /** Settle a conflict: keep local changes on top of the remote record, take the remote record, or use merged text. */
+    resolve(choice) {
+        const remote = this.remote;
+        if (!remote || this.busy)
+            return;
+        this.record = remote;
+        this.remote = null;
+        this.problem = null;
+        this.baseBody = this.adapter.body(remote);
+        if ("body" in choice)
+            this.body = choice.body;
+        else if (choice.keep === "theirs") {
+            this.body = this.baseBody;
+            this.patch = {};
+        }
+        this.emit();
+        if (this.dirtyLocally())
+            this.autosave();
+    }
+    /** Drop local changes and return to the latest record. */
+    discard() {
+        if (this.busy)
+            return;
+        clearTimeout(this.timer);
+        this.record = this.remote ?? this.record;
+        this.remote = null;
+        this.problem = null;
+        this.baseBody = this.body = this.adapter.body(this.record);
+        this.patch = {};
+        this.emit();
+    }
+    edited() {
+        this.problem = null;
+        this.lastEdit = Date.now();
+        this.emit();
+        this.schedule();
+    }
+    schedule() {
+        clearTimeout(this.timer);
+        if (this.idleMs === undefined || this.remote || this.deleted)
+            return;
+        const delay = Math.max(0, this.lastEdit + this.idleMs - Date.now());
+        this.timer = setTimeout(() => void this.save(), delay);
+    }
+    dirtyLocally() {
+        return this.body !== this.baseBody || Object.keys(this.patch).length > 0;
+    }
+    async write(options, rebaseOnRejection) {
+        if (this.remote)
+            return connectFailure(conflictProblem());
+        if (this.deleted)
+            return connectFailure(deletedProblem());
+        if (!this.dirtyLocally())
+            return connectSuccess(this.record);
+        const sent = {};
+        if (this.body !== this.baseBody)
+            sent.body = this.body;
+        if (Object.keys(this.patch).length)
+            sent.patch = structuredClone(this.patch);
+        this.busy = true;
+        this.emit();
+        const outcome = await this.guard(() => this.adapter.write(this.record, { ...sent }, options));
+        if (outcome.ok) {
+            this.acknowledge(outcome.value, sent);
+            return connectSuccess(this.record);
+        }
+        const requestId = outcomeUnknownRequestId(outcome.problem);
+        if (requestId) {
+            this.busy = false;
+            this.problem = outcome.problem;
+            this.pending = { requestId, sent };
+            this.emit();
+            this.schedule();
+            return outcome;
+        }
+        const classified = await this.classifyFailure(outcome.problem, options);
+        if (classified === "resolved")
+            return connectSuccess(this.record);
+        if (classified === "rebased" && rebaseOnRejection)
+            return this.write(options, false);
+        return this.failure(outcome.problem);
+    }
+    async recoverPending(options) {
+        const pending = this.pending;
+        const recover = this.adapter.recover;
+        if (!recover) {
+            return connectFailure(connectProblem("pending_mutation_unresolved", "Exact recovery of the interrupted write is unavailable. No new write was attempted."));
+        }
+        this.busy = true;
+        this.emit();
+        const outcome = await this.guard(() => recover(pending.requestId, options));
+        if (outcome.ok) {
+            if (pending.sent === "restored") {
+                // Unknown content, so accept it like an out-of-band result: newer typing is kept.
+                this.pending = undefined;
+                this.busy = false;
+                this.accept(outcome.value);
+                this.settle();
+            }
+            else {
+                this.acknowledge(outcome.value, pending.sent);
+            }
+            return connectSuccess(this.record);
+        }
+        // Only the SDK settling its durable handle proves the original intent was resolved.
+        const settled = outcome.problem.operation_outcome !== "unknown"
+            && outcome.problem.code !== "operation_outcome_unknown"
+            && this.adapter.isPending?.(pending.requestId) === false;
+        if (!settled) {
+            this.busy = false;
+            this.problem = outcome.problem;
+            this.emit();
+            return outcome;
+        }
+        this.pending = undefined;
+        await this.classifyFailure(outcome.problem, options);
+        return this.failure(outcome.problem);
+    }
+    /** An adapter that throws breaks its contract: rethrow, but leave the queue usable. */
+    async guard(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            this.busy = false;
+            this.emit();
+            throw error;
+        }
+    }
+    failure(problem) {
+        if (this.deleted)
+            return connectFailure(deletedProblem());
+        if (this.remote)
+            return connectFailure(conflictProblem());
+        return connectFailure(problem);
+    }
+    acknowledge(result, sent) {
+        this.seen.add(this.adapter.revision(result));
+        this.record = result;
+        if (sent.body !== undefined)
+            this.baseBody = sent.body;
+        for (const [key, value] of Object.entries(sent.patch ?? {})) {
+            if (key in this.patch && sameJson(this.patch[key], value))
+                delete this.patch[key];
+        }
+        this.problem = null;
+        this.pending = undefined;
+        this.settle();
+        if (this.dirtyLocally())
+            this.schedule();
+    }
+    /** Read once to learn whether a failed write met a conflict, a convergent edit or deletion. */
+    async classifyFailure(problem, options) {
+        const base = this.adapter.revision(this.record);
+        const read = this.adapter.read;
+        const outcome = read ? await this.guard(() => read(this.record, options)) : undefined;
+        if (outcome && !outcome.ok && outcome.problem.code === "file_not_found") {
+            this.deleted = true;
+            this.settle();
+            return "failed";
+        }
+        if (!outcome?.ok || this.adapter.revision(outcome.value) === base) {
+            this.problem = problem;
+            this.settle();
+            return "failed";
+        }
+        this.seen.add(this.adapter.revision(outcome.value));
+        this.classify(outcome.value);
+        this.settle();
+        if (this.remote)
+            return "failed";
+        return this.dirtyLocally() ? "rebased" : "resolved";
+    }
+    settle() {
+        this.busy = false;
+        for (const record of this.incoming.splice(0)) {
+            if (this.seen.has(this.adapter.revision(record)))
+                continue;
+            this.seen.add(this.adapter.revision(record));
+            this.classify(record);
+        }
+        this.emit();
+    }
+    /** Field-level three-way comparison of a newer record with the base and local changes. */
+    classify(record) {
+        if (this.adapter.revision(record) === this.adapter.revision(this.record))
+            return;
+        const baseBody = this.adapter.body(this.record);
+        const remoteBody = this.adapter.body(record);
+        const bodyChanged = remoteBody !== baseBody;
+        const bodyDirty = this.body !== this.baseBody;
+        const baseMatter = this.adapter.frontmatter?.(this.record) ?? {};
+        const remoteMatter = this.adapter.frontmatter?.(record) ?? {};
+        const conflict = (bodyDirty && bodyChanged && remoteBody !== this.body)
+            || Object.entries(this.patch).some(([key, value]) => !sameJson(remoteMatter[key], baseMatter[key]) && !sameJson(remoteMatter[key], value));
+        if (conflict) {
+            clearTimeout(this.timer);
+            this.remote = record;
+            return;
+        }
+        this.remote = null;
+        this.record = record;
+        // Not a conflict, so a changed remote body either replaces a clean draft or equals it.
+        if (bodyChanged)
+            this.baseBody = this.body = remoteBody;
+        for (const [key, value] of Object.entries(this.patch)) {
+            if (sameJson(remoteMatter[key], value))
+                delete this.patch[key];
+        }
+        if (!this.dirtyLocally())
+            this.problem = null;
+    }
+    compute() {
+        const dirty = this.busy || Boolean(this.pending) || this.dirtyLocally();
+        const state = this.deleted ? "deleted"
+            : this.remote ? "conflict"
+                : this.busy ? "saving"
+                    : this.pending ? "recovery"
+                        : this.problem ? "error"
+                            : dirty ? "unsaved" : "saved";
+        return {
+            state,
+            body: this.body,
+            frontmatter: { ...(this.adapter.frontmatter?.(this.record) ?? {}), ...this.patch },
+            record: this.record,
+            remote: this.remote,
+            dirty,
+            problem: this.problem,
+            ...(this.pending ? { pendingRequestId: this.pending.requestId } : {})
+        };
+    }
+    emit() {
+        this.current = this.compute();
+        this.listeners.forEach((listener) => listener());
+    }
+}
+function conflictProblem() {
+    return connectProblem("concurrent_modification", "This record changed elsewhere. Local changes are kept until the conflict is resolved.");
+}
+function deletedProblem() {
+    return connectProblem("file_not_found", "This record no longer exists. Local changes are kept.");
+}
+function outcomeUnknownRequestId(problem) {
+    return problem.code === "operation_outcome_unknown" ? problem.details.request_id : undefined;
+}
+function sameJson(left, right) {
+    if (left === right)
+        return true;
+    if (typeof left !== "object" || typeof right !== "object" || left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length
+            && left.every((value, index) => sameJson(value, right[index]));
+    }
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length
+        && keys.every((key) => key in right
+            && sameJson(left[key], right[key]));
+}

package/dist/records.d.ts

@@ -0,0 +1,56 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import type { ConnectRequestOptions, MdbaseWatchSubscription, PendingMutation, ReadInput, RecordDocument, UpdateInput } from "./operation-types.js";
+import { type CollectionMutationProblemCode, type CollectionReadProblemCode, type ConnectOutcome } from "./outcomes.js";
+import { MdbaseRecordSession, type MdbaseRecordSessionOptions } from "./record-session.js";
+export interface MdbaseRecordOpenOptions extends ConnectRequestOptions, MdbaseRecordSessionOptions {
+}
+/** One view's hold on a shared record session. */
+export interface MdbaseRecordLease<Frontmatter extends JsonObject = JsonObject> {
+    readonly session: MdbaseRecordSession<RecordDocument<Frontmatter>>;
+    /**
+     * Stop using the session from this view. Idempotent. Local changes are
+     * still saved; the session is dropped once no view holds it and it is saved.
+     */
+    release(): void;
+}
+/** The parts of a connection a record session uses; `MdbaseConnection` satisfies it. */
+interface RecordConnection<Frontmatter extends JsonObject> {
+    read(input: ReadInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionReadProblemCode>>;
+    update(input: UpdateInput<Frontmatter>, options?: ConnectRequestOptions): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionMutationProblemCode>>;
+    pendingMutation<Result>(requestId: string): PendingMutation<Result> | null;
+}
+/**
+ * Editable record sessions for one connection: `connection.records`. Every
+ * view that opens the same path shares one session, so a record never has
+ * two competing writers in one application.
+ */
+export declare class MdbaseRecords<Frontmatter extends JsonObject = JsonObject> {
+    private readonly connection;
+    /** Finds this record's interrupted update, which survives reloads in durable storage. */
+    private readonly pendingUpdate;
+    private readonly entries;
+    private readonly opening;
+    constructor(connection: RecordConnection<Frontmatter>, 
+    /** Finds this record's interrupted update, which survives reloads in durable storage. */
+    pendingUpdate?: (path: string) => Promise<string | null>);
+    /**
+     * Read a record and hold its editing session. Session options apply when
+     * the session is first created; later opens share it as it is. A save
+     * interrupted before a reload resumes as exact recovery.
+     */
+    open(path: string, options?: MdbaseRecordOpenOptions): Promise<ConnectOutcome<MdbaseRecordLease<Frontmatter>, CollectionReadProblemCode>>;
+    /**
+     * Keep open sessions current from a collection watch: changed records are
+     * refreshed, renamed records are followed and deleted records are marked.
+     * Returns a function that stops following.
+     */
+    follow(watch: Pick<MdbaseWatchSubscription, "subscribe">): () => void;
+    private load;
+    /** Writes and reads follow the entry's current path, so a followed rename needs no new session. */
+    private adapter;
+    private lease;
+    /** Drop an unheld session once it has nothing left to save. */
+    private retire;
+    private apply;
+}
+export {};

package/dist/records.js

@@ -0,0 +1,150 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+import { MdbaseRecordSession } from "./record-session.js";
+/**
+ * Editable record sessions for one connection: `connection.records`. Every
+ * view that opens the same path shares one session, so a record never has
+ * two competing writers in one application.
+ */
+export class MdbaseRecords {
+    connection;
+    pendingUpdate;
+    entries = new Map();
+    opening = new Map();
+    constructor(connection, 
+    /** Finds this record's interrupted update, which survives reloads in durable storage. */
+    pendingUpdate = async () => null) {
+        this.connection = connection;
+        this.pendingUpdate = pendingUpdate;
+    }
+    /**
+     * Read a record and hold its editing session. Session options apply when
+     * the session is first created; later opens share it as it is. A save
+     * interrupted before a reload resumes as exact recovery.
+     */
+    async open(path, options = {}) {
+        for (;;) {
+            const existing = this.entries.get(path);
+            if (existing)
+                return connectSuccess(this.lease(existing));
+            const shared = this.opening.get(path);
+            const opening = shared ?? this.load(path, options);
+            if (!shared) {
+                this.opening.set(path, opening);
+                void opening.then(() => this.opening.delete(path));
+            }
+            const opened = await opening;
+            if (opened.ok)
+                return connectSuccess(this.lease(opened.value));
+            // Another caller's cancellation or deadline does not end this one's open.
+            const foreign = shared && (opened.problem.code === "operation_cancelled" || opened.problem.code === "timeout");
+            if (!foreign || options.signal?.aborted)
+                return opened;
+        }
+    }
+    /**
+     * Keep open sessions current from a collection watch: changed records are
+     * refreshed, renamed records are followed and deleted records are marked.
+     * Returns a function that stops following.
+     */
+    follow(watch) {
+        return watch.subscribe((change) => this.apply(change), (status) => {
+            // Changes were missed: every open record may be stale.
+            if (status.state === "reset_required") {
+                for (const entry of this.entries.values())
+                    void entry.session.refresh();
+            }
+        });
+    }
+    async load(path, options) {
+        const { autosave, ...request } = options;
+        const read = await this.connection.read({ path }, request);
+        if (!read.ok)
+            return read;
+        const existing = this.entries.get(read.value.path);
+        if (existing)
+            return connectSuccess(existing);
+        const entry = { path: read.value.path, leases: 0 };
+        entry.session = new MdbaseRecordSession(read.value, this.adapter(entry), { autosave });
+        const interrupted = await this.pendingUpdate(entry.path);
+        if (interrupted)
+            entry.session.resumeRecovery(interrupted);
+        this.entries.set(entry.path, entry);
+        return connectSuccess(entry);
+    }
+    /** Writes and reads follow the entry's current path, so a followed rename needs no new session. */
+    adapter(entry) {
+        return {
+            revision: (record) => record.revision,
+            body: (record) => record.body ?? "",
+            frontmatter: (record) => record.frontmatter,
+            write: (base, change, options) => this.connection.update({
+                path: entry.path,
+                ifRevision: base.revision,
+                patch: (change.patch ?? {}),
+                ...(change.body === undefined ? {} : { body: change.body })
+            }, options),
+            read: (_base, options) => this.connection.read({ path: entry.path }, options),
+            recover: async (requestId, options) => {
+                const pending = this.connection.pendingMutation(requestId);
+                return pending
+                    ? pending.recover(options)
+                    : connectFailure(connectProblem("no_pending_mutation", "The interrupted write is no longer pending."));
+            },
+            isPending: (requestId) => this.connection.pendingMutation(requestId) !== null
+        };
+    }
+    lease(entry) {
+        entry.leases += 1;
+        entry.stopRetiring?.();
+        entry.stopRetiring = undefined;
+        let released = false;
+        return {
+            session: entry.session,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                entry.leases -= 1;
+                this.retire(entry);
+            }
+        };
+    }
+    /** Drop an unheld session once it has nothing left to save. */
+    retire(entry) {
+        if (entry.leases > 0)
+            return;
+        const drop = () => {
+            const { state } = entry.session.snapshot;
+            if (state !== "saved" && state !== "deleted")
+                return false;
+            entry.stopRetiring?.();
+            entry.stopRetiring = undefined;
+            if (this.entries.get(entry.path) === entry)
+                this.entries.delete(entry.path);
+            return true;
+        };
+        if (!drop())
+            entry.stopRetiring = entry.session.subscribe(() => void drop());
+    }
+    apply(change) {
+        const { payload } = change;
+        if (change.type === "mdbase.record.renamed") {
+            const entry = typeof payload.from === "string" ? this.entries.get(payload.from) : undefined;
+            if (!entry || typeof payload.to !== "string")
+                return;
+            this.entries.delete(entry.path);
+            entry.path = payload.to;
+            this.entries.set(entry.path, entry);
+            void entry.session.refresh();
+            return;
+        }
+        if (change.type !== "mdbase.record.modified" && change.type !== "mdbase.record.deleted")
+            return;
+        const entry = typeof payload.path === "string" ? this.entries.get(payload.path) : undefined;
+        // The echo of this session's own acknowledged write needs no read.
+        if (!entry || payload.revision === entry.session.snapshot.record.revision)
+            return;
+        void entry.session.refresh();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.111",
+  "version": "0.1.0-beta.113",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.111"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.113"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",