@liveblocks/node 2.21.0 → 2.22.1

package/dist/index.cjs

@@ -3,7 +3,7 @@ var _core = require('@liveblocks/core');
 
 // src/version.ts
 var PKG_NAME = "@liveblocks/node";
-var PKG_VERSION = "2.21.0";
+var PKG_VERSION = "2.22.1";
 var PKG_FORMAT = "cjs";
 
 // src/client.ts
@@ -19,6 +19,75 @@ var PKG_FORMAT = "cjs";
 
 
 
+
+
+
+
+
+// src/lib/itertools.ts
+async function asyncConsume(iterable) {
+  const result = [];
+  for await (const item of iterable) {
+    result.push(item);
+  }
+  return result;
+}
+async function runConcurrently(iterable, fn, concurrency) {
+  const queue = /* @__PURE__ */ new Set();
+  for await (const item of iterable) {
+    if (queue.size >= concurrency) {
+      await Promise.race(queue);
+    }
+    const promise = (async () => {
+      try {
+        await fn(item);
+      } finally {
+        queue.delete(promise);
+      }
+    })();
+    queue.add(promise);
+  }
+  if (queue.size > 0) {
+    await Promise.all(queue);
+  }
+}
+
+// src/lib/ndjson.ts
+var LineStream = class extends TransformStream {
+  constructor() {
+    let buffer = "";
+    super({
+      transform(chunk, controller) {
+        buffer += chunk;
+        if (buffer.includes("\n")) {
+          const lines = buffer.split("\n");
+          for (let i = 0; i < lines.length - 1; i++) {
+            if (lines[i].length > 0) {
+              controller.enqueue(lines[i]);
+            }
+          }
+          buffer = lines[lines.length - 1];
+        }
+      },
+      flush(controller) {
+        if (buffer.length > 0) {
+          controller.enqueue(buffer);
+        }
+      }
+    });
+  }
+};
+var NdJsonStream = class extends TransformStream {
+  constructor() {
+    super({
+      transform(line, controller) {
+        const json = JSON.parse(line);
+        controller.enqueue(json);
+      }
+    });
+  }
+};
+
 // src/Session.ts
 
 
@@ -407,8 +476,8 @@ var Liveblocks = class {
     if (!res.ok) {
       throw await LiveblocksError.from(res);
     }
-    const data = await res.json();
-    const rooms = data.data.map((room) => {
+    const page = await res.json();
+    const rooms = page.data.map((room) => {
       const lastConnectionAt = room.lastConnectionAt ? new Date(room.lastConnectionAt) : void 0;
       const createdAt = new Date(room.createdAt);
       return {
@@ -418,10 +487,42 @@ var Liveblocks = class {
       };
     });
     return {
-      ...data,
+      ...page,
       data: rooms
     };
   }
+  /**
+   * Iterates over all rooms that match the given criteria.
+   *
+   * The difference with .getRooms() is that pagination will happen
+   * automatically under the hood, using the given `pageSize`.
+   *
+   * @param criteria.userId (optional) A filter on users accesses.
+   * @param criteria.groupIds (optional) A filter on groups accesses. Multiple groups can be used.
+   * @param criteria.query.roomId (optional) A filter by room ID.
+   * @param criteria.query.metadata (optional) A filter by metadata.
+   *
+   * @param options.pageSize (optional) The page size to use for each request.
+   * @param options.signal (optional) An abort signal to cancel the request.
+   */
+  async *iterRooms(criteria, options) {
+    const { signal } = _nullishCoalesce(options, () => ( {}));
+    const pageSize = _core.checkBounds.call(void 0, "pageSize", _nullishCoalesce(_optionalChain([options, 'optionalAccess', _8 => _8.pageSize]), () => ( 40)), 20);
+    let cursor = void 0;
+    while (true) {
+      const { nextCursor, data } = await this.getRooms(
+        { ...criteria, startingAfter: cursor, limit: pageSize },
+        { signal }
+      );
+      for (const item of data) {
+        yield item;
+      }
+      if (!nextCursor) {
+        break;
+      }
+      cursor = nextCursor;
+    }
+  }
   /**
    * Creates a new room with the given id.
    * @param roomId The id of the room to create.
@@ -457,6 +558,51 @@ var Liveblocks = class {
       createdAt
     };
   }
+  /**
+   * Returns a room with the given id, or creates one with the given creation
+   * options if it doesn't exist yet.
+   *
+   * @param roomId The id of the room.
+   * @param params.defaultAccesses The default accesses for the room if the room will be created.
+   * @param params.groupsAccesses (optional) The group accesses for the room if the room will be created. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+   * @param params.usersAccesses (optional) The user accesses for the room if the room will be created. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+   * @param params.metadata (optional) The metadata for the room if the room will be created. Supports upto a maximum of 50 entries. Key length has a limit of 40 characters. Value length has a limit of 256 characters.
+   * @param options.signal (optional) An abort signal to cancel the request.
+   * @returns The room.
+   */
+  async getOrCreateRoom(roomId, params, options) {
+    try {
+      return await this.createRoom(roomId, params, options);
+    } catch (err) {
+      if (err instanceof LiveblocksError && err.status === 409) {
+        return await this.getRoom(roomId, options);
+      } else {
+        throw err;
+      }
+    }
+  }
+  /**
+   * Updates or creates a new room with the given properties.
+   *
+   * @param roomId The id of the room to update or create.
+   * @param params.defaultAccesses The default accesses for the room.
+   * @param params.groupsAccesses (optional) The group accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+   * @param params.usersAccesses (optional) The user accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+   * @param params.metadata (optional) The metadata for the room. Supports upto a maximum of 50 entries. Key length has a limit of 40 characters. Value length has a limit of 256 characters.
+   * @param options.signal (optional) An abort signal to cancel the request.
+   * @returns The room.
+   */
+  async upsertRoom(roomId, params, options) {
+    try {
+      return await this.createRoom(roomId, params, options);
+    } catch (err) {
+      if (err instanceof LiveblocksError && err.status === 409) {
+        return await this.updateRoom(roomId, params, options);
+      } else {
+        throw err;
+      }
+    }
+  }
   /**
    * Returns a room with the given id.
    * @param roomId The id of the room to return.
@@ -567,6 +713,27 @@ var Liveblocks = class {
     }
     return await res.json();
   }
+  async #requestStorageMutation(roomId, options) {
+    const resp = await this.#post(
+      _core.url`/v2/rooms/${roomId}/request-storage-mutation`,
+      {},
+      options
+    );
+    if (!resp.ok) {
+      throw await LiveblocksError.from(resp);
+    }
+    if (resp.headers.get("content-type") !== "application/x-ndjson") {
+      throw new Error("Unexpected response content type");
+    }
+    if (resp.body === null) {
+      throw new Error("Unexpected null body in response");
+    }
+    const stream = resp.body.pipeThrough(new TextDecoderStream()).pipeThrough(new LineStream()).pipeThrough(new NdJsonStream());
+    const iter = stream[Symbol.asyncIterator]();
+    const { actor } = await iter.next();
+    const nodes = await asyncConsume(iter);
+    return { actor, nodes };
+  }
   /**
    * Initializes a room’s Storage. The room must already exist and have an empty Storage.
    * Calling this endpoint will disconnect all users from the room if there are any.
@@ -911,7 +1078,7 @@ var Liveblocks = class {
       _core.url`/v2/rooms/${roomId}/threads/${threadId}/comments`,
       {
         ...data,
-        createdAt: _optionalChain([data, 'access', _8 => _8.createdAt, 'optionalAccess', _9 => _9.toISOString, 'call', _10 => _10()])
+        createdAt: _optionalChain([data, 'access', _9 => _9.createdAt, 'optionalAccess', _10 => _10.toISOString, 'call', _11 => _11()])
       },
       options
     );
@@ -934,7 +1101,7 @@ var Liveblocks = class {
     const { roomId, threadId, commentId, data } = params;
     const res = await this.#post(
       _core.url`/v2/rooms/${roomId}/threads/${threadId}/comments/${commentId}`,
-      { ...data, editedAt: _optionalChain([data, 'access', _11 => _11.editedAt, 'optionalAccess', _12 => _12.toISOString, 'call', _13 => _13()]) },
+      { ...data, editedAt: _optionalChain([data, 'access', _12 => _12.editedAt, 'optionalAccess', _13 => _13.toISOString, 'call', _14 => _14()]) },
       options
     );
     if (!res.ok) {
@@ -978,7 +1145,7 @@ var Liveblocks = class {
         ...data,
         comment: {
           ...data.comment,
-          createdAt: _optionalChain([data, 'access', _14 => _14.comment, 'access', _15 => _15.createdAt, 'optionalAccess', _16 => _16.toISOString, 'call', _17 => _17()])
+          createdAt: _optionalChain([data, 'access', _15 => _15.comment, 'access', _16 => _16.createdAt, 'optionalAccess', _17 => _17.toISOString, 'call', _18 => _18()])
         }
       },
       options
@@ -1060,7 +1227,7 @@ var Liveblocks = class {
       _core.url`/v2/rooms/${roomId}/threads/${threadId}/metadata`,
       {
         ...data,
-        updatedAt: _optionalChain([data, 'access', _18 => _18.updatedAt, 'optionalAccess', _19 => _19.toISOString, 'call', _20 => _20()])
+        updatedAt: _optionalChain([data, 'access', _19 => _19.updatedAt, 'optionalAccess', _20 => _20.toISOString, 'call', _21 => _21()])
       },
       options
     );
@@ -1086,7 +1253,7 @@ var Liveblocks = class {
       _core.url`/v2/rooms/${roomId}/threads/${threadId}/comments/${commentId}/add-reaction`,
       {
         ...data,
-        createdAt: _optionalChain([data, 'access', _21 => _21.createdAt, 'optionalAccess', _22 => _22.toISOString, 'call', _23 => _23()])
+        createdAt: _optionalChain([data, 'access', _22 => _22.createdAt, 'optionalAccess', _23 => _23.toISOString, 'call', _24 => _24()])
       },
       options
     );
@@ -1112,7 +1279,7 @@ var Liveblocks = class {
       _core.url`/v2/rooms/${roomId}/threads/${threadId}/comments/${params.commentId}/remove-reaction`,
       {
         ...data,
-        removedAt: _optionalChain([data, 'access', _24 => _24.removedAt, 'optionalAccess', _25 => _25.toISOString, 'call', _26 => _26()])
+        removedAt: _optionalChain([data, 'access', _25 => _25.removedAt, 'optionalAccess', _26 => _26.toISOString, 'call', _27 => _27()])
       },
       options
     );
@@ -1156,17 +1323,51 @@ var Liveblocks = class {
     }
     const res = await this.#get(
       _core.url`/v2/users/${userId}/inbox-notifications`,
-      { query },
+      {
+        query,
+        limit: _optionalChain([params, 'optionalAccess', _28 => _28.limit]),
+        startingAfter: _optionalChain([params, 'optionalAccess', _29 => _29.startingAfter])
+      },
       options
     );
     if (!res.ok) {
       throw await LiveblocksError.from(res);
     }
-    const { data } = await res.json();
+    const page = await res.json();
     return {
-      data: data.map(_core.convertToInboxNotificationData)
+      ...page,
+      data: page.data.map(_core.convertToInboxNotificationData)
     };
   }
+  /**
+   * Iterates over all inbox notifications for a user.
+   *
+   * The difference with .getInboxNotifications() is that pagination will
+   * happen automatically under the hood, using the given `pageSize`.
+   *
+   * @param criteria.userId The user ID to get the inbox notifications from.
+   * @param criteria.query The query to filter inbox notifications by. It is based on our query language and can filter by unread.
+   * @param options.pageSize (optional) The page size to use for each request.
+   * @param options.signal (optional) An abort signal to cancel the request.
+   */
+  async *iterInboxNotifications(criteria, options) {
+    const { signal } = _nullishCoalesce(options, () => ( {}));
+    const pageSize = _core.checkBounds.call(void 0, "pageSize", _nullishCoalesce(_optionalChain([options, 'optionalAccess', _30 => _30.pageSize]), () => ( 50)), 10);
+    let cursor = void 0;
+    while (true) {
+      const { nextCursor, data } = await this.getInboxNotifications(
+        { ...criteria, startingAfter: cursor, limit: pageSize },
+        { signal }
+      );
+      for (const item of data) {
+        yield item;
+      }
+      if (!nextCursor) {
+        break;
+      }
+      cursor = nextCursor;
+    }
+  }
   /**
    * Gets the user's room notification settings.
    * @param params.userId The user ID to get the room notifications from.
@@ -1338,6 +1539,121 @@ var Liveblocks = class {
       throw await LiveblocksError.from(res);
     }
   }
+  /**
+   * Retrieves the current Storage contents for the given room ID and calls the
+   * provided callback function, in which you can mutate the Storage contents
+   * at will.
+   *
+   * If you need to run the same mutation across multiple rooms, prefer using
+   * `.massMutateStorage()` instead of looping over room IDs yourself.
+   */
+  async mutateStorage(roomId, callback, options) {
+    return this.#_mutateOneRoom(roomId, void 0, callback, options);
+  }
+  /**
+   * Retrieves the Storage contents for each room that matches the given
+   * criteria and calls the provided callback function, in which you can mutate
+   * the Storage contents at will.
+   *
+   * You can use the `criteria` parameter to select which rooms to process by
+   * their metadata. If you pass `{}` (empty object), all rooms will be
+   * selected and processed.
+   *
+   * This method will execute mutations in parallel, using the specified
+   * `concurrency` value. If you which to run the mutations serially, set
+   * `concurrency` to 1.
+   */
+  async massMutateStorage(criteria, callback, massOptions) {
+    const concurrency = _core.checkBounds.call(void 0, 
+      "concurrency",
+      _nullishCoalesce(_optionalChain([massOptions, 'optionalAccess', _31 => _31.concurrency]), () => ( 8)),
+      1,
+      20
+    );
+    const pageSize = Math.max(20, concurrency * 4);
+    const { signal } = _nullishCoalesce(massOptions, () => ( {}));
+    const rooms = this.iterRooms(criteria, { pageSize, signal });
+    const options = { signal };
+    await runConcurrently(
+      rooms,
+      (roomData) => this.#_mutateOneRoom(roomData.id, roomData, callback, options),
+      concurrency
+    );
+  }
+  async #_mutateOneRoom(roomId, room, callback, options) {
+    const debounceInterval = 200;
+    const { signal, abort } = _core.makeAbortController.call(void 0, _optionalChain([options, 'optionalAccess', _32 => _32.signal]));
+    let opsBuffer = [];
+    let outstandingFlush$ = void 0;
+    let lastFlush = performance.now();
+    const flushIfNeeded = (force) => {
+      if (opsBuffer.length === 0)
+        return;
+      if (outstandingFlush$) {
+        return;
+      }
+      const now = performance.now();
+      if (!(force || now - lastFlush > debounceInterval)) {
+        return;
+      }
+      lastFlush = now;
+      const ops = opsBuffer;
+      opsBuffer = [];
+      outstandingFlush$ = this.#sendMessage(
+        roomId,
+        [{ type: _core.ClientMsgCode.UPDATE_STORAGE, ops }],
+        { signal }
+      ).catch((err) => {
+        abort(err);
+      }).finally(() => {
+        outstandingFlush$ = void 0;
+      });
+    };
+    try {
+      const resp = await this.#requestStorageMutation(roomId, { signal });
+      const { actor, nodes } = resp;
+      const pool = _core.createManagedPool.call(void 0, roomId, {
+        getCurrentConnectionId: () => actor,
+        onDispatch: (ops, _reverse, _storageUpdates) => {
+          if (ops.length === 0) return;
+          for (const op of ops) {
+            opsBuffer.push(op);
+          }
+          flushIfNeeded(
+            /* force */
+            false
+          );
+        }
+      });
+      const root = _core.LiveObject._fromItems(nodes, pool);
+      const callback$ = callback({ room, root });
+      flushIfNeeded(
+        /* force */
+        true
+      );
+      await callback$;
+    } catch (e) {
+      abort();
+      throw e;
+    } finally {
+      await outstandingFlush$;
+      flushIfNeeded(
+        /* force */
+        true
+      );
+      await outstandingFlush$;
+    }
+  }
+  async #sendMessage(roomId, messages, options) {
+    const res = await this.#post(
+      _core.url`/v2/rooms/${roomId}/send-message`,
+      { messages },
+      { signal: _optionalChain([options, 'optionalAccess', _33 => _33.signal]) }
+    );
+    if (!res.ok) {
+      throw await LiveblocksError.from(res);
+    }
+  }
 };
 var LiveblocksError = class _LiveblocksError extends Error {
   
@@ -1357,11 +1673,13 @@ ${this.details}`;
     return msg;
   }
   static async from(res) {
+    const origErrLocation = new Error();
+    Error.captureStackTrace(origErrLocation, _LiveblocksError.from);
     const FALLBACK = "An error happened without an error message";
     let text;
     try {
       text = await res.text();
-    } catch (e) {
+    } catch (e2) {
       text = FALLBACK;
     }
     const obj = _nullishCoalesce(_core.tryParseJson.call(void 0, text), () => ( { message: text }));
@@ -1370,7 +1688,9 @@ ${this.details}`;
       obj.suggestion ? `Suggestion: ${String(obj.suggestion)}` : void 0,
       obj.docs ? `See also: ${String(obj.docs)}` : void 0
     ].filter(Boolean).join("\n") || void 0;
-    return new _LiveblocksError(message, res.status, details);
+    const err = new _LiveblocksError(message, res.status, details);
+    err.stack = origErrLocation.stack;
+    return err;
   }
 };