feat: add support for Map Items

src/main/java/org/rumbledb/api/Item.java

@@ -60,6 +60,15 @@ default boolean isObject() {
         return false;
     }
 
+    /**
+     * Tests whether the item is an XDM map (not a JSON object).
+     *
+     * @return true if it is a map, false otherwise.
+     */
+    default boolean isMap() {
+        return false;
+    }
+
     /**
      * Tests whether the item is a function.
      *
@@ -87,6 +96,15 @@ default boolean isString() {
         return false;
     }
 
+    /**
+     * Tests whether the item is an atomic item of type xs:untypedAtomic.
+     *
+     * @return true if it is an atomic item of type xs:untypedAtomic, false otherwise.
+     */
+    default boolean isUntypedAtomic() {
+        return false;
+    }
+
     /**
      * Tests whether the item is an atomic item of type default boolean.
      *
@@ -457,6 +475,21 @@ default boolean isNode() {
         return false;
     }
 
+    /**
+     * Whether this array item's runtime representation allows non-singleton member sequences.
+     * <p>
+     * For arrays: {@code false} means each member is stored as a single {@link Item} (singleton
+     * members); {@code true} means members may be arbitrary sequences.
+     * <p>
+     * Defined only for array items; other item kinds throw.
+     *
+     * @return {@code true} if non-singleton members are supported, {@code false} if members are
+     *         singleton-only in the representation
+     */
+    default boolean allowsNonSingletons() {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Returns the members of the item if it is an array.
      *
@@ -466,6 +499,22 @@ default List<Item> getItems() {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Returns the logical member sequences of the item if it is an array or a map.
+     * <p>
+     * Each array or map member is represented as a sequence of items. For arrays or maps whose members are
+     * all singletons, each member sequence is of length 1.
+     * <p>
+     * Implementations that only support singleton members may return a singleton sequence per member.
+     * <p>
+     * For maps, the sequences are the value sequences associated with the keys.
+     *
+     * @return the list of member sequences (one sequence per array member).
+     */
+    default List<List<Item>> getSequences() {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Returns the member of the item at the specified position if it is an array.
      *
@@ -476,6 +525,18 @@ default Item getItemAt(int position) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Returns the logical member sequence at the specified position if it is an array.
+     * <p>
+     * The position is zero-based, consistent with {@link #getItemAt(int)}.
+     *
+     * @param position a zero-based member position.
+     * @return the sequence of items corresponding to that member.
+     */
+    default List<Item> getSequenceAt(int position) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Returns the keys of the item, if it is an object.
      *
@@ -504,6 +565,45 @@ default Item getItemByKey(String key) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Returns the value associated with a specific key, if it is an object.
+     *
+     * @param key a key item.
+     * @return the value associated with key.
+     */
+    default Item getItemByKey(Item key) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
+    /**
+     * Returns the (possibly non-string) atomic keys of the item, if it is a map-like object.
+     *
+     * @return the list of atomic keys as items.
+     */
+    default List<Item> getItemKeys() {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
+    /**
+     * Returns the value sequence associated with a key, if it is a map-like object.
+     *
+     * @param key an atomic key item.
+     * @return the value sequence for the key, or null if absent.
+     */
+    default List<Item> getSequenceByKey(Item key) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
+    /**
+     * Returns the value sequence associated with a string key, if it is a map-like object.
+     *
+     * @param key a string key.
+     * @return the value sequence for the key, or null if absent.
+     */
+    default List<Item> getSequenceByKey(String key) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Returns the size of the item, if it is an array.
      *
@@ -746,6 +846,18 @@ default void putItem(Item item) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Appends a logical member sequence, if it is an array.
+     * <p>
+     * For arrays whose members are all singletons, this is equivalent to {@link #putItem(Item)}
+     * when the sequence contains exactly one item.
+     *
+     * @param items the member sequence to append as a single array member.
+     */
+    default void appendSequence(List<Item> items) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Add an item at index i, if it is an array.
      *
@@ -756,6 +868,19 @@ default void putItemAt(Item item, int i) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Replace the logical member at index i with the supplied member sequence, if it is an array.
+     * <p>
+     * For arrays whose members are all singletons, callers should prefer {@link #putItemAt(Item, int)}
+     * when possible.
+     *
+     * @param items the member sequence to store at the given position.
+     * @param i a zero-based member index.
+     */
+    default void putSequenceAt(List<Item> items, int i) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Add all items in items at index i, if it is an array.
      *
@@ -794,6 +919,26 @@ default void putItemByKey(String key, Item value) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Adds a key-value pair, if it is a map-like object.
+     *
+     * @param key an atomic key.
+     * @param value a value.
+     */
+    default void putItemByKey(Item key, Item value) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
+    /**
+     * Adds a key-sequence pair, if it is a map-like object.
+     *
+     * @param key an atomic key.
+     * @param valueSequence a value sequence.
+     */
+    default void putSequenceByKey(Item key, List<Item> valueSequence) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Removes a key-value pair, if it is an object item.
      *
@@ -803,6 +948,15 @@ default void removeItemByKey(String key) {
         throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
     }
 
+    /**
+     * Removes a key-value pair, if it is a map-like object.
+     *
+     * @param key an atomic key.
+     */
+    default void removeItemByKey(Item key) {
+        throw new UnsupportedOperationException("Operation not defined for type " + this.getDynamicType());
+    }
+
     /**
      * Adds a key-value pair, if it is an object item. The value is lazily computed.
      *

src/main/java/org/rumbledb/compiler/CloneVisitor.java

@@ -49,6 +49,7 @@
 import org.rumbledb.expressions.primary.IntegerLiteralExpression;
 import org.rumbledb.expressions.primary.NamedFunctionReferenceExpression;
 import org.rumbledb.expressions.primary.NullLiteralExpression;
+import org.rumbledb.expressions.primary.MapConstructorExpression;
 import org.rumbledb.expressions.primary.ObjectConstructorExpression;
 import org.rumbledb.expressions.primary.StringLiteralExpression;
 import org.rumbledb.expressions.primary.VariableReferenceExpression;
@@ -421,12 +422,23 @@ public Node visitDynamicFunctionCallExpression(DynamicFunctionCallExpression exp
 
     // region primary
     public Node visitArrayConstructor(ArrayConstructorExpression expression, Node argument) {
-        ArrayConstructorExpression result = new ArrayConstructorExpression(
-                (expression.getExpression() == null)
-                    ? expression.getExpression()
-                    : (Expression) visit(expression.getExpression(), argument),
-                expression.getMetadata()
-        );
+        ArrayConstructorExpression result;
+        if (expression.isSquareConstructor()) {
+            List<Expression> clonedMembers = new java.util.ArrayList<>();
+            if (expression.getMemberExpressions() != null) {
+                for (Expression memberExpr : expression.getMemberExpressions()) {
+                    clonedMembers.add((Expression) visit(memberExpr, argument));
+                }
+            }
+            result = new ArrayConstructorExpression(clonedMembers, true, expression.getMetadata());
+        } else {
+            result = new ArrayConstructorExpression(
+                    (expression.getExpression() == null)
+                        ? expression.getExpression()
+                        : (Expression) visit(expression.getExpression(), argument),
+                    expression.getMetadata()
+            );
+        }
         result.setStaticSequenceType(expression.getStaticSequenceType());
         result.setStaticContext(expression.getStaticContext());
         return result;
@@ -458,6 +470,22 @@ public Node visitObjectConstructor(ObjectConstructorExpression expression, Node
         }
     }
 
+    @Override
+    public Node visitMapConstructor(MapConstructorExpression expression, Node argument) {
+        List<Expression> keys = expression.getKeys()
+            .stream()
+            .map(key -> (Expression) visit(key, argument))
+            .collect(Collectors.toList());
+        List<Expression> values = expression.getValues()
+            .stream()
+            .map(value -> (Expression) visit(value, argument))
+            .collect(Collectors.toList());
+        Expression result = new MapConstructorExpression(keys, values, expression.getMetadata());
+        result.setStaticContext(expression.getStaticContext());
+        result.setStaticSequenceType(expression.getStaticSequenceType());
+        return result;
+    }
+
     @Override
     public Node visitDirElemConstructor(DirElemConstructorExpression expression, Node argument) {
         List<Expression> content = expression.getContent()
@@ -892,6 +920,7 @@ public Node visitComparisonExpr(ComparisonExpression expression, Node argument)
                 expression.getComparisonOperator(),
                 expression.getMetadata()
         );
+        result.setOriginalComparisonOperator(expression.getOriginalComparisonOperator());
         result.setStaticSequenceType(expression.getStaticSequenceType());
         result.setStaticContext(expression.getStaticContext());
         return result;