@seaverse/data-service-sdk 0.10.2 → 0.11.0

package/README.md

@@ -16,6 +16,7 @@ SeaVerse Data Service SDK for accessing Firestore with secure token management a
 |---------------------|---------------|--------------|
 | **Write Public Data** | `helper.addToPublicData()` | `await helper.addToPublicData('posts', {title: 'Hello'})` |
 | **Read Public Data** | `helper.getPublicData()` | `const posts = await helper.getPublicData('posts')` |
+| **Read with Pagination** | `helper.getPublicData()` | `const posts = await helper.getPublicData('posts', false, {limit: 10})` |
 | **Write Private Data** | `helper.addToUserData()` | `await helper.addToUserData('notes', {text: 'Secret'})` |
 | **Read Private Data** | `helper.getUserData()` | `const notes = await helper.getUserData('notes')` |
 
@@ -378,6 +379,16 @@ posts.forEach(doc => {
   console.log(doc.id, doc.data());
 });
 
+// ✅ Pagination support: Get first 10 posts
+const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+
+// Get next 10 posts (start after last document)
+const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+const nextPage = await helper.getPublicData('posts', false, {
+  limit: 10,
+  startAfter: lastDoc
+});
+
 // ✅ LLM-FRIENDLY: Write to userData (private) - auto-isolated!
 await helper.addToUserData('notes', {
   title: 'Private Note',
@@ -762,6 +773,42 @@ const userPosts = query(
 const snapshot = await getDocs(userPosts);
 ```
 
+### Use Case 5: Pagination (New!)
+
+```typescript
+// ✅ Simple pagination with FirestoreHelper
+
+// Get first page (10 posts)
+const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+
+console.log(`Fetched ${firstPage.docs.length} posts`);
+firstPage.forEach(doc => {
+  console.log('Post:', doc.id, doc.data());
+});
+
+// Check if there are more pages
+if (firstPage.docs.length === 10) {
+  // Get next page (start after last document)
+  const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+  const nextPage = await helper.getPublicData('posts', false, {
+    limit: 10,
+    startAfter: lastDoc
+  });
+
+  console.log(`Next page: ${nextPage.docs.length} posts`);
+}
+
+// Also works with getUserData and getPublicRead
+const userNotes = await helper.getUserData('notes', false, { limit: 20 });
+const configs = await helper.getPublicRead('config', { limit: 5 });
+```
+
+**Pagination Best Practices:**
+- Use a consistent `limit` value across pages for predictable UX
+- Store the last document from the current page to fetch the next page
+- Check if `docs.length` equals your limit to determine if there might be more pages
+- For infinite scroll, keep appending results; for traditional pagination, replace the view
+
 ## Permission Examples
 
 ### What Users CAN Do
@@ -1316,4 +1363,4 @@ Here's a complete example for using the SDK directly in the browser without any
 ## Related SDKs
 
 - [@seaverse/auth-sdk](../auth-sdk) - User authentication and account management
-- [@seaverse/payment-sdk](../payment-sdk) - Payment processing integration
+- [@seaverse/assets-sdk](../assets-sdk) - Assets and payment processing integration

package/dist/browser.js

@@ -4782,6 +4782,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4794,11 +4795,21 @@ class FirestoreHelper {
      *
      * // Include deleted posts (admin use case)
      * const allPosts = await helper.getPublicData('posts', true);
+     *
+     * // Pagination: Get first 10 posts
+     * const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+     *
+     * // Get next 10 posts (start after last document)
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getPublicData('posts', false, {
+     *   limit: 10,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getPublicData(collectionName, includeDeleted = false) {
+    async getPublicData(collectionName, includeDeleted = false, options) {
         const path = getPublicDataPath(this.appId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from userData collection (user's private data)
@@ -4807,6 +4818,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4815,26 +4827,45 @@ class FirestoreHelper {
      * snapshot.forEach(doc => {
      *   console.log('My note:', doc.data());
      * });
+     *
+     * // Pagination: Get first 20 notes
+     * const firstPage = await helper.getUserData('notes', false, { limit: 20 });
+     *
+     * // Get next page
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getUserData('notes', false, {
+     *   limit: 20,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getUserData(collectionName, includeDeleted = false) {
+    async getUserData(collectionName, includeDeleted = false, options) {
         const path = getUserDataPath(this.appId, this.userId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from publicRead collection (read-only for users)
      *
      * @param collectionName - Collection name
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
      * ```typescript
      * const configs = await helper.getPublicRead('config');
+     *
+     * // Pagination
+     * const firstPage = await helper.getPublicRead('config', { limit: 10 });
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getPublicRead('config', {
+     *   limit: 10,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getPublicRead(collectionName) {
+    async getPublicRead(collectionName, options) {
         const path = getPublicReadPath(this.appId, collectionName);
-        return this.getDocs(path);
+        return this.getDocs(path, false, options);
     }
     /**
      * Get collection reference for publicData
@@ -5003,22 +5034,36 @@ class FirestoreHelper {
     }
     /**
      * Internal: Get all documents from collection
-     * Optionally filter out soft-deleted documents
+     * Optionally filter out soft-deleted documents and support pagination
      */
-    async getDocs(collectionPath, includeDeleted = false) {
-        const { getDocs, collection, query, where } = await this.loadFirestore();
+    async getDocs(collectionPath, includeDeleted = false, options) {
+        const { getDocs, collection, query, where, limit, startAfter } = await this.loadFirestore();
         const colRef = collection(this.db, collectionPath);
-        if (includeDeleted) {
-            // Return all documents (including soft-deleted)
-            return getDocs(colRef);
-        }
-        else {
+        // Build query constraints
+        const constraints = [];
+        // Add soft-delete filter if needed
+        if (!includeDeleted) {
             // Filter out soft-deleted documents
             // Use '!=' to include documents without _deleted field (new documents)
             // This will return documents where _deleted is missing, null, undefined, or false
-            const q = query(colRef, where('_deleted', '!=', true));
+            constraints.push(where('_deleted', '!=', true));
+        }
+        // Add pagination constraints if provided
+        if (options?.limit) {
+            constraints.push(limit(options.limit));
+        }
+        if (options?.startAfter) {
+            constraints.push(startAfter(options.startAfter));
+        }
+        // Execute query
+        if (constraints.length > 0) {
+            const q = query(colRef, ...constraints);
             return getDocs(q);
         }
+        else {
+            // No constraints, return all documents
+            return getDocs(colRef);
+        }
     }
     /**
      * Internal: Get collection reference
@@ -5047,7 +5092,8 @@ class FirestoreHelper {
             query: firestore.query,
             where: firestore.where,
             orderBy: firestore.orderBy,
-            limit: firestore.limit
+            limit: firestore.limit,
+            startAfter: firestore.startAfter
         };
     }
 }