dyno-table 2.0.2 → 2.1.0

package/dist/conditions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/conditions.ts"],"names":[],"mappings":";AAiGO,IAAM,yBAAA,GACX,CAAC,IAAA,KACD,CAAC,MAAc,KAAA,MAA+B;AAAA,EAC5C,IAAA;AAAA,EACA,IAAA;AAAA,EACA;AACF,CAAA;AAQK,IAAM,EAAA,GAAK,0BAA0B,IAAI;AAQzC,IAAM,EAAA,GAAK,0BAA0B,IAAI;AAQzC,IAAM,EAAA,GAAK,0BAA0B,IAAI;AAQzC,IAAM,GAAA,GAAM,0BAA0B,KAAK;AAQ3C,IAAM,EAAA,GAAK,0BAA0B,IAAI;AAQzC,IAAM,GAAA,GAAM,0BAA0B,KAAK;AAQ3C,IAAM,OAAA,GAAU,CAAC,IAAA,EAAc,KAAA,EAAgB,KAAA,MAA+B;AAAA,EACnF,IAAA,EAAM,SAAA;AAAA,EACN,IAAA;AAAA,EACA,KAAA,EAAO,CAAC,KAAA,EAAO,KAAK;AACtB,CAAA;AAQO,IAAM,OAAA,GAAU,CAAC,IAAA,EAAc,MAAA,MAAkC;AAAA,EACtE,IAAA,EAAM,IAAA;AAAA,EACN,IAAA;AAAA,EACA,KAAA,EAAO;AACT,CAAA;AAQO,IAAM,UAAA,GAAa,0BAA0B,YAAY;AAQzD,IAAM,QAAA,GAAW,0BAA0B,UAAU;AAQrD,IAAM,eAAA,GAAkB,CAAC,IAAA,MAA6B;AAAA,EAC3D,IAAA,EAAM,iBAAA;AAAA,EACN;AACF,CAAA;AAQO,IAAM,kBAAA,GAAqB,CAAC,IAAA,MAA6B;AAAA,EAC9D,IAAA,EAAM,oBAAA;AAAA,EACN;AACF,CAAA;AAaO,IAAM,GAAA,GAAM,IAAI,UAAA,MAAwC;AAAA,EAC7D,IAAA,EAAM,KAAA;AAAA,EACN;AACF,CAAA;AAWO,IAAM,EAAA,GAAK,IAAI,UAAA,MAAwC;AAAA,EAC5D,IAAA,EAAM,IAAA;AAAA,EACN;AACF,CAAA;AAQO,IAAM,GAAA,GAAM,CAAC,SAAA,MAAqC;AAAA,EACvD,IAAA,EAAM,KAAA;AAAA,EACN;AACF,CAAA","file":"conditions.js","sourcesContent":["import type { Path, PathType } from \"./builders/types\";\nimport type { DynamoItem } from \"./types\";\n\n/**\n * Supported comparison operators for DynamoDB conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Comparison Operator Reference}\n *\n * - eq: Equals (=)\n * - ne: Not equals (≠ / <>)\n * - lt: Less than (<)\n * - lte: Less than or equal to (≤)\n * - gt: Greater than (>)\n * - gte: Greater than or equal to (≥)\n * - between: Between two values (inclusive)\n * - in: Checks if attribute value is in a list of values\n * - beginsWith: Checks if string attribute begins with specified substring\n * - contains: Checks if string/set attribute contains specified value\n * - attributeExists: Checks if attribute exists\n * - attributeNotExists: Checks if attribute does not exist\n */\nexport type ComparisonOperator =\n  | \"eq\"\n  | \"ne\"\n  | \"lt\"\n  | \"lte\"\n  | \"gt\"\n  | \"gte\"\n  | \"between\"\n  | \"in\"\n  | \"beginsWith\"\n  | \"contains\"\n  | \"attributeExists\"\n  | \"attributeNotExists\";\n\n/**\n * Logical operators for combining multiple conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - Logical Operator Reference}\n *\n * - and: Evaluates to true if all conditions are true\n * - or: Evaluates to true if any condition is true\n * - not: Negate the result of a condition\n */\nexport type LogicalOperator = \"and\" | \"or\" | \"not\";\n\n/**\n * Represents a DynamoDB condition expression.\n * Can be either a comparison condition or a logical combination of conditions.\n *\n * @example\n * // Simple comparison condition\n * const condition: Condition = {\n *   type: \"eq\",\n *   attr: \"status\",\n *   value: \"ACTIVE\"\n * };\n *\n * @example\n * // Logical combination of conditions\n * const condition: Condition = {\n *   type: \"and\",\n *   conditions: [\n *     { type: \"eq\", attr: \"status\", value: \"ACTIVE\" },\n *     { type: \"gt\", attr: \"age\", value: 5 }\n *   ]\n * };\n */\nexport interface Condition {\n  /** The type of condition (comparison or logical operator) */\n  type: ComparisonOperator | LogicalOperator;\n  /** The attribute name for comparison conditions */\n  attr?: string;\n  /** The value to compare against for comparison conditions */\n  value?: unknown;\n  /** Array of conditions for logical operators (and/or) */\n  conditions?: Condition[];\n  /** Single condition for the 'not' operator */\n  condition?: Condition;\n}\n\n/**\n * Parameters used to build DynamoDB expression strings.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}\n */\nexport interface ExpressionParams {\n  /** Map of attribute name placeholders to actual attribute names */\n  expressionAttributeNames: Record<string, string>;\n  /** Map of value placeholders to actual values */\n  expressionAttributeValues: DynamoItem;\n  /** Counter for generating unique value placeholders */\n  valueCounter: { count: number };\n}\n\n/**\n * Creates a comparison condition builder function for the specified operator.\n * @internal\n */\nexport const createComparisonCondition =\n  (type: ComparisonOperator) =>\n  (attr: string, value: unknown): Condition => ({\n    type,\n    attr,\n    value,\n  });\n\n/**\n * Creates an equals (=) condition\n * @example\n * eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const eq = createComparisonCondition(\"eq\");\n\n/**\n * Creates a not equals (≠) condition\n * @example\n * ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const ne = createComparisonCondition(\"ne\");\n\n/**\n * Creates a less than (<) condition\n * @example\n * lt(\"age\", 18) // age < 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lt = createComparisonCondition(\"lt\");\n\n/**\n * Creates a less than or equal to (≤) condition\n * @example\n * lte(\"age\", 18) // age <= 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lte = createComparisonCondition(\"lte\");\n\n/**\n * Creates a greater than (>) condition\n * @example\n * gt(\"price\", 100) // price > 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gt = createComparisonCondition(\"gt\");\n\n/**\n * Creates a greater than or equal to (≥) condition\n * @example\n * gte(\"price\", 100) // price >= 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gte = createComparisonCondition(\"gte\");\n\n/**\n * Creates a between condition that checks if a value is within a range (inclusive)\n * @example\n * between(\"age\", 18, 65) // age BETWEEN 18 AND 65\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n */\nexport const between = (attr: string, lower: unknown, upper: unknown): Condition => ({\n  type: \"between\",\n  attr,\n  value: [lower, upper],\n});\n\n/**\n * Creates an in condition that checks if a value is in a list of values\n * @example\n * inArray(\"status\", [\"ACTIVE\", \"PENDING\", \"PROCESSING\"]) // status IN (\"ACTIVE\", \"PENDING\", \"PROCESSING\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}\n */\nexport const inArray = (attr: string, values: unknown[]): Condition => ({\n  type: \"in\",\n  attr,\n  value: values,\n});\n\n/**\n * Creates a begins_with condition that checks if a string attribute starts with a substring\n * @example\n * beginsWith(\"email\", \"@example.com\") // begins_with(email, \"@example.com\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n */\nexport const beginsWith = createComparisonCondition(\"beginsWith\");\n\n/**\n * Creates a contains condition that checks if a string contains a substring or if a set contains an element\n * @example\n * contains(\"tags\", \"important\") // contains(tags, \"important\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n */\nexport const contains = createComparisonCondition(\"contains\");\n\n/**\n * Creates a condition that checks if an attribute exists\n * @example\n * attributeExists(\"email\") // attribute_exists(email)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n */\nexport const attributeExists = (attr: string): Condition => ({\n  type: \"attributeExists\",\n  attr,\n});\n\n/**\n * Creates a condition that checks if an attribute does not exist\n * @example\n * attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n */\nexport const attributeNotExists = (attr: string): Condition => ({\n  type: \"attributeNotExists\",\n  attr,\n});\n\n// --- Logical Operators ---\n\n/**\n * Combines multiple conditions with AND operator\n * @example\n * and(\n *   eq(\"status\", \"ACTIVE\"),\n *   gt(\"age\", 18)\n * ) // status = \"ACTIVE\" AND age > 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n */\nexport const and = (...conditions: Condition[]): Condition => ({\n  type: \"and\",\n  conditions,\n});\n\n/**\n * Combines multiple conditions with OR operator\n * @example\n * or(\n *   eq(\"status\", \"PENDING\"),\n *   eq(\"status\", \"PROCESSING\")\n * ) // status = \"PENDING\" OR status = \"PROCESSING\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n */\nexport const or = (...conditions: Condition[]): Condition => ({\n  type: \"or\",\n  conditions,\n});\n\n/**\n * Negates a condition\n * @example\n * not(eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n */\nexport const not = (condition: Condition): Condition => ({\n  type: \"not\",\n  condition,\n});\n\n/**\n * Type-safe operators for building key conditions in DynamoDB queries.\n * Only includes operators that are valid for key conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions AWS DynamoDB - Key Condition Expressions}\n *\n * @example\n * // Using with sort key conditions\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#\")\n * })\n */\nexport type KeyConditionOperator = {\n  /** Equals comparison for key attributes */\n  eq: (value: unknown) => Condition;\n  /** Less than comparison for key attributes */\n  lt: (value: unknown) => Condition;\n  /** Less than or equal comparison for key attributes */\n  lte: (value: unknown) => Condition;\n  /** Greater than comparison for key attributes */\n  gt: (value: unknown) => Condition;\n  /** Greater than or equal comparison for key attributes */\n  gte: (value: unknown) => Condition;\n  /** Between range comparison for key attributes */\n  between: (lower: unknown, upper: unknown) => Condition;\n  /** Begins with comparison for key attributes */\n  beginsWith: (value: unknown) => Condition;\n  /** Combines multiple key conditions with AND */\n  and: (...conditions: Condition[]) => Condition;\n};\n\n// Helper types that allow string paths and unknown values when strict typing can't be resolved\ntype FlexiblePath<T> = Path<T> extends never ? string : Path<T>;\n// biome-ignore lint: Using any as we don't really know if it's not provided\ntype FlexiblePathType<T, K extends keyof any> = PathType<T, K> extends never ? unknown : PathType<T, K>;\n\n/**\n * Type-safe operators for building conditions in DynamoDB operations.\n * Includes all available condition operators with proper type inference.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Condition Expressions}\n *\n * @example\n * // Using with type-safe conditions\n * interface User {\n *   status: string;\n *   age: number;\n *   email?: string;\n * }\n *\n * table.scan<User>()\n *   .where(op => op.and(\n *     op.eq(\"status\", \"ACTIVE\"),\n *     op.gt(\"age\", 18),\n *     op.attributeExists(\"email\")\n *   ))\n *\n * @template T The type of the item being operated on\n */\nexport type ConditionOperator<T extends DynamoItem> = {\n  /**\n   * Creates an equals (=) condition for type-safe attribute comparison.\n   * Tests if the specified attribute equals the provided value.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr equals value\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; age: number; }\n   *\n   * // String comparison\n   * op.eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n   *\n   * // Numeric comparison\n   * op.eq(\"age\", 25) // age = 25\n   *\n   * // Nested attribute\n   * op.eq(\"profile.role\", \"admin\") // profile.role = \"admin\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  eq: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a not equals (≠ / <>) condition for type-safe attribute comparison.\n   * Tests if the specified attribute does not equal the provided value.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr does not equal value\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; priority: number; }\n   *\n   * // String comparison\n   * op.ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n   *\n   * // Numeric comparison\n   * op.ne(\"priority\", 0) // priority <> 0\n   *\n   * // Useful for filtering out specific values\n   * op.ne(\"category\", \"ARCHIVED\") // category <> \"ARCHIVED\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  ne: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a less than (<) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is less than the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is less than value\n   *\n   * @example\n   * ```typescript\n   * interface Product { price: number; name: string; createdAt: string; }\n   *\n   * // Numeric comparison\n   * op.lt(\"price\", 100) // price < 100\n   *\n   * // String comparison (lexicographic)\n   * op.lt(\"name\", \"M\") // name < \"M\" (names starting with A-L)\n   *\n   * // Date comparison (ISO strings)\n   * op.lt(\"createdAt\", \"2024-01-01\") // createdAt < \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  lt: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a less than or equal to (≤) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is less than or equal to the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is less than or equal to value\n   *\n   * @example\n   * ```typescript\n   * interface Order { total: number; priority: number; dueDate: string; }\n   *\n   * // Numeric comparison\n   * op.lte(\"total\", 1000) // total <= 1000\n   *\n   * // Priority levels\n   * op.lte(\"priority\", 3) // priority <= 3 (low to medium priority)\n   *\n   * // Date deadlines\n   * op.lte(\"dueDate\", \"2024-12-31\") // dueDate <= \"2024-12-31\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  lte: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a greater than (>) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is greater than the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is greater than value\n   *\n   * @example\n   * ```typescript\n   * interface User { age: number; score: number; lastLogin: string; }\n   *\n   * // Age restrictions\n   * op.gt(\"age\", 18) // age > 18 (adults only)\n   *\n   * // Performance thresholds\n   * op.gt(\"score\", 85) // score > 85 (high performers)\n   *\n   * // Recent activity\n   * op.gt(\"lastLogin\", \"2024-01-01\") // lastLogin > \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  gt: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a greater than or equal to (≥) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is greater than or equal to the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is greater than or equal to value\n   *\n   * @example\n   * ```typescript\n   * interface Product { rating: number; version: string; releaseDate: string; }\n   *\n   * // Minimum ratings\n   * op.gte(\"rating\", 4.0) // rating >= 4.0 (highly rated)\n   *\n   * // Version requirements\n   * op.gte(\"version\", \"2.0.0\") // version >= \"2.0.0\"\n   *\n   * // Release date filters\n   * op.gte(\"releaseDate\", \"2024-01-01\") // releaseDate >= \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  gte: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a between condition for type-safe range comparison.\n   * Tests if the specified attribute value falls within the inclusive range [lower, upper].\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param lower - The lower bound of the range (inclusive, must match attribute type)\n   * @param upper - The upper bound of the range (inclusive, must match attribute type)\n   * @returns A condition that evaluates to true when lower ≤ attr ≤ upper\n   *\n   * @example\n   * ```typescript\n   * interface Event { price: number; date: string; priority: number; }\n   *\n   * // Price range\n   * op.between(\"price\", 50, 200) // price BETWEEN 50 AND 200\n   *\n   * // Date range\n   * op.between(\"date\", \"2024-01-01\", \"2024-12-31\") // date BETWEEN \"2024-01-01\" AND \"2024-12-31\"\n   *\n   * // Priority levels\n   * op.between(\"priority\", 1, 5) // priority BETWEEN 1 AND 5\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n   */\n  between: <K extends FlexiblePath<T>>(\n    attr: K,\n    lower: FlexiblePathType<T, K>,\n    upper: FlexiblePathType<T, K>,\n  ) => Condition;\n\n  /**\n   * Creates an IN condition for type-safe list membership testing.\n   * Tests if the specified attribute value matches any value in the provided list.\n   * Supports up to 100 values in the list as per DynamoDB limitations.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param values - Array of values to test against (must match attribute type, max 100 items)\n   * @returns A condition that evaluates to true when attr matches any value in the list\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; role: string; priority: number; }\n   *\n   * // Status filtering\n   * op.inArray(\"status\", [\"ACTIVE\", \"PENDING\", \"PROCESSING\"]) // status IN (\"ACTIVE\", \"PENDING\", \"PROCESSING\")\n   *\n   * // Role-based access\n   * op.inArray(\"role\", [\"admin\", \"moderator\", \"editor\"]) // role IN (\"admin\", \"moderator\", \"editor\")\n   *\n   * // Priority levels\n   * op.inArray(\"priority\", [1, 2, 3]) // priority IN (1, 2, 3)\n   * ```\n   *\n   * @throws {Error} When values array is empty or contains more than 100 items\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}\n   */\n  inArray: <K extends FlexiblePath<T>>(attr: K, values: FlexiblePathType<T, K>[]) => Condition;\n\n  /**\n   * Creates a begins_with condition for type-safe string prefix testing.\n   * Tests if the specified string attribute starts with the provided substring.\n   * Only works with string attributes - will fail on other data types.\n   *\n   * @param attr - The string attribute path to test (with full type safety)\n   * @param value - The prefix string to test for (must match attribute type)\n   * @returns A condition that evaluates to true when attr starts with value\n   *\n   * @example\n   * ```typescript\n   * interface User { email: string; name: string; id: string; }\n   *\n   * // Email domain filtering\n   * op.beginsWith(\"email\", \"admin@\") // begins_with(email, \"admin@\")\n   *\n   * // Name prefix search\n   * op.beginsWith(\"name\", \"John\") // begins_with(name, \"John\")\n   *\n   * // ID pattern matching\n   * op.beginsWith(\"id\", \"USER#\") // begins_with(id, \"USER#\")\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n   */\n  beginsWith: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a contains condition for type-safe substring or set membership testing.\n   * For strings: tests if the attribute contains the specified substring.\n   * For sets: tests if the set contains the specified element.\n   *\n   * @param attr - The attribute path to test (with full type safety)\n   * @param value - The substring or element to search for (must match attribute type)\n   * @returns A condition that evaluates to true when attr contains value\n   *\n   * @example\n   * ```typescript\n   * interface Post { content: string; tags: Set<string>; categories: string[]; }\n   *\n   * // Substring search in content\n   * op.contains(\"content\", \"important\") // contains(content, \"important\")\n   *\n   * // Tag membership (for DynamoDB String Sets)\n   * op.contains(\"tags\", \"featured\") // contains(tags, \"featured\")\n   *\n   * // Category search (for string arrays stored as lists)\n   * op.contains(\"categories\", \"technology\") // contains(categories, \"technology\")\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n   */\n  contains: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates an attribute_exists condition for type-safe attribute presence testing.\n   * Tests if the specified attribute exists in the item, regardless of its value.\n   * Useful for filtering items that have optional attributes populated.\n   *\n   * @param attr - The attribute path to test for existence (with full type safety)\n   * @returns A condition that evaluates to true when the attribute exists\n   *\n   * @example\n   * ```typescript\n   * interface User { email: string; phone?: string; profile?: { avatar?: string; }; }\n   *\n   * // Check for optional fields\n   * op.attributeExists(\"phone\") // attribute_exists(phone)\n   *\n   * // Check for nested optional attributes\n   * op.attributeExists(\"profile.avatar\") // attribute_exists(profile.avatar)\n   *\n   * // Useful in combination with other conditions\n   * op.and(\n   *   op.eq(\"status\", \"ACTIVE\"),\n   *   op.attributeExists(\"email\") // Only active users with email\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n   */\n  attributeExists: <K extends FlexiblePath<T>>(attr: K) => Condition;\n\n  /**\n   * Creates an attribute_not_exists condition for type-safe attribute absence testing.\n   * Tests if the specified attribute does not exist in the item.\n   * Useful for conditional writes to prevent overwriting existing data.\n   *\n   * @param attr - The attribute path to test for absence (with full type safety)\n   * @returns A condition that evaluates to true when the attribute does not exist\n   *\n   * @example\n   * ```typescript\n   * interface User { id: string; email: string; deletedAt?: string; }\n   *\n   * // Ensure item hasn't been soft-deleted\n   * op.attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n   *\n   * // Prevent duplicate creation\n   * op.attributeNotExists(\"id\") // attribute_not_exists(id)\n   *\n   * // Conditional updates\n   * op.and(\n   *   op.eq(\"status\", \"PENDING\"),\n   *   op.attributeNotExists(\"processedAt\") // Only unprocessed items\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n   */\n  attributeNotExists: <K extends FlexiblePath<T>>(attr: K) => Condition;\n\n  /**\n   * Combines multiple conditions with logical AND operator.\n   * All provided conditions must evaluate to true for the AND condition to be true.\n   * Supports any number of conditions as arguments.\n   *\n   * @param conditions - Variable number of conditions to combine with AND\n   * @returns A condition that evaluates to true when all input conditions are true\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; age: number; role: string; verified: boolean; }\n   *\n   * // Multiple criteria\n   * op.and(\n   *   op.eq(\"status\", \"ACTIVE\"),\n   *   op.gt(\"age\", 18),\n   *   op.eq(\"verified\", true)\n   * ) // status = \"ACTIVE\" AND age > 18 AND verified = true\n   *\n   * // Complex business logic\n   * op.and(\n   *   op.inArray(\"role\", [\"admin\", \"moderator\"]),\n   *   op.attributeExists(\"permissions\"),\n   *   op.ne(\"status\", \"SUSPENDED\")\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n   */\n  and: (...conditions: Condition[]) => Condition;\n\n  /**\n   * Combines multiple conditions with logical OR operator.\n   * At least one of the provided conditions must evaluate to true for the OR condition to be true.\n   * Supports any number of conditions as arguments.\n   *\n   * @param conditions - Variable number of conditions to combine with OR\n   * @returns A condition that evaluates to true when any input condition is true\n   *\n   * @example\n   * ```typescript\n   * interface Order { status: string; priority: string; urgent: boolean; }\n   *\n   * // Alternative statuses\n   * op.or(\n   *   op.eq(\"status\", \"PENDING\"),\n   *   op.eq(\"status\", \"PROCESSING\"),\n   *   op.eq(\"status\", \"SHIPPED\")\n   * ) // status = \"PENDING\" OR status = \"PROCESSING\" OR status = \"SHIPPED\"\n   *\n   * // High priority items\n   * op.or(\n   *   op.eq(\"priority\", \"HIGH\"),\n   *   op.eq(\"urgent\", true)\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n   */\n  or: (...conditions: Condition[]) => Condition;\n\n  /**\n   * Negates a condition with logical NOT operator.\n   * Inverts the boolean result of the provided condition.\n   *\n   * @param condition - The condition to negate\n   * @returns A condition that evaluates to true when the input condition is false\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; role: string; banned: boolean; }\n   *\n   * // Exclude specific status\n   * op.not(op.eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n   *\n   * // Complex negation\n   * op.not(\n   *   op.and(\n   *     op.eq(\"role\", \"guest\"),\n   *     op.eq(\"banned\", true)\n   *   )\n   * ) // NOT (role = \"guest\" AND banned = true)\n   *\n   * // Exclude multiple values\n   * op.not(op.inArray(\"status\", [\"DELETED\", \"ARCHIVED\"]))\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n   */\n  not: (condition: Condition) => Condition;\n};\n\n/**\n * Primary key type for QUERY operations.\n * Allows building complex key conditions for the sort key.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html AWS DynamoDB - Query Operations}\n *\n * @example\n * // Query items with a specific partition key and sort key prefix\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#2023\")\n * })\n *\n * @example\n * // Query items within a specific sort key range\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.between(\"ORDER#2023-01\", \"ORDER#2023-12\")\n * })\n */\nexport type PrimaryKey = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key condition builder */\n  sk?: (op: KeyConditionOperator) => Condition;\n};\n\n/**\n * Primary key type for GET and DELETE operations.\n * Used when you need to specify exact key values without conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html AWS DynamoDB - Working with Items}\n *\n * @example\n * // Get a specific item by its complete primary key\n * table.get({\n *   pk: \"USER#123\",\n *   sk: \"PROFILE#123\"\n * })\n *\n * @example\n * // Delete a specific item by its complete primary key\n * table.delete({\n *   pk: \"USER#123\",\n *   sk: \"ORDER#456\"\n * })\n */\nexport type PrimaryKeyWithoutExpression = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key value */\n  sk?: string;\n};\n"]}
+{"version":3,"sources":["../src/conditions.ts"],"names":[],"mappings":";AAiGO,IAAM,yBACX,GAAA,CAAC,IACD,KAAA,CAAC,MAAc,KAA+B,MAAA;AAAA,EAC5C,IAAA;AAAA,EACA,IAAA;AAAA,EACA;AACF,CAAA;AAQW,IAAA,EAAA,GAAK,0BAA0B,IAAI;AAQnC,IAAA,EAAA,GAAK,0BAA0B,IAAI;AAQnC,IAAA,EAAA,GAAK,0BAA0B,IAAI;AAQnC,IAAA,GAAA,GAAM,0BAA0B,KAAK;AAQrC,IAAA,EAAA,GAAK,0BAA0B,IAAI;AAQnC,IAAA,GAAA,GAAM,0BAA0B,KAAK;AAQ3C,IAAM,OAAU,GAAA,CAAC,IAAc,EAAA,KAAA,EAAgB,KAA+B,MAAA;AAAA,EACnF,IAAM,EAAA,SAAA;AAAA,EACN,IAAA;AAAA,EACA,KAAA,EAAO,CAAC,KAAA,EAAO,KAAK;AACtB,CAAA;AAQa,IAAA,OAAA,GAAU,CAAC,IAAA,EAAc,MAAkC,MAAA;AAAA,EACtE,IAAM,EAAA,IAAA;AAAA,EACN,IAAA;AAAA,EACA,KAAO,EAAA;AACT,CAAA;AAQa,IAAA,UAAA,GAAa,0BAA0B,YAAY;AAQnD,IAAA,QAAA,GAAW,0BAA0B,UAAU;AAQ/C,IAAA,eAAA,GAAkB,CAAC,IAA6B,MAAA;AAAA,EAC3D,IAAM,EAAA,iBAAA;AAAA,EACN;AACF,CAAA;AAQa,IAAA,kBAAA,GAAqB,CAAC,IAA6B,MAAA;AAAA,EAC9D,IAAM,EAAA,oBAAA;AAAA,EACN;AACF,CAAA;AAaa,IAAA,GAAA,GAAM,IAAI,UAAwC,MAAA;AAAA,EAC7D,IAAM,EAAA,KAAA;AAAA,EACN;AACF,CAAA;AAWa,IAAA,EAAA,GAAK,IAAI,UAAwC,MAAA;AAAA,EAC5D,IAAM,EAAA,IAAA;AAAA,EACN;AACF,CAAA;AAQa,IAAA,GAAA,GAAM,CAAC,SAAqC,MAAA;AAAA,EACvD,IAAM,EAAA,KAAA;AAAA,EACN;AACF,CAAA","file":"conditions.js","sourcesContent":["import type { Path, PathType } from \"./builders/types\";\nimport type { DynamoItem } from \"./types\";\n\n/**\n * Supported comparison operators for DynamoDB conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Comparison Operator Reference}\n *\n * - eq: Equals (=)\n * - ne: Not equals (≠ / <>)\n * - lt: Less than (<)\n * - lte: Less than or equal to (≤)\n * - gt: Greater than (>)\n * - gte: Greater than or equal to (≥)\n * - between: Between two values (inclusive)\n * - in: Checks if attribute value is in a list of values\n * - beginsWith: Checks if string attribute begins with specified substring\n * - contains: Checks if string/set attribute contains specified value\n * - attributeExists: Checks if attribute exists\n * - attributeNotExists: Checks if attribute does not exist\n */\nexport type ComparisonOperator =\n  | \"eq\"\n  | \"ne\"\n  | \"lt\"\n  | \"lte\"\n  | \"gt\"\n  | \"gte\"\n  | \"between\"\n  | \"in\"\n  | \"beginsWith\"\n  | \"contains\"\n  | \"attributeExists\"\n  | \"attributeNotExists\";\n\n/**\n * Logical operators for combining multiple conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - Logical Operator Reference}\n *\n * - and: Evaluates to true if all conditions are true\n * - or: Evaluates to true if any condition is true\n * - not: Negate the result of a condition\n */\nexport type LogicalOperator = \"and\" | \"or\" | \"not\";\n\n/**\n * Represents a DynamoDB condition expression.\n * Can be either a comparison condition or a logical combination of conditions.\n *\n * @example\n * // Simple comparison condition\n * const condition: Condition = {\n *   type: \"eq\",\n *   attr: \"status\",\n *   value: \"ACTIVE\"\n * };\n *\n * @example\n * // Logical combination of conditions\n * const condition: Condition = {\n *   type: \"and\",\n *   conditions: [\n *     { type: \"eq\", attr: \"status\", value: \"ACTIVE\" },\n *     { type: \"gt\", attr: \"age\", value: 5 }\n *   ]\n * };\n */\nexport interface Condition {\n  /** The type of condition (comparison or logical operator) */\n  type: ComparisonOperator | LogicalOperator;\n  /** The attribute name for comparison conditions */\n  attr?: string;\n  /** The value to compare against for comparison conditions */\n  value?: unknown;\n  /** Array of conditions for logical operators (and/or) */\n  conditions?: Condition[];\n  /** Single condition for the 'not' operator */\n  condition?: Condition;\n}\n\n/**\n * Parameters used to build DynamoDB expression strings.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}\n */\nexport interface ExpressionParams {\n  /** Map of attribute name placeholders to actual attribute names */\n  expressionAttributeNames: Record<string, string>;\n  /** Map of value placeholders to actual values */\n  expressionAttributeValues: DynamoItem;\n  /** Counter for generating unique value placeholders */\n  valueCounter: { count: number };\n}\n\n/**\n * Creates a comparison condition builder function for the specified operator.\n * @internal\n */\nexport const createComparisonCondition =\n  (type: ComparisonOperator) =>\n  (attr: string, value: unknown): Condition => ({\n    type,\n    attr,\n    value,\n  });\n\n/**\n * Creates an equals (=) condition\n * @example\n * eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const eq = createComparisonCondition(\"eq\");\n\n/**\n * Creates a not equals (≠) condition\n * @example\n * ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const ne = createComparisonCondition(\"ne\");\n\n/**\n * Creates a less than (<) condition\n * @example\n * lt(\"age\", 18) // age < 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lt = createComparisonCondition(\"lt\");\n\n/**\n * Creates a less than or equal to (≤) condition\n * @example\n * lte(\"age\", 18) // age <= 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lte = createComparisonCondition(\"lte\");\n\n/**\n * Creates a greater than (>) condition\n * @example\n * gt(\"price\", 100) // price > 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gt = createComparisonCondition(\"gt\");\n\n/**\n * Creates a greater than or equal to (≥) condition\n * @example\n * gte(\"price\", 100) // price >= 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gte = createComparisonCondition(\"gte\");\n\n/**\n * Creates a between condition that checks if a value is within a range (inclusive)\n * @example\n * between(\"age\", 18, 65) // age BETWEEN 18 AND 65\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n */\nexport const between = (attr: string, lower: unknown, upper: unknown): Condition => ({\n  type: \"between\",\n  attr,\n  value: [lower, upper],\n});\n\n/**\n * Creates an in condition that checks if a value is in a list of values\n * @example\n * inArray(\"status\", [\"ACTIVE\", \"PENDING\", \"PROCESSING\"]) // status IN (\"ACTIVE\", \"PENDING\", \"PROCESSING\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}\n */\nexport const inArray = (attr: string, values: unknown[]): Condition => ({\n  type: \"in\",\n  attr,\n  value: values,\n});\n\n/**\n * Creates a begins_with condition that checks if a string attribute starts with a substring\n * @example\n * beginsWith(\"email\", \"@example.com\") // begins_with(email, \"@example.com\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n */\nexport const beginsWith = createComparisonCondition(\"beginsWith\");\n\n/**\n * Creates a contains condition that checks if a string contains a substring or if a set contains an element\n * @example\n * contains(\"tags\", \"important\") // contains(tags, \"important\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n */\nexport const contains = createComparisonCondition(\"contains\");\n\n/**\n * Creates a condition that checks if an attribute exists\n * @example\n * attributeExists(\"email\") // attribute_exists(email)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n */\nexport const attributeExists = (attr: string): Condition => ({\n  type: \"attributeExists\",\n  attr,\n});\n\n/**\n * Creates a condition that checks if an attribute does not exist\n * @example\n * attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n */\nexport const attributeNotExists = (attr: string): Condition => ({\n  type: \"attributeNotExists\",\n  attr,\n});\n\n// --- Logical Operators ---\n\n/**\n * Combines multiple conditions with AND operator\n * @example\n * and(\n *   eq(\"status\", \"ACTIVE\"),\n *   gt(\"age\", 18)\n * ) // status = \"ACTIVE\" AND age > 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n */\nexport const and = (...conditions: Condition[]): Condition => ({\n  type: \"and\",\n  conditions,\n});\n\n/**\n * Combines multiple conditions with OR operator\n * @example\n * or(\n *   eq(\"status\", \"PENDING\"),\n *   eq(\"status\", \"PROCESSING\")\n * ) // status = \"PENDING\" OR status = \"PROCESSING\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n */\nexport const or = (...conditions: Condition[]): Condition => ({\n  type: \"or\",\n  conditions,\n});\n\n/**\n * Negates a condition\n * @example\n * not(eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n */\nexport const not = (condition: Condition): Condition => ({\n  type: \"not\",\n  condition,\n});\n\n/**\n * Type-safe operators for building key conditions in DynamoDB queries.\n * Only includes operators that are valid for key conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions AWS DynamoDB - Key Condition Expressions}\n *\n * @example\n * // Using with sort key conditions\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#\")\n * })\n */\nexport type KeyConditionOperator = {\n  /** Equals comparison for key attributes */\n  eq: (value: unknown) => Condition;\n  /** Less than comparison for key attributes */\n  lt: (value: unknown) => Condition;\n  /** Less than or equal comparison for key attributes */\n  lte: (value: unknown) => Condition;\n  /** Greater than comparison for key attributes */\n  gt: (value: unknown) => Condition;\n  /** Greater than or equal comparison for key attributes */\n  gte: (value: unknown) => Condition;\n  /** Between range comparison for key attributes */\n  between: (lower: unknown, upper: unknown) => Condition;\n  /** Begins with comparison for key attributes */\n  beginsWith: (value: unknown) => Condition;\n  /** Combines multiple key conditions with AND */\n  and: (...conditions: Condition[]) => Condition;\n};\n\n// Helper types that allow string paths and unknown values when strict typing can't be resolved\ntype FlexiblePath<T> = Path<T> extends never ? string : Path<T>;\n// biome-ignore lint: Using any as we don't really know if it's not provided\ntype FlexiblePathType<T, K extends keyof any> = PathType<T, K> extends never ? unknown : PathType<T, K>;\n\n/**\n * Type-safe operators for building conditions in DynamoDB operations.\n * Includes all available condition operators with proper type inference.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Condition Expressions}\n *\n * @example\n * // Using with type-safe conditions\n * interface User {\n *   status: string;\n *   age: number;\n *   email?: string;\n * }\n *\n * table.scan<User>()\n *   .where(op => op.and(\n *     op.eq(\"status\", \"ACTIVE\"),\n *     op.gt(\"age\", 18),\n *     op.attributeExists(\"email\")\n *   ))\n *\n * @template T The type of the item being operated on\n */\nexport type ConditionOperator<T extends DynamoItem> = {\n  /**\n   * Creates an equals (=) condition for type-safe attribute comparison.\n   * Tests if the specified attribute equals the provided value.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr equals value\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; age: number; }\n   *\n   * // String comparison\n   * op.eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n   *\n   * // Numeric comparison\n   * op.eq(\"age\", 25) // age = 25\n   *\n   * // Nested attribute\n   * op.eq(\"profile.role\", \"admin\") // profile.role = \"admin\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  eq: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a not equals (≠ / <>) condition for type-safe attribute comparison.\n   * Tests if the specified attribute does not equal the provided value.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr does not equal value\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; priority: number; }\n   *\n   * // String comparison\n   * op.ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n   *\n   * // Numeric comparison\n   * op.ne(\"priority\", 0) // priority <> 0\n   *\n   * // Useful for filtering out specific values\n   * op.ne(\"category\", \"ARCHIVED\") // category <> \"ARCHIVED\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  ne: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a less than (<) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is less than the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is less than value\n   *\n   * @example\n   * ```typescript\n   * interface Product { price: number; name: string; createdAt: string; }\n   *\n   * // Numeric comparison\n   * op.lt(\"price\", 100) // price < 100\n   *\n   * // String comparison (lexicographic)\n   * op.lt(\"name\", \"M\") // name < \"M\" (names starting with A-L)\n   *\n   * // Date comparison (ISO strings)\n   * op.lt(\"createdAt\", \"2024-01-01\") // createdAt < \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  lt: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a less than or equal to (≤) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is less than or equal to the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is less than or equal to value\n   *\n   * @example\n   * ```typescript\n   * interface Order { total: number; priority: number; dueDate: string; }\n   *\n   * // Numeric comparison\n   * op.lte(\"total\", 1000) // total <= 1000\n   *\n   * // Priority levels\n   * op.lte(\"priority\", 3) // priority <= 3 (low to medium priority)\n   *\n   * // Date deadlines\n   * op.lte(\"dueDate\", \"2024-12-31\") // dueDate <= \"2024-12-31\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  lte: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a greater than (>) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is greater than the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is greater than value\n   *\n   * @example\n   * ```typescript\n   * interface User { age: number; score: number; lastLogin: string; }\n   *\n   * // Age restrictions\n   * op.gt(\"age\", 18) // age > 18 (adults only)\n   *\n   * // Performance thresholds\n   * op.gt(\"score\", 85) // score > 85 (high performers)\n   *\n   * // Recent activity\n   * op.gt(\"lastLogin\", \"2024-01-01\") // lastLogin > \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  gt: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a greater than or equal to (≥) condition for type-safe attribute comparison.\n   * Tests if the specified attribute is greater than or equal to the provided value.\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param value - The value to compare against (must match attribute type)\n   * @returns A condition that evaluates to true when attr is greater than or equal to value\n   *\n   * @example\n   * ```typescript\n   * interface Product { rating: number; version: string; releaseDate: string; }\n   *\n   * // Minimum ratings\n   * op.gte(\"rating\", 4.0) // rating >= 4.0 (highly rated)\n   *\n   * // Version requirements\n   * op.gte(\"version\", \"2.0.0\") // version >= \"2.0.0\"\n   *\n   * // Release date filters\n   * op.gte(\"releaseDate\", \"2024-01-01\") // releaseDate >= \"2024-01-01\"\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - Comparison Operators}\n   */\n  gte: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a between condition for type-safe range comparison.\n   * Tests if the specified attribute value falls within the inclusive range [lower, upper].\n   * Works with numbers, strings (lexicographic), and dates.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param lower - The lower bound of the range (inclusive, must match attribute type)\n   * @param upper - The upper bound of the range (inclusive, must match attribute type)\n   * @returns A condition that evaluates to true when lower ≤ attr ≤ upper\n   *\n   * @example\n   * ```typescript\n   * interface Event { price: number; date: string; priority: number; }\n   *\n   * // Price range\n   * op.between(\"price\", 50, 200) // price BETWEEN 50 AND 200\n   *\n   * // Date range\n   * op.between(\"date\", \"2024-01-01\", \"2024-12-31\") // date BETWEEN \"2024-01-01\" AND \"2024-12-31\"\n   *\n   * // Priority levels\n   * op.between(\"priority\", 1, 5) // priority BETWEEN 1 AND 5\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n   */\n  between: <K extends FlexiblePath<T>>(\n    attr: K,\n    lower: FlexiblePathType<T, K>,\n    upper: FlexiblePathType<T, K>,\n  ) => Condition;\n\n  /**\n   * Creates an IN condition for type-safe list membership testing.\n   * Tests if the specified attribute value matches any value in the provided list.\n   * Supports up to 100 values in the list as per DynamoDB limitations.\n   *\n   * @param attr - The attribute path to compare (with full type safety)\n   * @param values - Array of values to test against (must match attribute type, max 100 items)\n   * @returns A condition that evaluates to true when attr matches any value in the list\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; role: string; priority: number; }\n   *\n   * // Status filtering\n   * op.inArray(\"status\", [\"ACTIVE\", \"PENDING\", \"PROCESSING\"]) // status IN (\"ACTIVE\", \"PENDING\", \"PROCESSING\")\n   *\n   * // Role-based access\n   * op.inArray(\"role\", [\"admin\", \"moderator\", \"editor\"]) // role IN (\"admin\", \"moderator\", \"editor\")\n   *\n   * // Priority levels\n   * op.inArray(\"priority\", [1, 2, 3]) // priority IN (1, 2, 3)\n   * ```\n   *\n   * @throws {Error} When values array is empty or contains more than 100 items\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - IN}\n   */\n  inArray: <K extends FlexiblePath<T>>(attr: K, values: FlexiblePathType<T, K>[]) => Condition;\n\n  /**\n   * Creates a begins_with condition for type-safe string prefix testing.\n   * Tests if the specified string attribute starts with the provided substring.\n   * Only works with string attributes - will fail on other data types.\n   *\n   * @param attr - The string attribute path to test (with full type safety)\n   * @param value - The prefix string to test for (must match attribute type)\n   * @returns A condition that evaluates to true when attr starts with value\n   *\n   * @example\n   * ```typescript\n   * interface User { email: string; name: string; id: string; }\n   *\n   * // Email domain filtering\n   * op.beginsWith(\"email\", \"admin@\") // begins_with(email, \"admin@\")\n   *\n   * // Name prefix search\n   * op.beginsWith(\"name\", \"John\") // begins_with(name, \"John\")\n   *\n   * // ID pattern matching\n   * op.beginsWith(\"id\", \"USER#\") // begins_with(id, \"USER#\")\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n   */\n  beginsWith: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates a contains condition for type-safe substring or set membership testing.\n   * For strings: tests if the attribute contains the specified substring.\n   * For sets: tests if the set contains the specified element.\n   *\n   * @param attr - The attribute path to test (with full type safety)\n   * @param value - The substring or element to search for (must match attribute type)\n   * @returns A condition that evaluates to true when attr contains value\n   *\n   * @example\n   * ```typescript\n   * interface Post { content: string; tags: Set<string>; categories: string[]; }\n   *\n   * // Substring search in content\n   * op.contains(\"content\", \"important\") // contains(content, \"important\")\n   *\n   * // Tag membership (for DynamoDB String Sets)\n   * op.contains(\"tags\", \"featured\") // contains(tags, \"featured\")\n   *\n   * // Category search (for string arrays stored as lists)\n   * op.contains(\"categories\", \"technology\") // contains(categories, \"technology\")\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n   */\n  contains: <K extends FlexiblePath<T>>(attr: K, value: FlexiblePathType<T, K>) => Condition;\n\n  /**\n   * Creates an attribute_exists condition for type-safe attribute presence testing.\n   * Tests if the specified attribute exists in the item, regardless of its value.\n   * Useful for filtering items that have optional attributes populated.\n   *\n   * @param attr - The attribute path to test for existence (with full type safety)\n   * @returns A condition that evaluates to true when the attribute exists\n   *\n   * @example\n   * ```typescript\n   * interface User { email: string; phone?: string; profile?: { avatar?: string; }; }\n   *\n   * // Check for optional fields\n   * op.attributeExists(\"phone\") // attribute_exists(phone)\n   *\n   * // Check for nested optional attributes\n   * op.attributeExists(\"profile.avatar\") // attribute_exists(profile.avatar)\n   *\n   * // Useful in combination with other conditions\n   * op.and(\n   *   op.eq(\"status\", \"ACTIVE\"),\n   *   op.attributeExists(\"email\") // Only active users with email\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n   */\n  attributeExists: <K extends FlexiblePath<T>>(attr: K) => Condition;\n\n  /**\n   * Creates an attribute_not_exists condition for type-safe attribute absence testing.\n   * Tests if the specified attribute does not exist in the item.\n   * Useful for conditional writes to prevent overwriting existing data.\n   *\n   * @param attr - The attribute path to test for absence (with full type safety)\n   * @returns A condition that evaluates to true when the attribute does not exist\n   *\n   * @example\n   * ```typescript\n   * interface User { id: string; email: string; deletedAt?: string; }\n   *\n   * // Ensure item hasn't been soft-deleted\n   * op.attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n   *\n   * // Prevent duplicate creation\n   * op.attributeNotExists(\"id\") // attribute_not_exists(id)\n   *\n   * // Conditional updates\n   * op.and(\n   *   op.eq(\"status\", \"PENDING\"),\n   *   op.attributeNotExists(\"processedAt\") // Only unprocessed items\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n   */\n  attributeNotExists: <K extends FlexiblePath<T>>(attr: K) => Condition;\n\n  /**\n   * Combines multiple conditions with logical AND operator.\n   * All provided conditions must evaluate to true for the AND condition to be true.\n   * Supports any number of conditions as arguments.\n   *\n   * @param conditions - Variable number of conditions to combine with AND\n   * @returns A condition that evaluates to true when all input conditions are true\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; age: number; role: string; verified: boolean; }\n   *\n   * // Multiple criteria\n   * op.and(\n   *   op.eq(\"status\", \"ACTIVE\"),\n   *   op.gt(\"age\", 18),\n   *   op.eq(\"verified\", true)\n   * ) // status = \"ACTIVE\" AND age > 18 AND verified = true\n   *\n   * // Complex business logic\n   * op.and(\n   *   op.inArray(\"role\", [\"admin\", \"moderator\"]),\n   *   op.attributeExists(\"permissions\"),\n   *   op.ne(\"status\", \"SUSPENDED\")\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n   */\n  and: (...conditions: Condition[]) => Condition;\n\n  /**\n   * Combines multiple conditions with logical OR operator.\n   * At least one of the provided conditions must evaluate to true for the OR condition to be true.\n   * Supports any number of conditions as arguments.\n   *\n   * @param conditions - Variable number of conditions to combine with OR\n   * @returns A condition that evaluates to true when any input condition is true\n   *\n   * @example\n   * ```typescript\n   * interface Order { status: string; priority: string; urgent: boolean; }\n   *\n   * // Alternative statuses\n   * op.or(\n   *   op.eq(\"status\", \"PENDING\"),\n   *   op.eq(\"status\", \"PROCESSING\"),\n   *   op.eq(\"status\", \"SHIPPED\")\n   * ) // status = \"PENDING\" OR status = \"PROCESSING\" OR status = \"SHIPPED\"\n   *\n   * // High priority items\n   * op.or(\n   *   op.eq(\"priority\", \"HIGH\"),\n   *   op.eq(\"urgent\", true)\n   * )\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n   */\n  or: (...conditions: Condition[]) => Condition;\n\n  /**\n   * Negates a condition with logical NOT operator.\n   * Inverts the boolean result of the provided condition.\n   *\n   * @param condition - The condition to negate\n   * @returns A condition that evaluates to true when the input condition is false\n   *\n   * @example\n   * ```typescript\n   * interface User { status: string; role: string; banned: boolean; }\n   *\n   * // Exclude specific status\n   * op.not(op.eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n   *\n   * // Complex negation\n   * op.not(\n   *   op.and(\n   *     op.eq(\"role\", \"guest\"),\n   *     op.eq(\"banned\", true)\n   *   )\n   * ) // NOT (role = \"guest\" AND banned = true)\n   *\n   * // Exclude multiple values\n   * op.not(op.inArray(\"status\", [\"DELETED\", \"ARCHIVED\"]))\n   * ```\n   *\n   * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n   */\n  not: (condition: Condition) => Condition;\n};\n\n/**\n * Primary key type for QUERY operations.\n * Allows building complex key conditions for the sort key.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html AWS DynamoDB - Query Operations}\n *\n * @example\n * // Query items with a specific partition key and sort key prefix\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#2023\")\n * })\n *\n * @example\n * // Query items within a specific sort key range\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.between(\"ORDER#2023-01\", \"ORDER#2023-12\")\n * })\n */\nexport type PrimaryKey = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key condition builder */\n  sk?: (op: KeyConditionOperator) => Condition;\n};\n\n/**\n * Primary key type for GET and DELETE operations.\n * Used when you need to specify exact key values without conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html AWS DynamoDB - Working with Items}\n *\n * @example\n * // Get a specific item by its complete primary key\n * table.get({\n *   pk: \"USER#123\",\n *   sk: \"PROFILE#123\"\n * })\n *\n * @example\n * // Delete a specific item by its complete primary key\n * table.delete({\n *   pk: \"USER#123\",\n *   sk: \"ORDER#456\"\n * })\n */\nexport type PrimaryKeyWithoutExpression = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key value */\n  sk?: string;\n};\n"]}

package/dist/entity.cjs

@@ -1,13 +1,5 @@
 'use strict';
 
-// src/conditions.ts
-var createComparisonCondition = (type) => (attr, value) => ({
-  type,
-  attr,
-  value
-});
-var eq = createComparisonCondition("eq");
-
 // src/builders/entity-aware-builders.ts
 function createEntityAwareBuilder(builder, entityName) {
   return new Proxy(builder, {
@@ -36,27 +28,141 @@ function createEntityAwareDeleteBuilder(builder, entityName) {
   return createEntityAwareBuilder(builder, entityName);
 }
 
-// src/entity.ts
-function defineEntity(config) {
-  const entityTypeAttributeName = config.settings?.entityTypeAttributeName ?? "entityType";
-  const buildIndexes = (dataForKeyGeneration, table) => {
-    return Object.entries(config.indexes ?? {}).reduce(
-      (acc, [indexName, index]) => {
-        const key = index.generateKey(dataForKeyGeneration);
-        const gsiConfig = table.gsis[indexName];
+// src/conditions.ts
+var createComparisonCondition = (type) => (attr, value) => ({
+  type,
+  attr,
+  value
+});
+var eq = createComparisonCondition("eq");
+
+// src/entity/ddb-indexing.ts
+var IndexBuilder = class {
+  /**
+   * Creates a new IndexBuilder instance
+   *
+   * @param table - The DynamoDB table instance
+   * @param indexes - The index definitions
+   */
+  constructor(table, indexes = {}) {
+    this.table = table;
+    this.indexes = indexes;
+  }
+  /**
+   * Build index attributes for item creation
+   *
+   * @param item - The item to generate indexes for
+   * @param options - Options for building indexes
+   * @returns Record of GSI attribute names to their values
+   */
+  buildForCreate(item, options = {}) {
+    const attributes = {};
+    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
+      if (options.excludeReadOnly && indexDef.isReadOnly) {
+        continue;
+      }
+      const key = indexDef.generateKey(item);
+      const gsiConfig = this.table.gsis[indexName];
+      if (!gsiConfig) {
+        throw new Error(`GSI configuration not found for index: ${indexName}`);
+      }
+      if (key.pk) {
+        attributes[gsiConfig.partitionKey] = key.pk;
+      }
+      if (key.sk && gsiConfig.sortKey) {
+        attributes[gsiConfig.sortKey] = key.sk;
+      }
+    }
+    return attributes;
+  }
+  /**
+   * Build index attributes for item updates
+   *
+   * @param currentData - The current data before update
+   * @param updates - The update data
+   * @param options - Options for building indexes
+   * @returns Record of GSI attribute names to their updated values
+   */
+  buildForUpdate(currentData, updates) {
+    const attributes = {};
+    const updatedItem = { ...currentData, ...updates };
+    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
+      if (indexDef.isReadOnly) {
+        continue;
+      }
+      let shouldUpdateIndex = false;
+      try {
+        const currentKey = indexDef.generateKey(currentData);
+        const updatedKey = indexDef.generateKey(updatedItem);
+        if (currentKey.pk !== updatedKey.pk || currentKey.sk !== updatedKey.sk) {
+          shouldUpdateIndex = true;
+        }
+      } catch {
+        shouldUpdateIndex = true;
+      }
+      if (!shouldUpdateIndex) {
+        continue;
+      }
+      try {
+        const key = indexDef.generateKey(updatedItem);
+        if (this.hasUndefinedValues(key)) {
+          throw new Error(
+            `Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be marked as readOnly.`
+          );
+        }
+        const gsiConfig = this.table.gsis[indexName];
         if (!gsiConfig) {
           throw new Error(`GSI configuration not found for index: ${indexName}`);
         }
         if (key.pk) {
-          acc[gsiConfig.partitionKey] = key.pk;
+          attributes[gsiConfig.partitionKey] = key.pk;
         }
         if (key.sk && gsiConfig.sortKey) {
-          acc[gsiConfig.sortKey] = key.sk;
+          attributes[gsiConfig.sortKey] = key.sk;
+        }
+      } catch (error) {
+        if (error instanceof Error && error.message.includes("insufficient data")) {
+          throw error;
         }
-        return acc;
-      },
-      {}
-    );
+        throw new Error(
+          `Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be readOnly.`
+        );
+      }
+    }
+    return attributes;
+  }
+  /**
+   * Check if a key has undefined values
+   *
+   * @param key - The index key to check
+   * @returns True if the key contains undefined values, false otherwise
+   */
+  hasUndefinedValues(key) {
+    return (key.pk?.includes("undefined") ?? false) || (key.sk?.includes("undefined") ?? false);
+  }
+};
+
+// src/entity/index-utils.ts
+function buildIndexes(dataForKeyGeneration, table, indexes, excludeReadOnly = false) {
+  if (!indexes) {
+    return {};
+  }
+  const indexBuilder = new IndexBuilder(table, indexes);
+  return indexBuilder.buildForCreate(dataForKeyGeneration, { excludeReadOnly });
+}
+function buildIndexUpdates(currentData, updates, table, indexes) {
+  if (!indexes) {
+    return {};
+  }
+  const indexBuilder = new IndexBuilder(table, indexes);
+  return indexBuilder.buildForUpdate(currentData, updates);
+}
+
+// src/entity/entity.ts
+function defineEntity(config) {
+  const entityTypeAttributeName = config.settings?.entityTypeAttributeName ?? "entityType";
+  const buildIndexes2 = (dataForKeyGeneration, table, excludeReadOnly = false) => {
+    return buildIndexes(dataForKeyGeneration, table, config.indexes, excludeReadOnly);
   };
   const wrapMethodWithPreparation = (originalMethod, prepareFn, context) => {
     const wrappedMethod = (...args) => {
@@ -108,7 +214,7 @@ function defineEntity(config) {
               ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
             };
             const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table);
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               ...dataForKeyGeneration,
               [entityTypeAttributeName]: config.name,
@@ -134,7 +240,7 @@ function defineEntity(config) {
               ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
             };
             const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table);
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               ...dataForKeyGeneration,
               [entityTypeAttributeName]: config.name,
@@ -176,7 +282,7 @@ function defineEntity(config) {
               ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
             };
             const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table);
+            const indexes = buildIndexes2(dataForKeyGeneration, table, false);
             const validatedItem = {
               [table.partitionKey]: primaryKey.pk,
               ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
@@ -202,7 +308,7 @@ function defineEntity(config) {
               ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
             };
             const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table);
+            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               [table.partitionKey]: primaryKey.pk,
               ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
@@ -236,13 +342,21 @@ function defineEntity(config) {
           }
           return createEntityAwarePutBuilder(builder, config.name);
         },
-        get: (key) => createEntityAwareGetBuilder(table.get(config.primaryKey.generateKey(key)), config.name),
+        get: (key) => {
+          return createEntityAwareGetBuilder(table.get(config.primaryKey.generateKey(key)), config.name);
+        },
         update: (key, data) => {
           const primaryKeyObj = config.primaryKey.generateKey(key);
           const builder = table.update(primaryKeyObj);
           builder.condition(eq(entityTypeAttributeName, config.name));
           const timestamps = generateTimestamps(["updatedAt"], data);
-          builder.set({ ...data, ...timestamps });
+          const indexUpdates = buildIndexUpdates(
+            { ...key },
+            { ...data, ...timestamps },
+            table,
+            config.indexes
+          );
+          builder.set({ ...data, ...timestamps, ...indexUpdates });
           return builder;
         },
         delete: (key) => {
@@ -313,21 +427,57 @@ function createQueries() {
 }
 function createIndex() {
   return {
-    input: (schema) => ({
-      partitionKey: (pkFn) => ({
-        sortKey: (skFn) => ({
-          name: "custom",
-          partitionKey: "pk",
-          sortKey: "sk",
-          generateKey: (item) => ({ pk: pkFn(item), sk: skFn(item) })
+    input: (schema) => {
+      const createIndexBuilder = (isReadOnly = false) => ({
+        partitionKey: (pkFn) => ({
+          sortKey: (skFn) => {
+            const index = {
+              name: "custom",
+              partitionKey: "pk",
+              sortKey: "sk",
+              isReadOnly,
+              generateKey: (item) => {
+                const data = schema["~standard"].validate(item);
+                if ("issues" in data && data.issues) {
+                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
+                }
+                const validData = "value" in data ? data.value : item;
+                return { pk: pkFn(validData), sk: skFn(validData) };
+              }
+            };
+            return Object.assign(index, {
+              readOnly: (value = false) => ({
+                ...index,
+                isReadOnly: value
+              })
+            });
+          },
+          withoutSortKey: () => {
+            const index = {
+              name: "custom",
+              partitionKey: "pk",
+              isReadOnly,
+              generateKey: (item) => {
+                const data = schema["~standard"].validate(item);
+                if ("issues" in data && data.issues) {
+                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
+                }
+                const validData = "value" in data ? data.value : item;
+                return { pk: pkFn(validData) };
+              }
+            };
+            return Object.assign(index, {
+              readOnly: (value = true) => ({
+                ...index,
+                isReadOnly: value
+              })
+            });
+          }
         }),
-        withoutSortKey: () => ({
-          name: "custom",
-          partitionKey: "pk",
-          generateKey: (item) => ({ pk: pkFn(item) })
-        })
-      })
-    })
+        readOnly: (value = true) => createIndexBuilder(value)
+      });
+      return createIndexBuilder(false);
+    }
   };
 }