dyno-table 2.3.3 → 2.5.0

package/dist/{chunk-DTFJJASK.js → chunk-NYJGW3XH.js}

@@ -1,16 +1,7 @@
+import { BatchErrors, BatchError, ErrorCodes, ExpressionErrors, ConfigurationErrors, TransactionErrors, ValidationErrors } from './chunk-FF7FYGDH.js';
 import { not, or, and, attributeNotExists, attributeExists, contains, beginsWith, inArray, between, gte, gt, lte, lt, ne, eq } from './chunk-2WIBY7PZ.js';
 
 // src/builders/batch-builder.ts
-var BatchError = class extends Error {
-  operation;
-  cause;
-  constructor(message, operation, cause) {
-    super(message);
-    this.name = "BatchError";
-    this.operation = operation;
-    this.cause = cause;
-  }
-};
 var BatchBuilder = class {
   constructor(batchWriteExecutor, batchGetExecutor, config) {
     this.batchWriteExecutor = batchWriteExecutor;
@@ -45,10 +36,7 @@ var BatchBuilder = class {
    */
   validateNotEmpty() {
     if (this.isEmpty()) {
-      throw new BatchError(
-        "Cannot execute empty batch. Add operations using entity builders with .withBatch()",
-        "write"
-      );
+      throw BatchErrors.batchEmpty("write");
     }
   }
   /**
@@ -139,13 +127,14 @@ var BatchBuilder = class {
             key
           };
         }
-        throw new BatchError(`Unsupported batch item type for write operation: ${item.type}`, "write");
+        throw BatchErrors.unsupportedType("write", item);
       });
       return await this.batchWriteExecutor(operations);
     } catch (error) {
-      throw new BatchError(
-        `Failed to execute batch write operations: ${error instanceof Error ? error.message : "Unknown error"}`,
-        "write",
+      if (error instanceof BatchError) throw error;
+      throw BatchErrors.batchWriteFailed(
+        [],
+        { operationCount: this.writeItems.length },
         error instanceof Error ? error : void 0
       );
     }
@@ -172,13 +161,14 @@ var BatchBuilder = class {
             sk: this.config.sortKey ? tableKey[this.config.sortKey] : void 0
           };
         }
-        throw new BatchError(`Unsupported batch item type for get operation: ${item.type}`, "read");
+        throw BatchErrors.unsupportedType("read", item);
       });
       return await this.batchGetExecutor(keys);
     } catch (error) {
-      throw new BatchError(
-        `Failed to execute batch get operations: ${error instanceof Error ? error.message : "Unknown error"}`,
-        "read",
+      if (error instanceof BatchError) throw error;
+      throw BatchErrors.batchGetFailed(
+        [],
+        { operationCount: this.getItems.length },
         error instanceof Error ? error : void 0
       );
     }
@@ -230,7 +220,10 @@ var BatchBuilder = class {
           errors.push(
             new BatchError(
               "Unexpected error during write operations",
+              ErrorCodes.BATCH_WRITE_FAILED,
               "write",
+              [],
+              {},
               error instanceof Error ? error : void 0
             )
           );
@@ -247,7 +240,10 @@ var BatchBuilder = class {
           errors.push(
             new BatchError(
               "Unexpected error during read operations",
+              ErrorCodes.BATCH_GET_FAILED,
               "read",
+              [],
+              {},
               error instanceof Error ? error : void 0
             )
           );
@@ -314,16 +310,16 @@ var generateValueName = (params, value) => {
 };
 var validateCondition = (condition, requiresAttr = true, requiresValue = true) => {
   if (requiresAttr && !condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   if (requiresValue && condition.value === void 0) {
-    throw new Error(`Value is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingValue(condition.type, condition);
   }
 };
 var buildComparisonExpression = (condition, operator, params) => {
   validateCondition(condition);
   if (!condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   const attrName = generateAttributeName(params, condition.attr);
   const valueName = generateValueName(params, condition.value);
@@ -332,10 +328,14 @@ var buildComparisonExpression = (condition, operator, params) => {
 var buildBetweenExpression = (condition, params) => {
   validateCondition(condition);
   if (!condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   if (!Array.isArray(condition.value) || condition.value.length !== 2) {
-    throw new Error("Between condition requires an array of two values");
+    throw ExpressionErrors.invalidCondition(
+      condition.type,
+      condition,
+      "Provide an array with exactly two values: [lowerBound, upperBound]"
+    );
   }
   const attrName = generateAttributeName(params, condition.attr);
   const lowerName = generateValueName(params, condition.value[0]);
@@ -345,13 +345,17 @@ var buildBetweenExpression = (condition, params) => {
 var buildInExpression = (condition, params) => {
   validateCondition(condition);
   if (!condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   if (!Array.isArray(condition.value) || condition.value.length === 0) {
-    throw new Error("In condition requires a non-empty array of values");
+    throw ExpressionErrors.emptyArray(condition.type, condition.value);
   }
   if (condition.value.length > 100) {
-    throw new Error("In condition supports a maximum of 100 values");
+    throw ExpressionErrors.invalidCondition(
+      condition.type,
+      condition,
+      "Split your query into multiple operations or use a different condition type"
+    );
   }
   const attrName = generateAttributeName(params, condition.attr);
   const valueNames = condition.value.map((value) => generateValueName(params, value));
@@ -360,7 +364,7 @@ var buildInExpression = (condition, params) => {
 var buildFunctionExpression = (functionName, condition, params) => {
   validateCondition(condition);
   if (!condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   const attrName = generateAttributeName(params, condition.attr);
   const valueName = generateValueName(params, condition.value);
@@ -369,66 +373,65 @@ var buildFunctionExpression = (functionName, condition, params) => {
 var buildAttributeFunction = (functionName, condition, params) => {
   validateCondition(condition, true, false);
   if (!condition.attr) {
-    throw new Error(`Attribute is required for ${condition.type} condition`);
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
   }
   const attrName = generateAttributeName(params, condition.attr);
   return `${functionName}(${attrName})`;
 };
 var buildLogicalExpression = (operator, conditions, params) => {
   if (!conditions || conditions.length === 0) {
-    throw new Error(`At least one condition is required for ${operator} expression`);
+    throw ExpressionErrors.emptyArray(operator, conditions);
   }
   const expressions = conditions.map((c) => buildExpression(c, params));
   return `(${expressions.join(` ${operator} `)})`;
 };
 var buildExpression = (condition, params) => {
   if (!condition) return "";
-  try {
-    const expressionBuilders = {
-      eq: () => buildComparisonExpression(condition, "=", params),
-      ne: () => buildComparisonExpression(condition, "<>", params),
-      lt: () => buildComparisonExpression(condition, "<", params),
-      lte: () => buildComparisonExpression(condition, "<=", params),
-      gt: () => buildComparisonExpression(condition, ">", params),
-      gte: () => buildComparisonExpression(condition, ">=", params),
-      between: () => buildBetweenExpression(condition, params),
-      in: () => buildInExpression(condition, params),
-      beginsWith: () => buildFunctionExpression("begins_with", condition, params),
-      contains: () => buildFunctionExpression("contains", condition, params),
-      attributeExists: () => buildAttributeFunction("attribute_exists", condition, params),
-      attributeNotExists: () => buildAttributeFunction("attribute_not_exists", condition, params),
-      and: () => {
-        if (!condition.conditions) {
-          throw new Error("Conditions array is required for AND operator");
-        }
-        return buildLogicalExpression("AND", condition.conditions, params);
-      },
-      or: () => {
-        if (!condition.conditions) {
-          throw new Error("Conditions array is required for OR operator");
-        }
-        return buildLogicalExpression("OR", condition.conditions, params);
-      },
-      not: () => {
-        if (!condition.condition) {
-          throw new Error("Condition is required for NOT operator");
-        }
-        return `NOT (${buildExpression(condition.condition, params)})`;
+  const expressionBuilders = {
+    eq: () => buildComparisonExpression(condition, "=", params),
+    ne: () => buildComparisonExpression(condition, "<>", params),
+    lt: () => buildComparisonExpression(condition, "<", params),
+    lte: () => buildComparisonExpression(condition, "<=", params),
+    gt: () => buildComparisonExpression(condition, ">", params),
+    gte: () => buildComparisonExpression(condition, ">=", params),
+    between: () => buildBetweenExpression(condition, params),
+    in: () => buildInExpression(condition, params),
+    beginsWith: () => buildFunctionExpression("begins_with", condition, params),
+    contains: () => buildFunctionExpression("contains", condition, params),
+    attributeExists: () => buildAttributeFunction("attribute_exists", condition, params),
+    attributeNotExists: () => buildAttributeFunction("attribute_not_exists", condition, params),
+    and: () => {
+      if (!condition.conditions) {
+        throw ExpressionErrors.invalidCondition(
+          condition.type,
+          condition,
+          "Provide an array of conditions to combine with AND"
+        );
       }
-    };
-    const builder = expressionBuilders[condition.type];
-    if (!builder) {
-      throw new Error(`Unknown condition type: ${condition.type}`);
-    }
-    return builder();
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error(`Error building expression for condition type ${condition.type}:`, error.message);
-    } else {
-      console.error(`Error building expression for condition type ${condition.type}:`, error);
+      return buildLogicalExpression("AND", condition.conditions, params);
+    },
+    or: () => {
+      if (!condition.conditions) {
+        throw ExpressionErrors.invalidCondition(
+          condition.type,
+          condition,
+          "Provide an array of conditions to combine with OR"
+        );
+      }
+      return buildLogicalExpression("OR", condition.conditions, params);
+    },
+    not: () => {
+      if (!condition.condition) {
+        throw ExpressionErrors.invalidCondition(condition.type, condition, "Provide a condition to negate with NOT");
+      }
+      return `NOT (${buildExpression(condition.condition, params)})`;
     }
-    throw error;
+  };
+  const builder = expressionBuilders[condition.type];
+  if (!builder) {
+    throw ExpressionErrors.unknownType(condition.type, condition);
   }
+  return builder();
 };
 var prepareExpressionParams = (condition) => {
   if (!condition) return {};
@@ -1462,6 +1465,32 @@ var FilterBuilder = class {
     this.options.lastEvaluatedKey = lastEvaluatedKey;
     return this;
   }
+  /**
+   * Executes the operation and returns the first matching item, if any.
+   *
+   * This helper:
+   * - Applies an internal limit of 1
+   * - Streams results until a match is found or there are no more pages
+   * - Avoids mutating the current builder by using a clone
+   *
+   * @example
+   * ```typescript
+   * const latest = await table
+   *   .query(eq("moduleId", moduleId))
+   *   .useIndex("module-version-index")
+   *   .sortDescending()
+   *   .findOne();
+   * ```
+   *
+   * @returns The first matching item, or undefined if none found
+   */
+  async findOne() {
+    const iterator = await this.clone().limit(1).execute();
+    for await (const item of iterator) {
+      return item;
+    }
+    return void 0;
+  }
 };
 
 // src/builders/result-iterator.ts
@@ -1535,10 +1564,13 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
   keyCondition;
   options = {};
   executor;
-  constructor(executor, keyCondition) {
+  includeIndexAttributes = false;
+  indexAttributeNames;
+  constructor(executor, keyCondition, indexAttributeNames = []) {
     super();
     this.executor = executor;
     this.keyCondition = keyCondition;
+    this.indexAttributeNames = indexAttributeNames;
   }
   /**
    * Sets the maximum number of items to return from the query.
@@ -1611,6 +1643,24 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
     this.options.scanIndexForward = false;
     return this;
   }
+  /**
+   * Ensures index attributes are included in the result.
+   * By default, index attributes are removed from query responses.
+   */
+  includeIndexes() {
+    this.includeIndexAttributes = true;
+    if (this.selectedFields.size > 0) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
+  select(fields) {
+    super.select(fields);
+    if (this.includeIndexAttributes) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
   /**
    * Creates a deep clone of this QueryBuilder instance.
    *
@@ -1645,12 +1695,13 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
    * @returns A new QueryBuilder instance with the same configuration
    */
   clone() {
-    const clone = new _QueryBuilder(this.executor, this.keyCondition);
+    const clone = new _QueryBuilder(this.executor, this.keyCondition, this.indexAttributeNames);
     clone.options = {
       ...this.options,
       filter: this.deepCloneFilter(this.options.filter)
     };
     clone.selectedFields = new Set(this.selectedFields);
+    clone.includeIndexAttributes = this.includeIndexAttributes;
     return clone;
   }
   deepCloneFilter(filter) {
@@ -1702,9 +1753,39 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
    * @returns A promise that resolves to a ResultGenerator that behaves like an array
    */
   async execute() {
-    const directExecutor = () => this.executor(this.keyCondition, this.options);
+    const directExecutor = async () => {
+      const result = await this.executor(this.keyCondition, this.options);
+      if (this.includeIndexAttributes || this.indexAttributeNames.length === 0) {
+        return result;
+      }
+      return {
+        ...result,
+        items: result.items.map((item) => this.omitIndexAttributes(item))
+      };
+    };
     return new ResultIterator(this, directExecutor);
   }
+  addIndexAttributesToSelection() {
+    if (this.indexAttributeNames.length === 0) return;
+    for (const attributeName of this.indexAttributeNames) {
+      this.selectedFields.add(attributeName);
+    }
+    this.options.projection = Array.from(this.selectedFields);
+  }
+  omitIndexAttributes(item) {
+    if (this.indexAttributeNames.length === 0) {
+      return item;
+    }
+    let didOmit = false;
+    const cleaned = { ...item };
+    for (const attributeName of this.indexAttributeNames) {
+      if (attributeName in cleaned) {
+        delete cleaned[attributeName];
+        didOmit = true;
+      }
+    }
+    return didOmit ? cleaned : item;
+  }
 };
 
 // src/utils/debug-transaction.ts
@@ -1755,7 +1836,7 @@ var TransactionBuilder = class {
     const pkValue = newItem[pkName];
     const skValue = skName ? newItem[skName] : void 0;
     if (!pkValue) {
-      throw new Error(`Primary key value for '${pkName}' is missing`);
+      throw ConfigurationErrors.primaryKeyMissing(tableName, pkName, newItem);
     }
     const duplicateItem = this.items.find((item) => {
       let itemKey;
@@ -1787,8 +1868,10 @@ var TransactionBuilder = class {
       return false;
     });
     if (duplicateItem) {
-      throw new Error(
-        `Duplicate item detected in transaction: Table=${tableName}, ${pkName}=${String(pkValue)}, ${skName}=${skValue !== void 0 ? String(skValue) : "undefined"}. DynamoDB transactions do not allow multiple operations on the same item.`
+      throw TransactionErrors.duplicateItem(
+        tableName,
+        { name: pkName, value: pkValue },
+        skName ? { name: skName, value: skValue } : void 0
       );
     }
   }
@@ -1798,7 +1881,7 @@ var TransactionBuilder = class {
     };
     if (this.indexConfig.sortKey) {
       if (key.sk === void 0) {
-        throw new Error("Sort key is required for delete operation");
+        throw ConfigurationErrors.sortKeyRequired("", this.indexConfig.partitionKey, this.indexConfig.sortKey);
       }
       keyCondition[this.indexConfig.sortKey] = key.sk;
     }
@@ -2172,7 +2255,7 @@ var TransactionBuilder = class {
     this.checkForDuplicateItem(tableName, keyCondition);
     const { expression, names, values } = prepareExpressionParams(condition);
     if (!expression) {
-      throw new Error("Failed to generate condition expression");
+      throw ConfigurationErrors.conditionGenerationFailed(condition);
     }
     const transactionItem = {
       type: "ConditionCheck",
@@ -2326,7 +2409,7 @@ var TransactionBuilder = class {
    */
   async execute() {
     if (this.items.length === 0) {
-      throw new Error("No transaction items specified");
+      throw TransactionErrors.transactionEmpty();
     }
     const transactItems = this.items.map((item) => {
       switch (item.type) {
@@ -2373,7 +2456,7 @@ var TransactionBuilder = class {
           };
         default: {
           const exhaustiveCheck = item;
-          throw new Error(`Unsupported transaction item type: ${String(exhaustiveCheck)}`);
+          throw TransactionErrors.unsupportedType(exhaustiveCheck);
         }
       }
     });
@@ -2386,9 +2469,7 @@ var TransactionBuilder = class {
     try {
       await this.executor(params);
     } catch (error) {
-      console.log(this.debug());
-      console.error("Error executing transaction:", error);
-      throw error;
+      throw TransactionErrors.transactionFailed(this.items.length, {}, error instanceof Error ? error : void 0);
     }
   }
 };
@@ -2410,6 +2491,9 @@ var UpdateBuilder = class {
   set(valuesOrPath, value) {
     if (typeof valuesOrPath === "object") {
       for (const [key, value2] of Object.entries(valuesOrPath)) {
+        if (value2 === void 0) {
+          throw ValidationErrors.undefinedValue(key, this.tableName, this.key);
+        }
         this.updates.push({
           type: "SET",
           path: key,
@@ -2417,6 +2501,9 @@ var UpdateBuilder = class {
         });
       }
     } else {
+      if (value === void 0) {
+        throw ValidationErrors.undefinedValue(valuesOrPath, this.tableName, this.key);
+      }
       this.updates.push({
         type: "SET",
         path: valuesOrPath,
@@ -2472,6 +2559,9 @@ var UpdateBuilder = class {
    * @returns The builder instance for method chaining
    */
   add(path, value) {
+    if (value === void 0) {
+      throw ValidationErrors.undefinedValue(path, this.tableName, this.key);
+    }
     this.updates.push({
       type: "ADD",
       path,
@@ -2508,6 +2598,9 @@ var UpdateBuilder = class {
    * @returns The builder instance for method chaining
    */
   deleteElementsFromSet(path, value) {
+    if (value === void 0) {
+      throw ValidationErrors.undefinedValue(path, this.tableName, this.key);
+    }
     let valuesToDelete;
     if (Array.isArray(value)) {
       valuesToDelete = new Set(value);
@@ -2626,7 +2719,7 @@ var UpdateBuilder = class {
    */
   toDynamoCommand() {
     if (this.updates.length === 0) {
-      throw new Error("No update actions specified");
+      throw ValidationErrors.noUpdateActions(this.tableName, this.key);
     }
     const expressionParams = {
       expressionAttributeNames: {},
@@ -2900,11 +2993,11 @@ var ConditionCheckBuilder = class {
    */
   toDynamoCommand() {
     if (!this.conditionExpression) {
-      throw new Error("Condition is required for condition check operations");
+      throw ValidationErrors.conditionRequired(this.tableName, this.key);
     }
     const { expression, names, values } = prepareExpressionParams(this.conditionExpression);
     if (!expression) {
-      throw new Error("Failed to generate condition expression");
+      throw ConfigurationErrors.conditionGenerationFailed(this.conditionExpression);
     }
     return {
       tableName: this.tableName,
@@ -2936,7 +3029,7 @@ var ConditionCheckBuilder = class {
    */
   withTransaction(transaction) {
     if (!this.conditionExpression) {
-      throw new Error("Condition is required for condition check operations");
+      throw ValidationErrors.conditionRequired(this.tableName, this.key);
     }
     const command = this.toDynamoCommand();
     transaction.conditionCheckWithCommand(command);
@@ -2976,16 +3069,19 @@ var GetBuilder = class {
    * @param key - Primary key of the item to retrieve
    * @param tableName - Name of the DynamoDB table
    */
-  constructor(executor, key, tableName) {
+  constructor(executor, key, tableName, indexAttributeNames = []) {
     this.executor = executor;
     this.params = {
       tableName,
       key
     };
+    this.indexAttributeNames = indexAttributeNames;
   }
   params;
   options = {};
   selectedFields = /* @__PURE__ */ new Set();
+  includeIndexAttributes = false;
+  indexAttributeNames;
   /**
    * Specifies which attributes to return in the get results.
    *
@@ -3014,9 +3110,23 @@ var GetBuilder = class {
         this.selectedFields.add(field);
       }
     }
+    if (this.includeIndexAttributes) {
+      this.addIndexAttributesToSelection();
+    }
     this.options.projection = Array.from(this.selectedFields);
     return this;
   }
+  /**
+   * Ensures index attributes are included in the result.
+   * By default, index attributes are removed from get responses.
+   */
+  includeIndexes() {
+    this.includeIndexAttributes = true;
+    if (this.selectedFields.size > 0) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
   /**
    * Sets whether to use strongly consistent reads for the get operation.
    * Use this method when you need:
@@ -3095,6 +3205,27 @@ var GetBuilder = class {
       expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0
     };
   }
+  addIndexAttributesToSelection() {
+    if (this.indexAttributeNames.length === 0) return;
+    for (const attributeName of this.indexAttributeNames) {
+      this.selectedFields.add(attributeName);
+    }
+    this.options.projection = Array.from(this.selectedFields);
+  }
+  omitIndexAttributes(item) {
+    if (!item || this.includeIndexAttributes || this.indexAttributeNames.length === 0) {
+      return item;
+    }
+    let didOmit = false;
+    const cleaned = { ...item };
+    for (const attributeName of this.indexAttributeNames) {
+      if (attributeName in cleaned) {
+        delete cleaned[attributeName];
+        didOmit = true;
+      }
+    }
+    return didOmit ? cleaned : item;
+  }
   /**
    * Executes the get operation against DynamoDB.
    *
@@ -3121,7 +3252,10 @@ var GetBuilder = class {
    */
   async execute() {
     const command = this.toDynamoCommand();
-    return this.executor(command);
+    const result = await this.executor(command);
+    return {
+      item: this.omitIndexAttributes(result.item)
+    };
   }
 };
 
@@ -3197,4 +3331,4 @@ var ScanBuilder = class _ScanBuilder extends FilterBuilder {
   }
 };
 
-export { BatchBuilder, BatchError, ConditionCheckBuilder, DeleteBuilder, FilterBuilder, GetBuilder, Paginator, PutBuilder, QueryBuilder, ResultIterator, ScanBuilder, TransactionBuilder, UpdateBuilder, buildExpression, debugCommand, generateAttributeName };
+export { BatchBuilder, ConditionCheckBuilder, DeleteBuilder, FilterBuilder, GetBuilder, Paginator, PutBuilder, QueryBuilder, ResultIterator, ScanBuilder, TransactionBuilder, UpdateBuilder, buildExpression, generateAttributeName };