@ftschopp/dynatable-core 1.2.5 → 1.4.0

package/dist/utils/model-utils.d.ts

@@ -14,6 +14,34 @@ export declare const resolveTemplate: (template: string, data: Record<string, an
  * Resolves all keys or indexes for a model
  */
 export declare const resolveKeys: <M extends ModelDefinition>(model: M, input: Record<string, any>, type?: "key" | "index" | "both") => Record<string, string>;
+/**
+ * Result of analyzing how a partial update affects a model's secondary index keys.
+ *
+ * `actions` maps index-attribute name → freshly resolved template value, ready to SET.
+ * `missing` lists indexes whose template references at least one updated field but
+ * cannot be fully resolved from `keyVars + updates`; those entries identify the
+ * variables the caller must additionally provide.
+ */
+export type IndexUpdateAnalysis = {
+    actions: Record<string, string>;
+    missing: {
+        index: string;
+        template: string;
+        missing: string[];
+    }[];
+};
+/**
+ * Determines which secondary-index keys must be recomputed given a partial update.
+ *
+ * An index is "affected" iff at least one of its template variables appears in
+ * `updates`. For each affected index we attempt to resolve the template from the
+ * union of `keyVars` (template vars carried in the primary key, e.g. `id`) and
+ * `updates` (the user's `.set()` payload). If any template variable is missing
+ * from that union, the index is reported in `missing` instead of `actions` —
+ * recomputing it would require reading the existing item from DynamoDB, which
+ * the builder intentionally does not do.
+ */
+export declare const computeIndexUpdates: <M extends ModelDefinition>(model: M, keyVars: Record<string, any>, updates: Record<string, any>) => IndexUpdateAnalysis;
 /**
  * Applies default and generated values to validated input
  */

package/dist/utils/model-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAiCd,CAAC;AAOF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAoB1E,CAAC"}
+{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,eAAe,EAC3D,OAAO,CAAC,EACR,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,mBAwBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAiCd,CAAC;AAOF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAoB1E,CAAC"}

package/dist/utils/model-utils.js

@@ -1,7 +1,7 @@
 "use strict";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripInternalKeys = exports.applyPostDefaults = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
+exports.stripInternalKeys = exports.applyPostDefaults = exports.computeIndexUpdates = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
 const ulid_1 = require("ulid");
 /**
  * Extracts all variable names from a template string
@@ -53,6 +53,39 @@ const resolveKeys = (model, input, type = 'key') => {
     return out;
 };
 exports.resolveKeys = resolveKeys;
+/**
+ * Determines which secondary-index keys must be recomputed given a partial update.
+ *
+ * An index is "affected" iff at least one of its template variables appears in
+ * `updates`. For each affected index we attempt to resolve the template from the
+ * union of `keyVars` (template vars carried in the primary key, e.g. `id`) and
+ * `updates` (the user's `.set()` payload). If any template variable is missing
+ * from that union, the index is reported in `missing` instead of `actions` —
+ * recomputing it would require reading the existing item from DynamoDB, which
+ * the builder intentionally does not do.
+ */
+const computeIndexUpdates = (model, keyVars, updates) => {
+    const actions = {};
+    const missing = [];
+    if (!model.index)
+        return { actions, missing };
+    const updateKeys = new Set(Object.keys(updates));
+    const combined = { ...keyVars, ...updates };
+    for (const [indexName, indexDef] of Object.entries(model.index)) {
+        const templateVars = (0, exports.extractTemplateVars)(indexDef.value);
+        const isAffected = templateVars.some((v) => updateKeys.has(v));
+        if (!isAffected)
+            continue;
+        const missingVars = templateVars.filter((v) => combined[v] === undefined);
+        if (missingVars.length > 0) {
+            missing.push({ index: indexName, template: indexDef.value, missing: missingVars });
+            continue;
+        }
+        actions[indexName] = (0, exports.resolveTemplate)(indexDef.value, combined);
+    }
+    return { actions, missing };
+};
+exports.computeIndexUpdates = computeIndexUpdates;
 /**
  * Applies default and generated values to validated input
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.2.5",
+  "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', () => {
@@ -298,3 +418,207 @@ describe('QueryBuilder - GSI key recognition', () => {
     expect(params.FilterExpression).toBeUndefined();
   });
 });
+
+describe('QueryBuilder - multi-variable key templates', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface AirportResource {
+    id: string;
+    airport: string;
+    category: string;
+    code: string;
+    status: string;
+  }
+
+  const airportResourceModel: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'AIRPORT_RESOURCE#${id}' },
+      SK: { type: String, value: 'AIRPORT_RESOURCE#${id}' },
+    },
+    index: {
+      GSI1PK: { type: String, value: 'AIRPORT#${airport}' },
+      GSI1SK: { type: String, value: 'RES#${category}#${code}' },
+    },
+    attributes: {
+      id: { type: String, required: true },
+      airport: { type: String, required: true },
+      category: { type: String, required: true },
+      code: { type: String, required: true },
+      status: { type: String, required: true },
+    },
+  };
+
+  test('beginsWith on attribute that is part of multi-var template should truncate at the first unfilled variable', () => {
+    const params = createQueryBuilder<AirportResource>(tableName, client, airportResourceModel)
+      .where((attr, op) =>
+        op.and(op.eq(attr.airport, 'EZE'), op.beginsWith(attr.category, 'GPU'))
+      )
+      .useIndex('GSI1')
+      .dbParams();
+
+    expect(params.KeyConditionExpression).toBeDefined();
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.KeyConditionExpression).toContain('begins_with(#GSI1SK');
+    expect(params.IndexName).toBe('GSI1');
+
+    const values = params.ExpressionAttributeValues ?? {};
+    expect(Object.values(values)).toContain('AIRPORT#EZE');
+    // Should be the prefix up to the next unfilled var, NOT 'RES#GPU#${code}'
+    expect(Object.values(values)).toContain('RES#GPU#');
+    expect(Object.values(values).every((v) => !String(v).includes('${'))).toBe(true);
+  });
+
+  test('eq on attribute with multi-var template should throw a clear error', () => {
+    expect(() =>
+      createQueryBuilder<AirportResource>(tableName, client, airportResourceModel)
+        .where((attr, op) => op.eq(attr.category, 'GPU'))
+        .useIndex('GSI1')
+        .dbParams()
+    ).toThrow(/template/i);
+  });
+
+  test('beginsWith on a single-var template still works (no truncation needed)', () => {
+    const params = createQueryBuilder<AirportResource>(tableName, client, airportResourceModel)
+      .where((attr, op) => op.beginsWith(attr.airport, 'EZ'))
+      .useIndex('GSI1')
+      .dbParams();
+
+    const values = params.ExpressionAttributeValues ?? {};
+    expect(Object.values(values)).toContain('AIRPORT#EZ');
+  });
+});
+
+describe('QueryBuilder - entity type auto filter', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface AirportPersonnel {
+    id: string;
+    airport: string;
+    role: string;
+  }
+
+  // Mirrors the reported scenario: PK is entity-specific, GSI1 is shared
+  // across multiple entities (Airport, AirportPersonnel, etc.)
+  const airportPersonnelModel: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'AIRPORT_PERSONNEL#${id}' },
+      SK: { type: String, value: 'AIRPORT_PERSONNEL#${id}' },
+    },
+    index: {
+      GSI1PK: { type: String, value: 'AIRPORT#${airport}' },
+      GSI1SK: { type: String, value: 'PERSONNEL#${role}' },
+    },
+    attributes: {
+      id: { type: String, required: true },
+      airport: { type: String, required: true },
+      role: { type: String, required: true },
+    },
+  };
+
+  test('does NOT add _type filter when entityType is not provided (back-compat)', () => {
+    const params = createQueryBuilder<AirportPersonnel>(
+      tableName,
+      client,
+      airportPersonnelModel
+    )
+      .where((attr, op) => op.eq(attr.airport, 'EZE'))
+      .useIndex('GSI1')
+      .dbParams();
+
+    expect(params.FilterExpression).toBeUndefined();
+    const names = params.ExpressionAttributeNames ?? {};
+    expect(names['#_type']).toBeUndefined();
+  });
+
+  test('adds _type filter when entityType is provided and there are no other filters', () => {
+    const params = createQueryBuilder<AirportPersonnel>(
+      tableName,
+      client,
+      airportPersonnelModel,
+      undefined,
+      'AirportPersonnel'
+    )
+      .where((attr, op) => op.eq(attr.airport, 'EZE'))
+      .useIndex('GSI1')
+      .dbParams();
+
+    // Key cond goes to KeyConditionExpression, _type goes to FilterExpression
+    expect(params.KeyConditionExpression).toBeDefined();
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.FilterExpression).toBe('#_type = :_type');
+    expect(params.ExpressionAttributeNames?.['#_type']).toBe('_type');
+    expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
+  });
+
+  test('combines _type filter with a user-provided non-key filter via AND', () => {
+    const params = createQueryBuilder<AirportPersonnel & { status?: string }>(
+      tableName,
+      client,
+      airportPersonnelModel,
+      undefined,
+      'AirportPersonnel'
+    )
+      .where((attr, op) => op.and(op.eq(attr.airport, 'EZE'), op.eq(attr.status, 'active')))
+      .useIndex('GSI1')
+      .dbParams();
+
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.FilterExpression).toBeDefined();
+    expect(params.FilterExpression).toContain('#status');
+    expect(params.FilterExpression).toContain('#_type = :_type');
+    expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
+  });
+
+  test('repro of reported bug: GSI1 query with conditional beginsWith still filters by _type', () => {
+    // The exact shape from the user report:
+    //   .where((attr, op) =>
+    //     role
+    //       ? op.and(op.eq(attr.airport, airport), op.beginsWith(attr.role, role))
+    //       : op.eq(attr.airport, airport)
+    //   )
+    const airport = 'EZE';
+    const role = 'PILOT';
+
+    const params = createQueryBuilder<AirportPersonnel>(
+      tableName,
+      client,
+      airportPersonnelModel,
+      undefined,
+      'AirportPersonnel'
+    )
+      .where((attr, op) =>
+        role
+          ? op.and(op.eq(attr.airport, airport), op.beginsWith(attr.role, role))
+          : op.eq(attr.airport, airport)
+      )
+      .useIndex('GSI1')
+      .dbParams();
+
+    // Both airport (GSI1PK) and role (GSI1SK) become key conditions
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.KeyConditionExpression).toContain('begins_with(#GSI1SK');
+    // _type still gets enforced as a filter — this is the fix
+    expect(params.FilterExpression).toBe('#_type = :_type');
+    expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
+  });
+
+  test('does not collide with user attribute placeholders', () => {
+    // Confirm the auto-injected names/values don't clash with user-supplied ones
+    const params = createQueryBuilder<AirportPersonnel & { status?: string }>(
+      tableName,
+      client,
+      airportPersonnelModel,
+      undefined,
+      'AirportPersonnel'
+    )
+      .where((attr, op) => op.and(op.eq(attr.airport, 'EZE'), op.eq(attr.status, 'active')))
+      .useIndex('GSI1')
+      .dbParams();
+
+    expect(params.ExpressionAttributeNames?.['#_type']).toBe('_type');
+    expect(params.ExpressionAttributeNames?.['#status']).toBe('status');
+    expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
+  });
+});

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

@@ -24,6 +24,7 @@ type QueryState<Model> = {
   consistentReadEnabled?: boolean;
   exclusiveStartKey?: Record<string, any>;
   logger?: DynamoDBLogger;
+  entityType?: string;
 };
 
 /**
@@ -60,11 +61,32 @@ function getKeyNameForAttribute(
 }
 
 /**
- * Apply key template to transform attribute value to key value
- * e.g., applyKeyTemplate("UP#${username}", "username", "johndoe") -> "UP#johndoe"
+ * Apply key template to transform an attribute value to its key value.
+ *
+ * For multi-variable templates (e.g. "RES#${category}#${code}") we can only fill
+ * the variable matching `fieldName`. For `beginsWith` queries we truncate the
+ * result at the first remaining `${...}` placeholder so the prefix is usable.
+ * For other operators an exact match is required, so we throw a clear error.
  */
-function applyKeyTemplate(template: string, fieldName: string, fieldValue: any): string {
-  return template.replace(`\${${fieldName}}`, fieldValue);
+function applyKeyTemplate(
+  template: string,
+  fieldName: string,
+  fieldValue: any,
+  keyOperator?: string
+): string {
+  const substituted = template.replace(`\${${fieldName}}`, String(fieldValue));
+  const nextPlaceholder = substituted.indexOf('${');
+  if (nextPlaceholder === -1) return substituted;
+
+  if (keyOperator === 'beginsWith') {
+    return substituted.slice(0, nextPlaceholder);
+  }
+
+  throw new Error(
+    `Cannot use operator "${keyOperator ?? 'unknown'}" on key template "${template}" ` +
+      `with only "${fieldName}" provided — the template still contains unfilled ` +
+      `variable(s). Use beginsWith for prefix queries on composite keys.`
+  );
 }
 
 /**
@@ -116,7 +138,12 @@ function separateConditions(
         if (cond.values) {
           for (const [valuePlaceholder, value] of Object.entries(cond.values)) {
             // Apply the key template to transform the value
-            const transformedValue = applyKeyTemplate(keyInfo.template, fieldName, value);
+            const transformedValue = applyKeyTemplate(
+              keyInfo.template,
+              fieldName,
+              value,
+              cond.keyOperator
+            );
             newValues[valuePlaceholder] = transformedValue;
           }
         }
@@ -239,17 +266,29 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
       // Build KeyConditionExpression (simple AND)
       const keyExpr = buildSimpleAndExpression(keyConditions);
 
+      // Auto-inject an entity-type filter so query() only returns items
+      // belonging to this entity (single-table designs share PKs across
+      // entities, especially on GSIs).
+      const allFilters = [...filterConditions];
+      if (state.entityType) {
+        allFilters.push({
+          expression: '#_type = :_type',
+          names: { '#_type': '_type' },
+          values: { ':_type': state.entityType },
+        });
+      }
+
       // Build FilterExpression (can be complex with OR, NOT, etc.)
       let filterExpr = { expression: '', names: {}, values: {} };
-      if (filterConditions.length > 0) {
-        if (filterConditions.length === 1 && filterConditions[0]) {
-          filterExpr = buildExpression(filterConditions[0]);
+      if (allFilters.length > 0) {
+        if (allFilters.length === 1 && allFilters[0]) {
+          filterExpr = buildExpression(allFilters[0]);
         } else {
           // Multiple filter conditions - combine with AND
           filterExpr = buildExpression({
             expression: '',
             operator: 'AND',
-            children: filterConditions,
+            children: allFilters,
           });
         }
       }
@@ -294,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));
@@ -312,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);
+    },
   };
 }
 
@@ -322,7 +383,8 @@ export function createQueryBuilder<Model>(
   tableName: string,
   client: DynamoDBClient,
   model?: ModelDefinition,
-  logger?: DynamoDBLogger
+  logger?: DynamoDBLogger,
+  entityType?: string
 ): QueryBuilder<Model> {
   return {
     where(fn) {
@@ -346,6 +408,7 @@ export function createQueryBuilder<Model>(
         model,
         condition,
         logger,
+        entityType,
       };
 
       return createQueryExecutor(initialState);

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>;
 }
 
 /**