Update readonly example for ES2025 iterator chains

Author: steida

packages/common/src/Function.ts

@@ -86,6 +86,10 @@ export const identity = <A>(a: A): A => a;
  *
  * const lookup = readonly(new Map([["key", "value"]]));
  * // Type: ReadonlyMap<string, string>
+ *
+ * // ES2025 iterator chains: use .toArray() then readonly
+ * const doubled = readonly([1, 2, 3].values().map((x) => x * 2).toArray());
+ * // Type: ReadonlyArray<number>
  * ```
  *
  * @experimental

packages/common/test/Function.test.ts

@@ -153,6 +153,19 @@ describe("readonly", () => {
       expectTypeOf(map).toEqualTypeOf<ReadonlyMap<string, number>>();
     });
   });
+
+  describe("with ES2025 iterator .toArray()", () => {
+    test("converts iterator chain to ReadonlyArray", () => {
+      const result = readonly(
+        [1, 2, 3]
+          .values()
+          .map((x) => x * 2)
+          .toArray(),
+      );
+      expect(result).toEqual([2, 4, 6]);
+      expectTypeOf(result).toEqualTypeOf<ReadonlyArray<number>>();
+    });
+  });
 });
 
 describe("exhaustiveCheck", () => {