@ftschopp/dynatable-core 1.2.4 → 1.3.0

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' };

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

@@ -2,11 +2,18 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { buildExpression, AttrBuilder, Condition, createOpBuilder, AttrRef } from '../shared';
-import { UpdateBuilder, UpdateAction } from './types';
+import { UpdateBuilder, UpdateAction, IndexContext } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+import { computeIndexUpdates } from '../../utils/model-utils';
 
 /**
  * Creates an UpdateBuilder for an item key and table.
+ *
+ * When `indexContext` is provided, fields written via `.set()` that participate
+ * in any secondary-index template are detected and the affected index keys are
+ * recomputed automatically and included in the SET expression. If a template
+ * cannot be fully resolved from the primary-key vars plus the updates, building
+ * the params throws — the caller must include the missing fields in `.set()`.
  */
 export function createUpdateBuilder<Model>(
   tableName: string,
@@ -22,7 +29,9 @@ export function createUpdateBuilder<Model>(
   returnMode: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW' = 'NONE',
   valueCounter = 0,
   enableTimestamps = false,
-  logger?: DynamoDBLogger
+  logger?: DynamoDBLogger,
+  indexContext?: IndexContext,
+  setInputs: Record<string, any> = {}
 ): UpdateBuilder<Model> {
   const conditions = [...prevConditions];
 
@@ -55,27 +64,25 @@ export function createUpdateBuilder<Model>(
         returnMode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        setInputs
       );
     },
 
     set(attrOrUpdates: keyof Model | AttrRef | Partial<Model>, value?: any) {
-      // Check if this is a multiple updates object
-      // An AttrRef has only 'name' property and is a string value
-      // Multiple updates is an object with no value parameter
+      // When no value is provided and the first arg is a plain object,
+      // treat it as a Partial<Model>. The AttrRef overload always passes
+      // a value, so it's handled by the single-update path below.
       if (
         value === undefined &&
         typeof attrOrUpdates === 'object' &&
-        attrOrUpdates !== null &&
-        !(
-          Object.keys(attrOrUpdates).length === 1 &&
-          'name' in attrOrUpdates &&
-          typeof (attrOrUpdates as any).name === 'string'
-        )
+        attrOrUpdates !== null
       ) {
         // Multiple updates case
         const updates = attrOrUpdates as Partial<Model>;
         const newActions: UpdateAction[] = [];
+        const newSetInputs = { ...setInputs };
 
         for (const [attr, val] of Object.entries(updates)) {
           const attrName = attr;
@@ -85,6 +92,7 @@ export function createUpdateBuilder<Model>(
             names: { [`#${attrName}`]: attrName },
             values: { [`:${valueName}`]: val },
           });
+          newSetInputs[attrName] = val;
         }
 
         return createUpdateBuilder(
@@ -96,7 +104,9 @@ export function createUpdateBuilder<Model>(
           returnMode,
           valueCounter,
           enableTimestamps,
-          logger
+          logger,
+          indexContext,
+          newSetInputs
         );
       }
 
@@ -117,7 +127,9 @@ export function createUpdateBuilder<Model>(
         returnMode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        { ...setInputs, [attrName]: value }
       );
     },
 
@@ -136,7 +148,9 @@ export function createUpdateBuilder<Model>(
         returnMode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        setInputs
       );
     },
 
@@ -157,7 +171,9 @@ export function createUpdateBuilder<Model>(
         returnMode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        setInputs
       );
     },
 
@@ -178,7 +194,9 @@ export function createUpdateBuilder<Model>(
         returnMode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        setInputs
       );
     },
 
@@ -192,7 +210,9 @@ export function createUpdateBuilder<Model>(
         mode,
         valueCounter,
         enableTimestamps,
-        logger
+        logger,
+        indexContext,
+        setInputs
       );
     },
 
@@ -203,7 +223,40 @@ export function createUpdateBuilder<Model>(
       const allValues: Record<string, any> = {};
 
       // Clone updateActions to avoid mutation
-      const actionsToProcess = { ...updateActions };
+      const actionsToProcess = { ...updateActions, set: [...updateActions.set] };
+
+      // Auto-recompute secondary-index keys whose templates depend on any
+      // updated field. If a template can't be fully resolved from the primary
+      // key vars + the .set() payload, we throw — recomputing from the
+      // existing item would require an extra read the builder won't do.
+      if (indexContext) {
+        const { actions: idxActions, missing } = computeIndexUpdates(
+          indexContext.model,
+          indexContext.keyVars,
+          setInputs
+        );
+        if (missing.length > 0) {
+          const details = missing
+            .map(
+              (m) =>
+                `  - ${m.index} ("${m.template}"): missing ${m.missing.join(', ')}`
+            )
+            .join('\n');
+          throw new Error(
+            `Update touches fields that participate in secondary index templates, ` +
+              `but the templates cannot be fully resolved from the update payload. ` +
+              `Include the missing fields in .set():\n${details}`
+          );
+        }
+        for (const [indexName, resolved] of Object.entries(idxActions)) {
+          const valueName = getUniqueValueName(indexName);
+          actionsToProcess.set.push({
+            expression: `#${indexName} = :${valueName}`,
+            names: { [`#${indexName}`]: indexName },
+            values: { [`:${valueName}`]: resolved },
+          });
+        }
+      }
 
       // Add updatedAt timestamp if enabled
       if (enableTimestamps) {

package/src/builders/update/types.ts

@@ -1,4 +1,5 @@
 import type { UpdateCommandInput } from '@aws-sdk/lib-dynamodb';
+import { ModelDefinition } from '@/core/types';
 import { OperationBuilder, AttrRef } from '../shared';
 
 /**
@@ -10,6 +11,19 @@ export type UpdateAction = {
   values?: Record<string, any>;
 };
 
+/**
+ * Context that lets the update builder auto-recompute secondary-index keys
+ * when a `.set()` touches a field that participates in their templates.
+ *
+ * `keyVars` carries the original template-variable values used to build the
+ * primary key (e.g. `{ id: '123' }` from `update({ id: '123' })`) so they can
+ * be combined with the user's `.set()` payload when resolving index templates.
+ */
+export type IndexContext = {
+  model: ModelDefinition;
+  keyVars: Record<string, any>;
+};
+
 /**
  * Builder interface for DynamoDB UpdateItem operations
  */

package/src/core/types.test.ts

@@ -287,12 +287,10 @@ describe('Schema Definition Validation', () => {
         },
       },
       params: {
-        isoDates: true,
         timestamps: true,
       },
     } as const satisfies SchemaDefinition;
 
-    expect(schemaWithParams.params?.isoDates).toBe(true);
     expect(schemaWithParams.params?.timestamps).toBe(true);
   });
 

package/src/core/types.ts

@@ -141,7 +141,6 @@ export type ModelDefinition = {
  * Schema parameters configuration
  */
 export type SchemaParams = {
-  isoDates?: boolean;
   timestamps?: boolean;
   cleanInternalKeys?: boolean;
 };

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

@@ -85,9 +85,10 @@ export const createEntityAPI = <Model extends ModelDefinition>(
     },
 
     query() {
-      // Query builder doesn't have execute() until after .where() is called
-      // The cleanInternalKeys will be handled in the builder itself
-      return createQueryBuilder<InferModel<Model>>(tableName, client, model, logger);
+      // Auto-filter by entity type so query() only returns items for this
+      // entity. Without this, queries on shared GSIs return items from other
+      // entities that share the same partition key.
+      return createQueryBuilder<InferModel<Model>>(tableName, client, model, logger, modelName);
     },
 
     scan() {
@@ -130,7 +131,10 @@ export const createEntityAPI = <Model extends ModelDefinition>(
         'NONE',
         0,
         timestamps,
-        logger
+        logger,
+        // Carry the original template-vars-bearing key (e.g. { username: 'jane' })
+        // so the builder can recompute index keys when .set() touches their template fields.
+        { model, keyVars: key as Record<string, unknown> }
       );
 
       return withMiddleware(builder, createCleanKeysMiddleware(cleanInternalKeys));

package/src/utils/model-utils.test.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { applyPostDefaults, stripInternalKeys } from './model-utils';
+import { applyPostDefaults, computeIndexUpdates, stripInternalKeys } from './model-utils';
 import { ModelDefinition } from '../core/types';
 
 describe('applyPostDefaults - Timestamps', () => {
@@ -360,3 +360,93 @@ describe('stripInternalKeys', () => {
     });
   });
 });
+
+describe('computeIndexUpdates', () => {
+  const personnelModel: ModelDefinition = {
+    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 },
+    },
+  };
+
+  test('returns empty result when model has no indexes', () => {
+    const noIndexModel: ModelDefinition = {
+      key: {
+        PK: { type: String, value: 'USER#${id}' },
+        SK: { type: String, value: 'USER#${id}' },
+      },
+      attributes: { id: { type: String, required: true } },
+    };
+    const result = computeIndexUpdates(noIndexModel, { id: '1' }, { name: 'X' });
+    expect(result).toEqual({ actions: {}, missing: [] });
+  });
+
+  test('skips indexes whose template references no updated field', () => {
+    // Updating only "role" — none of the index templates mention role.
+    const result = computeIndexUpdates(
+      personnelModel,
+      { id: '1' },
+      { role: 'pilot' }
+    );
+    expect(result).toEqual({ actions: {}, missing: [] });
+  });
+
+  test('recomputes an affected index when all template vars resolve', () => {
+    const result = computeIndexUpdates(
+      personnelModel,
+      { id: '1' },
+      { firstName: 'Ada', lastName: 'Lovelace' }
+    );
+    expect(result.actions).toEqual({ GSI1SK: 'PERSON#Lovelace#Ada' });
+    expect(result.missing).toEqual([]);
+  });
+
+  test('reports missing template vars instead of throwing', () => {
+    const result = computeIndexUpdates(
+      personnelModel,
+      { id: '1' },
+      { lastName: 'Lovelace' }
+    );
+    expect(result.actions).toEqual({});
+    expect(result.missing).toEqual([
+      {
+        index: 'GSI1SK',
+        template: 'PERSON#${lastName}#${firstName}',
+        missing: ['firstName'],
+      },
+    ]);
+  });
+
+  test('uses keyVars to resolve fields not present in updates', () => {
+    // airportId is not in updates but in keyVars — GSI1PK should still resolve.
+    const result = computeIndexUpdates(
+      personnelModel,
+      { id: '1', airportId: 'EZE' },
+      { airportId: 'AEP' } // changing it
+    );
+    expect(result.actions).toEqual({ GSI1PK: 'AIRPORT#AEP' });
+  });
+
+  test('handles multiple affected indexes independently', () => {
+    const result = computeIndexUpdates(
+      personnelModel,
+      { id: '1' },
+      { airportId: 'AEP', firstName: 'Ada', lastName: 'Lovelace' }
+    );
+    expect(result.actions).toEqual({
+      GSI1PK: 'AIRPORT#AEP',
+      GSI1SK: 'PERSON#Lovelace#Ada',
+    });
+    expect(result.missing).toEqual([]);
+  });
+});

package/src/utils/model-utils.ts

@@ -59,6 +59,60 @@ export const resolveKeys = <M extends ModelDefinition>(
   return out;
 };
 
+/**
+ * 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 const computeIndexUpdates = <M extends ModelDefinition>(
+  model: M,
+  keyVars: Record<string, any>,
+  updates: Record<string, any>
+): IndexUpdateAnalysis => {
+  const actions: Record<string, string> = {};
+  const missing: { index: string; template: string; missing: string[] }[] = [];
+
+  if (!model.index) return { actions, missing };
+
+  const updateKeys = new Set(Object.keys(updates));
+  const combined: Record<string, any> = { ...keyVars, ...updates };
+
+  for (const [indexName, indexDef] of Object.entries(model.index)) {
+    const templateVars = 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] = resolveTemplate(indexDef.value, combined);
+  }
+
+  return { actions, missing };
+};
+
 /**
  * Applies default and generated values to validated input
  */