Merge branch 'Object.assign-documentation' into Object-docs

Author: jmagaram

src/Core__Object.res

@@ -34,8 +34,35 @@ external is: ('a, 'a) => bool = "Object.is"
 @val external createWithNull: (@as(json`null`) _, unit) => {..} = "Object.create"
 @val external createWithNullAndProperties: (@as(json`null`) _, {..}) => {..} = "Object.create"
 
-@val external assign: ({..}, {..}) => {..} = "Object.assign"
-@variadic @val external assignMany: ({..}, array<{..}>) => {..} = "Object.assign"
+/**
+`assign(target, source)` copies enumerable own properties from the source to the target, overwriting properties with the same name. It returns the modified target object. A deep clone is not created; properties are copied by reference.
+
+**Note:** ReScript provides [first-class support for immutable objects](https://rescript-lang.org/docs/manual/latest/object), including spreading one object into another. This is often more convenient than using `assign`.  
+
+See [Object.assign on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) or [ECMAScript Language Specification](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.assign).
+
+## Examples
+
+```rescript
+Object.assign({"a": 1}, {"a": 2}) // {"a": 2}
+Object.assign({"a": 1, "b": 2}, {"a": 0}) // {"a": 0, "b": 2}
+Object.assign({"a": 1}, {"a": null}) // {"a": null}
+```
+*/
+@val
+external assign: ({..}, {..}) => {..} = "Object.assign"
+
+@variadic
+@val
+/**
+`assignMany(target, sources)` copies enumerable own properties from each source to the target, overwriting properties with the same name. Later sources' properties overwrite earlier ones. It returns the modified target object. A deep clone is not created; properties are copied by reference.
+
+**Note:** ReScript provides [first-class support for immutable objects](https://rescript-lang.org/docs/manual/latest/object), including spreading one object into another. This is often more convenient than using `assign` or `assignMany`.  
+
+See [Object.assign on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) or [ECMAScript Language Specification](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.assign).
+*/
+external assignMany: ({..}, array<{..}>) => {..} = "Object.assign"
+
 @val external copy: (@as(json`{}`) _, {..}) => {..} = "Object.assign"
 
 @get_index external get: ({..}, string) => option<'a> = ""

test/ObjectTests.mjs

@@ -397,11 +397,79 @@ Test.run([
       "is: bigint"
     ], BigInt("123") === BigInt("123"), eq, true);
 
+Test.run([
+      [
+        "ObjectTests.res",
+        61,
+        13,
+        50
+      ],
+      "assign copies from source to target"
+    ], Object.assign({
+          a: 1,
+          b: 2
+        }, {
+          b: 3,
+          c: 0
+        }), eq, {
+      a: 1,
+      b: 3,
+      c: 0
+    });
+
+function assignOverwritesTarget(title, source) {
+  var sourceObj = {
+    a: source
+  };
+  Test.run([
+        [
+          "ObjectTests.res",
+          69,
+          22,
+          39
+        ],
+        "assign " + title + ""
+      ], Object.assign({
+            a: 1
+          }, sourceObj), eq, sourceObj);
+  Test.run([
+        [
+          "ObjectTests.res",
+          70,
+          22,
+          39
+        ],
+        "assign " + title + ""
+      ], Object.assign({
+            a: undefined
+          }, sourceObj), eq, sourceObj);
+  Test.run([
+        [
+          "ObjectTests.res",
+          71,
+          22,
+          39
+        ],
+        "assign " + title + ""
+      ], Object.assign({
+            a: null
+          }, sourceObj), eq, sourceObj);
+}
+
+assignOverwritesTarget("when source is undefined", undefined);
+
+assignOverwritesTarget("when source is null", null);
+
+assignOverwritesTarget("when source is a number", 1);
+
+assignOverwritesTarget("when source is a string", "abc");
+
 export {
   eq ,
   nums ,
   d ,
   x ,
   mkBig ,
+  assignOverwritesTarget ,
 }
 /*  Not a pure module */

test/ObjectTests.res

@@ -54,3 +54,24 @@ Test.run(__POS_OF__("is: bigint"), Object.is(mkBig("123489"), mkBig("123456789")
 Test.run(__POS_OF__("is: bigint"), Object.is(mkBig("000000000"), mkBig("0")), eq, true)
 Test.run(__POS_OF__("is: bigint"), mkBig("123") == mkBig("123"), eq, true)
 Test.run(__POS_OF__("is: bigint"), mkBig("123") === mkBig("123"), eq, true)
+
+// ====== assign ======
+
+Test.run(
+  __POS_OF__("assign copies from source to target"),
+  Object.assign({"a": 1, "b": 2}, {"b": 3, "c": 0}),
+  eq,
+  {"a": 1, "b": 3, "c": 0},
+)
+
+let assignOverwritesTarget = (~title, ~source) => {
+  let sourceObj = {"a": source}
+  Test.run(__POS_OF__(`assign ${title}`), Object.assign({"a": 1}, sourceObj), eq, sourceObj)
+  Test.run(__POS_OF__(`assign ${title}`), Object.assign({"a": undefined}, sourceObj), eq, sourceObj)
+  Test.run(__POS_OF__(`assign ${title}`), Object.assign({"a": null}, sourceObj), eq, sourceObj)
+}
+
+assignOverwritesTarget(~title="when source is undefined", ~source=undefined)
+assignOverwritesTarget(~title="when source is null", ~source=null)
+assignOverwritesTarget(~title="when source is a number", ~source=1)
+assignOverwritesTarget(~title="when source is a string", ~source="abc")

test/TestSuite.mjs

@@ -39,6 +39,8 @@ var x = ObjectTests.x;
 
 var mkBig = ObjectTests.mkBig;
 
+var assignOverwritesTarget = ObjectTests.assignOverwritesTarget;
+
 export {
   bign ,
   TestError ,
@@ -56,5 +58,6 @@ export {
   d ,
   x ,
   mkBig ,
+  assignOverwritesTarget ,
 }
 /* IntTests Not a pure module */