dyno-table 2.3.3 → 2.5.0

package/dist/{index-2cbm07Bi.d.ts → index-C9KOQdSC.d.ts}

@@ -1,7 +1,220 @@
-import { c as PrimaryKeyWithoutExpression, s as Path, a as Condition, b as ConditionOperator, t as PathType } from './conditions-D_w7vVYG.js';
+import { P as PrimaryKeyWithoutExpression, s as Path, b as Condition, c as ConditionOperator, t as PathType } from './conditions-BSAcZswY.js';
 import { DynamoItem, TableConfig, GSINames } from './types.js';
 import { TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
 
+/**
+ * Base error class for all dyno-table errors
+ *
+ * All custom errors in the library extend this class, allowing consumers
+ * to catch all library errors with a single catch block if needed.
+ */
+declare class DynoTableError extends Error {
+    /**
+     * Machine-readable error code for programmatic error handling
+     * @example "KEY_GENERATION_FAILED", "VALIDATION_ERROR", etc.
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error
+     * Contains operation-specific details like entity names, table names,
+     * expressions, conditions, and other relevant debugging information
+     */
+    readonly context: Record<string, unknown>;
+    /**
+     * The original error that caused this error (if wrapping another error)
+     * Useful for preserving AWS SDK errors or other underlying errors
+     */
+    readonly cause?: Error;
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for schema validation and input validation failures
+ *
+ * Thrown when user-provided data doesn't match the expected schema
+ * or when required fields are missing.
+ */
+declare class ValidationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for DynamoDB operation failures
+ *
+ * Wraps AWS SDK errors and adds library-specific context like
+ * the operation type, table name, and generated expressions.
+ */
+declare class OperationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for transaction-specific failures
+ *
+ * Thrown when transaction operations fail, including duplicate item
+ * detection, transaction cancellation, and other transaction-related issues.
+ */
+declare class TransactionError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for batch operation failures
+ *
+ * Thrown when batch operations fail or when batch limits are exceeded.
+ * Includes information about unprocessed items and operation details.
+ */
+declare class BatchError extends DynoTableError {
+    /**
+     * The type of batch operation that failed
+     */
+    readonly operation: "write" | "read";
+    /**
+     * The items that were not processed during the batch operation
+     */
+    readonly unprocessedItems: unknown[];
+    constructor(message: string, code: string, operation: "write" | "read", unprocessedItems?: unknown[], context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for expression building failures
+ *
+ * Thrown when building DynamoDB expressions (condition, filter, update, etc.)
+ * fails due to invalid conditions or missing required fields.
+ */
+declare class ExpressionError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for table/index configuration issues
+ *
+ * Thrown when there are problems with table configuration,
+ * such as missing GSIs or invalid index references.
+ */
+declare class ConfigurationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Base error for all entity-related errors
+ *
+ * Parent class for entity-specific errors like key generation
+ * and index generation failures.
+ */
+declare class EntityError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for primary key generation failures
+ *
+ * Thrown when generating entity primary keys fails due to missing
+ * attributes or invalid key formats.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await userRepo.create({ name: "John" }).execute();
+ * } catch (error) {
+ *   if (error instanceof KeyGenerationError) {
+ *     console.error("Failed to generate key");
+ *     console.error("Entity:", error.context.entityName);
+ *     console.error("Required attributes:", error.context.requiredAttributes);
+ *   }
+ * }
+ * ```
+ */
+declare class KeyGenerationError extends EntityError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for index key generation failures
+ *
+ * Thrown when generating secondary index keys fails due to missing
+ * attributes or when trying to update readonly indexes without forcing.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await orderRepo.update({ id: "123" }, { status: "shipped" }).execute();
+ * } catch (error) {
+ *   if (error instanceof IndexGenerationError) {
+ *     console.error("Index failed:", error.context.indexName);
+ *     console.error("Suggestion:", error.context.suggestion);
+ *   }
+ * }
+ * ```
+ */
+declare class IndexGenerationError extends EntityError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for entity schema validation failures
+ *
+ * Thrown when entity data doesn't pass schema validation.
+ * Includes validation issues and the entity context.
+ */
+declare class EntityValidationError extends ValidationError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error codes used throughout the library
+ *
+ * These codes allow for programmatic error handling and can be used
+ * to implement retry logic, user-friendly error messages, etc.
+ */
+declare const ErrorCodes: {
+    readonly KEY_GENERATION_FAILED: "KEY_GENERATION_FAILED";
+    readonly KEY_MISSING_ATTRIBUTES: "KEY_MISSING_ATTRIBUTES";
+    readonly KEY_INVALID_FORMAT: "KEY_INVALID_FORMAT";
+    readonly INDEX_GENERATION_FAILED: "INDEX_GENERATION_FAILED";
+    readonly INDEX_MISSING_ATTRIBUTES: "INDEX_MISSING_ATTRIBUTES";
+    readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
+    readonly INDEX_READONLY_UPDATE_FAILED: "INDEX_READONLY_UPDATE_FAILED";
+    readonly INDEX_UNDEFINED_VALUES: "INDEX_UNDEFINED_VALUES";
+    readonly ENTITY_VALIDATION_FAILED: "ENTITY_VALIDATION_FAILED";
+    readonly ASYNC_VALIDATION_NOT_SUPPORTED: "ASYNC_VALIDATION_NOT_SUPPORTED";
+    readonly QUERY_INPUT_VALIDATION_FAILED: "QUERY_INPUT_VALIDATION_FAILED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
+    readonly UNDEFINED_VALUE: "UNDEFINED_VALUE";
+    readonly EXPRESSION_MISSING_ATTRIBUTE: "EXPRESSION_MISSING_ATTRIBUTE";
+    readonly EXPRESSION_MISSING_VALUE: "EXPRESSION_MISSING_VALUE";
+    readonly EXPRESSION_INVALID_CONDITION: "EXPRESSION_INVALID_CONDITION";
+    readonly EXPRESSION_EMPTY_ARRAY: "EXPRESSION_EMPTY_ARRAY";
+    readonly EXPRESSION_UNKNOWN_TYPE: "EXPRESSION_UNKNOWN_TYPE";
+    readonly EXPRESSION_INVALID: "EXPRESSION_INVALID";
+    readonly EXPRESSION_INVALID_OPERATOR: "EXPRESSION_INVALID_OPERATOR";
+    readonly QUERY_FAILED: "QUERY_FAILED";
+    readonly SCAN_FAILED: "SCAN_FAILED";
+    readonly GET_FAILED: "GET_FAILED";
+    readonly PUT_FAILED: "PUT_FAILED";
+    readonly DELETE_FAILED: "DELETE_FAILED";
+    readonly UPDATE_FAILED: "UPDATE_FAILED";
+    readonly BATCH_GET_FAILED: "BATCH_GET_FAILED";
+    readonly BATCH_WRITE_FAILED: "BATCH_WRITE_FAILED";
+    readonly NO_UPDATE_ACTIONS: "NO_UPDATE_ACTIONS";
+    readonly CONDITIONAL_CHECK_FAILED: "CONDITIONAL_CHECK_FAILED";
+    readonly TRANSACTION_FAILED: "TRANSACTION_FAILED";
+    readonly TRANSACTION_DUPLICATE_ITEM: "TRANSACTION_DUPLICATE_ITEM";
+    readonly TRANSACTION_EMPTY: "TRANSACTION_EMPTY";
+    readonly TRANSACTION_UNSUPPORTED_TYPE: "TRANSACTION_UNSUPPORTED_TYPE";
+    readonly TRANSACTION_ITEM_LIMIT: "TRANSACTION_ITEM_LIMIT";
+    readonly TRANSACTION_CANCELLED: "TRANSACTION_CANCELLED";
+    readonly BATCH_EMPTY: "BATCH_EMPTY";
+    readonly BATCH_UNSUPPORTED_TYPE: "BATCH_UNSUPPORTED_TYPE";
+    readonly BATCH_UNPROCESSED_ITEMS: "BATCH_UNPROCESSED_ITEMS";
+    readonly BATCH_SIZE_EXCEEDED: "BATCH_SIZE_EXCEEDED";
+    readonly GSI_NOT_FOUND: "GSI_NOT_FOUND";
+    readonly SORT_KEY_REQUIRED: "SORT_KEY_REQUIRED";
+    readonly SORT_KEY_NOT_DEFINED: "SORT_KEY_NOT_DEFINED";
+    readonly PRIMARY_KEY_MISSING: "PRIMARY_KEY_MISSING";
+    readonly INVALID_CHUNK_SIZE: "INVALID_CHUNK_SIZE";
+    readonly CONDITION_REQUIRED: "CONDITION_REQUIRED";
+    readonly CONDITION_GENERATION_FAILED: "CONDITION_GENERATION_FAILED";
+    readonly PK_EXTRACTION_FAILED: "PK_EXTRACTION_FAILED";
+    readonly CONFIGURATION_INVALID: "CONFIGURATION_INVALID";
+    readonly CONFIGURATION_MISSING_SORT_KEY: "CONFIGURATION_MISSING_SORT_KEY";
+    readonly CONFIGURATION_INVALID_GSI: "CONFIGURATION_INVALID_GSI";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
 type BatchWriteOperation<T extends Record<string, unknown>> = {
     type: "put";
     item: T;
@@ -141,6 +354,7 @@ interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig
     getLimit(): number | undefined;
     startFrom(lastEvaluatedKey: DynamoItem): B;
     execute(): Promise<ResultIterator<T, TConfig>>;
+    findOne(): Promise<T | undefined>;
 }
 /**
  * Interface for the QueryBuilder class to be used by Paginator
@@ -246,6 +460,8 @@ declare class GetBuilder<T extends DynamoItem> {
     private readonly params;
     private options;
     private selectedFields;
+    private includeIndexAttributes;
+    private readonly indexAttributeNames;
     /**
      * Creates a new GetBuilder instance.
      *
@@ -253,7 +469,7 @@ declare class GetBuilder<T extends DynamoItem> {
      * @param key - Primary key of the item to retrieve
      * @param tableName - Name of the DynamoDB table
      */
-    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string);
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string, indexAttributeNames?: string[]);
     /**
      * Specifies which attributes to return in the get results.
      *
@@ -275,6 +491,11 @@ declare class GetBuilder<T extends DynamoItem> {
      * @returns The builder instance for method chaining
      */
     select<K extends Path<T>>(fields: K | K[]): GetBuilder<T>;
+    /**
+     * Ensures index attributes are included in the result.
+     * By default, index attributes are removed from get responses.
+     */
+    includeIndexes(): GetBuilder<T>;
     /**
      * Sets whether to use strongly consistent reads for the get operation.
      * Use this method when you need:
@@ -337,6 +558,8 @@ declare class GetBuilder<T extends DynamoItem> {
      * Converts the builder configuration to a DynamoDB command
      */
     private toDynamoCommand;
+    private addIndexAttributesToSelection;
+    private omitIndexAttributes;
     /**
      * Executes the get operation against DynamoDB.
      *
@@ -386,14 +609,6 @@ type BatchGetExecutor = (keys: Array<PrimaryKeyWithoutExpression>) => Promise<{
     items: DynamoItem[];
     unprocessedKeys: PrimaryKeyWithoutExpression[];
 }>;
-/**
- * Error class for batch operation failures
- */
-declare class BatchError extends Error {
-    readonly operation: "write" | "read";
-    readonly cause?: Error;
-    constructor(message: string, operation: "write" | "read", cause?: Error);
-}
 /**
  * Result structure for batch operations
  */
@@ -848,7 +1063,7 @@ declare class TransactionBuilder {
      * @returns The transaction builder for method chaining
      * @throws {Error} If a duplicate item is detected in the transaction
      */
-    update<T extends DynamoItem>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): this;
+    update<_T extends DynamoItem>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): this;
     /**
      * Adds a pre-configured update operation to the transaction.
      *
@@ -1971,6 +2186,26 @@ declare abstract class FilterBuilder<T extends DynamoItem, TConfig extends Table
      * their specific execution logic.
      */
     abstract execute(): Promise<ResultIterator<T, TConfig>>;
+    /**
+     * 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
+     */
+    findOne(): Promise<T | undefined>;
 }
 
 /**
@@ -2033,7 +2268,9 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
     private readonly keyCondition;
     protected options: QueryOptions;
     protected readonly executor: QueryExecutor<T>;
-    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
+    private includeIndexAttributes;
+    private readonly indexAttributeNames;
+    constructor(executor: QueryExecutor<T>, keyCondition: Condition, indexAttributeNames?: string[]);
     /**
      * Sets the maximum number of items to return from the query.
      *
@@ -2099,6 +2336,12 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      * @returns The builder instance for method chaining
      */
     sortDescending(): this;
+    /**
+     * Ensures index attributes are included in the result.
+     * By default, index attributes are removed from query responses.
+     */
+    includeIndexes(): this;
+    select<K extends Path<T>>(fields: K | K[]): this;
     /**
      * Creates a deep clone of this QueryBuilder instance.
      *
@@ -2173,6 +2416,8 @@ declare class QueryBuilder<T extends DynamoItem, TConfig extends TableConfig = T
      * @returns A promise that resolves to a ResultGenerator that behaves like an array
      */
     execute(): Promise<ResultIterator<T, TConfig>>;
+    private addIndexAttributesToSelection;
+    private omitIndexAttributes;
 }
 
 /**
@@ -2794,4 +3039,4 @@ declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = Ta
     execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
-export { BatchBuilder as B, ConditionCheckBuilder as C, DeleteBuilder as D, FilterBuilder as F, GetBuilder as G, PutBuilder as P, QueryBuilder as Q, ResultIterator as R, ScanBuilder as S, TransactionBuilder as T, UpdateBuilder as U, BatchError as a, type BatchResult as b, type DeleteOptions as c, type PutOptions as d, type QueryOptions as e, type TransactionOptions as f, type UpdateOptions as g, type BatchWriteOperation as h, type UpdateCommandParams as i, Paginator as j, type DeleteCommandParams as k, type PutCommandParams as l, type ConditionCheckCommandParams as m, type BaseBuilderInterface as n, type QueryBuilderInterface as o, type ScanBuilderInterface as p, type FilterBuilderInterface as q, type PaginationResult as r, type TransactionItem as s };
+export { BatchBuilder as B, ConditionCheckBuilder as C, DeleteBuilder as D, ExpressionError as E, FilterBuilder as F, GetBuilder as G, IndexGenerationError as I, KeyGenerationError as K, OperationError as O, PutBuilder as P, QueryBuilder as Q, ResultIterator as R, ScanBuilder as S, TransactionBuilder as T, UpdateBuilder as U, ValidationError as V, type TransactionOptions as a, type BatchWriteOperation as b, BatchError as c, ConfigurationError as d, EntityValidationError as e, TransactionError as f, DynoTableError as g, EntityError as h, type BatchResult as i, type DeleteOptions as j, type PutOptions as k, type QueryOptions as l, type UpdateOptions as m, ErrorCodes as n, type ErrorCode as o, type UpdateCommandParams as p, Paginator as q, type DeleteCommandParams as r, type PutCommandParams as s, type ConditionCheckCommandParams as t, type BaseBuilderInterface as u, type QueryBuilderInterface as v, type ScanBuilderInterface as w, type FilterBuilderInterface as x, type PaginationResult as y, type TransactionItem as z };