@ftschopp/dynatable-core 1.4.4 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# @ftschopp/dynatable-core [1.5.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.4...@ftschopp/dynatable-core@1.5.0) (2026-05-09)
+
+
+### Features
+
+* **core:** chunk and retry BatchGet/BatchWrite to handle DynamoDB limits ([#26](https://github.com/ftschopp/dynatable/issues/26)) ([5c7b1cc](https://github.com/ftschopp/dynatable/commit/5c7b1cc0044d0ae6a213735a40f20ef0232dbceb)), closes [#6](https://github.com/ftschopp/dynatable/issues/6)
+
 ## @ftschopp/dynatable-core [1.4.4](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.3...@ftschopp/dynatable-core@1.4.4) (2026-05-09)
 
 

package/dist/builders/batch-get/create-batch-get-builder.d.ts

@@ -4,9 +4,14 @@ import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 /**
  * Creates a BatchGetBuilder to retrieve multiple items by their keys.
  *
+ * `execute()` transparently chunks the request to at most 100 keys per
+ * SDK call (DynamoDB's `BatchGetItem` limit) and retries any
+ * UnprocessedKeys with exponential backoff. The `dbParams()` method
+ * still returns the un-chunked request — see its JSDoc.
+ *
  * @param requestItems - An object where keys are table names and values are objects containing Keys array
  * @param client - DynamoDB client instance
- * @param options - Optional configuration (projection, consistentRead)
+ * @param options - Optional configuration (projection, consistentRead, maxRetries, retryBackoffMs)
  * @param logger - Optional logger instance
  */
 export declare function createBatchGetBuilder<Model>(requestItems: Record<string, {
@@ -14,5 +19,7 @@ export declare function createBatchGetBuilder<Model>(requestItems: Record<string
 }>, client: DynamoDBClient, options?: {
     projection?: (keyof Model)[];
     consistentRead?: boolean;
+    maxRetries?: number;
+    retryBackoffMs?: number;
 }, logger?: DynamoDBLogger): BatchGetBuilder<Model>;
 //# sourceMappingURL=create-batch-get-builder.d.ts.map

package/dist/builders/batch-get/create-batch-get-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-batch-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/create-batch-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EACzC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,EAC7C,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,eAAe,CAAC,KAAK,CAAC,CAgFxB"}
+{"version":3,"file":"create-batch-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/create-batch-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAiB1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAsC7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EACzC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,EAC7C,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,eAAe,CAAC,KAAK,CAAC,CAqIxB"}

package/dist/builders/batch-get/create-batch-get-builder.js

@@ -3,70 +3,120 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBatchGetBuilder = createBatchGetBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const shared_1 = require("../shared");
+/**
+ * Builds the per-table request shape with projection placeholders applied.
+ *
+ * Resolves the same `#-placeholder` projection (from #5) for every table in
+ * the request — the projection is a property of the builder, not per-table.
+ */
+function buildEnhancedRequestItems(requestItems, projection, isConsistent) {
+    const proj = projection.length > 0 ? (0, shared_1.buildProjectionExpression)(projection) : undefined;
+    return Object.entries(requestItems).reduce((acc, [tableName, tableRequest]) => {
+        acc[tableName] = {
+            Keys: tableRequest.Keys,
+            ...(proj && {
+                ProjectionExpression: proj.ProjectionExpression,
+                ExpressionAttributeNames: proj.ExpressionAttributeNames,
+            }),
+            ...(isConsistent && { ConsistentRead: true }),
+        };
+        return acc;
+    }, {});
+}
 /**
  * Creates a BatchGetBuilder to retrieve multiple items by their keys.
  *
+ * `execute()` transparently chunks the request to at most 100 keys per
+ * SDK call (DynamoDB's `BatchGetItem` limit) and retries any
+ * UnprocessedKeys with exponential backoff. The `dbParams()` method
+ * still returns the un-chunked request — see its JSDoc.
+ *
  * @param requestItems - An object where keys are table names and values are objects containing Keys array
  * @param client - DynamoDB client instance
- * @param options - Optional configuration (projection, consistentRead)
+ * @param options - Optional configuration (projection, consistentRead, maxRetries, retryBackoffMs)
  * @param logger - Optional logger instance
  */
 function createBatchGetBuilder(requestItems, client, options, logger) {
     const projection = options?.projection ?? [];
     const isConsistent = options?.consistentRead ?? false;
+    const maxRetries = options?.maxRetries ?? shared_1.DEFAULT_MAX_RETRIES;
+    const retryBackoff = options?.retryBackoffMs ?? shared_1.DEFAULT_RETRY_BACKOFF_MS;
     return {
-        /**
-         * Select only specific attributes to retrieve.
-         */
         select(attrs) {
             return createBatchGetBuilder(requestItems, client, {
                 projection: attrs,
                 consistentRead: isConsistent,
+                maxRetries,
+                retryBackoffMs: retryBackoff,
             }, logger);
         },
-        /**
-         * Enable strongly consistent read.
-         */
         consistentRead() {
             return createBatchGetBuilder(requestItems, client, {
                 projection,
                 consistentRead: true,
+                maxRetries,
+                retryBackoffMs: retryBackoff,
+            }, logger);
+        },
+        maxRetries(n) {
+            return createBatchGetBuilder(requestItems, client, {
+                projection,
+                consistentRead: isConsistent,
+                maxRetries: n,
+                retryBackoffMs: retryBackoff,
+            }, logger);
+        },
+        retryBackoffMs(ms) {
+            return createBatchGetBuilder(requestItems, client, {
+                projection,
+                consistentRead: isConsistent,
+                maxRetries,
+                retryBackoffMs: ms,
             }, logger);
         },
-        /**
-         * Build the underlying DynamoDB input parameters.
-         */
         dbParams() {
-            // Build the projection once (with #-placeholders so reserved words
-            // like name/date/status/type don't blow up at DynamoDB) and reuse
-            // it per-table.
-            const proj = projection.length > 0 ? (0, shared_1.buildProjectionExpression)(projection.map(String)) : undefined;
-            const enhancedRequestItems = Object.entries(requestItems).reduce((acc, [tableName, tableRequest]) => {
-                acc[tableName] = {
-                    Keys: tableRequest.Keys,
-                    ...(proj && {
-                        ProjectionExpression: proj.ProjectionExpression,
-                        ExpressionAttributeNames: proj.ExpressionAttributeNames,
-                    }),
-                    ...(isConsistent && { ConsistentRead: true }),
-                };
-                return acc;
-            }, {});
             return {
-                RequestItems: enhancedRequestItems,
+                RequestItems: buildEnhancedRequestItems(requestItems, projection.map(String), isConsistent),
             };
         },
-        /**
-         * Execute the BatchGetItem command and return the items as a flat array.
-         */
         async execute() {
-            const params = this.dbParams();
-            const result = await client.send(new lib_dynamodb_1.BatchGetCommand(params));
-            logger?.log('BatchGetCommand', params, result);
-            if (!result.Responses) {
+            // Chunk only the Keys (the projection / consistentRead options are
+            // re-applied per chunk).
+            const flatKeys = {};
+            for (const [tableName, tr] of Object.entries(requestItems)) {
+                flatKeys[tableName] = tr.Keys;
+            }
+            const chunks = (0, shared_1.chunkRequestItems)(flatKeys, shared_1.BATCH_GET_LIMIT);
+            if (chunks.length === 0)
                 return [];
+            const aggregated = [];
+            for (const chunk of chunks) {
+                const chunkRequest = {};
+                for (const [tableName, keys] of Object.entries(chunk)) {
+                    chunkRequest[tableName] = { Keys: keys };
+                }
+                let pending = buildEnhancedRequestItems(chunkRequest, projection.map(String), isConsistent);
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    const params = { RequestItems: pending };
+                    const result = await client.send(new lib_dynamodb_1.BatchGetCommand(params));
+                    logger?.log('BatchGetCommand', params, result);
+                    if (result.Responses) {
+                        for (const items of Object.values(result.Responses)) {
+                            aggregated.push(...items);
+                        }
+                    }
+                    const unprocessed = result.UnprocessedKeys;
+                    if ((0, shared_1.isUnprocessedEmpty)(unprocessed)) {
+                        break;
+                    }
+                    if (attempt === maxRetries) {
+                        throw new shared_1.BatchUnprocessedError(`BatchGet still has unprocessed keys after ${maxRetries} retries.`, unprocessed);
+                    }
+                    await (0, shared_1.sleep)((0, shared_1.backoffMs)(attempt, retryBackoff));
+                    pending = unprocessed;
+                }
             }
-            return Object.values(result.Responses).flat();
+            return aggregated;
         },
     };
 }

package/dist/builders/batch-get/types.d.ts

@@ -1,7 +1,12 @@
 import { BatchGetItemCommandInput } from '@aws-sdk/client-dynamodb';
 /**
- * BatchGetBuilder allows you to retrieve multiple items from one or more tables
- * in a single request.
+ * BatchGetBuilder allows you to retrieve multiple items from one or more
+ * tables in a single logical operation.
+ *
+ * `execute()` chunks the request into sub-requests of at most 100 keys
+ * (DynamoDB's hard BatchGetItem limit) and retries any UnprocessedKeys
+ * with exponential backoff. After the retry budget is exhausted, a
+ * `BatchUnprocessedError` is thrown carrying whatever could not be retrieved.
  */
 export type BatchGetBuilder<Model> = {
     /**
@@ -12,12 +17,30 @@ export type BatchGetBuilder<Model> = {
      * Enable strongly consistent read for all items.
      */
     consistentRead(): BatchGetBuilder<Model>;
+    /**
+     * Configure the maximum number of retry attempts per chunk when the
+     * response carries UnprocessedKeys. Defaults to 3.
+     */
+    maxRetries(n: number): BatchGetBuilder<Model>;
+    /**
+     * Configure the initial exponential-backoff delay in milliseconds.
+     * Subsequent retries wait `initial * 2^attempt` ms. Defaults to 50ms.
+     */
+    retryBackoffMs(ms: number): BatchGetBuilder<Model>;
     /**
      * Build the underlying DynamoDB BatchGetItem input parameters.
+     *
+     * **Note:** this returns the request as a single, unchunked
+     * `BatchGetItem` input. If you have more than 100 keys total, sending
+     * this directly to the SDK will fail at runtime — `execute()` is what
+     * applies the chunking and retry logic.
      */
     dbParams(): BatchGetItemCommandInput;
     /**
-     * Execute the BatchGetItem command and return the items as a flat array.
+     * Execute the BatchGetItem operation and return the items as a flat
+     * array, aggregated across all chunks. Order across chunks is preserved
+     * but the order *within* a chunk is whatever DynamoDB returns
+     * (BatchGetItem does not guarantee item order).
      */
     execute(): Promise<Model[]>;
 };

package/dist/builders/batch-get/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IACnC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;OAEG;IACH,cAAc,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,IAAI,wBAAwB,CAAC;IAErC;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;CAC7B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IACnC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;OAEG;IACH,cAAc,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAEzC;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAE9C;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAEnD;;;;;;;OAOG;IACH,QAAQ,IAAI,wBAAwB,CAAC;IAErC;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;CAC7B,CAAC"}

package/dist/builders/batch-write/create-batch-write-builder.d.ts

@@ -4,9 +4,17 @@ import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 /**
  * Creates a BatchWriteBuilder to put or delete multiple items.
  *
+ * `execute()` transparently chunks `requestItems` into sub-requests of at
+ * most 25 items (DynamoDB's `BatchWriteItem` limit) and retries any
+ * UnprocessedItems with exponential backoff. The `dbParams()` method
+ * still returns the un-chunked request — see its JSDoc for details.
+ *
  * @param requestItems - An object where keys are table names and values are arrays of WriteRequest
  * @param client - DynamoDB client instance
  * @param logger - Optional logger instance
  */
-export declare function createBatchWriteBuilder(requestItems: Record<string, WriteRequest[]>, client: DynamoDBClient, logger?: DynamoDBLogger): BatchWriteBuilder;
+export declare function createBatchWriteBuilder(requestItems: Record<string, WriteRequest[]>, client: DynamoDBClient, logger?: DynamoDBLogger, options?: {
+    maxRetries?: number;
+    retryBackoffMs?: number;
+}): BatchWriteBuilder;
 //# sourceMappingURL=create-batch-write-builder.d.ts.map

package/dist/builders/batch-write/create-batch-write-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-batch-write-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-write/create-batch-write-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAC5C,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,cAAc,GACtB,iBAAiB,CA2BnB"}
+{"version":3,"file":"create-batch-write-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-write/create-batch-write-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAgB1D,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAC5C,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,iBAAiB,CAkEnB"}

package/dist/builders/batch-write/create-batch-write-builder.js

@@ -2,34 +2,63 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBatchWriteBuilder = createBatchWriteBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const shared_1 = require("../shared");
 /**
  * Creates a BatchWriteBuilder to put or delete multiple items.
  *
+ * `execute()` transparently chunks `requestItems` into sub-requests of at
+ * most 25 items (DynamoDB's `BatchWriteItem` limit) and retries any
+ * UnprocessedItems with exponential backoff. The `dbParams()` method
+ * still returns the un-chunked request — see its JSDoc for details.
+ *
  * @param requestItems - An object where keys are table names and values are arrays of WriteRequest
  * @param client - DynamoDB client instance
  * @param logger - Optional logger instance
  */
-function createBatchWriteBuilder(requestItems, client, logger) {
+function createBatchWriteBuilder(requestItems, client, logger, options) {
+    const maxRetries = options?.maxRetries ?? shared_1.DEFAULT_MAX_RETRIES;
+    const retryBackoff = options?.retryBackoffMs ?? shared_1.DEFAULT_RETRY_BACKOFF_MS;
     return {
-        /**
-         * Build the underlying DynamoDB input parameters.
-         */
+        maxRetries(n) {
+            return createBatchWriteBuilder(requestItems, client, logger, {
+                maxRetries: n,
+                retryBackoffMs: retryBackoff,
+            });
+        },
+        retryBackoffMs(ms) {
+            return createBatchWriteBuilder(requestItems, client, logger, {
+                maxRetries,
+                retryBackoffMs: ms,
+            });
+        },
         dbParams() {
             return {
                 RequestItems: requestItems,
             };
         },
-        /**
-         * Execute the BatchWriteItem command.
-         */
         async execute() {
-            const params = this.dbParams();
-            const result = await client.send(new lib_dynamodb_1.BatchWriteCommand(params));
-            logger?.log('BatchWriteCommand', params, result);
-            // Return unprocessed items if any
-            return {
-                unprocessedItems: result.UnprocessedItems,
-            };
+            const chunks = (0, shared_1.chunkRequestItems)(requestItems, shared_1.BATCH_WRITE_LIMIT);
+            if (chunks.length === 0) {
+                return {};
+            }
+            for (const chunk of chunks) {
+                let pending = chunk;
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    const params = { RequestItems: pending };
+                    const result = await client.send(new lib_dynamodb_1.BatchWriteCommand(params));
+                    logger?.log('BatchWriteCommand', params, result);
+                    const unprocessed = result.UnprocessedItems;
+                    if ((0, shared_1.isUnprocessedEmpty)(unprocessed)) {
+                        break; // chunk fully processed
+                    }
+                    if (attempt === maxRetries) {
+                        throw new shared_1.BatchUnprocessedError(`BatchWrite still has unprocessed items after ${maxRetries} retries.`, unprocessed);
+                    }
+                    await (0, shared_1.sleep)((0, shared_1.backoffMs)(attempt, retryBackoff));
+                    pending = unprocessed;
+                }
+            }
+            return {};
         },
     };
 }

package/dist/builders/batch-write/types.d.ts

@@ -12,16 +12,44 @@ export type WriteRequest = {
 };
 /**
  * BatchWriteBuilder allows you to put or delete multiple items from one or more tables
- * in a single request.
+ * in a single logical operation.
+ *
+ * `execute()` chunks the request into sub-requests of at most 25 items
+ * (DynamoDB's hard BatchWriteItem limit) and retries any UnprocessedItems
+ * with exponential backoff. After the retry budget is exhausted, a
+ * `BatchUnprocessedError` is thrown carrying whatever could not be processed.
  */
 export type BatchWriteBuilder = {
+    /**
+     * Configure the maximum number of retry attempts per chunk when the
+     * response carries UnprocessedItems. Defaults to 3.
+     */
+    maxRetries(n: number): BatchWriteBuilder;
+    /**
+     * Configure the initial exponential-backoff delay in milliseconds.
+     * Subsequent retries wait `initial * 2^attempt` ms. Defaults to 50ms.
+     */
+    retryBackoffMs(ms: number): BatchWriteBuilder;
     /**
      * Build the underlying DynamoDB BatchWriteItem input parameters.
+     *
+     * **Note:** this returns the request as a single, unchunked
+     * `BatchWriteItem` input. If you have more than 25 items total, sending
+     * this directly to the SDK will fail at runtime — `execute()` is what
+     * applies the chunking and retry logic.
      */
     dbParams(): BatchWriteItemCommandInput;
     /**
-     * Execute the BatchWriteItem command.
-     * Returns unprocessed items if any requests failed.
+     * Execute the BatchWriteItem operation.
+     *
+     * Internally chunks `RequestItems` to at most 25 items per SDK call and
+     * retries any UnprocessedItems with exponential backoff (default 3
+     * retries, configurable via {@link maxRetries}). Throws
+     * `BatchUnprocessedError` if items remain unprocessed after the budget.
+     *
+     * On success the resolved value is `{}` — there is nothing left to
+     * report. The legacy `unprocessedItems` field is no longer populated
+     * because partial success now surfaces as a thrown error.
      */
     execute(): Promise<{
         unprocessedItems?: Record<string, WriteRequest[]>;

package/dist/builders/batch-write/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-write/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,GAAG,CAAC;KACX,CAAC;IACF,aAAa,CAAC,EAAE;QACd,GAAG,EAAE,GAAG,CAAC;KACV,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,IAAI,0BAA0B,CAAC;IAEvC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;KACnD,CAAC,CAAC;CACJ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-write/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,GAAG,CAAC;KACX,CAAC;IACF,aAAa,CAAC,EAAE;QACd,GAAG,EAAE,GAAG,CAAC;KACV,CAAC;CACH,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAEzC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAE9C;;;;;;;OAOG;IACH,QAAQ,IAAI,0BAA0B,CAAC;IAEvC;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,OAAO,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;KACnD,CAAC,CAAC;CACJ,CAAC"}

package/dist/builders/shared/batch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared helpers for BatchGet / BatchWrite chunking + retry.
+ *
+ * DynamoDB caps batch operations at 100 items per BatchGetItem and 25 items
+ * per BatchWriteItem, *across all tables combined*. The service can also
+ * return UnprocessedItems / UnprocessedKeys when throttled or when the 16MB
+ * response limit is hit. This module centralises the chunking, the
+ * exponential-backoff retry, and the typed error so the two builders behave
+ * the same way.
+ */
+export declare const BATCH_WRITE_LIMIT = 25;
+export declare const BATCH_GET_LIMIT = 100;
+export declare const DEFAULT_MAX_RETRIES = 3;
+export declare const DEFAULT_RETRY_BACKOFF_MS = 50;
+/**
+ * Thrown when a BatchGet / BatchWrite still has unprocessed items / keys
+ * after the configured number of retries.
+ *
+ * The `unprocessed` payload mirrors the shape DynamoDB itself uses for
+ * `UnprocessedItems` / `UnprocessedKeys`, so the caller can re-issue the
+ * request manually if they want.
+ */
+export declare class BatchUnprocessedError extends Error {
+    readonly unprocessed: Record<string, any>;
+    constructor(message: string, unprocessed: Record<string, any>);
+}
+/**
+ * Splits a `(tableName -> items[])` map into chunks of at most `limit` items
+ * total across all tables. Each chunk is itself a `(tableName -> items[])` map,
+ * preserving the original per-table grouping.
+ *
+ * Items are emitted in iteration order: every item of the first table, then
+ * the second, etc. The relative order within a table is preserved.
+ */
+export declare function chunkRequestItems<T>(requestItems: Record<string, T[]>, limit: number): Record<string, T[]>[];
+/**
+ * Returns true when the SDK's UnprocessedItems / UnprocessedKeys map is
+ * empty (either undefined, no keys, or every per-table array empty).
+ */
+export declare function isUnprocessedEmpty(unprocessed: Record<string, any> | undefined): boolean;
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Backoff for retry attempt N (0-indexed): `initial * 2^N` ms.
+ */
+export declare function backoffMs(attempt: number, initial: number): number;
+//# sourceMappingURL=batch.d.ts.map

package/dist/builders/shared/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/batch.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAErC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAS9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAoBvB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAUxF;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/builders/shared/batch.js

@@ -0,0 +1,101 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Shared helpers for BatchGet / BatchWrite chunking + retry.
+ *
+ * DynamoDB caps batch operations at 100 items per BatchGetItem and 25 items
+ * per BatchWriteItem, *across all tables combined*. The service can also
+ * return UnprocessedItems / UnprocessedKeys when throttled or when the 16MB
+ * response limit is hit. This module centralises the chunking, the
+ * exponential-backoff retry, and the typed error so the two builders behave
+ * the same way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchUnprocessedError = exports.DEFAULT_RETRY_BACKOFF_MS = exports.DEFAULT_MAX_RETRIES = exports.BATCH_GET_LIMIT = exports.BATCH_WRITE_LIMIT = void 0;
+exports.chunkRequestItems = chunkRequestItems;
+exports.isUnprocessedEmpty = isUnprocessedEmpty;
+exports.sleep = sleep;
+exports.backoffMs = backoffMs;
+exports.BATCH_WRITE_LIMIT = 25;
+exports.BATCH_GET_LIMIT = 100;
+exports.DEFAULT_MAX_RETRIES = 3;
+exports.DEFAULT_RETRY_BACKOFF_MS = 50;
+/**
+ * Thrown when a BatchGet / BatchWrite still has unprocessed items / keys
+ * after the configured number of retries.
+ *
+ * The `unprocessed` payload mirrors the shape DynamoDB itself uses for
+ * `UnprocessedItems` / `UnprocessedKeys`, so the caller can re-issue the
+ * request manually if they want.
+ */
+class BatchUnprocessedError extends Error {
+    unprocessed;
+    constructor(message, unprocessed) {
+        super(message);
+        this.name = 'BatchUnprocessedError';
+        this.unprocessed = unprocessed;
+        // Preserve stack on V8.
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, BatchUnprocessedError);
+        }
+    }
+}
+exports.BatchUnprocessedError = BatchUnprocessedError;
+/**
+ * Splits a `(tableName -> items[])` map into chunks of at most `limit` items
+ * total across all tables. Each chunk is itself a `(tableName -> items[])` map,
+ * preserving the original per-table grouping.
+ *
+ * Items are emitted in iteration order: every item of the first table, then
+ * the second, etc. The relative order within a table is preserved.
+ */
+function chunkRequestItems(requestItems, limit) {
+    const flat = [];
+    for (const [tableName, items] of Object.entries(requestItems)) {
+        for (const item of items) {
+            flat.push({ tableName, item });
+        }
+    }
+    if (flat.length === 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < flat.length; i += limit) {
+        const slice = flat.slice(i, i + limit);
+        const grouped = {};
+        for (const { tableName, item } of slice) {
+            if (!grouped[tableName])
+                grouped[tableName] = [];
+            grouped[tableName].push(item);
+        }
+        chunks.push(grouped);
+    }
+    return chunks;
+}
+/**
+ * Returns true when the SDK's UnprocessedItems / UnprocessedKeys map is
+ * empty (either undefined, no keys, or every per-table array empty).
+ */
+function isUnprocessedEmpty(unprocessed) {
+    if (!unprocessed)
+        return true;
+    const keys = Object.keys(unprocessed);
+    if (keys.length === 0)
+        return true;
+    return keys.every((k) => {
+        const v = unprocessed[k];
+        if (Array.isArray(v))
+            return v.length === 0;
+        if (v && Array.isArray(v.Keys))
+            return v.Keys.length === 0;
+        return false;
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Backoff for retry attempt N (0-indexed): `initial * 2^N` ms.
+ */
+function backoffMs(attempt, initial) {
+    return initial * 2 ** attempt;
+}

package/dist/builders/shared/index.d.ts

@@ -2,4 +2,5 @@ export * from './types';
 export * from './operators';
 export * from './conditions';
 export * from './projection';
+export { BatchUnprocessedError, BATCH_WRITE_LIMIT, BATCH_GET_LIMIT, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_MS, chunkRequestItems, isUnprocessedEmpty, backoffMs, sleep, } from './batch';
 //# sourceMappingURL=index.d.ts.map

package/dist/builders/shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,KAAK,GACN,MAAM,SAAS,CAAC"}

package/dist/builders/shared/index.js

@@ -14,7 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = exports.backoffMs = exports.isUnprocessedEmpty = exports.chunkRequestItems = exports.DEFAULT_RETRY_BACKOFF_MS = exports.DEFAULT_MAX_RETRIES = exports.BATCH_GET_LIMIT = exports.BATCH_WRITE_LIMIT = exports.BatchUnprocessedError = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./operators"), exports);
 __exportStar(require("./conditions"), exports);
 __exportStar(require("./projection"), exports);
+var batch_1 = require("./batch");
+Object.defineProperty(exports, "BatchUnprocessedError", { enumerable: true, get: function () { return batch_1.BatchUnprocessedError; } });
+Object.defineProperty(exports, "BATCH_WRITE_LIMIT", { enumerable: true, get: function () { return batch_1.BATCH_WRITE_LIMIT; } });
+Object.defineProperty(exports, "BATCH_GET_LIMIT", { enumerable: true, get: function () { return batch_1.BATCH_GET_LIMIT; } });
+Object.defineProperty(exports, "DEFAULT_MAX_RETRIES", { enumerable: true, get: function () { return batch_1.DEFAULT_MAX_RETRIES; } });
+Object.defineProperty(exports, "DEFAULT_RETRY_BACKOFF_MS", { enumerable: true, get: function () { return batch_1.DEFAULT_RETRY_BACKOFF_MS; } });
+Object.defineProperty(exports, "chunkRequestItems", { enumerable: true, get: function () { return batch_1.chunkRequestItems; } });
+Object.defineProperty(exports, "isUnprocessedEmpty", { enumerable: true, get: function () { return batch_1.isUnprocessedEmpty; } });
+Object.defineProperty(exports, "backoffMs", { enumerable: true, get: function () { return batch_1.backoffMs; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return batch_1.sleep; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",