dyno-table 0.0.2 → 0.1.2

package/dist/index.d.ts

@@ -1,444 +1,2918 @@
-import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+import { DynamoDBDocument, TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
 
-interface ExpressionAttributes {
-    names?: Record<string, string>;
-    values?: Record<string, unknown>;
+interface Index {
+    partitionKey: string;
+    sortKey?: string;
 }
-interface ExpressionResult {
-    expression?: string;
-    attributes: ExpressionAttributes;
+interface IndexConfig$1 {
+    partitionKey: string;
+    sortKey?: string;
+    gsis?: Record<string, Index>;
 }
-type FunctionOperator = "attribute_exists" | "attribute_not_exists" | "begins_with" | "contains" | "not_contains" | "attribute_type";
-type ComparisonOperator = "=" | "<" | "<=" | ">" | ">=" | "<>";
-type SpecialOperator = "BETWEEN" | "IN" | "size";
-type ConditionOperator = FunctionOperator | ComparisonOperator | SpecialOperator;
-type FilterOperator = "=" | "<" | "<=" | ">" | ">=" | "<>" | "BETWEEN" | "IN" | "contains" | "begins_with";
-interface FilterCondition {
-    field: string;
-    operator: FilterOperator;
-    value: unknown;
+interface TableConfig {
+    client: DynamoDBDocument;
+    tableName: string;
+    indexes: IndexConfig$1;
 }
+type GSINames<T extends TableConfig> = keyof NonNullable<T["indexes"]["gsis"]>;
+interface EntityConfig<T> {
+    name: string;
+    partitionKeyPrefix?: string;
+    sortKeyPrefix?: string;
+    timestamps?: boolean;
+    discriminator?: string;
+}
+
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+type IsEqual<T1, T2> = T1 extends T2 ? (<G>() => G extends T1 ? 1 : 2) extends <G>() => G extends T2 ? 1 : 2 ? true : false : false;
+interface File extends Blob {
+    readonly lastModified: number;
+    readonly name: string;
+}
+interface FileList {
+    readonly length: number;
+    item(index: number): File | null;
+    [index: number]: File;
+}
+type BrowserNativeObject = Date | FileList | File;
+type IsTuple<T extends ReadonlyArray<any>> = number extends T["length"] ? false : true;
+type TupleKeys<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
+type AnyIsEqual<T1, T2> = T1 extends T2 ? (IsEqual<T1, T2> extends true ? true : never) : never;
+type PathImpl<K extends string | number, V, TraversedTypes> = V extends Primitive | BrowserNativeObject ? `${K}` : true extends AnyIsEqual<TraversedTypes, V> ? `${K}` : `${K}` | `${K}.${PathInternal<V, TraversedTypes | V>}`;
+type ArrayKey = number;
+type PathInternal<T, TraversedTypes = T> = T extends ReadonlyArray<infer V> ? IsTuple<T> extends true ? {
+    [K in TupleKeys<T>]-?: PathImpl<K & string, T[K], TraversedTypes>;
+}[TupleKeys<T>] : PathImpl<ArrayKey, V, TraversedTypes> : {
+    [K in keyof T]-?: PathImpl<K & string, T[K], TraversedTypes>;
+}[keyof T];
+type Path<T> = T extends any ? PathInternal<T> : never;
+type PathType<T, K extends keyof any> = K extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? Rest extends keyof any ? PathType<T[Key], Rest> : never : never : K extends keyof T ? T[K] : never;
+
+/**
+ * Supported comparison operators for DynamoDB conditions.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Comparison Operator Reference}
+ *
+ * - eq: Equals (=)
+ * - ne: Not equals (≠ / <>)
+ * - lt: Less than (<)
+ * - lte: Less than or equal to (≤)
+ * - gt: Greater than (>)
+ * - gte: Greater than or equal to (≥)
+ * - between: Between two values (inclusive)
+ * - beginsWith: Checks if string attribute begins with specified substring
+ * - contains: Checks if string/set attribute contains specified value
+ * - attributeExists: Checks if attribute exists
+ * - attributeNotExists: Checks if attribute does not exist
+ */
+type ComparisonOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "between" | "beginsWith" | "contains" | "attributeExists" | "attributeNotExists";
+/**
+ * Logical operators for combining multiple conditions.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - Logical Operator Reference}
+ *
+ * - and: Evaluates to true if all conditions are true
+ * - or: Evaluates to true if any condition is true
+ * - not: Negate the result of a condition
+ */
+type LogicalOperator = "and" | "or" | "not";
+/**
+ * Represents a DynamoDB condition expression.
+ * Can be either a comparison condition or a logical combination of conditions.
+ *
+ * @example
+ * // Simple comparison condition
+ * const condition: Condition = {
+ *   type: "eq",
+ *   attr: "status",
+ *   value: "ACTIVE"
+ * };
+ *
+ * @example
+ * // Logical combination of conditions
+ * const condition: Condition = {
+ *   type: "and",
+ *   conditions: [
+ *     { type: "eq", attr: "status", value: "ACTIVE" },
+ *     { type: "gt", attr: "age", value: 5 }
+ *   ]
+ * };
+ */
 interface Condition {
-    field: string;
-    operator: ConditionOperator;
+    /** The type of condition (comparison or logical operator) */
+    type: ComparisonOperator | LogicalOperator;
+    /** The attribute name for comparison conditions */
+    attr?: string;
+    /** The value to compare against for comparison conditions */
     value?: unknown;
+    /** Array of conditions for logical operators (and/or) */
+    conditions?: Condition[];
+    /** Single condition for the 'not' operator */
+    condition?: Condition;
 }
-type SKCondition = {
-    operator: FilterOperator;
-    value: string;
+/**
+ * Creates an equals (=) condition
+ * @example
+ * eq("status", "ACTIVE") // status = "ACTIVE"
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const eq: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a not equals (≠) condition
+ * @example
+ * ne("status", "DELETED") // status <> "DELETED"
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const ne: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a less than (<) condition
+ * @example
+ * lt("age", 18) // age < 18
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const lt: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a less than or equal to (≤) condition
+ * @example
+ * lte("age", 18) // age <= 18
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const lte: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a greater than (>) condition
+ * @example
+ * gt("price", 100) // price > 100
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const gt: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a greater than or equal to (≥) condition
+ * @example
+ * gte("price", 100) // price >= 100
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}
+ */
+declare const gte: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a between condition that checks if a value is within a range (inclusive)
+ * @example
+ * between("age", 18, 65) // age BETWEEN 18 AND 65
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}
+ */
+declare const between: (attr: string, lower: unknown, upper: unknown) => Condition;
+/**
+ * Creates a begins_with condition that checks if a string attribute starts with a substring
+ * @example
+ * beginsWith("email", "@example.com") // begins_with(email, "@example.com")
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}
+ */
+declare const beginsWith: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a contains condition that checks if a string contains a substring or if a set contains an element
+ * @example
+ * contains("tags", "important") // contains(tags, "important")
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}
+ */
+declare const contains: (attr: string, value: unknown) => Condition;
+/**
+ * Creates a condition that checks if an attribute exists
+ * @example
+ * attributeExists("email") // attribute_exists(email)
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}
+ */
+declare const attributeExists: (attr: string) => Condition;
+/**
+ * Creates a condition that checks if an attribute does not exist
+ * @example
+ * attributeNotExists("deletedAt") // attribute_not_exists(deletedAt)
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}
+ */
+declare const attributeNotExists: (attr: string) => Condition;
+/**
+ * Combines multiple conditions with AND operator
+ * @example
+ * and(
+ *   eq("status", "ACTIVE"),
+ *   gt("age", 18)
+ * ) // status = "ACTIVE" AND age > 18
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}
+ */
+declare const and: (...conditions: Condition[]) => Condition;
+/**
+ * Combines multiple conditions with OR operator
+ * @example
+ * or(
+ *   eq("status", "PENDING"),
+ *   eq("status", "PROCESSING")
+ * ) // status = "PENDING" OR status = "PROCESSING"
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}
+ */
+declare const or: (...conditions: Condition[]) => Condition;
+/**
+ * Negates a condition
+ * @example
+ * not(eq("status", "DELETED")) // NOT status = "DELETED"
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}
+ */
+declare const not: (condition: Condition) => Condition;
+/**
+ * Type-safe operators for building key conditions in DynamoDB queries.
+ * Only includes operators that are valid for key conditions.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions AWS DynamoDB - Key Condition Expressions}
+ *
+ * @example
+ * // Using with sort key conditions
+ * table.query({
+ *   pk: "USER#123",
+ *   sk: op => op.beginsWith("ORDER#")
+ * })
+ */
+type KeyConditionOperator = {
+    /** Equals comparison for key attributes */
+    eq: (value: unknown) => Condition;
+    /** Less than comparison for key attributes */
+    lt: (value: unknown) => Condition;
+    /** Less than or equal comparison for key attributes */
+    lte: (value: unknown) => Condition;
+    /** Greater than comparison for key attributes */
+    gt: (value: unknown) => Condition;
+    /** Greater than or equal comparison for key attributes */
+    gte: (value: unknown) => Condition;
+    /** Between range comparison for key attributes */
+    between: (lower: unknown, upper: unknown) => Condition;
+    /** Begins with comparison for key attributes */
+    beginsWith: (value: unknown) => Condition;
+    /** Combines multiple key conditions with AND */
+    and: (...conditions: Condition[]) => Condition;
+};
+/**
+ * Type-safe operators for building conditions in DynamoDB operations.
+ * Includes all available condition operators with proper type inference.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Condition Expressions}
+ *
+ * @example
+ * // Using with type-safe conditions
+ * interface User {
+ *   status: string;
+ *   age: number;
+ *   email?: string;
+ * }
+ *
+ * table.scan<User>()
+ *   .where(op => op.and(
+ *     op.eq("status", "ACTIVE"),
+ *     op.gt("age", 18),
+ *     op.attributeExists("email")
+ *   ))
+ *
+ * @template T The type of the item being operated on
+ */
+type ConditionOperator<T extends Record<string, unknown>> = {
+    eq: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    ne: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    lt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    lte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    gt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    gte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    between: <K extends Path<T>>(attr: K, lower: PathType<T, K>, upper: PathType<T, K>) => Condition;
+    beginsWith: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    contains: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    attributeExists: <K extends Path<T>>(attr: K) => Condition;
+    attributeNotExists: <K extends Path<T>>(attr: K) => Condition;
+    and: (...conditions: Condition[]) => Condition;
+    or: (...conditions: Condition[]) => Condition;
+    not: (condition: Condition) => Condition;
 };
+/**
+ * Primary key type for QUERY operations.
+ * Allows building complex key conditions for the sort key.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html AWS DynamoDB - Query Operations}
+ *
+ * @example
+ * // Query items with a specific partition key and sort key prefix
+ * table.query({
+ *   pk: "USER#123",
+ *   sk: op => op.beginsWith("ORDER#2023")
+ * })
+ *
+ * @example
+ * // Query items within a specific sort key range
+ * table.query({
+ *   pk: "USER#123",
+ *   sk: op => op.between("ORDER#2023-01", "ORDER#2023-12")
+ * })
+ */
 type PrimaryKey = {
+    /** Partition key value */
     pk: string;
-    sk?: SKCondition | string;
+    /** Optional sort key condition builder */
+    sk?: (op: KeyConditionOperator) => Condition;
+};
+/**
+ * Primary key type for GET and DELETE operations.
+ * Used when you need to specify exact key values without conditions.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html AWS DynamoDB - Working with Items}
+ *
+ * @example
+ * // Get a specific item by its complete primary key
+ * table.get({
+ *   pk: "USER#123",
+ *   sk: "PROFILE#123"
+ * })
+ *
+ * @example
+ * // Delete a specific item by its complete primary key
+ * table.delete({
+ *   pk: "USER#123",
+ *   sk: "ORDER#456"
+ * })
+ */
+type PrimaryKeyWithoutExpression = {
+    /** Partition key value */
+    pk: string;
+    /** Optional sort key value */
+    sk?: string;
 };
-interface TableIndexConfig {
-    pkName: string;
-    skName?: string;
-}
 
-interface IExpressionBuilder {
-    buildKeyCondition(key: PrimaryKey, indexConfig: TableIndexConfig): ExpressionResult;
-    createExpression(filters: Condition[]): ExpressionResult;
-    buildUpdateExpression(updates: Record<string, unknown>): ExpressionResult;
+/**
+ * Represents the result of a single page query operation.
+ * This interface provides all necessary information about the current page
+ * and the availability of subsequent pages.
+ */
+interface PaginationResult<T> {
+    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
+    items: T[];
+    /** DynamoDB's last evaluated key, used internally for pagination */
+    lastEvaluatedKey?: Record<string, unknown>;
+    /** Indicates whether there are more pages available */
+    hasNextPage: boolean;
+    /** The current page number (1-indexed) */
+    page: number;
 }
-declare class ExpressionBuilder implements IExpressionBuilder {
-    private nameCount;
-    private valueCount;
-    private generateAlias;
-    private reset;
-    private createAttributePath;
-    private addValue;
-    private buildComparison;
-    createExpression(conditions: Array<{
-        field: string;
-        operator: ConditionOperator;
-        value?: unknown;
-    }>): ExpressionResult;
-    private formatAttributes;
-    buildKeyCondition(key: PrimaryKey, indexConfig: TableIndexConfig): ExpressionResult;
-    buildUpdateExpression(updates: Record<string, unknown>): ExpressionResult;
+/**
+ * A utility class for handling DynamoDB pagination.
+ * Use this class when you need to:
+ * - Browse large collections of dinosaurs
+ * - Review extensive security logs
+ * - Analyze habitat inspection history
+ * - Process feeding schedules
+ *
+ * The paginator maintains internal state and automatically handles:
+ * - Page boundaries
+ * - Result set limits
+ * - Continuation tokens
+ *
+ * @example
+ * ```typescript
+ * // List all velociraptors with pagination
+ * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .paginate(10);
+ *
+ * // Process each page of dinosaurs
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   console.log(`Processing page ${page.page} of velociraptors`);
+ *
+ *   for (const raptor of page.items) {
+ *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being paginated
+ * @typeParam TConfig - The table configuration type
+ */
+declare class Paginator<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private readonly pageSize;
+    private currentPage;
+    private lastEvaluatedKey?;
+    private hasMorePages;
+    private totalItemsRetrieved;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilder<T, TConfig>, pageSize: number);
+    /**
+     * Gets the current page number (1-indexed).
+     * Use this method when you need to:
+     * - Track progress through dinosaur lists
+     * - Display habitat inspection status
+     * - Monitor security sweep progress
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+     *   .paginate(5);
+     *
+     * await paginator.getNextPage();
+     * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+     * ```
+     *
+     * @returns The current page number, starting from 1
+     */
+    getCurrentPage(): number;
+    /**
+     * Checks if there are more pages of dinosaurs or habitats to process.
+     * Use this method when you need to:
+     * - Check for more dinosaurs to review
+     * - Continue habitat inspections
+     * - Process security incidents
+     * - Complete feeding schedules
+     *
+     * This method takes into account both:
+     * - DynamoDB's lastEvaluatedKey mechanism
+     * - Any overall limit set on the query
+     *
+     * @example
+     * ```ts
+     * // Process all security incidents
+     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .sortDescending()
+     *   .paginate(10);
+     *
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   for (const incident of page.items) {
+     *     await processSecurityBreach(incident);
+     *   }
+     *   console.log(`Processed incidents page ${page.page}`);
+     * }
+     * ```
+     *
+     * @returns true if there are more pages available, false otherwise
+     */
+    hasNextPage(): boolean;
+    /**
+     * Retrieves the next page of dinosaurs or habitats from DynamoDB.
+     * Use this method when you need to:
+     * - Process dinosaur groups systematically
+     * - Review habitat inspections in batches
+     * - Monitor security incidents in sequence
+     * - Schedule feeding rotations
+     *
+     * This method handles:
+     * - Automatic continuation between groups
+     * - Respect for park capacity limits
+     * - Group size adjustments for safety
+     *
+     * @example
+     * ```ts
+     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(5);
+     *
+     * // Check first raptor group
+     * const page1 = await paginator.getNextPage();
+     * console.log(`Found ${page1.items.length} active raptors`);
+     *
+     * // Continue inspection if more groups exist
+     * if (page1.hasNextPage) {
+     *   const page2 = await paginator.getNextPage();
+     *   console.log(`Inspecting raptor group ${page2.page}`);
+     *
+     *   for (const raptor of page2.items) {
+     *     await performHealthCheck(raptor);
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to a PaginationResult containing:
+     *          - items: The dinosaurs/habitats for this page
+     *          - hasNextPage: Whether more groups exist
+     *          - page: The current group number
+     *          - lastEvaluatedKey: DynamoDB's continuation token
+     */
+    getNextPage(): Promise<PaginationResult<T>>;
+    /**
+     * Gets all remaining dinosaurs or habitats and combines them into a single array.
+     * Use this method when you need to:
+     * - Generate complete park inventory
+     * - Perform full security audit
+     * - Create comprehensive feeding schedule
+     * - Run park-wide health checks
+     *
+     * Note: Use with caution! This method:
+     * - Could overwhelm systems with large dinosaur populations
+     * - Makes multiple database requests
+     * - May cause system strain during peak hours
+     *
+     * @example
+     * ```ts
+     * // Get complete carnivore inventory
+     * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * try {
+     *   const allCarnivores = await paginator.getAllPages();
+     *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+     *
+     *   // Calculate total threat level
+     *   const totalThreat = allCarnivores.reduce(
+     *     (sum, dino) => sum + dino.stats.threatLevel,
+     *     0
+     *   );
+     *   console.log(`Total threat level: ${totalThreat}`);
+     * } catch (error) {
+     *   console.error('Failed to complete carnivore census:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an array containing all remaining items
+     */
+    getAllPages(): Promise<T[]>;
 }
 
-type DynamoKey = Record<string, unknown>;
-interface DynamoExpression {
-    expression?: string;
-    names?: Record<string, string>;
-    values?: Record<string, unknown>;
-}
-interface DynamoBatchWriteItem {
-    put?: Record<string, unknown>;
-    delete?: DynamoKey;
-}
-interface DynamoPutOperation {
-    type: "put";
-    item: Record<string, unknown>;
-    condition?: DynamoExpression;
-}
-interface DynamoUpdateOperation {
-    type: "update";
-    key: PrimaryKeyWithoutExpression;
-    update: DynamoExpression;
-    condition?: DynamoExpression;
-}
-interface DynamoQueryOperation {
-    type: "query";
-    keyCondition?: DynamoExpression;
-    filter?: DynamoExpression;
-    limit?: number;
-    indexName?: string;
-}
-interface DynamoDeleteOperation {
-    type: "delete";
-    key: PrimaryKeyWithoutExpression;
-    condition?: DynamoExpression;
-}
-interface DynamoScanOperation {
-    type: "scan";
-    filter?: DynamoExpression;
+/**
+ * Configuration options for DynamoDB query operations.
+ */
+interface QueryOptions {
+    /** Condition for the sort key in the table or index */
+    sortKeyCondition?: Condition;
+    /** Additional filter conditions applied after the key condition */
+    filter?: Condition;
+    /** Maximum number of items to return */
     limit?: number;
-    pageKey?: Record<string, unknown>;
+    /** Name of the Global Secondary Index to query */
     indexName?: string;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+    /** Direction of sort key traversal (true for ascending, false for descending) */
+    scanIndexForward?: boolean;
+    /** List of attributes to return in the result */
+    projection?: string[];
+    /** Number of items to fetch per page when using pagination */
+    paginationSize?: number;
+    /** Token for starting the query from a specific point */
+    lastEvaluatedKey?: Record<string, unknown>;
 }
-interface DynamoBatchWriteOperation {
-    type: "batchWrite";
-    operations: DynamoBatchWriteItem[];
-}
-interface DynamoTransactOperation {
-    type: "transactWrite";
-    operations: Array<{
-        put?: {
-            item: Record<string, unknown>;
-            condition?: DynamoExpression;
-        };
-        delete?: {
-            key: PrimaryKeyWithoutExpression;
-            condition?: DynamoExpression;
-        };
-        update?: {
-            key: PrimaryKeyWithoutExpression;
-            update: DynamoExpression;
-            condition?: DynamoExpression;
-        };
+/**
+ * Function type for executing DynamoDB query operations.
+ * @typeParam T - The type of items being queried
+ */
+type QueryExecutor<T extends Record<string, unknown>> = (keyCondition: Condition, options: QueryOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}>;
+/**
+ * Builder for creating DynamoDB query operations.
+ * Use this builder when you need to:
+ * - Query items using partition key (and optionally sort key)
+ * - Filter results based on non-key attributes
+ * - Use Global Secondary Indexes (GSIs)
+ * - Implement pagination
+ * - Control result ordering
+ * - Project specific attributes
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Forward and reverse sorting
+ *
+ * @example
+ * ```ts
+ * // Simple query
+ * const result = await new QueryBuilder(executor, eq('userId', '123'))
+ *   .execute();
+ *
+ * // Complex query with GSI and filtering
+ * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
+ *   .useIndex('status-index')
+ *   .filter(op => op.beginsWith('name', 'John'))
+ *   .select(['id', 'name', 'email'])
+ *   .sortDescending()
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Query with pagination
+ * const paginator = new QueryBuilder(executor, eq('type', 'order'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being queried
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+/**
+ * Builder for creating DynamoDB query operations.
+ * Use this builder when you need to:
+ * - Find dinosaurs by species or status
+ * - Search habitats by type or region
+ * - List incidents by date range
+ * - Retrieve feeding schedules
+ *
+ * The builder supports:
+ * - Complex filtering conditions
+ * - Sorting and pagination
+ * - Global Secondary Indexes
+ * - Attribute projection
+ *
+ * @example
+ * ```typescript
+ * // Find active carnivores
+ * const result = await new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .execute();
+ *
+ * // Search habitats by security level
+ * const result = await new QueryBuilder(executor, eq('type', 'CARNIVORE'))
+ *   .useIndex('security-level-index')
+ *   .filter(op => op.gt('securityLevel', 8))
+ *   .select(['id', 'capacity', 'currentOccupants'])
+ *   .sortDescending()
+ *   .execute();
+ *
+ * // List recent incidents
+ * const result = await new QueryBuilder(executor, eq('type', 'INCIDENT'))
+ *   .useIndex('date-index')
+ *   .filter(op => op.gt('severityLevel', 5))
+ *   .paginate(10);
+ * ```
+ *
+ * @typeParam T - The type of items being queried
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> {
+    private readonly keyCondition;
+    private options;
+    private selectedFields;
+    private readonly executor;
+    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
+    /**
+     * Sets the maximum number of items to return from the query.
+     * Use this method when you need to:
+     * - Limit the result set size
+     * - Implement manual pagination
+     * - Control data transfer size
+     *
+     * Note: This limit applies to the items that match the key condition
+     * before any filter expressions are applied.
+     *
+     * @example
+     * ```ts
+     * // Get first 10 orders for a user
+     * const result = await new QueryBuilder(executor, eq('userId', '123'))
+     *   .limit(10)
+     *   .execute();
+     * ```
+     *
+     * @param limit - Maximum number of items to return
+     * @returns The builder instance for method chaining
+     */
+    limit(limit: number): QueryBuilder<T>;
+    /**
+     * Gets the current limit set on the query.
+     * This is used internally by the paginator to manage result sets.
+     *
+     * @returns The current limit or undefined if no limit is set
+     */
+    getLimit(): number | undefined;
+    /**
+     * Specifies a Global Secondary Index (GSI) to use for the query.
+     * Use this method when you need to:
+     * - Query data using non-primary key attributes
+     * - Access data through alternate access patterns
+     * - Optimize query performance for specific access patterns
+     *
+     * This method provides type safety by only allowing valid GSI names
+     * defined in your table configuration.
+     *
+     * @example
+     * ```ts
+     * // Query by status using a GSI
+     * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
+     *   .useIndex('status-index')
+     *   .execute();
+     *
+     * // Query by category and date range
+     * const result = await new QueryBuilder(executor, eq('category', 'books'))
+     *   .useIndex('category-date-index')
+     *   .filter(op => op.between('date', startDate, endDate))
+     *   .execute();
+     * ```
+     *
+     * Note: Be aware that GSIs:
+     * - May have different projected attributes
+     * - Have eventually consistent reads only
+     * - May have different provisioned throughput
+     *
+     * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Specifies a Global Secondary Index (GSI) to use for the query.
+     * Use this method when you need to:
+     * - Query dinosaurs by species or status
+     * - Search habitats by security level
+     * - Find incidents by date
+     * - List feeding schedules by time
+     *
+     * @example
+     * ```typescript
+     * // Find all dinosaurs of a specific species
+     * builder
+     *   .useIndex('species-status-index')
+     *   .filter(op => op.eq('status', 'ACTIVE'));
+     *
+     * // Search high-security habitats
+     * builder
+     *   .useIndex('security-level-index')
+     *   .filter(op =>
+     *     op.and([
+     *       op.gt('securityLevel', 8),
+     *       op.eq('status', 'OPERATIONAL')
+     *     ])
+     *   );
+     * ```
+     *
+     * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+     * @returns The builder instance for method chaining
+     */
+    useIndex<I extends GSINames<TConfig>>(indexName: I): QueryBuilder<T, TConfig>;
+    /**
+     * Sets whether to use strongly consistent reads for the query.
+     * Use this method when you need to:
+     * - Get real-time dinosaur status updates
+     * - Monitor critical security systems
+     * - Track immediate habitat changes
+     * - Verify containment protocols
+     *
+     * Note:
+     * - Consistent reads are not available on GSIs
+     * - Consistent reads consume twice the throughput
+     * - Default is eventually consistent reads
+     *
+     * @example
+     * ```ts
+     * // Check immediate dinosaur status
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .consistentRead()
+     *   .execute();
+     *
+     * // Monitor security breaches
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_ALERT'))
+     *   .useIndex('primary-index')
+     *   .consistentRead(isEmergencyMode)
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): QueryBuilder<T>;
+    /**
+     * Adds a filter expression to the query.
+     * Use this method when you need to:
+     * - Filter results based on non-key attributes
+     * - Apply complex filtering conditions
+     * - Combine multiple filter conditions
+     *
+     * Note: Filter expressions are applied after the key condition,
+     * so they don't reduce the amount of data read from DynamoDB.
+     *
+     * @example
+     * ```ts
+     * // Simple filter
+     * builder.filter(op => op.eq('status', 'ACTIVE'))
+     *
+     * // Complex filter with multiple conditions
+     * builder.filter(op =>
+     *   op.and([
+     *     op.gt('amount', 1000),
+     *     op.beginsWith('category', 'ELECTRONICS'),
+     *     op.attributeExists('reviewDate')
+     *   ])
+     * )
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Adds a filter expression to refine the query results.
+     * Use this method when you need to:
+     * - Filter dinosaurs by behavior patterns
+     * - Find habitats with specific conditions
+     * - Search for security incidents
+     * - Monitor feeding patterns
+     *
+     * @example
+     * ```typescript
+     * // Find aggressive carnivores
+     * builder.filter(op =>
+     *   op.and([
+     *     op.eq('diet', 'CARNIVORE'),
+     *     op.gt('aggressionLevel', 7),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * );
+     *
+     * // Search suitable breeding habitats
+     * builder.filter(op =>
+     *   op.and([
+     *     op.between('temperature', 25, 30),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('quarantineStatus', 'CLEAR')
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    filter(condition: Condition | ((op: ConditionOperator<T>) => Condition)): QueryBuilder<T>;
+    /**
+     * Specifies which attributes to return in the query results.
+     * Use this method when you need to:
+     * - Reduce data transfer by selecting specific attributes
+     * - Optimize response size
+     * - Focus on relevant attributes only
+     *
+     * Note: Using projection can significantly reduce the amount
+     * of data returned and lower your costs.
+     *
+     * @example
+     * ```ts
+     * // Select single attribute
+     * builder.select('email')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'name', 'email'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['name', 'email'])
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Specifies which attributes to return in the query results.
+     * Use this method when you need to:
+     * - Get specific dinosaur attributes
+     * - Retrieve habitat statistics
+     * - Monitor security metrics
+     * - Optimize response size
+     *
+     * @example
+     * ```typescript
+     * // Get basic dinosaur info
+     * builder.select([
+     *   'species',
+     *   'status',
+     *   'stats.health',
+     *   'stats.aggressionLevel'
+     * ]);
+     *
+     * // Monitor habitat conditions
+     * builder
+     *   .select('securityStatus')
+     *   .select([
+     *     'currentOccupants',
+     *     'temperature',
+     *     'lastInspectionDate'
+     *   ]);
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select(fields: string | string[]): QueryBuilder<T>;
+    /**
+     * Sets the query to return items in ascending order by sort key.
+     * Use this method when you need to:
+     * - Retrieve items in natural order (e.g., timestamps, versions)
+     * - Implement chronological ordering
+     * - Get oldest items first
+     *
+     * Note: This is the default behavior if no sort order is specified.
+     *
+     * @example
+     * ```typescript
+     * // Get orders in chronological order
+     * const result = await new QueryBuilder(executor, eq('userId', '123'))
+     *   .sortAscending()
+     *   .execute();
+     *
+     * // Get events from oldest to newest
+     * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
+     *   .useIndex('entity-timestamp-index')
+     *   .sortAscending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Sets the query to return items in ascending order by sort key.
+     * Use this method when you need to:
+     * - List dinosaurs by age (youngest first)
+     * - View incidents chronologically
+     * - Track feeding schedule progression
+     * - Monitor habitat inspections
+     *
+     * @example
+     * ```typescript
+     * // List dinosaurs by age
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('age-index')
+     *   .sortAscending()
+     *   .execute();
+     *
+     * // View incidents chronologically
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .useIndex('date-index')
+     *   .sortAscending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    sortAscending(): QueryBuilder<T>;
+    /**
+     * Sets the query to return items in descending order by sort key.
+     * Use this method when you need to:
+     * - Get most recent security breaches
+     * - Find oldest dinosaurs first
+     * - Check latest habitat modifications
+     * - Monitor recent feeding events
+     *
+     * @example
+     * ```typescript
+     * // Get most recent security incidents
+     * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .useIndex('date-index')
+     *   .sortDescending()
+     *   .limit(10)
+     *   .execute();
+     *
+     * // Check latest dinosaur activities
+     * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('activity-time-index')
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .sortDescending()
+     *   .execute();
+     * ```
+     *
+     * @returns The builder instance for method chaining
+     */
+    sortDescending(): QueryBuilder<T>;
+    /**
+     * Creates a paginator that handles DynamoDB pagination automatically.
+     * Use this method when you need to:
+     * - Browse large dinosaur collections
+     * - View habitat inspection history
+     * - Monitor security incidents
+     * - Track feeding patterns
+     *
+     * The paginator handles:
+     * - Tracking the last evaluated key
+     * - Managing page boundaries
+     * - Respecting overall query limits
+     *
+     * @example
+     * ```typescript
+     * // List dinosaurs by species
+     * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .useIndex('species-index')
+     *   .paginate(10);
+     *
+     * // Process pages of security incidents
+     * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+     *   .filter(op => op.gt('severityLevel', 7))
+     *   .sortDescending()
+     *   .paginate(25);
+     *
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   console.log(`Processing incidents page ${page.page}, count: ${page.items.length}`);
+     *   // Handle security incidents
+     * }
+     * ```
+     *
+     * @param pageSize - The number of items to return per page
+     * @returns A Paginator instance that manages the pagination state
+     * @see Paginator for more pagination control options
+     */
+    paginate(pageSize: number): Paginator<T, TConfig>;
+    /**
+     * Sets the starting point for the query using a previous lastEvaluatedKey.
+     * Use this method when you need to:
+     * - Implement manual dinosaur list pagination
+     * - Resume habitat inspection reviews
+     * - Continue security incident analysis
+     * - Store query position between sessions
+     *
+     * Note: This method is typically used for manual pagination.
+     * For automatic pagination, use the paginate() method instead.
+     *
+     * @example
+     * ```typescript
+     * // First batch of dinosaurs
+     * const result1 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .limit(5)
+     *   .execute();
+     *
+     * if (result1.lastEvaluatedKey) {
+     *   // Continue listing dinosaurs
+     *   const result2 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *     .filter(op => op.eq('status', 'ACTIVE'))
+     *     .startFrom(result1.lastEvaluatedKey)
+     *     .limit(5)
+     *     .execute();
+     *
+     *   console.log('Additional dinosaurs:', result2.items);
+     * }
+     * ```
+     *
+     * @param lastEvaluatedKey - The exclusive start key from a previous query result
+     * @returns The builder instance for method chaining
+     */
+    startFrom(lastEvaluatedKey: Record<string, unknown>): QueryBuilder<T>;
+    /**
+     * Creates a deep clone of this QueryBuilder instance.
+     * Use this method when you need to:
+     * - Query different dinosaur statuses
+     * - Check multiple habitat conditions
+     * - Monitor various security levels
+     * - Create report templates
+     *
+     * This is particularly useful when:
+     * - Implementing pagination (used internally by paginate())
+     * - Creating query templates
+     * - Running multiple variations of a query
+     *
+     * @example
+     * ```typescript
+     * // Create base dinosaur query
+     * const baseQuery = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+     *   .useIndex('status-index')
+     *   .select(['id', 'status', 'location']);
+     *
+     * // Check active dinosaurs
+     * const activeRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'HUNTING'))
+     *   .execute();
+     *
+     * // Check contained dinosaurs
+     * const containedRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
+     *   .execute();
+     *
+     * // Check sedated dinosaurs
+     * const sedatedRaptors = baseQuery.clone()
+     *   .filter(op => op.eq('status', 'SEDATED'))
+     *   .execute();
+     * ```
+     *
+     * @returns A new QueryBuilder instance with the same configuration
+     */
+    clone(): QueryBuilder<T, TConfig>;
+    /**
+     * Executes the query against DynamoDB.
+     * Use this method when you need to:
+     * - Find specific dinosaur groups
+     * - Check habitat conditions
+     * - Monitor security incidents
+     * - Track feeding patterns
+     *
+     * The method returns both the matched items and, if there are more results,
+     * a lastEvaluatedKey that can be used with startFrom() to continue the query.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find active carnivores in specific habitat
+     *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+     *     .useIndex('species-status-index')
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('diet', 'CARNIVORE'),
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .sortDescending()
+     *     .limit(5)
+     *     .execute();
+     *
+     *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
+     *
+     *   if (result.lastEvaluatedKey) {
+     *     console.log('Additional threats detected');
+     *   }
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - items: Array of items matching the query
+     *          - lastEvaluatedKey: Token for continuing the query, if more items exist
+     */
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
     }>;
 }
-type DynamoOperation = DynamoPutOperation | DynamoUpdateOperation | DynamoQueryOperation | DynamoDeleteOperation | DynamoBatchWriteOperation | DynamoTransactOperation | DynamoScanOperation;
-type PrimaryKeyWithoutExpression = {
-    pk: string;
-    sk?: string;
-};
-type BatchWriteOperation = {
-    type: "put";
-    item: Record<string, unknown>;
-} | {
-    type: "delete";
-    key: PrimaryKeyWithoutExpression;
-};
 
-interface DynamoRecord {
+/**
+ * Interface for DynamoDB command objects that can contain expressions
+ */
+interface DynamoCommandWithExpressions {
+    conditionExpression?: string;
+    updateExpression?: string;
+    filterExpression?: string;
+    keyConditionExpression?: string;
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
     [key: string]: unknown;
 }
 
-type StringKeys<T> = Extract<keyof T, string>;
 /**
- * Base builder class for DynamoDB operations that supports condition expressions
- * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
  */
-declare abstract class OperationBuilder<T extends DynamoRecord, TOperation extends DynamoOperation> {
-    protected expressionBuilder: IExpressionBuilder;
-    protected conditions: Array<{
-        field: keyof T;
-        operator: ConditionOperator;
-        value?: unknown;
-    }>;
-    constructor(expressionBuilder: IExpressionBuilder);
-    where<K extends keyof T>(field: K, operator: FilterOperator, value: T[K] | T[K][]): this;
-    whereExists<K extends StringKeys<T>>(field: K): this;
-    whereNotExists<K extends keyof T>(field: K): this;
-    whereEquals<K extends keyof T>(field: K, value: T[K]): this;
-    whereBetween<K extends keyof T>(field: K, start: T[K], end: T[K]): this;
-    whereIn<K extends keyof T>(field: K, values: T[K][]): this;
-    whereLessThan<K extends keyof T>(field: K, value: T[K]): this;
-    whereLessThanOrEqual<K extends keyof T>(field: K, value: T[K]): this;
-    whereGreaterThan<K extends keyof T>(field: K, value: T[K]): this;
-    whereGreaterThanOrEqual<K extends keyof T>(field: K, value: T[K]): this;
-    whereNotEqual<K extends keyof T>(field: K, value: T[K]): this;
-    whereBeginsWith<K extends keyof T>(field: K, value: T[K]): this;
-    whereContains<K extends keyof T>(field: K, value: T[K]): this;
-    whereNotContains<K extends keyof T>(field: K, value: T[K]): this;
-    whereAttributeType<K extends keyof T>(field: K, value: "S" | "SS" | "N" | "NS" | "B" | "BS" | "BOOL" | "NULL" | "M" | "L"): this;
-    whereSize<K extends keyof T>(field: K, value: T[K]): this;
-    protected buildConditionExpression(): ExpressionResult;
-    abstract build(): TOperation;
+interface UpdateCommandParams extends DynamoCommandWithExpressions {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to update */
+    key: PrimaryKeyWithoutExpression;
+    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
+    updateExpression: string;
+    /** Optional condition expression that must be satisfied */
+    conditionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Map of expression attribute value placeholders to actual values */
+    expressionAttributeValues?: Record<string, unknown>;
+    /** Which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
 }
-
-declare class PutBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoPutOperation> {
-    private readonly onBuild;
-    private item;
-    constructor(item: T, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoPutOperation) => Promise<T>);
-    set<K extends keyof T>(field: K, value: T[K]): this;
-    setMany(attributes: Partial<T>): this;
-    build(): DynamoPutOperation;
+/**
+ * Function type for executing DynamoDB update operations.
+ * @typeParam T - The type of the item being updated
+ */
+type UpdateExecutor<T extends Record<string, unknown>> = (params: UpdateCommandParams) => Promise<{
+    item?: T;
+}>;
+/**
+ * Type utility to get the element type of a set.
+ * Extracts the element type from either a Set or Array type.
+ * @typeParam T - The set or array type
+ */
+type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
+/**
+ * Type utility to get the element type from a path that points to a set.
+ * Combines PathType and SetElementType to get the element type at a specific path.
+ * @typeParam T - The type of the item
+ * @typeParam K - The path within the item
+ */
+type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
+/**
+ * Builder for creating DynamoDB update operations.
+ * Use this builder when you need to:
+ * - Modify existing items in DynamoDB
+ * - Update multiple attributes atomically
+ * - Perform conditional updates
+ * - Work with nested attributes
+ * - Update sets and lists
+ *
+ * The builder supports all DynamoDB update operations:
+ * - SET: Modify or add attributes
+ * - REMOVE: Delete attributes
+ * - ADD: Update numbers and sets
+ * - DELETE: Remove elements from a set
+ *
+ * @example
+ * ```typescript
+ * // Simple update
+ * const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .set('status', 'HUNTING')
+ *   .set('lastFed', new Date().toISOString())
+ *   .execute();
+ *
+ * // Complex update with multiple operations
+ * const result = await new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+ *   .set({
+ *     status: 'OCCUPIED',
+ *     occupants: 3,
+ *     'metadata.lastInspection': new Date().toISOString()
+ *   })
+ *   .add('securityBreaches', 1)
+ *   .deleteElementsFromSet('suitableDinosaurs', ['VELOCIRAPTOR'])
+ *   .condition(op => op.gt('securityLevel', 8))
+ *   .returnValues('ALL_NEW')
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being updated
+ */
+declare class UpdateBuilder<T extends Record<string, unknown>> {
+    private updates;
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    private readonly key;
+    constructor(executor: UpdateExecutor<T>, tableName: string, key: PrimaryKeyWithoutExpression);
     /**
-     * Runs the put operation to insert the provided attributes into the table.
+     * Sets multiple attributes of an item using an object.
+     * Use this method when you need to:
+     * - Update multiple attributes at once
+     * - Set nested attribute values
+     * - Modify complex data structures
      *
-     * @returns The provided attributes. This does not load the model from the DB after insert
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
      */
-    execute(): Promise<T>;
-}
-
-interface DynamoQueryResponse {
-    Items?: Record<string, unknown>[];
-    Count?: number;
-    ScannedCount?: number;
-    LastEvaluatedKey?: Record<string, unknown>;
+    set(values: Partial<T>): UpdateBuilder<T>;
+    /**
+     * Sets a single attribute to a specific value.
+     * Use this method when you need to:
+     * - Update one attribute at a time
+     * - Set values with type safety
+     * - Update nested attributes
+     *
+     * @example
+     * ```typescript
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
+     *
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
+     */
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
+    /**
+     * Removes an attribute from the item.
+     * Use this method when you need to:
+     * - Delete attributes completely
+     * - Remove nested attributes
+     * - Clean up deprecated fields
+     *
+     * @example
+     * ```typescript
+     * // Remove simple attributes
+     * builder
+     *   .remove('temporaryTag')
+     *   .remove('previousLocation');
+     *
+     * // Remove nested attributes
+     * builder
+     *   .remove('metadata.testData')
+     *   .remove('stats.experimentalMetrics');
+     * ```
+     *
+     * @param path - The path to the attribute to remove
+     * @returns The builder instance for method chaining
+     */
+    remove<K extends Path<T>>(path: K): UpdateBuilder<T>;
+    /**
+     * Adds a value to a number attribute or adds elements to a set.
+     * Use this method when you need to:
+     * - Increment counters
+     * - Add elements to a set atomically
+     * - Update numerical statistics
+     *
+     * @example
+     * ```typescript
+     * // Increment counters
+     * builder
+     *   .add('escapeAttempts', 1)
+     *   .add('feedingCount', 1);
+     *
+     * // Add to sets
+     * builder
+     *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
+     *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
+     * ```
+     *
+     * @param path - The path to the attribute to update
+     * @param value - The value to add (number or set)
+     * @returns The builder instance for method chaining
+     */
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): UpdateBuilder<T>;
+    /**
+     * Removes elements from a set attribute.
+     * Use this method when you need to:
+     * - Remove specific elements from a set
+     * - Update set-based attributes atomically
+     * - Maintain set membership
+     *
+     * @example
+     * ```typescript
+     * // Remove from sets using arrays
+     * builder.deleteElementsFromSet(
+     *   'allowedHabitats',
+     *   ['JUNGLE', 'COASTAL']
+     * );
+     *
+     * // Remove from sets using Set objects
+     * builder.deleteElementsFromSet(
+     *   'knownBehaviors',
+     *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+     * );
+     *
+     * // Remove from nested sets
+     * builder.deleteElementsFromSet(
+     *   'stats.compatibleSpecies',
+     *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+     * );
+     * ```
+     *
+     * @param path - The path to the set attribute
+     * @param value - Elements to remove (array or Set)
+     * @returns The builder instance for method chaining
+     */
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): UpdateBuilder<T>;
+    /**
+     * Adds a condition that must be satisfied for the update to succeed.
+     * Use this method when you need to:
+     * - Implement optimistic locking
+     * - Ensure item state before update
+     * - Validate business rules
+     * - Prevent concurrent modifications
+     *
+     * @example
+     * ```typescript
+     * // Simple condition
+     * builder.condition(op =>
+     *   op.eq('status', 'ACTIVE')
+     * );
+     *
+     * // Health check condition
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('health', 50),
+     *     op.eq('status', 'HUNTING')
+     *   ])
+     * );
+     *
+     * // Complex security condition
+     * builder.condition(op =>
+     *   op.and([
+     *     op.attributeExists('securitySystem'),
+     *     op.eq('containmentStatus', 'SECURE'),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
+     * );
+     *
+     * // Version check (optimistic locking)
+     * builder.condition(op =>
+     *   op.eq('version', currentVersion)
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): UpdateBuilder<T>;
+    /**
+     * Sets which item attributes to include in the response.
+     * Use this method when you need to:
+     * - Get the complete updated item
+     * - Track changes to specific attributes
+     * - Compare old and new values
+     * - Monitor attribute modifications
+     *
+     * Available options:
+     * - ALL_NEW: All attributes after the update
+     * - UPDATED_NEW: Only updated attributes, new values
+     * - ALL_OLD: All attributes before the update
+     * - UPDATED_OLD: Only updated attributes, old values
+     * - NONE: No attributes returned (default)
+     *
+     * @example
+     * ```typescript
+     * // Get complete updated dinosaur
+     * const result = await builder
+     *   .set('status', 'SLEEPING')
+     *   .returnValues('ALL_NEW')
+     *   .execute();
+     *
+     * // Track specific attribute changes
+     * const result = await builder
+     *   .set({
+     *     'stats.health': 100,
+     *     'stats.energy': 95
+     *   })
+     *   .returnValues('UPDATED_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Previous health:', result.item.stats?.health);
+     * }
+     * ```
+     *
+     * @param returnValues - Which attributes to return in the response
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): UpdateBuilder<T>;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    toDynamoCommand(): UpdateCommandParams;
+    /**
+     * Adds this update operation to a transaction.
+     * Use this method when you need to:
+     * - Update items as part of a larger transaction
+     * - Ensure multiple updates are atomic
+     * - Coordinate updates across multiple items
+     *
+     * @example
+     * ```typescript
+     * const transaction = new TransactionBuilder(executor);
+     *
+     * // Update dinosaur status and habitat occupancy atomically
+     * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .set('location', 'PADDOCK_A')
+     *   .set('status', 'CONTAINED')
+     *   .withTransaction(transaction);
+     *
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', 1)
+     *   .set('lastOccupied', new Date().toISOString())
+     *   .withTransaction(transaction);
+     *
+     * // Execute all operations atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): void;
+    /**
+     * Gets a human-readable representation of the update command.
+     * Use this method when you need to:
+     * - Debug complex update expressions
+     * - Verify attribute names and values
+     * - Log update operations
+     * - Troubleshoot condition expressions
+     *
+     * @example
+     * ```typescript
+     * // Create complex update
+     * const builder = new UpdateBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .set({
+     *     status: 'HUNTING',
+     *     'stats.health': 95,
+     *     'behavior.lastObserved': new Date().toISOString()
+     *   })
+     *   .add('huntingSuccesses', 1)
+     *   .condition(op => op.gt('health', 50));
+     *
+     * // Debug the update
+     * const debugInfo = builder.debug();
+     * console.log('Update operation:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the update command with resolved expressions
+     */
+    debug(): Record<string, unknown>;
+    /**
+     * Executes the update operation against DynamoDB.
+     * Use this method when you need to:
+     * - Apply updates immediately
+     * - Get the updated item values
+     * - Handle conditional update failures
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Update dinosaur status with conditions
+     *   const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *     .set({
+     *       status: 'FEEDING',
+     *       lastMeal: new Date().toISOString(),
+     *       'stats.hunger': 0
+     *     })
+     *     .add('feedingCount', 1)
+     *     .condition(op =>
+     *       op.and([
+     *         op.gt('stats.hunger', 80),
+     *         op.eq('status', 'HUNTING')
+     *       ])
+     *     )
+     *     .returnValues('ALL_NEW')
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Updated dinosaur:', result.item);
+     *   }
+     * } catch (error) {
+     *   // Handle condition check failure
+     *   console.error('Failed to update dinosaur:', error);
+     *   // Check if dinosaur wasn't hungry enough
+     *   if (error.name === 'ConditionalCheckFailedException') {
+     *     console.log('Dinosaur not ready for feeding');
+     *   }
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing the updated item (if returnValues is set)
+     * @throws {ConditionalCheckFailedException} If the condition check fails
+     * @throws {Error} If the update operation fails for other reasons
+     */
+    execute(): Promise<{
+        item?: T;
+    }>;
 }
 
-declare class QueryBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoQueryOperation> {
-    private readonly key;
-    private readonly indexConfig;
-    private readonly onBuild;
-    private limitValue?;
-    private indexNameValue?;
-    constructor(key: PrimaryKey, indexConfig: TableIndexConfig, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoQueryOperation) => Promise<DynamoQueryResponse>);
-    limit(value: number): this;
-    useIndex(indexName: string): this;
-    build(): DynamoQueryOperation;
-    execute(): Promise<DynamoQueryResponse>;
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: PrimaryKeyWithoutExpression;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD";
 }
-
-declare class UpdateBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoUpdateOperation> {
+type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
+    item?: Record<string, unknown>;
+}>;
+/**
+ * Builder for creating DynamoDB delete operations.
+ * Use this builder when you need to:
+ * - Delete items from a DynamoDB table
+ * - Conditionally delete items based on attribute values
+ * - Delete items as part of a transaction
+ * - Retrieve the old item values after deletion
+ *
+ * @example
+ * ```ts
+ * const result = await new DeleteBuilder(executor, 'myTable', { id: '123' })
+ *   .condition(op => op.attributeExists('status'))
+ *   .returnValues('ALL_OLD')
+ *   .execute();
+ * ```
+ */
+/**
+ * Builder for creating DynamoDB delete operations.
+ * Use this builder when you need to:
+ * - Remove dinosaurs from the registry
+ * - Clean up abandoned habitats
+ * - Delete historical tracking data
+ * - Remove deprecated classifications
+ *
+ * @example
+ * ```typescript
+ * // Simple delete
+ * const result = await new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+ *   .execute();
+ *
+ * // Conditional delete with old value retrieval
+ * const result = await new DeleteBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'DECOMMISSIONED'),
+ *       op.eq('occupants', 0),
+ *       op.lt('securityIncidents', 1)
+ *     ])
+ *   )
+ *   .returnValues('ALL_OLD')
+ *   .execute();
+ * ```
+ */
+declare class DeleteBuilder {
+    private options;
+    private readonly executor;
+    private readonly tableName;
     private readonly key;
-    private readonly onBuild;
-    private updates;
-    constructor(key: PrimaryKeyWithoutExpression, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoUpdateOperation) => Promise<{
-        Attributes?: T;
-    }>);
-    set<K extends keyof T>(field: K, value: T[K]): this;
-    setMany(attributes: Partial<T>): this;
-    remove(...fields: Array<keyof T>): this;
-    increment<K extends keyof T>(field: K, by?: number): this;
-    build(): DynamoUpdateOperation;
+    constructor(executor: DeleteExecutor, tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Adds a condition that must be satisfied for the delete operation to succeed.
+     * Use this method when you need to:
+     * - Implement optimistic locking (e.g., version check)
+     * - Ensure item exists before deletion
+     * - Validate item state before deletion
+     *
+     * @example
+     * ```ts
+     * // Simple condition
+     * builder.condition(op => op.attributeExists('id'))
+     *
+     * // Complex condition with version check
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('version', 1),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * )
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Adds a condition that must be satisfied for the delete operation to succeed.
+     * Use this method when you need to:
+     * - Ensure safe removal conditions
+     * - Verify habitat status before deletion
+     * - Implement safety protocols
+     *
+     * @example
+     * ```typescript
+     * // Ensure dinosaur can be safely removed
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.attributeExists('lastCheckup')
+     *   ])
+     * );
+     *
+     * // Verify habitat is empty
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('occupants', 0),
+     *     op.eq('maintenanceStatus', 'COMPLETE'),
+     *     op.not(op.attributeExists('activeAlerts'))
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): DeleteBuilder;
+    /**
+     * Sets whether to return the item's attribute values before deletion.
+     * Use this method when you need to:
+     * - Archive removed dinosaur data
+     * - Track habitat decommissioning history
+     * - Maintain removal audit logs
+     *
+     * @example
+     * ```ts
+     * // Archive dinosaur data before removal
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Removed dinosaur data:', {
+     *     species: result.item.species,
+     *     age: result.item.age,
+     *     lastLocation: result.item.location
+     *   });
+     * }
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return all attributes of the deleted item
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD"): DeleteBuilder;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this delete operation to a transaction.
+     * Use this method when you need to:
+     * - Coordinate dinosaur transfers
+     * - Manage habitat decommissioning
+     * - Handle species relocations
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Remove dinosaur from old habitat
+     * new DeleteBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+     *   .condition(op => op.eq('status', 'SEDATED'))
+     *   .withTransaction(transaction);
+     *
+     * // Update old habitat occupancy
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+     *   .add('occupants', -1)
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     */
+    withTransaction(transaction: TransactionBuilder): void;
+    /**
+     * Executes the delete operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * // Delete with condition and retrieve old values
+     * const result = await new DeleteBuilder(executor, 'myTable', { id: '123' })
+     *   .condition(op => op.eq('status', 'INACTIVE'))
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result.item) {
+     *   console.log('Deleted item:', result.item);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
+     */
     execute(): Promise<{
-        Attributes?: T;
+        item?: Record<string, unknown>;
     }>;
+    /**
+     * Gets a human-readable representation of the delete command
+     * with all expression placeholders replaced by their actual values.
+     * Use this method when you need to:
+     * - Debug complex deletion conditions
+     * - Verify safety checks
+     * - Log removal operations
+     * - Troubleshoot failed deletions
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.eq('status', 'SEDATED'),
+     *     op.eq('location', 'MEDICAL_BAY'),
+     *     op.gt('sedationLevel', 8)
+     *     op.eq('version', 1),
+     *     op.attributeExists('status')
+     *   ]))
+     *   .debug();
+     *
+     * console.log('Delete command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the delete command with resolved expressions
+     */
+    debug(): Record<string, unknown>;
 }
 
-declare class ScanBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoScanOperation> {
-    private readonly onBuild;
-    private limitValue?;
-    private indexNameValue?;
-    private pageKeyValue?;
-    constructor(expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoScanOperation) => Promise<DynamoQueryResponse>);
-    limit(value: number): this;
-    useIndex(indexName: string): this;
-    startKey(key: Record<string, unknown>): this;
-    build(): {
-        type: "scan";
-        filter: {
-            expression: string;
-            names: Record<string, string> | undefined;
-            values: Record<string, unknown> | undefined;
-        } | undefined;
-        limit: number | undefined;
-        pageKey: Record<string, unknown> | undefined;
-        indexName: string | undefined;
-    };
-    execute(): Promise<DynamoQueryResponse>;
-}
-
-type IndexConfig = Record<string, TableIndexConfig> & {
-    primary: TableIndexConfig;
-};
-declare class Table {
-    private readonly dynamoService;
-    private readonly expressionBuilder;
-    private readonly indexes;
-    constructor({ client, tableName, tableIndexes, expressionBuilder, }: {
-        client: DynamoDBDocument;
-        tableName: string;
-        tableIndexes: IndexConfig;
-        expressionBuilder?: ExpressionBuilder;
-    });
-    getIndexConfig(indexName?: string): TableIndexConfig;
-    put<T extends DynamoRecord>(item: T): PutBuilder<T>;
-    update<T extends DynamoRecord>(key: PrimaryKeyWithoutExpression, data?: Partial<T>): UpdateBuilder<T>;
-    query<T extends DynamoRecord>(key: PrimaryKey): QueryBuilder<T>;
-    get(key: PrimaryKeyWithoutExpression, options?: {
-        indexName?: string;
-    }): Promise<Record<string, any> | undefined>;
-    delete(key: PrimaryKeyWithoutExpression): Promise<unknown>;
-    scan<T extends DynamoRecord>(): ScanBuilder<T>;
-    batchWrite(operations: BatchWriteOperation[]): Promise<unknown>;
-    transactWrite(operations: Array<{
-        put?: {
-            item: Record<string, unknown>;
-            condition?: {
-                expression: string;
-                names?: Record<string, string>;
-                values?: Record<string, unknown>;
-            };
-        };
-        delete?: {
-            key: PrimaryKeyWithoutExpression;
-            condition?: {
-                expression: string;
-                names?: Record<string, string>;
-                values?: Record<string, unknown>;
-            };
-        };
-        update?: {
-            key: PrimaryKeyWithoutExpression;
-            update: {
-                expression: string;
-                names?: Record<string, string>;
-                values?: Record<string, unknown>;
-            };
-            condition?: {
-                expression: string;
-                names?: Record<string, string>;
-                values?: Record<string, unknown>;
-            };
-        };
-    }>): Promise<unknown>;
-    private executeOperation;
-    private buildKeyFromIndex;
-    private validateKey;
+interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: PrimaryKeyWithoutExpression;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
 }
-
-declare abstract class BaseRepository<TData extends DynamoRecord> {
-    protected readonly table: Table;
-    constructor(table: Table);
+/**
+ * Builder for creating DynamoDB condition check operations.
+ * Use this builder when you need to:
+ * - Verify item state without modifying it
+ * - Ensure preconditions in transactions
+ * - Implement optimistic locking patterns
+ * - Validate business rules
+ *
+ * @example
+ * ```typescript
+ * // Check if dinosaur is ready for feeding
+ * const check = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'HUNTING'),
+ *       op.gt('stats.hunger', 80),
+ *       op.lt('stats.health', 100)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ *
+ * // Check habitat security status
+ * const securityCheck = new ConditionCheckBuilder('habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('securityStatus', 'ACTIVE'),
+ *       op.attributeExists('lastInspection'),
+ *       op.lt('threatLevel', 5)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ * ```
+ */
+declare class ConditionCheckBuilder {
+    private readonly key;
+    private readonly tableName;
+    private conditionExpression?;
+    constructor(tableName: string, key: PrimaryKeyWithoutExpression);
     /**
-     * Templates out the primary key for the record, it is consumed for create, put, update and delete actions
+     * Adds a condition that must be satisfied for the check to succeed.
+     * Use this method when you need to:
+     * - Validate complex item states
+     * - Check multiple attributes together
+     * - Ensure safety conditions are met
+     *
+     * @example
+     * ```typescript
+     * // Check dinosaur health and behavior
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('stats.health', 50),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
+     * );
      *
-     * Unfortunately, TypeScript is not inferring the TData type when implmenting this method in a subclass.
-     * https://github.com/microsoft/TypeScript/issues/32082
+     * // Verify habitat conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('powerStatus', 'ONLINE'),
+     *     op.between('temperature', 20, 30),
+     *     op.attributeExists('lastMaintenance')
+     *   ])
+     * );
+     *
+     * // Check breeding conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('species', 'VELOCIRAPTOR'),
+     *     op.gte('age', 3),
+     *     op.eq('geneticPurity', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
      */
-    protected abstract createPrimaryKey(data: TData): PrimaryKeyWithoutExpression;
+    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): ConditionCheckBuilder;
     /**
-     * Default attribute applied to ALL records that get stored in DDB
-     * Defines the type of the record.
-     * For example User, Post, Comment etc.
+     * Generates the DynamoDB command parameters for direct execution.
+     * Use this method when you want to:
+     * - Execute the condition check as a standalone operation
+     * - Get the raw DynamoDB command for custom execution
+     * - Inspect the generated command parameters
      *
-     * This helps to ensure isolation of models when using a single table design
-     * @returns The type of the record as a string.
+     * @example
+     * ```ts
+     * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+     *   .condition(op => op.attributeExists('status'))
+     *   .toDynamoCommand();
+     * // Use command with DynamoDB client
+     * ```
+     *
+     * @throws {Error} If no condition has been set
+     * @returns The DynamoDB command parameters
      */
-    protected abstract getType(): string;
+    private toDynamoCommand;
     /**
-     * Used to define the attribute name for the type.
-     * @returns The type attribute name as a string.
+     * Adds this condition check operation to a transaction.
+     * Use this method when you need to:
+     * - Verify habitat safety before transfers
+     * - Ensure proper feeding conditions
+     * - Validate security protocols
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+     *   .condition(op => op.and([
+     *     op.eq('securityStatus', 'ACTIVE'),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('habitatType', 'CARNIVORE')
+     *   ]))
+     *   .withTransaction(transaction);
+     * // Add dinosaur transfer operations
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @throws {Error} If no condition has been set
+     * @returns The builder instance for method chaining
      */
-    protected abstract getTypeAttributeName(): string;
+    withTransaction(transaction: TransactionBuilder): ConditionCheckBuilder;
     /**
-     * Hook method called before inserting a record.
-     * Subclasses can override this method to modify the data before insertion.
-     * @param data - The record data.
-     * @returns The modified record data.
+     * Gets a human-readable representation of the condition check command
+     * with all expression placeholders replaced by their actual values.
+     * Use this method when you need to:
+     * - Debug complex condition expressions
+     * - Verify condition parameters
+     * - Log safety checks
+     * - Troubleshoot condition failures
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.between('stats.health', 50, 100),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.attributeExists('lastFeedingTime')
+     *     op.eq('version', 1)
+     *   ]))
+     *   .debug();
+     * console.log(debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the condition check command with resolved expressions
      */
-    protected beforeInsert(data: TData): TData;
+    debug(): Record<string, unknown>;
+}
+
+/**
+ * Configuration options for DynamoDB transactions.
+ */
+interface TransactionOptions {
+    /** Unique identifier for the transaction request (idempotency token) */
+    clientRequestToken?: string;
+    /** Level of consumed capacity details to return */
+    returnConsumedCapacity?: "INDEXES" | "TOTAL" | "NONE";
+    /** Whether to return item collection metrics */
+    returnItemCollectionMetrics?: "SIZE" | "NONE";
+}
+/**
+ * Configuration for table indexes used in duplicate detection.
+ * Defines the key structure for checking uniqueness constraints.
+ */
+interface IndexConfig {
+    /** The partition key attribute name */
+    partitionKey: string;
+    /** Optional sort key attribute name */
+    sortKey?: string;
+}
+/**
+ * Function type for executing DynamoDB transaction operations.
+ * @param params - The complete transaction command input
+ * @returns A promise that resolves when the transaction completes
+ */
+type TransactionExecutor = (params: TransactWriteCommandInput) => Promise<void>;
+/**
+ * Builder for creating and executing DynamoDB transactions.
+ * Use this builder when you need to:
+ * - Perform multiple operations atomically
+ * - Ensure data consistency across operations
+ * - Implement complex business logic that requires atomic updates
+ * - Prevent duplicate items across tables
+ *
+ * The builder supports:
+ * - Put operations (insert/replace items)
+ * - Delete operations
+ * - Update operations
+ * - Condition checks
+ * - Duplicate detection
+ * - Transaction-wide options
+ *
+ * @example
+ * ```typescript
+ * // Create a transaction with multiple operations
+ * const transaction = new TransactionBuilder(executor, {
+ *   partitionKey: 'id',
+ *   sortKey: 'type'
+ * });
+ *
+ * // Add a new order
+ * transaction.put('orders', {
+ *   orderId: '123',
+ *   status: 'PENDING'
+ * });
+ *
+ * // Update inventory with condition
+ * transaction.update(
+ *   'inventory',
+ *   { productId: 'ABC' },
+ *   'set quantity = quantity - :amount',
+ *   { ':amount': 1 },
+ *   op => op.gte('quantity', 1)
+ * );
+ *
+ * // Execute the transaction atomically
+ * await transaction.execute();
+ * ```
+ *
+ * Note: DynamoDB transactions have some limitations:
+ * - Maximum 25 operations per transaction
+ * - All operations must be in the same AWS region
+ * - Cannot include table scans or queries
+ */
+declare class TransactionBuilder {
+    private items;
+    private options;
+    private indexConfig;
+    private readonly executor;
+    constructor(executor: TransactionExecutor, indexConfig: IndexConfig);
     /**
-     * Hook method called before updating a record.
-     * Subclasses can override this method to modify the data before updating.
-     * @param data - The partial record data to be updated.
-     * @returns The modified partial record data.
+     * Checks if an item with the same primary key already exists in the transaction
+     * @private
      */
-    protected beforeUpdate(data: Partial<TData>): Partial<TData>;
+    private checkForDuplicateItem;
     /**
-     * Checks if a record exists in the table.
-     * @param key - The primary key of the record.
-     * @returns A promise that resolves to true if the record exists, false otherwise.
+     * Adds a put operation to the transaction.
+     * Use this method when you need to:
+     * - Insert new items as part of a transaction
+     * - Replace existing items atomically
+     * - Ensure items meet certain conditions before insertion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple put operation
+     * transaction.put('orders', {
+     *   orderId: '123',
+     *   status: 'PENDING',
+     *   amount: 100
+     * });
+     *
+     * // Conditional put operation
+     * transaction.put(
+     *   'inventory',
+     *   { productId: 'ABC', quantity: 50 },
+     *   op => op.attributeNotExists('productId')
+     * );
+     *
+     * // Put with complex condition
+     * transaction.put(
+     *   'users',
+     *   { userId: '123', status: 'ACTIVE' },
+     *   op => op.and([
+     *     op.attributeNotExists('userId'),
+     *     op.beginsWith('status', 'ACTIVE')
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param item - The item to put into the table
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
      */
-    exists(key: PrimaryKeyWithoutExpression): Promise<boolean>;
+    put<T extends Record<string, unknown>>(tableName: string, item: T, condition?: Condition): TransactionBuilder;
     /**
-     * Type guard to check if the value is a primary key.
-     * @param value - The value to check.
-     * @returns True if the value is a primary key, false otherwise.
+     * Adds a pre-configured put operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse put commands from PutBuilder
+     * - Add complex put operations with pre-configured parameters
+     * - Integrate with existing put command configurations
+     *
+     * This method is particularly useful when working with PutBuilder
+     * to maintain consistency in put operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a put command with PutBuilder
+     * const putCommand = new PutBuilder(executor, newItem, 'users')
+     *   .condition(op => op.attributeNotExists('userId'))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.putWithCommand(putCommand);
+     * ```
+     *
+     * @param command - The complete put command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see PutBuilder for creating put commands
      */
-    protected isPrimaryKey(value: PrimaryKeyWithoutExpression | TData): value is PrimaryKeyWithoutExpression;
+    putWithCommand(command: PutCommandParams): TransactionBuilder;
     /**
-     * Creates a new record in the table.
-     * @param data - The record data.
-     * @returns A PutBuilder instance to execute the put operation.
+     * Adds a delete operation to the transaction.
+     * Use this method when you need to:
+     * - Remove items as part of a transaction
+     * - Conditionally delete items
+     * - Ensure items exist before deletion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple delete operation
+     * transaction.delete('orders', {
+     *   pk: 'ORDER#123',
+     *   sk: 'METADATA'
+     * });
+     *
+     * // Conditional delete operation
+     * transaction.delete(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.eq('status', 'INACTIVE')
+     * );
+     *
+     * // Delete with complex condition
+     * transaction.delete(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.eq('status', 'DRAFT'),
+     *     op.lt('version', 5)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to delete
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    delete(tableName: string, key: PrimaryKeyWithoutExpression, condition?: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured delete operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse delete commands from DeleteBuilder
+     * - Add complex delete operations with pre-configured parameters
+     * - Integrate with existing delete command configurations
+     *
+     * This method is particularly useful when working with DeleteBuilder
+     * to maintain consistency in delete operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a delete command with DeleteBuilder
+     * const deleteCommand = new DeleteBuilder(executor, 'users', { pk: 'USER#123' })
+     *   .condition(op => op.and([
+     *     op.attributeExists('pk'),
+     *     op.eq('status', 'INACTIVE')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.deleteWithCommand(deleteCommand);
+     * ```
+     *
+     * @param command - The complete delete command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see DeleteBuilder for creating delete commands
      */
-    create(data: TData): PutBuilder<TData>;
+    deleteWithCommand(command: DeleteCommandParams): TransactionBuilder;
     /**
-     * Updates an existing record in the table.
-     * @param key - The primary key of the record.
-     * @param updates - The partial record data to be updated.
-     * @returns A promise that resolves to the updated record or null if the record does not exist.
+     * Adds an update operation to the transaction.
+     * Use this method when you need to:
+     * - Modify existing items as part of a transaction
+     * - Update multiple attributes atomically
+     * - Apply conditional updates
+     * - Perform complex attribute manipulations
+     *
+     * The method supports all DynamoDB update expressions:
+     * - SET: Modify or add attributes
+     * - REMOVE: Delete attributes
+     * - ADD: Update numbers and sets
+     * - DELETE: Remove elements from a set
+     *
+     * @example
+     * ```typescript
+     * // Simple update
+     * transaction.update(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   'SET #status = :status',
+     *   { '#status': 'status' },
+     *   { ':status': 'PROCESSING' }
+     * );
+     *
+     * // Complex update with multiple operations
+     * transaction.update(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   'SET #qty = #qty - :amount, #status = :status REMOVE #oldAttr',
+     *   { '#qty': 'quantity', '#status': 'status', '#oldAttr': 'deprecated_field' },
+     *   { ':amount': 1, ':status': 'LOW_STOCK' }
+     * );
+     *
+     * // Conditional update
+     * transaction.update(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   'SET #lastLogin = :now',
+     *   { '#lastLogin': 'lastLoginDate' },
+     *   { ':now': new Date().toISOString() },
+     *   op => op.attributeExists('pk')
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to update
+     * @param updateExpression - The update expression (SET, REMOVE, ADD, DELETE)
+     * @param expressionAttributeNames - Map of attribute name placeholders to actual names
+     * @param expressionAttributeValues - Map of value placeholders to actual values
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    update<T extends Record<string, unknown>>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured update operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse update commands from UpdateBuilder
+     * - Add complex update operations with pre-configured parameters
+     * - Integrate with existing update command configurations
+     *
+     * This method is particularly useful when working with UpdateBuilder
+     * to maintain consistency in update operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create an update command with UpdateBuilder
+     * const updateCommand = new UpdateBuilder(executor, 'inventory', { pk: 'PROD#ABC' })
+     *   .set('quantity', ':qty')
+     *   .set('lastUpdated', ':now')
+     *   .values({
+     *     ':qty': 100,
+     *     ':now': new Date().toISOString()
+     *   })
+     *   .condition(op => op.gt('quantity', 0))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.updateWithCommand(updateCommand);
+     * ```
+     *
+     * @param command - The complete update command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see UpdateBuilder for creating update commands
      */
-    update(key: PrimaryKeyWithoutExpression, updates: Partial<TData>): Promise<TData | null>;
+    updateWithCommand(command: UpdateCommandParams): TransactionBuilder;
     /**
-     * Upserts (inserts or updates) a record in the table.
-     * @param data - The record data.
-     * @returns A PutBuilder instance to execute the put operation.
+     * Adds a condition check operation to the transaction.
+     * Use this method when you need to:
+     * - Validate item state without modifying it
+     * - Ensure data consistency across tables
+     * - Implement complex business rules
+     * - Verify preconditions for other operations
+     *
+     * Condition checks are particularly useful for:
+     * - Implementing optimistic locking
+     * - Ensuring referential integrity
+     * - Validating business rules atomically
+     *
+     * @example
+     * ```typescript
+     * // Check if order is in correct state
+     * transaction.conditionCheck(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   op => op.eq('status', 'PENDING')
+     * );
+     *
+     * // Complex condition check
+     * transaction.conditionCheck(
+     *   'inventory',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.gt('quantity', 0),
+     *     op.eq('status', 'ACTIVE'),
+     *     op.attributeExists('lastRestockDate')
+     *   ])
+     * );
+     *
+     * // Check with multiple attributes
+     * transaction.conditionCheck(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.or([
+     *     op.eq('status', 'PREMIUM'),
+     *     op.gte('credits', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to check
+     * @param condition - The condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @throws {Error} If condition expression generation fails
      */
-    upsert(data: TData): PutBuilder<TData>;
+    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
     /**
-     * Deletes a record from the table.
-     * @param keyOrDTO - The primary key or the record data.
-     * @returns A promise that resolves when the record is deleted.
+     * Adds a pre-configured condition check operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse condition checks from ConditionCheckBuilder
+     * - Add complex condition checks with pre-configured parameters
+     * - Integrate with existing condition check configurations
+     *
+     * This method is particularly useful when working with ConditionCheckBuilder
+     * to maintain consistency in condition checks across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a condition check with ConditionCheckBuilder
+     * const checkCommand = new ConditionCheckBuilder('inventory', { pk: 'PROD#ABC' })
+     *   .condition(op => op.and([
+     *     op.between('quantity', 10, 100),
+     *     op.beginsWith('category', 'ELECTRONICS'),
+     *     op.attributeExists('lastAuditDate')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.conditionCheckWithCommand(checkCommand);
+     * ```
+     *
+     * @param command - The complete condition check command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see ConditionCheckBuilder for creating condition check commands
      */
-    delete(keyOrDTO: PrimaryKeyWithoutExpression | TData): Promise<void>;
+    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
     /**
-     * Finds a single record by its primary key.
-     * @param key - The primary key of the record.
-     * @returns A promise that resolves to the record or null if the record does not exist.
+     * Sets options for the transaction execution.
+     * Use this method when you need to:
+     * - Enable idempotent transactions
+     * - Track consumed capacity
+     * - Monitor item collection metrics
+     *
+     * @example
+     * ```typescript
+     * // Enable idempotency and capacity tracking
+     * transaction.withOptions({
+     *   clientRequestToken: 'unique-request-id-123',
+     *   returnConsumedCapacity: 'TOTAL'
+     * });
+     *
+     * // Track item collection metrics
+     * transaction.withOptions({
+     *   returnItemCollectionMetrics: 'SIZE'
+     * });
+     * ```
+     *
+     * Note: ClientRequestToken can be used to make transactions idempotent,
+     * ensuring the same transaction is not executed multiple times.
+     *
+     * @param options - Configuration options for the transaction
+     * @returns The transaction builder for method chaining
      */
-    findOne(key: PrimaryKey): Promise<TData | null>;
+    withOptions(options: TransactionOptions): TransactionBuilder;
     /**
-     * Finds a single record by its primary key or throws an error if the record does not exist.
-     * @param key - The primary key of the record.
-     * @returns A promise that resolves to the record.
-     * @throws An error if the record does not exist.
+     * Gets a human-readable representation of the transaction items.
+     * Use this method when you need to:
+     * - Debug complex transactions
+     * - Verify operation parameters
+     * - Log transaction details
+     * - Troubleshoot condition expressions
+     *
+     * The method resolves all expression placeholders with their actual values,
+     * making it easier to understand the transaction's operations.
+     *
+     * @example
+     * ```typescript
+     * // Add multiple operations
+     * transaction
+     *   .put('orders', { orderId: '123', status: 'PENDING' })
+     *   .update('inventory',
+     *     { productId: 'ABC' },
+     *     'SET quantity = quantity - :amount',
+     *     undefined,
+     *     { ':amount': 1 }
+     *   );
+     *
+     * // Debug the transaction
+     * const debugInfo = transaction.debug();
+     * console.log('Transaction operations:', debugInfo);
+     * ```
+     *
+     * @returns An array of readable representations of the transaction items
      */
-    findOrFail(key: PrimaryKeyWithoutExpression): Promise<TData>;
+    debug(): Record<string, unknown>[];
     /**
-     * Creates a query builder for querying records by their primary key.
-     * @param key - The primary key of the record.
-     * @returns A QueryBuilder instance to build and execute the query.
+     * Executes all operations in the transaction atomically.
+     * Use this method when you need to:
+     * - Perform multiple operations atomically
+     * - Ensure all-or-nothing execution
+     * - Maintain data consistency across operations
+     *
+     * The transaction will only succeed if all operations succeed.
+     * If any operation fails, the entire transaction is rolled back.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Build and execute transaction
+     *   await transaction
+     *     .put('orders', newOrder)
+     *     .update('inventory',
+     *       { productId: 'ABC' },
+     *       'SET quantity = quantity - :qty',
+     *       undefined,
+     *       { ':qty': 1 }
+     *     )
+     *     .conditionCheck('products',
+     *       { productId: 'ABC' },
+     *       op => op.eq('status', 'ACTIVE')
+     *     )
+     *     .execute();
+     *
+     *   console.log('Transaction completed successfully');
+     * } catch (error) {
+     *   // Handle transaction failure
+     *   console.error('Transaction failed:', error);
+     * }
+     * ```
+     *
+     * @throws {Error} If no transaction items are specified
+     * @throws {Error} If any operation in the transaction fails
+     * @returns A promise that resolves when the transaction completes
      */
-    query(key: PrimaryKey): QueryBuilder<TData>;
+    execute(): Promise<void>;
 }
 
-interface RetryStrategy {
-    maxAttempts: number;
-    baseDelay: number;
+/**
+ * Parameters for the DynamoDB put command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE";
+}
+type PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;
+/**
+ * Builder for creating DynamoDB put operations.
+ * Use this builder when you need to:
+ * - Insert new items into a DynamoDB table
+ * - Replace existing items completely
+ * - Conditionally put items based on their current state
+ * - Put items as part of a transaction
+ *
+ * The builder supports:
+ * - Conditional puts with complex conditions
+ * - Retrieving old item values
+ * - Transaction integration
+ *
+ * @example
+ * ```ts
+ * // Simple put
+ * const result = await new PutBuilder(executor, { id: '123', status: 'ACTIVE' }, 'myTable')
+ *   .execute();
+ *
+ * // Conditional put with old value retrieval
+ * const result = await new PutBuilder(executor, newItem, 'myTable')
+ *   .condition(op => op.attributeNotExists('id'))
+ *   .returnValues('ALL_OLD')
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being put into the table
+ */
+/**
+ * Builder for creating DynamoDB put operations.
+ * Use this builder when you need to:
+ * - Add new dinosaurs to the registry
+ * - Create new habitats
+ * - Update dinosaur profiles completely
+ * - Initialize tracking records
+ *
+ * @example
+ * ```typescript
+ * // Add new dinosaur
+ * const result = await new PutBuilder(executor, {
+ *   id: 'RAPTOR-001',
+ *   species: 'Velociraptor',
+ *   status: 'ACTIVE',
+ *   stats: {
+ *     health: 100,
+ *     age: 5,
+ *     threatLevel: 8
+ *   }
+ * }, 'dinosaurs').execute();
+ *
+ * // Create new habitat with conditions
+ * const result = await new PutBuilder(executor, {
+ *   id: 'PADDOCK-C',
+ *   type: 'CARNIVORE',
+ *   securityLevel: 'MAXIMUM',
+ *   capacity: 3,
+ *   environmentType: 'TROPICAL'
+ * }, 'habitats')
+ *   .condition(op => op.attributeNotExists('id'))
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being put into the table
+ */
+declare class PutBuilder<T extends Record<string, unknown>> {
+    private readonly item;
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    constructor(executor: PutExecutor<T>, item: T, tableName: string);
     /**
-     * Check if the error should be retried
-     * @param error The error that was thrown
-     * @param attempt The amount of attempts this action has made to run the action
-     * @returns Whether the action should be retried
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     * Use this method when you need to:
+     * - Prevent overwriting existing items (optimistic locking)
+     * - Ensure items meet certain criteria before replacement
+     * - Implement complex business rules for item updates
+     *
+     * @example
+     * ```ts
+     * // Ensure item doesn't exist (insert only)
+     * builder.condition(op => op.attributeNotExists('id'))
+     *
+     * // Complex condition with version check
+     * builder.condition(op =>
+     *   op.and([
+     *     op.attributeExists('id'),
+     *     op.eq('version', currentVersion),
+     *     op.eq('status', 'ACTIVE')
+     *   ])
+     * )
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    /**
+     * Adds a condition that must be satisfied for the put operation to succeed.
+     * Use this method when you need to:
+     * - Prevent duplicate dinosaur entries
+     * - Ensure habitat requirements
+     * - Validate security protocols
+     *
+     * @example
+     * ```typescript
+     * // Ensure unique dinosaur ID
+     * builder.condition(op =>
+     *   op.attributeNotExists('id')
+     * );
+     *
+     * // Verify habitat requirements
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('securityStatus', 'READY'),
+     *     op.attributeExists('lastInspection'),
+     *     op.gt('securityLevel', 5)
+     *   ])
+     * );
+     *
+     * // Check breeding facility conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.between('temperature', 25, 30),
+     *     op.between('humidity', 60, 80),
+     *     op.eq('quarantineStatus', 'CLEAR')
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition object or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): PutBuilder<T>;
+    /**
+     * Sets whether to return the item's previous values (if it existed).
+     * Use this method when you need to:
+     * - Track dinosaur profile updates
+     * - Monitor habitat modifications
+     * - Maintain change history
+     *
+     * @example
+     * ```ts
+     * // Get previous dinosaur state
+     * const result = await builder
+     *   .returnValues('ALL_OLD')
+     *   .execute();
+     *
+     * if (result) {
+     *   console.log('Previous profile:', {
+     *     species: result.species,
+     *     status: result.status,
+     *     stats: {
+     *       health: result.stats.health,
+     *       threatLevel: result.stats.threatLevel
+     *     }
+     *   });
+     * }
+     * ```
+     *
+     * @param returnValues - Use 'ALL_OLD' to return previous values, or 'NONE' (default)
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD" | "NONE"): PutBuilder<T>;
+    /**
+     * Generate the DynamoDB command parameters
      */
-    shouldRetry: (error: unknown, attempt: number) => boolean;
+    private toDynamoCommand;
     /**
-     * Get the delay in milliseconds for the next retry attempt
-     * @param attempt The amount of attempts this action has made to run the action
-     * @returns The delay in milliseconds
+     * Adds this put operation to a transaction.
+     * Use this method when you need to:
+     * - Transfer dinosaurs between habitats
+     * - Initialize new breeding programs
+     * - Update multiple facility records
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     *
+     * // Add dinosaur to new habitat
+     * new PutBuilder(executor, {
+     *   id: 'TREX-002',
+     *   location: 'PADDOCK-B',
+     *   status: 'ACTIVE',
+     *   transferDate: new Date().toISOString()
+     * }, 'dinosaurs')
+     *   .withTransaction(transaction);
+     *
+     * // Update habitat records
+     * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })
+     *   .add('occupants', 1)
+     *   .set('lastTransfer', new Date().toISOString())
+     *   .withTransaction(transaction);
+     *
+     * // Execute transfer atomically
+     * await transaction.execute();
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): PutBuilder<T>;
+    /**
+     * Executes the put operation against DynamoDB.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   // Put with condition and return old values
+     *   const result = await new PutBuilder(executor, newItem, 'myTable')
+     *     .condition(op => op.eq('version', 1))
+     *     .returnValues('ALL_OLD')
+     *     .execute();
+     *
+     *   console.log('Put successful, old item:', result);
+     * } catch (error) {
+     *   // Handle condition check failure or other errors
+     *   console.error('Put failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to the operation result (type depends on returnValues setting)
+     * @throws Will throw an error if the condition check fails or other DynamoDB errors occur
+     */
+    execute(): Promise<T>;
+    /**
+     * Gets a human-readable representation of the put command
+     * with all expression placeholders replaced by their actual values.
+     * Use this method when you need to:
+     * - Debug complex dinosaur transfers
+     * - Verify habitat assignments
+     * - Log security protocols
+     * - Troubleshoot breeding program conditions
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new PutBuilder(executor, {
+     *   id: 'RAPTOR-003',
+     *   species: 'Velociraptor',
+     *   status: 'QUARANTINE',
+     *   stats: {
+     *     health: 100,
+     *     aggressionLevel: 7,
+     *     age: 2
+     *   }
+     * }, 'dinosaurs')
+     *   .condition(op =>
+     *     op.and([
+     *       op.attributeNotExists('id'),
+     *       op.eq('quarantineStatus', 'READY'),
+     *       op.gt('securityLevel', 8)
+     *     ])
+     *   )
+     *   .debug();
+     *
+     * console.log('Dinosaur transfer command:', debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the put command with resolved expressions
      */
-    getDelay: (attempt: number) => number;
+    debug(): Record<string, unknown>;
 }
 
-declare class ExponentialBackoffStrategy implements RetryStrategy {
-    maxAttempts: number;
-    baseDelay: number;
-    private maxDelay;
-    private jitter;
-    constructor(maxAttempts?: number, baseDelay?: number, maxDelay?: number, jitter?: boolean);
-    shouldRetry(error: unknown, attempt: number): boolean;
-    getDelay(attempt: number): number;
-}
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
 
-declare class DynamoError extends Error {
-    readonly originalError: Error;
-    readonly context?: Record<string, unknown> | undefined;
-    constructor(message: string, originalError: Error, context?: Record<string, unknown> | undefined);
+/**
+ * Parameters for the DynamoDB get command.
+ */
+interface GetCommandParams {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to get */
+    key: PrimaryKeyWithoutExpression;
+    /** Comma-separated list of attributes to return */
+    projectionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
 }
-declare class ConditionalCheckFailedError extends DynamoError {
-    constructor(message: string, originalError: Error, context?: Record<string, unknown>);
+/**
+ * Function type for executing DynamoDB get operations.
+ * @typeParam T - The type of item being retrieved
+ */
+type GetExecutor<T extends Record<string, unknown>> = (params: GetCommandParams) => Promise<{
+    item: T | undefined;
+}>;
+/**
+ * Builder for creating DynamoDB get operations.
+ * Use this builder when you need to:
+ * - Retrieve a single dinosaur by its primary key
+ * - Project specific dinosaur attributes
+ * - Use consistent reads for critical dinosaur data
+ *
+ * @example
+ * ```typescript
+ * // Simple get
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .execute();
+ *
+ * // Get with projection and consistent read
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .select(['species', 'name', 'diet'])
+ *   .consistentRead()
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being retrieved
+ */
+declare class GetBuilder<T extends Record<string, unknown>> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    /**
+     * Creates a new GetBuilder instance.
+     *
+     * @param executor - Function that executes the get operation
+     * @param key - Primary key of the item to retrieve
+     * @param tableName - Name of the DynamoDB table
+     */
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string);
+    /**
+     * Specifies which attributes to return in the get results.
+     * Use this method when you need to:
+     * - Reduce data transfer by selecting specific dinosaur attributes
+     * - Optimize response size for dinosaur records
+     * - Focus on relevant dinosaur characteristics only
+     *
+     * @example
+     * ```typescript
+     * // Select single attribute
+     * builder.select('species')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'species', 'diet'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['species', 'diet'])
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select(fields: string | string[]): GetBuilder<T>;
+    /**
+     * Sets whether to use strongly consistent reads for the get operation.
+     * Use this method when you need:
+     * - The most up-to-date dinosaur data
+     * - To ensure you're reading the latest dinosaur status
+     * - Critical safety information about dangerous species
+     *
+     * Note: Consistent reads consume twice the throughput
+     *
+     * @example
+     * ```typescript
+     * // Get the latest T-Rex data
+     * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *   .consistentRead()
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): GetBuilder<T>;
+    /**
+     * Executes the get operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *     .select(['species', 'name', 'diet'])
+     *     .consistentRead()
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Dinosaur found:', result.item);
+     *   } else {
+     *     console.log('Dinosaur not found');
+     *   }
+     * } catch (error) {
+     *   console.error('Error getting dinosaur:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - item: The retrieved dinosaur or undefined if not found
+     */
+    execute(): Promise<{
+        item: T | undefined;
+    }>;
 }
-declare class ResourceNotFoundError extends DynamoError {
-    constructor(message: string, originalError: Error, context?: Record<string, unknown>);
+
+declare class Table<TConfig extends TableConfig = TableConfig> {
+    private dynamoClient;
+    readonly tableName: string;
+    readonly partitionKey: string;
+    readonly sortKey?: string;
+    readonly gsis: Record<string, Index>;
+    constructor(config: TConfig);
+    /**
+     * Creates a new item in the table, it will fail if the item already exists
+     *
+     * @param item The item to create
+     * @returns A PutBuilder instance for chaining conditions and executing the put operation
+     */
+    create<T extends Record<string, unknown>>(item: T): PutBuilder<T>;
+    get<T extends Record<string, unknown>>(keyCondition: PrimaryKeyWithoutExpression): GetBuilder<T>;
+    /**
+     * 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<T extends Record<string, unknown>>(item: T): PutBuilder<T>;
+    /**
+     * Creates a query builder for complex queries
+     * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
+     */
+    query<T extends Record<string, unknown>>(keyCondition: PrimaryKey): QueryBuilder<T, TConfig>;
+    delete(keyCondition: PrimaryKeyWithoutExpression): DeleteBuilder;
+    /**
+     * 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<T extends Record<string, unknown>>(keyCondition: PrimaryKeyWithoutExpression): UpdateBuilder<T>;
+    /**
+     * Creates a transaction builder for performing multiple operations atomically
+     */
+    transactionBuilder(): TransactionBuilder;
+    /**
+     * 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
+     */
+    transaction<T>(callback: (tx: TransactionBuilder) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * 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: PrimaryKeyWithoutExpression): ConditionCheckBuilder;
+    /**
+     * 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
+     */
+    batchGet<T extends Record<string, unknown>>(keys: Array<PrimaryKeyWithoutExpression>): Promise<{
+        items: T[];
+        unprocessedKeys: PrimaryKeyWithoutExpression[];
+    }>;
+    /**
+     * 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
+     */
+    batchWrite<T extends Record<string, unknown>>(operations: Array<BatchWriteOperation<T>>): Promise<{
+        unprocessedItems: Array<BatchWriteOperation<T>>;
+    }>;
 }
 
-export { BaseRepository, ConditionalCheckFailedError, DynamoError, ExponentialBackoffStrategy, type FilterCondition, type FilterOperator, type PrimaryKey, ResourceNotFoundError, type RetryStrategy, Table, type TableIndexConfig };
+export { type Condition, ConditionCheckBuilder, type ConditionOperator, DeleteBuilder, type EntityConfig, type GSINames, type Index, type PaginationResult, Paginator, PutBuilder, QueryBuilder, Table, type TableConfig, TransactionBuilder, UpdateBuilder, and, attributeExists, attributeNotExists, beginsWith, between, contains, eq, gt, gte, lt, lte, ne, not, or };