Object.create docs

Author: jmagaram

src/Core__Object.res

@@ -41,8 +41,24 @@ fruit === {"name": "Apple" } // false
 @val
 external is: ('a, 'a) => bool = "Object.is"
 
-@val external create: {..} => {..} = "Object.create"
-@val external createWithProperties: ({..}, {..}) => {..} = "Object.create"
+/**
+`create` creates a new object, using an existing object as the prototype of the new object. See [Object.create on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create)
+
+**Note:** ReScript provides [first-class support for immutable objects](https://rescript-lang.org/docs/manual/latest/object) and [records](https://rescript-lang.org/docs/manual/latest/record). This is often safer and more convenient than using `create` and other functions in this module.
+
+## Examples
+
+```rescript
+let x = {"fruit": "banana"}
+let y = Object.create(x)
+y->Object.get("fruit") // Some("banana")
+```
+*/
+@val
+external create: {..} => {..} = "Object.create"
+
+@val
+external createWithProperties: ({..}, {..}) => {..} = "Object.create"
 @val external createWithNull: (@as(json`null`) _, unit) => {..} = "Object.create"
 @val external createWithNullAndProperties: (@as(json`null`) _, {..}) => {..} = "Object.create"
 

test/ObjectTests.mjs

@@ -599,6 +599,30 @@ Test.run([
       "Object.getSymbol when not exists return it as None"
     ], ({})[Symbol("fruit")], eq, undefined);
 
+Test.run([
+      [
+        "ObjectTests.res",
+        168,
+        13,
+        46
+      ],
+      "Object.create clones properties"
+    ], Object.create({
+            a: 1
+          })["a"], eq, 1);
+
+Test.run([
+      [
+        "ObjectTests.res",
+        175,
+        13,
+        46
+      ],
+      "Object.create clones properties"
+    ], Object.create({
+            a: 1
+          })["b"], eq, undefined);
+
 export {
   eq ,
   nums ,

test/ObjectTests.res

@@ -161,3 +161,20 @@ Test.run(
   eq,
   None,
 )
+
+// ===== create =====
+
+Test.run(
+  __POS_OF__(`Object.create clones properties`),
+  {"a": 1}->Object.create->Object.get("a"),
+  eq,
+  Some(1),
+)
+
+Test.run(
+  __POS_OF__(`Object.create clones properties`),
+  {"a": 1}->Object.create->Object.get("b"),
+  eq,
+  None,
+)
+