@ftschopp/dynatable-core 1.4.4 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## @ftschopp/dynatable-core [1.5.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.5.0...@ftschopp/dynatable-core@1.5.1) (2026-05-10)
+
+
+### Bug Fixes
+
+* **core:** close cleanInternalKeys gaps — derive from schema; cover put/query ([#41](https://github.com/ftschopp/dynatable/issues/41)) ([b429f36](https://github.com/ftschopp/dynatable/commit/b429f360ef70fec9612bc983b14903f2d1c1df91))
+
+# @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/query/create-query-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-query-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/query/create-query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAiB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA8a7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA6BrB"}
+{"version":3,"file":"create-query-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/query/create-query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAiB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAub7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA6BrB"}

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

@@ -99,7 +99,15 @@ function separateConditions(condition, model, indexName) {
             }
             return;
         }
-        // It's a leaf condition - check if it's a key field
+        // It's a leaf condition - check if it's a key field. A negated leaf
+        // (`op.not(op.eq(attr.x, …))`) can never be a KeyConditionExpression
+        // — DynamoDB's KeyConditionExpression grammar has no NOT — and
+        // dropping the negation would silently change query semantics. Keep
+        // it as a filter so the negation is honored.
+        if (cond.isNegated) {
+            filterConditions.push(cond);
+            return;
+        }
         // Extract field name from the expression (e.g., "#username" -> "username")
         const fieldMatch = cond.expression.match(/#(\w+)/);
         if (fieldMatch && fieldMatch[1]) {

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;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"}
+{"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,CAmXtB"}

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

@@ -196,6 +196,16 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 updateParts.push(`DELETE ${deleteExpressions.join(', ')}`);
             }
             const updateExpression = updateParts.join(' ');
+            // DynamoDB rejects an UpdateCommand without an UpdateExpression
+            // ("ValidationException: ExpressionAttributeNames must not be empty"
+            // or worse, "Member must not be null"). Throw a clearer error
+            // before the request leaves the process so the caller knows they
+            // forgot to call .set/.add/.remove/.delete.
+            if (!updateExpression) {
+                throw new Error('Update has no SET, REMOVE, ADD, or DELETE actions. Add at least one ' +
+                    'before calling dbParams() / execute(). To check for existence without ' +
+                    'modifying anything, use a get() instead.');
+            }
             // Build ConditionExpression from conditions
             let conditionExpression = '';
             let conditionNames = {};

package/dist/entity/create-entity-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAyLtE,CAAC"}
+{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CA4NtE,CAAC"}

package/dist/entity/create-entity-api.js

@@ -18,9 +18,10 @@ const key_validation_1 = require("./validation/key-validation");
  * @returns EntityAPI with get, put, query, scan, update, delete, batchGet, and batchWrite methods
  */
 const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
-    const { logger, timestamps = false, cleanInternalKeys = false } = options;
+    const { logger, timestamps = false, cleanInternalKeys = false, internalKeys } = options;
     // Build a Zod schema from the model
     const zodSchema = (0, zod_utils_1.modelToZod)(model);
+    const cleanKeysMiddleware = (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys, internalKeys);
     return {
         get(key) {
             // Validate key fields
@@ -28,7 +29,7 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             // Resolve any key defaults or computed keys
             const fullKey = (0, model_utils_1.resolveKeys)(model, key);
             const builder = (0, builders_1.createGetBuilder)(tableName, fullKey, client, undefined, logger);
-            return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         put(item) {
             // Validate full input data
@@ -46,13 +47,29 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
                 ...fullKey,
                 _type: modelName, // Add entity type identifier
             };
-            return (0, builders_1.createPutBuilder)(tableName, fullItem, client, [], false, 'NONE', false, logger);
+            const builder = (0, builders_1.createPutBuilder)(tableName, fullItem, client, [], false, 'NONE', false, logger);
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         query() {
             // Auto-filter by entity type so query() only returns items for this
             // entity. Without this, queries on shared GSIs return items from other
             // entities that share the same partition key.
-            return (0, builders_1.createQueryBuilder)(tableName, client, model, logger, modelName);
+            const builder = (0, builders_1.createQueryBuilder)(tableName, client, model, logger, modelName);
+            // QueryBuilder exposes only `where()` — the executable surface lives
+            // on the QueryExecutor it returns. Wrap that executor's `execute()`
+            // so cleanInternalKeys is honored on the common direct path.
+            //
+            // KNOWN LIMITATION: chained executor calls (`.limit()`, `.useIndex()`,
+            // etc.) recreate a fresh executor without the wrap, and
+            // `executeWithPagination()` / `iterate()` are not wrapped at all.
+            // This matches the pre-existing behavior of scan/update/delete and is
+            // tracked as a follow-up — pushing cleanup down into the builders
+            // themselves is the proper fix.
+            return {
+                where(fn) {
+                    return (0, with_middleware_1.withMiddleware)(builder.where(fn), cleanKeysMiddleware);
+                },
+            };
         },
         scan() {
             // Auto-filter by entity type so scan only returns items for this entity
@@ -62,7 +79,7 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
                 values: { ':_type': modelName },
             };
             const builder = (0, builders_1.createScanBuilder)(tableName, client, [typeFilter], [], undefined, false, undefined, undefined, undefined, logger);
-            return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         update(key) {
             // Validate key fields
@@ -73,7 +90,7 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             // Carry the original template-vars-bearing key (e.g. { username: 'jane' })
             // so the builder can recompute index keys when .set() touches their template fields.
             { model, keyVars: key });
-            return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         delete(key) {
             // Validate key fields
@@ -81,7 +98,7 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             // Resolve any key defaults or computed keys
             const fullKey = (0, model_utils_1.resolveKeys)(model, key);
             const builder = (0, builders_1.createDeleteBuilder)(tableName, fullKey, client, [], 'NONE', logger);
-            return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         batchGet(keys) {
             // Process all keys and validate them
@@ -98,7 +115,7 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
                 },
             };
             const builder = (0, builders_1.createBatchGetBuilder)(requestItems, client, undefined, logger);
-            return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
+            return (0, with_middleware_1.withMiddleware)(builder, cleanKeysMiddleware);
         },
         batchWrite(items) {
             // Validate and process all items

package/dist/entity/middleware/factories.d.ts

@@ -1,6 +1,12 @@
 import { ExecutionMiddleware } from './types';
 /**
- * Creates middleware configuration for cleaning internal keys
+ * Creates middleware configuration for cleaning internal keys.
+ *
+ * @param shouldClean - When false, returns a no-op middleware.
+ * @param internalKeys - Optional schema-derived list of column names to
+ *   strip. Falls back to the default `['PK', 'SK', '_type']` when omitted,
+ *   which is only correct for schemas that follow the conventional naming
+ *   AND have no secondary indexes whose columns leak into returned items.
  */
-export declare function createCleanKeysMiddleware(shouldClean: boolean): ExecutionMiddleware;
+export declare function createCleanKeysMiddleware(shouldClean: boolean, internalKeys?: readonly string[]): ExecutionMiddleware;
 //# sourceMappingURL=factories.d.ts.map

package/dist/entity/middleware/factories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../../src/entity/middleware/factories.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,mBAAmB,CAQnF"}
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../../src/entity/middleware/factories.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,mBAAmB,CAQrB"}

package/dist/entity/middleware/factories.js

@@ -3,13 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCleanKeysMiddleware = createCleanKeysMiddleware;
 const model_utils_1 = require("../../utils/model-utils");
 /**
- * Creates middleware configuration for cleaning internal keys
+ * Creates middleware configuration for cleaning internal keys.
+ *
+ * @param shouldClean - When false, returns a no-op middleware.
+ * @param internalKeys - Optional schema-derived list of column names to
+ *   strip. Falls back to the default `['PK', 'SK', '_type']` when omitted,
+ *   which is only correct for schemas that follow the conventional naming
+ *   AND have no secondary indexes whose columns leak into returned items.
  */
-function createCleanKeysMiddleware(shouldClean) {
+function createCleanKeysMiddleware(shouldClean, internalKeys) {
     if (!shouldClean) {
         return {};
     }
     return {
-        after: (result) => (0, model_utils_1.stripInternalKeys)(result),
+        after: (result) => (0, model_utils_1.stripInternalKeys)(result, internalKeys),
     };
 }

package/dist/entity/types.d.ts

@@ -7,6 +7,14 @@ export type EntityAPIOptions = {
     logger?: DynamoDBLogger;
     timestamps?: boolean;
     cleanInternalKeys?: boolean;
+    /**
+     * Schema-derived list of column names that `cleanInternalKeys` should
+     * strip from returned items. When omitted, falls back to the default
+     * `['PK', 'SK', '_type']` — which misses GSI/LSI columns and any
+     * primary key not literally named `PK` / `SK`. The Table constructor
+     * always populates this from `schema.indexes`.
+     */
+    internalKeys?: readonly string[];
 };
 /**
  * Entity API interface for a model

package/dist/entity/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EACL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,IAAI;IAC9C;;;;OAIG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEpD;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;IAEjC;;;OAGG;IACH,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,iBAAiB,CAAC;CACnD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EACL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,IAAI;IAC9C;;;;OAIG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEpD;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;IAEjC;;;OAGG;IACH,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,iBAAiB,CAAC;CACnD,CAAC"}

package/dist/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAA8B,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EAA4B,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAAI;IACpD,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC;AAEjD;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,gBAAgB,IAAI;KAC1C,CAAC,IAAI,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,SAAS,CACjC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACpC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACpC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACxC;CACF,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,KAAK,CAAC,CAAC,SAAS,gBAAgB;IAC3C,4BAA4B;IAC5B,SAAgB,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEvC,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAuBlC;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,oBAAoB;IAIrC;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,kBAAkB;CAGlC"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAA8B,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EAA4B,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGzD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAAI;IACpD,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC;AAEjD;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,gBAAgB,IAAI;KAC1C,CAAC,IAAI,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,SAAS,CACjC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACpC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACpC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACxC;CACF,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,KAAK,CAAC,CAAC,SAAS,gBAAgB;IAC3C,4BAA4B;IAC5B,SAAgB,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEvC,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IA+BlC;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,oBAAoB;IAIrC;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,kBAAkB;CAGlC"}

package/dist/table.js

@@ -4,6 +4,7 @@ exports.Table = void 0;
 const entity_1 = require("./entity");
 const transact_write_1 = require("./builders/transact-write");
 const transact_get_1 = require("./builders/transact-get");
+const model_utils_1 = require("./utils/model-utils");
 /**
  * Represents a typed DynamoDB Table with entity APIs
  *
@@ -18,6 +19,12 @@ class Table {
     constructor(config) {
         const { client, schema, logger, name: tableName } = config;
         this.client = client;
+        // Derive the full list of internal column names (primary + every GSI/LSI
+        // hash & sort key, plus the `_type` discriminator) once, from the schema
+        // itself. This way `cleanInternalKeys` strips GSI columns like
+        // `GSI1PK`/`GSI1SK` that the hardcoded fallback misses, and also works
+        // for schemas that use non-conventional primary key names.
+        const internalKeys = (0, model_utils_1.collectInternalKeyColumns)(schema.indexes);
         const rawEntities = {};
         for (const modelName in schema.models) {
             const model = schema.models[modelName];
@@ -28,6 +35,7 @@ class Table {
                 logger,
                 timestamps: schema.params?.timestamps ?? false,
                 cleanInternalKeys: schema.params?.cleanInternalKeys ?? false,
+                internalKeys,
             });
         }
         this.entities = rawEntities;

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

@@ -1,4 +1,4 @@
-import { InferModel, ModelDefinition } from '../core/types';
+import { IndexesDefinition, InferModel, ModelDefinition } from '../core/types';
 /**
  * Extracts all variable names from a template string
  * @param template - Template string with ${variable} syntax
@@ -49,6 +49,18 @@ export declare const applyPostDefaults: <M extends ModelDefinition>(model: M, va
     isUpdate?: boolean;
     timestamps?: boolean;
 }) => InferModel<M>;
+/**
+ * Derives the list of column names that should be stripped from returned
+ * items when `cleanInternalKeys` is enabled, based on the schema's index
+ * configuration. Returns the union of every index's hash + sort columns
+ * plus the `_type` discriminator.
+ *
+ * Examples:
+ * - `{ primary: { hash: 'PK', sort: 'SK' }, gsi1: { hash: 'GSI1PK', sort: 'GSI1SK' } }`
+ *   → `['PK', 'SK', 'GSI1PK', 'GSI1SK', '_type']`
+ * - `{ primary: { hash: 'pk', sort: 'sk' } }` → `['pk', 'sk', '_type']`
+ */
+export declare const collectInternalKeyColumns: (indexes: IndexesDefinition | undefined) => string[];
 /**
  * Removes internal DynamoDB keys from an item or array of items.
  *
@@ -58,7 +70,11 @@ export declare const applyPostDefaults: <M extends ModelDefinition>(model: M, va
  * passed through untouched — recursing into them would lose their type.
  *
  * @param data - Single item, array of items, or any nested value from DynamoDB
+ * @param internalKeys - Column names to strip. Defaults to `['PK', 'SK', '_type']`
+ *   for backwards compatibility; consumers operating on a real schema should
+ *   derive the list with {@link collectInternalKeyColumns} so GSI/LSI keys
+ *   and custom-named primary keys are also removed.
  * @returns Data with internal keys removed at every level
  */
-export declare const stripInternalKeys: <T>(data: T | T[] | undefined) => T | T[] | undefined;
+export declare const stripInternalKeys: <T>(data: T | T[] | undefined, internalKeys?: readonly string[]) => 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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAqB1E,CAAC"}
+{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG7F;;;;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;AAWF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,iBAAiB,GAAG,SAAS,KACrC,MAAM,EAUR,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EACjC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,EACzB,eAAc,SAAS,MAAM,EAA0B,KACtD,CAAC,GAAG,CAAC,EAAE,GAAG,SAqBZ,CAAC"}

package/dist/utils/model-utils.js

@@ -1,7 +1,7 @@
 "use strict";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripInternalKeys = exports.applyPostDefaults = exports.computeIndexUpdates = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
+exports.stripInternalKeys = exports.collectInternalKeyColumns = exports.applyPostDefaults = exports.computeIndexUpdates = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
 const ulid_1 = require("ulid");
 /**
  * Extracts all variable names from a template string
@@ -121,9 +121,38 @@ const applyPostDefaults = (model, validatedItem, options) => {
 };
 exports.applyPostDefaults = applyPostDefaults;
 /**
- * Internal DynamoDB keys that should be stripped when cleanInternalKeys is enabled
+ * Default fallback list used when the caller doesn't pass a schema-derived
+ * set. Covers only the conventional primary-key column names (PK, SK) and
+ * the entity-type discriminator. Real consumers should pass the
+ * schema-derived list returned by {@link collectInternalKeyColumns} so that
+ * GSI/LSI columns and custom-named primary keys are also stripped.
  */
-const INTERNAL_KEYS = ['PK', 'SK', '_type'];
+const DEFAULT_INTERNAL_KEYS = ['PK', 'SK', '_type'];
+/**
+ * Derives the list of column names that should be stripped from returned
+ * items when `cleanInternalKeys` is enabled, based on the schema's index
+ * configuration. Returns the union of every index's hash + sort columns
+ * plus the `_type` discriminator.
+ *
+ * Examples:
+ * - `{ primary: { hash: 'PK', sort: 'SK' }, gsi1: { hash: 'GSI1PK', sort: 'GSI1SK' } }`
+ *   → `['PK', 'SK', 'GSI1PK', 'GSI1SK', '_type']`
+ * - `{ primary: { hash: 'pk', sort: 'sk' } }` → `['pk', 'sk', '_type']`
+ */
+const collectInternalKeyColumns = (indexes) => {
+    const cols = new Set();
+    if (indexes) {
+        for (const idx of Object.values(indexes)) {
+            if (idx?.hash)
+                cols.add(idx.hash);
+            if (idx?.sort)
+                cols.add(idx.sort);
+        }
+    }
+    cols.add('_type');
+    return [...cols];
+};
+exports.collectInternalKeyColumns = collectInternalKeyColumns;
 /**
  * Removes internal DynamoDB keys from an item or array of items.
  *
@@ -133,23 +162,27 @@ const INTERNAL_KEYS = ['PK', 'SK', '_type'];
  * passed through untouched — recursing into them would lose their type.
  *
  * @param data - Single item, array of items, or any nested value from DynamoDB
+ * @param internalKeys - Column names to strip. Defaults to `['PK', 'SK', '_type']`
+ *   for backwards compatibility; consumers operating on a real schema should
+ *   derive the list with {@link collectInternalKeyColumns} so GSI/LSI keys
+ *   and custom-named primary keys are also removed.
  * @returns Data with internal keys removed at every level
  */
-const stripInternalKeys = (data) => {
+const stripInternalKeys = (data, internalKeys = DEFAULT_INTERNAL_KEYS) => {
     if (data === undefined || data === null) {
         return data;
     }
     if (Array.isArray(data)) {
-        return data.map((item) => (0, exports.stripInternalKeys)(item));
+        return data.map((item) => (0, exports.stripInternalKeys)(item, internalKeys));
     }
     // 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))
+            if (internalKeys.includes(key))
                 continue;
-            cleaned[key] = (0, exports.stripInternalKeys)(value);
+            cleaned[key] = (0, exports.stripInternalKeys)(value, internalKeys);
         }
         return cleaned;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../../src/utils/zod-utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAK,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,mBAAmB,KAAG,OAgCrD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,eAAe,KAAG,SAAS,CAAC,GAAG,CAMhE,CAAC"}
+{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../../src/utils/zod-utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAK,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,mBAAmB,KAAG,OAoCrD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,eAAe,KAAG,SAAS,CAAC,GAAG,CAMhE,CAAC"}

package/dist/utils/zod-utils.js

@@ -35,9 +35,13 @@ const typeToZod = (attr) => {
                     ? zod_1.z.number()
                     : attr.type === Boolean
                         ? zod_1.z.boolean()
-                        : attr.type === Date
-                            ? zod_1.z.date()
-                            : zod_1.z.unknown();
+                        : // applyPostDefaults stores Date values as ISO strings (e.g.
+                            // createdAt/updatedAt). Use coerce so reading back a stored
+                            // Date attribute through zod accepts both the ISO string we
+                            // wrote and a native Date the caller might pass on input.
+                            attr.type === Date
+                                ? zod_1.z.coerce.date()
+                                : zod_1.z.unknown();
     }
     const isGenerated = 'generate' in attr;
     return attr.required && !isGenerated ? zodType : zodType.optional();

package/package.json

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