feat: implement tag list to return the textual representation of an array

Author: customcommander

README.md

@@ -52,6 +52,7 @@ lower`I only had ${1} ${'BURRITO'}!`;
 
 * [defaults](#defaults) - _Replace an empty value with a default value_
 * [hide](#hide) - _Hides interpolated values_
+* [list](#list) - _Textual representation of an array_
 * [lower](#lower) - _Lowercase interpolated values_
 * [pluralize](#pluralize) - _Choose between singular or plural forms._
 * [time](#time) - _Format dates within a string._
@@ -132,6 +133,42 @@ Options:
    ```
 
 
+### list
+
+
+All items in the list are joined with `', '` expected for the last two items
+which are joined with `' and '`.
+
+```javascript
+import {list} from '@customcommander/tagtical';
+
+const arr = ['Huey', 'Dewey', 'Louie'];
+list`Hey ${arr}!`;
+//=> "Hey Huey, Dewey and Louie!"
+```
+
+Options:
+
+* __delim__ (default `', '`)
+
+  The string to use to join all items expect the last.
+
+   ```javascript
+   const arr = ['Huey', 'Dewey', 'Louie'];
+   list({delim: '; '})`Hey ${arr}!`;
+   //=> "Hey Huey; Dewey and Louie!"
+   ```
+* __delimlast__ (default `' and '`)
+
+  The string to use to join the last two items.
+
+   ```javascript
+   const arr = ['Huey', 'Dewey', 'Louie'];
+   list({delimlast: ' & '})`Hey ${arr}!`;
+   //=> "Hey Huey, Dewey & Louie!"
+   ```
+
+
 ### lower
 
 

src/index.js

@@ -3,6 +3,7 @@ const use_tag = require('./utils/use-tag');
 const intersperse = require('./utils/intersperse');
 const defaults = require('./defaults');
 const hide = require('./hide');
+const list = require('./list');
 const lower = require('./lower');
 const pluralize = require('./pluralize');
 const time = require('./time');
@@ -20,6 +21,7 @@ const tag = (...fns) =>
       (intersperse(strs, vals));
 
 tag.defaults = use_tag(defaults);
+tag.list = use_tag(list);
 tag.hide = use_tag(hide);
 tag.lower = use_tag(lower);
 tag.pluralize = use_tag(pluralize);

src/list.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright (c) 2020 Julien Gonzalez
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+const tag_function = require('./utils/tag-function');
+
+/**
+ * @typedef {Object} ListOpts
+ * @property {string} [delim=', ']
+ *    The string to use to join all items expect the last.
+ *
+ *    ```javascript
+ *    const arr = ['Huey', 'Dewey', 'Louie'];
+ *    list({delim: '; '})`Hey ${arr}!`;
+ *    //=> "Hey Huey; Dewey and Louie!"
+ *    ```
+ *
+ * @property {string} [delimlast=' and ']
+ *    The string to use to join the last two items.
+ *
+ *    ```javascript
+ *    const arr = ['Huey', 'Dewey', 'Louie'];
+ *    list({delimlast: ' & '})`Hey ${arr}!`;
+ *    //=> "Hey Huey, Dewey & Louie!"
+ *    ```
+ */
+
+/** @type ListOpts */
+const DEFAULT_OPTS =
+  { delim: ', '
+  , delimlast: ' and '
+  };
+
+/**
+ * Join `arr` according to given options `opts`.
+ * @param {ListOpts} opts
+ * @param {Array} arr
+ * @return {string}
+ */
+const join = ({delim, delimlast}, arr) =>
+    typeof delim !== 'string'      ? join({delim: DEFAULT_OPTS.delim, delimlast}, arr)
+  : typeof delimlast !== 'string'  ? join({delim, delimlast: DEFAULT_OPTS.delimlast}, arr)
+  : arr.length === 0               ? ''
+  : arr.length === 1               ? arr[0]
+  : arr.length === 2               ? arr[0] + delimlast + arr[1]
+                                   : arr.slice(0, -1).join(delim) + delimlast + arr[arr.length-1];
+
+/**
+ * Textual representation of an array
+ *
+ * All items in the list are joined with `', '` expected for the last two items
+ * which are joined with `' and '`.
+ *
+ * ```javascript
+ * import {list} from '@customcommander/tagtical';
+ *
+ * const arr = ['Huey', 'Dewey', 'Louie'];
+ * list`Hey ${arr}!`;
+ * //=> "Hey Huey, Dewey and Louie!"
+ * ```
+ */
+module.exports =
+  tag_function
+    ( (l, x, r, opts) =>
+        [ l
+        , Array.isArray(x)
+            ? join(opts, x)
+            : x
+        , r
+        ]
+    , DEFAULT_OPTS
+    );

test.js

@@ -3,6 +3,7 @@ const tag = require('./dist');
 const
   { defaults
   , hide
+  , list
   , lower
   , pluralize
   , time
@@ -197,3 +198,43 @@ test('lower: lowercase all values', t => {
     , 'I had bread, beans and covfefe for breakfast'
     );
 });
+
+test('list: returns a textual representation of a list', t => {
+  t.plan(6);
+
+  t.is
+    ( list`${[]}`
+    , ''
+    , 'An empty array returns an empty string'
+    );
+
+  t.is
+    ( list`${['foo']}`
+    , 'foo'
+    , 'A single-item array simply returns that item'
+    );
+
+  t.is
+    ( list`${['foo', 'bar']}`
+    , 'foo and bar'
+    , 'A pair is joined with the default `delimlast` option'
+    );
+
+  t.is
+    ( list`${['foo', 'bar', 'baz']}`
+    , 'foo, bar and baz'
+    , 'Items are joined with the default `delim` and `delimlast` options'
+    );
+
+  t.is
+    ( list({delim: 4, delimlast: 5})`${['foo', 'bar', 'baz']}`
+    , 'foo, bar and baz'
+    , '`delim` and `delimlast` must be string'
+    );
+
+  t.is
+    ( list({delim: '; ', delimlast: ' & '})`${['foo', 'bar', 'baz']}`
+    , 'foo; bar & baz'
+    , '`delim` and `delimlast` can be changed'
+    );
+});