Closed #2: Added support for accented characters

- Upgraded Webpack to v3.0.0
- Upgraded ESLint to v4.0.0
- Upgraded Babel and others

Author: jherax

.eslintrc.json

@@ -17,19 +17,20 @@
   "globals": {},
   "parser": "babel-eslint",
   "parserOptions": {
-    "ecmaVersion": 6,
     "sourceType": "module",
+    "codeFrame": true,
+    "ecmaVersion": 6,
     "ecmaFeatures": {
       "impliedStrict": true,
       "experimentalObjectRestSpread": true
     }
   },
   "rules": {
     "valid-jsdoc": [1, {
-      "requireParamDescription": false,
+      "requireParamDescription": true,
       "requireReturnDescription": false,
-      "requireReturn": false,
       "requireReturnType": true,
+      "requireReturn": false,
       "prefer": { "returns": "return" }
     }],
     "require-jsdoc": [2, {
@@ -42,6 +43,7 @@
     "one-var": [2, {
       "uninitialized": "always"
     }],
+    "one-var-declaration-per-line": [2, "initializations"],
     "max-len": 0,
     "no-param-reassign": 0,
     "no-underscore-dangle": 0,

README.md

@@ -2,15 +2,15 @@
 
 <!-- markdownlint-disable MD033 MD034 MD014 -->
 
-The motivation for creating this utility was to provide a mechanism to organize elements,
-with the ability to specify multiple ordering criteria.
+Sorts an array and allows specify multiple sorting criteria.
+It has support for accented characters, and also ignore case sensitive.
 
 ## Content
 
 1. [Getting started](#getting-started)
 1. [Including the library](#including-the-library)
 1. [Examples](#examples)
-1. [Shimming-polyfills](#shimming-polyfills)
+1. [Polyfills](#polyfills)
 1. [Running the project](#running-the-project)
 
 ## Getting started
@@ -25,41 +25,54 @@ $ npm install array-sort-by --save
 $ yarn add array-sort-by
 ```
 
-The library has been written as an **ES2015 Module** and the exported module has the following signature:
+The `sortBy` function has the following signature:
 
 ```javascript
-/*
- * @param  {Array} array: the list of elements to sort
- * @param  {Function} parser: transforms each item and specifies the sort order
+/**
+ * @param  {Array} array: the collection of elements to sort
+ * @param  {Function} parser: transforms each item and specifies the sorting order
  * @return {Array}
  */
-function sortBy(array, /*optional*/ parser);
+sortBy(array: Array, parser: Function) : Array
+sortBy(array: Array) : Array
 ```
 
-The optional parameter `parser` is a function that transforms each element being iterated and sets the sort rules:
-ascending, descending, and multiple fields for sorting. It has the following signature:
+The optional parameter `parser` is a function that transforms each element
+being iterated and sets the sorting rules: _ascending_ or _descending_, and
+the option to specify multiple fields for sorting.
+
+The `parser` callback has the following signature:
 
 ```javascript
-/*
+/**
  * @param  {Any} item: the element being iterated over the list
  * @param  {Number} index: the index of the element in the list
  * @return {Any}
  */
-function parser(item, index);
+parser(item: Any, index: Number) : Any
+parser(item: Any) : Any
 ```
 
+[&#9751; Back to Index](#content)
+
 ## Including the library
 
-`array-sort-by` can be included directly from a CDN in your page:
+`array-sort-by` can be included directly from a CDN in your site:
 
 ```html
-<script src="https://cdn.rawgit.com/jherax/array-sort-by/1.0.3/dist/sort-by.min.js"></script>
+<!-- from unpkg.com -->
+<script src="https://unpkg.com/array-sort-by/dist/sort-by.min.js"></script>
+
+<!-- or from rawgit.com -->
+<script src="https://cdn.rawgit.com/jherax/array-sort-by/1.1.0/dist/sort-by.min.js"></script>
 ```
 
-In the above case, the function [`sortBy`](#examples) is included as a global object in the browser.
+In the above case, the function [`sortBy`](#examples) is included as
+global object in the browser.
 
-As this library is built as an [UMD](http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/)
-(Universal Module Definition), it can be included from a module loader as AMD, CommonJS, or ES2015 Export.
+As `sortBy` is built as [UMD] _(Universal Module Definition)_, it can
+be included from module loaders such as [CommonJS], [ES2015 Export]
+or [AMD RequireJS].
 
 ### CommonJS
 
@@ -88,7 +101,9 @@ require(['array-sort-by'], function(sortBy) {
 });
 ```
 
-See an example with RequireJS here: http://jsfiddle.net/FdKTn/69/
+See an example with RequireJS here: http://jsfiddle.net/FdKTn/73/
+
+[&#9751; Back to Index](#content)
 
 ## Examples
 
@@ -98,7 +113,7 @@ See an example with RequireJS here: http://jsfiddle.net/FdKTn/69/
 let arr = [10, 8, 5, 3, 0, 7, 4, 5, 1];
 sortBy(arr);
 
-/*
+/**
  * expected:
  * [0, 1, 3, 4, 5, 5, 7, 8, 10]
  */
@@ -110,7 +125,7 @@ sortBy(arr);
 let arr = [5, 1, 8, 0, 3, 7, 10, 4, 3, 8];
 sortBy(arr, n => -n);
 
-/*
+/**
  * expected:
  * [10, 8, 8, 7, 5, 4, 3, 3, 1, 0]
  */
@@ -122,7 +137,7 @@ sortBy(arr, n => -n);
 let arr = ["1983/03/06", "1980/12/24", "1985/08/31", "1983/03/05"];
 sortBy(arr, (s) => -new Date(s));
 
-/*
+/**
  * expected:
  * ["1985/08/31", "1983/03/06", "1983/03/05", "1980/12/24"]
  */
@@ -136,12 +151,50 @@ Because we use the minus **(-)** symbol to specify a descending order, it will p
 let arr = ["1983/03/06", "1980/12/24", "1985/08/31", "1983/03/05"];
 sortBy(arr, (s) => "desc:" + s);
 
-/*
+/**
  * expected:
  * ["1985/08/31", "1983/03/06", "1983/03/05", "1980/12/24"]
  */
 ```
 
+### Sorting accented words
+
+```javascript
+var arr = ['único', 'cosas', 'Árbol', 'fútbol', 'algo'];
+sortBy(arr);
+/**
+ * expected:
+ * ["algo", "Árbol", "cosas", "fútbol", "único"]
+ */
+
+sortBy(arr, item => 'desc:' + item);
+/**
+ * expected:
+ * ["único", "fútbol", "cosas", "Árbol", "algo"]
+ */
+```
+
+### Sorting accented words by @n
+
+```javascript
+var arr = [
+  { n: 'Woche' },
+  { n: 'wöchentlich' },
+  { n: 'wäre' }
+];
+
+sortBy(arr, item => item.n);
+
+/**
+ * expected:
+ * [
+ *   { n: "wäre" },
+ *   { n: "Woche" },
+ *   { n: "wöchentlich" }
+ * ]
+ */
+```
+
 ### Sorting DESC by @a, after ASC by @d (as Date)
 
 ```javascript
@@ -154,7 +207,7 @@ let arr = [
 
 sortBy(arr, (o) => [-o.a, new Date(o.d)]);
 
-/*
+/**
  * expected:
  * [
  *   { a: 8, d: "1983/03/06" },
@@ -165,53 +218,55 @@ sortBy(arr, (o) => [-o.a, new Date(o.d)]);
  */
 ```
 
-### Sorting DESC by @name (ignore case sensitive)
+### Sorting DESC by @name
 
 ```javascript
 let arr = [
   { id: 4, name: "Pedro" },
-  { id: 6, name: "Lucia" },
+  { id: 6, name: "Lucía" },
   { id: 7, name: "paco" },
   { id: 3, name: "luis" }
 ];
 
-sortBy(arr, (o) => "DESC:" + o.name.toUpperCase());
+sortBy(arr, item => "DESC:" + item.name);
 
-/*
+/**
  * expected:
  * [
  *   { id: 4, name: "Pedro" },
  *   { id: 7, name: "paco" },
  *   { id: 3, name: "luis" },
- *   { id: 6, name: "Lucia" }
+ *   { id: 6, name: "Lucía" }
  * ]
  */
 ```
 
-### Sorting ASC by @name (ignore case sensitive), after DESC by @age, after ASC by @a
+### Sorting ASC by @name, after DESC by @age, after ASC by @a
 
 ```javascript
 let arr = [
   { a: 4, age: 26, name: "pedro" },
   { a: 6, age: 32, name: "Pedro" },
-  { a: 7, age: 26, name: "Luis" },
-  { a: 2, age: 26, name: "luis" }
+  { a: 7, age: 26, name: "Maria" },
+  { a: 2, age: 26, name: "maría" }
 ];
 
-sortBy(arr, (o) => [o.name.toUpperCase(), -o.age, o.a]);
+sortBy(arr, item => [item.name, -item.age, item.a]);
 
-/*
+/**
  * expected:
  * [
- *   { a: 2, age: 26, name: "luis" },
- *   { a: 7, age: 26, name: "Luis" },
+ *   { a: 2, age: 26, name: "maría" },
+ *   { a: 7, age: 26, name: "Maria" },
  *   { a: 6, age: 32, name: "Pedro" },
  *   { a: 4, age: 26, name: "pedro" }
  * ]
  */
 ```
 
-## Shimming-polyfills
+[&#9751; Back to Index](#content)
+
+## Polyfills
 
 This library is written using some of the new ES5/ES6 features. If you have
 to support Non-standard-compliant browsers like Internet Explorer, you can
@@ -247,28 +302,29 @@ to the url, for example:
 Read the list of available features:
 [Features and Browsers Supported](https://polyfill.io/v2/docs/features/).
 
+[&#9751; Back to Index](#content)
+
 ## Running the project
 
 If you want to fork or build your own, you must run this project.
 
 ### Requirements
 
-1. Git ([git-linux](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-   or [git-windows](https://git-for-windows.github.io/)).
+1. Git on [linux](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+   or [windows](https://git-for-windows.github.io/).
 1. [Node.js](https://nodejs.org/en/) (latest stable version v6+).<br>
-   It is preferable install **[nvm](https://github.com/creationix/nvm)**
-   (Node Version Manager).
-1. [Yarn](https://yarnpkg.com/en/docs/cli/) installed as a global package.
+   It is preferable install [nvm](https://github.com/creationix/nvm)
+   (node version manager).
+1. [Yarn](https://yarnpkg.com/en/docs/cli/) installed as global package.
 
-**NOTE**: Consider install Node Version Manager (**nvm**) to upgrade easily the NodeJS version.
-<br>Go to https://github.com/creationix/nvm and check the installation process for your OS.
+**NOTE**: Consider install Node Version Manager (**nvm**) to upgrade easily
+the Node version.<br>Go to https://github.com/creationix/nvm and check the
+installation process for your OS.
 
-If you are running Windows, you can install
-[nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows).
-Follow every step mentioned
-[here](https://github.com/coreybutler/nvm-windows#installation--upgrades)
-so that nvm will be correctly installed to manage multiple installations
-of **node.js** (with **npm**) on a Windows computer.
+If you are running Windows, you can install [nvm-windows]. Follow every
+step mentioned [here][nvm-windows-install] so that **nvm** will be correctly
+installed to manage multiple installations of **Node** (with **npm**)
+on a Windows computer.
 
 ### Building the project
 
@@ -296,20 +352,27 @@ And finally execute the webpack task:
 $ yarn run build
 ```
 
-This command will lint the code with [ESLint](http://eslint.org/docs/user-guide/getting-started) and transpile the source files from `src/` to `dist/` as an [UMD](http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/) with [Babel](https://babeljs.io/). It also generates the minified and source map files.
+This command will lint the code with
+[ESLint](http://eslint.org/docs/user-guide/getting-started)
+and transpile the source files from `src/` to `dist/` as an [UMD] with
+[Babel](https://babeljs.io/). It also generates the minified and source map
+files.
+
+[&#9751; Back to Index](#content)
 
 ## Versioning
 
-This projects adopts the [Semantic Versioning](http://semver.org/) (SemVer) guidelines:
+This projects adopts the [Semantic Versioning](http://semver.org/)
+(SemVer) guidelines:
 
 ```text
 <MAJOR>.<MINOR>.<PATCH>
 ```
 
 Given a version number MAJOR.MINOR.PATCH, increment the:
 
-1. MAJOR version when you make incompatible API changes
-1. MINOR version when you add functionality in a backwards-compatible manner
+1. MAJOR version when you make incompatible API changes.
+1. MINOR version when you add functionality in a backwards-compatible manner.
 1. PATCH version when you make backwards-compatible bug fixes.
 
 ## Issues
@@ -323,3 +386,12 @@ To report an issue and keep traceability of bug-fixes, please report to:
 This project has been released under the [ISC](https://opensource.org/licenses/ISC) license.
 This license applies ONLY to the source of this repository and does not extend to any other distribution,
 or any other 3rd party libraries used in a repository. See [LICENSE](LICENSE) file for more information.
+
+<!-- LINKS -->
+
+[UMD]: http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/
+[CommonJS]: https://blog.risingstack.com/node-js-at-scale-module-system-commonjs-require/
+[ES2015 Export]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
+[AMD RequireJS]: http://requirejs.org/docs/api.html#jsfiles
+[nvm-windows]: https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows
+[nvm-windows-install]: https://github.com/coreybutler/nvm-windows#installation--upgrades