@ftschopp/dynatable-core 1.2.5 → 1.3.0

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

@@ -298,3 +298,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,
           });
         }
       }
@@ -322,7 +361,8 @@ export function createQueryBuilder<Model>(
   tableName: string,
   client: DynamoDBClient,
   model?: ModelDefinition,
-  logger?: DynamoDBLogger
+  logger?: DynamoDBLogger,
+  entityType?: string
 ): QueryBuilder<Model> {
   return {
     where(fn) {
@@ -346,6 +386,7 @@ export function createQueryBuilder<Model>(
         model,
         condition,
         logger,
+        entityType,
       };
 
       return createQueryExecutor(initialState);

package/src/builders/shared/operators.ts

@@ -21,6 +21,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} = :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'eq',
       };
     },
     ne: (attr, value) => {
@@ -29,6 +30,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} <> :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'ne',
       };
     },
     lt: (attr, value) => {
@@ -37,6 +39,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} < :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'lt',
       };
     },
     lte: (attr, value) => {
@@ -45,6 +48,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} <= :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'lte',
       };
     },
     gt: (attr, value) => {
@@ -53,6 +57,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} > :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'gt',
       };
     },
     gte: (attr, value) => {
@@ -61,6 +66,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `#${attr.name} >= :${valueName}`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'gte',
       };
     },
     between: (attr, low, high) => {
@@ -73,6 +79,7 @@ export function createOpBuilder(): OpBuilder {
           [`:${lowName}`]: low,
           [`:${highName}`]: high,
         },
+        keyOperator: 'between',
       };
     },
     beginsWith: (attr, value) => {
@@ -81,6 +88,7 @@ export function createOpBuilder(): OpBuilder {
         expression: `begins_with(#${attr.name}, :${valueName})`,
         names: { [`#${attr.name}`]: attr.name },
         values: { [`:${valueName}`]: value },
+        keyOperator: 'beginsWith',
       };
     },
     contains: (attr, value) => {

package/src/builders/shared/types.ts

@@ -11,6 +11,7 @@ export type Condition = {
   names?: Record<string, string>;
   values?: Record<string, any>;
   operator?: 'AND' | 'OR';
+  keyOperator?: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'beginsWith';
   isNegated?: boolean;
   children?: Condition[];
 };

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

@@ -76,6 +76,30 @@ describe('UpdateBuilder', () => {
       });
     });
 
+    test('should build params with single-property object whose key is "name"', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createUpdateBuilder<TestModel>(tableName, key, client)
+        .set({ name: 'Ministro Pistarini' })
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #name = :name_0');
+      expect(params.ExpressionAttributeNames).toEqual({ '#name': 'name' });
+      expect(params.ExpressionAttributeValues).toEqual({
+        ':name_0': 'Ministro Pistarini',
+      });
+    });
+
+    test('should build params with single-property object whose key is not "name"', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createUpdateBuilder<TestModel>(tableName, key, client)
+        .set({ age: 30 })
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #age = :age_0');
+      expect(params.ExpressionAttributeNames).toEqual({ '#age': 'age' });
+      expect(params.ExpressionAttributeValues).toEqual({ ':age_0': 30 });
+    });
+
     test('should combine single and multiple SET operations', () => {
       const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
       const params = createUpdateBuilder<TestModel>(tableName, key, client)
@@ -344,6 +368,179 @@ describe('UpdateBuilder', () => {
     });
   });
 
+  describe('Secondary-index recomputation (indexContext)', () => {
+    interface PersonnelModel {
+      id: string;
+      airportId: string;
+      firstName: string;
+      lastName: string;
+      role: string;
+    }
+
+    const personnelModel = {
+      key: {
+        PK: { type: String, value: 'PERSON#${id}' },
+        SK: { type: String, value: 'PROFILE' },
+      },
+      index: {
+        GSI1PK: { type: String, value: 'AIRPORT#${airportId}' },
+        GSI1SK: { type: String, value: 'PERSON#${lastName}#${firstName}' },
+      },
+      attributes: {
+        id: { type: String, required: true },
+        airportId: { type: String, required: true },
+        firstName: { type: String, required: true },
+        lastName: { type: String, required: true },
+        role: { type: String },
+      },
+    } as const;
+
+    test('does nothing when no .set() field appears in any index template', () => {
+      const params = createUpdateBuilder<PersonnelModel>(
+        tableName,
+        { id: '1' } as Partial<PersonnelModel>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        false,
+        undefined,
+        { model: personnelModel as any, keyVars: { id: '1' } }
+      )
+        .set('role', 'pilot')
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #role = :role_0');
+      expect(params.ExpressionAttributeNames).toEqual({ '#role': 'role' });
+    });
+
+    test('recomputes affected index when all template vars are present in updates', () => {
+      const params = createUpdateBuilder<PersonnelModel>(
+        tableName,
+        { id: '1' } as Partial<PersonnelModel>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        false,
+        undefined,
+        { model: personnelModel as any, keyVars: { id: '1' } }
+      )
+        .set({ firstName: 'Ada', lastName: 'Lovelace' })
+        .dbParams();
+
+      // GSI1SK depends on lastName + firstName — both supplied → recomputed.
+      // GSI1PK depends on airportId — untouched, no recompute.
+      expect(params.UpdateExpression).toBe(
+        'SET #firstName = :firstName_0, #lastName = :lastName_1, #GSI1SK = :GSI1SK_2'
+      );
+      expect(params.ExpressionAttributeValues).toMatchObject({
+        ':firstName_0': 'Ada',
+        ':lastName_1': 'Lovelace',
+        ':GSI1SK_2': 'PERSON#Lovelace#Ada',
+      });
+    });
+
+    test('throws when an affected index template references a field not in updates or key', () => {
+      const builder = createUpdateBuilder<PersonnelModel>(
+        tableName,
+        { id: '1' } as Partial<PersonnelModel>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        false,
+        undefined,
+        { model: personnelModel as any, keyVars: { id: '1' } }
+      ).set({ lastName: 'Lovelace' });
+
+      // GSI1SK template = "PERSON#${lastName}#${firstName}" — firstName is missing.
+      expect(() => builder.dbParams()).toThrow(/firstName/);
+      expect(() => builder.dbParams()).toThrow(/GSI1SK/);
+    });
+
+    test('uses primary-key template vars when resolving index templates', () => {
+      const userModel = {
+        key: {
+          PK: { type: String, value: 'USER#${username}' },
+          SK: { type: String, value: 'USER#${username}' },
+        },
+        index: {
+          GSI1PK: { type: String, value: 'USER#${username}#STATUS#${status}' },
+        },
+        attributes: {
+          username: { type: String, required: true },
+          status: { type: String, required: true },
+        },
+      } as const;
+
+      const params = createUpdateBuilder<{ username: string; status: string }>(
+        tableName,
+        { username: 'jane' } as any,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        false,
+        undefined,
+        { model: userModel as any, keyVars: { username: 'jane' } }
+      )
+        .set('status', 'active')
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe(
+        'SET #status = :status_0, #GSI1PK = :GSI1PK_1'
+      );
+      expect(params.ExpressionAttributeValues).toMatchObject({
+        ':status_0': 'active',
+        ':GSI1PK_1': 'USER#jane#STATUS#active',
+      });
+    });
+
+    test('accumulates set inputs across chained calls before resolving', () => {
+      const params = createUpdateBuilder<PersonnelModel>(
+        tableName,
+        { id: '1' } as Partial<PersonnelModel>,
+        client,
+        [],
+        { set: [], remove: [], add: [], delete: [] },
+        'NONE',
+        0,
+        false,
+        undefined,
+        { model: personnelModel as any, keyVars: { id: '1' } }
+      )
+        .set('lastName', 'Lovelace')
+        .set('firstName', 'Ada')
+        .dbParams();
+
+      // Each individual .set() was missing one var, but the accumulator has both
+      // by the time dbParams() runs.
+      expect(params.UpdateExpression).toBe(
+        'SET #lastName = :lastName_0, #firstName = :firstName_1, #GSI1SK = :GSI1SK_2'
+      );
+      expect(params.ExpressionAttributeValues).toMatchObject({
+        ':GSI1SK_2': 'PERSON#Lovelace#Ada',
+      });
+    });
+
+    test('does nothing when indexContext is omitted (backwards-compatible default)', () => {
+      const params = createUpdateBuilder<PersonnelModel>(
+        tableName,
+        { id: '1' } as Partial<PersonnelModel>,
+        client
+      )
+        .set({ lastName: 'Lovelace' })
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #lastName = :lastName_0');
+    });
+  });
+
   describe('Complex scenarios', () => {
     test('should handle complex update with all features', () => {
       const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };