From edb17985961490e78a3959590eb9c3991147caf1 Mon Sep 17 00:00:00 2001
From: jmagaram <justin@magaram.com>
Date: Thu, 23 Mar 2023 11:22:41 -0700
Subject: [PATCH] Object.create docs

---
 src/Core__Object.res | 20 ++++++++++++++++++--
 test/ObjectTests.mjs | 24 ++++++++++++++++++++++++
 test/ObjectTests.res | 17 +++++++++++++++++
 3 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/src/Core__Object.res b/src/Core__Object.res
index 3d93427c..af83a19e 100644
--- a/src/Core__Object.res
+++ b/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"
 
diff --git a/test/ObjectTests.mjs b/test/ObjectTests.mjs
index c180d955..5b2ac5cd 100644
--- a/test/ObjectTests.mjs
+++ b/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 ,
diff --git a/test/ObjectTests.res b/test/ObjectTests.res
index c0605598..6f888696 100644
--- a/test/ObjectTests.res
+++ b/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,
+)
+