@ftschopp/dynatable-core 1.4.2 → 1.4.3

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

@@ -1,455 +0,0 @@
-/* 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 { buildProjectionExpression } from '../shared/projection';
-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;
-  entityType?: string;
-};
-
-/**
- * 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,
-  indexName?: string
-): { keyName: string; template: string } | null {
-  if (!model?.key) return null;
-
-  // When an index is specified, check model.index first for key templates
-  if (indexName && model.index) {
-    for (const [keyName, keyDef] of Object.entries(model.index)) {
-      if (!keyName.startsWith(indexName)) {
-        continue;
-      }
-      const templateVars = extractTemplateVars(keyDef.value);
-      if (templateVars.includes(fieldName)) {
-        return { keyName, template: keyDef.value };
-      }
-    }
-  }
-
-  for (const [keyName, keyDef] of Object.entries(model.key)) {
-    const templateVars = extractTemplateVars(keyDef.value);
-    if (templateVars.includes(fieldName)) {
-      return { keyName, template: keyDef.value };
-    }
-  }
-  return null;
-}
-
-/**
- * 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,
-  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.`
-  );
-}
-
-/**
- * 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,
-  indexName?: string
-): { 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, indexName);
-
-      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,
-              cond.keyOperator
-            );
-            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>(state: QueryState<Model>): QueryExecutor<Model> {
-  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,
-        state.indexName
-      );
-
-      // DynamoDB Query requires at least a partition-key condition. If
-      // separation didn't pick anything as a key condition, the caller is
-      // either filtering on non-key attributes (which means they want
-      // scan()) or referencing the wrong attribute name. Fail loudly here
-      // instead of letting the SDK reject the request at execute time.
-      if (keyConditions.length === 0) {
-        const keyTemplates = state.indexName
-          ? Object.entries(state.model?.index ?? {})
-              .filter(([keyName]) => keyName.startsWith(state.indexName!))
-              .map(([, def]) => def.value)
-          : Object.values(state.model?.key ?? {}).map((def) => def.value);
-        const templateVars = Array.from(
-          new Set(keyTemplates.flatMap((tpl) => extractTemplateVars(tpl)))
-        );
-        const indexHint = state.indexName ? ` on index "${state.indexName}"` : '';
-        const fieldsHint =
-          templateVars.length > 0
-            ? ` Expected a condition on one of: ${templateVars.join(', ')}.`
-            : '';
-        throw new Error(
-          `Query requires a condition on the partition key${indexHint}.${fieldsHint} ` +
-            `For non-key filtering use scan() instead.`
-        );
-      }
-
-      // 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 (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: allFilters,
-          });
-        }
-      }
-
-      // Merge attribute names and values from both expressions
-      const allNames: Record<string, string> = {
-        ...(keyExpr.names ?? {}),
-        ...(filterExpr.names ?? {}),
-      };
-      const allValues = {
-        ...(keyExpr.values ?? {}),
-        ...(filterExpr.values ?? {}),
-      };
-
-      // Build ProjectionExpression with placeholders so reserved words
-      // (name, date, status, type, …) don't blow up at DynamoDB.
-      // Idempotent merge: filter/key and projection placeholders both map
-      // `#name → name`, so collisions resolve to the same value.
-      let projectionExpression: string | undefined;
-      if (state.projection && state.projection.length > 0) {
-        const proj = buildProjectionExpression(
-          (state.projection as (keyof Model)[]).map((a) => String(a))
-        );
-        projectionExpression = proj.ProjectionExpression;
-        Object.assign(allNames, proj.ExpressionAttributeNames);
-      }
-
-      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,
-        }),
-        ...(projectionExpression && {
-          ProjectionExpression: projectionExpression,
-        }),
-        ...(state.consistentReadEnabled && { ConsistentRead: true }),
-        ...(state.exclusiveStartKey && {
-          ExclusiveStartKey: state.exclusiveStartKey,
-        }),
-      };
-    },
-
-    /**
-     * ⚠️ Returns only the FIRST page of results. DynamoDB caps each Query
-     * response at ~1MB (or `Limit` if set). If the matching set is larger,
-     * the remaining items are silently dropped.
-     *
-     * Use {@link executeWithPagination} when you need to drive pagination
-     * yourself, or {@link iterate} to walk every matching item lazily.
-     */
-    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,
-      };
-    },
-
-    async *iterate(): AsyncIterableIterator<Model> {
-      const baseParams = this.dbParams();
-      let cursor: Record<string, any> | undefined = baseParams.ExclusiveStartKey;
-      do {
-        const params = { ...baseParams, ExclusiveStartKey: cursor };
-        const result = await state.client.send(new QueryCommand(params));
-        state.logger?.log('QueryCommand', params, result);
-        for (const item of (result.Items ?? []) as unknown as Model[]) {
-          yield item;
-        }
-        cursor = result.LastEvaluatedKey;
-      } while (cursor);
-    },
-  };
-}
-
-/**
- * Creates a QueryBuilder for a table
- */
-export function createQueryBuilder<Model>(
-  tableName: string,
-  client: DynamoDBClient,
-  model?: ModelDefinition,
-  logger?: DynamoDBLogger,
-  entityType?: string
-): QueryBuilder<Model> {
-  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,
-        entityType,
-      };
-
-      return createQueryExecutor(initialState);
-    },
-  };
-}

package/src/builders/query/index.ts

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

package/src/builders/query/types.ts

@@ -1,109 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
-
-/**
- * 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> extends ExecutableBuilder<Model[]> {
-  /**
-   * Limit the number of items to return
-   */
-  limit(count: number): QueryExecutor<Model>;
-
-  /**
-   * Scan index forward (ascending) or backward (descending)
-   */
-  scanIndexForward(forward: boolean): QueryExecutor<Model>;
-
-  /**
-   * Use a secondary index
-   */
-  useIndex(indexName: string): QueryExecutor<Model>;
-
-  /**
-   * Select specific attributes to return
-   */
-  select(attrs: (keyof Model)[]): QueryExecutor<Model>;
-
-  /**
-   * Use consistent read
-   */
-  consistentRead(): QueryExecutor<Model>;
-
-  /**
-   * Start query from a specific key (for pagination)
-   */
-  startFrom(key: Record<string, any>): QueryExecutor<Model>;
-
-  /**
-   * 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>>;
-
-  /**
-   * 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>;
-}
-
-/**
- * Main Query Builder interface with type-safe where clause
- */
-export interface QueryBuilder<Model> {
-  /**
-   * 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>;
-}