@ftschopp/dynatable-core 1.3.0 → 1.4.1

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

@@ -60,7 +60,13 @@ describe('QueryBuilder - Pagination', () => {
       expect(params.ExclusiveStartKey).toEqual(startKey);
       expect(params.Limit).toBe(10);
       expect(params.ScanIndexForward).toBe(false);
-      expect(params.ProjectionExpression).toBe('name, age');
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      expect(params.ExpressionAttributeNames).toEqual(
+        expect.objectContaining({
+          '#name': 'name',
+          '#age': 'age',
+        })
+      );
     });
 
     test('should not include ExclusiveStartKey if not set', () => {
@@ -227,6 +233,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', () => {
@@ -502,3 +628,81 @@ describe('QueryBuilder - entity type auto filter', () => {
     expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
   });
 });
+
+describe('QueryBuilder - projection placeholders', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface UserModel {
+    pk: string;
+    sk: string;
+    name?: string;
+    status?: string;
+    age?: number;
+    type?: string;
+  }
+
+  const userModel: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'USER#${username}' },
+      SK: { type: String, value: 'USER#${username}' },
+    },
+    attributes: {
+      username: { type: String, required: true },
+      name: { type: String },
+      status: { type: String },
+      age: { type: Number },
+      type: { type: String },
+    },
+  };
+
+  test('projects reserved DynamoDB words via #-placeholders', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, userModel)
+      .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+      .select(['name', 'status', 'type'])
+      .dbParams();
+
+    expect(params.ProjectionExpression).toBe('#name, #status, #type');
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#name': 'name',
+        '#status': 'status',
+        '#type': 'type',
+      })
+    );
+  });
+
+  test('merges projection names with key/filter names without clobbering', () => {
+    const params = createQueryBuilder<UserModel & { username: string }>(
+      tableName,
+      client,
+      userModel
+    )
+      .where((attr, op) => op.and(op.eq(attr.username, 'alice'), op.gt(attr.age, 18)))
+      .select(['name', 'status'])
+      .dbParams();
+
+    // Projection placeholders (#name, #status) merged with key (#PK from
+    // the username→PK template rewrite) and filter (#age) — none clobbered.
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#name': 'name',
+        '#status': 'status',
+        '#PK': 'PK',
+        '#age': 'age',
+      })
+    );
+  });
+
+  test('shares the same placeholder when an attribute is both projected and filtered (no key duplication)', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, userModel)
+      .where((attr, op) => op.and(op.eq(attr.pk, 'USER#alice'), op.eq(attr.status, 'active')))
+      .select(['name', 'status'])
+      .dbParams();
+
+    // The map has #status exactly once, mapping to "status".
+    expect(params.ExpressionAttributeNames!['#status']).toBe('status');
+    expect(params.ProjectionExpression).toBe('#name, #status');
+    expect(params.FilterExpression).toMatch(/#status = :status_\d+/);
+  });
+});

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

@@ -4,6 +4,7 @@ import { QueryCommand, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import { Condition, AttrBuilder, AttrRef } from '../shared';
 import { createOpBuilder } from '../shared/operators';
 import { buildExpression } from '../shared/conditions';
+import { buildProjectionExpression } from '../shared/projection';
 import { QueryBuilder, QueryExecutor, QueryResult } from './types';
 import { ModelDefinition } from '../../core/types';
 import { extractTemplateVars } from '../../utils/model-utils';
@@ -294,7 +295,7 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
       }
 
       // Merge attribute names and values from both expressions
-      const allNames = {
+      const allNames: Record<string, string> = {
         ...(keyExpr.names ?? {}),
         ...(filterExpr.names ?? {}),
       };
@@ -303,6 +304,19 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         ...(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: string | undefined;
+      if (state.projection && state.projection.length > 0) {
+        const proj = buildProjectionExpression(
+          (state.projection as (keyof Model)[]).map((a) => String(a))
+        );
+        projectionExpression = proj.ProjectionExpression;
+        Object.assign(allNames, proj.ExpressionAttributeNames);
+      }
+
       return {
         TableName: state.tableName,
         ...(keyExpr.expression && {
@@ -322,10 +336,9 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         ...(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 && {
           ExclusiveStartKey: state.exclusiveStartKey,
@@ -333,6 +346,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 +372,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';
@@ -73,17 +77,52 @@ describe('ScanBuilder', () => {
         .select(['name', 'age', 'status'])
         .dbParams();
 
-      expect(params.ProjectionExpression).toBe('name, age, status');
+      expect(params.ProjectionExpression).toBe('#name, #age, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#status': 'status',
+      });
     });
 
-    test('should build params with select and filter', () => {
+    test('should build params with select and filter, merging ExpressionAttributeNames', () => {
       const params = createScanBuilder<TestModel>(tableName, client)
         .select(['name', 'age'])
-        .filter((attr, op) => op.gt(attr.age, 18))
+        .filter((attr, op) => op.gt(attr.score, 50))
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      expect(params.FilterExpression).toMatch(/#score > :score_\d+/);
+      // Merged names from filter (#score) + projection (#name, #age)
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#score': 'score',
+      });
+    });
+
+    test('placeholders survive when projected attribute is also referenced in the filter (no key collision)', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'age'])
+        .filter((attr, op) => op.eq(attr.name, 'alice'))
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      // #name resolves to "name" — filter and projection share the placeholder.
+      expect(params.ExpressionAttributeNames!['#name']).toBe('name');
+      expect(params.ExpressionAttributeNames!['#age']).toBe('age');
+    });
+
+    test('reserved DynamoDB words like "name", "date", "status", "type" can be projected', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'status'])
         .dbParams();
 
-      expect(params.ProjectionExpression).toBe('name, age');
-      expect(params.FilterExpression).toMatch(/#age > :age_\d+/);
+      expect(params.ProjectionExpression).toBe('#name, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#status': 'status',
+      });
     });
   });
 
@@ -180,7 +219,7 @@ describe('ScanBuilder', () => {
 
       expect(params.TableName).toBe(tableName);
       expect(params.FilterExpression).toMatch(/\(#age > :age_\d+\) AND \(#status = :status_\d+\)/);
-      expect(params.ProjectionExpression).toBe('name, age, status');
+      expect(params.ProjectionExpression).toBe('#name, #age, #status');
       expect(params.Limit).toBe(100);
       expect(params.ConsistentRead).toBe(true);
       expect(params.IndexName).toBe('GSI1');
@@ -257,4 +296,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

@@ -1,8 +1,14 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 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 {
+  buildExpression,
+  AttrBuilder,
+  Condition,
+  createOpBuilder,
+  buildProjectionExpression,
+} from '../shared';
+import { ScanBuilder, ScanResult } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
 /**
@@ -155,10 +161,18 @@ export function createScanBuilder<Model>(
         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 = 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: any = {
@@ -205,12 +219,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>;
 }

package/src/builders/shared/index.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './operators';
 export * from './conditions';
+export * from './projection';