dyno-table 2.2.0 → 2.3.0

package/dist/chunk-EODPMYPE.js

@@ -0,0 +1,558 @@
+import { GetBuilder, PutBuilder, QueryBuilder, ScanBuilder, DeleteBuilder, UpdateBuilder, TransactionBuilder, BatchBuilder, ConditionCheckBuilder, buildExpression, generateAttributeName, debugCommand } from './chunk-DTFJJASK.js';
+import { eq, and, beginsWith, between, gte, gt, lte, lt } from './chunk-2WIBY7PZ.js';
+
+// src/utils/chunk-array.ts
+function* chunkArray(array, size) {
+  if (size <= 0) {
+    throw new Error("Chunk size must be greater than 0");
+  }
+  for (let i = 0; i < array.length; i += size) {
+    yield array.slice(i, i + size);
+  }
+}
+
+// src/table.ts
+var DDB_BATCH_WRITE_LIMIT = 25;
+var DDB_BATCH_GET_LIMIT = 100;
+var Table = class {
+  dynamoClient;
+  tableName;
+  /**
+   * The column name of the partitionKey for the Table
+   */
+  partitionKey;
+  /**
+   * The column name of the sortKey for the Table
+   */
+  sortKey;
+  /**
+   * The Global Secondary Indexes that are configured on this table
+   */
+  gsis;
+  constructor(config) {
+    this.dynamoClient = config.client;
+    this.tableName = config.tableName;
+    this.partitionKey = config.indexes.partitionKey;
+    this.sortKey = config.indexes.sortKey;
+    this.gsis = config.indexes.gsis || {};
+  }
+  createKeyForPrimaryIndex(keyCondition) {
+    const primaryCondition = { [this.partitionKey]: keyCondition.pk };
+    if (this.sortKey) {
+      if (!keyCondition.sk) {
+        throw new Error("Sort key has not been provided but the Table has a sort key");
+      }
+      primaryCondition[this.sortKey] = keyCondition.sk;
+    }
+    return primaryCondition;
+  }
+  /**
+   * Creates a new item in the table, it will fail if the item already exists.
+   *
+   * By default, this method returns the input values passed to the create operation
+   * upon successful creation.
+   *
+   * You can customise the return behaviour by chaining the `.returnValues()` method:
+   *
+   * @param item The item to create
+   * @returns A PutBuilder instance for chaining additional conditions and executing the create operation
+   *
+   * @example
+   * ```ts
+   * // Create with default behavior (returns input values)
+   * const result = await table.create({
+   *   id: 'user-123',
+   *   name: 'John Doe',
+   *   email: 'john@example.com'
+   * }).execute();
+   * console.log(result); // Returns the input object
+   *
+   * // Create with no return value for better performance
+   * await table.create(userData).returnValues('NONE').execute();
+   *
+   * // Create and get fresh data from dynamodb using a strongly consistent read
+   * const freshData = await table.create(userData).returnValues('CONSISTENT').execute();
+   *
+   * // Create and get previous values (if the item was overwritten)
+   * const oldData = await table.create(userData).returnValues('ALL_OLD').execute();
+   * ```
+   */
+  create(item) {
+    return this.put(item).condition((op) => op.attributeNotExists(this.partitionKey)).returnValues("INPUT");
+  }
+  get(keyCondition) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.get({
+          TableName: params.tableName,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
+          ProjectionExpression: params.projectionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ConsistentRead: params.consistentRead
+        });
+        return {
+          item: result.Item ? result.Item : void 0
+        };
+      } catch (error) {
+        console.error("Error getting item:", error);
+        throw error;
+      }
+    };
+    return new GetBuilder(executor, keyCondition, this.tableName);
+  }
+  /**
+   * Updates an item in the table
+   *
+   * @param item The item to update
+   * @returns A PutBuilder instance for chaining conditions and executing the put operation
+   */
+  put(item) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.put({
+          TableName: params.tableName,
+          Item: params.item,
+          ConditionExpression: params.conditionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ExpressionAttributeValues: params.expressionAttributeValues,
+          // CONSISTENT and INPUT are not valid ReturnValues for DDB, so we set NONE as we are not interested in its
+          // response and will be handling these cases separately
+          ReturnValues: params.returnValues === "CONSISTENT" || params.returnValues === "INPUT" ? "NONE" : params.returnValues
+        });
+        if (params.returnValues === "INPUT") {
+          return params.item;
+        }
+        if (params.returnValues === "CONSISTENT") {
+          const getResult = await this.dynamoClient.get({
+            TableName: params.tableName,
+            Key: this.createKeyForPrimaryIndex({
+              pk: params.item[this.partitionKey],
+              ...this.sortKey && { sk: params.item[this.sortKey] }
+            }),
+            ConsistentRead: true
+          });
+          return getResult.Item;
+        }
+        return result.Attributes;
+      } catch (error) {
+        console.error("Error creating item:", error);
+        throw error;
+      }
+    };
+    return new PutBuilder(executor, item, this.tableName);
+  }
+  /**
+   * Creates a query builder for complex queries
+   * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
+   */
+  query(keyCondition) {
+    const pkAttributeName = this.partitionKey;
+    const skAttributeName = this.sortKey;
+    let keyConditionExpression = eq(pkAttributeName, keyCondition.pk);
+    if (keyCondition.sk) {
+      if (!skAttributeName) {
+        throw new Error("Sort key is not defined for Index");
+      }
+      const keyConditionOperator = {
+        eq: (value) => eq(skAttributeName, value),
+        lt: (value) => lt(skAttributeName, value),
+        lte: (value) => lte(skAttributeName, value),
+        gt: (value) => gt(skAttributeName, value),
+        gte: (value) => gte(skAttributeName, value),
+        between: (lower, upper) => between(skAttributeName, lower, upper),
+        beginsWith: (value) => beginsWith(skAttributeName, value),
+        and: (...conditions) => and(...conditions)
+      };
+      const skCondition = keyCondition.sk(keyConditionOperator);
+      keyConditionExpression = and(eq(pkAttributeName, keyCondition.pk), skCondition);
+    }
+    const executor = async (originalKeyCondition, options) => {
+      let finalKeyCondition = originalKeyCondition;
+      if (options.indexName) {
+        const gsiName = String(options.indexName);
+        const gsi = this.gsis[gsiName];
+        if (!gsi) {
+          throw new Error(`GSI with name "${gsiName}" does not exist on table "${this.tableName}"`);
+        }
+        const gsiPkAttributeName = gsi.partitionKey;
+        const gsiSkAttributeName = gsi.sortKey;
+        let pkValue;
+        let skValue;
+        let extractedSkCondition;
+        if (originalKeyCondition.type === "eq") {
+          pkValue = originalKeyCondition.value;
+        } else if (originalKeyCondition.type === "and" && originalKeyCondition.conditions) {
+          const pkCondition = originalKeyCondition.conditions.find(
+            (c) => c.type === "eq" && c.attr === pkAttributeName
+          );
+          if (pkCondition && pkCondition.type === "eq") {
+            pkValue = pkCondition.value;
+          }
+          const skConditions = originalKeyCondition.conditions.filter((c) => c.attr === skAttributeName);
+          if (skConditions.length > 0) {
+            if (skConditions.length === 1) {
+              extractedSkCondition = skConditions[0];
+              if (extractedSkCondition && extractedSkCondition.type === "eq") {
+                skValue = extractedSkCondition.value;
+              }
+            } else if (skConditions.length > 1) {
+              extractedSkCondition = and(...skConditions);
+            }
+          }
+        }
+        if (!pkValue) {
+          throw new Error("Could not extract partition key value from key condition");
+        }
+        let gsiKeyCondition = eq(gsiPkAttributeName, pkValue);
+        if (skValue && gsiSkAttributeName) {
+          gsiKeyCondition = and(gsiKeyCondition, eq(gsiSkAttributeName, skValue));
+        } else if (extractedSkCondition && gsiSkAttributeName) {
+          if (extractedSkCondition.attr === skAttributeName) {
+            const updatedSkCondition = {
+              ...extractedSkCondition,
+              attr: gsiSkAttributeName
+            };
+            gsiKeyCondition = and(gsiKeyCondition, updatedSkCondition);
+          } else {
+            gsiKeyCondition = and(gsiKeyCondition, extractedSkCondition);
+          }
+        }
+        finalKeyCondition = gsiKeyCondition;
+      }
+      const expressionParams = {
+        expressionAttributeNames: {},
+        expressionAttributeValues: {},
+        valueCounter: { count: 0 }
+      };
+      const keyConditionExpression2 = buildExpression(finalKeyCondition, expressionParams);
+      let filterExpression;
+      if (options.filter) {
+        filterExpression = buildExpression(options.filter, expressionParams);
+      }
+      const projectionExpression = options.projection?.map((p) => generateAttributeName(expressionParams, p)).join(", ");
+      const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
+      const { indexName, limit, consistentRead, scanIndexForward, lastEvaluatedKey } = options;
+      const params = {
+        TableName: this.tableName,
+        KeyConditionExpression: keyConditionExpression2,
+        FilterExpression: filterExpression,
+        ExpressionAttributeNames: expressionAttributeNames,
+        ExpressionAttributeValues: expressionAttributeValues,
+        IndexName: indexName,
+        Limit: limit,
+        ConsistentRead: consistentRead,
+        ScanIndexForward: scanIndexForward,
+        ProjectionExpression: projectionExpression,
+        ExclusiveStartKey: lastEvaluatedKey
+      };
+      try {
+        const result = await this.dynamoClient.query(params);
+        return {
+          items: result.Items,
+          lastEvaluatedKey: result.LastEvaluatedKey
+        };
+      } catch (error) {
+        console.log(debugCommand(params));
+        console.error("Error querying items:", error);
+        throw error;
+      }
+    };
+    return new QueryBuilder(executor, keyConditionExpression);
+  }
+  /**
+   * Creates a scan builder for scanning the entire table
+   * Use this when you need to:
+   * - Process all items in a table
+   * - Apply filters to a large dataset
+   * - Use a GSI for scanning
+   *
+   * @returns A ScanBuilder instance for chaining operations
+   */
+  scan() {
+    const executor = async (options) => {
+      const expressionParams = {
+        expressionAttributeNames: {},
+        expressionAttributeValues: {},
+        valueCounter: { count: 0 }
+      };
+      let filterExpression;
+      if (options.filter) {
+        filterExpression = buildExpression(options.filter, expressionParams);
+      }
+      const projectionExpression = options.projection?.map((p) => generateAttributeName(expressionParams, p)).join(", ");
+      const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
+      const { indexName, limit, consistentRead, lastEvaluatedKey } = options;
+      const params = {
+        TableName: this.tableName,
+        FilterExpression: filterExpression,
+        ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0,
+        ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : void 0,
+        IndexName: indexName,
+        Limit: limit,
+        ConsistentRead: consistentRead,
+        ProjectionExpression: projectionExpression,
+        ExclusiveStartKey: lastEvaluatedKey
+      };
+      try {
+        const result = await this.dynamoClient.scan(params);
+        return {
+          items: result.Items,
+          lastEvaluatedKey: result.LastEvaluatedKey
+        };
+      } catch (error) {
+        console.log(debugCommand(params));
+        console.error("Error scanning items:", error);
+        throw error;
+      }
+    };
+    return new ScanBuilder(executor);
+  }
+  delete(keyCondition) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.delete({
+          TableName: params.tableName,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
+          ConditionExpression: params.conditionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ExpressionAttributeValues: params.expressionAttributeValues,
+          ReturnValues: params.returnValues
+        });
+        return {
+          item: result.Attributes
+        };
+      } catch (error) {
+        console.error("Error deleting item:", error);
+        throw error;
+      }
+    };
+    return new DeleteBuilder(executor, this.tableName, keyCondition);
+  }
+  /**
+   * Updates an item in the table
+   *
+   * @param keyCondition The primary key of the item to update
+   * @returns An UpdateBuilder instance for chaining update operations and conditions
+   */
+  update(keyCondition) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.update({
+          TableName: params.tableName,
+          Key: this.createKeyForPrimaryIndex(keyCondition),
+          UpdateExpression: params.updateExpression,
+          ConditionExpression: params.conditionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ExpressionAttributeValues: params.expressionAttributeValues,
+          ReturnValues: params.returnValues
+        });
+        return {
+          item: result.Attributes
+        };
+      } catch (error) {
+        console.error("Error updating item:", error);
+        throw error;
+      }
+    };
+    return new UpdateBuilder(executor, this.tableName, keyCondition);
+  }
+  /**
+   * Creates a transaction builder for performing multiple operations atomically
+   */
+  transactionBuilder() {
+    const executor = async (params) => {
+      await this.dynamoClient.transactWrite(params);
+    };
+    return new TransactionBuilder(executor, {
+      partitionKey: this.partitionKey,
+      sortKey: this.sortKey
+    });
+  }
+  /**
+   * Creates a batch builder for performing multiple operations efficiently with optional type inference
+   *
+   * @example Basic Usage
+   * ```typescript
+   * const batch = table.batchBuilder();
+   *
+   * // Add operations
+   * userRepo.create(newUser).withBatch(batch);
+   * orderRepo.get({ id: 'order-1' }).withBatch(batch);
+   *
+   * // Execute operations
+   * const result = await batch.execute();
+   * ```
+   *
+   * @example Typed Usage
+   * ```typescript
+   * // Define entity types for the batch
+   * const batch = table.batchBuilder<{
+   *   User: UserEntity;
+   *   Order: OrderEntity;
+   *   Product: ProductEntity;
+   * }>();
+   *
+   * // Add operations with type information
+   * userRepo.create(newUser).withBatch(batch, 'User');
+   * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+   * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
+   *
+   * // Execute and get typed results
+   * const result = await batch.execute();
+   * const users: UserEntity[] = result.reads.itemsByType.User;
+   * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+   * ```
+   */
+  batchBuilder() {
+    const batchWriteExecutor = async (operations) => {
+      return this.batchWrite(operations);
+    };
+    const batchGetExecutor = async (keys) => {
+      return this.batchGet(keys);
+    };
+    return new BatchBuilder(batchWriteExecutor, batchGetExecutor, {
+      partitionKey: this.partitionKey,
+      sortKey: this.sortKey
+    });
+  }
+  /**
+   * Executes a transaction using a callback function
+   *
+   * @param callback A function that receives a transaction context and performs operations on it
+   * @param options Optional transaction options
+   * @returns A promise that resolves when the transaction is complete
+   */
+  async transaction(callback, options) {
+    const transactionExecutor = async (params) => {
+      await this.dynamoClient.transactWrite(params);
+    };
+    const transaction = new TransactionBuilder(transactionExecutor, {
+      partitionKey: this.partitionKey,
+      sortKey: this.sortKey
+    });
+    if (options) {
+      transaction.withOptions(options);
+    }
+    const result = await callback(transaction);
+    await transaction.execute();
+    return result;
+  }
+  /**
+   * Creates a condition check operation for use in transactions
+   *
+   * This is useful for when you require a transaction to succeed only when a specific condition is met on a
+   * a record within the database that you are not directly updating.
+   *
+   * For example, you are updating a record and you want to ensure that another record exists and/or has a specific value before proceeding.
+   */
+  conditionCheck(keyCondition) {
+    return new ConditionCheckBuilder(this.tableName, keyCondition);
+  }
+  /**
+   * Performs a batch get operation to retrieve multiple items at once
+   *
+   * @param keys Array of primary keys to retrieve
+   * @returns A promise that resolves to the retrieved items
+   */
+  async batchGet(keys) {
+    const allItems = [];
+    const allUnprocessedKeys = [];
+    for (const chunk of chunkArray(keys, DDB_BATCH_GET_LIMIT)) {
+      const formattedKeys = chunk.map((key) => ({
+        [this.partitionKey]: key.pk,
+        ...this.sortKey ? { [this.sortKey]: key.sk } : {}
+      }));
+      const params = {
+        RequestItems: {
+          [this.tableName]: {
+            Keys: formattedKeys
+          }
+        }
+      };
+      try {
+        const result = await this.dynamoClient.batchGet(params);
+        if (result.Responses?.[this.tableName]) {
+          allItems.push(...result.Responses[this.tableName]);
+        }
+        const unprocessedKeysArray = result.UnprocessedKeys?.[this.tableName]?.Keys || [];
+        const unprocessedKeys = unprocessedKeysArray.map((key) => ({
+          pk: key[this.partitionKey],
+          sk: this.sortKey ? key[this.sortKey] : void 0
+        }));
+        if (unprocessedKeys.length > 0) {
+          allUnprocessedKeys.push(...unprocessedKeys);
+        }
+      } catch (error) {
+        console.error("Error in batch get operation:", error);
+        throw error;
+      }
+    }
+    return {
+      items: allItems,
+      unprocessedKeys: allUnprocessedKeys
+    };
+  }
+  /**
+   * Performs a batch write operation to put or delete multiple items at once
+   *
+   * @param operations Array of put or delete operations
+   * @returns A promise that resolves to any unprocessed operations
+   */
+  async batchWrite(operations) {
+    const allUnprocessedItems = [];
+    for (const chunk of chunkArray(operations, DDB_BATCH_WRITE_LIMIT)) {
+      const writeRequests = chunk.map((operation) => {
+        if (operation.type === "put") {
+          return {
+            PutRequest: {
+              Item: operation.item
+            }
+          };
+        }
+        return {
+          DeleteRequest: {
+            Key: this.createKeyForPrimaryIndex(operation.key)
+          }
+        };
+      });
+      const params = {
+        RequestItems: {
+          [this.tableName]: writeRequests
+        }
+      };
+      try {
+        const result = await this.dynamoClient.batchWrite(params);
+        const unprocessedRequestsArray = result.UnprocessedItems?.[this.tableName] || [];
+        if (unprocessedRequestsArray.length > 0) {
+          const unprocessedItems = unprocessedRequestsArray.map((request) => {
+            if (request?.PutRequest?.Item) {
+              return {
+                type: "put",
+                item: request.PutRequest.Item
+              };
+            }
+            if (request?.DeleteRequest?.Key) {
+              return {
+                type: "delete",
+                key: {
+                  pk: request.DeleteRequest.Key[this.partitionKey],
+                  sk: this.sortKey ? request.DeleteRequest.Key[this.sortKey] : void 0
+                }
+              };
+            }
+            throw new Error("Invalid unprocessed item format returned from DynamoDB");
+          });
+          allUnprocessedItems.push(...unprocessedItems);
+        }
+      } catch (error) {
+        console.error("Error in batch write operation:", error);
+        throw error;
+      }
+    }
+    return {
+      unprocessedItems: allUnprocessedItems
+    };
+  }
+};
+
+export { Table };