@ftschopp/dynatable-core 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# @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/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;AAK1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAiX7D;;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

@@ -255,6 +255,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 +280,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,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,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,CAqOpB"}

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

@@ -92,12 +92,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/package.json

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

package/src/builders/query/create-query-builder.test.ts

@@ -227,6 +227,126 @@ describe('QueryBuilder - Pagination', () => {
       expect(builder2.dbParams().ExclusiveStartKey).toEqual(startKey);
     });
   });
+
+  describe('iterate method', () => {
+    test('walks every page transparently and yields items in order', async () => {
+      const page1 = [
+        { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
+        { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+      ];
+      const page2 = [
+        { pk: 'USER#3', sk: 'USER#3', name: 'User 3' },
+        { pk: 'USER#4', sk: 'USER#4', name: 'User 4' },
+      ];
+      const page3 = [{ pk: 'USER#5', sk: 'USER#5', name: 'User 5' }];
+
+      ddbMock
+        .on(QueryCommand)
+        .resolvesOnce({ Items: page1, LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' } })
+        .resolvesOnce({ Items: page2, LastEvaluatedKey: { pk: 'USER#4', sk: 'USER#4' } })
+        .resolvesOnce({ Items: page3 });
+
+      const collected: TestModel[] = [];
+      for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .iterate()) {
+        collected.push(item);
+      }
+
+      expect(collected).toHaveLength(5);
+      expect(collected.map((u) => u.name)).toEqual([
+        'User 1',
+        'User 2',
+        'User 3',
+        'User 4',
+        'User 5',
+      ]);
+      expect(ddbMock.calls()).toHaveLength(3);
+    });
+
+    test('forwards ExclusiveStartKey from each response into the next call', async () => {
+      const cursor1 = { pk: 'USER#2', sk: 'USER#2' };
+      const cursor2 = { pk: 'USER#4', sk: 'USER#4' };
+
+      ddbMock
+        .on(QueryCommand)
+        .resolvesOnce({ Items: [{ pk: 'USER#1', sk: 'USER#1' }], LastEvaluatedKey: cursor1 })
+        .resolvesOnce({ Items: [{ pk: 'USER#3', sk: 'USER#3' }], LastEvaluatedKey: cursor2 })
+        .resolvesOnce({ Items: [{ pk: 'USER#5', sk: 'USER#5' }] });
+
+      const iterator = createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .iterate();
+
+      // Consume the iterator
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for await (const _ of iterator) {
+        // drain
+      }
+
+      const calls = ddbMock.calls();
+      expect(calls).toHaveLength(3);
+      expect((calls[0]!.args[0].input as any).ExclusiveStartKey).toBeUndefined();
+      expect((calls[1]!.args[0].input as any).ExclusiveStartKey).toEqual(cursor1);
+      expect((calls[2]!.args[0].input as any).ExclusiveStartKey).toEqual(cursor2);
+    });
+
+    test('starts from the user-provided cursor on the first call', async () => {
+      const startKey = { pk: 'USER#10', sk: 'USER#10' };
+
+      ddbMock.on(QueryCommand).resolves({ Items: [{ pk: 'USER#11', sk: 'USER#11' }] });
+
+      const iterator = createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .startFrom(startKey)
+        .iterate();
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for await (const _ of iterator) {
+        // drain
+      }
+
+      const calls = ddbMock.calls();
+      expect((calls[0]!.args[0].input as any).ExclusiveStartKey).toEqual(startKey);
+    });
+
+    test('break out of the loop stops further DynamoDB calls', async () => {
+      ddbMock
+        .on(QueryCommand)
+        .resolvesOnce({
+          Items: [
+            { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
+            { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+          ],
+          LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' },
+        });
+
+      const collected: TestModel[] = [];
+      for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .iterate()) {
+        collected.push(item);
+        if (collected.length >= 1) break;
+      }
+
+      expect(collected).toHaveLength(1);
+      expect(ddbMock.calls()).toHaveLength(1);
+    });
+
+    test('handles an empty result without making extra calls', async () => {
+      ddbMock.on(QueryCommand).resolves({ Items: [] });
+
+      const collected: TestModel[] = [];
+      for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'NONE#'))
+        .iterate()) {
+        collected.push(item);
+      }
+
+      expect(collected).toEqual([]);
+      expect(ddbMock.calls()).toHaveLength(1);
+    });
+  });
 });
 
 describe('QueryBuilder - GSI key recognition', () => {

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

@@ -333,6 +333,14 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
       };
     },
 
+    /**
+     * ⚠️ 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(): Promise<Model[]> {
       const params = this.dbParams();
       const result = await state.client.send(new QueryCommand(params));
@@ -351,6 +359,20 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         scannedCount: result.ScannedCount,
       };
     },
+
+    async *iterate(): AsyncIterableIterator<Model> {
+      const baseParams = this.dbParams();
+      let cursor: Record<string, any> | undefined = baseParams.ExclusiveStartKey;
+      do {
+        const params = { ...baseParams, ExclusiveStartKey: cursor };
+        const result = await state.client.send(new QueryCommand(params));
+        state.logger?.log('QueryCommand', params, result);
+        for (const item of (result.Items ?? []) as unknown as Model[]) {
+          yield item;
+        }
+        cursor = result.LastEvaluatedKey;
+      } while (cursor);
+    },
   };
 }
 

package/src/builders/query/types.ts

@@ -74,6 +74,23 @@ 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>;
 }
 
 /**

package/src/builders/scan/create-scan-builder.test.ts

@@ -1,7 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { mockClient } from 'aws-sdk-client-mock';
 import { createScanBuilder } from './create-scan-builder';
 
+const ddbMock = mockClient(DynamoDBClient);
+
 describe('ScanBuilder', () => {
   const client = new DynamoDBClient({});
   const tableName = 'TestTable';
@@ -257,4 +261,121 @@ describe('ScanBuilder', () => {
       expect(Object.values(params.ExpressionAttributeValues || {})).toContain(65);
     });
   });
+
+  describe('executeWithPagination', () => {
+    beforeEach(() => {
+      ddbMock.reset();
+    });
+
+    test('returns items, lastEvaluatedKey and counts', async () => {
+      const items = [
+        { pk: 'USER#alice', sk: 'USER#alice', name: 'Alice' },
+        { pk: 'USER#bob', sk: 'USER#bob', name: 'Bob' },
+      ];
+      const lastKey = { pk: 'USER#bob', sk: 'USER#bob' };
+
+      ddbMock.on(ScanCommand).resolves({
+        Items: items,
+        LastEvaluatedKey: lastKey,
+        Count: 2,
+        ScannedCount: 5,
+      });
+
+      const result = await createScanBuilder<TestModel>(tableName, client).executeWithPagination();
+
+      expect(result.items).toEqual(items);
+      expect(result.lastEvaluatedKey).toEqual(lastKey);
+      expect(result.count).toBe(2);
+      expect(result.scannedCount).toBe(5);
+    });
+
+    test('returns undefined lastEvaluatedKey on the final page', async () => {
+      ddbMock.on(ScanCommand).resolves({ Items: [], Count: 0, ScannedCount: 0 });
+
+      const result = await createScanBuilder<TestModel>(tableName, client).executeWithPagination();
+
+      expect(result.items).toEqual([]);
+      expect(result.lastEvaluatedKey).toBeUndefined();
+    });
+  });
+
+  describe('iterate', () => {
+    beforeEach(() => {
+      ddbMock.reset();
+    });
+
+    test('walks every page transparently and yields items in order', async () => {
+      const page1 = [
+        { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
+        { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+      ];
+      const page2 = [{ pk: 'USER#3', sk: 'USER#3', name: 'User 3' }];
+
+      ddbMock
+        .on(ScanCommand)
+        .resolvesOnce({ Items: page1, LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' } })
+        .resolvesOnce({ Items: page2 });
+
+      const collected: TestModel[] = [];
+      for await (const item of createScanBuilder<TestModel>(tableName, client).iterate()) {
+        collected.push(item);
+      }
+
+      expect(collected.map((u) => u.name)).toEqual(['User 1', 'User 2', 'User 3']);
+      expect(ddbMock.calls()).toHaveLength(2);
+    });
+
+    test('forwards LastEvaluatedKey from each response into the next call', async () => {
+      const cursor1 = { pk: 'USER#2', sk: 'USER#2' };
+
+      ddbMock
+        .on(ScanCommand)
+        .resolvesOnce({ Items: [{ pk: 'USER#1', sk: 'USER#1' }], LastEvaluatedKey: cursor1 })
+        .resolvesOnce({ Items: [{ pk: 'USER#3', sk: 'USER#3' }] });
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for await (const _ of createScanBuilder<TestModel>(tableName, client).iterate()) {
+        // drain
+      }
+
+      const calls = ddbMock.calls();
+      expect((calls[0]!.args[0].input as any).ExclusiveStartKey).toBeUndefined();
+      expect((calls[1]!.args[0].input as any).ExclusiveStartKey).toEqual(cursor1);
+    });
+
+    test('starts from the user-provided cursor on the first call', async () => {
+      const startKey = { pk: 'USER#10', sk: 'USER#10' };
+
+      ddbMock.on(ScanCommand).resolves({ Items: [{ pk: 'USER#11', sk: 'USER#11' }] });
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for await (const _ of createScanBuilder<TestModel>(tableName, client)
+        .startFrom(startKey)
+        .iterate()) {
+        // drain
+      }
+
+      const calls = ddbMock.calls();
+      expect((calls[0]!.args[0].input as any).ExclusiveStartKey).toEqual(startKey);
+    });
+
+    test('break out of the loop stops further DynamoDB calls', async () => {
+      ddbMock.on(ScanCommand).resolvesOnce({
+        Items: [
+          { pk: 'USER#1', sk: 'USER#1' },
+          { pk: 'USER#2', sk: 'USER#2' },
+        ],
+        LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' },
+      });
+
+      const collected: TestModel[] = [];
+      for await (const item of createScanBuilder<TestModel>(tableName, client).iterate()) {
+        collected.push(item);
+        if (collected.length >= 1) break;
+      }
+
+      expect(collected).toHaveLength(1);
+      expect(ddbMock.calls()).toHaveLength(1);
+    });
+  });
 });

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

@@ -2,7 +2,7 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import { buildExpression, AttrBuilder, Condition, createOpBuilder } from '../shared';
-import { ScanBuilder } from './types';
+import { ScanBuilder, ScanResult } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
 /**
@@ -205,12 +205,46 @@ export function createScanBuilder<Model>(
       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 ScanCommand(params));
       logger?.log('ScanCommand', params, response);
       return (response.Items || []) as Model[];
     },
+
+    async executeWithPagination(): Promise<ScanResult<Model>> {
+      const params = build().dbParams();
+      const response = await client.send(new ScanCommand(params));
+      logger?.log('ScanCommand', params, response);
+      return {
+        items: (response.Items ?? []) as Model[],
+        lastEvaluatedKey: response.LastEvaluatedKey,
+        count: response.Count,
+        scannedCount: response.ScannedCount,
+      };
+    },
+
+    async *iterate(): AsyncIterableIterator<Model> {
+      const baseParams = build().dbParams();
+      let cursor: Record<string, any> | undefined = baseParams.ExclusiveStartKey;
+      do {
+        const params = { ...baseParams, ExclusiveStartKey: cursor };
+        const response = await client.send(new ScanCommand(params));
+        logger?.log('ScanCommand', params, response);
+        for (const item of (response.Items ?? []) as Model[]) {
+          yield item;
+        }
+        cursor = response.LastEvaluatedKey;
+      } while (cursor);
+    },
   });
 
   return build();

package/src/builders/scan/types.ts

@@ -1,5 +1,20 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 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.
@@ -46,4 +61,28 @@ 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>;
 }