@adobe/spacecat-shared-data-access 2.77.1 → 2.79.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v2.79.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.78.0...@adobe/spacecat-shared-data-access-v2.79.0) (2025-11-07)
+
+
+### Features
+
+* PTA2 Summary query ([#1102](https://github.com/adobe/spacecat-shared/issues/1102)) ([06e902a](https://github.com/adobe/spacecat-shared/commit/06e902a5487c2fc2e79a3f15d7acf1072900fab4))
+
+# [@adobe/spacecat-shared-data-access-v2.78.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.77.1...@adobe/spacecat-shared-data-access-v2.78.0) (2025-11-06)
+
+
+### Features
+
+* **data-access:** add early-monday interval ([#1099](https://github.com/adobe/spacecat-shared/issues/1099)) ([3c7cc87](https://github.com/adobe/spacecat-shared/commit/3c7cc87b89c2bf06c9b5322ca20c26863cac14ac))
+
 # [@adobe/spacecat-shared-data-access-v2.77.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.77.0...@adobe/spacecat-shared-data-access-v2.77.1) (2025-11-01)
 
 

package/package.json

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

package/src/models/configuration/configuration.model.js

@@ -37,6 +37,7 @@ class Configuration extends BaseModel {
     EVERY_HOUR: 'every-hour',
     DAILY: 'daily',
     WEEKLY: 'weekly',
+    EARLY_MONDAY: 'early-monday',
     EVERY_SATURDAY: 'every-saturday',
     EVERY_SUNDAY: 'every-sunday',
     FORTNIGHTLY: 'fortnightly',

package/src/readme.md

@@ -88,7 +88,7 @@ const single = await Suggestion.findByOpportunityIdAndStatus('op-12345', 'OPEN')
 - `get...()`: Getters for entity attributes.
 - `set...()`: Setters for entity attributes.
 
-Additionally, `BaseModel` generates methods to fetch referenced entities. 
+Additionally, `BaseModel` generates methods to fetch referenced entities.
 For example, if `User` belongs to `Organization`, `BaseModel` will create:
 
 - `getOrganization()`: Fetch the referenced `Organization` entity.
@@ -116,6 +116,206 @@ const org = await user.getOrganization();
 console.log(org.getName());
 ```
 
+## Pagination Support
+
+All `allBy...` methods automatically support pagination through an optional `options` parameter. Pagination is built into `BaseCollection` and available for every entity without additional configuration.
+
+### Query Options
+
+Every `allBy...` method accepts an optional `options` object with the following parameters:
+
+```typescript
+interface QueryOptions {
+  // Pagination control
+  limit?: number;              // Limit results per page
+  cursor?: string;             // Cursor from previous page
+  returnCursor?: boolean;      // Return {data, cursor} instead of array
+  fetchAllPages?: boolean;     // true: fetch all pages, false: single page only
+
+  // Query control
+  order?: 'asc' | 'desc';      // Sort order (default: 'desc')
+  attributes?: string[];        // Which fields to return
+
+  // Range queries
+  between?: {
+    attribute: string;
+    start: string | number;
+    end: string | number;
+  };
+}
+```
+
+### Pagination Behavior
+
+By default, `allBy...` methods **automatically fetch all pages** of results. You can control this behavior:
+
+- **Default (no options):** Fetches all pages automatically
+- **`fetchAllPages: true`:** Explicitly fetch all pages
+- **`fetchAllPages: false`:** Fetch only the first page
+- **`limit` without `fetchAllPages`:** Fetch only the first page (limited results)
+
+### Usage Examples
+
+#### Fetch All Results (Default)
+```js
+// Automatically fetches all pages
+const suggestions = await Suggestion.allByOpportunityId('op-12345');
+// Returns: Suggestion[] (all matching results)
+```
+
+#### Manual Pagination with Cursor
+```js
+// Fetch first page
+const firstPage = await Suggestion.allByOpportunityIdAndStatus(
+  'op-12345',
+  'NEW',
+  { limit: 50, returnCursor: true }
+);
+// Returns: { data: Suggestion[], cursor: string | null }
+
+console.log(`Found ${firstPage.data.length} suggestions`);
+
+// Fetch next page if cursor exists
+if (firstPage.cursor) {
+  const secondPage = await Suggestion.allByOpportunityIdAndStatus(
+    'op-12345',
+    'NEW',
+    { limit: 50, cursor: firstPage.cursor, returnCursor: true }
+  );
+}
+```
+
+#### Limit Results (Single Page)
+```js
+// Get only first 20 results (stops after first page)
+const limitedResults = await Suggestion.allByOpportunityId(
+  'op-12345',
+  { limit: 20, fetchAllPages: false }
+);
+// Returns: Suggestion[] (max 20 items)
+```
+
+#### Filter by Attributes
+```js
+// Fetch only specific fields
+const suggestions = await Suggestion.allByOpportunityId(
+  'op-12345',
+  { attributes: ['suggestionId', 'status', 'rank'] }
+);
+```
+
+### Exposing Pagination in TypeScript
+
+Pagination is implemented in `BaseCollection` but must be exposed in your entity's TypeScript definitions to provide IntelliSense support for consumers.
+
+#### Required Steps
+
+**1. Import Required Types**
+
+In your entity's `index.d.ts`, add these imports:
+
+```typescript
+import type {
+  BaseCollection,
+  BaseModel,
+  QueryOptions,      // For options parameter
+  PaginatedResult,   // For return type
+  // ... other imports
+} from '../index';
+```
+
+**2. Update Method Signatures**
+
+For each `allBy...` method, add the `options` parameter and update the return type:
+
+```typescript
+export interface MyEntityCollection extends BaseCollection<MyEntity> {
+  // Before: allByParentId(parentId: string): Promise<MyEntity[]>;
+
+  // After:
+  allByParentId(
+    parentId: string,
+    options?: QueryOptions
+  ): Promise<MyEntity[] | PaginatedResult<MyEntity>>;
+
+  allByParentIdAndStatus(
+    parentId: string,
+    status: string,
+    options?: QueryOptions
+  ): Promise<MyEntity[] | PaginatedResult<MyEntity>>;
+}
+```
+
+**3. Update `findBy...` Methods (Optional)**
+
+For `findBy...` methods, add the `options` parameter (keeps single-item return type):
+
+```typescript
+export interface MyEntityCollection extends BaseCollection<MyEntity> {
+  findByParentId(
+    parentId: string,
+    options?: QueryOptions
+  ): Promise<MyEntity | null>;
+}
+```
+
+#### Complete Example
+
+```typescript
+import type {
+  BaseCollection, BaseModel, QueryOptions, PaginatedResult,
+} from '../index';
+
+export interface Suggestion extends BaseModel {
+  getStatus(): string;
+  setStatus(status: string): Suggestion;
+  // ... other methods
+}
+
+export interface SuggestionCollection extends BaseCollection<Suggestion> {
+  // With pagination support
+  allByOpportunityId(
+    opportunityId: string,
+    options?: QueryOptions
+  ): Promise<Suggestion[] | PaginatedResult<Suggestion>>;
+
+  allByOpportunityIdAndStatus(
+    opportunityId: string,
+    status: string,
+    options?: QueryOptions
+  ): Promise<Suggestion[] | PaginatedResult<Suggestion>>;
+
+  findByOpportunityId(
+    opportunityId: string,
+    options?: QueryOptions
+  ): Promise<Suggestion | null>;
+}
+```
+
+### Type-Safe Result Handling
+
+TypeScript will correctly infer the return type based on usage:
+
+```typescript
+// Returns Suggestion[]
+const all = await Suggestion.allByOpportunityId('op-12345');
+
+// Returns { data: Suggestion[], cursor: string | null }
+const page = await Suggestion.allByOpportunityId(
+  'op-12345',
+  { limit: 50, returnCursor: true }
+);
+
+// Type guard for handling both cases
+if (Array.isArray(result)) {
+  // result is Suggestion[]
+  console.log(result.length);
+} else {
+  // result is PaginatedResult<Suggestion>
+  console.log(result.data.length, result.cursor);
+}
+```
+
 ## Step-by-Step: Adding a New Entity
 
 Follow these steps to introduce a new entity into the framework.