@ftschopp/dynatable-core 1.0.0

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

@@ -0,0 +1,230 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { QueryCommand } from '@aws-sdk/lib-dynamodb';
+import { mockClient } from 'aws-sdk-client-mock';
+import { createQueryBuilder } from './create-query-builder';
+import { ModelDefinition } from '../../core/types';
+
+const ddbMock = mockClient(DynamoDBClient);
+
+describe('QueryBuilder - Pagination', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface TestModel {
+    pk: string;
+    sk: string;
+    name?: string;
+    age?: number;
+    status?: string;
+  }
+
+  const testModel: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'USER#${username}' },
+      SK: { type: String, value: 'USER#${username}' },
+    },
+    attributes: {
+      username: { type: String, required: true },
+      name: { type: String },
+      age: { type: Number },
+      status: { type: String },
+    },
+  };
+
+  beforeEach(() => {
+    ddbMock.reset();
+  });
+
+  describe('startFrom method', () => {
+    test('should add ExclusiveStartKey to query params', () => {
+      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const params = createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .startFrom(startKey)
+        .dbParams();
+
+      expect(params.ExclusiveStartKey).toEqual(startKey);
+    });
+
+    test('should work with all other query options', () => {
+      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const params = createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .startFrom(startKey)
+        .limit(10)
+        .scanIndexForward(false)
+        .select(['name', 'age'])
+        .dbParams();
+
+      expect(params.ExclusiveStartKey).toEqual(startKey);
+      expect(params.Limit).toBe(10);
+      expect(params.ScanIndexForward).toBe(false);
+      expect(params.ProjectionExpression).toBe('name, age');
+    });
+
+    test('should not include ExclusiveStartKey if not set', () => {
+      const params = createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .dbParams();
+
+      expect(params.ExclusiveStartKey).toBeUndefined();
+    });
+  });
+
+  describe('executeWithPagination method', () => {
+    test('should return items and lastEvaluatedKey', async () => {
+      const mockItems = [
+        { pk: 'USER#alice', sk: 'USER#alice', name: 'Alice' },
+        { pk: 'USER#bob', sk: 'USER#bob', name: 'Bob' },
+      ];
+      const mockLastKey = { pk: 'USER#bob', sk: 'USER#bob' };
+
+      ddbMock.on(QueryCommand).resolves({
+        Items: mockItems,
+        LastEvaluatedKey: mockLastKey,
+        Count: 2,
+        ScannedCount: 2,
+      });
+
+      const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .limit(2)
+        .executeWithPagination();
+
+      expect(result.items).toEqual(mockItems);
+      expect(result.lastEvaluatedKey).toEqual(mockLastKey);
+      expect(result.count).toBe(2);
+      expect(result.scannedCount).toBe(2);
+    });
+
+    test('should return undefined lastEvaluatedKey when no more results', async () => {
+      const mockItems = [{ pk: 'USER#alice', sk: 'USER#alice', name: 'Alice' }];
+
+      ddbMock.on(QueryCommand).resolves({
+        Items: mockItems,
+        Count: 1,
+        ScannedCount: 1,
+      });
+
+      const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .executeWithPagination();
+
+      expect(result.items).toEqual(mockItems);
+      expect(result.lastEvaluatedKey).toBeUndefined();
+    });
+
+    test('should handle empty results', async () => {
+      ddbMock.on(QueryCommand).resolves({
+        Items: [],
+        Count: 0,
+        ScannedCount: 0,
+      });
+
+      const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.eq(attr.pk, 'USER#nonexistent'))
+        .executeWithPagination();
+
+      expect(result.items).toEqual([]);
+      expect(result.lastEvaluatedKey).toBeUndefined();
+      expect(result.count).toBe(0);
+      expect(result.scannedCount).toBe(0);
+    });
+  });
+
+  describe('Pagination workflow', () => {
+    test('should support manual pagination loop', async () => {
+      // First page
+      const page1Items = [
+        { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
+        { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+      ];
+      const page1LastKey = { pk: 'USER#2', sk: 'USER#2' };
+
+      // Second page
+      const page2Items = [
+        { pk: 'USER#3', sk: 'USER#3', name: 'User 3' },
+        { pk: 'USER#4', sk: 'USER#4', name: 'User 4' },
+      ];
+      const page2LastKey = { pk: 'USER#4', sk: 'USER#4' };
+
+      // Third page (last)
+      const page3Items = [{ pk: 'USER#5', sk: 'USER#5', name: 'User 5' }];
+
+      ddbMock
+        .on(QueryCommand)
+        .resolvesOnce({
+          Items: page1Items,
+          LastEvaluatedKey: page1LastKey,
+          Count: 2,
+          ScannedCount: 2,
+        })
+        .resolvesOnce({
+          Items: page2Items,
+          LastEvaluatedKey: page2LastKey,
+          Count: 2,
+          ScannedCount: 2,
+        })
+        .resolvesOnce({
+          Items: page3Items,
+          Count: 1,
+          ScannedCount: 1,
+        });
+
+      const allItems: any[] = [];
+      let lastKey: any = undefined;
+
+      // Page 1
+      const result1 = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .limit(2)
+        .executeWithPagination();
+
+      allItems.push(...result1.items);
+      lastKey = result1.lastEvaluatedKey;
+      expect(lastKey).toBeDefined();
+
+      // Page 2
+      const result2 = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .limit(2)
+        .startFrom(lastKey)
+        .executeWithPagination();
+
+      allItems.push(...result2.items);
+      lastKey = result2.lastEvaluatedKey;
+      expect(lastKey).toBeDefined();
+
+      // Page 3
+      const result3 = await createQueryBuilder<TestModel>(tableName, client, testModel)
+        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .limit(2)
+        .startFrom(lastKey)
+        .executeWithPagination();
+
+      allItems.push(...result3.items);
+      lastKey = result3.lastEvaluatedKey;
+      expect(lastKey).toBeUndefined();
+
+      // Verify all items collected
+      expect(allItems).toHaveLength(5);
+      expect(allItems[0].name).toBe('User 1');
+      expect(allItems[4].name).toBe('User 5');
+    });
+  });
+
+  describe('Immutability', () => {
+    test('should create new builder instance when using startFrom', () => {
+      const builder1 = createQueryBuilder<TestModel>(tableName, client, testModel).where(
+        (attr, op) => op.eq(attr.pk, 'USER#alice')
+      );
+
+      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const builder2 = builder1.startFrom(startKey);
+
+      expect(builder1.dbParams().ExclusiveStartKey).toBeUndefined();
+      expect(builder2.dbParams().ExclusiveStartKey).toEqual(startKey);
+    });
+  });
+});

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

@@ -0,0 +1,353 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { QueryCommand, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
+import { Condition, AttrBuilder, AttrRef } from '../shared';
+import { createOpBuilder } from '../shared/operators';
+import { buildExpression } from '../shared/conditions';
+import { QueryBuilder, QueryExecutor, QueryResult } from './types';
+import { ModelDefinition } from '../../core/types';
+import { extractTemplateVars } from '../../utils/model-utils';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Internal state for the query builder
+ */
+type QueryState<Model> = {
+  tableName: string;
+  client: DynamoDBClient;
+  model?: ModelDefinition;
+  condition?: Condition;
+  indexName?: string;
+  limitValue?: number;
+  scanForward?: boolean;
+  projection?: (keyof Model)[];
+  consistentReadEnabled?: boolean;
+  exclusiveStartKey?: Record<string, any>;
+  logger?: DynamoDBLogger;
+};
+
+/**
+ * Determines if a field is a key field (used in pk/sk templates)
+ */
+function isKeyField(fieldName: string, model?: ModelDefinition): boolean {
+  if (!model?.key) return false;
+
+  const keyEntries = Object.entries(model.key);
+  for (const [, keyDef] of keyEntries) {
+    const templateVars = extractTemplateVars(keyDef.value);
+    if (templateVars.includes(fieldName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
+ * Also returns the key template for value transformation
+ */
+function getKeyNameForAttribute(
+  fieldName: string,
+  model?: ModelDefinition
+): { keyName: string; template: string } | null {
+  if (!model?.key) return null;
+
+  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 null;
+}
+
+/**
+ * Apply key template to transform attribute value to key value
+ * e.g., applyKeyTemplate("UP#${username}", "username", "johndoe") -> "UP#johndoe"
+ */
+function applyKeyTemplate(template: string, fieldName: string, fieldValue: any): string {
+  return template.replace(`\${${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: Condition,
+  model?: ModelDefinition
+): { keyConditions: Condition[]; filterConditions: Condition[] } {
+  const keyConditions: Condition[] = [];
+  const filterConditions: Condition[] = [];
+
+  function traverse(cond: Condition) {
+    // If it's a combinator
+    if (cond.operator && cond.children) {
+      // For KeyConditionExpression, we can only use AND at the top level
+      if (cond.operator === 'AND') {
+        cond.children.forEach((child) => {
+          // Check if this is a leaf condition or another combinator
+          if (child.children) {
+            // Nested combinator - goes to filter
+            filterConditions.push(child);
+          } else {
+            traverse(child);
+          }
+        });
+      } else {
+        // OR at any level must go to filter
+        filterConditions.push(cond);
+      }
+      return;
+    }
+
+    // It's a leaf condition - check if it's a key field
+    // Extract field name from the expression (e.g., "#username" -> "username")
+    const fieldMatch = cond.expression.match(/#(\w+)/);
+    if (fieldMatch && fieldMatch[1]) {
+      const fieldName = fieldMatch[1];
+      const keyInfo = getKeyNameForAttribute(fieldName, model);
+
+      if (keyInfo) {
+        // This is a key field - rewrite the condition to use the actual key name
+        // and apply the template to the value
+
+        // Find the value placeholder in the condition and transform it
+        const newValues: Record<string, any> = {};
+        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);
+            newValues[valuePlaceholder] = transformedValue;
+          }
+        }
+
+        const rewrittenCond = {
+          ...cond,
+          expression: cond.expression.replace(
+            new RegExp(`#${fieldName}\\b`, 'g'),
+            `#${keyInfo.keyName}`
+          ),
+          names: {
+            [`#${keyInfo.keyName}`]: keyInfo.keyName,
+          },
+          values: newValues,
+        };
+
+        keyConditions.push(rewrittenCond);
+      } else {
+        filterConditions.push(cond);
+      }
+    } else {
+      // Can't determine field, put in filter to be safe
+      filterConditions.push(cond);
+    }
+  }
+
+  traverse(condition);
+
+  return { keyConditions, filterConditions };
+}
+
+/**
+ * Builds a simple AND expression from multiple conditions
+ */
+function buildSimpleAndExpression(conditions: Condition[]): {
+  expression: string;
+  names: Record<string, string>;
+  values: Record<string, any>;
+} {
+  if (conditions.length === 0) {
+    return { expression: '', names: {}, values: {} };
+  }
+
+  const expressions: string[] = [];
+  const names: Record<string, string> = {};
+  const values: Record<string, any> = {};
+
+  conditions.forEach((cond) => {
+    expressions.push(cond.expression);
+    Object.assign(names, cond.names || {});
+    Object.assign(values, cond.values || {});
+  });
+
+  return {
+    expression: expressions.join(' AND '),
+    names,
+    values,
+  };
+}
+
+/**
+ * Creates the query executor with all query methods
+ */
+function createQueryExecutor<Model, M extends ModelDefinition = any>(
+  state: QueryState<Model>
+): QueryExecutor<Model, M> {
+  return {
+    limit(count) {
+      return createQueryExecutor({
+        ...state,
+        limitValue: count,
+      });
+    },
+
+    scanIndexForward(forward) {
+      return createQueryExecutor({
+        ...state,
+        scanForward: forward,
+      });
+    },
+
+    useIndex(indexName) {
+      return createQueryExecutor({
+        ...state,
+        indexName,
+      });
+    },
+
+    select(attrs) {
+      return createQueryExecutor({
+        ...state,
+        projection: attrs,
+      });
+    },
+
+    consistentRead() {
+      return createQueryExecutor({
+        ...state,
+        consistentReadEnabled: true,
+      });
+    },
+
+    startFrom(key) {
+      return createQueryExecutor({
+        ...state,
+        exclusiveStartKey: key,
+      });
+    },
+
+    dbParams(): QueryCommandInput {
+      if (!state.condition) {
+        throw new Error('No where condition specified');
+      }
+
+      // Separate key conditions from filter conditions
+      const { keyConditions, filterConditions } = separateConditions(state.condition, state.model);
+
+      // Build KeyConditionExpression (simple AND)
+      const keyExpr = buildSimpleAndExpression(keyConditions);
+
+      // 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]);
+        } else {
+          // Multiple filter conditions - combine with AND
+          filterExpr = buildExpression({
+            expression: '',
+            operator: 'AND',
+            children: filterConditions,
+          });
+        }
+      }
+
+      // Merge attribute names and values from both expressions
+      const allNames = {
+        ...(keyExpr.names ?? {}),
+        ...(filterExpr.names ?? {}),
+      };
+      const allValues = {
+        ...(keyExpr.values ?? {}),
+        ...(filterExpr.values ?? {}),
+      };
+
+      return {
+        TableName: state.tableName,
+        ...(keyExpr.expression && {
+          KeyConditionExpression: keyExpr.expression,
+        }),
+        ...(filterExpr.expression && {
+          FilterExpression: filterExpr.expression,
+        }),
+        ...(Object.keys(allNames).length && {
+          ExpressionAttributeNames: allNames,
+        }),
+        ...(Object.keys(allValues).length && {
+          ExpressionAttributeValues: allValues,
+        }),
+        ...(state.indexName && { IndexName: state.indexName }),
+        ...(state.limitValue && { Limit: state.limitValue }),
+        ...(state.scanForward !== undefined && {
+          ScanIndexForward: state.scanForward,
+        }),
+        ...(state.projection &&
+          state.projection.length > 0 && {
+            ProjectionExpression: state.projection.join(', '),
+          }),
+        ...(state.consistentReadEnabled && { ConsistentRead: true }),
+        ...(state.exclusiveStartKey && {
+          ExclusiveStartKey: state.exclusiveStartKey,
+        }),
+      };
+    },
+
+    async execute(): Promise<Model[]> {
+      const params = this.dbParams();
+      const result = await state.client.send(new QueryCommand(params));
+      state.logger?.log('QueryCommand', params, result);
+      return (result.Items ?? []) as unknown as Model[];
+    },
+
+    async executeWithPagination(): Promise<QueryResult<Model>> {
+      const params = this.dbParams();
+      const result = await state.client.send(new QueryCommand(params));
+      state.logger?.log('QueryCommand', params, result);
+      return {
+        items: (result.Items ?? []) as unknown as Model[],
+        lastEvaluatedKey: result.LastEvaluatedKey,
+        count: result.Count,
+        scannedCount: result.ScannedCount,
+      };
+    },
+  };
+}
+
+/**
+ * Creates a QueryBuilder for a table
+ */
+export function createQueryBuilder<Model, M extends ModelDefinition = any>(
+  tableName: string,
+  client: DynamoDBClient,
+  model?: M,
+  logger?: DynamoDBLogger
+): QueryBuilder<Model, M> {
+  return {
+    where(fn) {
+      // Create attribute builder proxy
+      const attrProxy = new Proxy({} as AttrBuilder<Model>, {
+        get(_, prop: string): AttrRef {
+          return { name: prop };
+        },
+      });
+
+      // Create a scoped opBuilder for this query to avoid global state
+      const opBuilder = createOpBuilder();
+
+      // Call the user's function to get the condition tree
+      const condition = fn(attrProxy, opBuilder);
+
+      // Create initial state with the condition
+      const initialState: QueryState<Model> = {
+        tableName,
+        client,
+        model,
+        condition,
+        logger,
+      };
+
+      return createQueryExecutor(initialState);
+    },
+  };
+}

package/src/builders/query/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './create-query-builder';

package/src/builders/query/types.ts

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
+import { ModelDefinition } from '../../core/types';
+
+/**
+ * Query result with pagination support
+ */
+export interface QueryResult<Model> {
+  /**
+   * The items returned by the query
+   */
+  items: Model[];
+
+  /**
+   * The LastEvaluatedKey for pagination (if more results available)
+   */
+  lastEvaluatedKey?: Record<string, any>;
+
+  /**
+   * Number of items examined before applying filters
+   */
+  count?: number;
+
+  /**
+   * Number of items returned after applying filters
+   */
+  scannedCount?: number;
+}
+
+/**
+ * Query executor with additional query-specific options
+ */
+export interface QueryExecutor<Model, M extends ModelDefinition = any> extends ExecutableBuilder<
+  Model[]
+> {
+  /**
+   * Limit the number of items to return
+   */
+  limit(count: number): QueryExecutor<Model, M>;
+
+  /**
+   * Scan index forward (ascending) or backward (descending)
+   */
+  scanIndexForward(forward: boolean): QueryExecutor<Model, M>;
+
+  /**
+   * Use a secondary index
+   */
+  useIndex(indexName: string): QueryExecutor<Model, M>;
+
+  /**
+   * Select specific attributes to return
+   */
+  select(attrs: (keyof Model)[]): QueryExecutor<Model, M>;
+
+  /**
+   * Use consistent read
+   */
+  consistentRead(): QueryExecutor<Model, M>;
+
+  /**
+   * Start query from a specific key (for pagination)
+   */
+  startFrom(key: Record<string, any>): QueryExecutor<Model, M>;
+
+  /**
+   * Returns the raw DynamoDB query parameters
+   */
+  dbParams(): any;
+
+  /**
+   * Executes the query and returns matching items
+   */
+  execute(): Promise<Model[]>;
+
+  /**
+   * Executes the query and returns result with pagination metadata
+   */
+  executeWithPagination(): Promise<QueryResult<Model>>;
+}
+
+/**
+ * Main Query Builder interface with type-safe where clause
+ */
+export interface QueryBuilder<Model, M extends ModelDefinition = any> {
+  /**
+   * Build a condition expression using attributes and operators
+   * Usage: .where((attr, op) => op.eq(attr.username, 'juanca'))
+   * Usage: .where((attr, op) => op.and(
+   *   op.eq(attr.username, 'juanca'),
+   *   op.gt(attr.age, 18)
+   * ))
+   */
+  where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): QueryExecutor<Model, M>;
+}