@ftschopp/dynatable-core 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## @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/package.json

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