@ftschopp/dynatable-core 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# @ftschopp/dynatable-core [1.6.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.5.2...@ftschopp/dynatable-core@1.6.0) (2026-05-10)
+
+
+### Features
+
+* **core:** expose ReturnConsumedCapacity on query/scan/update/put/delete ([#44](https://github.com/ftschopp/dynatable/issues/44)) ([048e52f](https://github.com/ftschopp/dynatable/commit/048e52f8172cd13a0ad1720e8c701af8bf20603d))
+
+## @ftschopp/dynatable-core [1.5.2](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.5.1...@ftschopp/dynatable-core@1.5.2) (2026-05-10)
+
+
+### Bug Fixes
+
+* **core:** guard primary-key template fields and non-set ops on GSI templates in update builder ([#42](https://github.com/ftschopp/dynatable/issues/42)) ([4487ff2](https://github.com/ftschopp/dynatable/commit/4487ff22ad507b37aa0e2e279a602a4813afddba))
+
 ## @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)
 
 

package/dist/builders/delete/create-delete-builder.d.ts

@@ -5,5 +5,5 @@ import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 /**
  * Creates a DeleteBuilder for an item key and table.
  */
-export declare function createDeleteBuilder<Model>(tableName: string, key: Partial<Model>, client: DynamoDBClient, prevConditions?: Condition[], returnMode?: 'NONE' | 'ALL_OLD', logger?: DynamoDBLogger): DeleteBuilder<Model>;
+export declare function createDeleteBuilder<Model>(tableName: string, key: Partial<Model>, client: DynamoDBClient, prevConditions?: Condition[], returnMode?: 'NONE' | 'ALL_OLD', logger?: DynamoDBLogger, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE'): DeleteBuilder<Model>;
 //# sourceMappingURL=create-delete-builder.d.ts.map

package/dist/builders/delete/create-delete-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-delete-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/delete/create-delete-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;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,UAAU,GAAE,MAAM,GAAG,SAAkB,EACvC,MAAM,CAAC,EAAE,cAAc,GACtB,aAAa,CAAC,KAAK,CAAC,CAkFtB"}
+{"version":3,"file":"create-delete-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/delete/create-delete-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;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,UAAU,GAAE,MAAM,GAAG,SAAkB,EACvC,MAAM,CAAC,EAAE,cAAc,EACvB,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAC9C,aAAa,CAAC,KAAK,CAAC,CAwGtB"}

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

@@ -6,7 +6,7 @@ const shared_1 = require("../shared");
 /**
  * Creates a DeleteBuilder for an item key and table.
  */
-function createDeleteBuilder(tableName, key, client, prevConditions = [], returnMode = 'NONE', logger) {
+function createDeleteBuilder(tableName, key, client, prevConditions = [], returnMode = 'NONE', logger, consumedCapacity) {
     const conditions = [...prevConditions];
     const build = () => ({
         where(fn) {
@@ -17,10 +17,13 @@ function createDeleteBuilder(tableName, key, client, prevConditions = [], return
             });
             const opBuilder = (0, shared_1.createOpBuilder)();
             const condition = fn(attrs, opBuilder);
-            return createDeleteBuilder(tableName, key, client, [...conditions, condition], returnMode, logger);
+            return createDeleteBuilder(tableName, key, client, [...conditions, condition], returnMode, logger, consumedCapacity);
         },
         returning(mode) {
-            return createDeleteBuilder(tableName, key, client, conditions, mode, logger);
+            return createDeleteBuilder(tableName, key, client, conditions, mode, logger, consumedCapacity);
+        },
+        returnConsumedCapacity(mode) {
+            return createDeleteBuilder(tableName, key, client, conditions, returnMode, logger, mode);
         },
         dbParams() {
             // Build ConditionExpression from condition tree
@@ -53,6 +56,7 @@ function createDeleteBuilder(tableName, key, client, prevConditions = [], return
                 ...(Object.keys(expressionAttributeValues).length && {
                     ExpressionAttributeValues: expressionAttributeValues,
                 }),
+                ...(consumedCapacity && { ReturnConsumedCapacity: consumedCapacity }),
                 ...extra,
             };
         },

package/dist/builders/delete/types.d.ts

@@ -8,6 +8,15 @@ export interface DeleteBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbP
      * Configures what values should be returned after the delete operation
      */
     returning(mode: 'NONE' | 'ALL_OLD'): DeleteBuilder<Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter so DynamoDB reports
+     * how many WCUs the delete consumed. Useful for diagnosing throttling.
+     *
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): DeleteBuilder<Model>;
     /**
      * Converts the builder state to DynamoDB DeleteItem parameters
      */

package/dist/builders/delete/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/delete/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/delete/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;;;;;;OAOG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjF;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}

package/dist/builders/put/create-put-builder.d.ts

@@ -5,5 +5,5 @@ import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 /**
  * Creates a PutBuilder for an item and table.
  */
-export declare function createPutBuilder<Model>(tableName: string, item: Model, client: DynamoDBClient, prevConditions?: Condition[], shouldCheckNotExists?: boolean, returnMode?: 'NONE' | 'ALL_OLD', enableTimestamps?: boolean, logger?: DynamoDBLogger): PutBuilder<Model>;
+export declare function createPutBuilder<Model>(tableName: string, item: Model, client: DynamoDBClient, prevConditions?: Condition[], shouldCheckNotExists?: boolean, returnMode?: 'NONE' | 'ALL_OLD', enableTimestamps?: boolean, logger?: DynamoDBLogger, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE'): PutBuilder<Model>;
 //# sourceMappingURL=create-put-builder.d.ts.map

package/dist/builders/put/create-put-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-put-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/put/create-put-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAgB7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,oBAAoB,UAAQ,EAC5B,UAAU,GAAE,MAAM,GAAG,SAAkB,EACvC,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,KAAK,CAAC,CA8HnB"}
+{"version":3,"file":"create-put-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/put/create-put-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAgB7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,oBAAoB,UAAQ,EAC5B,UAAU,GAAE,MAAM,GAAG,SAAkB,EACvC,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,EACvB,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAC9C,UAAU,CAAC,KAAK,CAAC,CAgJnB"}

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

@@ -18,7 +18,7 @@ function buildNotExistsConditions(item) {
 /**
  * Creates a PutBuilder for an item and table.
  */
-function createPutBuilder(tableName, item, client, prevConditions = [], shouldCheckNotExists = false, returnMode = 'NONE', enableTimestamps = false, logger) {
+function createPutBuilder(tableName, item, client, prevConditions = [], shouldCheckNotExists = false, returnMode = 'NONE', enableTimestamps = false, logger, consumedCapacity) {
     const conditions = [...prevConditions];
     const build = () => ({
         where(fn) {
@@ -30,13 +30,16 @@ function createPutBuilder(tableName, item, client, prevConditions = [], shouldCh
             // Create a scoped opBuilder for this operation to avoid global state
             const opBuilder = (0, shared_1.createOpBuilder)();
             const condition = fn(attrs, opBuilder);
-            return createPutBuilder(tableName, item, client, [...conditions, condition], shouldCheckNotExists, returnMode, enableTimestamps, logger);
+            return createPutBuilder(tableName, item, client, [...conditions, condition], shouldCheckNotExists, returnMode, enableTimestamps, logger, consumedCapacity);
         },
         ifNotExists() {
-            return createPutBuilder(tableName, item, client, conditions, true, returnMode, enableTimestamps, logger);
+            return createPutBuilder(tableName, item, client, conditions, true, returnMode, enableTimestamps, logger, consumedCapacity);
         },
         returning(mode) {
-            return createPutBuilder(tableName, item, client, conditions, shouldCheckNotExists, mode, enableTimestamps, logger);
+            return createPutBuilder(tableName, item, client, conditions, shouldCheckNotExists, mode, enableTimestamps, logger, consumedCapacity);
+        },
+        returnConsumedCapacity(mode) {
+            return createPutBuilder(tableName, item, client, conditions, shouldCheckNotExists, returnMode, enableTimestamps, logger, mode);
         },
         dbParams() {
             let finalConditions = [...conditions];
@@ -85,6 +88,7 @@ function createPutBuilder(tableName, item, client, prevConditions = [], shouldCh
                 ...(Object.keys(expressionAttributeValues).length && {
                     ExpressionAttributeValues: expressionAttributeValues,
                 }),
+                ...(consumedCapacity && { ReturnConsumedCapacity: consumedCapacity }),
                 ...extra,
             };
         },

package/dist/builders/put/types.d.ts

@@ -14,6 +14,16 @@ export interface PutBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbPara
      * - ALL_OLD: Returns the item as it was before being replaced (if it existed)
      */
     returning(mode: 'NONE' | 'ALL_OLD'): PutBuilder<Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter so DynamoDB reports
+     * how many WCUs the put consumed. Useful for diagnosing throttling and
+     * accounting for index amplification on tables with multiple GSIs.
+     *
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): PutBuilder<Model>;
     /**
      * Converts the builder state to DynamoDB PutItem parameters
      */

package/dist/builders/put/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/put/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAClF;;OAEG;IACH,WAAW,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAEjC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAEvD;;OAEG;IACH,QAAQ,IAAI,eAAe,CAAC;CAC7B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/put/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAClF;;OAEG;IACH,WAAW,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAEjC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAEvD;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAE9E;;OAEG;IACH,QAAQ,IAAI,eAAe,CAAC;CAC7B"}

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

@@ -23,6 +23,21 @@ function keyBelongsToIndex(keyName, keyDef, indexName) {
     }
     return keyName === `${indexName}PK` || keyName === `${indexName}SK`;
 }
+/**
+ * Cache of compiled `#<fieldName>\b` regexes used to rewrite a leaf
+ * condition's expression when its field maps onto a key. Without this,
+ * `separateConditions` allocates a fresh `RegExp` per AND-leaf per query —
+ * cheap individually, noisy under load on multi-condition queries.
+ */
+const fieldPlaceholderRegexCache = new Map();
+function fieldPlaceholderRegex(fieldName) {
+    let re = fieldPlaceholderRegexCache.get(fieldName);
+    if (!re) {
+        re = new RegExp(`#${fieldName}\\b`, 'g');
+        fieldPlaceholderRegexCache.set(fieldName, re);
+    }
+    return re;
+}
 /**
  * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
  * Also returns the key template for value transformation
@@ -127,7 +142,7 @@ function separateConditions(condition, model, indexName) {
                 }
                 const rewrittenCond = {
                     ...cond,
-                    expression: cond.expression.replace(new RegExp(`#${fieldName}\\b`, 'g'), `#${keyInfo.keyName}`),
+                    expression: cond.expression.replace(fieldPlaceholderRegex(fieldName), `#${keyInfo.keyName}`),
                     names: {
                         [`#${keyInfo.keyName}`]: keyInfo.keyName,
                     },
@@ -209,6 +224,12 @@ function createQueryExecutor(state) {
                 exclusiveStartKey: key,
             });
         },
+        returnConsumedCapacity(mode) {
+            return createQueryExecutor({
+                ...state,
+                returnConsumedCapacity: mode,
+            });
+        },
         dbParams() {
             if (!state.condition) {
                 throw new Error('No where condition specified');
@@ -307,6 +328,9 @@ function createQueryExecutor(state) {
                 ...(state.exclusiveStartKey && {
                     ExclusiveStartKey: state.exclusiveStartKey,
                 }),
+                ...(state.returnConsumedCapacity && {
+                    ReturnConsumedCapacity: state.returnConsumedCapacity,
+                }),
             };
         },
         /**

package/dist/builders/query/types.d.ts

@@ -48,6 +48,16 @@ export interface QueryExecutor<Model> extends ExecutableBuilder<Model[]> {
      * Start query from a specific key (for pagination)
      */
     startFrom(key: Record<string, any>): QueryExecutor<Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter so DynamoDB reports
+     * how many RCUs the query consumed. Useful for diagnosing throttling
+     * and confirming a query hit the expected (G)SI.
+     *
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): QueryExecutor<Model>;
     /**
      * Returns the raw DynamoDB query parameters
      */

package/dist/builders/query/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/query/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC;;OAEG;IACH,KAAK,EAAE,KAAK,EAAE,CAAC;IAEf;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEvC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACtE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE3C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEzD;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAElD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAErD;;OAEG;IACH,cAAc,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;IAEvC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,QAAQ,IAAI,GAAG,CAAC;IAEhB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE5B;;OAEG;IACH,qBAAqB,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAErD;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;CACzF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/query/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC;;OAEG;IACH,KAAK,EAAE,KAAK,EAAE,CAAC;IAEf;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEvC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACtE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE3C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEzD;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAElD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAErD;;OAEG;IACH,cAAc,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;IAEvC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjF;;OAEG;IACH,QAAQ,IAAI,GAAG,CAAC;IAEhB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE5B;;OAEG;IACH,qBAAqB,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAErD;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;CACzF"}

package/dist/builders/scan/create-scan-builder.d.ts

@@ -8,5 +8,5 @@ import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 export declare function createScanBuilder<Model>(tableName: string, client: DynamoDBClient, filters?: Condition[], projectionAttrs?: (keyof Model)[], limitValue?: number, isConsistentRead?: boolean, indexName?: string, exclusiveStartKey?: Record<string, any>, segmentConfig?: {
     segment: number;
     totalSegments: number;
-}, logger?: DynamoDBLogger): ScanBuilder<Model>;
+}, logger?: DynamoDBLogger, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE'): ScanBuilder<Model>;
 //# sourceMappingURL=create-scan-builder.d.ts.map

package/dist/builders/scan/create-scan-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-scan-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/create-scan-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAGL,SAAS,EAGV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,SAAS,EAAO,EACzB,eAAe,GAAE,CAAC,MAAM,KAAK,CAAC,EAAO,EACrC,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,UAAQ,EACxB,SAAS,CAAC,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvC,aAAa,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,CAAC,EAAE,cAAc,GACtB,WAAW,CAAC,KAAK,CAAC,CA6OpB"}
+{"version":3,"file":"create-scan-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/create-scan-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAGL,SAAS,EAGV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,SAAS,EAAO,EACzB,eAAe,GAAE,CAAC,MAAM,KAAK,CAAC,EAAO,EACrC,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,UAAQ,EACxB,SAAS,CAAC,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvC,aAAa,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,CAAC,EAAE,cAAc,EACvB,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAC9C,WAAW,CAAC,KAAK,CAAC,CAwQpB"}

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

@@ -6,7 +6,7 @@ const shared_1 = require("../shared");
 /**
  * Creates a ScanBuilder for scanning a table or index.
  */
-function createScanBuilder(tableName, client, filters = [], projectionAttrs = [], limitValue, isConsistentRead = false, indexName, exclusiveStartKey, segmentConfig, logger) {
+function createScanBuilder(tableName, client, filters = [], projectionAttrs = [], limitValue, isConsistentRead = false, indexName, exclusiveStartKey, segmentConfig, logger, consumedCapacity) {
     const build = () => ({
         filter(fn) {
             const attrs = new Proxy({}, {
@@ -16,25 +16,28 @@ function createScanBuilder(tableName, client, filters = [], projectionAttrs = []
             });
             const opBuilder = (0, shared_1.createOpBuilder)();
             const condition = fn(attrs, opBuilder);
-            return createScanBuilder(tableName, client, [...filters, condition], projectionAttrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger);
+            return createScanBuilder(tableName, client, [...filters, condition], projectionAttrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger, consumedCapacity);
         },
         select(attrs) {
-            return createScanBuilder(tableName, client, filters, attrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger);
+            return createScanBuilder(tableName, client, filters, attrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger, consumedCapacity);
         },
         limit(count) {
-            return createScanBuilder(tableName, client, filters, projectionAttrs, count, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger);
+            return createScanBuilder(tableName, client, filters, projectionAttrs, count, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger, consumedCapacity);
         },
         consistentRead() {
-            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, true, indexName, exclusiveStartKey, segmentConfig, logger);
+            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, true, indexName, exclusiveStartKey, segmentConfig, logger, consumedCapacity);
         },
         usingIndex(index) {
-            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, index, exclusiveStartKey, segmentConfig, logger);
+            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, index, exclusiveStartKey, segmentConfig, logger, consumedCapacity);
         },
         startFrom(key) {
-            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, indexName, key, segmentConfig, logger);
+            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, indexName, key, segmentConfig, logger, consumedCapacity);
         },
         segment(segmentNumber, totalSegments) {
-            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, { segment: segmentNumber, totalSegments }, logger);
+            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, { segment: segmentNumber, totalSegments }, logger, consumedCapacity);
+        },
+        returnConsumedCapacity(mode) {
+            return createScanBuilder(tableName, client, filters, projectionAttrs, limitValue, isConsistentRead, indexName, exclusiveStartKey, segmentConfig, logger, mode);
         },
         dbParams() {
             let filterExpression = '';
@@ -98,6 +101,9 @@ function createScanBuilder(tableName, client, filters = [], projectionAttrs = []
                 params.Segment = segmentConfig.segment;
                 params.TotalSegments = segmentConfig.totalSegments;
             }
+            if (consumedCapacity) {
+                params.ReturnConsumedCapacity = consumedCapacity;
+            }
             return params;
         },
         /**

package/dist/builders/scan/types.d.ts

@@ -52,6 +52,16 @@ export interface ScanBuilder<Model> extends ExecutableBuilder<Model[]> {
      * Returns a new immutable builder.
      */
     segment(segmentNumber: number, totalSegments: number): ScanBuilder<Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter so DynamoDB reports
+     * how many RCUs the scan consumed. Useful for diagnosing throttling
+     * and confirming filter selectivity.
+     *
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): ScanBuilder<Model>;
     /**
      * Executes a single Scan request and returns the page along with the
      * `lastEvaluatedKey` cursor and counts. Use this when you want to drive

package/dist/builders/scan/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK;IAC/B,mCAAmC;IACnC,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACvC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACpE;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEvF;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEnD;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEzC;;;OAGG;IACH,cAAc,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAErC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAElD;;;OAGG;IACH,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEtE;;;OAGG;IACH,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAE1E;;;;OAIG;IACH,qBAAqB,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;CACzC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK;IAC/B,mCAAmC;IACnC,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACvC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACpE;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEvF;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEnD;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEzC;;;OAGG;IACH,cAAc,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAErC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAElD;;;OAGG;IACH,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEtE;;;OAGG;IACH,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAE1E;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAE/E;;;;OAIG;IACH,qBAAqB,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;CACzC"}

package/dist/builders/update/create-update-builder.d.ts

@@ -16,5 +16,5 @@ export declare function createUpdateBuilder<Model>(tableName: string, key: Parti
     remove: UpdateAction[];
     add: UpdateAction[];
     delete: UpdateAction[];
-}, returnMode?: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW', valueCounter?: number, enableTimestamps?: boolean, logger?: DynamoDBLogger, indexContext?: IndexContext, setInputs?: Record<string, any>): UpdateBuilder<Model>;
+}, returnMode?: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW', valueCounter?: number, enableTimestamps?: boolean, logger?: DynamoDBLogger, indexContext?: IndexContext, setInputs?: Record<string, any>, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE'): UpdateBuilder<Model>;
 //# sourceMappingURL=create-update-builder.d.ts.map

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,CAmXtB"}
+{"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;AAyB7D;;;;;;;;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,EACnC,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAC9C,aAAa,CAAC,KAAK,CAAC,CAidtB"}

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

@@ -13,6 +13,18 @@ function extractAttrName(action) {
     const m = action.expression.match(/^\s*#([A-Za-z0-9_]+)\s*=/);
     return m?.[1];
 }
+/**
+ * Pull the attribute name from any update action (set / remove / add / delete).
+ * Each action emitted by this builder carries exactly one entry in `names`
+ * mapping `#<attr>` → `<attr>`, so the value side of that map is the source
+ * of truth regardless of the surrounding expression syntax.
+ */
+function actionAttrName(action) {
+    if (!action.names)
+        return undefined;
+    const values = Object.values(action.names);
+    return values[0];
+}
 /**
  * Creates an UpdateBuilder for an item key and table.
  *
@@ -22,7 +34,7 @@ function extractAttrName(action) {
  * cannot be fully resolved from the primary-key vars plus the updates, building
  * the params throws — the caller must include the missing fields in `.set()`.
  */
-function createUpdateBuilder(tableName, key, client, prevConditions = [], updateActions = { set: [], remove: [], add: [], delete: [] }, returnMode = 'NONE', valueCounter = 0, enableTimestamps = false, logger, indexContext, setInputs = {}) {
+function createUpdateBuilder(tableName, key, client, prevConditions = [], updateActions = { set: [], remove: [], add: [], delete: [] }, returnMode = 'NONE', valueCounter = 0, enableTimestamps = false, logger, indexContext, setInputs = {}, consumedCapacity) {
     const conditions = [...prevConditions];
     const getUniqueValueName = (baseName) => {
         return `${baseName}_${valueCounter++}`;
@@ -42,7 +54,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
             });
             const opBuilder = (0, shared_1.createOpBuilder)();
             const condition = fn(attrs, opBuilder);
-            return createUpdateBuilder(tableName, key, client, [...conditions, condition], updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs);
+            return createUpdateBuilder(tableName, key, client, [...conditions, condition], updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
         },
         set(attrOrUpdates, value) {
             // When no value is provided and the first arg is a plain object,
@@ -65,7 +77,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                     });
                     newSetInputs[attrName] = val;
                 }
-                return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, ...newActions] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, newSetInputs);
+                return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, ...newActions] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, newSetInputs, consumedCapacity);
             }
             // Single update case
             const attrName = normalizeAttr(attrOrUpdates);
@@ -75,7 +87,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, { ...setInputs, [attrName]: value });
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, { ...setInputs, [attrName]: value }, consumedCapacity);
         },
         remove(attr) {
             const attrName = normalizeAttr(attr);
@@ -83,7 +95,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 expression: `#${attrName}`,
                 names: { [`#${attrName}`]: attrName },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, remove: [...updateActions.remove, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, remove: [...updateActions.remove, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
         },
         add(attr, value) {
             const attrName = normalizeAttr(attr);
@@ -93,7 +105,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, add: [...updateActions.add, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, add: [...updateActions.add, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
         },
         delete(attr, value) {
             const attrName = normalizeAttr(attr);
@@ -103,10 +115,13 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, delete: [...updateActions.delete, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, delete: [...updateActions.delete, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
         },
         returning(mode) {
-            return createUpdateBuilder(tableName, key, client, conditions, updateActions, mode, valueCounter, enableTimestamps, logger, indexContext, setInputs);
+            return createUpdateBuilder(tableName, key, client, conditions, updateActions, mode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+        },
+        returnConsumedCapacity(mode) {
+            return createUpdateBuilder(tableName, key, client, conditions, updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, mode);
         },
         dbParams() {
             // Build UpdateExpression from actions
@@ -120,6 +135,68 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
             // key vars + the .set() payload, we throw — recomputing from the
             // existing item would require an extra read the builder won't do.
             if (indexContext) {
+                // Collect the attribute name targeted by every update action,
+                // grouped by op. `setInputs` carries the .set() payload (already
+                // structured) — for remove/add/delete we read from the action's
+                // attribute-name map.
+                const setFields = Object.keys(setInputs);
+                const removeFields = updateActions.remove
+                    .map(actionAttrName)
+                    .filter((n) => !!n);
+                const addFields = updateActions.add
+                    .map(actionAttrName)
+                    .filter((n) => !!n);
+                const deleteFields = updateActions.delete
+                    .map(actionAttrName)
+                    .filter((n) => !!n);
+                // Guard 1: primary-key template fields are immutable in DynamoDB.
+                // The Key on the UpdateItem request fixes the row to operate on; if
+                // the user changes a field that participates in the PK/SK template,
+                // the row's PK doesn't move (DynamoDB doesn't allow that) but the
+                // attribute does — leaving an inconsistent row whose PK encodes the
+                // old value. Catch this on every op (.set / .remove / .add / .delete)
+                // before it leaves the process.
+                const primaryKeyTemplateVars = new Set();
+                for (const keyDef of Object.values(indexContext.model.key)) {
+                    for (const v of (0, model_utils_1.extractTemplateVars)(keyDef.value)) {
+                        primaryKeyTemplateVars.add(v);
+                    }
+                }
+                const allTouched = [...setFields, ...removeFields, ...addFields, ...deleteFields];
+                const pkConflicts = [
+                    ...new Set(allTouched.filter((f) => primaryKeyTemplateVars.has(f))),
+                ];
+                if (pkConflicts.length > 0) {
+                    throw new Error(`Cannot update field(s) [${pkConflicts.join(', ')}] — they participate ` +
+                        `in the primary key template, which is immutable in DynamoDB. To ` +
+                        `"rename" a primary-key value, delete the old item and put a new one ` +
+                        `(ideally inside a transactWrite for atomicity).`);
+                }
+                // Guard 2: .add() / .remove() / .delete() against a field used in a
+                // SECONDARY-index template. The recompute path needs an explicit new
+                // value to resolve the template — ADD increments without exposing
+                // the new value, REMOVE strips the field entirely, and DELETE
+                // mutates a Set without naming a scalar. Switching to .set(field,
+                // newValue) lets the recompute path handle it correctly.
+                if (indexContext.model.index) {
+                    const indexTemplateVars = new Set();
+                    for (const indexDef of Object.values(indexContext.model.index)) {
+                        for (const v of (0, model_utils_1.extractTemplateVars)(indexDef.value)) {
+                            indexTemplateVars.add(v);
+                        }
+                    }
+                    const nonSetTouches = [...removeFields, ...addFields, ...deleteFields];
+                    const gsiConflicts = [
+                        ...new Set(nonSetTouches.filter((f) => indexTemplateVars.has(f))),
+                    ];
+                    if (gsiConflicts.length > 0) {
+                        throw new Error(`Cannot use .add() / .remove() / .delete() on field(s) ` +
+                            `[${gsiConflicts.join(', ')}] — they participate in a ` +
+                            `secondary-index template, and the affected index key cannot be ` +
+                            `recomputed without an explicit new value. Use .set(field, ` +
+                            `newValue) instead so the index key is recomputed atomically.`);
+                    }
+                }
                 const { actions: idxActions, missing } = (0, model_utils_1.computeIndexUpdates)(indexContext.model, indexContext.keyVars, setInputs);
                 if (missing.length > 0) {
                     const details = missing
@@ -246,6 +323,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 ...(Object.keys(expressionAttributeValues).length && {
                     ExpressionAttributeValues: expressionAttributeValues,
                 }),
+                ...(consumedCapacity && { ReturnConsumedCapacity: consumedCapacity }),
                 ...extra,
             };
         },

package/dist/builders/update/types.d.ts

@@ -46,6 +46,16 @@ export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbP
      * Configures what values should be returned after the update operation
      */
     returning(mode: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW'): UpdateBuilder<Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter so DynamoDB reports
+     * how many WCUs the update consumed. Useful for diagnosing throttling
+     * and validating cost when index keys are auto-recomputed.
+     *
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): UpdateBuilder<Model>;
     /**
      * Converts the builder state to DynamoDB UpdateItem parameters
      */

package/dist/builders/update/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACnE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtE;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GACnE,aAAa,CAAC,KAAK,CAAC,CAAC;IAExB;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACnE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtE;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GACnE,aAAa,CAAC,KAAK,CAAC,CAAC;IAExB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjF;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}

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,CA4NtE,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,CA0OtE,CAAC"}

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

@@ -54,6 +54,14 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             // 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.
+            //
+            // GOTCHA: this is implemented as a `FilterExpression` (`_type = …`),
+            // and DynamoDB applies `Limit` BEFORE filtering. On a single-table
+            // design where many entities share PKs, a `.limit(10)` query can
+            // return 0 items and a non-empty `LastEvaluatedKey` if none of the
+            // first 10 scanned items happen to belong to this entity. Either
+            // ignore Limit when type-mixing is heavy, or paginate via
+            // `iterate()` / `executeWithPagination()` and accumulate yourself.
             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()`
@@ -72,7 +80,13 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             };
         },
         scan() {
-            // Auto-filter by entity type so scan only returns items for this entity
+            // Auto-filter by entity type so scan only returns items for this entity.
+            //
+            // Same Limit-vs-Filter gotcha as `query()`: DynamoDB applies `Limit`
+            // before the FilterExpression, so on a multi-entity table a
+            // `.limit(N)` scan may return fewer than N items of THIS entity even
+            // when more exist deeper in the table. Use `iterate()` for "give me
+            // every item of this entity" semantics.
             const typeFilter = {
                 expression: '#_type = :_type',
                 names: { '#_type': '_type' },

package/package.json

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