@adobe/spacecat-shared-data-access 3.17.0 → 3.18.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/spacecat-shared-data-access-v3.18.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.17.0...@adobe/spacecat-shared-data-access-v3.18.0) (2026-03-12)
+
+### Features
+
+* **data-access:** add saveMany() to BaseCollection for chunked bulk upsert ([#1428](https://github.com/adobe/spacecat-shared/issues/1428)) ([802bfec](https://github.com/adobe/spacecat-shared/commit/802bfecb21981e577fc1e72b38c24002edcd8bb1))
+
 ## [@adobe/spacecat-shared-data-access-v3.17.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.16.0...@adobe/spacecat-shared-data-access-v3.17.0) (2026-03-12)
 
 ### Features

package/package.json

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

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

@@ -876,6 +876,48 @@ class BaseCollection {
     }
   }
 
+  /**
+   * Saves multiple model instances to the database in chunked batches.
+   * Each chunk is persisted via a single PostgREST upsert call, avoiding
+   * the thundering-herd problem caused by N concurrent individual saves.
+   *
+   * Chunks are processed sequentially. If a chunk fails, the error is
+   * propagated immediately — chunks already persisted are NOT rolled back.
+   * Callers must account for partial saves on failure.
+   *
+   * @param {BaseModel[]} items - Model instances with in-memory mutations to persist.
+   * @param {Object} [options] - Options.
+   * @param {number} [options.chunkSize=25] - Max items per upsert request.
+   *   Keep low for entities with large payloads (e.g. Suggestion.data JSONB).
+   * @returns {Promise<void>}
+   * @throws {DataAccessError} If any chunk fails. Previously completed chunks
+   *   are already persisted — callers must account for partial saves.
+   */
+  async saveMany(items, { chunkSize = 25 } = {}) {
+    if (!isNonEmptyArray(items)) {
+      return;
+    }
+
+    const effectiveChunkSize = Math.max(1, Math.floor(chunkSize)) || 25;
+    const totalChunks = Math.ceil(items.length / effectiveChunkSize);
+
+    if (totalChunks > 1) {
+      this.log.info(`[${this.entityName}] saveMany: saving ${items.length} items in ${totalChunks} chunks of ${effectiveChunkSize}`);
+    }
+
+    for (let i = 0; i < items.length; i += effectiveChunkSize) {
+      const chunkIndex = Math.floor(i / effectiveChunkSize) + 1;
+      const chunk = items.slice(i, i + effectiveChunkSize);
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await this._saveMany(chunk);
+      } catch (error) {
+        this.log.error(`[${this.entityName}] saveMany: chunk ${chunkIndex}/${totalChunks} failed — ${i} of ${items.length} items already persisted`);
+        throw error;
+      }
+    }
+  }
+
   async _saveMany(items) {
     if (!isNonEmptyArray(items)) {
       const message = `Failed to save many [${this.entityName}]: items must be a non-empty array`;

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

@@ -62,7 +62,8 @@ export interface BatchGetOptions {
 export interface BaseCollection<T extends BaseModel> {
   _onCreate(item: T): void;
   _onCreateMany(items: MultiStatusCreateResult<T>): void;
-  _saveMany(items: T[]): Promise<T[]>;
+  _saveMany(items: T[]): Promise<void>;
+  saveMany(items: T[], options?: { chunkSize?: number }): Promise<void>;
   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[] }>;

package/src/models/suggestion/suggestion.collection.js

@@ -55,7 +55,7 @@ class SuggestionCollection extends BaseCollection {
       suggestion.setStatus(status);
     });
 
-    await this._saveMany(suggestions);
+    await this.saveMany(suggestions);
 
     return suggestions;
   }