dyno-table 1.3.0 → 1.4.0

package/dist/conditions-BIpBkh4m.d.ts

@@ -0,0 +1,729 @@
+import { DynamoItem } from './types.js';
+
+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)
+ * - in: Checks if attribute value is in a list of values
+ * - 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" | "in" | "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: DynamoItem;
+    /** 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 an in condition that checks if a value is in a list of values
+ * @example
+ * inArray("status", ["ACTIVE", "PENDING", "PROCESSING"]) // status IN ("ACTIVE", "PENDING", "PROCESSING")
+ * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}
+ */
+declare const inArray: (attr: string, values: 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 DynamoItem> = {
+    /**
+     * Creates an equals (=) condition for type-safe attribute comparison.
+     * Tests if the specified attribute equals the provided value.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr equals value
+     *
+     * @example
+     * ```typescript
+     * interface User { status: string; age: number; }
+     *
+     * // String comparison
+     * op.eq("status", "ACTIVE") // status = "ACTIVE"
+     *
+     * // Numeric comparison
+     * op.eq("age", 25) // age = 25
+     *
+     * // Nested attribute
+     * op.eq("profile.role", "admin") // profile.role = "admin"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    eq: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a not equals (≠ / <>) condition for type-safe attribute comparison.
+     * Tests if the specified attribute does not equal the provided value.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr does not equal value
+     *
+     * @example
+     * ```typescript
+     * interface User { status: string; priority: number; }
+     *
+     * // String comparison
+     * op.ne("status", "DELETED") // status <> "DELETED"
+     *
+     * // Numeric comparison
+     * op.ne("priority", 0) // priority <> 0
+     *
+     * // Useful for filtering out specific values
+     * op.ne("category", "ARCHIVED") // category <> "ARCHIVED"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    ne: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a less than (<) condition for type-safe attribute comparison.
+     * Tests if the specified attribute is less than the provided value.
+     * Works with numbers, strings (lexicographic), and dates.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr is less than value
+     *
+     * @example
+     * ```typescript
+     * interface Product { price: number; name: string; createdAt: string; }
+     *
+     * // Numeric comparison
+     * op.lt("price", 100) // price < 100
+     *
+     * // String comparison (lexicographic)
+     * op.lt("name", "M") // name < "M" (names starting with A-L)
+     *
+     * // Date comparison (ISO strings)
+     * op.lt("createdAt", "2024-01-01") // createdAt < "2024-01-01"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    lt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a less than or equal to (≤) condition for type-safe attribute comparison.
+     * Tests if the specified attribute is less than or equal to the provided value.
+     * Works with numbers, strings (lexicographic), and dates.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr is less than or equal to value
+     *
+     * @example
+     * ```typescript
+     * interface Order { total: number; priority: number; dueDate: string; }
+     *
+     * // Numeric comparison
+     * op.lte("total", 1000) // total <= 1000
+     *
+     * // Priority levels
+     * op.lte("priority", 3) // priority <= 3 (low to medium priority)
+     *
+     * // Date deadlines
+     * op.lte("dueDate", "2024-12-31") // dueDate <= "2024-12-31"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    lte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a greater than (>) condition for type-safe attribute comparison.
+     * Tests if the specified attribute is greater than the provided value.
+     * Works with numbers, strings (lexicographic), and dates.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr is greater than value
+     *
+     * @example
+     * ```typescript
+     * interface User { age: number; score: number; lastLogin: string; }
+     *
+     * // Age restrictions
+     * op.gt("age", 18) // age > 18 (adults only)
+     *
+     * // Performance thresholds
+     * op.gt("score", 85) // score > 85 (high performers)
+     *
+     * // Recent activity
+     * op.gt("lastLogin", "2024-01-01") // lastLogin > "2024-01-01"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    gt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a greater than or equal to (≥) condition for type-safe attribute comparison.
+     * Tests if the specified attribute is greater than or equal to the provided value.
+     * Works with numbers, strings (lexicographic), and dates.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param value - The value to compare against (must match attribute type)
+     * @returns A condition that evaluates to true when attr is greater than or equal to value
+     *
+     * @example
+     * ```typescript
+     * interface Product { rating: number; version: string; releaseDate: string; }
+     *
+     * // Minimum ratings
+     * op.gte("rating", 4.0) // rating >= 4.0 (highly rated)
+     *
+     * // Version requirements
+     * op.gte("version", "2.0.0") // version >= "2.0.0"
+     *
+     * // Release date filters
+     * op.gte("releaseDate", "2024-01-01") // releaseDate >= "2024-01-01"
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}
+     */
+    gte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a between condition for type-safe range comparison.
+     * Tests if the specified attribute value falls within the inclusive range [lower, upper].
+     * Works with numbers, strings (lexicographic), and dates.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param lower - The lower bound of the range (inclusive, must match attribute type)
+     * @param upper - The upper bound of the range (inclusive, must match attribute type)
+     * @returns A condition that evaluates to true when lower ≤ attr ≤ upper
+     *
+     * @example
+     * ```typescript
+     * interface Event { price: number; date: string; priority: number; }
+     *
+     * // Price range
+     * op.between("price", 50, 200) // price BETWEEN 50 AND 200
+     *
+     * // Date range
+     * op.between("date", "2024-01-01", "2024-12-31") // date BETWEEN "2024-01-01" AND "2024-12-31"
+     *
+     * // Priority levels
+     * op.between("priority", 1, 5) // priority BETWEEN 1 AND 5
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}
+     */
+    between: <K extends Path<T>>(attr: K, lower: PathType<T, K>, upper: PathType<T, K>) => Condition;
+    /**
+     * Creates an IN condition for type-safe list membership testing.
+     * Tests if the specified attribute value matches any value in the provided list.
+     * Supports up to 100 values in the list as per DynamoDB limitations.
+     *
+     * @param attr - The attribute path to compare (with full type safety)
+     * @param values - Array of values to test against (must match attribute type, max 100 items)
+     * @returns A condition that evaluates to true when attr matches any value in the list
+     *
+     * @example
+     * ```typescript
+     * interface User { status: string; role: string; priority: number; }
+     *
+     * // Status filtering
+     * op.inArray("status", ["ACTIVE", "PENDING", "PROCESSING"]) // status IN ("ACTIVE", "PENDING", "PROCESSING")
+     *
+     * // Role-based access
+     * op.inArray("role", ["admin", "moderator", "editor"]) // role IN ("admin", "moderator", "editor")
+     *
+     * // Priority levels
+     * op.inArray("priority", [1, 2, 3]) // priority IN (1, 2, 3)
+     * ```
+     *
+     * @throws {Error} When values array is empty or contains more than 100 items
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}
+     */
+    inArray: <K extends Path<T>>(attr: K, values: PathType<T, K>[]) => Condition;
+    /**
+     * Creates a begins_with condition for type-safe string prefix testing.
+     * Tests if the specified string attribute starts with the provided substring.
+     * Only works with string attributes - will fail on other data types.
+     *
+     * @param attr - The string attribute path to test (with full type safety)
+     * @param value - The prefix string to test for (must match attribute type)
+     * @returns A condition that evaluates to true when attr starts with value
+     *
+     * @example
+     * ```typescript
+     * interface User { email: string; name: string; id: string; }
+     *
+     * // Email domain filtering
+     * op.beginsWith("email", "admin@") // begins_with(email, "admin@")
+     *
+     * // Name prefix search
+     * op.beginsWith("name", "John") // begins_with(name, "John")
+     *
+     * // ID pattern matching
+     * op.beginsWith("id", "USER#") // begins_with(id, "USER#")
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}
+     */
+    beginsWith: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates a contains condition for type-safe substring or set membership testing.
+     * For strings: tests if the attribute contains the specified substring.
+     * For sets: tests if the set contains the specified element.
+     *
+     * @param attr - The attribute path to test (with full type safety)
+     * @param value - The substring or element to search for (must match attribute type)
+     * @returns A condition that evaluates to true when attr contains value
+     *
+     * @example
+     * ```typescript
+     * interface Post { content: string; tags: Set<string>; categories: string[]; }
+     *
+     * // Substring search in content
+     * op.contains("content", "important") // contains(content, "important")
+     *
+     * // Tag membership (for DynamoDB String Sets)
+     * op.contains("tags", "featured") // contains(tags, "featured")
+     *
+     * // Category search (for string arrays stored as lists)
+     * op.contains("categories", "technology") // contains(categories, "technology")
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}
+     */
+    contains: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;
+    /**
+     * Creates an attribute_exists condition for type-safe attribute presence testing.
+     * Tests if the specified attribute exists in the item, regardless of its value.
+     * Useful for filtering items that have optional attributes populated.
+     *
+     * @param attr - The attribute path to test for existence (with full type safety)
+     * @returns A condition that evaluates to true when the attribute exists
+     *
+     * @example
+     * ```typescript
+     * interface User { email: string; phone?: string; profile?: { avatar?: string; }; }
+     *
+     * // Check for optional fields
+     * op.attributeExists("phone") // attribute_exists(phone)
+     *
+     * // Check for nested optional attributes
+     * op.attributeExists("profile.avatar") // attribute_exists(profile.avatar)
+     *
+     * // Useful in combination with other conditions
+     * op.and(
+     *   op.eq("status", "ACTIVE"),
+     *   op.attributeExists("email") // Only active users with email
+     * )
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}
+     */
+    attributeExists: <K extends Path<T>>(attr: K) => Condition;
+    /**
+     * Creates an attribute_not_exists condition for type-safe attribute absence testing.
+     * Tests if the specified attribute does not exist in the item.
+     * Useful for conditional writes to prevent overwriting existing data.
+     *
+     * @param attr - The attribute path to test for absence (with full type safety)
+     * @returns A condition that evaluates to true when the attribute does not exist
+     *
+     * @example
+     * ```typescript
+     * interface User { id: string; email: string; deletedAt?: string; }
+     *
+     * // Ensure item hasn't been soft-deleted
+     * op.attributeNotExists("deletedAt") // attribute_not_exists(deletedAt)
+     *
+     * // Prevent duplicate creation
+     * op.attributeNotExists("id") // attribute_not_exists(id)
+     *
+     * // Conditional updates
+     * op.and(
+     *   op.eq("status", "PENDING"),
+     *   op.attributeNotExists("processedAt") // Only unprocessed items
+     * )
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}
+     */
+    attributeNotExists: <K extends Path<T>>(attr: K) => Condition;
+    /**
+     * Combines multiple conditions with logical AND operator.
+     * All provided conditions must evaluate to true for the AND condition to be true.
+     * Supports any number of conditions as arguments.
+     *
+     * @param conditions - Variable number of conditions to combine with AND
+     * @returns A condition that evaluates to true when all input conditions are true
+     *
+     * @example
+     * ```typescript
+     * interface User { status: string; age: number; role: string; verified: boolean; }
+     *
+     * // Multiple criteria
+     * op.and(
+     *   op.eq("status", "ACTIVE"),
+     *   op.gt("age", 18),
+     *   op.eq("verified", true)
+     * ) // status = "ACTIVE" AND age > 18 AND verified = true
+     *
+     * // Complex business logic
+     * op.and(
+     *   op.inArray("role", ["admin", "moderator"]),
+     *   op.attributeExists("permissions"),
+     *   op.ne("status", "SUSPENDED")
+     * )
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}
+     */
+    and: (...conditions: Condition[]) => Condition;
+    /**
+     * Combines multiple conditions with logical OR operator.
+     * At least one of the provided conditions must evaluate to true for the OR condition to be true.
+     * Supports any number of conditions as arguments.
+     *
+     * @param conditions - Variable number of conditions to combine with OR
+     * @returns A condition that evaluates to true when any input condition is true
+     *
+     * @example
+     * ```typescript
+     * interface Order { status: string; priority: string; urgent: boolean; }
+     *
+     * // Alternative statuses
+     * op.or(
+     *   op.eq("status", "PENDING"),
+     *   op.eq("status", "PROCESSING"),
+     *   op.eq("status", "SHIPPED")
+     * ) // status = "PENDING" OR status = "PROCESSING" OR status = "SHIPPED"
+     *
+     * // High priority items
+     * op.or(
+     *   op.eq("priority", "HIGH"),
+     *   op.eq("urgent", true)
+     * )
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}
+     */
+    or: (...conditions: Condition[]) => Condition;
+    /**
+     * Negates a condition with logical NOT operator.
+     * Inverts the boolean result of the provided condition.
+     *
+     * @param condition - The condition to negate
+     * @returns A condition that evaluates to true when the input condition is false
+     *
+     * @example
+     * ```typescript
+     * interface User { status: string; role: string; banned: boolean; }
+     *
+     * // Exclude specific status
+     * op.not(op.eq("status", "DELETED")) // NOT status = "DELETED"
+     *
+     * // Complex negation
+     * op.not(
+     *   op.and(
+     *     op.eq("role", "guest"),
+     *     op.eq("banned", true)
+     *   )
+     * ) // NOT (role = "guest" AND banned = true)
+     *
+     * // Exclude multiple values
+     * op.not(op.inArray("status", ["DELETED", "ARCHIVED"]))
+     * ```
+     *
+     * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}
+     */
+    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;
+};
+
+export { type Condition as C, type ExpressionParams as E, type KeyConditionOperator as K, type LogicalOperator as L, type PrimaryKeyWithoutExpression as P, type PrimaryKey as a, type ConditionOperator as b, type Path as c, type PathType as d, type ComparisonOperator as e, createComparisonCondition as f, eq as g, lte as h, gt as i, gte as j, between as k, lt as l, inArray as m, ne as n, beginsWith as o, contains as p, attributeExists as q, attributeNotExists as r, and as s, or as t, not as u };