dyno-table 0.2.0-0 → 1.0.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,2971 @@
+import { DynamoDBDocument, TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+
+interface Index {
+    partitionKey: string;
+    sortKey?: string;
+}
+interface IndexConfig$1 {
+    partitionKey: string;
+    sortKey?: string;
+    gsis?: Record<string, Index>;
+}
+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 {
+    /** 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;
+}
+/**
+ * Parameters used to build DynamoDB expression strings.
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}
+ */
+interface ExpressionParams {
+    /** Map of attribute name placeholders to actual attribute names */
+    expressionAttributeNames: Record<string, string>;
+    /** Map of value placeholders to actual values */
+    expressionAttributeValues: Record<string, unknown>;
+    /** Counter for generating unique value placeholders */
+    valueCounter: {
+        count: number;
+    };
+}
+/**
+ * Creates a comparison condition builder function for the specified operator.
+ * @internal
+ */
+declare const createComparisonCondition: (type: ComparisonOperator) => (attr: string, value: unknown) => Condition;
+/**
+ * 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;
+    /** 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 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;
+}
+
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: PrimaryKeyWithoutExpression;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD";
+}
+/**
+ * Parameters for the DynamoDB put command.
+ *
+ * These parameters are used when executing the operation against DynamoDB.
+ *
+ * The `returnValues` property can be:
+ * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
+ * - `"NONE"`: Return nothing
+ * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+/**
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+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";
+}
+interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: PrimaryKeyWithoutExpression;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+interface BaseBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: Record<string, unknown>): B;
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface QueryBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the ScanBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface ScanBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the FilterBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface FilterBuilderInterface<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
+}
+/**
+ * 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;
+}
+
+/**
+ * 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: QueryBuilderInterface<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[]>;
+}
+
+/**
+ * Configuration options for DynamoDB filter operations.
+ * These are common options shared between query and scan operations.
+ */
+interface FilterOptions {
+    /** Filter conditions applied to results */
+    filter?: Condition;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Name of the Global Secondary Index to use */
+    indexName?: string;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+    /** List of attributes to return in the result */
+    projection?: string[];
+    /** Token for starting the operation from a specific point */
+    lastEvaluatedKey?: Record<string, unknown>;
+}
+/**
+ * Abstract base builder for creating DynamoDB filter operations.
+ * This class provides common functionality for both Query and Scan operations.
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Pagination
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @typeParam T - The type of items being filtered
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare abstract class FilterBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> implements FilterBuilderInterface<T, TConfig> {
+    protected options: FilterOptions;
+    protected selectedFields: Set<string>;
+    /**
+     * Sets the maximum number of items to return.
+     * Use this method when you need to:
+     * - Limit the number of dinosaurs returned
+     * - Control the size of habitat reports
+     * - Implement manual pagination of security logs
+     *
+     * Note: This limit applies to the items that match the key condition
+     * before any filter expressions are applied.
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 dinosaurs
+     * const result = await builder
+     *   .limit(10)
+     *   .execute();
+     * ```
+     *
+     * @param limit - Maximum number of items to return
+     * @returns The builder instance for method chaining
+     */
+    limit(limit: number): this;
+    /**
+     * Gets the current limit set on the operation.
+     * 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 operation.
+     * Use this method when you need to:
+     * - Find 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): this;
+    /**
+     * Sets whether to use strongly consistent reads for the operation.
+     * 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
+     * ```typescript
+     * // Check immediate dinosaur status
+     * const result = await builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .consistentRead()
+     *   .execute();
+     *
+     * // Monitor security breaches
+     * const result = await builder
+     *   .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): this;
+    /**
+     * Adds a filter expression to refine the operation 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)): this;
+    /**
+     * Specifies which attributes to return in the 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[]): this;
+    /**
+     * Creates a paginator that handles DynamoDB pagination automatically.
+     * The paginator handles:
+     * - Tracking the last evaluated key
+     * - Managing page boundaries
+     * - Respecting overall query limits
+     *
+     * @example
+     * ```typescript
+     * // Create a paginator for dinosaur records
+     * const paginator = builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .paginate(10);
+     *
+     * // Process pages of dinosaur results
+     * while (paginator.hasNextPage()) {
+     *   const page = await paginator.getNextPage();
+     *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
+     *   // Process dinosaur data
+     * }
+     * ```
+     *
+     * @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 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 operation 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 builder
+     *   .filter(op => op.eq('status', 'ACTIVE'))
+     *   .limit(5)
+     *   .execute();
+     *
+     * if (result1.lastEvaluatedKey) {
+     *   // Continue listing dinosaurs
+     *   const result2 = await builder
+     *     .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 result
+     * @returns The builder instance for method chaining
+     */
+    startFrom(lastEvaluatedKey: Record<string, unknown>): this;
+    /**
+     * Creates a deep clone of this builder 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 operation templates
+     * - Running multiple variations of an operation
+     *
+     * @example
+     * ```typescript
+     * // Create base dinosaur query
+     * const baseBuilder = builder
+     *   .useIndex('status-index')
+     *   .select(['id', 'status', 'location']);
+     *
+     * // Check active dinosaurs
+     * const activeRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'HUNTING'))
+     *   .execute();
+     *
+     * // Check contained dinosaurs
+     * const containedRaptors = baseBuilder.clone()
+     *   .filter(op => op.eq('status', 'CONTAINED'))
+     *   .execute();
+     * ```
+     *
+     * @returns A new builder instance with the same configuration
+     */
+    abstract clone(): FilterBuilderInterface<T, TConfig>;
+    /**
+     * Executes the operation against DynamoDB.
+     * This method must be implemented by subclasses to handle
+     * their specific execution logic.
+     */
+    abstract execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * Configuration options for DynamoDB query operations.
+ * Extends the base FilterOptions with query-specific options.
+ */
+interface QueryOptions extends FilterOptions {
+    /** Condition for the sort key in the table or index */
+    sortKeyCondition?: Condition;
+    /** Direction of sort key traversal (true for ascending, false for descending) */
+    scanIndexForward?: boolean;
+}
+/**
+ * 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.
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Forward and reverse sorting
+ *
+ * @example
+ * ```typescript
+ * // 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
+ */
+declare class QueryBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements QueryBuilderInterface<T, TConfig> {
+    private readonly keyCondition;
+    protected options: QueryOptions;
+    protected readonly executor: QueryExecutor<T>;
+    constructor(executor: QueryExecutor<T>, keyCondition: Condition);
+    /**
+     * Sets the maximum number of items to return from the query.
+     *
+     * 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.
+     *
+     * @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.
+     *
+     * @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 deep clone of this QueryBuilder instance.
+     *
+     * 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.
+     *
+     * 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>;
+    }>;
+}
+
+/**
+ * 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);
+    /**
+     * Checks if an item with the same primary key already exists in the transaction
+     * @private
+     */
+    private checkForDuplicateItem;
+    /**
+     * 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
+     */
+    put<T extends Record<string, unknown>>(tableName: string, item: T, condition?: Condition): TransactionBuilder;
+    /**
+     * 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
+     */
+    putWithCommand(command: PutCommandParams): TransactionBuilder;
+    /**
+     * 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
+     */
+    deleteWithCommand(command: DeleteCommandParams): TransactionBuilder;
+    /**
+     * 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
+     */
+    updateWithCommand(command: UpdateCommandParams): TransactionBuilder;
+    /**
+     * 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
+     */
+    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
+    /**
+     * 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
+     */
+    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
+    /**
+     * 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
+     */
+    withOptions(options: TransactionOptions): TransactionBuilder;
+    /**
+     * 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
+     */
+    debug(): Record<string, unknown>[];
+    /**
+     * 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
+     */
+    execute(): Promise<void>;
+}
+
+/**
+ * Configuration options for DynamoDB put operations.
+ */
+interface PutOptions {
+    /** Optional condition that must be satisfied for the put operation to succeed */
+    condition?: Condition;
+    /** Determines how to handle the return value of the put operation
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed
+     *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state
+     */
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+type PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;
+/**
+ * Builder for creating DynamoDB put operations.
+ *
+ * @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);
+    /**
+     * 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.
+     *
+     * @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)): this;
+    /**
+     * Sets whether to return the item's previous values (if it existed).
+     *
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed
+     *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state
+     *
+     * @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 if the item was overwritten, or 'NONE' (default).
+     * @returns The builder instance for method chaining
+     */
+    returnValues(returnValues: "ALL_OLD" | "NONE" | "CONSISTENT"): this;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * 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): this;
+    /**
+     * 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 | undefined>;
+    /**
+     * Gets a human-readable representation of the put command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @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
+     */
+    debug(): Record<string, unknown>;
+}
+
+interface DeleteOptions {
+    condition?: Condition;
+    returnValues?: "ALL_OLD";
+}
+type DeleteExecutor = (params: DeleteCommandParams) => Promise<{
+    item?: Record<string, unknown>;
+}>;
+/**
+ * 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;
+    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:
+     * - 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<{
+        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>;
+}
+
+/**
+ * Configuration options for DynamoDB update operations.
+ */
+interface UpdateOptions {
+    /** Optional condition that must be satisfied for the update to succeed */
+    condition?: Condition;
+    /** Determines which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+/**
+ * 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;
+}>;
+/**
+ * Represents a single update action within an update operation.
+ * Each action modifies the item in a specific way:
+ * - SET: Modify or add attributes
+ * - REMOVE: Delete attributes
+ * - ADD: Update numbers and sets
+ * - DELETE: Remove elements from a set
+ */
+type UpdateAction = {
+    /** The type of update action */
+    type: "SET" | "REMOVE" | "ADD" | "DELETE";
+    /** The attribute path to update */
+    path: string;
+    /** The value to use in the update (not used for REMOVE actions) */
+    value?: unknown;
+};
+/**
+ * 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);
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
+     */
+    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;
+    }>;
+}
+
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
+/**
+ * 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);
+    /**
+     * 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)
+     *   ])
+     * );
+     *
+     * // 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
+     */
+    condition<T extends Record<string, unknown>>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): ConditionCheckBuilder;
+    /**
+     * 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
+     *
+     * @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
+     */
+    private toDynamoCommand;
+    /**
+     * 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
+     */
+    withTransaction(transaction: TransactionBuilder): ConditionCheckBuilder;
+    /**
+     * 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
+     */
+    debug(): Record<string, unknown>;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+    }>;
+}
+
+/**
+ * Configuration options for DynamoDB scan operations.
+ * Extends the base FilterOptions.
+ */
+type ScanOptions = FilterOptions;
+/**
+ * Function type for executing DynamoDB filter operations.
+ * @typeParam T - The type of items being filtered
+ */
+type ScanExecutor<T extends Record<string, unknown>> = (options: ScanOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}>;
+/**
+ * Builder for creating DynamoDB scan operations.
+ * Use this builder when you need to:
+ * - Scan all items in a table
+ * - Filter results based on non-key attributes
+ * - Scan items on a Secondary Index (GSI)
+ * - Implement pagination
+ * - Project specific attributes
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @example
+ * ```typescript
+ * // Simple scan with filtering
+ * const result = await new ScanBuilder(executor)
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .execute();
+ *
+ * // Scan with GSI and filtering
+ * const result = await new ScanBuilder(executor)
+ *   .useIndex('status-index')
+ *   .filter(op => op.gt('securityLevel', 8))
+ *   .select(['id', 'capacity', 'currentOccupants'])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Scan with pagination
+ * const paginator = new ScanBuilder(executor)
+ *   .filter(op => op.eq('type', 'INCIDENT'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being scanned
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare class ScanBuilder<T extends Record<string, unknown>, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements ScanBuilderInterface<T, TConfig> {
+    protected readonly executor: ScanExecutor<T>;
+    constructor(executor: ScanExecutor<T>);
+    /**
+     * Creates a deep clone of this ScanBuilder instance.
+     * Use this method when you need to:
+     * - Create scan templates
+     * - Run multiple variations of a scan
+     * - Implement pagination (used internally by paginate())
+     *
+     * @returns A new ScanBuilder instance with the same configuration
+     */
+    clone(): ScanBuilder<T, TConfig>;
+    /**
+     * Executes the scan against DynamoDB.
+     * Use this method when you need to:
+     * - Search across the entire table
+     * - Find items matching specific criteria
+     * - Perform full table analysis
+     * - Generate reports across all data
+     *
+     * The method returns both the matched items and, if there are more results,
+     * a lastEvaluatedKey that can be used with startFrom() to continue the scan.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find all dinosaurs with high aggression levels
+     *   const result = await new ScanBuilder(executor)
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .limit(20)
+     *     .execute();
+     *
+     *   console.log(`Found ${result.items.length} potentially dangerous dinosaurs`);
+     *
+     *   if (result.lastEvaluatedKey) {
+     *     console.log('More results available');
+     *   }
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - items: Array of items matching the scan criteria
+     *          - lastEvaluatedKey: Token for continuing the scan, if more items exist
+     */
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+
+declare class Table<TConfig extends TableConfig = TableConfig> {
+    private readonly dynamoClient;
+    readonly tableName: string;
+    /**
+     * The column name of the partitionKey for the Table
+     */
+    readonly partitionKey: string;
+    /**
+     * The column name of the sortKey for the Table
+     */
+    readonly sortKey?: string;
+    /**
+     * The Global Secondary Indexes that are configured on this table
+     */
+    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>;
+    /**
+     * Creates a scan builder for scanning the entire table
+     * Use this when you need to:
+     * - Process all items in a table
+     * - Apply filters to a large dataset
+     * - Use a GSI for scanning
+     *
+     * @returns A ScanBuilder instance for chaining operations
+     */
+    scan<T extends Record<string, unknown>>(): ScanBuilder<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 { type ComparisonOperator, type Condition, ConditionCheckBuilder, type ConditionOperator, DeleteBuilder, type DeleteOptions, type EntityConfig, type ExpressionParams, type GSINames, type Index, type KeyConditionOperator, type LogicalOperator, Paginator, type PrimaryKey, type PrimaryKeyWithoutExpression, PutBuilder, type PutOptions, QueryBuilder, type QueryOptions, Table, type TableConfig, TransactionBuilder, type TransactionExecutor, type TransactionOptions, type UpdateAction, UpdateBuilder, type UpdateOptions, and, attributeExists, attributeNotExists, beginsWith, between, contains, createComparisonCondition, eq, gt, gte, lt, lte, ne, not, or };