improve jsutils docs (#17421)

* improve jsutils docs

* address comments

1 files changed, 42 insertions, 10 deletions

diff --git a/lib/std/private/jsutils.nim b/lib/std/private/jsutils.nim
index 32c717c56..836b3512a 100644
--- a/lib/std/private/jsutils.nim
+++ b/lib/std/private/jsutils.nim
@@ -1,4 +1,4 @@
-when defined(js) or defined(nimdoc):
+when defined(js):
   import std/jsbigints
 
   type
@@ -14,7 +14,6 @@ when defined(js) or defined(nimdoc):
   func newUint32Array*(buffer: ArrayBuffer): Uint32Array {.importjs: "new Uint32Array(#)".}
   func newBigUint64Array*(buffer: ArrayBuffer): BigUint64Array {.importjs: "new BigUint64Array(#)".}
 
-
   func newUint8Array*(n: int): Uint8Array {.importjs: "new Uint8Array(#)".}
 
   func `[]`*(arr: Uint32Array, i: int): uint32 {.importjs: "#[#]".}
@@ -22,12 +21,22 @@ when defined(js) or defined(nimdoc):
   func `[]`*(arr: BigUint64Array, i: int): JsBigInt {.importjs: "#[#]".}
   func `[]=`*(arr: Float64Array, i: int, v: float) {.importjs: "#[#] = #".}
 
-
-  proc jsTypeOf*[T](x: T): cstring {.importjs: "typeof(#)".}
-  ## Returns the name of the JsObject's JavaScript type as a cstring.
-  # xxx replace jsffi.jsTypeOf with this definition and add tests
+  proc jsTypeOf*[T](x: T): cstring {.importjs: "typeof(#)".} =
+    ## Returns the name of the JsObject's JavaScript type as a cstring.
+    # xxx replace jsffi.jsTypeOf with this definition and add tests
+    runnableExamples:
+      import std/[jsffi, jsbigints]
+      assert jsTypeOf(1.toJs) == "number"
+      assert jsTypeOf(false.toJs) == "boolean"
+      assert [1].toJs.jsTypeOf == "object" # note the difference with `getProtoName`
+      assert big"1".toJs.jsTypeOf == "bigint"
 
   proc jsConstructorName*[T](a: T): cstring =
+    runnableExamples:
+      import std/jsffi
+      let a = array[2, float64].default
+      assert jsConstructorName(a) == "Float64Array"
+      assert jsConstructorName(a.toJs) == "Float64Array"
     asm """`result` = `a`.constructor.name"""
 
   proc hasJsBigInt*(): bool =
@@ -36,16 +45,39 @@ when defined(js) or defined(nimdoc):
   proc hasBigUint64Array*(): bool =
     asm """`result` = typeof BigUint64Array != 'undefined'"""
 
-  proc getProtoName*[T](a: T): cstring {.importjs: "Object.prototype.toString.call(#)".}
+  proc getProtoName*[T](a: T): cstring {.importjs: "Object.prototype.toString.call(#)".} =
+    runnableExamples:
+      import std/[jsffi, jsbigints]
+      type A = ref object
+      assert 1.toJs.getProtoName == "[object Number]"
+      assert "a".toJs.getProtoName == "[object String]"
+      assert big"1".toJs.getProtoName == "[object BigInt]"
+      assert false.toJs.getProtoName == "[object Boolean]"
+      assert (a: 1).toJs.getProtoName == "[object Object]"
+      assert A.default.toJs.getProtoName == "[object Null]"
+      assert [1].toJs.getProtoName == "[object Int32Array]" # implementation defined
+      assert @[1].toJs.getProtoName == "[object Array]" # ditto
 
-  proc isInteger*[T](x: T): bool {.importjs: "Number.isInteger(#)".}
+  const maxSafeInteger* = 9007199254740991
+    ## The same as `Number.MAX_SAFE_INTEGER` or `2^53 - 1`.
+    ## See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
+  runnableExamples:
+    let a {.importjs: "Number.MAX_SAFE_INTEGER".}: int64
+    assert a == maxSafeInteger
+
+  proc isInteger*[T](x: T): bool {.importjs: "Number.isInteger(#)".} =
+    runnableExamples:
+      import std/jsffi
+      assert 1.isInteger
+      assert not 1.5.isInteger
+      assert 1.toJs.isInteger
+      assert not 1.5.toJs.isInteger
 
   proc isSafeInteger*[T](x: T): bool {.importjs: "Number.isSafeInteger(#)".} =
     runnableExamples:
       import std/jsffi
       assert not "123".toJs.isSafeInteger
+      assert 123.isSafeInteger
       assert 123.toJs.isSafeInteger
       assert 9007199254740991.toJs.isSafeInteger
       assert not 9007199254740992.toJs.isSafeInteger
-
-  let maxSafeInteger* {.importjs: "Number.MAX_SAFE_INTEGER".} : int64