@ftschopp/dynatable-core 1.2.4 → 1.3.0

package/dist/utils/model-utils.js

@@ -1,7 +1,7 @@
 "use strict";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripInternalKeys = exports.applyPostDefaults = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
+exports.stripInternalKeys = exports.applyPostDefaults = exports.computeIndexUpdates = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
 const ulid_1 = require("ulid");
 /**
  * Extracts all variable names from a template string
@@ -53,6 +53,39 @@ const resolveKeys = (model, input, type = 'key') => {
     return out;
 };
 exports.resolveKeys = resolveKeys;
+/**
+ * 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.
+ */
+const computeIndexUpdates = (model, keyVars, updates) => {
+    const actions = {};
+    const missing = [];
+    if (!model.index)
+        return { actions, missing };
+    const updateKeys = new Set(Object.keys(updates));
+    const combined = { ...keyVars, ...updates };
+    for (const [indexName, indexDef] of Object.entries(model.index)) {
+        const templateVars = (0, exports.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] = (0, exports.resolveTemplate)(indexDef.value, combined);
+    }
+    return { actions, missing };
+};
+exports.computeIndexUpdates = computeIndexUpdates;
 /**
  * Applies default and generated values to validated input
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/builders/batch-get/README.md

@@ -1,57 +1,29 @@
 # BatchGet Builder
 
-The `BatchGetBuilder` allows retrieving multiple items from one or more tables in a single request to DynamoDB.
+The `BatchGetBuilder` retrieves multiple items by key in a single DynamoDB `BatchGetItem` request. It is consumed via the entity API (`table.entities.<Entity>.batchGet([...])`), and `execute()` returns a flat `Model[]`.
 
 ## Features
 
 - Retrieve multiple items by their keys
 - Supports attribute projection (select only specific fields)
 - Supports consistent read
-- Can retrieve items from multiple tables in a single request
 
 ## Basic Usage
 
 ```typescript
-import { createBatchGetBuilder } from './builders/batch-get';
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+const users = await table.entities.User.batchGet([
+  { username: 'alice' },
+  { username: 'bob' },
+  { username: 'charlie' },
+]).execute();
 
-const client = new DynamoDBClient({});
-
-// Retrieve multiple users
-const result = await createBatchGetBuilder(
-  {
-    Users: {
-      Keys: [
-        { pk: 'USER#alice', sk: 'USER#alice' },
-        { pk: 'USER#bob', sk: 'USER#bob' },
-        { pk: 'USER#charlie', sk: 'USER#charlie' },
-      ],
-    },
-  },
-  client
-).execute();
+users.forEach((user) => console.log(user.username));
 ```
 
 ## With Attribute Projection
 
 ```typescript
-interface User {
-  username: string;
-  name: string;
-  followerCount: number;
-}
-
-const result = await createBatchGetBuilder<User>(
-  {
-    Users: {
-      Keys: [
-        { pk: 'USER#alice', sk: 'USER#alice' },
-        { pk: 'USER#bob', sk: 'USER#bob' },
-      ],
-    },
-  },
-  client
-)
+const users = await table.entities.User.batchGet([{ username: 'alice' }, { username: 'bob' }])
   .select(['username', 'name', 'followerCount'])
   .execute();
 ```
@@ -59,38 +31,11 @@ const result = await createBatchGetBuilder<User>(
 ## With Consistent Read
 
 ```typescript
-const result = await createBatchGetBuilder(
-  {
-    Users: {
-      Keys: [
-        { pk: 'USER#alice', sk: 'USER#alice' },
-        { pk: 'USER#bob', sk: 'USER#bob' },
-      ],
-    },
-  },
-  client
-)
+const users = await table.entities.User.batchGet([{ username: 'alice' }, { username: 'bob' }])
   .consistentRead()
   .execute();
 ```
 
-## Using the Table Class
-
-```typescript
-// Retrieve multiple users using the Table class
-const result = await table
-  .batchGet({
-    InstagramClone: {
-      Keys: [
-        { pk: 'USER#alice', sk: 'USER#alice' },
-        { pk: 'USER#bob', sk: 'USER#bob' },
-      ],
-    },
-  })
-  .select(['username', 'name'])
-  .execute();
-```
-
 ## DynamoDB Limitations
 
 - Maximum 100 items per request

package/src/builders/batch-get/create-batch-get-builder.ts

@@ -84,23 +84,18 @@ export function createBatchGetBuilder<Model>(
     },
 
     /**
-     * Execute the BatchGetItem command and return the items.
+     * Execute the BatchGetItem command and return the items as a flat array.
      */
-    async execute(): Promise<Record<string, Model[]>> {
+    async execute(): Promise<Model[]> {
       const params = this.dbParams();
       const result: BatchGetCommandOutput = await client.send(new BatchGetCommand(params));
       logger?.log('BatchGetCommand', params, result);
 
-      // Transform the response into a more usable format
-      const responses: Record<string, Model[]> = {};
-
-      if (result.Responses) {
-        for (const [tableName, items] of Object.entries(result.Responses)) {
-          responses[tableName] = items as unknown as Model[];
-        }
+      if (!result.Responses) {
+        return [];
       }
 
-      return responses;
+      return Object.values(result.Responses).flat() as unknown as Model[];
     },
   };
 }

package/src/builders/batch-get/types.ts

@@ -22,8 +22,7 @@ export type BatchGetBuilder<Model> = {
   dbParams(): BatchGetItemCommandInput;
 
   /**
-   * Execute the BatchGetItem command and return the items.
-   * Returns an object mapping table names to arrays of items.
+   * Execute the BatchGetItem command and return the items as a flat array.
    */
-  execute(): Promise<Record<string, Model[]>>;
+  execute(): Promise<Model[]>;
 };

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[];
 };