DDB Mapper filter expressions (runtime components) (#1401)

Author: ianbotsf

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
 kotlin-version = "2.0.10"
-ksp-version = "2.0.0-1.0.24" # Keep in sync with kotlin-version
+ksp-version = "2.0.10-1.0.24" # Keep in sync with kotlin-version
 
 dokka-version = "1.9.10"
 
@@ -29,7 +29,6 @@ slf4j-version = "2.0.9"
 [libraries]
 aws-kotlin-repo-tools-build-support = { module="aws.sdk.kotlin.gradle:build-support", version.ref = "aws-kotlin-repo-tools-version" }
 
-kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin-version" }
 kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin-version" }
 kotlin-stdlib-jdk8 = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8", version.ref = "kotlin-version" }
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin-version" }

hll/dynamodb-mapper/dynamodb-mapper/api/dynamodb-mapper.api

@@ -34,7 +34,6 @@ kotlin {
 
         commonTest {
             dependencies {
-                implementation(libs.kotlin.reflect)
                 implementation(libs.kotlinx.coroutines.test)
                 implementation(libs.kotest.assertions.core)
                 implementation(libs.kotest.runner.junit5)

hll/dynamodb-mapper/dynamodb-mapper/build.gradle.kts

@@ -0,0 +1,27 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.AndExprImpl
+
+/**
+ * Represents an `AND` expression as described in
+ * [DynamoDB's **logical evaluations** documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.LogicalEvaluations).
+ * This expression will be true if `(operand[0] && operand[1] && ... && operand[n - 1])`.
+ */
+public interface AndExpr : BooleanExpr {
+    /**
+     * A list of 2 or more [BooleanExpr] conditions which are ANDed together
+     */
+    public val operands: List<BooleanExpr>
+
+    override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
+}
+
+/**
+ * Creates a new [AndExpr] with the given [operands]
+ * @param operands A list of 2 or more [BooleanExpr] conditions which are ANDed together
+ */
+public fun AndExpr(operands: List<BooleanExpr>): AndExpr = AndExprImpl(operands)

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/AndExpr.kt

@@ -0,0 +1,75 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.AttrPathIndexImpl
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.AttrPathNameImpl
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.AttributePathImpl
+
+/**
+ * Represents an element in an [AttributePath]
+ */
+public sealed interface AttrPathElement {
+    /**
+     * Represents the name of a top-level attribute or a key in a map
+     */
+    public interface Name : AttrPathElement {
+        /**
+         * The name or key of this element
+         */
+        public val name: String
+    }
+
+    /**
+     * Represents an index into a list/set
+     */
+    public interface Index : AttrPathElement {
+        /**
+         * The index (starting at `0`)
+         */
+        public val index: Int
+    }
+}
+
+/**
+ * Represents an expression that consists of an attribute. Attributes are referenced by attribute paths, analogous to
+ * [document paths in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Attributes.html#Expressions.Attributes.NestedElements.DocumentPathExamples).
+ * Attribute paths consist of one or more elements, which are either names (e.g., of a top-level attribute or a nested
+ * key in a map attribute) or indices (i.e., into a list). The first (and often only) element of an attribute path is a
+ * name.
+ *
+ * See [Filter] for more information about creating references to attributes.
+ */
+public interface AttributePath : Expression {
+    /**
+     * The [AttrPathElement] for this path
+     */
+    public val element: AttrPathElement
+
+    /**
+     * The parent [AttributePath] (if any). If [parent] is `null` then this instance represents a top-level attribute
+     * and [element] must be a name (not an index).
+     */
+    public val parent: AttributePath?
+
+    override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
+}
+
+/**
+ * Creates a new [AttributePath] reference with the given name and optional parent path
+ * @param name The name or key of this element
+ * @param parent The parent [AttributePath] (if any) of this element. If [parent] is `null` then this instance
+ * represents a top-level attribute.
+ */
+public fun AttributePath(name: String, parent: AttributePath? = null): AttributePath =
+    AttributePathImpl(AttrPathNameImpl(name), parent)
+
+/**
+ * Creates a new [AttributePath] reference with the given index and parent path
+ * @param index The index (starting at `0`) of this element
+ * @param parent The parent [AttributePath] of this element
+ */
+public fun AttributePath(index: Int, parent: AttributePath): AttributePath =
+    AttributePathImpl(AttrPathIndexImpl(index), parent)

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/AttributePath.kt

@@ -0,0 +1,62 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+/**
+ * Represents a
+ * [DynamoDB attribute data type](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
+ * @param abbreviation The DynamoDB type name
+ */
+public enum class AttributeType(public val abbreviation: kotlin.String) {
+    /**
+     * Binary data type, denoted in DynamoDB as `B`
+     */
+    Binary("B"),
+
+    /**
+     * Binary set data type, denoted in DynamoDB as `BS`
+     */
+    BinarySet("BS"),
+
+    /**
+     * Boolean data type, denoted in DynamoDB as `BOOL`
+     */
+    Boolean("BOOL"),
+
+    /**
+     * List data type, denoted in DynamoDB as `L`
+     */
+    List("L"),
+
+    /**
+     * Map data type, denoted in DynamoDB as `M`
+     */
+    Map("M"),
+
+    /**
+     * Null data type, denoted in DynamoDB as `NULL`
+     */
+    Null("NULL"),
+
+    /**
+     * Number data type, denoted in DynamoDB as `N`
+     */
+    Number("N"),
+
+    /**
+     * Number set data type, denoted in DynamoDB as `NS`
+     */
+    NumberSet("NS"),
+
+    /**
+     * String data type, denoted in DynamoDB as `S`
+     */
+    String("S"),
+
+    /**
+     * String set data type, denoted in DynamoDB as `SS`
+     */
+    StringSet("SS"),
+}

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/AttributeType.kt

@@ -0,0 +1,40 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.BetweenExprImpl
+
+/**
+ * Represents a `BETWEEN` expression as described in
+ * [DynamoDB's **making comparisons** documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators).
+ * This expression will be true if `value >= min && value <= max`.
+ */
+public interface BetweenExpr : BooleanExpr {
+    /**
+     * The value being compared to the [min] and [max]
+     */
+    public val value: Expression
+
+    /**
+     * The minimum bound for the comparison
+     */
+    public val min: Expression
+
+    /**
+     * The maximum bound for the comparison
+     */
+    public val max: Expression
+
+    override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
+}
+
+/**
+ * Creates a new [BetweenExpr] for the given [value] and range bounded by [min] and [max]
+ * @param value The value being compared to the [min] and [max]
+ * @param min The minimum bound for the comparison
+ * @param max The maximum bound for the comparison
+ */
+public fun BetweenExpr(value: Expression, min: Expression, max: Expression): BetweenExpr =
+    BetweenExprImpl(value, min, max)

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/BetweenExpr.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+/**
+ * Identifies a
+ * [DynamoDB expression function](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)
+ * which returns a boolean value
+ * @param exprString The literal name of the function to use in expression strings
+ */
+public enum class BooleanFunc(public val exprString: String) {
+    /**
+     * The `attribute_exist` function
+     */
+    ATTRIBUTE_EXISTS("attribute_exists"),
+
+    /**
+     * The `attribute_not_exists` function
+     */
+    ATTRIBUTE_NOT_EXISTS("attribute_not_exists"),
+
+    /**
+     * The `attribute_type` function
+     */
+    ATTRIBUTE_TYPE("attribute_type"),
+
+    /**
+     * The `begins_with` function
+     */
+    BEGINS_WITH("begins_with"),
+
+    /**
+     * The `contains` function
+     */
+    CONTAINS("contains"),
+}

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/BooleanFunc.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+import aws.sdk.kotlin.hll.dynamodbmapper.expressions.internal.BooleanFuncExprImpl
+
+/**
+ * Represents a function expression that yields a boolean result as described in
+ * [DynamoDB's **function** documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)
+ */
+public interface BooleanFuncExpr : BooleanExpr {
+    /**
+     * The specific boolean function to use
+     */
+    public val func: BooleanFunc
+
+    /**
+     * The attribute path to pass as the function's first argument
+     */
+    public val path: AttributePath
+
+    /**
+     * Any additional arguments used by the function
+     */
+    public val additionalOperands: List<Expression>
+
+    override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
+}
+
+/**
+ * Creates a new boolean function expression
+ * @param func The specific boolean function to use
+ * @param path The attribute path to pass as the function's first argument
+ * @param additionalOperands Any additional arguments used by the function
+ */
+public fun BooleanFuncExpr(
+    func: BooleanFunc,
+    path: AttributePath,
+    additionalOperands: List<Expression> = listOf(),
+): BooleanFuncExpr = BooleanFuncExprImpl(func, path, additionalOperands)
+
+/**
+ * Creates a new boolean function expression
+ * @param func The specific boolean function to use
+ * @param path The attribute path to pass as the function's first argument
+ * @param additionalOperands Any additional arguments used by the function
+ */
+public fun BooleanFuncExpr(
+    func: BooleanFunc,
+    path: AttributePath,
+    vararg additionalOperands: Expression,
+): BooleanFuncExpr = BooleanFuncExprImpl(func, path, additionalOperands.toList())

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/BooleanFuncExpr.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.hll.dynamodbmapper.expressions
+
+/**
+ * Identifies a comparison operator to use in an expression
+ * @param exprString The literal value of the operator to use in an expression string
+ */
+public enum class Comparator(public val exprString: String) {
+    /**
+     * An equality comparison, equivalent to `==` in Kotlin and to `=` in DynamoDB
+     */
+    EQUALS("="),
+
+    /**
+     * An inequality comparison, equivalent to `!=` in Kotlin and to `<>` in DynamoDB
+     */
+    NOT_EQUALS("<>"),
+
+    /**
+     * A less-than comparison, equivalent to `<` in Kotlin and DynamoDB
+     */
+    LESS_THAN("<"),
+
+    /**
+     * A less-than-or-equal-to comparison, equivalent to `<=` in Kotlin and DynamoDB
+     */
+    LESS_THAN_OR_EQUAL("<="),
+
+    /**
+     * A greater-than comparison, equivalent to `>` in Kotlin and DynamoDB
+     */
+    GREATER_THAN(">"),
+
+    /**
+     * A greater-than-or-equal-to comparison, equivalent to `>=` in Kotlin and DynamoDB
+     */
+    GREATER_THAN_OR_EQUAL(">="),
+}