Return unwrapped primitive values from Array iterator (#1178)

Change the default `for...of` iterator on JSONArray to return raw
primitive values instead of Primitive wrappers, making it consistent
with `.values()`, `.map()`, and other read-only array methods. Add
`elements()` method as an alternative for accessing wrapped elements
with CRDT metadata.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: hackerwins

packages/sdk/src/document/json/array.ts

@@ -114,6 +114,11 @@ export type JSONArray<T> = {
    */
   moveLast(id: TimeTicket): void;
 
+  /**
+   * `elements` returns an iterator of wrapped elements including CRDT metadata.
+   */
+  elements(): IterableIterator<WrappedElement<T>>;
+
   /**
    * `toTestString` returns a String containing the meta data of the node
    * for debugging purpose.
@@ -324,6 +329,8 @@ export class ArrayProxy {
           return target.length;
         } else if (typeof method === 'symbol' && method === Symbol.iterator) {
           return ArrayProxy.iteratorInternal.bind(this, context, target);
+        } else if (method === 'elements') {
+          return ArrayProxy.wrappedIteratorInternal.bind(this, context, target);
         } else if (method === 'includes') {
           return (searchElement: JSONElement, fromIndex?: number): boolean => {
             return ArrayProxy.includes(
@@ -398,6 +405,16 @@ export class ArrayProxy {
   public static *iteratorInternal(
     change: ChangeContext,
     target: CRDTArray,
+  ): IterableIterator<JSONElement> {
+    for (const elem of target) {
+      yield toJSONElement(change, elem)!;
+    }
+  }
+
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public static *wrappedIteratorInternal(
+    change: ChangeContext,
+    target: CRDTArray,
   ): IterableIterator<WrappedElement> {
     for (const elem of target) {
       yield toWrappedElement(change, elem)!;