Merge pull request #2870 from jgonggrijp/prepare-1.11

Author: jgonggrijp

index.html

@@ -186,13 +186,14 @@
   <div id="sidebar" class="interface">
 
     <a class="toc_title" href="#">
-      Underscore.js <span class="version">(1.10.2)</span>
+      Underscore.js <span class="version">(1.11.0)</span>
     </a>
     <ul class="toc_section">
       <li>&raquo; <a href="https://github.com/jashkenas/underscore">GitHub Repository</a></li>
       <li>&raquo; <a href="docs/modules/index-all.html">Annotated Source (modular)</a></li>
       <li>&raquo; <a href="docs/underscore-esm.html">Annotated Source (single read)</a></li>
       <li>&raquo; <a href="https://documentcloud.github.io/underscore-contrib/">Underscore-contrib</a></li>
+      <li>&raquo; <a href="https://twitter.com/underscoredotjs">Twitter</a></li>
     </ul>
 
     <input id="function_filter" placeholder="Filter" type="text" autofocus />
@@ -333,6 +334,9 @@
         <li data-name="isWeakMap">- <a href="#isWeakMap">isWeakMap</a></li>
         <li data-name="isSet">- <a href="#isSet">isSet</a></li>
         <li data-name="isWeakSet">- <a href="#isWeakSet">isWeakSet</a></li>
+        <li data-name="isArrayBuffer">- <a href="#isArrayBuffer">isArrayBuffer</a></li>
+        <li data-name="isDataView">- <a href="#isDataView">isDataView</a></li>
+        <li data-name="isTypedArray" data-aliases="isInt8Array isUint8Array isUint8ClampedArray isInt16Array isUint16Array isInt32Array isUint32Array isBigInt64Array isBigUint64Array isFloat32Array isFloat64Array">- <a href="#isTypedArray">isTypedArray</a></li>
         <li data-name="isNaN">- <a href="#isNaN">isNaN</a></li>
         <li data-name="isNull">- <a href="#isNull">isNull</a></li>
         <li data-name="isUndefined">- <a href="#isUndefined">isUndefined</a></li>
@@ -427,7 +431,18 @@
     </p>
 
     <p>
-      You may also read through the <a href="docs/underscore.html">annotated source code</a>.
+      You may also read through the <a
+      href="docs/underscore-esm.html">annotated source code</a>. There is a <a
+      href="docs/modules/index-all.html">modular version</a> with clickable
+      import references as well.
+    </p>
+
+    <p>
+        You may choose between monolithic and modular imports. There is a quick
+        summary of the options below, as well as a more comprehensive
+        discussion in <a
+    href="https://juliangonggrijp.com/article/introducing-modular-underscore.html"
+        >the article</a>.
     </p>
 
     <p>
@@ -447,34 +462,42 @@
       <i>Underscore is an open-source component of <a href="https://documentcloud.org/">DocumentCloud</a>.</i>
     </p>
 
-    <h2>v1.10.2 Downloads <i style="padding-left: 12px; font-size:12px;">(Right-click, and use "Save As")</i></h2>
+    <h2>v1.11.0 Downloads <i style="padding-left: 12px; font-size:12px;">(Right-click, and use "Save As")</i></h2>
 
     <table>
       <tr>
-        <td class="dl-link"><a href="modules/index.js">ES Module</a></td>
+        <td class="dl-link"><a href="underscore-esm.js">ESM (Development)</a></td>
+        <td>
+          <i>62kb, Uncompressed with Plentiful Comments</i>
+          &nbsp;<small>(<a href="underscore-esm.js.map">Source Map</a>)</small>
+        </td>
+      </tr>
+      <tr>
+        <td class="dl-link"><a href="underscore-esm-min.js">ESM (Production)</a></td>
         <td>
-          <i>56kb, Uncompressed with Plentiful Comments</i>
+          <i>8.18kb, Minified and Gzipped</i>
+          &nbsp;<small>(<a href="underscore-esm-min.js.map">Source Map</a>)</small>
         </td>
       </tr>
       <tr>
         <td class="dl-link"><a href="underscore.js">UMD (Development)</a></td>
         <td>
-          <i>60kb, Uncompressed with Bountiful Comments</i>
+          <i>64kb, Uncompressed with Bountiful Comments</i>
           &nbsp;<small>(<a href="underscore.js.map">Source Map</a>)</small>
         </td>
       </tr>
       <tr>
         <td class="dl-link"><a href="underscore-min.js">UMD (Production)</a></td>
         <td>
-          <i>6.78kb, Minified and Gzipped</i>
+          <i>7.15kb, Minified and Gzipped</i>
           &nbsp;<small>(<a href="underscore-min.js.map">Source Map</a>)</small>
         </td>
       </tr>
       <tr>
         <td colspan="2"><div class="rule"></div></td>
       </tr>
       <tr>
-        <td class="dl-link"><a href="https://raw.github.com/jashkenas/underscore/master/modules/index.js">Edge ES Module</a></td>
+        <td class="dl-link"><a href="https://raw.github.com/jashkenas/underscore/master/underscore-esm.js">Edge ESM</a></td>
         <td><i>Unreleased, current <tt>master</tt>, use by your own judgement and at your own risk</i></td>
       </tr>
       <tr>
@@ -483,7 +506,36 @@ <h2>v1.10.2 Downloads <i style="padding-left: 12px; font-size:12px;">(Right-clic
       </tr>
     </table>
 
-    <h2>Installation</h2>
+    <h2>v1.11.0 CDN URLs <i style="padding-left: 12px; font-size:12px;">(Use with <tt>&lt;script src="..."&gt;&lt;/script&gt;</tt>)</i></h2>
+
+    <ul>
+      <li>
+        <tt>https://cdn.jsdelivr.net/npm/underscore@1.11.0/underscore-min.js</tt>
+      </li>
+      <li>
+        <tt>https://cdn.jsdelivr.net/npm/underscore@1.11.0/underscore-esm-min.js</tt>
+      </li>
+      <li>
+        <tt>https://unpkg.com/underscore@1.11.0/underscore-min.js</tt>
+      </li>
+      <li>
+        <tt>https://unpkg.com/underscore@1.11.0/underscore-esm-min.js</tt>
+      </li>
+      <li>
+        <tt>https://pagecdn.io/lib/underscore/1.11.0/underscore-min.js</tt>
+      </li>
+      <li>
+        <tt>https://pagecdn.io/lib/underscore/1.11.0/underscore-esm-min.js</tt>
+      </li>
+      <li>
+        <tt>https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.11.0/underscore-min.js</tt>
+      </li>
+      <li>
+        <tt>https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.11.0/underscore-esm-min.js</tt>
+      </li>
+    </ul>
+
+    <h2>Package Installation</h2>
 
     <ul>
       <li>
@@ -493,22 +545,49 @@ <h2>Installation</h2>
         <b>Meteor.js</b> <tt>meteor add underscore</tt>
       </li>
       <li>
-        <b>Require.js</b> <tt>require(["underscore"], ...</tt>
+        <b>Bower</b> <tt>bower install underscore</tt>
+      </li>
+    </ul>
+
+    <h2>Monolithic Import</h2>
+
+    <ul>
+      <li>
+        <b>ESM</b> <tt>import _, { map } from 'underscore';</tt>
       </li>
       <li>
-        <b>Bower</b> <tt>bower install underscore</tt>
+        <b>AMD</b> <tt>require(['underscore'], ...)</tt>
+      </li>
+      <li>
+        <b>CommonJS</b> <tt>var _ = require('underscore');</tt>
       </li>
       <li>
         <b>ExtendScript</b> <tt>#include "underscore.js"</tt>
       </li>
+    </ul>
+
+    <h2>Modular Import</h2>
+
+    <ul>
+      <li>
+        <b>ESM</b> <tt>import map from 'underscore/modules/map.js'</tt>
+      </li>
+      <li>
+        <b>AMD</b> <tt>require(['underscore/amd/map.js'], ...)</tt>
+      </li>
       <li>
-        <b>Rollup</b> If you want to enable treeshaking and you don&rsquo;t
-        need the full <tt>_</tt> object (with all Underscore functions as
-        properties), you can import individual functions by name from
-        <tt>underscore/modules/index</tt> instead of <tt>underscore</tt>.
+        <b>CommonJS</b> <tt>var map = require('underscore/cjs/map.js');</tt>
       </li>
     </ul>
 
+    <p>
+      <i>For functions with multiple aliases, the file name of the module is
+      always the <b>first</b> name that appears in the documentation. For
+      example, <tt>_.reduce</tt>/<tt>_.inject</tt>/<tt>_.foldl</tt> is exported
+      from <tt>underscore/modules/reduce.js</tt>. Modular usage is mostly
+      recommended for creating a customized build of Underscore.</i>
+    </p>
+
     <div id="documentation">
 
       <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
@@ -966,17 +1045,24 @@ <h2 id="arrays">Array Functions</h2>
 </pre>
 
       <p id="flatten">
-        <b class="header">flatten</b><code>_.flatten(array, [shallow])</code>
+        <b class="header">flatten</b><code>_.flatten(array, [depth])</code>
         <br />
-        Flattens a nested <b>array</b> (the nesting can be to any depth). If you
-        pass <b>shallow</b>, the array will only be flattened a single level.
+        Flattens a nested <b>array</b>. If you pass <tt>true</tt> or <tt>1</tt>
+        as the <b>depth</b>, the array will only be flattened a single level.
+        Passing a greater number will cause the flattening to descend deeper
+        into the nesting hierarchy. Omitting the <b>depth</b> argument, or
+        passing <tt>false</tt> or <tt>Infinity</tt>, flattens the array all the
+        way to the deepest nesting level.
       </p>
       <pre>
 _.flatten([1, [2], [3, [[4]]]]);
 =&gt; [1, 2, 3, 4];
 
 _.flatten([1, [2], [3, [[4]]]], true);
 =&gt; [1, 2, 3, [[4]]];
+
+_.flatten([1, [2], [3, [[4]]]], 2);
+=&gt; [1, 2, 3, [4]];
 </pre>
 
       <p id="without">
@@ -1948,6 +2034,36 @@ <h2 id="objects">Object Functions</h2>
       <pre>
 _.isWeakSet(WeakSet());
 =&gt; true
+</pre>
+
+      <p id="isArrayBuffer">
+        <b class="header">isArrayBuffer</b><code>_.isArrayBuffer(object)</code>
+        <br />
+        Returns <i>true</i> if <b>object</b> is an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer">ArrayBuffer</a>.
+      </p>
+      <pre>
+_.isArrayBuffer(new ArrayBuffer(8));
+=&gt; true
+</pre>
+
+      <p id="isDataView">
+        <b class="header">isDataView</b><code>_.isDataView(object)</code>
+        <br />
+        Returns <i>true</i> if <b>object</b> is a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView">DataView</a>.
+      </p>
+      <pre>
+_.isDataView(new DataView(new ArrayBuffer(8)));
+=&gt; true
+</pre>
+
+      <p id="isTypedArray">
+        <b class="header">isTypedArray</b><code>_.isTypedArray(object)</code>
+        <br />
+        Returns <i>true</i> if <b>object</b> is a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray">TypedArray</a>.
+      </p>
+      <pre>
+_.isTypedArray(new Int8Array(8));
+=&gt; true
 </pre>
 
       <p id="isNaN">
@@ -2484,6 +2600,87 @@ <h2 id="notes">Notes</h2>
 
       <h2 id="changelog">Change Log</h2>
 
+      <p id="1.11.0">
+        <b class="header">1.11.0</b> &mdash; <small><i><!-- TODO: date --></i></small> &mdash; <a href="https://github.com/jashkenas/underscore/compare/1.10.2...1.11.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/underscore/1.11.0/index.html">Docs</a> &mdash; <a href="https://juliangonggrijp.com/article/introducing-modular-underscore.html">Article</a><br />
+        <ul>
+          <li>
+            Puts the source of every function in a separate module, following
+            up on the move to EcmaScript 6 <tt>export</tt> notation in <a
+            href="#1.10.0">version 1.10.0</a>. AMD and CommonJS versions of the
+            function modules are provided as well. This brings perfect
+            treeshaking to all users and unlocks the possibility to create
+            arbitrary custom Underscore builds without code size overhead.
+            <tt>modules/index.js</tt> is still present and the UMD bundle is
+            still recommended for most users.<br>
+            Since the modularization obfuscates the diff, piecewise diffs are provided below.
+            <ul>
+              <li><a href="https://github.com/jashkenas/underscore/compare/1.10.2...3236023">
+                Changes before modularization
+              </a></li>
+              <li><a href="https://github.com/jashkenas/underscore/compare/3236023...240d60a">
+                Modularization itself
+              </a></li>
+              <li><a href="https://github.com/jashkenas/underscore/compare/240d60a...1.11.0">
+                Changes after modularization
+              </a></li>
+            </ul>
+          </li>
+          <li>
+            Adds a monolithic bundle in EcmaScript 6 module format,
+            <tt>underscore-esm.js</tt>, as a modern alternative to the
+            monolithic UMD bundle. Users who want to use ES module imports in
+            the browser are advised to use this new bundle instead of
+            <tt>modules/index.js</tt>, because <tt>underscore-esm.js</tt>
+            provides the complete Underscore interface in a single download.
+          </li>
+          <li>
+            Adds a modular version of the annotated source, reflecting the full
+            internal structure of the primary source code.
+          </li>
+          <li>
+            Adds <tt>_.isArrayBuffer</tt>, <tt>_.isDataView</tt> and
+            <tt>_.isTypedArray</tt> functions, as well as support for the
+            corresponding value types to <tt>_.isEqual</tt>.
+          </li>
+          <li>
+            Adds the option to flatten arrays to a specific depth:
+            <tt>_.flatten(anArray, 3)</tt>.
+          </li>
+          <li>
+            Adds <tt>_.transpose</tt> as an alias to <tt>_.unzip</tt>.
+          </li>
+          <li>
+            Fixes an inconsistency where <tt>Array.prototype</tt> methods on
+            the Underscore wrapper would error when the wrapped value is
+            <tt>null</tt> or <tt>undefined</tt>. These methods now perform a
+            no-op on null values like the other Underscore functions.
+          </li>
+          <li>
+            Fixes a bug that caused <tt>_.first</tt> and <tt>_.last</tt> to
+            return <tt>[]</tt> instead of <tt>undefined</tt> for empty arrays
+            when used as an iteratee.
+          </li>
+          <li>
+            Fixes a regression introduced in version 1.9.0 that caused
+            <tt>_.bindAll</tt> to return <tt>undefined</tt> instead of the
+            bound object.
+          </li>
+          <li>
+            Restores continuous integration testing with Travis CI.
+          </li>
+          <li>
+            Replaces stigmatizing
+            &ldquo;whitelist&rdquo;/&ldquo;blacklist&rdquo; terminology in
+            comments and documentation by neutral
+            &ldquo;allowed&rdquo;/&ldquo;disallowed&rdquo; terminology.
+          </li>
+          <li>
+            Various clarifications and minor enhancements and fixes to the
+            documentation, source comments and a test.
+          </li>
+        </ul>
+      </p>
+
       <p id="1.10.2">
         <b class="header">1.10.2</b> &mdash; <small><i>March 30, 2020</i></small> &mdash; <a href="https://github.com/jashkenas/underscore/compare/1.10.1...1.10.2">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/underscore/1.10.2/index.html">Docs</a><br />
         <ul>

modules/debounce.js

@@ -2,9 +2,9 @@ import restArguments from './restArguments.js';
 import delay from './delay.js';
 
 // When a sequence of calls of the returned function ends, the argument
-// function is triggered. The end of a sequence is defined by the ‘wait’ 
-// parameter. If ‘immediate’ is passed, the argument function will be 
-// triggered at the beginning of the sequence as well. 
+// function is triggered. The end of a sequence is defined by the `wait`
+// parameter. If `immediate` is passed, the argument function will be
+// triggered at the beginning of the sequence instead of at the end.
 export default function debounce(func, wait, immediate) {
   var timeout, result;