@adobe/spacecat-shared-data-access 2.76.1 → 2.77.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v2.77.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.76.1...@adobe/spacecat-shared-data-access-v2.77.0) (2025-10-31)
+
+
+### Features
+
+* pagination base code ([#1077](https://github.com/adobe/spacecat-shared/issues/1077)) ([7cd3806](https://github.com/adobe/spacecat-shared/commit/7cd38061c74f5a6e73097e2ceabcd1e90bf8de3b))
+
 # [@adobe/spacecat-shared-data-access-v2.76.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.76.0...@adobe/spacecat-shared-data-access-v2.76.1) (2025-10-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.76.1",
+  "version": "2.77.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/base.collection.js

@@ -237,6 +237,7 @@ class BaseCollection {
         order: options.order || 'desc',
         ...options.limit && { limit: options.limit },
         ...options.attributes && { attributes: options.attributes },
+        ...options.cursor && { cursor: options.cursor },
       };
 
       let query = index(keys);
@@ -268,10 +269,16 @@ class BaseCollection {
         }
       }
 
+      // Return cursor when explicitly requested via returnCursor option
+      const shouldReturnCursor = options.returnCursor === true;
+
       if (options.limit === 1) {
         return allData.length ? this.#createInstance(allData[0]) : null;
       } else {
-        return this.#createInstances(allData);
+        const instances = this.#createInstances(allData);
+        return shouldReturnCursor
+          ? { data: instances, cursor: result.cursor || null }
+          : instances;
       }
     } catch (error) {
       return this.#logAndThrowError('Failed to query', error);

package/src/models/base/index.d.ts

@@ -34,13 +34,25 @@ export interface QueryOptions {
   limit?: number;
   order?: string;
   attributes?: string[];
-  /** 
-   * Whether to automatically fetch all pages of results. 
+  cursor?: string;
+  /**
+   * Whether to automatically fetch all pages of results.
    * - `true`: Always paginate through all results
    * - `false`: Only fetch first page
    * - `undefined`: Auto-paginate when no limit specified, respect limits otherwise
    */
   fetchAllPages?: boolean;
+  /**
+   * Whether to return cursor information for manual pagination.
+   * - `true`: Returns { data, cursor } for paginated results
+   * - `false` or `undefined`: Returns data array directly (default)
+   */
+  returnCursor?: boolean;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  cursor: string | null;
 }
 
 export interface BatchGetOptions {
@@ -51,8 +63,8 @@ export interface BaseCollection<T extends BaseModel> {
   _onCreate(item: T): void;
   _onCreateMany(items: MultiStatusCreateResult<T>): void;
   _saveMany(items: T[]): Promise<T[]>;
-  all(sortKeys?: object, options?: QueryOptions): Promise<T[]>;
-  allByIndexKeys(keys: object, options?: QueryOptions): Promise<T[]>;
+  all(sortKeys?: object, options?: QueryOptions): Promise<T[] | PaginatedResult<T>>;
+  allByIndexKeys(keys: object, options?: QueryOptions): Promise<T[] | PaginatedResult<T>>;
   batchGetByKeys(keys: object[], options?: BatchGetOptions): Promise<{ data: T[]; unprocessed: object[] }>;
   create(item: object): Promise<T>;
   createMany(items: object[], parent?: T): Promise<MultiStatusCreateResult<T>>;

package/src/models/suggestion/index.d.ts

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import type { BaseCollection, BaseModel, Opportunity, FixEntitySuggestion, FixEntity } from '../index';
+import type { BaseCollection, BaseModel, Opportunity, FixEntitySuggestion, FixEntity, QueryOptions, PaginatedResult } from '../index';
 
 export interface Suggestion extends BaseModel {
   getData(): object;
@@ -28,10 +28,10 @@ export interface Suggestion extends BaseModel {
 }
 
 export interface SuggestionCollection extends BaseCollection<Suggestion> {
-  allByOpportunityId(opportunityId: string): Promise<Suggestion[]>;
-  allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion[]>;
+  allByOpportunityId(opportunityId: string, options?: QueryOptions): Promise<Suggestion[] | PaginatedResult<Suggestion>>;
+  allByOpportunityIdAndStatus(opportunityId: string, status: string, options?: QueryOptions): Promise<Suggestion[] | PaginatedResult<Suggestion>>;
   bulkUpdateStatus(suggestions: Suggestion[], status: string): Promise<Suggestion[]>;
-  findByOpportunityId(opportunityId: string): Promise<Suggestion | null>;
-  findByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion | null>;
+  findByOpportunityId(opportunityId: string, options?: QueryOptions): Promise<Suggestion | null>;
+  findByOpportunityIdAndStatus(opportunityId: string, status: string, options?: QueryOptions): Promise<Suggestion | null>;
   getFixEntitiesBySuggestionId(suggestionId: string): Promise<{data: Array<FixEntity>, unprocessed: Array<string>}>;
 }