@ftschopp/dynatable-core 1.5.2 → 1.6.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## @ftschopp/dynatable-core [1.6.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.6.0...@ftschopp/dynatable-core@1.6.1) (2026-05-10)
+
+
+### Bug Fixes
+
+* **core:** preserve concrete builder type through where(), unblock IDE typecheck on tests ([#45](https://github.com/ftschopp/dynatable/issues/45)) ([fb98553](https://github.com/ftschopp/dynatable/commit/fb98553684943291f6d500200bb4b7d32e2fa613))
+
+# @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)
 
 

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

@@ -1,13 +1,32 @@
 import type { DeleteCommandInput } from '@aws-sdk/lib-dynamodb';
-import { OperationBuilder } from '../shared';
+import { OperationBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
 /**
  * Builder interface for DynamoDB DeleteItem operations
  */
-export interface DeleteBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
+export interface DeleteBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams' | 'where'> {
+    /**
+     * Adds a condition expression to the delete operation. Returns a new
+     * immutable builder.
+     *
+     * Override of `OperationBuilder.where(): this` because `Omit<>` doesn't
+     * preserve `this`-polymorphism — chains like `.where(...).returning(...)`
+     * would otherwise widen to `OperationBuilder<Model>` and lose the
+     * delete-specific methods.
+     */
+    where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): DeleteBuilder<Model>;
     /**
      * 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,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/F;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAExF;;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

@@ -1,9 +1,19 @@
 import type { PutCommandInput } from '@aws-sdk/lib-dynamodb';
-import { OperationBuilder } from '../shared';
+import { OperationBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
 /**
  * Builder interface for DynamoDB PutItem operations
  */
-export interface PutBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
+export interface PutBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams' | 'where'> {
+    /**
+     * Adds a condition expression to the put operation. Returns a new
+     * immutable builder.
+     *
+     * Override of `OperationBuilder.where(): this` because `Omit<>` doesn't
+     * preserve `this`-polymorphism — chains like `.where(...).ifNotExists()`
+     * would otherwise widen to `OperationBuilder<Model>` and lose the
+     * put-specific methods.
+     */
+    where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): PutBuilder<Model>;
     /**
      * Adds a condition that the item must not exist (checks pk and sk)
      */
@@ -14,6 +24,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,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5F;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAErF;;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;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,GAClC,aAAa,CAAC,KAAK,CAAC,CAwbtB"}
+{"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

@@ -34,7 +34,7 @@ function actionAttrName(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++}`;
@@ -54,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,
@@ -77,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);
@@ -87,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);
@@ -95,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);
@@ -105,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);
@@ -115,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
@@ -320,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

@@ -1,6 +1,6 @@
 import type { UpdateCommandInput } from '@aws-sdk/lib-dynamodb';
 import { ModelDefinition } from '../../core/types';
-import { OperationBuilder, AttrRef } from '../shared';
+import { OperationBuilder, AttrRef, AttrBuilder, OpBuilder, Condition } from '../shared';
 /**
  * Update actions that can be performed on attributes
  */
@@ -24,7 +24,17 @@ export type IndexContext = {
 /**
  * Builder interface for DynamoDB UpdateItem operations
  */
-export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
+export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams' | 'where'> {
+    /**
+     * Adds a condition expression to the update operation. Returns a new
+     * immutable builder.
+     *
+     * Override of `OperationBuilder.where(): this` because `Omit<>` doesn't
+     * preserve `this`-polymorphism — chains like `.where(...).set(...)` or
+     * `.where(...).returning(...)` would otherwise widen to
+     * `OperationBuilder<Model>` and lose the update-specific methods.
+     */
+    where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): UpdateBuilder<Model>;
     /**
      * Sets an attribute to a specific value, or sets multiple attributes at once
      */
@@ -46,6 +56,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,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEzF;;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,GAAG,OAAO,CAAC;IAC/F;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAExF;;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.2",
+  "version": "1.6.1",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",