@ftschopp/dynatable-core 1.4.2 → 1.4.3

package/src/builders/scan/types.ts

@@ -1,88 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
-
-/**
- * A single page of scan results plus metadata for manual pagination.
- */
-export interface ScanResult<Model> {
-  /** Items returned in this page. */
-  items: Model[];
-  /** Cursor for the next page; `undefined` when there are no more results. */
-  lastEvaluatedKey?: Record<string, any>;
-  /** Number of items returned after applying the filter. */
-  count?: number;
-  /** Number of items examined before applying the filter. */
-  scannedCount?: number;
-}
-
-/**
- * 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>;
-
-  /**
-   * Executes a single Scan request and returns the page along with the
-   * `lastEvaluatedKey` cursor and counts. Use this when you want to drive
-   * pagination yourself (e.g. expose a cursor to a client).
-   */
-  executeWithPagination(): Promise<ScanResult<Model>>;
-
-  /**
-   * Returns an async iterator that paginates internally and yields one item at
-   * a time. Memory stays at one page; you can `break` out of the loop early.
-   *
-   * `Limit` set via `.limit()` is forwarded to DynamoDB as a *per-request*
-   * cap, not a total cap. To cap the total, count yourself inside the loop:
-   *
-   * ```ts
-   * let n = 0;
-   * for await (const item of builder.iterate()) {
-   *   if (n++ >= 1000) break;
-   *   process(item);
-   * }
-   * ```
-   */
-  iterate(): AsyncIterableIterator<Model>;
-}

package/src/builders/shared/conditions.ts

@@ -1,58 +0,0 @@
-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

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

package/src/builders/shared/operators.test.ts

@@ -1,270 +0,0 @@
-import { createOpBuilder } from './operators';
-
-describe('OpBuilder Counter Isolation', () => {
-  it('should have isolated counters for each opBuilder instance', () => {
-    const op1 = createOpBuilder();
-    const op2 = createOpBuilder();
-
-    const attr = { name: 'username' };
-
-    // Create conditions with both builders
-    const cond1a = op1.eq(attr, 'alice');
-    const cond1b = op1.eq(attr, 'bob');
-
-    const cond2a = op2.eq(attr, 'charlie');
-    const cond2b = op2.eq(attr, 'dave');
-
-    // Each builder should have its own counter starting at 0
-    expect(cond1a.values).toEqual({ ':username_0': 'alice' });
-    expect(cond1b.values).toEqual({ ':username_1': 'bob' });
-
-    // Second builder should also start at 0
-    expect(cond2a.values).toEqual({ ':username_0': 'charlie' });
-    expect(cond2b.values).toEqual({ ':username_1': 'dave' });
-  });
-
-  it('should not share state between different builder instances', () => {
-    const op1 = createOpBuilder();
-    const op2 = createOpBuilder();
-
-    const attr = { name: 'age' };
-
-    // Use first builder
-    op1.gt(attr, 18);
-    op1.lt(attr, 65);
-
-    // Second builder should start from 0, not continue from first
-    const cond = op2.eq(attr, 25);
-    expect(cond.values).toEqual({ ':age_0': 25 });
-  });
-
-  it('should generate unique names for multiple values in same condition', () => {
-    const op = createOpBuilder();
-    const attr = { name: 'score' };
-
-    const between = op.between(attr, 10, 20);
-
-    expect(between.values).toEqual({
-      ':score_low_0': 10,
-      ':score_high_1': 20,
-    });
-  });
-});
-
-describe('New Operators', () => {
-  describe('contains operator', () => {
-    it('should build contains expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'tags' };
-
-      const condition = op.contains(attr, 'featured');
-
-      expect(condition.expression).toBe('contains(#tags, :tags_0)');
-      expect(condition.names).toEqual({ '#tags': 'tags' });
-      expect(condition.values).toEqual({ ':tags_0': 'featured' });
-    });
-  });
-
-  describe('exists operator', () => {
-    it('should build attribute_exists expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'email' };
-
-      const condition = op.exists(attr);
-
-      expect(condition.expression).toBe('attribute_exists(#email)');
-      expect(condition.names).toEqual({ '#email': 'email' });
-      expect(condition.values).toBeUndefined();
-    });
-  });
-
-  describe('notExists operator', () => {
-    it('should build attribute_not_exists expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'deletedAt' };
-
-      const condition = op.notExists(attr);
-
-      expect(condition.expression).toBe('attribute_not_exists(#deletedAt)');
-      expect(condition.names).toEqual({ '#deletedAt': 'deletedAt' });
-      expect(condition.values).toBeUndefined();
-    });
-  });
-
-  describe('attributeType operator', () => {
-    it('should build attribute_type expression for String', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'name' };
-
-      const condition = op.attributeType(attr, 'S');
-
-      expect(condition.expression).toBe('attribute_type(#name, :name_type_0)');
-      expect(condition.names).toEqual({ '#name': 'name' });
-      expect(condition.values).toEqual({ ':name_type_0': 'S' });
-    });
-
-    it('should build attribute_type expression for Number', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'age' };
-
-      const condition = op.attributeType(attr, 'N');
-
-      expect(condition.expression).toBe('attribute_type(#age, :age_type_0)');
-      expect(condition.names).toEqual({ '#age': 'age' });
-      expect(condition.values).toEqual({ ':age_type_0': 'N' });
-    });
-
-    it('should build attribute_type expression for List', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'items' };
-
-      const condition = op.attributeType(attr, 'L');
-
-      expect(condition.expression).toBe('attribute_type(#items, :items_type_0)');
-      expect(condition.names).toEqual({ '#items': 'items' });
-      expect(condition.values).toEqual({ ':items_type_0': 'L' });
-    });
-  });
-
-  describe('in operator', () => {
-    it('should build IN expression with multiple values', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'status' };
-
-      const condition = op.in(attr, ['active', 'pending', 'approved']);
-
-      expect(condition.expression).toBe('#status IN (:status_in0_0, :status_in1_1, :status_in2_2)');
-      expect(condition.names).toEqual({ '#status': 'status' });
-      expect(condition.values).toEqual({
-        ':status_in0_0': 'active',
-        ':status_in1_1': 'pending',
-        ':status_in2_2': 'approved',
-      });
-    });
-
-    it('should build IN expression with single value', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'category' };
-
-      const condition = op.in(attr, ['books']);
-
-      expect(condition.expression).toBe('#category IN (:category_in0_0)');
-      expect(condition.names).toEqual({ '#category': 'category' });
-      expect(condition.values).toEqual({
-        ':category_in0_0': 'books',
-      });
-    });
-  });
-
-  describe('size operator', () => {
-    it('should build size() = expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'tags' };
-
-      const condition = op.size(attr).eq(5);
-
-      expect(condition.expression).toBe('size(#tags) = :tags_size_0');
-      expect(condition.names).toEqual({ '#tags': 'tags' });
-      expect(condition.values).toEqual({ ':tags_size_0': 5 });
-    });
-
-    it('should build size() <> expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'items' };
-
-      const condition = op.size(attr).ne(0);
-
-      expect(condition.expression).toBe('size(#items) <> :items_size_0');
-      expect(condition.names).toEqual({ '#items': 'items' });
-      expect(condition.values).toEqual({ ':items_size_0': 0 });
-    });
-
-    it('should build size() < expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'name' };
-
-      const condition = op.size(attr).lt(100);
-
-      expect(condition.expression).toBe('size(#name) < :name_size_0');
-      expect(condition.names).toEqual({ '#name': 'name' });
-      expect(condition.values).toEqual({ ':name_size_0': 100 });
-    });
-
-    it('should build size() <= expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'description' };
-
-      const condition = op.size(attr).lte(500);
-
-      expect(condition.expression).toBe('size(#description) <= :description_size_0');
-      expect(condition.names).toEqual({ '#description': 'description' });
-      expect(condition.values).toEqual({ ':description_size_0': 500 });
-    });
-
-    it('should build size() > expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'password' };
-
-      const condition = op.size(attr).gt(8);
-
-      expect(condition.expression).toBe('size(#password) > :password_size_0');
-      expect(condition.names).toEqual({ '#password': 'password' });
-      expect(condition.values).toEqual({ ':password_size_0': 8 });
-    });
-
-    it('should build size() >= expression', () => {
-      const op = createOpBuilder();
-      const attr = { name: 'content' };
-
-      const condition = op.size(attr).gte(10);
-
-      expect(condition.expression).toBe('size(#content) >= :content_size_0');
-      expect(condition.names).toEqual({ '#content': 'content' });
-      expect(condition.values).toEqual({ ':content_size_0': 10 });
-    });
-  });
-
-  describe('Combined operators', () => {
-    it('should combine exists and other conditions with AND', () => {
-      const op = createOpBuilder();
-      const attr1 = { name: 'email' };
-      const attr2 = { name: 'verified' };
-
-      const condition = op.and(op.exists(attr1), op.eq(attr2, true));
-
-      expect(condition.operator).toBe('AND');
-      expect(condition.children).toBeDefined();
-      expect(condition.children).toHaveLength(2);
-      expect(condition.children![0]!.expression).toBe('attribute_exists(#email)');
-      expect(condition.children![1]!.expression).toBe('#verified = :verified_0');
-    });
-
-    it('should combine size with comparison', () => {
-      const op = createOpBuilder();
-      const attr1 = { name: 'tags' };
-      const attr2 = { name: 'status' };
-
-      const condition = op.and(op.size(attr1).gt(0), op.eq(attr2, 'active'));
-
-      expect(condition.operator).toBe('AND');
-      expect(condition.children).toBeDefined();
-      expect(condition.children).toHaveLength(2);
-      expect(condition.children![0]!.expression).toBe('size(#tags) > :tags_size_0');
-      expect(condition.children![1]!.expression).toBe('#status = :status_1');
-    });
-
-    it('should use IN with OR', () => {
-      const op = createOpBuilder();
-      const attr1 = { name: 'status' };
-      const attr2 = { name: 'priority' };
-
-      const condition = op.or(op.in(attr1, ['active', 'pending']), op.eq(attr2, 'high'));
-
-      expect(condition.operator).toBe('OR');
-      expect(condition.children).toBeDefined();
-      expect(condition.children).toHaveLength(2);
-      expect(condition.children![0]!.expression).toContain('IN');
-      expect(condition.children![1]!.expression).toBe('#priority = :priority_2');
-    });
-  });
-});

package/src/builders/shared/operators.ts

@@ -1,208 +0,0 @@
-import { OpBuilder } from './types';
-
-/**
- * Creates a scoped OpBuilder with its own counter for unique value placeholders.
- * Each builder instance maintains isolated state to prevent naming conflicts.
- */
-export function createOpBuilder(): OpBuilder {
-  let valueCounter = 0;
-
-  /**
-   * Generates a unique value placeholder name within this builder's scope
-   */
-  function getUniqueValueName(baseName: string): string {
-    return `${baseName}_${valueCounter++}`;
-  }
-
-  return {
-    eq: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} = :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'eq',
-      };
-    },
-    ne: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} <> :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'ne',
-      };
-    },
-    lt: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} < :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'lt',
-      };
-    },
-    lte: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} <= :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'lte',
-      };
-    },
-    gt: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} > :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'gt',
-      };
-    },
-    gte: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `#${attr.name} >= :${valueName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'gte',
-      };
-    },
-    between: (attr, low, high) => {
-      const lowName = getUniqueValueName(`${attr.name}_low`);
-      const highName = getUniqueValueName(`${attr.name}_high`);
-      return {
-        expression: `#${attr.name} BETWEEN :${lowName} AND :${highName}`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: {
-          [`:${lowName}`]: low,
-          [`:${highName}`]: high,
-        },
-        keyOperator: 'between',
-      };
-    },
-    beginsWith: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `begins_with(#${attr.name}, :${valueName})`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-        keyOperator: 'beginsWith',
-      };
-    },
-    contains: (attr, value) => {
-      const valueName = getUniqueValueName(attr.name);
-      return {
-        expression: `contains(#${attr.name}, :${valueName})`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: value },
-      };
-    },
-    exists: (attr) => ({
-      expression: `attribute_exists(#${attr.name})`,
-      names: { [`#${attr.name}`]: attr.name },
-    }),
-    notExists: (attr) => ({
-      expression: `attribute_not_exists(#${attr.name})`,
-      names: { [`#${attr.name}`]: attr.name },
-    }),
-    attributeType: (attr, type) => {
-      const valueName = getUniqueValueName(`${attr.name}_type`);
-      return {
-        expression: `attribute_type(#${attr.name}, :${valueName})`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: { [`:${valueName}`]: type },
-      };
-    },
-    in: (attr, values) => {
-      const valueNames = values.map((_, i) => getUniqueValueName(`${attr.name}_in${i}`));
-      const placeholders = valueNames.map((name) => `:${name}`).join(', ');
-      const valuesObj: Record<string, any> = {};
-      valueNames.forEach((name, i) => {
-        valuesObj[`:${name}`] = values[i];
-      });
-
-      return {
-        expression: `#${attr.name} IN (${placeholders})`,
-        names: { [`#${attr.name}`]: attr.name },
-        values: valuesObj,
-      };
-    },
-    size: (attr) => {
-      const sizeExpr = `size(#${attr.name})`;
-      const names = { [`#${attr.name}`]: attr.name };
-
-      return {
-        eq: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} = :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-        ne: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} <> :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-        lt: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} < :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-        lte: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} <= :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-        gt: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} > :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-        gte: (value: number) => {
-          const valueName = getUniqueValueName(`${attr.name}_size`);
-          return {
-            expression: `${sizeExpr} >= :${valueName}`,
-            names,
-            values: { [`:${valueName}`]: value },
-          };
-        },
-      };
-    },
-    and: (...conditions) => ({
-      expression: '',
-      operator: 'AND',
-      children: conditions,
-    }),
-    or: (...conditions) => ({
-      expression: '',
-      operator: 'OR',
-      children: conditions,
-    }),
-    not: (condition) => ({
-      ...condition,
-      isNegated: true,
-    }),
-  };
-}
-
-/**
- * @deprecated Use createOpBuilder() instead to avoid global state.
- * This export is maintained for backward compatibility.
- */
-export const opBuilder: OpBuilder = createOpBuilder();

package/src/builders/shared/projection.ts

@@ -1,28 +0,0 @@
-/**
- * Builds a `ProjectionExpression` together with the matching
- * `ExpressionAttributeNames` map so that any attribute — including
- * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
- * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
- * via a `#placeholder`.
- *
- * Without this indirection DynamoDB rejects the request with
- * `ValidationException: Attribute name is a reserved keyword`.
- */
-export function buildProjectionExpression(attrs: string[]): {
-  ProjectionExpression: string;
-  ExpressionAttributeNames: Record<string, string>;
-} {
-  const names: Record<string, string> = {};
-  const projectionParts: string[] = [];
-
-  attrs.forEach((attr) => {
-    const placeholder = `#${attr}`;
-    names[placeholder] = attr;
-    projectionParts.push(placeholder);
-  });
-
-  return {
-    ProjectionExpression: projectionParts.join(', '),
-    ExpressionAttributeNames: names,
-  };
-}