@ftschopp/dynatable-core 1.2.5 → 1.3.0

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

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

@@ -250,15 +250,20 @@ describe('Should test dbParams function builder', () => {
       .where((attr, op) => op.eq(attr.username, 'juanca'))
       .dbParams();
 
-    // After query builder fix: username -> pk, and value gets template applied
+    // After query builder fix: username -> pk, and value gets template applied.
+    // Entity API auto-injects a `_type = <modelName>` filter so that queries on
+    // shared partition keys don't return items of other entities.
     expect(params).toEqual({
       TableName: 'InstagramClone',
       KeyConditionExpression: '#PK = :username_0',
+      FilterExpression: '#_type = :_type',
       ExpressionAttributeNames: {
         '#PK': 'PK',
+        '#_type': '_type',
       },
       ExpressionAttributeValues: {
         ':username_0': 'UP#juanca', // Template applied: UP#${username}
+        ':_type': 'Photo',
       },
     });
 
@@ -266,6 +271,7 @@ describe('Should test dbParams function builder', () => {
     expect(params.KeyConditionExpression).toMatch(/#PK = :username_\d+/);
     expect(params.ExpressionAttributeNames).toEqual({
       '#PK': 'PK',
+      '#_type': '_type',
     });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('UP#juanca');
   });
@@ -278,23 +284,27 @@ describe('Should test dbParams function builder', () => {
     expect(params).toEqual({
       TableName: 'InstagramClone',
       KeyConditionExpression: '#PK = :username_0',
-      FilterExpression: '#likesCount > :likesCount_1',
+      FilterExpression: '(#likesCount > :likesCount_1) AND (#_type = :_type)',
       ExpressionAttributeNames: {
         '#likesCount': 'likesCount',
         '#PK': 'PK',
+        '#_type': '_type',
       },
       ExpressionAttributeValues: {
         ':likesCount_1': 0,
         ':username_0': 'UP#juanca',
+        ':_type': 'Photo',
       },
     });
 
     expect(params.TableName).toBe('InstagramClone');
     expect(params.KeyConditionExpression).toMatch(/#PK = :username_\d+/);
     expect(params.FilterExpression).toMatch(/#likesCount > :likesCount_\d+/);
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(params.ExpressionAttributeNames).toEqual({
       '#PK': 'PK',
       '#likesCount': 'likesCount',
+      '#_type': '_type',
     });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('UP#juanca');
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain(0);
@@ -310,11 +320,14 @@ describe('Should test dbParams function builder', () => {
     expect(params).toEqual({
       TableName: 'InstagramClone',
       KeyConditionExpression: '#PK = :username_0',
+      FilterExpression: '#_type = :_type',
       ExpressionAttributeNames: {
         '#PK': 'PK',
+        '#_type': '_type',
       },
       ExpressionAttributeValues: {
         ':username_0': 'UP#juanca',
+        ':_type': 'Photo',
       },
       Limit: 10,
       ScanIndexForward: false,
@@ -344,16 +357,19 @@ describe('Should test dbParams function builder', () => {
     expect(params).toEqual({
       TableName: 'InstagramClone',
       KeyConditionExpression: '#PK = :photoId_0',
+      FilterExpression: '#_type = :_type',
       ExpressionAttributeNames: {
         '#PK': 'PK',
+        '#_type': '_type',
       },
       ExpressionAttributeValues: {
         ':photoId_0': 'PL#photo123', // Template applied: PL#${photoId}
+        ':_type': 'Like',
       },
     });
     expect(params.TableName).toBe('InstagramClone');
     expect(params.KeyConditionExpression).toMatch(/#PK = :photoId_\d+/);
-    expect(params.ExpressionAttributeNames).toEqual({ '#PK': 'PK' });
+    expect(params.ExpressionAttributeNames).toEqual({ '#PK': 'PK', '#_type': '_type' });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('PL#photo123');
   });
 
@@ -372,10 +388,12 @@ describe('Should test dbParams function builder', () => {
     expect(params.FilterExpression).toMatch(
       /\(#likesCount > :likesCount_\d+\) OR \(#commentCount > :commentCount_\d+\)/
     );
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(params.ExpressionAttributeNames).toEqual({
       '#PK': 'PK',
       '#likesCount': 'likesCount',
       '#commentCount': 'commentCount',
+      '#_type': '_type',
     });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('UP#juanca');
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain(100);
@@ -401,10 +419,12 @@ describe('Should test dbParams function builder', () => {
       /\(#likesCount > :likesCount_\d+\) AND \(#commentCount < :commentCount_\d+\)/
     );
     expect(params.FilterExpression).toMatch(/OR/);
+    expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(params.ExpressionAttributeNames).toEqual({
       '#PK': 'PK',
       '#likesCount': 'likesCount',
       '#commentCount': 'commentCount',
+      '#_type': '_type',
     });
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain('UP#juanca');
     expect(Object.values(params.ExpressionAttributeValues || {})).toContain(100);