@next-buildr/editor 0.0.0-stage → 2.0.1

package/dist/persistence/controller.js

@@ -0,0 +1,341 @@
+import { createStore } from 'zustand/vanilla';
+import { checkSaveResult, loadDocument } from './load.js';
+/** How long to wait before retrying a failed save; the last delay repeats. */
+export const RETRY_DELAYS_MS = [2000, 5000, 15_000];
+/** How often an idle, visible editor asks the backend whether somebody else saved. */
+export const EXTERNAL_CHECK_INTERVAL_MS = 30_000;
+export const systemClock = {
+    now: () => Date.now(),
+    setTimeout: (handler, ms) => setTimeout(handler, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+const errorMessage = (cause) => (cause instanceof Error ? cause.message : String(cause));
+/**
+ * The autosave state machine (docs/state-management.md#autosave):
+ * `clean → dirty → saving → clean`, with `conflict` and `error` on the side. One save is in flight
+ * at a time; a change made while it runs is saved by the next one. Whether the document is dirty
+ * is read from the history (`cursorId` ≠ `savedCursorId`), so undoing back to the saved state is
+ * clean again.
+ */
+export function createPersistence(options) {
+    const { store, adapter, ref } = options;
+    const clock = options.clock ?? systemClock;
+    const debounceMs = options.debounceMs ?? 2000;
+    const maxWaitMs = options.maxWaitMs ?? 20_000;
+    const state = createStore(() => ({
+        status: 'clean',
+        revision: options.revision,
+        lastSavedAt: undefined,
+        error: undefined,
+        conflictRevision: undefined,
+        external: undefined,
+    }));
+    const set = (patch) => state.setState(patch);
+    let debounceTimer;
+    let maxWaitTimer;
+    let retryTimer;
+    let attempt = 0;
+    let inFlight;
+    let saveAgain = false;
+    let stopped = true;
+    let externalTimer;
+    let checking = false;
+    const externalMs = options.externalCheckMs ?? EXTERNAL_CHECK_INTERVAL_MS;
+    const isVisible = options.isVisible ??
+        (() => typeof document === 'undefined' || document.visibilityState !== 'hidden');
+    const isDirty = () => {
+        const { cursorId, savedCursorId } = store.getState();
+        return cursorId !== savedCursorId;
+    };
+    const clearTimers = () => {
+        if (debounceTimer !== undefined)
+            clock.clearTimeout(debounceTimer);
+        if (maxWaitTimer !== undefined)
+            clock.clearTimeout(maxWaitTimer);
+        if (retryTimer !== undefined)
+            clock.clearTimeout(retryTimer);
+        debounceTimer = maxWaitTimer = retryTimer = undefined;
+    };
+    async function attemptSave(autosave, baseRevision) {
+        const { doc, cursorId } = store.getState();
+        set({ status: 'saving' });
+        let result;
+        try {
+            result = checkSaveResult(await adapter.save(ref, { document: doc, baseRevision, autosave }));
+        }
+        catch (cause) {
+            if (stopped)
+                return;
+            attempt += 1;
+            set({ status: 'error', error: { kind: 'network', message: errorMessage(cause), attempt } });
+            // Ctrl+S retries by itself when the author presses it again; the autosave keeps trying.
+            const delay = RETRY_DELAYS_MS[Math.min(attempt, RETRY_DELAYS_MS.length) - 1] ?? 15_000;
+            retryTimer = clock.setTimeout(() => {
+                retryTimer = undefined;
+                void run(true);
+            }, delay);
+            return;
+        }
+        if (stopped)
+            return;
+        if (result.ok) {
+            attempt = 0;
+            store.markSaved(cursorId);
+            set({
+                revision: result.revision,
+                lastSavedAt: result.updatedAt,
+                error: undefined,
+                conflictRevision: undefined,
+                external: undefined,
+            });
+            if (isDirty()) {
+                // Changed while saving: the next save takes it.
+                set({ status: 'dirty' });
+                schedule();
+            }
+            else {
+                set({ status: 'clean' });
+            }
+            return;
+        }
+        if (result.kind === 'conflict') {
+            clearTimers();
+            set({
+                status: 'conflict',
+                conflictRevision: result.currentRevision,
+                error: undefined,
+                external: undefined,
+            });
+            return;
+        }
+        clearTimers();
+        // Rejected for what it contains: retrying the same document cannot help; a change re-arms it.
+        set({ status: 'error', error: { kind: 'invalid', diagnostics: result.diagnostics } });
+    }
+    /** One save at a time; anything asked for meanwhile runs after it. */
+    function run(autosave, baseRevision) {
+        if (inFlight !== undefined) {
+            saveAgain = true;
+            return inFlight;
+        }
+        if (store.getState().readOnly)
+            return Promise.resolve();
+        clearTimers();
+        const flight = (async () => {
+            try {
+                await attemptSave(autosave, baseRevision ?? state.getState().revision);
+            }
+            finally {
+                inFlight = undefined;
+            }
+            if (saveAgain && !stopped) {
+                saveAgain = false;
+                const { status } = state.getState();
+                if (status === 'dirty' || (status === 'clean' && isDirty()))
+                    await run(autosave);
+            }
+        })();
+        inFlight = flight;
+        return flight;
+    }
+    function schedule() {
+        if (stopped || store.getState().readOnly)
+            return;
+        if (debounceTimer !== undefined)
+            clock.clearTimeout(debounceTimer);
+        debounceTimer = clock.setTimeout(() => {
+            debounceTimer = undefined;
+            void run(true);
+        }, debounceMs);
+        if (maxWaitTimer === undefined) {
+            maxWaitTimer = clock.setTimeout(() => {
+                maxWaitTimer = undefined;
+                void run(true);
+            }, maxWaitMs);
+        }
+    }
+    function onDocumentChanged() {
+        const { status } = state.getState();
+        if (status === 'conflict')
+            return;
+        if (!isDirty()) {
+            // Undone back to the saved state.
+            if (status === 'dirty' || status === 'error') {
+                clearTimers();
+                set({ status: 'clean', error: undefined });
+            }
+            return;
+        }
+        if (status === 'saving')
+            return; // The save that follows it picks the change up.
+        const { external } = state.getState();
+        if (external !== undefined) {
+            // Somebody else saved and now there are local edits too: ask now, not at the refused save.
+            clearTimers();
+            set({
+                status: 'conflict',
+                conflictRevision: external.revision,
+                error: undefined,
+                external: undefined,
+            });
+            return;
+        }
+        if (status === 'error') {
+            // A new change gives a rejected document another chance, and a failing network a sooner retry.
+            clearTimers();
+            set({ status: 'dirty', error: undefined });
+        }
+        else if (status === 'clean') {
+            set({ status: 'dirty' });
+        }
+        schedule();
+    }
+    async function checkExternal() {
+        if (stopped || checking || adapter.getRevision === undefined || !isVisible())
+            return;
+        const { status, revision } = state.getState();
+        if (status === 'saving' || status === 'conflict' || inFlight !== undefined)
+            return;
+        checking = true;
+        try {
+            const info = await adapter.getRevision(ref);
+            const now = state.getState();
+            // The answer is stale when a save, a reload or a conflict happened while it was on its way.
+            if (stopped || now.revision !== revision)
+                return;
+            if (now.status === 'saving' || now.status === 'conflict' || inFlight !== undefined)
+                return;
+            if (info.revision <= now.revision) {
+                if (now.external !== undefined)
+                    set({ external: undefined });
+                return;
+            }
+            if (isDirty()) {
+                clearTimers();
+                set({
+                    status: 'conflict',
+                    conflictRevision: info.revision,
+                    error: undefined,
+                    external: undefined,
+                });
+            }
+            else {
+                set({ external: { revision: info.revision, updatedBy: info.updatedBy } });
+            }
+        }
+        catch {
+            // Not knowing is not a reason to bother the author; the save still detects a conflict.
+        }
+        finally {
+            checking = false;
+        }
+    }
+    function scheduleExternalCheck() {
+        if (externalMs <= 0 || adapter.getRevision === undefined)
+            return;
+        externalTimer = clock.setTimeout(() => {
+            externalTimer = undefined;
+            void checkExternal().finally(() => {
+                if (!stopped)
+                    scheduleExternalCheck();
+            });
+        }, externalMs);
+    }
+    return {
+        state,
+        checkExternal,
+        start() {
+            stopped = false;
+            scheduleExternalCheck();
+            // Every step of the history moves the cursor, so this sees edits, undo, redo and replacements.
+            const stopSubscription = store.subscribe((next, previous) => {
+                if (next.cursorId !== previous.cursorId || next.savedCursorId !== previous.savedCursorId) {
+                    onDocumentChanged();
+                }
+            });
+            return () => {
+                stopped = true;
+                stopSubscription();
+                clearTimers();
+                if (externalTimer !== undefined)
+                    clock.clearTimeout(externalTimer);
+                externalTimer = undefined;
+            };
+        },
+        saveNow: () => {
+            const { status } = state.getState();
+            if (status === 'conflict')
+                return Promise.resolve();
+            if (!isDirty() && status !== 'error')
+                return Promise.resolve();
+            return run(false);
+        },
+        async reload() {
+            const loaded = await loadDocument(adapter, ref);
+            clearTimers();
+            attempt = 0;
+            store.replaceDocument(loaded.document, { readOnly: loaded.readOnly === true });
+            set({
+                status: 'clean',
+                revision: loaded.revision,
+                lastSavedAt: loaded.updatedAt,
+                error: undefined,
+                conflictRevision: undefined,
+                external: undefined,
+            });
+        },
+        overwrite() {
+            const { conflictRevision } = state.getState();
+            if (conflictRevision === undefined)
+                return Promise.resolve();
+            return run(false, conflictRevision);
+        },
+        async publish() {
+            if (state.getState().status === 'conflict') {
+                return {
+                    ok: false,
+                    kind: 'conflict',
+                    currentRevision: state.getState().conflictRevision ?? 0,
+                };
+            }
+            await this.saveNow();
+            const { status, revision } = state.getState();
+            if (status === 'conflict') {
+                return {
+                    ok: false,
+                    kind: 'conflict',
+                    currentRevision: state.getState().conflictRevision ?? 0,
+                };
+            }
+            // Publishing a revision the backend does not have would publish something else than what the author sees.
+            if (status !== 'clean')
+                return { ok: false, kind: 'unsaved' };
+            let result;
+            try {
+                result = checkSaveResult(await adapter.publish(ref, { baseRevision: revision }));
+            }
+            catch (cause) {
+                return { ok: false, kind: 'network', message: errorMessage(cause) };
+            }
+            if (result.ok) {
+                set({ revision: result.revision, lastSavedAt: result.updatedAt });
+                return { ok: true, revision: result.revision, updatedAt: result.updatedAt };
+            }
+            if (result.kind === 'conflict') {
+                clearTimers();
+                set({
+                    status: 'conflict',
+                    conflictRevision: result.currentRevision,
+                    error: undefined,
+                    external: undefined,
+                });
+                return { ok: false, kind: 'conflict', currentRevision: result.currentRevision };
+            }
+            return { ok: false, kind: 'invalid', diagnostics: result.diagnostics };
+        },
+        hasUnsavedWork() {
+            const { status } = state.getState();
+            return status === 'saving' || status === 'conflict' || isDirty();
+        },
+    };
+}

package/dist/persistence/index.d.ts

@@ -0,0 +1,6 @@
+export type { PersistenceController, PersistenceOptions } from './controller.ts';
+export { createPersistence, EXTERNAL_CHECK_INTERVAL_MS, RETRY_DELAYS_MS, systemClock, } from './controller.ts';
+export { LoadError, loadDocument, saveResultSchema } from './load.ts';
+export { PersistenceProvider, SaveStatus, usePersistence, usePersistenceState, useSaveAction, } from './react.tsx';
+export type { Clock, DocumentAdapter, DocumentRef, EditorSession, LoadedDocument, MediaSearchResult, PersistenceError, PersistenceState, PersistenceStatus, PublishOutcome, PublishResult, RevisionInfo, SaveRequest, SaveResult, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EACL,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,KAAK,EACL,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/persistence/index.js

@@ -0,0 +1,3 @@
+export { createPersistence, EXTERNAL_CHECK_INTERVAL_MS, RETRY_DELAYS_MS, systemClock, } from './controller.js';
+export { LoadError, loadDocument, saveResultSchema } from './load.js';
+export { PersistenceProvider, SaveStatus, usePersistence, usePersistenceState, useSaveAction, } from './react.js';

package/dist/persistence/load.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { DocumentAdapter, DocumentRef, LoadedDocument, SaveResult } from './types.ts';
+/** The reply of a save, checked where it enters the editor. */
+export declare const saveResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    kind: z.ZodLiteral<"conflict">;
+    currentRevision: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    kind: z.ZodLiteral<"invalid">;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export declare class LoadError extends Error {
+    readonly name = "LoadError";
+}
+/** Checks a `SaveResult` an adapter returned; a malformed one is a failed (retryable) save. */
+export declare function checkSaveResult(value: unknown): SaveResult;
+/**
+ * Loads the document of `ref` and its session, and validates what the backend sent. A viewer
+ * without edit rights gets a read-only document. Throws `LoadError` for a reply the editor cannot
+ * open (the caller shows an error screen); a rejection of the adapter itself passes through.
+ */
+export declare function loadDocument(adapter: DocumentAdapter, ref: DocumentRef): Promise<LoadedDocument>;
+//# sourceMappingURL=load.d.ts.map

package/dist/persistence/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/persistence/load.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ3F,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;mBAY3B,CAAC;AAaH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,eAAe;CACtC;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAI1D;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,cAAc,CAAC,CAmBzB"}

package/dist/persistence/load.js

@@ -0,0 +1,67 @@
+import { parseDocument } from '@next-buildr/core';
+import { z } from 'zod';
+const diagnosticSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['error', 'warning']),
+});
+/** The reply of a save, checked where it enters the editor. */
+export const saveResultSchema = z.union([
+    z.object({ ok: z.literal(true), revision: z.number().int(), updatedAt: z.string() }),
+    z.object({
+        ok: z.literal(false),
+        kind: z.literal('conflict'),
+        currentRevision: z.number().int(),
+    }),
+    z.object({
+        ok: z.literal(false),
+        kind: z.literal('invalid'),
+        diagnostics: z.array(diagnosticSchema),
+    }),
+]);
+const loadedSchema = z.object({
+    title: z.string(),
+    slug: z.string().optional(),
+    status: z.enum(['draft', 'published']),
+    updatedAt: z.string(),
+    revision: z.number().int(),
+    document: z.unknown(),
+    readOnly: z.boolean().optional(),
+    contextRef: z.string().optional(),
+});
+export class LoadError extends Error {
+    name = 'LoadError';
+}
+/** Checks a `SaveResult` an adapter returned; a malformed one is a failed (retryable) save. */
+export function checkSaveResult(value) {
+    const parsed = saveResultSchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error('the adapter returned a malformed save result');
+    return parsed.data;
+}
+/**
+ * Loads the document of `ref` and its session, and validates what the backend sent. A viewer
+ * without edit rights gets a read-only document. Throws `LoadError` for a reply the editor cannot
+ * open (the caller shows an error screen); a rejection of the adapter itself passes through.
+ */
+export async function loadDocument(adapter, ref) {
+    const [session, raw] = await Promise.all([adapter.getSession(ref), adapter.load(ref)]);
+    const shape = loadedSchema.safeParse(raw);
+    if (!shape.success)
+        throw new LoadError('the backend sent a malformed document reply');
+    const parsed = parseDocument(shape.data.document);
+    if (!parsed.ok) {
+        throw new LoadError(`the document is invalid: ${parsed.error[0]?.message ?? 'unknown'}`);
+    }
+    const document = parsed.value;
+    return {
+        title: shape.data.title,
+        slug: shape.data.slug,
+        status: shape.data.status,
+        updatedAt: shape.data.updatedAt,
+        revision: shape.data.revision,
+        document,
+        readOnly: shape.data.readOnly === true || !session.canEdit,
+        contextRef: shape.data.contextRef,
+    };
+}

package/dist/persistence/persistence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=persistence.test.d.ts.map

package/dist/persistence/persistence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.test.d.ts","sourceRoot":"","sources":["../../src/persistence/persistence.test.tsx"],"names":[],"mappings":""}