@pixerate/editor 0.23.0 → 0.24.0

package/dist/persistence/index.d.ts

@@ -0,0 +1,347 @@
+export { J as JsonObject, L as LoadDocumentOptions, a as LoadDocumentResult, b as LoadReport, c as LoadSectionsOptions, d as LoadSectionsResult, M as MigrateOptions, e as MigrateResult, f as MigrationStep, R as ReadOnlyReason, S as SectionProblem, g as SectionSpec, h as SectionSpecs, i as createLoadReport, j as hasLoadProblems, l as loadDocument, k as loadSections, m as migrateDocument } from '../migrate-iTlm3a8h.js';
+
+/**
+ * What the caller should do now (see `RecoveryPolicy.tick`).
+ *
+ * - `writeSnapshot`: write the snapshot and a dirty meta for `revision`, then report with `written`.
+ * - `writeClean`: write a clean meta (retire the snapshot), then report with `cleaned`.
+ * - `wakeAfter`: nothing now; tick again after `delay` (same unit as `now`).
+ */
+type RecoveryAction = {
+    type: "nothing";
+} | {
+    type: "writeSnapshot";
+    revision: number;
+} | {
+    type: "writeClean";
+} | {
+    type: "wakeAfter";
+    delay: number;
+};
+interface RecoveryPolicyOptions {
+    /**
+     * Minimum time between snapshots of a changing document, in the unit of `now`
+     * (default 5000, i.e. milliseconds).
+     */
+    interval?: number;
+    /**
+     * Wait before retrying after the `failures`-th consecutive failed write
+     * (default: `interval`, as in FilmCraft). Use `exponentialBackoff` for doubling delays.
+     */
+    retryDelay?: (failures: number) => number;
+}
+interface RecoveryTickOptions {
+    /** Ignore the interval and any retry wait (e.g. on `pagehide`). */
+    force?: boolean;
+}
+interface RecoveryPolicy {
+    /** Called whenever something may have changed, with the revisions and the current time. */
+    tick(now: number, revision: number, savedRevision: number, options?: RecoveryTickOptions): RecoveryAction;
+    /** The snapshot write for `revision` finished. */
+    written(revision: number, ok: boolean, now: number): void;
+    /** The clean-meta write finished. */
+    cleaned(ok: boolean, now: number): void;
+    /** Whether this session wrote a dirty snapshot that is not retired yet. */
+    readonly ownsSnapshot: boolean;
+    /** Consecutive failed writes (reset by a successful one). */
+    readonly failures: number;
+}
+/**
+ * Exponential backoff: `base`, `2·base`, `4·base`, … capped at `max`.
+ * `failures` is 1 for the first failure.
+ */
+declare function exponentialBackoff(failures: number, base?: number, max?: number): number;
+/**
+ * Pure state machine deciding when a crash-recovery snapshot is written or
+ * retired. Deterministic: time is always passed in.
+ *
+ * - A dirty document is snapshotted at most every `interval`, once per revision.
+ *   A write that fails is retried after `retryDelay`, without waiting for another edit.
+ * - The snapshot is marked clean only if this session wrote it. A snapshot left by an
+ *   earlier session (that was not restored) stays dirty, so it can still be recovered.
+ * - An edit made while the clean write is in flight keeps the snapshot owned.
+ */
+declare function createRecoveryPolicy(options?: RecoveryPolicyOptions): RecoveryPolicy;
+
+/**
+ * Key/value storage adapters for autosave and crash recovery. Every adapter is
+ * async, stores strings, feature-detects its backend (an unavailable backend
+ * rejects every call with `StorageUnavailableError` instead of throwing at
+ * construction, so SSR and old browsers are safe) and accepts an injectable
+ * failure mode for tests.
+ */
+type StorageOperation = "get" | "set" | "remove";
+/**
+ * Injected failure: return `true` (or an `Error`) to make that operation fail.
+ * Example: `failure: (op) => op === "set"` simulates a full disk.
+ */
+type StorageFailureMode = (operation: StorageOperation, key: string) => boolean | Error | undefined | void;
+interface StorageAdapter {
+    /** Short backend name, e.g. `"memory"`, `"localStorage"`, `"indexedDB"`, `"opfs"`. */
+    readonly kind: string;
+    /** Whether the backend was found. When `false`, every call rejects. */
+    readonly available: boolean;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+interface StorageAdapterOptions {
+    failure?: StorageFailureMode;
+}
+declare class StorageUnavailableError extends Error {
+    constructor(kind: string);
+}
+declare class InjectedStorageError extends Error {
+    constructor(operation: StorageOperation, key: string);
+}
+/** Wraps an adapter so `failure` can make any of its operations fail. */
+declare function withStorageFailures(inner: StorageAdapter, failure: StorageFailureMode): StorageAdapter;
+interface MemoryStorage extends StorageAdapter {
+    /** The underlying map (inspect it in tests). */
+    readonly entries: Map<string, string>;
+}
+/** In-memory storage (tests, SSR, or a session-only fallback). */
+declare function createMemoryStorage(options?: StorageAdapterOptions & {
+    initial?: Record<string, string>;
+}): MemoryStorage;
+/** Minimal `Storage` surface used by the localStorage adapter. */
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface LocalStorageAdapterOptions extends StorageAdapterOptions {
+    /** Storage to use (default `globalThis.localStorage`, e.g. pass `sessionStorage`). */
+    storage?: WebStorageLike;
+}
+/** Whether `localStorage` can be used (it throws when site data is blocked). */
+declare function isLocalStorageAvailable(): boolean;
+/**
+ * `localStorage` adapter; every key is prefixed with `prefix`. Writes are
+ * synchronous under the hood, so they complete even inside `pagehide`.
+ * A full quota rejects the `set` (`QuotaExceededError`).
+ */
+declare function createLocalStorageAdapter(prefix?: string, options?: LocalStorageAdapterOptions): StorageAdapter;
+/** Minimal `IDBFactory` surface (the real `indexedDB`, or a fake in tests). */
+interface IdbFactoryLike {
+    open(name: string, version?: number): any;
+}
+interface IndexedDbAdapterOptions extends StorageAdapterOptions {
+    /** Object store name (default `"kv"`). */
+    store?: string;
+    /** Factory to use (default `globalThis.indexedDB`). */
+    indexedDB?: IdbFactoryLike;
+}
+/** Whether `indexedDB` exists in this environment. */
+declare function isIndexedDbAvailable(): boolean;
+/**
+ * IndexedDB adapter: one database `name` with a single key/value object store.
+ * A `set` resolves when its transaction completes (not merely when the request
+ * succeeds), so a resolved write is durable.
+ */
+declare function createIndexedDbAdapter(name?: string, options?: IndexedDbAdapterOptions): StorageAdapter;
+/** Minimal `FileSystemDirectoryHandle` surface used by the OPFS adapter. */
+interface OpfsDirectoryLike {
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<OpfsDirectoryLike>;
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<OpfsFileLike>;
+    removeEntry(name: string): Promise<void>;
+}
+interface OpfsFileLike {
+    getFile(): Promise<{
+        text(): Promise<string>;
+    }>;
+    createWritable?(): Promise<{
+        write(data: string): Promise<void>;
+        close(): Promise<void>;
+    }>;
+    /** Rename in place (Chromium, Safari). Used for temp-file + rename writes. */
+    move?(name: string): Promise<void>;
+}
+interface OpfsAdapterOptions extends StorageAdapterOptions {
+    /** Root directory (default `navigator.storage.getDirectory()`). */
+    root?: () => Promise<OpfsDirectoryLike>;
+    /** Force the write-then-pointer-swap strategy even when `move` exists. */
+    disableRename?: boolean;
+}
+/** Whether the Origin Private File System exists (`navigator.storage.getDirectory`). */
+declare function isOpfsAvailable(): boolean;
+/**
+ * Origin Private File System adapter. Values are files in `dir` (created on
+ * demand), named after the URI-encoded key.
+ *
+ * Writes never leave a half-written value behind: where file handles support
+ * `move`, the value is written to `<file>.tmp` and renamed over `<file>`;
+ * otherwise it alternates between two slots (`<file>.a` / `<file>.b`) and then
+ * swaps a pointer file (`<file>.ptr`), so a crash mid-write keeps the previous
+ * value. Main-thread writes need `createWritable` (missing in some Safari
+ * versions); without it, `set` rejects with `StorageUnavailableError`.
+ */
+declare function createOpfsAdapter(dir?: string, options?: OpfsAdapterOptions): StorageAdapter;
+
+type AutosaveStatus = "idle" | "dirty" | "saving" | "saved" | "error";
+interface AutosaveStatusInfo {
+    status: AutosaveStatus;
+    /** Last write error (while `status` is `"error"`). */
+    error: unknown;
+    /** Consecutive failed writes. */
+    failures: number;
+    /** When the next attempt is due (`now()` units), while waiting. */
+    nextAttemptAt: number | null;
+    /** When the last snapshot was written (`now()` units). */
+    lastSavedAt: number | null;
+    /** Whether `ready()` was called. */
+    ready: boolean;
+}
+/** Stored next to the snapshot (`<key>:meta`). */
+interface RecoveryMeta {
+    dirty: boolean;
+    revision?: number;
+    /** `Date.now()` of the write. */
+    time?: number;
+    /** Document name, for the "Restore unsaved changes from …?" prompt. */
+    name?: string;
+}
+interface AutosaveRecovery<T = unknown> {
+    /** The parsed snapshot (`undefined` when `deserialize` threw; see `error`). */
+    snapshot: T | undefined;
+    /** The stored text. */
+    text: string;
+    meta: RecoveryMeta & {
+        dirty: true;
+    };
+    error?: unknown;
+}
+interface AutosaveControllerOptions<T> {
+    storage: StorageAdapter;
+    /** Snapshot key; the meta lives at `<key>:meta`. */
+    key: string;
+    /** Reads the current document. */
+    getSnapshot: () => T;
+    /** Default `JSON.stringify`. */
+    serialize?: (snapshot: T) => string;
+    /** Default `JSON.parse` (used by `checkRecovery`). */
+    deserialize?: (text: string) => T;
+    /** Current document revision; must change on every edit. */
+    revision: () => number;
+    /** Revision of the last explicit save (equal to `revision()` when clean). */
+    savedRevision: () => number;
+    /** Document name stored in the meta. */
+    name?: string | (() => string | undefined);
+    onStatus?: (info: AutosaveStatusInfo) => void;
+    /** Minimum time between snapshots while edits keep coming (default 5000 ms). */
+    interval?: number;
+    /** Quiet time after the last edit before a snapshot is written (default 1000 ms). */
+    debounceMs?: number;
+    /** First retry delay after a failed write; doubles per failure (default 1000 ms). */
+    retryBaseMs?: number;
+    /** Retry delay cap (default 30000 ms). */
+    retryMaxMs?: number;
+    /** Clock for scheduling (default `Date.now`). */
+    now?: () => number;
+    /** Wall clock stored in the meta (default `Date.now`). */
+    wallClock?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: any) => void;
+    /** Start hydrated, i.e. as if `ready()` was already called (default `false`). */
+    ready?: boolean;
+}
+interface AutosaveController<T = unknown> {
+    /** Current status. */
+    getStatus(): AutosaveStatusInfo;
+    /** Listener is called on every status change (not immediately). */
+    subscribe(listener: (info: AutosaveStatusInfo) => void): () => void;
+    /** Call after every change (edit, undo, save). Cheap; the write is scheduled. */
+    notify(): void;
+    /** Lifts the hydration gate: no snapshot is written before this. */
+    ready(): void;
+    readonly isReady: boolean;
+    /**
+     * Writes a snapshot of unsaved changes right away, skipping the debounce, the
+     * interval and retry waits. Use on `pagehide` / `visibilitychange`. Resolves
+     * once the write settled.
+     */
+    flushNow(): Promise<void>;
+    /**
+     * Call after the document was saved (`savedRevision()` now equals
+     * `revision()`): retires the snapshot only if this session wrote it.
+     */
+    markClean(): Promise<void>;
+    /**
+     * A dirty snapshot left by an earlier session, or `null`. Returns `null` once
+     * this session has written its own snapshot.
+     */
+    checkRecovery(): Promise<AutosaveRecovery<T> | null>;
+    /** Deletes an earlier session's snapshot. No-op once this session wrote its own. */
+    discardRecovery(): Promise<boolean>;
+    /** Runs one scheduling step now (normally driven by `notify` and timers). */
+    tick(): void;
+    /** Resolves when no write is in flight. */
+    whenIdle(): Promise<void>;
+    /** Stops all timers. Pending changes are not written; call `flushNow` first. */
+    destroy(): void;
+}
+declare const recoveryMetaKey: (key: string) => string;
+/**
+ * Text for a recovery prompt: "Restore unsaved changes from <time>?" (the
+ * React and Svelte `RecoveryPrompt` components use it).
+ */
+declare function formatRecoveryMessage(meta: Pick<RecoveryMeta, "time">, formatTime?: (time: number) => string): string;
+/**
+ * Debounced autosave of crash-recovery snapshots.
+ *
+ * - Hydration gate: nothing is written until `ready()`, so loading a document
+ *   (or deciding about a recovered one) never overwrites the previous session's snapshot.
+ * - A snapshot is written `debounceMs` after the last edit, and at least every
+ *   `interval` while edits keep coming; never twice for one revision.
+ * - Failed writes are retried with exponential backoff (`retryBaseMs` doubling up to
+ *   `retryMaxMs`) without waiting for another edit.
+ * - The snapshot is written before its dirty meta, so the meta never points at a
+ *   missing snapshot. Once saved, the meta is marked clean only if this session
+ *   wrote the snapshot (`createRecoveryPolicy`).
+ */
+declare function createAutosaveController<T>(options: AutosaveControllerOptions<T>): AutosaveController<T>;
+
+/** Anything that notifies on every document change (`HistoryManager` satisfies it). */
+interface RevisionChangeSource {
+    subscribe(listener: (...args: any[]) => void): () => void;
+}
+/** Anything with a dirty flag (`DirtyTracker` and `HistoryDirtyBinding` satisfy it). */
+interface DirtyFlagSource {
+    readonly dirty: boolean;
+    subscribe(listener: (dirty: boolean) => void): () => void;
+}
+interface RevisionTrackerOptions {
+    /** Change notifications (e.g. a `HistoryManager`). Every notification is a new revision. */
+    history?: RevisionChangeSource;
+    /**
+     * Saved-vs-current flag (e.g. `bindDirtyToHistory(...)` or a `DirtyTracker`).
+     * Whenever it reads clean, the current revision counts as saved, so undoing
+     * back to the saved state needs no snapshot. Without it, call `markSaved()`.
+     */
+    dirty?: DirtyFlagSource;
+}
+interface RevisionTracker {
+    /** Bumped on every change. */
+    revision(): number;
+    /** Revision of the last save; equals `revision()` while clean. */
+    savedRevision(): number;
+    /** Records a change made outside `history`. */
+    bump(): void;
+    /** Marks the current revision saved. */
+    markSaved(): void;
+    /** Called after every change, save or dirty flip. */
+    subscribe(listener: () => void): () => void;
+    destroy(): void;
+}
+/**
+ * Derives the `revision` / `savedRevision` pair an autosave controller needs
+ * from a history and a dirty flag (`bindDirtyToHistory` or `DirtyTracker`).
+ * Structural types only, so this entry stays dependency-free.
+ */
+declare function createRevisionTracker(options?: RevisionTrackerOptions): RevisionTracker;
+
+export { type AutosaveController, type AutosaveControllerOptions, type AutosaveRecovery, type AutosaveStatus, type AutosaveStatusInfo, type DirtyFlagSource, type IdbFactoryLike, type IndexedDbAdapterOptions, InjectedStorageError, type LocalStorageAdapterOptions, type MemoryStorage, type OpfsAdapterOptions, type OpfsDirectoryLike, type OpfsFileLike, type RecoveryAction, type RecoveryMeta, type RecoveryPolicy, type RecoveryPolicyOptions, type RecoveryTickOptions, type RevisionChangeSource, type RevisionTracker, type RevisionTrackerOptions, type StorageAdapter, type StorageAdapterOptions, type StorageFailureMode, type StorageOperation, StorageUnavailableError, type WebStorageLike, createAutosaveController, createIndexedDbAdapter, createLocalStorageAdapter, createMemoryStorage, createOpfsAdapter, createRecoveryPolicy, createRevisionTracker, exponentialBackoff, formatRecoveryMessage, isIndexedDbAvailable, isLocalStorageAvailable, isOpfsAvailable, recoveryMetaKey, withStorageFailures };