@ftschopp/dynatable-core 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# @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)
+
+
+### Bug Fixes
+
+* **core:** detect SET-collisions on auto-recomputed index keys; stripInternalKeys recurses ([#38](https://github.com/ftschopp/dynatable/issues/38)) ([d609c5b](https://github.com/ftschopp/dynatable/commit/d609c5bbeb566145ec034ec9883246a6d77d7cf6)), closes [#17](https://github.com/ftschopp/dynatable/issues/17) [#GSI1](https://github.com/ftschopp/dynatable/issues/GSI1) [#GSI1](https://github.com/ftschopp/dynatable/issues/GSI1)
+
 ## @ftschopp/dynatable-core [1.4.3](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.2...@ftschopp/dynatable-core@1.4.3) (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/dist/builders/update/create-update-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-update-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/update/create-update-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,EACnB,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,aAAa,GAAE;IACb,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACuB,EAChD,UAAU,GAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAsB,EACnF,YAAY,SAAI,EAChB,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,EACvB,YAAY,CAAC,EAAE,YAAY,EAC3B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAClC,aAAa,CAAC,KAAK,CAAC,CAoVtB"}
+{"version":3,"file":"create-update-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/update/create-update-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAa7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,EACnB,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,aAAa,GAAE;IACb,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACuB,EAChD,UAAU,GAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAsB,EACnF,YAAY,SAAI,EAChB,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,EACvB,YAAY,CAAC,EAAE,YAAY,EAC3B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAClC,aAAa,CAAC,KAAK,CAAC,CAsWtB"}

package/dist/builders/update/create-update-builder.js

@@ -4,6 +4,15 @@ exports.createUpdateBuilder = createUpdateBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const shared_1 = require("../shared");
 const model_utils_1 = require("../../utils/model-utils");
+/**
+ * Pull the LHS attribute name out of a SET-action expression like
+ * `#GSI1PK = :v_0` → `'GSI1PK'`. Returns `undefined` for shapes the
+ * builder doesn't emit so callers can ignore them safely.
+ */
+function extractAttrName(action) {
+    const m = action.expression.match(/^\s*#([A-Za-z0-9_]+)\s*=/);
+    return m?.[1];
+}
 /**
  * Creates an UpdateBuilder for an item key and table.
  *
@@ -120,6 +129,22 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                         `but the templates cannot be fully resolved from the update payload. ` +
                         `Include the missing fields in .set():\n${details}`);
                 }
+                // If the user's `.set()` already targets the same index-key
+                // attribute (e.g. `.set('GSI1PK', 'foo')`), refuse to silently
+                // emit a second SET against the same path. DynamoDB rejects
+                // `SET #GSI1PK = :a, #GSI1PK = :b` outright, and namespacing the
+                // placeholders only hides which one wins. Force the caller to
+                // resolve the conflict explicitly.
+                const userSetKeys = new Set(actionsToProcess.set.map(extractAttrName));
+                userSetKeys.delete(undefined);
+                const conflicts = Object.keys(idxActions).filter((k) => userSetKeys.has(k));
+                if (conflicts.length > 0) {
+                    throw new Error(`Update would write the same secondary-index key twice: ` +
+                        `[${conflicts.join(', ')}] is recomputed from the index template AND ` +
+                        `set explicitly via .set(). Either remove the explicit .set() and let ` +
+                        `the recomputation handle it, or include all template variables in ` +
+                        `.set() so you take full control.`);
+                }
                 for (const [indexName, resolved] of Object.entries(idxActions)) {
                     const valueName = getUniqueValueName(indexName);
                     actionsToProcess.set.push({

package/dist/utils/model-utils.d.ts

@@ -50,9 +50,15 @@ export declare const applyPostDefaults: <M extends ModelDefinition>(model: M, va
     timestamps?: boolean;
 }) => InferModel<M>;
 /**
- * Removes internal DynamoDB keys from an item or array of items
- * @param data - Single item or array of items from DynamoDB
- * @returns Data with internal keys removed
+ * Removes internal DynamoDB keys from an item or array of items.
+ *
+ * Recurses into nested plain objects and arrays so an `_type` / `PK` / `SK`
+ * field embedded inside an attribute value (e.g. a denormalized snapshot
+ * of another entity) is also stripped. Class instances such as `Date` are
+ * passed through untouched — recursing into them would lose their type.
+ *
+ * @param data - Single item, array of items, or any nested value from DynamoDB
+ * @returns Data with internal keys removed at every level
  */
 export declare const stripInternalKeys: <T>(data: T | T[] | undefined) => T | T[] | undefined;
 //# sourceMappingURL=model-utils.d.ts.map

package/dist/utils/model-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,eAAe,EAC3D,OAAO,CAAC,EACR,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,mBAwBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAiCd,CAAC;AAOF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAoB1E,CAAC"}
+{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,eAAe,EAC3D,OAAO,CAAC,EACR,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,mBAwBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAiCd,CAAC;AAOF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAqB1E,CAAC"}

package/dist/utils/model-utils.js

@@ -125,9 +125,15 @@ exports.applyPostDefaults = applyPostDefaults;
  */
 const INTERNAL_KEYS = ['PK', 'SK', '_type'];
 /**
- * Removes internal DynamoDB keys from an item or array of items
- * @param data - Single item or array of items from DynamoDB
- * @returns Data with internal keys removed
+ * Removes internal DynamoDB keys from an item or array of items.
+ *
+ * Recurses into nested plain objects and arrays so an `_type` / `PK` / `SK`
+ * field embedded inside an attribute value (e.g. a denormalized snapshot
+ * of another entity) is also stripped. Class instances such as `Date` are
+ * passed through untouched — recursing into them would lose their type.
+ *
+ * @param data - Single item, array of items, or any nested value from DynamoDB
+ * @returns Data with internal keys removed at every level
  */
 const stripInternalKeys = (data) => {
     if (data === undefined || data === null) {
@@ -136,12 +142,14 @@ const stripInternalKeys = (data) => {
     if (Array.isArray(data)) {
         return data.map((item) => (0, exports.stripInternalKeys)(item));
     }
-    if (typeof data === 'object') {
+    // Only recurse into plain objects; preserve Date, Buffer, Set, Map,
+    // and anything else with a non-Object prototype.
+    if (typeof data === 'object' && Object.getPrototypeOf(data) === Object.prototype) {
         const cleaned = {};
         for (const [key, value] of Object.entries(data)) {
-            if (!INTERNAL_KEYS.includes(key)) {
-                cleaned[key] = value;
-            }
+            if (INTERNAL_KEYS.includes(key))
+                continue;
+            cleaned[key] = (0, exports.stripInternalKeys)(value);
         }
         return cleaned;
     }

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "README.md",
@@ -15,6 +22,7 @@
   "scripts": {
     "build": "tsc && tsc-alias",
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "lint": "eslint src",
     "test": "jest",
     "prepublishOnly": "yarn build"
   },