@liveblocks/server 1.5.0 → 1.6.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Json, asPos, IUserInfo, SerializedCrdt, JsonObject, DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, Brand, SerializedRootObject, SerializedChild, StorageNode, Awaitable, CompactNode, PlainLsonObject, NodeMap as NodeMap$1, NodeStream as NodeStream$1, ClientWireOp, ServerMsg as ServerMsg$1, BaseUserMeta, IgnoredOp } from '@liveblocks/core';
+import { Json, asPos, IUserInfo, SerializedCrdt, JsonObject, DistributiveOmit, SetParentKeyOp, DeleteCrdtOp, ClientMsg as ClientMsg$1, Brand, SerializedRootObject, SerializedChild, StorageNode, CompactNode, PlainLsonObject, NodeMap as NodeMap$1, NodeStream as NodeStream$1, ClientWireOp, CreateOp, HasOpId, ServerMsg as ServerMsg$1, BaseUserMeta, IgnoredOp } from '@liveblocks/core';
 export { BroadcastEventClientMsg, ClientMsg, ClientWireOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, DeleteCrdtOp, DeleteObjectKeyOp, FetchStorageClientMsg, FetchYDocClientMsg, HasOpId, IgnoredOp, Op, RoomStateServerMsg, ServerMsg, ServerWireOp, SetParentKeyOp, UpdateObjectOp, UpdatePresenceClientMsg, UpdateStorageClientMsg, UpdateYDocClientMsg } from '@liveblocks/core';
 import * as decoders from 'decoders';
 import { Decoder } from 'decoders';
@@ -521,96 +521,6 @@ interface IServerWebSocket {
     getLastPongTimestamp?(): Date | null;
 }
 
-/**
- * Copyright (c) Liveblocks Inc.
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
-
-declare enum LogLevel {
-    DEBUG = 0,
-    INFO = 1,
-    WARNING = 2,
-    ERROR = 3
-}
-/**
- * Inherit from this abstract log target to implement your own custom
- * LogTarget.
- */
-declare abstract class LogTarget {
-    #private;
-    readonly level: LogLevel;
-    constructor(level?: LogLevel | keyof typeof LogLevelNames);
-    /** Helper for formatting a log level */
-    protected formatLevel(level: LogLevel): string;
-    /** Helper for formatting an Arg */
-    protected formatArg(arg: string | Error): string;
-    /**
-     * Helper for formatting a Context. Override this in a subclass to change the
-     * formatting.
-     */
-    protected formatContextImpl(context: JsonObject): string;
-    /**
-     * Helper for formatting a Context. Will only compute the string once for
-     * every Context instance, and keep its computed string value cached for
-     * performance.
-     */
-    protected formatContext(context: JsonObject): string;
-    /**
-     * Implement this in a concrete subclass. The goal is to do whatever to log
-     * the given log level, context, and log arg. You'll typically want to
-     * utilize the pre-defined helper methods .formatContext() and .formatArg()
-     * to implement this.
-     */
-    abstract log(level: LogLevel, context: JsonObject, arg: string | Error): void;
-}
-declare class ConsoleTarget extends LogTarget {
-    log(level: LogLevel, context: JsonObject, arg: string | Error): void;
-}
-declare const LogLevelNames: {
-    readonly debug: LogLevel.DEBUG;
-    readonly info: LogLevel.INFO;
-    readonly warning: LogLevel.WARNING;
-    readonly error: LogLevel.ERROR;
-};
-type LogFn = (arg: string | Error) => void;
-/**
- * Structured logger with configurable log targets.
- */
-declare class Logger {
-    readonly debug: LogFn;
-    readonly info: LogFn;
-    readonly warn: LogFn;
-    readonly error: LogFn;
-    readonly o: {
-        readonly debug?: LogFn;
-        readonly info?: LogFn;
-        readonly warn?: LogFn;
-        readonly error?: LogFn;
-    };
-    private readonly _context;
-    private readonly _targets;
-    constructor(target?: LogTarget | readonly LogTarget[], context?: JsonObject);
-    /**
-     * Creates a new Logger instance with the given extra context applied. All
-     * log calls made from that new Logger will carry all current _and_ the extra
-     * context, with the extra context taking precedence. Assign an explicit
-     * `undefined` value to a key to "remove" it from the context.
-     */
-    withContext(extra: JsonObject): Logger;
-}
-
 /**
  * Copyright (c) Liveblocks Inc.
  *
@@ -697,14 +607,20 @@ interface IReadableSnapshot {
     destroy(): void;
 }
 /**
- * CRDT node storage with synchronous reads and async persistence.
+ * Persistent storage backend for Liveblocks room data: CRDT nodes, metadata,
+ * actor IDs, and Yjs updates.
+ *
+ * The node methods will initialize lazily (but synchronously): on first node
+ * access, the driver loads/repairs its node state internally, at most once per
+ * instance. DANGEROUSLY_reset_nodes() invalidates that state, after which the
+ * next access transparently re-runs the load/repair sanitization.
  *
  * INVARIANTS:
  * - A virtual root node `{type: OBJECT, data: {}}` always exists.
  * - All non-root nodes have parentId and parentKey forming a tree.
- * - Reads reflect writes immediately, before the returned Promise resolves.
+ * - Reads reflect writes immediately.
  */
-interface IStorageDriverNodeAPI {
+interface IStorageDriver {
     /**
      * Return the node with the given id, or undefined if no such node exists.
      * Must always return a valid root node for id="root", even if empty.
@@ -769,18 +685,18 @@ interface IStorageDriverNodeAPI {
      * If allowOverwrite=true: replace any existing node at this id, deleting its
      * entire subtree if it has children.
      */
-    set_child(id: string, node: SerializedChild, allowOverwrite?: boolean): Awaitable<void>;
+    set_child(id: string, node: SerializedChild, allowOverwrite?: boolean): void;
     /**
      * Change a node's parentKey, effectively repositioning the node within its
      * parent. The new position must be free.
      * Throw if another node already occupies (parentId, newPos).
      */
-    move_sibling(id: string, newPos: Pos): Awaitable<void>;
+    move_sibling(id: string, newPos: Pos): void;
     /**
      * Delete a node and its entire subtree recursively.
      * Ignore if id="root" (root is immortal).
      */
-    delete_node(id: string): Awaitable<void>;
+    delete_node(id: string): void;
     /**
      * Delete a key from node `id`. Handle two cases:
      *
@@ -790,7 +706,7 @@ interface IStorageDriverNodeAPI {
      *
      * No-op if neither applies or if the node doesn't exist.
      */
-    delete_child_key(id: string, key: string): Awaitable<void>;
+    delete_child_key(id: string, key: string): void;
     /**
      * Replace the data object of an OBJECT node.
      *
@@ -799,7 +715,7 @@ interface IStorageDriverNodeAPI {
      * If allowOverwrite=true: first delete any conflicting children (and their
      * entire subtrees), then set the data.
      */
-    set_object_data(id: string, data: JsonObject, allowOverwrite?: boolean): Awaitable<void>;
+    set_object_data(id: string, data: JsonObject, allowOverwrite?: boolean): void;
     /**
      * Return a readable snapshot of the storage tree.
      *
@@ -808,45 +724,39 @@ interface IStorageDriverNodeAPI {
      * access.
      */
     get_snapshot(lowMemory?: boolean): IReadableSnapshot;
-}
-/**
- * Persistent storage backend for Liveblocks room data: CRDT nodes, metadata,
- * actor IDs, and Yjs updates. All methods may be async.
- */
-interface IStorageDriver {
     /**
-     * Load all nodes from storage, validate/repair corruptions (orphans, cycles,
-     * conflicting siblings), and return an IStorageDriverNodeAPI for operations.
-     *
-     * After DANGEROUSLY_reset_nodes(), any previously-loaded instance is
-     * invalid—must call this again to get a fresh one.
+     * Release any lazily-initialized in-memory node state (caches/indexes
+     * built on first node access), freeing it up for garbage collection.
+     * Persisted data is NOT touched — the next node access transparently
+     * re-initializes. (Contrast with DANGEROUSLY_reset_nodes(), which deletes
+     * the actual data.)
      */
-    load_nodes_api(logger: Logger): Awaitable<IStorageDriverNodeAPI>;
+    reinitialize(): void;
     /**
      * Delete all CRDT nodes and replace them with the given document.
      * Does NOT affect metadata, actor IDs, or Yjs updates.
-     * Invalidates any previously-loaded IStorageDriverNodeAPI.
+     * Invalidates the driver's internally loaded node state.
      *
      * Pass `{ liveblocksType: "LiveObject", data: {} }` to reset to an empty root.
      */
-    DANGEROUSLY_reset_nodes(doc: PlainLsonObject): Awaitable<void>;
+    DANGEROUSLY_reset_nodes(doc: PlainLsonObject): void;
     /**
      * Return the value for `key`, or undefined if not set.
      */
-    get_meta(key: string): Awaitable<Json | undefined>;
+    get_meta(key: string): Json | undefined;
     /**
      * Store `value` under `key`. Overwrite any existing value.
      */
-    put_meta(key: string, value: Json): Awaitable<void>;
+    put_meta(key: string, value: Json): void;
     /**
      * Delete the value under `key`. No-op if not set.
      */
-    delete_meta(key: string): Awaitable<void>;
+    delete_meta(key: string): void;
     /**
      * Return a unique actor ID. Each call must return a distinct integer ≥ 0.
      * Concurrent calls must never return duplicates.
      */
-    next_actor(): Awaitable<number>;
+    next_actor(): number;
     /**
      * If defined, called once before each storage mutation batch. Can be used by
      * the driver to more efficiently implement snapshot isolation.
@@ -855,42 +765,42 @@ interface IStorageDriver {
     /**
      * Return all Yjs updates for docId as [key, data] pairs. Return empty if none.
      */
-    iter_y_updates(docId: YDocId): Awaitable<Iterable<[string, Uint8Array]>>;
+    iter_y_updates(docId: YDocId): Iterable<[string, Uint8Array]>;
     /**
      * Store a Yjs update under (docId, key). Overwrite if key exists.
      */
-    write_y_updates(docId: YDocId, key: string, data: Uint8Array): Awaitable<void>;
+    write_y_updates(docId: YDocId, key: string, data: Uint8Array): void;
     /**
      * Delete the specified keys for docId.
      */
-    delete_y_updates(docId: YDocId, keys: string[]): Awaitable<void>;
+    delete_y_updates(docId: YDocId, keys: string[]): void;
     /**
      * Delete ALL Yjs updates across ALL documents.
      * @private Test-only: never use in production.
      */
-    DANGEROUSLY_wipe_all_y_updates(): Awaitable<void>;
+    DANGEROUSLY_wipe_all_y_updates(): void;
     /**
      * List all leased sessions.
      * Note: Does NOT filter by expiration - returns all stored sessions.
      * Expiration logic is handled at the Room.ts level.
      */
-    list_leased_sessions(): Awaitable<Iterable<[sessionId: string, session: LeasedSession]>>;
+    list_leased_sessions(): Iterable<[sessionId: string, session: LeasedSession]>;
     /**
      * Get a specific leased session by session ID.
      * Note: Does NOT check expiration - returns the stored session if it exists.
      * Expiration logic is handled at the Room.ts level.
      */
-    get_leased_session(sessionId: string): Awaitable<LeasedSession | undefined>;
+    get_leased_session(sessionId: string): LeasedSession | undefined;
     /**
      * Create or update a leased session.
      * Note: This is a full replace operation - the caller is responsible for
      * merging/patching presence if needed.
      */
-    put_leased_session(session: LeasedSession): Awaitable<void>;
+    put_leased_session(session: LeasedSession): void;
     /**
      * Delete a leased session by session ID.
      */
-    delete_leased_session(sessionId: string): Awaitable<void>;
+    delete_leased_session(sessionId: string): void;
     /**
      * Return the number of storage rows written since last call to this method,
      * and reset the counter.
@@ -900,41 +810,41 @@ interface IStorageDriver {
      * List feeds with pagination, filtering, and metadata querying.
      * Feeds are sorted by createdAt descending (newest first).
      */
-    list_feeds(options?: ListFeedsOptions): Awaitable<ListFeedsResult>;
+    list_feeds(options?: ListFeedsOptions): ListFeedsResult;
     /**
      * Get a specific feed by feed ID.
      * Returns feed metadata only (without messages).
      * Use list_feed_messages to retrieve messages for this feed.
      * Returns undefined if the feed doesn't exist.
      */
-    get_feed(feedId: string): Awaitable<Feed | undefined>;
+    get_feed(feedId: string): Feed | undefined;
     /**
      * Create a new feed.
      * If feedId already exists, throws an error.
      */
-    create_feed(feed: Feed): Awaitable<void>;
+    create_feed(feed: Feed): void;
     /**
      * Update a feed's metadata.
      * The feed must exist, otherwise throws an error.
      */
-    update_feed_metadata(feedId: string, metadata: Json): Awaitable<void>;
+    update_feed_metadata(feedId: string, metadata: Json): void;
     /**
      * Delete a feed by feed ID.
      * Also deletes all messages associated with the feed (via CASCADE).
      * No-op if feed doesn't exist.
      */
-    delete_feed(feedId: string): Awaitable<void>;
+    delete_feed(feedId: string): void;
     /**
      * List feed messages for a feed with pagination.
      * Messages are sorted by createdAt descending (newest first).
      */
-    list_feed_messages(feedId: string, options?: ListFeedMessagesOptions): Awaitable<ListFeedMessagesResult>;
+    list_feed_messages(feedId: string, options?: ListFeedMessagesOptions): ListFeedMessagesResult;
     /**
      * Add a message to a feed.
      * The message must have id, createdAt, and updatedAt already set (handled by Room layer).
      * The feed must exist, otherwise throws an error.
      */
-    add_feed_message(feedId: string, message: FeedMessage): Awaitable<void>;
+    add_feed_message(feedId: string, message: FeedMessage): void;
     /**
      * Update a feed message's data.
      * Returns the updated message.
@@ -942,12 +852,12 @@ interface IStorageDriver {
      * If timestamp is not provided, current server time is used.
      * Messages are only updated if the provided timestamp is greater than or equal to the stored updatedAt.
      */
-    update_feed_message(feedId: string, messageId: string, data: Json, timestamp?: number): Awaitable<FeedMessage>;
+    update_feed_message(feedId: string, messageId: string, data: Json, timestamp?: number): FeedMessage;
     /**
      * Delete a feed message.
      * The feed and message must exist, otherwise throws an error.
      */
-    delete_feed_message(feedId: string, messageId: string): Awaitable<void>;
+    delete_feed_message(feedId: string, messageId: string): void;
 }
 
 /**
@@ -1093,10 +1003,10 @@ declare function makeInMemorySnapshot(values: NodeMap$1 | NodeStream$1): IReadab
  */
 
 interface MetadataDB {
-    get(key: string): Promise<Json | undefined>;
-    get<T>(decoder: Decoder<T>, key: string): Promise<T | undefined>;
-    put(key: string, value: Json): Awaitable<void>;
-    delete(key: string): Awaitable<void>;
+    get(key: string): Json | undefined;
+    get<T>(decoder: Decoder<T>, key: string): T | undefined;
+    put(key: string, value: Json): void;
+    delete(key: string): void;
 }
 /**
  * Returns a thin wrapper around an IStorageDriver to provide MetadataDB
@@ -1121,7 +1031,108 @@ declare function makeMetadataDB(driver: IStorageDriver): MetadataDB;
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 
-type ApplyOpResult = OpAccepted | OpIgnored;
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARNING = 2,
+    ERROR = 3
+}
+/**
+ * Inherit from this abstract log target to implement your own custom
+ * LogTarget.
+ */
+declare abstract class LogTarget {
+    #private;
+    readonly level: LogLevel;
+    constructor(level?: LogLevel | keyof typeof LogLevelNames);
+    /** Helper for formatting a log level */
+    protected formatLevel(level: LogLevel): string;
+    /** Helper for formatting an Arg */
+    protected formatArg(arg: string | Error): string;
+    /**
+     * Helper for formatting a Context. Override this in a subclass to change the
+     * formatting.
+     */
+    protected formatContextImpl(context: JsonObject): string;
+    /**
+     * Helper for formatting a Context. Will only compute the string once for
+     * every Context instance, and keep its computed string value cached for
+     * performance.
+     */
+    protected formatContext(context: JsonObject): string;
+    /**
+     * Implement this in a concrete subclass. The goal is to do whatever to log
+     * the given log level, context, and log arg. You'll typically want to
+     * utilize the pre-defined helper methods .formatContext() and .formatArg()
+     * to implement this.
+     */
+    abstract log(level: LogLevel, context: JsonObject, arg: string | Error): void;
+}
+declare class ConsoleTarget extends LogTarget {
+    log(level: LogLevel, context: JsonObject, arg: string | Error): void;
+}
+declare const LogLevelNames: {
+    readonly debug: LogLevel.DEBUG;
+    readonly info: LogLevel.INFO;
+    readonly warning: LogLevel.WARNING;
+    readonly error: LogLevel.ERROR;
+};
+type LogFn = (arg: string | Error) => void;
+/**
+ * Structured logger with configurable log targets.
+ */
+declare class Logger {
+    readonly debug: LogFn;
+    readonly info: LogFn;
+    readonly warn: LogFn;
+    readonly error: LogFn;
+    readonly o: {
+        readonly debug?: LogFn;
+        readonly info?: LogFn;
+        readonly warn?: LogFn;
+        readonly error?: LogFn;
+    };
+    private readonly _context;
+    private readonly _targets;
+    constructor(target?: LogTarget | readonly LogTarget[], context?: JsonObject);
+    /**
+     * Creates a new Logger instance with the given extra context applied. All
+     * log calls made from that new Logger will carry all current _and_ the extra
+     * context, with the extra context taking precedence. Assign an explicit
+     * `undefined` value to a key to "remove" it from the context.
+     */
+    withContext(extra: JsonObject): Logger;
+}
+
+/**
+ * Copyright (c) Liveblocks Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * The three possible outcomes of applying a client op. They differ along
+ * when the op (first) changed storage state, who hears about it, and what
+ * gets sent back to the originating client:
+ *
+ * |             | state change | fan out to others | reply to sender  |
+ * |-------------|--------------|-------------------|------------------|
+ * | OpAccepted  | now          | yes               | ack echo (+ fix) |
+ * | OpRectified | in the past  | no                | ack echo + fix   |
+ * | OpIgnored   | never        | no                | bare (H)Ack      |
+ */
+type ApplyOpResult = OpAccepted | OpIgnored | OpRectified;
 type OpAccepted = {
     action: "accepted";
     op: ClientWireOp;
@@ -1131,24 +1142,32 @@ type OpIgnored = {
     action: "ignored";
     ignoredOpId?: string;
 };
-declare class Storage {
-    private readonly coreDriver;
-    private _loadedDriver;
-    constructor(coreDriver: IStorageDriver);
-    get loadedDriver(): IStorageDriverNodeAPI;
-    raw_iter_nodes(): Awaitable<Iterable<[string, SerializedCrdt]>>;
+type OpRectified = {
+    action: "rectified";
+    /**
+     * Echo of the client's op, with the stored, authoritative parentKey. Sent
+     * back to the originating client as the acknowledgement, instead of the
+     * bare (H)Ack. Used for re-sent CREATE ops whose node the server already
+     * stored: the echo carries the authoritative position, so the client can
+     * correct any optimistic local position it may have predicted while the op
+     * was pending. Never fanned out to others: they already received the op
+     * when it was originally accepted.
+     */
+    ackOp: CreateOp & HasOpId;
     /**
-     * Load the room data from object storage into memory. Persisted room
-     * data consists of the main node map, which represents the Liveblocks
-     * Storage tree, and special keys where we store usage metrics, or room
-     * metadata.
+     * A corrective op to send back to the originating client, stating that
+     * same authoritative position (see ackOp).
      */
-    load(logger: Logger): Promise<void>;
-    unload(): void;
+    fix: FixOp;
+};
+declare class Storage {
+    readonly driver: IStorageDriver;
+    constructor(driver: IStorageDriver);
+    raw_iter_nodes(): Iterable<[string, SerializedCrdt]>;
     /**
      * Applies a batch of Ops.
      */
-    applyOps(ops: ClientWireOp[]): Promise<ApplyOpResult[]>;
+    applyOps(ops: ClientWireOp[]): ApplyOpResult[];
     /**
      * Applies a single Op.
      */
@@ -1228,41 +1247,46 @@ declare class Storage {
 declare class YjsStorage {
     private readonly driver;
     private readonly updateCountThreshold;
-    private readonly doc;
+    /**
+     * The root Y.Doc instance, which may not have been hydrated from storage
+     * yet. Use getRootDoc() instead, which lazily hydrates it on first access —
+     * only touch this field directly when the unhydrated instance is fine
+     * (e.g. identity checks, subdoc traversal).
+     */
+    private readonly rawRootDoc;
     private readonly lastSnapshotById;
-    private readonly initPromisesById;
+    private readonly docsById;
     private readonly storedKeysById;
     constructor(driver: IStorageDriver, updateCountThreshold?: number);
-    getYDoc(logger: Logger, docId: YDocId): Promise<Y.Doc>;
+    getYDoc(logger: Logger, docId: YDocId): Y.Doc;
+    /**
+     * Returns the root Y.Doc, lazily loading it from storage first if it
+     * hasn't been loaded yet during this instance's lifetime.
+     */
+    private getRootDoc;
     /**
      * If passed a state vector, an update with diff will be returned, if not the entire doc is returned.
      *
      * @param stateVector a base64 encoded target state vector created by running Y.encodeStateVector(Doc) on the client
      * @returns a base64 encoded array of YJS updates
      */
-    getYDocUpdate(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<string | null>;
-    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<Uint8Array<ArrayBuffer> | null>;
-    getYStateVector(logger: Logger, guid?: Guid): Promise<string | null>;
+    getYDocUpdate(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): string | null;
+    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Uint8Array<ArrayBuffer> | null;
+    getYStateVector(logger: Logger, guid?: Guid): string | null;
     getSnapshotHash(logger: Logger, options: {
         guid?: Guid;
         isV2?: boolean;
-    }): Promise<string | null>;
+    }): string | null;
     /**
      * @param update base64 encoded uint8array
      * @returns { isUpdated: boolean; snapshotHash: string }
      *   isUpdated: true if the update had an effect on the YDoc
      *   snapshotHash: the hash of the new snapshot
      */
-    addYDocUpdate(logger: Logger, update: string | Uint8Array, guid?: Guid, isV2?: boolean): Promise<{
+    addYDocUpdate(logger: Logger, update: string | Uint8Array, guid?: Guid, isV2?: boolean): {
         isUpdated: boolean;
         snapshotHash: string;
-    }>;
-    loadDocByIdIfNotAlreadyLoaded(logger: Logger, docId: YDocId): Promise<Y.Doc>;
-    load(logger: Logger): Promise<void>;
-    /**
-     * Unloads the Yjs documents from memory.
-     */
-    unload(): void;
+    };
     private _getOrPutLastSnapshot;
     private _putLastSnapshot;
     private _compactYJSUpdates;
@@ -1292,7 +1316,6 @@ declare class YjsStorage {
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 
-type LoadingState = "initial" | "loading" | "loaded";
 type ActorID = Brand<number, "ActorID">;
 /** Number of milliseconds since Unix epoch. */
 type Millis = Brand<number, "Millis">;
@@ -1401,14 +1424,8 @@ type RoomOptions<SM, CM extends JsonObject, C> = {
         };
         /** Called whenever the server acknowledged a ping with a pong */
         onDidPong?: (ctx?: C) => void | Promise<void>;
-        /** Called before the room is attempted to be loaded */
-        onRoomWillLoad?: (ctx?: C) => void | Promise<void>;
-        /** Called right after the room's contents are loaded, but before any session has been started */
-        onRoomDidLoad?: (ctx?: C) => void | Promise<void>;
         /** Called right before the room is attempted to be unloaded. Synchronous. May throw to abort the unloading. */
         onRoomWillUnload?: (ctx?: C) => void;
-        /** Called right after the room has been unloaded from memory. Synchronous. */
-        onRoomDidUnload?: (ctx?: C) => void;
         /** Called when a new user entered the room. */
         onSessionDidStart?: (session: BrowserSession<SM, CM>, ctx?: C) => void | Promise<void>;
         /** Called when a user left the room. */
@@ -1444,7 +1461,6 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     #private;
     meta: RM;
     readonly driver: IStorageDriver;
-    logger: Logger;
     /**
      * While a room is in "maintenance mode", all WebSocket connections to the
      * room should be rejected until it's pulled out of maintenance mode again.
@@ -1454,18 +1470,18 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * init-storage, storage-reset, etc.) cannot interfere with one another.
      */
     private readonly _maintenanceMode;
-    private _loadData$;
-    private _data;
+    private _storage;
+    private _yjsStorage;
+    readonly mutex: Mutex;
+    get storage(): Storage;
+    get yjsStorage(): YjsStorage;
     private _qsize;
     private readonly sessions;
     private readonly hooks;
     constructor(meta: RM, options?: RoomOptions<SM, CM, C>);
-    get loadingState(): LoadingState;
+    get logger(): Logger;
+    addLoggerContext(attrs: JsonObject): void;
     get numSessions(): number;
-    get storage(): Storage;
-    get yjsStorage(): YjsStorage;
-    get mutex(): Mutex;
-    private get data();
     /**
      * Returns true if the room is currently in maintenance mode.
      * When in maintenance mode, callers should refuse new WebSocket connections.
@@ -1476,17 +1492,11 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * If the room is already in maintenance mode, throws E_ALREADY_LOCKED
      * immediately instead of queuing the request.
      */
-    runInMaintenanceMode<T>(callback: () => Promise<T>): Promise<T>;
-    /**
-     * Initializes the Room, so it's ready to start accepting connections. Safe
-     * to call multiple times. After awaiting `room.load()` the Room is ready to
-     * be used.
-     */
-    load(ctx?: C): Promise<void>;
+    runInMaintenanceMode<T>(callback: () => T | Promise<T>): Promise<T>;
     /**
-     * Releases the currently-loaded storage tree from worker memory, freeing it
-     * up to be garbage collected. The next time a user will join the room, the
-     * room will be reloaded from storage.
+     * Releases the currently-loaded storage tree and Yjs documents from worker
+     * memory, freeing them up to be garbage collected. The next time the room
+     * is used, fresh instances will lazily be created.
      */
     unload(ctx?: C): void;
     /**
@@ -1500,11 +1510,11 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * connection is established. If the socket is never established, this
      * unused Ticket will simply get garbage collected.
      */
-    createTicket(options?: CreateTicketOptions<SM, CM>): Promise<Ticket<SM, CM>>;
-    createBackendSession_experimental(): Promise<[
+    createTicket(options?: CreateTicketOptions<SM, CM>): Ticket<SM, CM>;
+    createBackendSession_experimental(): [
         session: BackendSession,
         outgoingMessages: jstring<ServerMsg>[]
-    ]>;
+    ];
     /**
      * Restores the given sessions as the Room server's session list. Can only be
      * called as long as there are no existing sessions.
@@ -1531,7 +1541,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * - Sends a ROOM_STATE message to the socket.
      * - Broadcasts a USER_JOINED message to all other sessions in the room.
      */
-    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    startBrowserSession(ticket: Ticket<SM, CM>, socket: IServerWebSocket, ctx?: C, defer?: (promise: Promise<void>) => void): void;
     /**
      * Unregisters the BrowserSession for the given actor. Call this when the socket has
      * been closed from the client's end.
@@ -1587,46 +1597,46 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * Upsert a leased session. Creates a new session if it doesn't exist (or is expired),
      * or updates an existing session with merged presence.
      */
-    upsertLeasedSession(sessionId: string, presence: JsonObject, ttl: number, info: IUserInfo, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    upsertLeasedSession(sessionId: string, presence: JsonObject, ttl: number, info: IUserInfo, ctx?: C, defer?: (promise: Promise<void>) => void): void;
     /**
      * List all server sessions. As a side effect, it will delete expired sessions.
      */
-    listLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<LeasedSession[]>;
+    listLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): LeasedSession[];
     /**
      * Delete a server session and broadcast USER_LEFT to all sessions.
      */
-    deleteLeasedSession(session: LeasedSession, ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    deleteLeasedSession(session: LeasedSession, ctx?: C, defer?: (promise: Promise<void>) => void): void;
     /**
      * Delete all server sessions and broadcast USER_LEFT to all sessions.
      */
-    deleteAllLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): Promise<void>;
+    deleteAllLeasedSessions(ctx?: C, defer?: (promise: Promise<void>) => void): void;
     /**
      * List feeds with pagination and filtering.
      */
-    listFeeds(options?: ListFeedsOptions): Promise<ListFeedsResult>;
+    listFeeds(options?: ListFeedsOptions): ListFeedsResult;
     /**
      * Get a specific feed by feed ID.
      */
-    getFeed(feedId: string): Promise<Feed | undefined>;
+    getFeed(feedId: string): Feed | undefined;
     /**
      * Create a new feed.
      * If timestamp is not provided, current server time is used.
      */
     createFeed(feed: Omit<Feed, "createdAt" | "updatedAt"> & {
         timestamp?: number;
-    }): Promise<Feed>;
+    }): Feed;
     /**
      * Update a feed's metadata.
      */
-    updateFeedMetadata(feedId: string, metadata: Json): Promise<void>;
+    updateFeedMetadata(feedId: string, metadata: Json): void;
     /**
      * Delete a feed.
      */
-    deleteFeed(feedId: string): Promise<void>;
+    deleteFeed(feedId: string): void;
     /**
      * List feed messages for a feed with pagination.
      */
-    listFeedMessages(feedId: string, options?: ListFeedMessagesOptions): Promise<ListFeedMessagesResult>;
+    listFeedMessages(feedId: string, options?: ListFeedMessagesOptions): ListFeedMessagesResult;
     /**
      * Add a message to a feed.
      * If message id is not provided, a unique ID is automatically generated.
@@ -1634,16 +1644,16 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      */
     addFeedMessage(feedId: string, message: Omit<FeedMessage, "id" | "createdAt" | "updatedAt"> & Partial<Pick<FeedMessage, "id">> & {
         timestamp?: number;
-    }): Promise<FeedMessage>;
+    }): FeedMessage;
     /**
      * Update a feed message's data.
      * Returns the updated message.
      */
-    updateFeedMessage(feedId: string, messageId: string, data: Json, timestamp?: number): Promise<FeedMessage>;
+    updateFeedMessage(feedId: string, messageId: string, data: Json, timestamp?: number): FeedMessage;
     /**
      * Delete a feed message.
      */
-    deleteFeedMessage(feedId: string, messageId: string): Promise<void>;
+    deleteFeedMessage(feedId: string, messageId: string): void;
     /**
      * Will send the given ServerMsg through all Session, except the Session
      * where the message originates from.
@@ -1653,13 +1663,10 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
      * Will broadcast the given ServerMsg to all Sessions in the Room.
      */
     sendToAll(serverMsg: ServerMsg | readonly ServerMsg[], ctx?: C, defer?: (promise: Promise<void>) => void): void;
-    private _loadStorage;
-    private _loadYjsStorage;
-    private _load;
     /**
      * Returns a new, unique, actor ID.
      */
-    private getNextActor;
+    getNextActor(): ActorID;
     /**
      * Iterates over all *other* Sessions and their session keys.
      */
@@ -1716,32 +1723,8 @@ declare function isLeasedSessionExpired(leasedSession: LeasedSession): boolean;
  * You should have received a copy of the GNU Affero General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-/**
- * Given a promise or promise factory, returns a 2-tuple of success or failure.
- * This pattern avoids having to build deeply nested try / catch clauses, where
- * success variables need to be defined as a `let` outside of the `try` block.
- *
- * Turns:
- *
- *   let result;
- *   try {
- *     result = await doSomething();
- *   } catch (error) {
- *     // do something with error
- *   }
- *
- *   doAnotherThing(result);
- *
- * Into:
- *
- *   const [result, error] = await tryCatch(doSomething());
- *   if (error) {
- *     // do something with error
- *   }
- *   doAnotherThing(result);
- *
- */
-declare function tryCatch<T, E = Error>(promise: Promise<T> | (() => Promise<T>) | (() => T)): Promise<[T, undefined] | [undefined, E]>;
+declare function tryCatch<T, E = Error>(promise: PromiseLike<T> | (() => PromiseLike<T>)): Promise<[T, undefined] | [undefined, E]>;
+declare function tryCatch<T, E = Error>(fn: () => T): [T, undefined] | [undefined, E];
 
 /**
  * Copyright (c) Liveblocks Inc.
@@ -1924,6 +1907,7 @@ declare class UniqueMap<K, V, UK> extends Map<K, V> {
 declare class InMemoryDriver implements IStorageDriver {
     private _nextActor;
     private _nodes;
+    private _nodesApi?;
     private _metadb;
     private _ydb;
     private _leasedSessions;
@@ -1934,32 +1918,53 @@ declare class InMemoryDriver implements IStorageDriver {
         initialNodes?: Iterable<[string, SerializedCrdt]>;
     });
     raw_iter_nodes(): MapIterator<[string, SerializedCrdt]>;
+    reinitialize(): void;
     /** Deletes all nodes and replaces them with the given document. */
     DANGEROUSLY_reset_nodes(doc: PlainLsonObject): void;
-    get_meta(key: string): Promise<Json | undefined>;
-    put_meta(key: string, value: Json): Promise<void>;
-    delete_meta(key: string): Promise<void>;
-    list_leased_sessions(): Promise<MapIterator<[string, LeasedSession]>>;
-    get_leased_session(sessionId: string): Promise<LeasedSession | undefined>;
-    put_leased_session(session: LeasedSession): Promise<void>;
-    delete_leased_session(sessionId: string): Promise<void>;
+    get_meta(key: string): Json | undefined;
+    put_meta(key: string, value: Json): void;
+    delete_meta(key: string): void;
+    list_leased_sessions(): MapIterator<[string, LeasedSession]>;
+    get_leased_session(sessionId: string): LeasedSession | undefined;
+    put_leased_session(session: LeasedSession): void;
+    delete_leased_session(sessionId: string): void;
     takeRowsWritten(): number;
-    list_feeds(options?: ListFeedsOptions): Promise<ListFeedsResult>;
-    get_feed(feedId: string): Promise<Feed | undefined>;
-    create_feed(feed: Feed): Promise<void>;
-    update_feed_metadata(feedId: string, metadata: Json): Promise<void>;
-    delete_feed(feedId: string): Promise<void>;
-    list_feed_messages(feedId: string, options?: ListFeedMessagesOptions): Promise<ListFeedMessagesResult>;
-    add_feed_message(feedId: string, message: FeedMessage): Promise<void>;
-    update_feed_message(feedId: string, messageId: string, data: Json, timestamp?: number): Promise<FeedMessage>;
-    delete_feed_message(feedId: string, messageId: string): Promise<void>;
+    list_feeds(options?: ListFeedsOptions): ListFeedsResult;
+    get_feed(feedId: string): Feed | undefined;
+    create_feed(feed: Feed): void;
+    update_feed_metadata(feedId: string, metadata: Json): void;
+    delete_feed(feedId: string): void;
+    list_feed_messages(feedId: string, options?: ListFeedMessagesOptions): ListFeedMessagesResult;
+    add_feed_message(feedId: string, message: FeedMessage): void;
+    update_feed_message(feedId: string, messageId: string, data: Json, timestamp?: number): FeedMessage;
+    delete_feed_message(feedId: string, messageId: string): void;
     next_actor(): number;
-    iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array<ArrayBufferLike>]>>;
-    write_y_updates(docId: YDocId, key: string, data: Uint8Array): Promise<void>;
-    delete_y_updates(docId: YDocId, keys: string[]): Promise<void>;
+    iter_y_updates(docId: YDocId): IterableIterator<[string, Uint8Array<ArrayBufferLike>]>;
+    write_y_updates(docId: YDocId, key: string, data: Uint8Array): void;
+    delete_y_updates(docId: YDocId, keys: string[]): void;
     /** @private Only use this in unit tests, never in production. */
-    DANGEROUSLY_wipe_all_y_updates(): Promise<void>;
-    load_nodes_api(): IStorageDriverNodeAPI;
+    DANGEROUSLY_wipe_all_y_updates(): void;
+    /**
+     * The lazily-built node API. Building it ensures the root node exists and
+     * constructs the reverse-lookup index. Invalidated by
+     * DANGEROUSLY_reset_nodes(), after which the next access rebuilds it.
+     */
+    private get loadedApi();
+    get_node(id: string): SerializedCrdt | undefined;
+    iter_nodes(): NodeStream$1;
+    iter_nodes_optimized(): Iterable<jstring<CompactNode>>;
+    has_node(id: string): boolean;
+    get_child_at(parentId: string, parentKey: string): string | undefined;
+    has_child_at(parentId: string, parentKey: string): boolean;
+    get_next_sibling(parentId: string, pos: Pos): Pos | undefined;
+    get_last_sibling(parentId: string): Pos | undefined;
+    set_child(id: string, node: SerializedChild, allowOverwrite?: boolean): void;
+    move_sibling(id: string, newPos: Pos): void;
+    delete_node(id: string): void;
+    delete_child_key(id: string, key: string): void;
+    set_object_data(id: string, data: JsonObject, allowOverwrite?: boolean): void;
+    get_snapshot(lowMemory?: boolean): IReadableSnapshot;
+    private _loadNodesApi;
 }
 
-export { type ActorID, type AddFeedClientMsg, type AddFeedMessageClientMsg, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type DeleteFeedClientMsg, type DeleteFeedMessageClientMsg, type Feed, type FeedDeletedServerMsg, type FeedMessage, type FeedMessagesAddedServerMsg, type FeedMessagesDeletedServerMsg, type FeedMessagesListServerMsg, type FeedMessagesServerMsg, type FeedMessagesUpdatedServerMsg, FeedMsgCode, FeedRequestErrorCode, type FeedRequestFailedServerMsg, type FeedsAddedServerMsg, type FeedsListServerMsg, type FeedsServerMsg, type FeedsUpdatedServerMsg, type FetchFeedMessagesClientMsg, type FetchFeedsClientMsg, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type ListFeedMessagesOptions, type ListFeedMessagesResult, type ListFeedsOptions, type ListFeedsResult, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, type Millis, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type UpdateFeedClientMsg, type UpdateFeedMessageClientMsg, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, feedFailureServerMsg, feedMetadataIdDecoder, feedMetadataUpdateDecoder, feedRequestFailed, fetchFeedsMetadataFilterDecoder, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, type jstring, makeInMemorySnapshot, makeMetadataDB, mapFeedError, optionalFeedMetadataDecoder, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };
+export { type ActorID, type AddFeedClientMsg, type AddFeedMessageClientMsg, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type DeleteFeedClientMsg, type DeleteFeedMessageClientMsg, type Feed, type FeedDeletedServerMsg, type FeedMessage, type FeedMessagesAddedServerMsg, type FeedMessagesDeletedServerMsg, type FeedMessagesListServerMsg, type FeedMessagesServerMsg, type FeedMessagesUpdatedServerMsg, FeedMsgCode, FeedRequestErrorCode, type FeedRequestFailedServerMsg, type FeedsAddedServerMsg, type FeedsListServerMsg, type FeedsServerMsg, type FeedsUpdatedServerMsg, type FetchFeedMessagesClientMsg, type FetchFeedsClientMsg, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IUserData, InMemoryDriver, type LeasedSession, type ListFeedMessagesOptions, type ListFeedMessagesResult, type ListFeedsOptions, type ListFeedsResult, LogLevel, LogTarget, Logger, type MetadataDB, type Millis, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type UpdateFeedClientMsg, type UpdateFeedMessageClientMsg, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, feedFailureServerMsg, feedMetadataIdDecoder, feedMetadataUpdateDecoder, feedRequestFailed, fetchFeedsMetadataFilterDecoder, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, type jstring, makeInMemorySnapshot, makeMetadataDB, mapFeedError, optionalFeedMetadataDecoder, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };