Simplify and document coalesce

Author: mtdowling

docs/source-2.0/additional-specs/rules-engine/standard-library.rst

@@ -38,6 +38,54 @@ parameter is equal to the value ``false``:
     }
 
 
+.. _rules-engine-standard-library-coalesce:
+
+``coalesce`` function
+=====================
+
+Summary
+    Evaluates the first argument and returns the result if it is present, otherwise evaluates and returns the result
+    of the second argument.
+Argument types
+    * value1: ``T`` or ``option<T>``
+    * value2: ``T`` or ``option<T>``
+Return type
+    * ``coalesce(T, T)`` → ``T``
+    * ``coalesce(option<T>, T)`` → ``T``
+    * ``coalesce(T, option<T>)`` → ``T``
+    * ``coalesce(option<T>, option<T>)`` → ``option<T>``
+Since
+    1.1
+
+The ``coalesce`` function provides null-safe chaining by returning the result of the first argument if it returns a
+value, otherwise returns the result of the second argument. This is particularly useful for providing default values
+for optional parameters, chaining multiple optional values together, and related optimizations.
+
+The following example demonstrates chaining multiple ``coalesce`` calls to try several optional values
+in sequence:
+
+.. code-block:: json
+
+    {
+        "fn": "coalesce",
+        "argv": [
+            {"ref": "customEndpoint"},
+            {
+                "fn": "coalesce",
+                "argv": [
+                    {"ref": "regionalEndpoint"},
+                    {"ref": "defaultEndpoint"}
+                ]
+            }
+        ]
+    }
+
+.. important::
+    Both arguments must be of the same type after unwrapping any optionals (types are known at compile time and do not
+    need to be validated at runtime). Note that the first result is returned even if it's ``false`` (coalesce is
+    looking for a *non-empty* value).
+
+
 .. _rules-engine-standard-library-getAttr:
 
 ``getAttr`` function

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/syntax/expressions/functions/Coalesce.java

@@ -7,7 +7,6 @@
 import java.util.Arrays;
 import java.util.List;
 import software.amazon.smithy.rulesengine.language.evaluation.Scope;
-import software.amazon.smithy.rulesengine.language.evaluation.type.AnyType;
 import software.amazon.smithy.rulesengine.language.evaluation.type.OptionalType;
 import software.amazon.smithy.rulesengine.language.evaluation.type.Type;
 import software.amazon.smithy.rulesengine.language.evaluation.value.Value;
@@ -17,24 +16,17 @@
 import software.amazon.smithy.utils.SmithyUnstableApi;
 
 /**
- * A coalesce function that returns the first non-empty value, with type-safe fallback handling.
+ * A coalesce function that returns the first non-empty value.
  * At runtime, returns the left value unless it's EmptyValue, in which case returns the right value.
  *
  * <p>Type checking rules:
  * <ul>
  * <li>{@code coalesce(T, T) => T} (same types)</li>
- * <li>{@code coalesce(T, AnyType) => T} (AnyType adapts to concrete type)</li>
- * <li>{@code coalesce(AnyType, T) => T} (AnyType adapts to concrete type)</li>
- * <li>{@code coalesce(T, S) => S} (if T.isA(S), i.e., S is more general)</li>
- * <li>{@code coalesce(T, S) => T} (if S.isA(T), i.e., T is more general)</li>
- * <li>{@code coalesce(Optional<T>, S) => common_type(T, S)} (unwraps optional)</li>
- * <li>{@code coalesce(T, Optional<S>) => common_type(T, S)} (unwraps optional)</li>
- * <li>{@code coalesce(Optional<T>, Optional<S>) => Optional<common_type(T, S)>}</li>
+ * <li>{@code coalesce(Optional<T>, T) => T} (unwraps optional)</li>
+ * <li>{@code coalesce(T, Optional<T>) => T} (unwraps optional)</li>
+ * <li>{@code coalesce(Optional<T>, Optional<T>) => Optional<T>}</li>
  * </ul>
  *
- * <p>Special handling for AnyType: Since AnyType can masquerade as any type, when coalescing
- * with a concrete type, the concrete type is used as the result type.
- *
  * <p>Supports chaining:
  * {@code coalesce(opt1, coalesce(opt2, coalesce(opt3, default)))}
  *
@@ -80,29 +72,6 @@ public <R> R accept(ExpressionVisitor<R> visitor) {
         return visitor.visitCoalesce(args.get(0), args.get(1));
     }
 
-    // Type checking rules for coalesce:
-    //
-    // This function returns the first non-empty value with type-safe fallback handling.
-    // The type resolution follows these rules:
-    //
-    // 1. If both types are identical, use that type
-    // 2. Special handling for AnyType: Since AnyType.isA() always returns true (it can masquerade as any type), we
-    //    need to handle it specially. When coalescing AnyType with a concrete type, we use the concrete type as the
-    //    result, since AnyType can adapt to it at runtime.
-    // 3. For other types, we use the isA relationship to find the more general type:
-    //    - If left.isA(right), then right is more general, use right
-    //    - If right.isA(left), then left is more general, use left
-    // 4. If no type relationship exists, throw a type mismatch error
-    //
-    // The result is wrapped in Optional only if BOTH inputs are Optional, since coalesce(optional, required)
-    // guarantees a non-empty result.
-    //
-    // Examples:
-    // - coalesce(String, String) => String
-    // - coalesce(Optional<String>, String) => String
-    // - coalesce(Optional<String>, Optional<String>) => Optional<String>
-    // - coalesce(String, AnyType) => String (AnyType adapts)
-    // - coalesce(SubType, SuperType) => SuperType (more general)
     @Override
     public Type typeCheck(Scope<Type> scope) {
         List<Expression> args = getArguments();
@@ -113,38 +82,23 @@ public Type typeCheck(Scope<Type> scope) {
 
         Type leftType = args.get(0).typeCheck(scope);
         Type rightType = args.get(1).typeCheck(scope);
-
-        // Find the least upper bound (most specific common type)
-        Type resultType = lubForCoalesce(leftType, rightType);
-
-        // Only return Optional if both sides can be empty
-        if (leftType instanceof OptionalType && rightType instanceof OptionalType) {
-            return Type.optionalType(resultType);
+        Type leftInner = getInnerType(leftType);
+        Type rightInner = getInnerType(rightType);
+
+        // Both must be the same type (after unwrapping optionals)
+        if (!leftInner.equals(rightInner)) {
+            throw new IllegalArgumentException(String.format(
+                    "Type mismatch in coalesce: %s and %s must be the same type",
+                    leftType,
+                    rightType));
         }
 
-        return resultType;
-    }
-
-    // Finds the least upper bound (LUB) for coalesce type checking.
-    // The LUB is the most specific type that both input types can be assigned to.
-    // Special handling for AnyType: it adapts to concrete types rather than dominating them.
-    private static Type lubForCoalesce(Type a, Type b) {
-        Type ai = getInnerType(a);
-        Type bi = getInnerType(b);
-
-        if (ai.equals(bi)) {
-            return ai;
-        } else if (ai instanceof AnyType) {
-            return bi; // AnyType adapts to concrete type
-        } else if (bi instanceof AnyType) {
-            return ai; // AnyType adapts to concrete type
-        } else if (ai.isA(bi)) {
-            return bi; // bi is more general
-        } else if (bi.isA(ai)) {
-            return ai; // ai is more general
+        // Only return Optional if both sides are optional
+        if (leftType instanceof OptionalType && rightType instanceof OptionalType) {
+            return Type.optionalType(leftInner);
         }
 
-        throw new IllegalArgumentException("Type mismatch in coalesce: " + a + " and " + b + " have no common type");
+        return leftInner;
     }
 
     private static Type getInnerType(Type t) {