@spacelr/sdk 0.2.1 → 0.2.2

package/dist/index.mjs

@@ -1642,6 +1642,68 @@ var StorageModule = class {
 };
 
 // libs/sdk/src/modules/database.module.ts
+var Paginator = class {
+  constructor(http, basePath, opts) {
+    this.http = http;
+    this.basePath = basePath;
+    this._exhausted = false;
+    /**
+     * Tail of the serialized `next()` chain. Each call appends to this so
+     * concurrent invocations from a UI scroll handler (e.g. user spam-tapping
+     * "load more") don't issue parallel requests with the same cursor — which
+     * would return duplicate pages and clobber the cursor based on whichever
+     * response settles last. Calls execute strictly in invocation order.
+     */
+    this.chain = Promise.resolve({
+      documents: [],
+      hasMore: false
+    });
+    this.cursor = opts.cursor;
+    this.direction = opts.sort?._id ?? -1;
+    this.pageSize = opts.limit ?? 50;
+    this.where = opts.where;
+  }
+  /**
+   * True once a `next()` call has returned an empty page. Subsequent
+   * `next()` calls return an empty page without hitting the server.
+   *
+   * Note: only the empty-page signal flips this flag; a server response
+   * that returns documents but `hasMore: false` does NOT exhaust. This
+   * lets ascending paginators (`sort: { _id: 1 }`) keep polling for
+   * documents inserted after the caller caught up to the current tail —
+   * the next `.after(lastSeen)` call will simply return zero documents
+   * until something new lands.
+   */
+  get exhausted() {
+    return this._exhausted;
+  }
+  next() {
+    const run = this.chain.then(
+      () => this.fetchNextPage(),
+      () => this.fetchNextPage()
+    );
+    this.chain = run;
+    return run;
+  }
+  async fetchNextPage() {
+    if (this._exhausted) return { documents: [], hasMore: false };
+    const builder = new QueryBuilder(this.http, this.basePath, this.where).sort({ _id: this.direction }).limit(this.pageSize);
+    let result;
+    if (this.cursor !== void 0) {
+      const cursorBuilder = this.direction === -1 ? builder.before(this.cursor) : builder.after(this.cursor);
+      result = await cursorBuilder.execute();
+    } else {
+      result = await builder.execute();
+    }
+    if (result.documents.length === 0) {
+      this._exhausted = true;
+      return { documents: [], hasMore: false };
+    }
+    this.cursor = result.documents[result.documents.length - 1]._id;
+    const hasMore = result.mode === "cursor" ? result.hasMore : result.documents.length < result.total;
+    return { documents: result.documents, hasMore };
+  }
+};
 var QueryBuilder = class {
   constructor(http, basePath, filter) {
     this.http = http;
@@ -1758,6 +1820,20 @@ var CollectionRef = class {
   find(filter) {
     return new QueryBuilder(this.http, this.basePath, filter);
   }
+  /**
+   * Cursor-based scroll-back helper. Returns a `Paginator` whose `.next()`
+   * yields successive pages and tracks the last-seen `_id` internally.
+   * Defaults to descending sort and 50 docs per page (chat scroll-back is
+   * the canonical use case). See `PaginateOptions` for tuning.
+   *
+   * **Cursor constraint:** uses `_id` keyset pagination, which requires
+   * 24-hex ObjectId `_id`s. Collections with custom string `_id` schemes
+   * fall back to comparing strings as ObjectIds — the server's handler
+   * documents this limitation on `before` / `after` directly.
+   */
+  paginate(opts = {}) {
+    return new Paginator(this.http, this.basePath, opts);
+  }
   /**
    * Server-side substring search across the specified fields.
    *