edytor 0.1.0-next.24 → 0.1.0-next.26

package/README.md

@@ -15,7 +15,7 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **Work in progress.** Edytor is a pre-release (`0.1.0-next.24`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **Work in progress.** Edytor is a pre-release (`0.1.0-next.26`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 

package/dist/cloudflare/DocumentRoom.d.ts

@@ -96,7 +96,9 @@
 import { DurableObject } from 'cloudflare:workers';
 import * as E from '../crdt/index.js';
 import type { PurgeReport } from '../crdt/purge.js';
-import { type HistoryEntry, type HistoryOptions, type KVLike } from './history.js';
+import { type HistoryEntry, type HistoryOptions, type KVLike, type R2BucketLike } from './history.js';
+import { type LockOptions } from './locks.js';
+import { type CommitResult, type ExportedBlocks, type ImportReceipt, type ImportRequest, type LateEditBatch, type MoveNamespace } from './move.js';
 import type { AwarenessEntry, DocumentSemanticsConfig, EdytorDoc, JSONBlock, JSONDoc, YDoc } from '../crdt/index.js';
 /** Under SQLite-backed Durable Objects' 2 MB row cap, with room for the other columns. */
 export declare const DEFAULT_MAX_ROW_BYTES: number;
@@ -162,7 +164,7 @@ export type SavedDocument = {
 };
 /** What `onLoad` may return: JSON, a bare v14 update, or `{ update, replicas }` (a `SavedDocument`). */
 export type LoadedDocument = JSONDoc | Uint8Array | Pick<SavedDocument, 'update' | 'replicas'>;
-/** The header `routeDocumentSocket` sets on an authorized `lastUpdated` probe (H12). */
+/** The header `routeDocumentSocket` sets on an authorized probe: `lastUpdated` (H12) or `snapshot` (P8). */
 export declare const PROBE_HEADER = "X-Edytor-Probe";
 /** The transaction origin of the room's own edits (`transact`, `onLoad` seeds). */
 export declare const ROOM_ORIGIN: unique symbol;
@@ -204,12 +206,24 @@ export type DocumentRoomEnv = {
      * retention, else 30); `off` never purges.
      */
     EDYTOR_PURGE_AFTER_DAYS?: string | number;
-    /** A KV namespace binding: the room keeps its version history there (H11, `history()`). */
-    EDYTOR_HISTORY?: KVLike;
+    /**
+     * Where the room keeps its version history (H11, `history()`): a KV
+     * namespace or an R2 bucket binding, or the string `room` (the room's own
+     * storage, {@link roomHistory}). Unset: no history.
+     */
+    EDYTOR_HISTORY?: KVLike | R2BucketLike | 'room';
     /** Days a version is kept (default 30). */
     EDYTOR_HISTORY_RETENTION_DAYS?: string | number;
     /** The IANA time zone of the history's half-day slots (default `UTC`). */
     EDYTOR_HISTORY_TIME_ZONE?: string;
+    /** Per-block locks (`locks()`): the data key naming a block's owner, e.g. `lockedBy`. Unset: none. */
+    EDYTOR_LOCKS?: string;
+    /**
+     * The namespace of the rooms blocks move to (`rooms()`, H10): the room
+     * forwards late edits of moved blocks there itself. Unset: they wait
+     * for the host's `forwardLateEdits`.
+     */
+    EDYTOR_ROOMS?: MoveNamespace;
 };
 /** What a socket is bound to: its verified user, its replica (Yjs client id), its access. */
 export type SocketIdentity = {
@@ -317,6 +331,25 @@ export type RoomLogEntry = {
     edytor: 'fault';
     reason: 'storage' | 'internal';
     detail: string;
+} | {
+    edytor: 'convert';
+    from: number;
+    to: number;
+    blocks: number;
+    bytes: number;
+} | {
+    edytor: 'move';
+    moveId: string;
+    role: 'out' | 'in';
+    peer: string;
+    blocks: number;
+} | {
+    edytor: 'late';
+    moveId: string;
+    seq: number;
+    edits: number;
+    structural: number;
+    forwarded: boolean;
 };
 /** `pending`: deletes of items the room does not hold yet (they wait for them). */
 type RowKind = 'generation' | 'update' | 'snapshot' | 'pending';
@@ -418,6 +451,19 @@ export type AttachDocumentOptions = {
      * when set (the room then keeps an index of every block's state).
      */
     validate?: (frame: FrameValidation) => boolean | void;
+    /**
+     * Per-block locks (H10, `room.locks`): a block whose data names a user
+     * under `key` (default `lockedBy`) is that user's alone — a frame from
+     * anyone else touching it is denied and compensated, as `validate`'s
+     * denials are ({@link lockedBlocks}). Asked before `validate`.
+     */
+    locks?: LockOptions;
+    /**
+     * The rooms blocks move to (H10, `room.move`): with it, the room forwards
+     * the late edits of blocks it moved out to their destination itself, on
+     * its alarm; without it, they wait for the host's `forwardLateEdits`.
+     */
+    rooms?: () => MoveNamespace | undefined;
     /**
      * The room's log (H14): one entry per compaction, quota hit, denial or
      * fault. Default: `console.log` of the entry as JSON (Workers Logs and
@@ -481,6 +527,10 @@ export declare class AttachedDocument {
     } | {
         kind: 'restored';
         records: number;
+    } | {
+        kind: 'converted';
+        from: number;
+        records: number;
     };
     private nextRecord;
     private updates;
@@ -539,7 +589,13 @@ export declare class AttachedDocument {
     private readonly epochsTable;
     private readonly editorsTable;
     private readonly restoreTable;
+    private readonly movesTable;
+    private readonly lateTable;
+    /** The blocks moved out and watched for late edits, by id → their move (`null`: not read yet). */
+    private watched;
     private _lookups;
+    private readonly tablePrefix;
+    private _validator;
     private _history;
     constructor(ctx: DurableObjectState, options?: AttachDocumentOptions);
     /**
@@ -651,6 +707,18 @@ export declare class AttachedDocument {
      * engine refuses) is refused for good.
      */
     private load;
+    /**
+     * The generation cutover at load (`room.generation.convert`): the
+     * records of a generation-4 container are read as JSON
+     * (`crdt.generations.previousJSON`), which this generation seeds as
+     * `onLoad`'s JSON is (deterministic: every replica converting the same
+     * state writes the same update), and the container is replaced by it in
+     * one storage transaction: rows, replicas, purge epochs, slot editors
+     * and the stored restore go; the document data, the alarm's due tasks
+     * and `lastUpdated` stay. What a generation-4 client never sent is not
+     * in it; history, attribution and CRDT identity do not cross.
+     */
+    private convert;
     /** The bytes of the stored `pending` records (uncompressed, as every record but a snapshot). */
     private pendingBytes;
     /**
@@ -711,6 +779,11 @@ export declare class AttachedDocument {
     lastUpdated(): number | null;
     /** The room's id: its name (`getByName`), else the object's id. */
     private get roomId();
+    /**
+     * The frame check, resolved at first use: per-block locks (`locks`),
+     * then `validate`; `null` when neither is set (no block index is kept).
+     */
+    private get validator();
     /** The history settings, resolved at first use (`null`: none; an unknown time zone is noted `history`). */
     private get historyConfig();
     /** Days after which deleted content is purged (`null`: never), `room.purge.timing`. */
@@ -750,6 +823,15 @@ export declare class AttachedDocument {
      * room keeps no history.
      */
     listHistory(): Promise<HistoryEntry[]>;
+    /** Every version key the store holds under this room's prefix, page by page. */
+    private storedVersions;
+    /**
+     * The `retention` task (`room.history.retention`), for a store that
+     * expires nothing itself: delete every version past its expiry, then
+     * re-arm at the next one's. A failure is noted `history` and retried
+     * an hour later.
+     */
+    private expireVersions;
     /** Version `key` as JSON (a preview), or `null` when this room holds no such version. */
     readHistory(key: string): Promise<JSONDoc | null>;
     /**
@@ -782,6 +864,77 @@ export declare class AttachedDocument {
      * is released and collected (the next compaction stores it collected).
      */
     private dropRestore;
+    private ensureMoves;
+    /** One move's row. */
+    private moveRow;
+    /** Days a moved-out block is watched for late edits: the purge horizon, else {@link DEFAULT_MOVE_GRACE_DAYS}. */
+    private get graceMs();
+    /**
+     * Export blocks `ids` for a move (`room.move`, step 1): their visible
+     * subtrees as JSON, the outermost only, in document order. Writes
+     * nothing to the document; records the export (`moveId`) for
+     * `commitMove`. Throws when none of them shows.
+     */
+    exportBlocks(ids: string[]): ExportedBlocks;
+    /**
+     * Import a move's blocks (`room.move`, step 2) under `dest.parent` at
+     * `dest.index`, as one room transaction: each keeps its id unless this
+     * document holds it already (then `<id>~<n>`). Idempotent: a second
+     * call with the same `moveId` writes nothing and returns the same ids,
+     * the acknowledgement `commitMove` needs.
+     */
+    importBlocks(request: ImportRequest): ImportReceipt;
+    /**
+     * Commit a move (`room.move`, step 3), with the destination's
+     * acknowledgement: delete the exported blocks with their subtrees, as
+     * one room transaction, and watch them for late edits (`room.move.late`)
+     * for the grace period. Idempotent; `refused` for an unknown or aborted
+     * move.
+     */
+    commitMove(moveId: string, receipt: {
+        to: string;
+        ids: Record<string, string>;
+    }): CommitResult;
+    /** Drop an export that was not committed (`room.move`): the blocks stay. */
+    abortMove(moveId: string): {
+        moveId: string;
+        status: 'applied' | 'noop';
+    };
+    /** The late edits waiting to reach their destination (`room.move.late`), oldest first. */
+    lateEdits(): LateEditBatch[];
+    /** The destination applied a move's late edits through `seq`: they are dropped here. */
+    ackLateEdits(moveId: string, seq: number): void;
+    /**
+     * Apply a batch of late edits of a move this room imported
+     * (`room.move.late`): each block's content and data merged three ways
+     * into what it holds now (what was written here since stays), as one
+     * room transaction. Idempotent by sequence number; a block that no
+     * longer shows is skipped. Returns the last sequence applied.
+     */
+    applyLateEdits(batch: LateEditBatch): {
+        applied: number;
+        skipped: string[];
+    };
+    /** One block's late edit, merged into what it holds (inside a room transaction). */
+    private mergeLateEdit;
+    /** The registry entries carrying a `del.<marker>` mark written between clocks `c0` and `c1`. */
+    private markedBetween;
+    /** The moved-out blocks watched for late edits (`room.move.late`), by id → their move. */
+    private watchedBlocks;
+    /** A transaction that changed a watched block marks its move dirty (inside the `update` emit: no doc write). */
+    private noteLateEdits;
+    /**
+     * The `forward` task (`room.move.late`): turn each dirty move's changes
+     * into a batch of late edits — read on a copy of the document with the
+     * move's own deletes left out — then forward the waiting batches to
+     * their destinations (with `rooms`), and stop watching moves past the
+     * grace period. A forward that fails runs again a minute later.
+     */
+    private forwardMoves;
+    /** The document's blocks as they show without the deletes of `moves`' commits: a copy, read once. */
+    private withoutMoveDeletes;
+    /** One dirty move's changes since its last batch, as a new batch of late edits (or a report). */
+    private collectLateEdits;
     /**
      * The purge task, also over RPC (`room.purge.timing`): record an epoch
      * (the state vector, now) when the document changed since the last one,
@@ -1046,10 +1199,23 @@ export declare class DocumentRoom<Env = DocumentRoomEnv> extends DurableObject<E
     protected semantics(): DocumentSemanticsConfig;
     /**
      * Version history — see {@link AttachDocumentOptions.history}. Default:
-     * the `EDYTOR_HISTORY` KV binding, with `EDYTOR_HISTORY_RETENTION_DAYS`
+     * `EDYTOR_HISTORY` — a KV namespace binding ({@link kvHistory}), an R2
+     * bucket binding ({@link r2History}) or the string `room` (the room's
+     * own storage, {@link roomHistory}) — with `EDYTOR_HISTORY_RETENTION_DAYS`
      * and `EDYTOR_HISTORY_TIME_ZONE`; none without it. Read once, at first use.
      */
     protected history(): HistoryOptions | undefined;
+    /**
+     * Per-block locks — see {@link AttachDocumentOptions.locks}. Default: the
+     * `EDYTOR_LOCKS` var names the data key (`{ key }`); none without it.
+     * Read once, at the first frame.
+     */
+    protected locks(): LockOptions | undefined;
+    /**
+     * The rooms blocks move to — see {@link AttachDocumentOptions.rooms}.
+     * Default: the `EDYTOR_ROOMS` binding; none without it.
+     */
+    protected rooms(): MoveNamespace | undefined;
     /** The room's clock — see {@link AttachDocumentOptions.now}. */
     protected now(): number;
     fetch(request: Request): Promise<Response>;
@@ -1074,6 +1240,29 @@ export declare class DocumentRoom<Env = DocumentRoomEnv> extends DurableObject<E
     }>;
     /** The version writes in flight, also over RPC — see {@link AttachedDocument.historyWritten}. */
     historyWritten(): Promise<void>;
+    /** Export blocks for a move, also over RPC — see {@link AttachedDocument.exportBlocks}. */
+    exportBlocks(ids: string[]): ExportedBlocks;
+    /** Import a move's blocks, also over RPC — see {@link AttachedDocument.importBlocks}. */
+    importBlocks(request: ImportRequest): ImportReceipt;
+    /** Commit a move, also over RPC — see {@link AttachedDocument.commitMove}. */
+    commitMove(moveId: string, receipt: {
+        to: string;
+        ids: Record<string, string>;
+    }): CommitResult;
+    /** Abort an export, also over RPC — see {@link AttachedDocument.abortMove}. */
+    abortMove(moveId: string): {
+        moveId: string;
+        status: 'applied' | 'noop';
+    };
+    /** The late edits waiting, also over RPC — see {@link AttachedDocument.lateEdits}. */
+    lateEdits(): LateEditBatch[];
+    /** Drop forwarded late edits, also over RPC — see {@link AttachedDocument.ackLateEdits}. */
+    ackLateEdits(moveId: string, seq: number): void;
+    /** Apply late edits, also over RPC — see {@link AttachedDocument.applyLateEdits}. */
+    applyLateEdits(batch: LateEditBatch): {
+        applied: number;
+        skipped: string[];
+    };
     /** Run the purge task now, also over RPC — see {@link AttachedDocument.purge}. */
     purge(): (PurgeReport & {
         horizon: number;