@ftschopp/dynatable-core 1.0.0

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

@@ -0,0 +1,260 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createScanBuilder } from './create-scan-builder';
+
+describe('ScanBuilder', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface TestModel {
+    pk: string;
+    sk: string;
+    name?: string;
+    age?: number;
+    status?: string;
+    score?: number;
+  }
+
+  describe('Basic scan operations', () => {
+    test('should build params for basic scan', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.FilterExpression).toBeUndefined();
+      expect(params.ProjectionExpression).toBeUndefined();
+      expect(params.Limit).toBeUndefined();
+    });
+
+    test('should build params with filter', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.eq(attr.status, 'active'))
+        .dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.FilterExpression).toMatch(/#status = :status_\d+/);
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#status': 'status',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('active');
+    });
+
+    test('should build params with multiple filters using AND', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.gt(attr.age, 18))
+        .filter((attr, op) => op.eq(attr.status, 'active'))
+        .dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.FilterExpression).toMatch(/\(#age > :age_\d+\) AND \(#status = :status_\d+\)/);
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#age': 'age',
+        '#status': 'status',
+      });
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(18);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('active');
+    });
+
+    test('should build params with OR filter', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.or(op.eq(attr.status, 'active'), op.eq(attr.status, 'pending')))
+        .dbParams();
+
+      expect(params.FilterExpression).toMatch(
+        /\(#status = :status_\d+\) OR \(#status = :status_\d+\)/
+      );
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('active');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('pending');
+    });
+  });
+
+  describe('Projection', () => {
+    test('should build params with select', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'age', 'status'])
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('name, age, status');
+    });
+
+    test('should build params with select and filter', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'age'])
+        .filter((attr, op) => op.gt(attr.age, 18))
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('name, age');
+      expect(params.FilterExpression).toMatch(/#age > :age_\d+/);
+    });
+  });
+
+  describe('Limit', () => {
+    test('should build params with limit', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).limit(100).dbParams();
+
+      expect(params.Limit).toBe(100);
+    });
+
+    test('should build params with limit and filter', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.eq(attr.status, 'active'))
+        .limit(50)
+        .dbParams();
+
+      expect(params.Limit).toBe(50);
+      expect(params.FilterExpression).toMatch(/#status = :status_\d+/);
+    });
+  });
+
+  describe('Consistent Read', () => {
+    test('should build params with consistent read', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).consistentRead().dbParams();
+
+      expect(params.ConsistentRead).toBe(true);
+    });
+
+    test('should not set ConsistentRead by default', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).dbParams();
+
+      expect(params.ConsistentRead).toBeUndefined();
+    });
+  });
+
+  describe('Index Scan', () => {
+    test('should build params with index name', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).usingIndex('GSI1').dbParams();
+
+      expect(params.IndexName).toBe('GSI1');
+    });
+
+    test('should build params with index and filter', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .usingIndex('GSI1')
+        .filter((attr, op) => op.gt(attr.score, 100))
+        .dbParams();
+
+      expect(params.IndexName).toBe('GSI1');
+      expect(params.FilterExpression).toMatch(/#score > :score_\d+/);
+    });
+  });
+
+  describe('Pagination', () => {
+    test('should build params with ExclusiveStartKey', () => {
+      const startKey = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createScanBuilder<TestModel>(tableName, client).startFrom(startKey).dbParams();
+
+      expect(params.ExclusiveStartKey).toEqual(startKey);
+    });
+  });
+
+  describe('Parallel Scan', () => {
+    test('should build params with segment configuration', () => {
+      const params = createScanBuilder<TestModel>(tableName, client).segment(0, 4).dbParams();
+
+      expect(params.Segment).toBe(0);
+      expect(params.TotalSegments).toBe(4);
+    });
+
+    test('should build params with multiple segments', () => {
+      const params1 = createScanBuilder<TestModel>(tableName, client).segment(0, 3).dbParams();
+      const params2 = createScanBuilder<TestModel>(tableName, client).segment(1, 3).dbParams();
+      const params3 = createScanBuilder<TestModel>(tableName, client).segment(2, 3).dbParams();
+
+      expect(params1.Segment).toBe(0);
+      expect(params1.TotalSegments).toBe(3);
+      expect(params2.Segment).toBe(1);
+      expect(params2.TotalSegments).toBe(3);
+      expect(params3.Segment).toBe(2);
+      expect(params3.TotalSegments).toBe(3);
+    });
+  });
+
+  describe('Complex scenarios', () => {
+    test('should build params with all features', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.and(op.gt(attr.age, 18), op.eq(attr.status, 'active')))
+        .select(['name', 'age', 'status'])
+        .limit(100)
+        .consistentRead()
+        .usingIndex('GSI1')
+        .dbParams();
+
+      expect(params.TableName).toBe(tableName);
+      expect(params.FilterExpression).toMatch(/\(#age > :age_\d+\) AND \(#status = :status_\d+\)/);
+      expect(params.ProjectionExpression).toBe('name, age, status');
+      expect(params.Limit).toBe(100);
+      expect(params.ConsistentRead).toBe(true);
+      expect(params.IndexName).toBe('GSI1');
+    });
+
+    test('should build params for parallel scan with filter and limit', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.exists(attr.name))
+        .limit(50)
+        .segment(1, 4)
+        .dbParams();
+
+      expect(params.FilterExpression).toMatch(/attribute_exists\(#name\)/);
+      expect(params.Limit).toBe(50);
+      expect(params.Segment).toBe(1);
+      expect(params.TotalSegments).toBe(4);
+    });
+  });
+
+  describe('Immutability', () => {
+    test('should create new builder instance on each method call', () => {
+      const builder1 = createScanBuilder<TestModel>(tableName, client);
+      const builder2 = builder1.filter((attr, op) => op.eq(attr.status, 'active'));
+      const builder3 = builder2.limit(50);
+
+      expect(builder1.dbParams().FilterExpression).toBeUndefined();
+      expect(builder1.dbParams().Limit).toBeUndefined();
+
+      expect(builder2.dbParams().FilterExpression).toMatch(/#status = :status_\d+/);
+      expect(builder2.dbParams().Limit).toBeUndefined();
+
+      expect(builder3.dbParams().FilterExpression).toMatch(/#status = :status_\d+/);
+      expect(builder3.dbParams().Limit).toBe(50);
+    });
+  });
+
+  describe('Advanced operators', () => {
+    test('should support contains operator', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.contains(attr.name, 'John'))
+        .dbParams();
+
+      expect(params.FilterExpression).toMatch(/contains\(#name, :name_\d+\)/);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('John');
+    });
+
+    test('should support IN operator', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.in(attr.status, ['active', 'pending', 'approved']))
+        .dbParams();
+
+      expect(params.FilterExpression).toContain('IN');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('active');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('pending');
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain('approved');
+    });
+
+    test('should support size operator', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.size(attr.name).gt(10))
+        .dbParams();
+
+      expect(params.FilterExpression).toMatch(/size\(#name\) > :name_size_\d+/);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(10);
+    });
+
+    test('should support between operator', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .filter((attr, op) => op.between(attr.age, 18, 65))
+        .dbParams();
+
+      expect(params.FilterExpression).toMatch(/#age BETWEEN :age_low_\d+ AND :age_high_\d+/);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(18);
+      expect(Object.values(params.ExpressionAttributeValues || {})).toContain(65);
+    });
+  });
+});

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

@@ -0,0 +1,217 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { buildExpression, AttrBuilder, Condition, createOpBuilder } from '../shared';
+import { ScanBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+
+/**
+ * Creates a ScanBuilder for scanning a table or index.
+ */
+export function createScanBuilder<Model>(
+  tableName: string,
+  client: DynamoDBClient,
+  filters: Condition[] = [],
+  projectionAttrs: (keyof Model)[] = [],
+  limitValue?: number,
+  isConsistentRead = false,
+  indexName?: string,
+  exclusiveStartKey?: Record<string, any>,
+  segmentConfig?: { segment: number; totalSegments: number },
+  logger?: DynamoDBLogger
+): ScanBuilder<Model> {
+  const build = (): ScanBuilder<Model> => ({
+    filter(fn) {
+      const attrs = new Proxy({} as AttrBuilder<Model>, {
+        get(_, prop: string) {
+          return { name: prop };
+        },
+      });
+      const opBuilder = createOpBuilder();
+      const condition = fn(attrs, opBuilder);
+      return createScanBuilder(
+        tableName,
+        client,
+        [...filters, condition],
+        projectionAttrs,
+        limitValue,
+        isConsistentRead,
+        indexName,
+        exclusiveStartKey,
+        segmentConfig,
+        logger
+      );
+    },
+
+    select(attrs) {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        attrs,
+        limitValue,
+        isConsistentRead,
+        indexName,
+        exclusiveStartKey,
+        segmentConfig,
+        logger
+      );
+    },
+
+    limit(count) {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        projectionAttrs,
+        count,
+        isConsistentRead,
+        indexName,
+        exclusiveStartKey,
+        segmentConfig,
+        logger
+      );
+    },
+
+    consistentRead() {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        projectionAttrs,
+        limitValue,
+        true,
+        indexName,
+        exclusiveStartKey,
+        segmentConfig,
+        logger
+      );
+    },
+
+    usingIndex(index) {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        projectionAttrs,
+        limitValue,
+        isConsistentRead,
+        index,
+        exclusiveStartKey,
+        segmentConfig,
+        logger
+      );
+    },
+
+    startFrom(key) {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        projectionAttrs,
+        limitValue,
+        isConsistentRead,
+        indexName,
+        key,
+        segmentConfig,
+        logger
+      );
+    },
+
+    segment(segmentNumber, totalSegments) {
+      return createScanBuilder(
+        tableName,
+        client,
+        filters,
+        projectionAttrs,
+        limitValue,
+        isConsistentRead,
+        indexName,
+        exclusiveStartKey,
+        { segment: segmentNumber, totalSegments },
+        logger
+      );
+    },
+
+    dbParams() {
+      let filterExpression = '';
+      let expressionAttributeNames: Record<string, string> = {};
+      let expressionAttributeValues: Record<string, any> = {};
+
+      // Build FilterExpression from filters
+      if (filters.length > 0) {
+        const combinedFilter =
+          filters.length === 1 && filters[0]
+            ? filters[0]
+            : {
+                expression: '',
+                operator: 'AND' as const,
+                children: filters,
+              };
+
+        const result = buildExpression(combinedFilter);
+        filterExpression = result.expression;
+        expressionAttributeNames = result.names;
+        expressionAttributeValues = result.values;
+      }
+
+      // Build ProjectionExpression
+      let projectionExpression = '';
+      if (projectionAttrs.length > 0) {
+        projectionExpression = projectionAttrs.map((attr) => String(attr)).join(', ');
+      }
+
+      const params: any = {
+        TableName: tableName,
+      };
+
+      if (filterExpression) {
+        params.FilterExpression = filterExpression;
+      }
+
+      if (Object.keys(expressionAttributeNames).length > 0) {
+        params.ExpressionAttributeNames = expressionAttributeNames;
+      }
+
+      if (Object.keys(expressionAttributeValues).length > 0) {
+        params.ExpressionAttributeValues = expressionAttributeValues;
+      }
+
+      if (projectionExpression) {
+        params.ProjectionExpression = projectionExpression;
+      }
+
+      if (limitValue !== undefined) {
+        params.Limit = limitValue;
+      }
+
+      if (isConsistentRead) {
+        params.ConsistentRead = true;
+      }
+
+      if (indexName) {
+        params.IndexName = indexName;
+      }
+
+      if (exclusiveStartKey) {
+        params.ExclusiveStartKey = exclusiveStartKey;
+      }
+
+      if (segmentConfig) {
+        params.Segment = segmentConfig.segment;
+        params.TotalSegments = segmentConfig.totalSegments;
+      }
+
+      return params;
+    },
+
+    async execute() {
+      const params = build().dbParams();
+      const response = await client.send(new ScanCommand(params));
+      logger?.log('ScanCommand', params, response);
+      return (response.Items || []) as Model[];
+    },
+  });
+
+  return build();
+}

package/src/builders/scan/index.ts

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

package/src/builders/scan/types.ts

@@ -0,0 +1,49 @@
+import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
+
+/**
+ * Builder for DynamoDB Scan operations.
+ * Scans the entire table or index without requiring key conditions.
+ */
+export interface ScanBuilder<Model> extends ExecutableBuilder<Model[]> {
+  /**
+   * Adds a filter expression to the scan.
+   * Returns a new immutable builder.
+   */
+  filter(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): ScanBuilder<Model>;
+
+  /**
+   * Adds a projection expression to only return specific attributes.
+   * Returns a new immutable builder.
+   */
+  select(attrs: (keyof Model)[]): ScanBuilder<Model>;
+
+  /**
+   * Sets the maximum number of items to evaluate (not necessarily return).
+   * Returns a new immutable builder.
+   */
+  limit(count: number): ScanBuilder<Model>;
+
+  /**
+   * Enables consistent read (eventual consistency is default).
+   * Returns a new immutable builder.
+   */
+  consistentRead(): ScanBuilder<Model>;
+
+  /**
+   * Specifies an index to scan.
+   * Returns a new immutable builder.
+   */
+  usingIndex(indexName: string): ScanBuilder<Model>;
+
+  /**
+   * Sets the starting position for the scan (pagination).
+   * Returns a new immutable builder.
+   */
+  startFrom(exclusiveStartKey: Record<string, any>): ScanBuilder<Model>;
+
+  /**
+   * Enables parallel scan by specifying segment and total segments.
+   * Returns a new immutable builder.
+   */
+  segment(segmentNumber: number, totalSegments: number): ScanBuilder<Model>;
+}

package/src/builders/shared/conditions.ts

@@ -0,0 +1,58 @@
+import { Condition } from './types';
+
+/**
+ * Builds a DynamoDB expression from a condition tree
+ */
+export function buildExpression(condition: Condition): {
+  expression: string;
+  names: Record<string, string>;
+  values: Record<string, any>;
+} {
+  const names: Record<string, string> = {};
+  const values: Record<string, any> = {};
+
+  function processCondition(cond: Condition): string {
+    // If it's a combinator (AND/OR)
+    if (cond.operator && cond.children) {
+      const childExpressions = cond.children
+        .map((child) => processCondition(child))
+        .filter((expr) => expr.length > 0);
+
+      if (childExpressions.length === 0) return '';
+      if (childExpressions.length === 1) return childExpressions[0]!;
+
+      const combined = childExpressions.map((expr) => `(${expr})`).join(` ${cond.operator} `);
+
+      return cond.isNegated ? `NOT (${combined})` : combined;
+    }
+
+    // It's a leaf condition
+    if (cond.names) {
+      Object.assign(names, cond.names);
+    }
+    if (cond.values) {
+      Object.assign(values, cond.values);
+    }
+
+    return cond.isNegated ? `NOT (${cond.expression})` : cond.expression;
+  }
+
+  const expression = processCondition(condition);
+
+  return { expression, names, values };
+}
+
+/**
+ * Combines multiple conditions into a DynamoDB-compatible expression object.
+ */
+export function buildConditionExpr(conditions: Condition[]) {
+  const expression = conditions.map((c) => c.expression).join(' AND ');
+  const names = Object.assign({}, ...conditions.map((c) => c.names ?? {}));
+  const values = Object.assign({}, ...conditions.map((c) => c.values ?? {}));
+
+  return {
+    ConditionExpression: expression || undefined,
+    ExpressionAttributeNames: Object.keys(names).length ? names : undefined,
+    ExpressionAttributeValues: Object.keys(values).length ? values : undefined,
+  };
+}

package/src/builders/shared/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './operators';
+export * from './conditions';