feat: implement tag time to format dates within a string

README.md

@@ -59,6 +59,7 @@ lower`I only had ${num} ${food}!`;
 * [hide](#hide) - _Hides interpolated values_
 * [lower](#lower) - _Lowercase interpolated values_
 * [pluralize](#pluralize) - _Choose between singular or plural forms._
+* [time](#time) - _Format dates within a string._
 * [trim](#trim) - _Trim interpolated values_
 * [upper](#upper) - _Uppercase interpolated values_
 
@@ -198,6 +199,48 @@ the `pluralize` tag __won't__ perform any replacement on the adjacent text!
 
 _(The `pluralize` tag does not have any options.)_
 
+### time
+
+
+The `time` tag formats all interpolated dates according to a given format.
+
+```javascript
+import {time} from '@customcommander/tagtical';
+
+time`Last login on ${date}@Y-m-d`;
+//=> "Last login on 2020-01-09"
+```
+
+The format is attached to the date as follow `${date}@Y-m-d`.
+
+The `@` sign links a date with a format and the format is made of formatting characters
+as seen in [PHP's date function](https://www.php.net/manual/en/function.date.php).
+The format is removed from the string after processing.
+
+Only a subset of these options is supported at the moment:
+
+| Character | Description |
+|:----------|:------------------------------------------------|
+| Y | Year. Four digits |
+| y | Year. Two digits |
+| m | Month. Two digits with leading zeros. e.g. "01" |
+| n | Month. No leading zeros. e.g. "1" |
+| d | Day. Two digits; leading zeros. e.g. "01" |
+| j | Day. No leading zeros. e.g. "1" |
+
+Anything that isn't a formatting character is rendered as is.
+
+When an interpolated value isn't a date, the value is rendered as is and the date format is removed.
+
+```javascript
+time`Last login on ${0/0}@Y-m-d`;
+//=> Last login on NaN
+```
+
+
+
+_(The `time` tag does not have any options.)_
+
 ### trim
 
 

src/index.js

@@ -1,15 +1,19 @@
 const tag_function = require('./utils/tag-function');
 const use_tag = require('./utils/use-tag');
-const join = require('./utils/join');
 const intersperse = require('./utils/intersperse');
-const compose = require('./utils/compose');
 const defaults = require('./defaults');
 const hide = require('./hide');
 const lower = require('./lower');
 const pluralize = require('./pluralize');
+const time = require('./time');
 const trim = require('./trim');
 const upper = require('./upper');
 
+const
+ { compose
+ , join
+ } = require('./utils/fp');
+
 const tag = (...fns) =>
  (strs, ...vals) =>
  compose(join(''), ...fns.map(use_tag.unwrap))
@@ -19,6 +23,7 @@ tag.defaults = use_tag(defaults);
 tag.hide = use_tag(hide);
 tag.lower = use_tag(lower);
 tag.pluralize = use_tag(pluralize);
+tag.time = use_tag(time);
 tag.trim = use_tag(trim);
 tag.upper = use_tag(upper);
 tag.of = compose(use_tag, tag_function);

src/time.js

@@ -0,0 +1,161 @@
+/**
+ * @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');
+
+const
+ { compose
+ , constant
+ , fallback
+ , join
+ , map
+ , match
+ , split
+ , tail
+ , trim
+ } = require('./utils/fp');
+
+const INVALID_DATE = String(new Date('All those moments will be lost in time, like tears in the rain.'));
+const RE = /^\s*@\S+/;
+
+/** @enum {string} */
+const formatOptions =
+ { DAY_NUM_LEADING_ZEROS: 'd'
+ , DAY_NUM: 'j'
+ , MONTH_NUM_LEADING_ZEROS: 'm'
+ , MONTH_NUM: 'n'
+ , YEAR_NUM_LONG: 'Y'
+ , YEAR_NUM: 'y'
+ };
+
+/**
+ * @type {Object<string, function(Date): string>}
+ */
+const formatFunctions =
+ { [formatOptions.DAY_NUM_LEADING_ZEROS]:
+ d => String(d.getDate()).padStart(2, '0')
+
+ , [formatOptions.DAY_NUM]:
+ d => String(d.getDate())
+
+ , [formatOptions.MONTH_NUM_LEADING_ZEROS]:
+ d => String(d.getMonth() + 1).padStart(2, '0')
+
+ , [formatOptions.MONTH_NUM]:
+ d => String(d.getMonth() + 1)
+
+ , [formatOptions.YEAR_NUM_LONG]:
+ d => String(d.getFullYear())
+
+ , [formatOptions.YEAR_NUM]:
+ d => String(d.getFullYear()).slice(-2)
+ };
+
+const is_date =
+ x =>
+ x instanceof Date
+ && String(x) !== INVALID_DATE;
+
+/**
+ * Extract a date format from a string
+ *
+ * @example
+ * get_format('@Y-m-d some extraneous text');
+ * //=> "Y-m-d"
+ *
+ * @function
+ * @param {string} str
+ * @return {string}
+ */
+const get_format =
+ compose
+ ( tail
+ , trim
+ , fallback('')
+ , match(RE)
+ );
+
+const clear_format = str => str.replace(RE, '');
+
+const formatter =
+ d =>
+ f =>
+ (formatFunctions[f] || constant(f))
+ (d);
+
+const format =
+ (f, d) =>
+ compose
+ ( join('')
+ , map(formatter(d))
+ , split(/([^Yymndj]+)/)
+ )(f);
+
+/**
+ * Format dates within a string.
+ *
+ * The `time` tag formats all interpolated dates according to a given format.
+ *
+ * ```javascript
+ * import {time} from '@customcommander/tagtical';
+ * 
+ * time`Last login on ${date}@Y-m-d`;
+ * //=> "Last login on 2020-01-09"
+ * ```
+ *
+ * The format is attached to the date as follow `${date}@Y-m-d`.
+ *
+ * The `@` sign links a date with a format and the format is made of formatting characters
+ * as seen in [PHP's date function](https://www.php.net/manual/en/function.date.php).
+ * The format is removed from the string after processing.
+ *
+ * Only a subset of these options is supported at the moment:
+ *
+ * | Character | Description |
+ * |:----------|:------------------------------------------------|
+ * | Y | Year. Four digits |
+ * | y | Year. Two digits |
+ * | m | Month. Two digits with leading zeros. e.g. "01" |
+ * | n | Month. No leading zeros. e.g. "1" |
+ * | d | Day. Two digits; leading zeros. e.g. "01" |
+ * | j | Day. No leading zeros. e.g. "1" |
+ *
+ * Anything that isn't a formatting character is rendered as is.
+ *
+ * When an interpolated value isn't a date, the value is rendered as is and the date format is removed.
+ *
+ * ```javascript
+ * time`Last login on ${0/0}@Y-m-d`;
+ * //=> Last login on NaN
+ * ```
+ */
+module.exports =
+ tag_function
+ ( (l, x, r) =>
+ [ l
+ , !is_date(x) || !get_format(r)
+ ? x
+ : format(get_format(r), x)
+ , clear_format(r)
+ ]
+ );