@pixerate/editor 0.278.0 → 0.279.0

package/dist/persistence/remoteSync.d.cts

@@ -0,0 +1,152 @@
+import type { EditorDocument } from "./editorDocument.cjs";
+import type { EditorAutosave } from "./editorAutosave.cjs";
+export type EditorRemoteSyncState = "idle" | "pending" | "saving" | "saved" | "error";
+export interface EditorRemoteSyncStatus {
+    status: EditorRemoteSyncState;
+    version: number;
+    savedVersion: number;
+    dirty: boolean;
+    lastSavedAt: number | null;
+    error?: unknown;
+}
+export interface EditorRemoteSaveContext<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    /** The version to write. */
+    version: number;
+    /**
+     * The server version this save builds on (the last one confirmed). For a compare-and-set
+     * write, update only where the stored version still equals it, and return `{ conflict: true }`
+     * when nothing was updated.
+     */
+    baseVersion: number;
+    /** Changes since the last saved snapshot (with the `diff` option). */
+    diff?: TDiff;
+}
+export interface EditorRemoteSaveResult {
+    version?: number;
+    /**
+     * The server holds a newer version than `baseVersion`, so nothing was written. The controller
+     * calls `onConflict` (or reports an `EditorRemoteConflictError` without it) and keeps the edits.
+     */
+    conflict?: boolean;
+}
+export interface EditorRemoteConflictContext<TDocument = unknown> {
+    /** What this session tried to save. */
+    document: TDocument;
+    /** The last snapshot the server confirmed: the common base for a three-way merge. */
+    base: TDocument;
+    /** The server version reported with the conflict, when `save` returned one. */
+    serverVersion?: number;
+    /**
+     * Runs `fn` (e.g. loading the merged document into the editor) without it counting as a local
+     * change, so it is not broadcast as one; the retry save picks the result up.
+     */
+    apply<TResult>(fn: () => TResult): TResult;
+}
+export interface EditorRemoteConflictResolution<TDocument = unknown> {
+    /** The server's version the merge was made on; the retry save builds on it. */
+    serverVersion: number;
+    /** The server's document, used as the base for the retry's `diff` (default: the old base). */
+    serverDocument?: TDocument;
+}
+/** Reported through `onError` / `status().error` when a save conflicts and is not resolved. */
+export declare class EditorRemoteConflictError extends Error {
+    readonly serverVersion?: number | undefined;
+    constructor(serverVersion?: number | undefined);
+}
+export interface EditorRemoteLocalChangeEvent<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    baseline: TDocument;
+    diff?: TDiff;
+    version: number;
+}
+export interface EditorRemoteSyncOptions<TDocument = unknown, TDiff = unknown> {
+    /**
+     * Persists the latest document snapshot and version to the remote backend.
+     * May return `{ version }` or a numeric `version` if the server advanced the version higher.
+     */
+    save: (context: EditorRemoteSaveContext<TDocument, TDiff>) => Promise<EditorRemoteSaveResult | number | void>;
+    /** Initial known server version of the document (default `0`). */
+    initialVersion?: number;
+    /** Debounce delay in milliseconds after a local edit before calling `save` (default `500`). */
+    debounceMs?: number;
+    /**
+     * Optional diff calculator. `onLocalChange` receives the diff from the previous local snapshot
+     * (the one edit); `save` receives the diff from the last saved snapshot (every edit it covers).
+     */
+    diff?: (current: TDocument, baseline: TDocument) => TDiff;
+    /**
+     * Optional predicate returning `true` when `diff` represents no meaningful change.
+     * When omitted, compares `JSON.stringify(current) === JSON.stringify(baseline)`.
+     */
+    isEmptyDiff?: (diff: TDiff, current: TDocument, baseline: TDocument) => boolean;
+    /**
+     * Invoked immediately whenever a local document change is detected (before `save` debounce),
+     * e.g. for broadcasting incremental diffs to realtime collaborators.
+     */
+    onLocalChange?: (event: EditorRemoteLocalChangeEvent<TDocument, TDiff>) => void;
+    /** Invoked when a remote `save` completes. */
+    onSaved?: (event: {
+        document: TDocument;
+        version: number;
+    }) => void;
+    /** Invoked when a remote `save` throws. */
+    onError?: (error: unknown) => void;
+    /**
+     * Resolves a conflicting save (`save` returned `{ conflict: true }`): fetch the server's
+     * document, merge this session's edits into it (`base` → `document`), load the result with
+     * `apply`, and return the server's version. The controller then saves again on top of it.
+     */
+    onConflict?: (context: EditorRemoteConflictContext<TDocument>) => Promise<EditorRemoteConflictResolution<TDocument>> | EditorRemoteConflictResolution<TDocument>;
+    /** Conflicts resolved in a row before the controller gives up with an error (default `3`). */
+    maxConflictRetries?: number;
+    /**
+     * Optional crash-recovery autosave instance. When a remote save succeeds and no newer
+     * local edits occurred while it was in flight, `autosave.markClean()` is called automatically.
+     */
+    autosave?: Pick<EditorAutosave, "markClean">;
+    /** Wall clock (default `Date.now`). */
+    now?: () => number;
+}
+export interface EditorRemoteSync<TDocument = unknown, TDiff = unknown> {
+    /** Current local version number. */
+    version(): number;
+    /** Last version confirmed saved by the remote server. */
+    savedVersion(): number;
+    /** Whether local changes are waiting to be saved or currently saving. */
+    dirty(): boolean;
+    /** Current sync status snapshot. */
+    status(): EditorRemoteSyncStatus;
+    /** Last committed local baseline snapshot. */
+    baseline(): TDocument;
+    /** Checks the document for changes against `baseline()` (called automatically via `doc.subscribe`). */
+    notify(): boolean;
+    /**
+     * Runs `fn` while suppressing local change detection (so incoming collaborator diffs or
+     * server loads do not echo back a save), then updates `baseline` and advances `version` /
+     * `savedVersion` to `Math.max(version, remoteVersion)`.
+     */
+    applyRemote<TResult>(fn: () => TResult, remoteVersion?: number): TResult;
+    /** Resets the baseline to `doc.getDocument()` and updates `version` / `savedVersion`. */
+    resetBaseline(remoteVersion?: number): void;
+    /** Cancels any debounce timer and immediately saves pending changes. */
+    flush(): Promise<boolean>;
+    /** Resolves when any pending or in-flight save has settled. */
+    whenIdle(): Promise<void>;
+    /** Subscribes to status changes. */
+    subscribe(listener: (status: EditorRemoteSyncStatus) => void): () => void;
+    /** Cancels timers and unsubscribes from `doc`, without discarding in-flight work. */
+    destroy(): void;
+}
+/**
+ * Reactive, version-safe remote persistence controller for an `EditorDocument`.
+ *
+ * - Subscribes to `doc` so every edit (history steps, undo/redo, node drags/resizes, inline
+ *   node data updates, and companion `extras` changes) automatically diffs against the last
+ *   baseline, emits `onLocalChange` for realtime collaboration, and schedules a debounced save.
+ * - Serializes remote `save` calls so two saves never overlap on the wire; edits made while a
+ *   save is in flight are coalesced into a single follow-up save.
+ * - Advances versions monotonically (`Math.max(localVersion, remoteVersion) + 1`), preventing
+ *   version-mismatch wedging when collaborators or server triggers advance the remote version.
+ */
+export declare function createEditorRemoteSync<TDocument = unknown, TDiff = unknown>(doc: EditorDocument<TDocument>, options: EditorRemoteSyncOptions<TDocument, TDiff>): EditorRemoteSync<TDocument, TDiff>;

package/dist/persistence/remoteSync.d.ts

@@ -0,0 +1,152 @@
+import type { EditorDocument } from "./editorDocument.js";
+import type { EditorAutosave } from "./editorAutosave.js";
+export type EditorRemoteSyncState = "idle" | "pending" | "saving" | "saved" | "error";
+export interface EditorRemoteSyncStatus {
+    status: EditorRemoteSyncState;
+    version: number;
+    savedVersion: number;
+    dirty: boolean;
+    lastSavedAt: number | null;
+    error?: unknown;
+}
+export interface EditorRemoteSaveContext<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    /** The version to write. */
+    version: number;
+    /**
+     * The server version this save builds on (the last one confirmed). For a compare-and-set
+     * write, update only where the stored version still equals it, and return `{ conflict: true }`
+     * when nothing was updated.
+     */
+    baseVersion: number;
+    /** Changes since the last saved snapshot (with the `diff` option). */
+    diff?: TDiff;
+}
+export interface EditorRemoteSaveResult {
+    version?: number;
+    /**
+     * The server holds a newer version than `baseVersion`, so nothing was written. The controller
+     * calls `onConflict` (or reports an `EditorRemoteConflictError` without it) and keeps the edits.
+     */
+    conflict?: boolean;
+}
+export interface EditorRemoteConflictContext<TDocument = unknown> {
+    /** What this session tried to save. */
+    document: TDocument;
+    /** The last snapshot the server confirmed: the common base for a three-way merge. */
+    base: TDocument;
+    /** The server version reported with the conflict, when `save` returned one. */
+    serverVersion?: number;
+    /**
+     * Runs `fn` (e.g. loading the merged document into the editor) without it counting as a local
+     * change, so it is not broadcast as one; the retry save picks the result up.
+     */
+    apply<TResult>(fn: () => TResult): TResult;
+}
+export interface EditorRemoteConflictResolution<TDocument = unknown> {
+    /** The server's version the merge was made on; the retry save builds on it. */
+    serverVersion: number;
+    /** The server's document, used as the base for the retry's `diff` (default: the old base). */
+    serverDocument?: TDocument;
+}
+/** Reported through `onError` / `status().error` when a save conflicts and is not resolved. */
+export declare class EditorRemoteConflictError extends Error {
+    readonly serverVersion?: number | undefined;
+    constructor(serverVersion?: number | undefined);
+}
+export interface EditorRemoteLocalChangeEvent<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    baseline: TDocument;
+    diff?: TDiff;
+    version: number;
+}
+export interface EditorRemoteSyncOptions<TDocument = unknown, TDiff = unknown> {
+    /**
+     * Persists the latest document snapshot and version to the remote backend.
+     * May return `{ version }` or a numeric `version` if the server advanced the version higher.
+     */
+    save: (context: EditorRemoteSaveContext<TDocument, TDiff>) => Promise<EditorRemoteSaveResult | number | void>;
+    /** Initial known server version of the document (default `0`). */
+    initialVersion?: number;
+    /** Debounce delay in milliseconds after a local edit before calling `save` (default `500`). */
+    debounceMs?: number;
+    /**
+     * Optional diff calculator. `onLocalChange` receives the diff from the previous local snapshot
+     * (the one edit); `save` receives the diff from the last saved snapshot (every edit it covers).
+     */
+    diff?: (current: TDocument, baseline: TDocument) => TDiff;
+    /**
+     * Optional predicate returning `true` when `diff` represents no meaningful change.
+     * When omitted, compares `JSON.stringify(current) === JSON.stringify(baseline)`.
+     */
+    isEmptyDiff?: (diff: TDiff, current: TDocument, baseline: TDocument) => boolean;
+    /**
+     * Invoked immediately whenever a local document change is detected (before `save` debounce),
+     * e.g. for broadcasting incremental diffs to realtime collaborators.
+     */
+    onLocalChange?: (event: EditorRemoteLocalChangeEvent<TDocument, TDiff>) => void;
+    /** Invoked when a remote `save` completes. */
+    onSaved?: (event: {
+        document: TDocument;
+        version: number;
+    }) => void;
+    /** Invoked when a remote `save` throws. */
+    onError?: (error: unknown) => void;
+    /**
+     * Resolves a conflicting save (`save` returned `{ conflict: true }`): fetch the server's
+     * document, merge this session's edits into it (`base` → `document`), load the result with
+     * `apply`, and return the server's version. The controller then saves again on top of it.
+     */
+    onConflict?: (context: EditorRemoteConflictContext<TDocument>) => Promise<EditorRemoteConflictResolution<TDocument>> | EditorRemoteConflictResolution<TDocument>;
+    /** Conflicts resolved in a row before the controller gives up with an error (default `3`). */
+    maxConflictRetries?: number;
+    /**
+     * Optional crash-recovery autosave instance. When a remote save succeeds and no newer
+     * local edits occurred while it was in flight, `autosave.markClean()` is called automatically.
+     */
+    autosave?: Pick<EditorAutosave, "markClean">;
+    /** Wall clock (default `Date.now`). */
+    now?: () => number;
+}
+export interface EditorRemoteSync<TDocument = unknown, TDiff = unknown> {
+    /** Current local version number. */
+    version(): number;
+    /** Last version confirmed saved by the remote server. */
+    savedVersion(): number;
+    /** Whether local changes are waiting to be saved or currently saving. */
+    dirty(): boolean;
+    /** Current sync status snapshot. */
+    status(): EditorRemoteSyncStatus;
+    /** Last committed local baseline snapshot. */
+    baseline(): TDocument;
+    /** Checks the document for changes against `baseline()` (called automatically via `doc.subscribe`). */
+    notify(): boolean;
+    /**
+     * Runs `fn` while suppressing local change detection (so incoming collaborator diffs or
+     * server loads do not echo back a save), then updates `baseline` and advances `version` /
+     * `savedVersion` to `Math.max(version, remoteVersion)`.
+     */
+    applyRemote<TResult>(fn: () => TResult, remoteVersion?: number): TResult;
+    /** Resets the baseline to `doc.getDocument()` and updates `version` / `savedVersion`. */
+    resetBaseline(remoteVersion?: number): void;
+    /** Cancels any debounce timer and immediately saves pending changes. */
+    flush(): Promise<boolean>;
+    /** Resolves when any pending or in-flight save has settled. */
+    whenIdle(): Promise<void>;
+    /** Subscribes to status changes. */
+    subscribe(listener: (status: EditorRemoteSyncStatus) => void): () => void;
+    /** Cancels timers and unsubscribes from `doc`, without discarding in-flight work. */
+    destroy(): void;
+}
+/**
+ * Reactive, version-safe remote persistence controller for an `EditorDocument`.
+ *
+ * - Subscribes to `doc` so every edit (history steps, undo/redo, node drags/resizes, inline
+ *   node data updates, and companion `extras` changes) automatically diffs against the last
+ *   baseline, emits `onLocalChange` for realtime collaboration, and schedules a debounced save.
+ * - Serializes remote `save` calls so two saves never overlap on the wire; edits made while a
+ *   save is in flight are coalesced into a single follow-up save.
+ * - Advances versions monotonically (`Math.max(localVersion, remoteVersion) + 1`), preventing
+ *   version-mismatch wedging when collaborators or server triggers advance the remote version.
+ */
+export declare function createEditorRemoteSync<TDocument = unknown, TDiff = unknown>(doc: EditorDocument<TDocument>, options: EditorRemoteSyncOptions<TDocument, TDiff>): EditorRemoteSync<TDocument, TDiff>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.278.0",
+  "version": "0.279.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",