Object.assign documentation and tests

Author: jmagaram

src/Core__Object.res

@@ -7,8 +7,26 @@
 @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`.  
+
+## 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}
+```
+## Specifications
+- [ECMAScript Language Specification](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.assign)
+- [Object.assign on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
+*/
+@val
+external assign: ({..}, {..}) => {..} = "Object.assign"
+@variadic @val
+external assignMany: ({..}, array<{..}>) => {..} = "Object.assign"
 @val external copy: (@as(json`{}`) _, {..}) => {..} = "Object.assign"
 
 @get_index external get: ({..}, string) => option<'a> = ""

test/ObjectTests.mjs

@@ -0,0 +1,79 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Test from "./Test.mjs";
+import * as Caml_obj from "rescript/lib/es6/caml_obj.js";
+
+var eq = Caml_obj.equal;
+
+Test.run([
+      [
+        "ObjectTests.res",
+        8,
+        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",
+          16,
+          22,
+          39
+        ],
+        "assign " + title + ""
+      ], Object.assign({
+            a: 1
+          }, sourceObj), eq, sourceObj);
+  Test.run([
+        [
+          "ObjectTests.res",
+          17,
+          22,
+          39
+        ],
+        "assign " + title + ""
+      ], Object.assign({
+            a: undefined
+          }, sourceObj), eq, sourceObj);
+  Test.run([
+        [
+          "ObjectTests.res",
+          18,
+          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 ,
+  assignOverwritesTarget ,
+}
+/*  Not a pure module */

test/ObjectTests.res

@@ -0,0 +1,24 @@
+open RescriptCore
+
+let eq = (a, b) => a == b
+
+// ====== 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

@@ -4,6 +4,7 @@ import * as IntTests from "./IntTests.mjs";
 import * as TestTests from "./TestTests.mjs";
 import * as ArrayTests from "./ArrayTests.mjs";
 import * as ErrorTests from "./ErrorTests.mjs";
+import * as ObjectTests from "./ObjectTests.mjs";
 import * as PromiseTest from "./PromiseTest.mjs";
 
 var bign = TestTests.bign;
@@ -26,10 +27,12 @@ var Concurrently = PromiseTest.Concurrently;
 
 var panicTest = ErrorTests.panicTest;
 
-var eq = IntTests.eq;
-
 var $$catch = IntTests.$$catch;
 
+var eq = ObjectTests.eq;
+
+var assignOverwritesTarget = ObjectTests.assignOverwritesTarget;
+
 export {
   bign ,
   TestError ,
@@ -41,7 +44,8 @@ export {
   Catching ,
   Concurrently ,
   panicTest ,
-  eq ,
   $$catch ,
+  eq ,
+  assignOverwritesTarget ,
 }
 /* IntTests Not a pure module */

test/TestSuite.res

@@ -3,3 +3,4 @@ include PromiseTest
 include ErrorTests
 include ArrayTests
 include IntTests
+include ObjectTests