@ftschopp/dynatable-core 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## @ftschopp/dynatable-core [1.4.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.0...@ftschopp/dynatable-core@1.4.1) (2026-05-08)
+
+
+### Bug Fixes
+
+* **core:** use ExpressionAttributeNames placeholders for projections ([#25](https://github.com/ftschopp/dynatable/issues/25)) ([0e14ebd](https://github.com/ftschopp/dynatable/commit/0e14ebd64cfc58eb2b2353fa7678239bdddb22a6)), closes [#5](https://github.com/ftschopp/dynatable/issues/5)
+
+# @ftschopp/dynatable-core [1.4.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.3.0...@ftschopp/dynatable-core@1.4.0) (2026-05-08)
+
+
+### Features
+
+* **core:** add iterate() async iterator and Scan executeWithPagination ([#21](https://github.com/ftschopp/dynatable/issues/21)) ([c31d458](https://github.com/ftschopp/dynatable/commit/c31d45861e92ba0c52240128084939128a6e4acc)), closes [#4](https://github.com/ftschopp/dynatable/issues/4)
+
 # @ftschopp/dynatable-core [1.3.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.2.5...@ftschopp/dynatable-core@1.3.0) (2026-05-07)
 
 

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

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

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBatchGetBuilder = createBatchGetBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const shared_1 = require("../shared");
 /**
  * Creates a BatchGetBuilder to retrieve multiple items by their keys.
  *
@@ -36,12 +37,16 @@ function createBatchGetBuilder(requestItems, client, options, logger) {
          * Build the underlying DynamoDB input parameters.
          */
         dbParams() {
-            // Apply projection and consistentRead to all tables
+            // Build the projection once (with #-placeholders so reserved words
+            // like name/date/status/type don't blow up at DynamoDB) and reuse
+            // it per-table.
+            const proj = projection.length > 0 ? (0, shared_1.buildProjectionExpression)(projection.map(String)) : undefined;
             const enhancedRequestItems = Object.entries(requestItems).reduce((acc, [tableName, tableRequest]) => {
                 acc[tableName] = {
                     Keys: tableRequest.Keys,
-                    ...(projection.length > 0 && {
-                        ProjectionExpression: projection.join(', '),
+                    ...(proj && {
+                        ProjectionExpression: proj.ProjectionExpression,
+                        ExpressionAttributeNames: proj.ExpressionAttributeNames,
                     }),
                     ...(isConsistent && { ConsistentRead: true }),
                 };

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

@@ -1 +1 @@
-{"version":3,"file":"create-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/get/create-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA0B7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAC9C,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;CACvD,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAgG7B"}
+{"version":3,"file":"create-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/get/create-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAC9C,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;CACvD,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAgG7B"}

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

@@ -2,24 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGetBuilder = createGetBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
-/**
- * Builds a ProjectionExpression with proper ExpressionAttributeNames
- * to handle reserved words and special characters.
- */
-function buildProjectionExpression(attrs) {
-    const names = {};
-    const projectionParts = [];
-    attrs.forEach((attr) => {
-        // Use a placeholder for the attribute name to avoid reserved word conflicts
-        const placeholder = `#${attr}`;
-        names[placeholder] = attr;
-        projectionParts.push(placeholder);
-    });
-    return {
-        ProjectionExpression: projectionParts.join(', '),
-        ExpressionAttributeNames: names,
-    };
-}
+const shared_1 = require("../shared");
 /**
  * Creates a GetBuilder to retrieve an item by its key.
  */
@@ -68,7 +51,7 @@ function createGetBuilder(tableName, key, client, options, logger) {
             };
             // Add projection with proper ExpressionAttributeNames
             if (projection.length > 0) {
-                const projectionExpr = buildProjectionExpression(projection);
+                const projectionExpr = (0, shared_1.buildProjectionExpression)(projection);
                 params.ProjectionExpression = projectionExpr.ProjectionExpression;
                 params.ExpressionAttributeNames = projectionExpr.ExpressionAttributeNames;
             }

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;AAK1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA2V7D;;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,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA6X7D;;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

@@ -4,6 +4,7 @@ exports.createQueryBuilder = createQueryBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const operators_1 = require("../shared/operators");
 const conditions_1 = require("../shared/conditions");
+const projection_1 = require("../shared/projection");
 const model_utils_1 = require("../../utils/model-utils");
 /**
  * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
@@ -226,6 +227,16 @@ function createQueryExecutor(state) {
                 ...(keyExpr.values ?? {}),
                 ...(filterExpr.values ?? {}),
             };
+            // Build ProjectionExpression with placeholders so reserved words
+            // (name, date, status, type, …) don't blow up at DynamoDB.
+            // Idempotent merge: filter/key and projection placeholders both map
+            // `#name → name`, so collisions resolve to the same value.
+            let projectionExpression;
+            if (state.projection && state.projection.length > 0) {
+                const proj = (0, projection_1.buildProjectionExpression)(state.projection.map((a) => String(a)));
+                projectionExpression = proj.ProjectionExpression;
+                Object.assign(allNames, proj.ExpressionAttributeNames);
+            }
             return {
                 TableName: state.tableName,
                 ...(keyExpr.expression && {
@@ -245,9 +256,8 @@ function createQueryExecutor(state) {
                 ...(state.scanForward !== undefined && {
                     ScanIndexForward: state.scanForward,
                 }),
-                ...(state.projection &&
-                    state.projection.length > 0 && {
-                    ProjectionExpression: state.projection.join(', '),
+                ...(projectionExpression && {
+                    ProjectionExpression: projectionExpression,
                 }),
                 ...(state.consistentReadEnabled && { ConsistentRead: true }),
                 ...(state.exclusiveStartKey && {
@@ -255,6 +265,14 @@ function createQueryExecutor(state) {
                 }),
             };
         },
+        /**
+         * ⚠️ Returns only the FIRST page of results. DynamoDB caps each Query
+         * response at ~1MB (or `Limit` if set). If the matching set is larger,
+         * the remaining items are silently dropped.
+         *
+         * Use {@link executeWithPagination} when you need to drive pagination
+         * yourself, or {@link iterate} to walk every matching item lazily.
+         */
         async execute() {
             const params = this.dbParams();
             const result = await state.client.send(new lib_dynamodb_1.QueryCommand(params));
@@ -272,6 +290,19 @@ function createQueryExecutor(state) {
                 scannedCount: result.ScannedCount,
             };
         },
+        async *iterate() {
+            const baseParams = this.dbParams();
+            let cursor = baseParams.ExclusiveStartKey;
+            do {
+                const params = { ...baseParams, ExclusiveStartKey: cursor };
+                const result = await state.client.send(new lib_dynamodb_1.QueryCommand(params));
+                state.logger?.log('QueryCommand', params, result);
+                for (const item of (result.Items ?? [])) {
+                    yield item;
+                }
+                cursor = result.LastEvaluatedKey;
+            } while (cursor);
+        },
     };
 }
 /**

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

@@ -60,6 +60,22 @@ export interface QueryExecutor<Model> extends ExecutableBuilder<Model[]> {
      * Executes the query and returns result with pagination metadata
      */
     executeWithPagination(): Promise<QueryResult<Model>>;
+    /**
+     * Returns an async iterator that paginates internally and yields one item at
+     * a time. Memory stays at one page; you can `break` out of the loop early.
+     *
+     * `Limit` set via `.limit()` is forwarded to DynamoDB as a *per-request*
+     * cap, not a total cap. To cap the total, count yourself inside the loop:
+     *
+     * ```ts
+     * let n = 0;
+     * for await (const item of builder.iterate()) {
+     *   if (n++ >= 1000) break;
+     *   process(item);
+     * }
+     * ```
+     */
+    iterate(): AsyncIterableIterator<Model>;
 }
 /**
  * Main Query Builder interface with type-safe where clause

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;CACtD;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;;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.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,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,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,CAmMpB"}
+{"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"}

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

@@ -54,10 +54,18 @@ function createScanBuilder(tableName, client, filters = [], projectionAttrs = []
                 expressionAttributeNames = result.names;
                 expressionAttributeValues = result.values;
             }
-            // Build ProjectionExpression
+            // Build ProjectionExpression with placeholders so reserved words
+            // (name, date, status, type, …) don't blow up at DynamoDB.
             let projectionExpression = '';
             if (projectionAttrs.length > 0) {
-                projectionExpression = projectionAttrs.map((attr) => String(attr)).join(', ');
+                const proj = (0, shared_1.buildProjectionExpression)(projectionAttrs.map((attr) => String(attr)));
+                projectionExpression = proj.ProjectionExpression;
+                // Idempotent merge: filter and projection placeholders both map
+                // `#name → name`, so collisions resolve to the same value.
+                expressionAttributeNames = {
+                    ...proj.ExpressionAttributeNames,
+                    ...expressionAttributeNames,
+                };
             }
             const params = {
                 TableName: tableName,
@@ -92,12 +100,44 @@ function createScanBuilder(tableName, client, filters = [], projectionAttrs = []
             }
             return params;
         },
+        /**
+         * ⚠️ Returns only the FIRST page of results. DynamoDB caps each Scan
+         * response at ~1MB (or `Limit` if set). If the matching set is larger,
+         * the remaining items are silently dropped.
+         *
+         * Use {@link executeWithPagination} when you need to drive pagination
+         * yourself, or {@link iterate} to walk every matching item lazily.
+         */
         async execute() {
             const params = build().dbParams();
             const response = await client.send(new lib_dynamodb_1.ScanCommand(params));
             logger?.log('ScanCommand', params, response);
             return (response.Items || []);
         },
+        async executeWithPagination() {
+            const params = build().dbParams();
+            const response = await client.send(new lib_dynamodb_1.ScanCommand(params));
+            logger?.log('ScanCommand', params, response);
+            return {
+                items: (response.Items ?? []),
+                lastEvaluatedKey: response.LastEvaluatedKey,
+                count: response.Count,
+                scannedCount: response.ScannedCount,
+            };
+        },
+        async *iterate() {
+            const baseParams = build().dbParams();
+            let cursor = baseParams.ExclusiveStartKey;
+            do {
+                const params = { ...baseParams, ExclusiveStartKey: cursor };
+                const response = await client.send(new lib_dynamodb_1.ScanCommand(params));
+                logger?.log('ScanCommand', params, response);
+                for (const item of (response.Items ?? [])) {
+                    yield item;
+                }
+                cursor = response.LastEvaluatedKey;
+            } while (cursor);
+        },
     });
     return build();
 }

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

@@ -1,4 +1,17 @@
 import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
+/**
+ * A single page of scan results plus metadata for manual pagination.
+ */
+export interface ScanResult<Model> {
+    /** Items returned in this page. */
+    items: Model[];
+    /** Cursor for the next page; `undefined` when there are no more results. */
+    lastEvaluatedKey?: Record<string, any>;
+    /** Number of items returned after applying the filter. */
+    count?: number;
+    /** Number of items examined before applying the filter. */
+    scannedCount?: number;
+}
 /**
  * Builder for DynamoDB Scan operations.
  * Scans the entire table or index without requiring key conditions.
@@ -39,5 +52,27 @@ export interface ScanBuilder<Model> extends ExecutableBuilder<Model[]> {
      * Returns a new immutable builder.
      */
     segment(segmentNumber: number, totalSegments: number): 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
+     * pagination yourself (e.g. expose a cursor to a client).
+     */
+    executeWithPagination(): Promise<ScanResult<Model>>;
+    /**
+     * Returns an async iterator that paginates internally and yields one item at
+     * a time. Memory stays at one page; you can `break` out of the loop early.
+     *
+     * `Limit` set via `.limit()` is forwarded to DynamoDB as a *per-request*
+     * cap, not a total cap. To cap the total, count yourself inside the loop:
+     *
+     * ```ts
+     * let n = 0;
+     * for await (const item of builder.iterate()) {
+     *   if (n++ >= 1000) break;
+     *   process(item);
+     * }
+     * ```
+     */
+    iterate(): AsyncIterableIterator<Model>;
 }
 //# sourceMappingURL=types.d.ts.map

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":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjF;;;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;CAC3E"}
+{"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"}

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

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './operators';
 export * from './conditions';
+export * from './projection';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/builders/shared/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./operators"), exports);
 __exportStar(require("./conditions"), exports);
+__exportStar(require("./projection"), exports);

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

@@ -0,0 +1,15 @@
+/**
+ * Builds a `ProjectionExpression` together with the matching
+ * `ExpressionAttributeNames` map so that any attribute — including
+ * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
+ * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
+ * via a `#placeholder`.
+ *
+ * Without this indirection DynamoDB rejects the request with
+ * `ValidationException: Attribute name is a reserved keyword`.
+ */
+export declare function buildProjectionExpression(attrs: string[]): {
+    ProjectionExpression: string;
+    ExpressionAttributeNames: Record<string, string>;
+};
+//# sourceMappingURL=projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAC1D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD,CAcA"}

package/dist/builders/shared/projection.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProjectionExpression = buildProjectionExpression;
+/**
+ * Builds a `ProjectionExpression` together with the matching
+ * `ExpressionAttributeNames` map so that any attribute — including
+ * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
+ * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
+ * via a `#placeholder`.
+ *
+ * Without this indirection DynamoDB rejects the request with
+ * `ValidationException: Attribute name is a reserved keyword`.
+ */
+function buildProjectionExpression(attrs) {
+    const names = {};
+    const projectionParts = [];
+    attrs.forEach((attr) => {
+        const placeholder = `#${attr}`;
+        names[placeholder] = attr;
+        projectionParts.push(placeholder);
+    });
+    return {
+        ProjectionExpression: projectionParts.join(', '),
+        ExpressionAttributeNames: names,
+    };
+}

package/package.json

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

package/src/builders/batch-get/create-batch-get-builder.test.ts

@@ -64,7 +64,12 @@ describe('BatchGetBuilder', () => {
               { pk: 'USER#alice', sk: 'USER#alice' },
               { pk: 'USER#bob', sk: 'USER#bob' },
             ],
-            ProjectionExpression: 'username, name, followerCount',
+            ProjectionExpression: '#username, #name, #followerCount',
+            ExpressionAttributeNames: {
+              '#username': 'username',
+              '#name': 'name',
+              '#followerCount': 'followerCount',
+            },
           },
         },
       });
@@ -155,11 +160,34 @@ describe('BatchGetBuilder', () => {
               { pk: 'USER#alice', sk: 'USER#alice' },
               { pk: 'USER#bob', sk: 'USER#bob' },
             ],
-            ProjectionExpression: 'username, name',
+            ProjectionExpression: '#username, #name',
+            ExpressionAttributeNames: {
+              '#username': 'username',
+              '#name': 'name',
+            },
             ConsistentRead: true,
           },
         },
       });
     });
+
+    test('reserved DynamoDB words like "name", "date", "status" can be projected', () => {
+      const requestItems = {
+        Users: {
+          Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
+        },
+      };
+
+      const builder = createBatchGetBuilder<User>(requestItems, client).select(['name']);
+      const params = builder.dbParams();
+
+      expect(params.RequestItems!['Users']).toEqual({
+        Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
+        ProjectionExpression: '#name',
+        ExpressionAttributeNames: {
+          '#name': 'name',
+        },
+      });
+    });
   });
 });

package/src/builders/batch-get/create-batch-get-builder.ts

@@ -5,6 +5,7 @@ import {
   BatchGetCommandInput,
   BatchGetCommandOutput,
 } from '@aws-sdk/lib-dynamodb';
+import { buildProjectionExpression } from '../shared';
 import { BatchGetBuilder } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
@@ -63,13 +64,19 @@ export function createBatchGetBuilder<Model>(
      * Build the underlying DynamoDB input parameters.
      */
     dbParams(): BatchGetCommandInput {
-      // Apply projection and consistentRead to all tables
+      // Build the projection once (with #-placeholders so reserved words
+      // like name/date/status/type don't blow up at DynamoDB) and reuse
+      // it per-table.
+      const proj =
+        projection.length > 0 ? buildProjectionExpression(projection.map(String)) : undefined;
+
       const enhancedRequestItems = Object.entries(requestItems).reduce(
         (acc, [tableName, tableRequest]) => {
           acc[tableName] = {
             Keys: tableRequest.Keys,
-            ...(projection.length > 0 && {
-              ProjectionExpression: projection.join(', '),
+            ...(proj && {
+              ProjectionExpression: proj.ProjectionExpression,
+              ExpressionAttributeNames: proj.ExpressionAttributeNames,
             }),
             ...(isConsistent && { ConsistentRead: true }),
           };

package/src/builders/get/create-get-builder.ts

@@ -1,33 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { GetCommand, GetCommandInput, GetCommandOutput } from '@aws-sdk/lib-dynamodb';
+import { buildProjectionExpression } from '../shared';
 import { GetBuilder } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
-/**
- * Builds a ProjectionExpression with proper ExpressionAttributeNames
- * to handle reserved words and special characters.
- */
-function buildProjectionExpression(attrs: string[]): {
-  ProjectionExpression: string;
-  ExpressionAttributeNames: Record<string, string>;
-} {
-  const names: Record<string, string> = {};
-  const projectionParts: string[] = [];
-
-  attrs.forEach((attr) => {
-    // Use a placeholder for the attribute name to avoid reserved word conflicts
-    const placeholder = `#${attr}`;
-    names[placeholder] = attr;
-    projectionParts.push(placeholder);
-  });
-
-  return {
-    ProjectionExpression: projectionParts.join(', '),
-    ExpressionAttributeNames: names,
-  };
-}
-
 /**
  * Creates a GetBuilder to retrieve an item by its key.
  */