more bindings to node, and provide type safe typeof (#691)

* more clean api (+3 squashed commits)
Squashed commits:
[f5f00dd] split js into js_types, provide Js.null and Js.undefined
[b034aff] more docs and more tests
[f479a48] more tests for type safe typeof (+2 squashed commits)
Squashed commits:
[17fe000] more ides
[94f4314] more bindings for node and practical solution to get typesafe typeof

* more docs

Author: bobzhang

README.md

@@ -12,10 +12,6 @@ A JavaScript backend for [OCaml](https://ocaml.org/) focused on smooth integrati
 You can try BuckleScript directly [in your browser](http://bloomberg.github.io/bucklescript/js-demo/). Write OCaml in the left panel and
 watch as it instantly compiles to JavaScript shown in the right panel.
 
-## Getting Help and Providing Feedback
-
-If you need help or have a question, comment, or suggestion, please feel free to [open an
-issue](https://github.com/bloomberg/bucklescript/issues).
 
 ## Installing BuckleScript
 ```
@@ -175,6 +171,10 @@ function test() {
 test();
 ```
 
+## Getting Help and Providing Feedback
+
+If you need help or have a question, comment, or suggestion, please feel free to [open an
+issue](https://github.com/bloomberg/bucklescript/issues).
 
 ## Licensing
 

docs/Manual.html

@@ -583,6 +583,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
 </li>
 </ul>
 </li>
+<li><a href="#_js_module">Js module</a></li>
 <li><a href="#_extended_compiler_options">Extended compiler options</a>
 <ul class="sectlevel2">
 <li><a href="#__bs_main_single_directory_build">-bs-main (single directory build)</a></li>
@@ -2901,6 +2902,128 @@ <h4 id="_a_simple_example_binding_to_mocha_unit_test_library"><a class="anchor"
 </div>
 </div>
 <div class="sect1">
+<h2 id="_js_module"><a class="anchor" href="#_js_module"></a>Js module</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Js module is shipped with BuckleScript, both the namespace <code>Js</code> and <code>Node</code> are preserved.</p>
+</div>
+<div class="listingblock">
+<div class="title">Js Public types</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-o">+</span><span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span>
+<span class="tok-c">(** Js object type *)</span>
+<span class="tok-k">type</span> <span class="tok-o">+</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">null</span>
+<span class="tok-c">(** nullable, value of this type can be either [null] or [&#39;a]</span>
+<span class="tok-c">    this type is the same as {!Js.Null.t}  *)</span>
+<span class="tok-k">type</span> <span class="tok-o">+</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">undefined</span>
+<span class="tok-c">(** value of this type can be either [undefined] or [&#39;a]</span>
+<span class="tok-c">    this type is the same as {!Js.Undefined.t}  *)</span>
+<span class="tok-k">type</span> <span class="tok-o">+</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">null_undefined</span>
+<span class="tok-c">(** value of this type can be [undefined], [null] or [&#39;a]</span>
+<span class="tok-c">    this type is the same as {!Js.Null_undefined.t}*)</span>
+<span class="tok-k">type</span> <span class="tok-n">boolean</span></code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">Js Nested modules</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-c">(** {3 nested modules}*)</span>
+<span class="tok-k">module</span> <span class="tok-nc">Null</span> <span class="tok-o">=</span> <span class="tok-nc">Js_null</span>
+<span class="tok-k">module</span> <span class="tok-nc">Undefined</span> <span class="tok-o">=</span> <span class="tok-nc">Js_undefined</span>
+<span class="tok-k">module</span> <span class="tok-nc">Null_undefined</span> <span class="tok-o">=</span> <span class="tok-nc">Js_null_undefined</span>
+<span class="tok-k">module</span> <span class="tok-nc">Types</span> <span class="tok-o">=</span> <span class="tok-nc">Js_types</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Note that <code>Null</code>, <code>Undefined</code> and <code>Null_undefined</code> have similar interfaces, for example:</p>
+</div>
+<div class="listingblock">
+<div class="title">Js.Null module</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-o">+</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span> <span class="tok-o">=</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-nn">Js</span><span class="tok-p">.</span><span class="tok-n">null</span>
+<span class="tok-k">external</span> <span class="tok-n">to_opt</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">option</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_from_nullable&quot;</span>
+<span class="tok-k">external</span> <span class="tok-n">return</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span>  <span class="tok-o">=</span> <span class="tok-s2">&quot;%identity&quot;</span>
+<span class="tok-k">external</span> <span class="tok-n">test</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">bool</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_is_nil&quot;</span>
+<span class="tok-k">external</span> <span class="tok-n">empty</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">t</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;null&quot;</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The interface for <code>Js.Types</code> is as below</p>
+</div>
+<div class="listingblock">
+<div class="title">Js.Types module</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">symbol</span>
+<span class="tok-c">(**Js symbol type only available in ES6 *)</span>
+
+<span class="tok-k">type</span> <span class="tok-n">obj_val</span>
+<span class="tok-k">type</span> <span class="tok-n">undefined_val</span>
+<span class="tok-c">(** This type has only one value [undefined] *)</span>
+<span class="tok-k">type</span> <span class="tok-n">null_val</span>
+<span class="tok-c">(** This type has only one value [null] *)</span>
+<span class="tok-k">type</span> <span class="tok-n">function_val</span>
+
+<span class="tok-k">type</span> <span class="tok-o">_</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Undefined</span> <span class="tok-o">:</span>  <span class="tok-n">undefined_val</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Null</span> <span class="tok-o">:</span> <span class="tok-n">null_val</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Boolean</span> <span class="tok-o">:</span> <span class="tok-nn">Js</span><span class="tok-p">.</span><span class="tok-n">boolean</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Number</span> <span class="tok-o">:</span> <span class="tok-kt">float</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">String</span> <span class="tok-o">:</span> <span class="tok-kt">string</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Function</span> <span class="tok-o">:</span> <span class="tok-n">function_val</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Object</span> <span class="tok-o">:</span> <span class="tok-n">obj_val</span> <span class="tok-n">t</span>
+  <span class="tok-o">|</span> <span class="tok-nc">Symbol</span> <span class="tok-o">:</span> <span class="tok-n">symbol</span> <span class="tok-n">t</span>
+
+<span class="tok-k">val</span> <span class="tok-n">reify_type</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">b</span> <span class="tok-n">t</span> <span class="tok-o">*</span> <span class="tok-k">&#39;</span><span class="tok-n">b</span>
+<span class="tok-c">(** given any value it returns its type and the same value.</span>
+<span class="tok-c">    Note that  since [&#39;b t] is GADT, the type system will reify its type automatically,</span>
+<span class="tok-c">    for example</span>
+<span class="tok-c">    {[</span>
+<span class="tok-c">    match reify_type &quot;3&quot; with</span>
+<span class="tok-c">    | String, v -&gt; v  ^ &quot; this type safe control flow analysis will infer v as string&quot;</span>
+<span class="tok-c">    | _ -&gt; assert false</span>
+<span class="tok-c">    ]}</span>
+<span class="tok-c"> *)</span>
+<span class="tok-k">val</span> <span class="tok-n">test</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">b</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">bool</span>
+<span class="tok-c">(** {[</span>
+<span class="tok-c">  test &quot;x&quot; String = true</span>
+<span class="tok-c">  ]}*)</span></code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">Js Utility functions</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">external</span> <span class="tok-n">to_bool</span> <span class="tok-o">:</span> <span class="tok-n">boolean</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">bool</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_boolean_to_bool&quot;</span>
+<span class="tok-c">(** convert Js boolean to OCaml bool *)</span>
+<span class="tok-k">external</span> <span class="tok-n">typeof</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">string</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_typeof&quot;</span>
+<span class="tok-c">(** [typeof x] will be compiled as [typeof x] in JS *)</span>
+<span class="tok-k">external</span> <span class="tok-n">log</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_dump&quot;</span>
+<span class="tok-c">(** A convenience function to log *)</span>
+
+<span class="tok-c">(** {4 operators }*)</span>
+<span class="tok-k">external</span> <span class="tok-n">unsafe_lt</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_unsafe_lt&quot;</span>
+<span class="tok-c">(**  [unsafe_lt a b] will be compiled as [a &lt; b] *)</span>
+<span class="tok-k">external</span> <span class="tok-n">unsafe_le</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_unsafe_le&quot;</span>
+<span class="tok-c">(**  [unsafe_le a b] will be compiled as [a &lt;= b] *)</span>
+<span class="tok-k">external</span> <span class="tok-n">unsafe_gt</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_unsafe_gt&quot;</span>
+<span class="tok-c">(**  [unsafe_gt a b] will be compiled as [a &gt; b] *)</span>
+<span class="tok-k">external</span> <span class="tok-n">unsafe_ge</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-o">-&gt;</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;js_unsafe_ge&quot;</span>
+<span class="tok-c">(**  [unsafe_ge a b] will be compiled as [a &gt;= b] *)</span></code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">Js Predefined JS values</div>
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">external</span> <span class="tok-bp">true</span><span class="tok-o">_</span> <span class="tok-o">:</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;true&quot;</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span>
+<span class="tok-k">external</span> <span class="tok-bp">false</span><span class="tok-o">_</span> <span class="tok-o">:</span> <span class="tok-n">boolean</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;false&quot;</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span>
+<span class="tok-k">external</span> <span class="tok-n">null</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">null</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;&quot;</span>
+<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span> <span class="tok-c">(* The same as {!Js.Null.empty} will be compiled as [null]*)</span>
+<span class="tok-k">external</span> <span class="tok-n">undefined</span> <span class="tok-o">:</span> <span class="tok-k">&#39;</span><span class="tok-n">a</span> <span class="tok-n">undefined</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;&quot;</span>
+<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span> <span class="tok-c">(* The same as  {!Js.Undefined.empty} will be compiled as [undefined]*)</span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
 <h2 id="_extended_compiler_options"><a class="anchor" href="#_extended_compiler_options"></a>Extended compiler options</h2>
 <div class="sectionbody">
 <div class="paragraph">

jscomp/bin/compiler.js

@@ -1,33 +1,38 @@
-bs_node_path.cmj :
-bs_node_path.cmx :
-bs_node_fs.cmj :
-bs_node_fs.cmx :
-bs_node_process.cmj :
-bs_node_process.cmx :
-bs_dict.cmj :
-bs_dict.cmx :
-bs_node_module.cmj : bs_node.cmj bs_dict.cmj
-bs_node_module.cmx : bs_node.cmx bs_dict.cmx
+node_path.cmj :
+node_path.cmx :
+node_fs.cmj : node.cmj js_string.cmj
+node_fs.cmx : node.cmx js_string.cmx
+node_process.cmj :
+node_process.cmx :
+node_module.cmj : node.cmj js_dict.cmj
+node_module.cmx : node.cmx js_dict.cmx
 js_array.cmj :
 js_array.cmx :
 js_string.cmj : js_re.cmi
 js_string.cmx : js_re.cmx
 js_re.cmj : js_re.cmi
 js_re.cmx : js_re.cmi
+node_buffer.cmj : node.cmj
+node_buffer.cmx : node.cmx
+js_types.cmj : js_types.cmi
+js_types.cmx : js_types.cmi
 js_re.cmi :
-bs_node_path.cmo :
-bs_node_path.cmj :
-bs_node_fs.cmo :
-bs_node_fs.cmj :
-bs_node_process.cmo :
-bs_node_process.cmj :
-bs_dict.cmo :
-bs_dict.cmj :
-bs_node_module.cmo : bs_node.cmo bs_dict.cmo
-bs_node_module.cmj : bs_node.cmj bs_dict.cmj
+js_types.cmi :
+node_path.cmo :
+node_path.cmj :
+node_fs.cmo : node.cmo js_string.cmo
+node_fs.cmj : node.cmj js_string.cmj
+node_process.cmo :
+node_process.cmj :
+node_module.cmo : node.cmo js_dict.cmo
+node_module.cmj : node.cmj js_dict.cmj
 js_array.cmo :
 js_array.cmj :
 js_string.cmo : js_re.cmi
 js_string.cmj : js_re.cmj
 js_re.cmo : js_re.cmi
 js_re.cmj : js_re.cmi
+node_buffer.cmo : node.cmo
+node_buffer.cmj : node.cmj
+js_types.cmo : js_types.cmi
+js_types.cmj : js_types.cmi

jscomp/others/.depend

@@ -2,9 +2,9 @@ include ../Makefile.shared
 
 COMPILER=../bin/bsc
 
-MAP_FILES= bs_node 
+MAP_FILES= node 
 
-SOURCE_LIST=  bs_node_path bs_node_fs bs_node_process bs_dict bs_node_module js_array js_string js_re
+SOURCE_LIST=  node_path node_fs node_process dict node_module js_array js_string js_re node_buffer js_types
 
 $(addsuffix .cmj, $(SOURCE_LIST)): $(addsuffix .cmj, $(MAP_FILES))
 

jscomp/others/Makefile

@@ -61,8 +61,8 @@ external lastIndexOf_from :  t -> int -> int = "lastIndexOf" [@@bs.send.pipe: t]
 
 external localeCompare :  t -> float = "" [@@bs.send.pipe: t]
 
-external replace : Js_re.t ->  t ->  t = "" [@@bs.send.pipe: t]
-external replace_string :  t ->  t ->  t = "replace" [@@bs.send.pipe: t]
+external replaceByReg : Js_re.t ->  t ->  t = "replace" [@@bs.send.pipe: t]
+external replace :  t ->  t ->  t = "" [@@bs.send.pipe: t]
 
 external search : Js_re.t -> int = "" [@@bs.send.pipe: t]
 external slice : int -> int ->  t = "" [@@bs.send.pipe: t]