@ftschopp/dynatable-core 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## @ftschopp/dynatable-core [1.2.2](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.2.1...@ftschopp/dynatable-core@1.2.2) (2026-04-15)
+
+
+### Bug Fixes
+
+* add filter type scan entity ([dddff15](https://github.com/ftschopp/dynatable/commit/dddff15228f84fd11b0c6d2daa6f5cc8d77c641d))
+
+## @ftschopp/dynatable-core [1.2.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.2.0...@ftschopp/dynatable-core@1.2.1) (2026-04-15)
+
+
+### Bug Fixes
+
+* resolve GSI key attributes to KeyConditionExpression when using useIndex ([8b2ee35](https://github.com/ftschopp/dynatable/commit/8b2ee35ca56bae9a32c8f1fec764365e8496674d))
+
+## @ftschopp/dynatable-core [1.2.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.2.0...@ftschopp/dynatable-core@1.2.1) (2026-04-15)
+
+
+### Bug Fixes
+
+* resolve GSI key attributes to KeyConditionExpression when using useIndex ([8b2ee35](https://github.com/ftschopp/dynatable/commit/8b2ee35ca56bae9a32c8f1fec764365e8496674d))
+
 # @ftschopp/dynatable-core [1.2.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.1.0...@ftschopp/dynatable-core@1.2.0) (2026-03-20)
 
 

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;AAiT7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,GACtB,YAAY,CAAC,KAAK,CAAC,CA4BrB"}
+{"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;AAuU7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,GACtB,YAAY,CAAC,KAAK,CAAC,CA4BrB"}

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

@@ -6,11 +6,20 @@ const operators_1 = require("../shared/operators");
 const conditions_1 = require("../shared/conditions");
 const model_utils_1 = require("../../utils/model-utils");
 /**
- * Determines if a field is a key field (used in pk/sk templates)
+ * Determines if a field is a key field (used in pk/sk or index key templates)
  */
-function isKeyField(fieldName, model) {
+function isKeyField(fieldName, model, indexName) {
     if (!model?.key)
         return false;
+    // When an index is specified, also check model.index for key templates
+    if (indexName && model.index) {
+        for (const [, keyDef] of Object.entries(model.index)) {
+            const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
+            if (templateVars.includes(fieldName)) {
+                return true;
+            }
+        }
+    }
     const keyEntries = Object.entries(model.key);
     for (const [, keyDef] of keyEntries) {
         const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
@@ -24,13 +33,22 @@ function isKeyField(fieldName, model) {
  * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
  * Also returns the key template for value transformation
  */
-function getKeyNameForAttribute(fieldName, model) {
+function getKeyNameForAttribute(fieldName, model, indexName) {
     if (!model?.key)
         return null;
+    // When an index is specified, check model.index first for key templates
+    if (indexName && model.index) {
+        for (const [keyName, keyDef] of Object.entries(model.index)) {
+            const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
+            if (templateVars.includes(fieldName)) {
+                return { keyName, template: keyDef.value };
+            }
+        }
+    }
     for (const [keyName, keyDef] of Object.entries(model.key)) {
         const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
         if (templateVars.includes(fieldName)) {
-            return { keyName, template: keyDef.value }; // Returns "PK" and "UP#${username}"
+            return { keyName, template: keyDef.value };
         }
     }
     return null;
@@ -46,7 +64,7 @@ function applyKeyTemplate(template, fieldName, fieldValue) {
  * Separates a condition tree into key conditions and filter conditions
  * Key conditions are rewritten to use actual DynamoDB key names (PK/SK)
  */
-function separateConditions(condition, model) {
+function separateConditions(condition, model, indexName) {
     const keyConditions = [];
     const filterConditions = [];
     function traverse(cond) {
@@ -76,7 +94,7 @@ function separateConditions(condition, model) {
         const fieldMatch = cond.expression.match(/#(\w+)/);
         if (fieldMatch && fieldMatch[1]) {
             const fieldName = fieldMatch[1];
-            const keyInfo = getKeyNameForAttribute(fieldName, model);
+            const keyInfo = getKeyNameForAttribute(fieldName, model, indexName);
             if (keyInfo) {
                 // This is a key field - rewrite the condition to use the actual key name
                 // and apply the template to the value
@@ -178,7 +196,7 @@ function createQueryExecutor(state) {
                 throw new Error('No where condition specified');
             }
             // Separate key conditions from filter conditions
-            const { keyConditions, filterConditions } = separateConditions(state.condition, state.model);
+            const { keyConditions, filterConditions } = separateConditions(state.condition, state.model, state.indexName);
             // Build KeyConditionExpression (simple AND)
             const keyExpr = buildSimpleAndExpression(keyConditions);
             // Build FilterExpression (can be complex with OR, NOT, etc.)

package/dist/entity/create-entity-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAKtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CA8KtE,CAAC"}
+{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAqLtE,CAAC"}

package/dist/entity/create-entity-api.js

@@ -54,7 +54,13 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             return (0, builders_1.createQueryBuilder)(tableName, client, model, logger);
         },
         scan() {
-            const builder = (0, builders_1.createScanBuilder)(tableName, client, [], [], undefined, false, undefined, undefined, undefined, logger);
+            // Auto-filter by entity type so scan only returns items for this entity
+            const typeFilter = {
+                expression: '#_type = :_type',
+                names: { '#_type': '_type' },
+                values: { ':_type': modelName },
+            };
+            const builder = (0, builders_1.createScanBuilder)(tableName, client, [typeFilter], [], undefined, false, undefined, undefined, undefined, logger);
             return (0, with_middleware_1.withMiddleware)(builder, (0, factories_1.createCleanKeysMiddleware)(cleanInternalKeys));
         },
         update(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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

@@ -228,3 +228,73 @@ describe('QueryBuilder - Pagination', () => {
     });
   });
 });
+
+describe('QueryBuilder - GSI key recognition', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface UserModel {
+    id: string;
+    email: string;
+    name?: string;
+  }
+
+  const modelWithIndex: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'USER#${id}' },
+      SK: { type: String, value: 'USER#${id}' },
+    },
+    index: {
+      GSI1PK: { type: String, value: 'EMAIL#${email}' },
+      GSI1SK: { type: String, value: 'EMAIL#${email}' },
+    },
+    attributes: {
+      id: { type: String, required: true },
+      email: { type: String, required: true },
+      name: { type: String },
+    },
+  };
+
+  test('should place GSI index attribute into KeyConditionExpression when useIndex is set', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, modelWithIndex)
+      .where((attr, op) => op.eq(attr.email, 'alice@example.com'))
+      .useIndex('GSI1')
+      .dbParams();
+
+    // email should be recognized as a key field via model.index and placed in KeyConditionExpression
+    expect(params.KeyConditionExpression).toBeDefined();
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.ExpressionAttributeValues).toBeDefined();
+    // The value should have the template applied
+    expect(Object.values(params.ExpressionAttributeValues!)).toContain('EMAIL#alice@example.com');
+    // It should NOT be in FilterExpression
+    expect(params.FilterExpression).toBeUndefined();
+    expect(params.IndexName).toBe('GSI1');
+  });
+
+  test('should place GSI attribute into FilterExpression when NO index is specified', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, modelWithIndex)
+      .where((attr, op) => op.and(op.eq(attr.id, '123'), op.eq(attr.email, 'alice@example.com')))
+      .dbParams();
+
+    // id maps to PK -> KeyConditionExpression
+    expect(params.KeyConditionExpression).toBeDefined();
+    expect(params.KeyConditionExpression).toContain('#PK');
+    // email is NOT a primary key field, so without useIndex it goes to filter
+    expect(params.FilterExpression).toBeDefined();
+    expect(params.FilterExpression).toContain('#email');
+  });
+
+  test('should handle both primary key and GSI key fields together with useIndex', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, modelWithIndex)
+      .where((attr, op) => op.and(op.eq(attr.email, 'alice@example.com'), op.eq(attr.id, '123')))
+      .useIndex('GSI1')
+      .dbParams();
+
+    // Both should be key conditions: email via index, id via primary key
+    expect(params.KeyConditionExpression).toBeDefined();
+    expect(params.KeyConditionExpression).toContain('#GSI1PK');
+    expect(params.KeyConditionExpression).toContain('#PK');
+    expect(params.FilterExpression).toBeUndefined();
+  });
+});

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

@@ -27,11 +27,21 @@ type QueryState<Model> = {
 };
 
 /**
- * Determines if a field is a key field (used in pk/sk templates)
+ * Determines if a field is a key field (used in pk/sk or index key templates)
  */
-function isKeyField(fieldName: string, model?: ModelDefinition): boolean {
+function isKeyField(fieldName: string, model?: ModelDefinition, indexName?: string): boolean {
   if (!model?.key) return false;
 
+  // When an index is specified, also check model.index for key templates
+  if (indexName && model.index) {
+    for (const [, keyDef] of Object.entries(model.index)) {
+      const templateVars = extractTemplateVars(keyDef.value);
+      if (templateVars.includes(fieldName)) {
+        return true;
+      }
+    }
+  }
+
   const keyEntries = Object.entries(model.key);
   for (const [, keyDef] of keyEntries) {
     const templateVars = extractTemplateVars(keyDef.value);
@@ -48,14 +58,25 @@ function isKeyField(fieldName: string, model?: ModelDefinition): boolean {
  */
 function getKeyNameForAttribute(
   fieldName: string,
-  model?: ModelDefinition
+  model?: ModelDefinition,
+  indexName?: string
 ): { keyName: string; template: string } | null {
   if (!model?.key) return null;
 
+  // When an index is specified, check model.index first for key templates
+  if (indexName && model.index) {
+    for (const [keyName, keyDef] of Object.entries(model.index)) {
+      const templateVars = extractTemplateVars(keyDef.value);
+      if (templateVars.includes(fieldName)) {
+        return { keyName, template: keyDef.value };
+      }
+    }
+  }
+
   for (const [keyName, keyDef] of Object.entries(model.key)) {
     const templateVars = extractTemplateVars(keyDef.value);
     if (templateVars.includes(fieldName)) {
-      return { keyName, template: keyDef.value }; // Returns "PK" and "UP#${username}"
+      return { keyName, template: keyDef.value };
     }
   }
   return null;
@@ -75,7 +96,8 @@ function applyKeyTemplate(template: string, fieldName: string, fieldValue: any):
  */
 function separateConditions(
   condition: Condition,
-  model?: ModelDefinition
+  model?: ModelDefinition,
+  indexName?: string
 ): { keyConditions: Condition[]; filterConditions: Condition[] } {
   const keyConditions: Condition[] = [];
   const filterConditions: Condition[] = [];
@@ -106,7 +128,7 @@ function separateConditions(
     const fieldMatch = cond.expression.match(/#(\w+)/);
     if (fieldMatch && fieldMatch[1]) {
       const fieldName = fieldMatch[1];
-      const keyInfo = getKeyNameForAttribute(fieldName, model);
+      const keyInfo = getKeyNameForAttribute(fieldName, model, indexName);
 
       if (keyInfo) {
         // This is a key field - rewrite the condition to use the actual key name
@@ -231,7 +253,7 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
       }
 
       // Separate key conditions from filter conditions
-      const { keyConditions, filterConditions } = separateConditions(state.condition, state.model);
+      const { keyConditions, filterConditions } = separateConditions(state.condition, state.model, state.indexName);
 
       // Build KeyConditionExpression (simple AND)
       const keyExpr = buildSimpleAndExpression(keyConditions);

package/src/entity/create-entity-api.ts

@@ -18,6 +18,7 @@ import { EntityAPI, EntityAPIOptions } from './types';
 import { withMiddleware } from './middleware/with-middleware';
 import { createCleanKeysMiddleware } from './middleware/factories';
 import { validateKeyFields } from './validation/key-validation';
+import { Condition } from '@/builders/shared/types';
 
 /**
  * Creates an entity API instance with validation, key resolution, and builder creation.
@@ -90,10 +91,17 @@ export const createEntityAPI = <Model extends ModelDefinition>(
     },
 
     scan() {
+      // Auto-filter by entity type so scan only returns items for this entity
+      const typeFilter: Condition = {
+        expression: '#_type = :_type',
+        names: { '#_type': '_type' },
+        values: { ':_type': modelName },
+      };
+
       const builder = createScanBuilder<InferModel<Model>>(
         tableName,
         client,
-        [],
+        [typeFilter],
         [],
         undefined,
         false,

package/tests/integration/instagram-clone.integration.test.ts

@@ -726,7 +726,9 @@ describe('Should test dbParams function builder', () => {
     const params = await table.entities.User.scan().dbParams();
 
     expect(params.TableName).toBe('InstagramClone');
-    expect(params.FilterExpression).toBeUndefined();
+    expect(params.FilterExpression).toBe('#_type = :_type');
+    expect(params.ExpressionAttributeNames).toMatchObject({ '#_type': '_type' });
+    expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'User' });
   });
 
   test('SCAN Users with filter', async () => {
@@ -736,10 +738,12 @@ describe('Should test dbParams function builder', () => {
 
     expect(params.TableName).toBe('InstagramClone');
     expect(params.FilterExpression).toMatch(/#followerCount > :followerCount_\d+/);
-    expect(params.ExpressionAttributeNames).toEqual({
+    expect(params.ExpressionAttributeNames).toMatchObject({
       '#followerCount': 'followerCount',
+      '#_type': '_type',
     });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain(100);
+    expect(Object.values(params.ExpressionAttributeValues || {})).toContain('User');
   });
 
   test('SCAN Users with multiple filters', async () => {
@@ -751,9 +755,10 @@ describe('Should test dbParams function builder', () => {
     expect(params.FilterExpression).toMatch(
       /\(#followerCount > :followerCount_\d+\) AND \(#followingCount > :followingCount_\d+\)/
     );
-    expect(params.ExpressionAttributeNames).toEqual({
+    expect(params.ExpressionAttributeNames).toMatchObject({
       '#followerCount': 'followerCount',
       '#followingCount': 'followingCount',
+      '#_type': '_type',
     });
   });
 
@@ -763,6 +768,8 @@ describe('Should test dbParams function builder', () => {
       .dbParams();
 
     expect(params.ProjectionExpression).toBe('username, photoId, likesCount');
+    expect(params.FilterExpression).toBe('#_type = :_type');
+    expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'Photo' });
   });
 
   test('SCAN Photos with limit', async () => {
@@ -773,6 +780,8 @@ describe('Should test dbParams function builder', () => {
 
     expect(params.Limit).toBe(10);
     expect(params.FilterExpression).toMatch(/#likesCount > :likesCount_\d+/);
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
+    expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'Photo' });
   });
 
   test('SCAN with IN operator', async () => {
@@ -781,9 +790,11 @@ describe('Should test dbParams function builder', () => {
       .dbParams();
 
     expect(params.FilterExpression).toContain('IN');
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('alice');
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('bob');
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('charlie');
+    expect(Object.values(params.ExpressionAttributeValues || {})).toContain('User');
   });
 
   test('SCAN with size operator', async () => {
@@ -792,7 +803,9 @@ describe('Should test dbParams function builder', () => {
       .dbParams();
 
     expect(params.FilterExpression).toMatch(/size\(#name\) > :name_size_\d+/);
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain(5);
+    expect(Object.values(params.ExpressionAttributeValues || {})).toContain('User');
   });
 
   test('SCAN Comments with complex filter', async () => {
@@ -804,6 +817,8 @@ describe('Should test dbParams function builder', () => {
 
     expect(params.FilterExpression).toMatch(/attribute_exists\(#content\)/);
     expect(params.FilterExpression).toMatch(/size\(#content\) > :content_size_\d+/);
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
+    expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'Comment' });
     expect(params.ProjectionExpression).toBe('photoId, commentId, content');
     expect(params.Limit).toBe(50);
   });