@valkyriestudios/utils 12.23.0 → 12.25.0

package/README.md

@@ -30,7 +30,7 @@ isNotEmptyArray([]); // FALSE
 isNotEmptyArray([0, 1, 2]); // TRUE
 ```
 
-### array/mapKey(val:Record[], key:string, opts:object={})
+### array/mapKey(val:Record[], key:string, opts?:{merge?:boolean;filter_fn?:(el:T) => boolean})
 Map a non-primitive object array into an object map by key
 ```typescript
 import mapKey from '@valkyriestudios/utils/array/mapKey';
@@ -39,9 +39,7 @@ mapKey([
     {uid: 15, name: 'Jonas'},
     {uid: 87, name: 'Josh'},
 ], 'uid');
-
-output:
-
+/* Expected output: */
 {
     12: {uid: 12, name: 'Peter'},
     15: {uid: 15, name: 'Jonas'},
@@ -64,9 +62,7 @@ mapKey([
     new Date(),
     {uid: 87, name: 'Josh'},
 ], 'uid');
-
-output:
-
+/* Expected output: */
 {
     12: {uid: 12, name: 'Peter'},
     15: {uid: 15, name: 'Jonas'},
@@ -92,9 +88,7 @@ mapKey([
     {uid: 87, name: 'Josh'},
     {uid: 12, name: 'Farah'},
 ], 'uid', {merge: true})
-
-output:
-
+/* Expected output: */
 {
     12: {uid: 12, name: 'Farah'},
     15: {uid: 15, name: 'Bob', dob: '2022-02-07'},
@@ -102,6 +96,24 @@ output:
 }
 ```
 
+allows filtering out objects with a custom filter_fn:
+```typescript
+import mapKey from '@valkyriestudios/utils/array/mapKey';
+mapKey([
+    {uid: 12, name: 'Peter', isActive: true},
+    {uid: 15, name: 'Jonas', dob: '2022-02-07', isActive: true},
+    {uid: 15, name: 'Bob', isActive: false},
+    {name: 'Alana', isActive: true},
+    {uid: 87, name: 'Josh', isActive: false},
+    {uid: 12, name: 'Farah', isActive: false},
+], 'uid', {merge: true})
+/* Expected output: */
+{
+    12: {uid: 12, name: 'Peter', isActive: true},
+    15: {uid: 15, name: 'Jonas', dob: '2022-02-07'},
+}
+```
+
 ### array/mapFn(val:Record[], key:Function, opts:object={})
 Same behavior as mapKey but instead of a key, a function is passed to generate your own key. Eg:
 
@@ -112,9 +124,7 @@ mapFn([
     {uid: 15, name: 'Jonas'},
     {uid: 87, name: 'Josh'},
 ], el => el.uid)
-
-output:
-
+/* Expected output: */
 {
     12: {uid: 12, name: 'Peter'},
     15: {uid: 15, name: 'Jonas'},
@@ -124,7 +134,7 @@ output:
 
 options are the same as the mapKey function
 
-### array/mapPrimitive(val:any[], opts:object={valtrim:false,keyround:false,valround:false})
+### array/mapPrimitive(val:any[], opts?:{valtrim:false;keyround:false;valround:false;filter_fn:(el)=>boolean})
 Map an array of primitives (number/string)
 ```typescript
 import mapPrimitive from '@valkyriestudios/utils/array/mapPrimitive';
@@ -133,6 +143,12 @@ mapPrimitive(['hello', 'hello', 'foo', 'bar']); // {hello: 'hello', foo: 'foo',
 mapPrimitive(['hello', ' hello', 'foo', '  foo'], {valtrim: true}); // {hello: 'hello', foo: 'foo'}
 ```
 
+Allows filtering out unwanted values:
+```typescript
+import mapPrimitive from '@valkyriestudios/utils/array/mapPrimitive';
+mapPrimitive([1,2,'bla', 3, false], {filter_fn: isNumber}); // {1: 1, 2: 2, 3: 3}
+```
+
 ### array/groupBy(val:Record[], handler:Function|string)
 Return a grouped object from an array. This function **will automatically filter out any non/empty objects**.
 
@@ -428,7 +444,15 @@ Available tokens for usage in spec:
 | `Z` | Zone, does not allow full zone names, only Z or offsets | `Z` `+02:00` |
 | `ISO` | Check for full iso date format, take note this enforces milliseconds as a requirement | 2024-02-03T10:28:30.000Z |
 
-Note: The `ISO` token is a shorthand for `YYYY-MM-DDTHH:mm:ss.SSSZ`
+Allows for marking certain portions as optional by wrapping in `{...}`:
+```typescript
+import isFormat from '@valkyriestudios/utils/date/isFormat';
+isFormat('2024-02-07', 'YYYY-MM-DD{THH:mm:ss}'); // true
+isFormat('2024-02-07T14:50', 'YYYY-MM-DD{THH:mm:ss}'); // false, optional part passed but invalid
+isFormat('2024-02-07T14:50:30', 'YYYY-MM-DD{THH:mm:ss}'); // true
+```
+
+Note: The `ISO` token is a shorthand for `YYYY-MM-DDTHH:mm:ss{.SSS}Z`
 Note: You can escape characters by surrounding them with `[...]` in your spec, eg: `YYYY-[Q]Q` would check for example `2024-Q1`
 
 ### date/diff(val_a:Date, val_b:Date, key:string)
@@ -787,7 +811,7 @@ isFormData(new FormData()); // TRUE
 isFormData({hi: 'there'}); // FALSE
 ```
 
-### formdata/toObject(val:FormData, {raw?:string[]|true;single?:string[]} = {})
+### formdata/toObject(val:FormData, {raw?:string[]|true;single?:string[];normalize_bool?:boolean;normalize_date?:bool;normalize_number?:bool} = {})
 Converts an instance of FormData to an object
 ```typescript
 import toObject from '@valkyriestudios/utils/formdata/toObject';
@@ -800,7 +824,7 @@ form.append('emptyField', '');
 toObject(form); // {name: 'Alice', hobbies: ['reading', 'writing'], emptyField: ''}
 ```
 
-Automatically converts strings to numbers and booleans, and nests objects/arrays based on key structures:
+Automatically converts strings to numbers, dates, booleans and nests objects/arrays based on key structures:
 ```typescript
 const form = new FormData();
 form.append('user[0].name', 'Alice');
@@ -853,6 +877,24 @@ formData.append('action', 'reset');
 toObject(formData, { single: ['status', 'action'] }) /* {status: 'inactive', action: 'reset'} */
 ```
 
+Allows configuring what types of data to normalize:
+```typescript
+const form = new FormData();
+form.append('pincode', '0123');
+form.append('enabled', 'false');
+form.append('config.isGood', 'true');
+form.append('config.amount', ' 50 ');
+
+toObject(form, {raw: ['pincode'], normalize_bool: false}); /* {
+    pincode: '0123',
+    enabled: 'false',
+    config: {
+        isGood: 'true',
+        amount: 50,
+    },
+} */
+```
+
 ### hash/guid()
 Generate a unique identifier (guid) according to RFC4122
 ```typescript

package/array/join.js

@@ -4,7 +4,7 @@ exports.join = join;
 exports.default = join;
 const round_1 = require("../number/round");
 const isIntegerAboveOrEqual_1 = require("../number/isIntegerAboveOrEqual");
-const SPACE_RGX = /(\s){2,}/g;
+const SPACE_RGX = /(\s)+/g;
 function join(val, opts) {
     if (!Array.isArray(val) || !val.length)
         return '';
@@ -17,9 +17,12 @@ function join(val, opts) {
     let hasVal = false;
     for (let i = 0; i < val.length; i++) {
         const el = val[i];
-        if (typeof el === 'string' && el.trim().length) {
-            const trimmed = VALTRIM ? el.trim() : el;
-            result = result + (hasVal ? DELIM : '') + (INNERTRIM ? trimmed.replace(SPACE_RGX, ' ') : trimmed);
+        if (typeof el === 'string') {
+            const trimmed = el.trim();
+            if (!trimmed)
+                continue;
+            const n_el = VALTRIM ? trimmed : el;
+            result = result + (hasVal ? DELIM : '') + (INNERTRIM ? n_el.replace(SPACE_RGX, ' ') : n_el);
             hasVal = true;
         }
         else if (Number.isFinite(el)) {

package/array/mapFn.d.ts

@@ -1,4 +1,4 @@
-interface mapOptions {
+type MapOptions = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -11,8 +11,8 @@ interface mapOptions {
      *  {12: {uid: 12, b: 'ho'}}
      */
     merge?: boolean;
-}
-type mapFn<T extends Record<string, any>> = (entry: T) => (string | number | boolean);
+};
+type MapFn<T extends Record<string, any>> = (entry: T) => (string | number | boolean);
 /**
  * Map an object array into a kv-object through a function that generates a key. Returning a non-string,
  * non-numeric value from the function (eg: false) will filter out the object.
@@ -23,10 +23,10 @@ type mapFn<T extends Record<string, any>> = (entry: T) => (string | number | boo
  *  {12: {uid: 12, name: 'Peter'}, 15: {uid: 15, name: 'Jonas'}}
  *
  * @param {Record<string, any>[]} val - Array to map
- * @param {mapFn} fn - Handler function which is run for each of the objects and should return a string or number
- * @param {mapOptions?} opts - Options object to override built-in defaults
+ * @param {MapFn} fn - Handler function which is run for each of the objects and should return a string or number
+ * @param {MapOptions?} opts - Options object to override built-in defaults
  *
  * @returns {Record<string, T>} KV-Map object
  */
-declare function mapFn<T extends Record<string, any>>(arr: T[], fn: mapFn<T>, opts?: mapOptions): Record<string, T>;
+declare function mapFn<T extends Record<string, any>>(arr: T[], fn: MapFn<T>, opts?: MapOptions): Record<string, T>;
 export { mapFn, mapFn as default };

package/array/mapFn.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapFn = mapFn;
 exports.default = mapFn;
+const merge_1 = require("../object/merge");
 function mapFn(arr, fn, opts) {
     if ((!Array.isArray(arr) || !arr.length) ||
         typeof fn !== 'function')
@@ -17,7 +18,7 @@ function mapFn(arr, fn, opts) {
         if (!Number.isFinite(hash) && !(typeof hash === 'string' && hash.trim().length))
             continue;
         hash = hash + '';
-        map[hash] = MERGE && map[hash] !== undefined ? { ...map[hash], ...el } : el;
+        map[hash] = (MERGE && hash in map ? (0, merge_1.merge)(map[hash], el, { union: true }) : el);
     }
     return map;
 }

package/array/mapKey.d.ts

@@ -1,4 +1,4 @@
-interface mapOptions {
+type MapOptions<T> = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -11,7 +11,11 @@ interface mapOptions {
      *  {12: {uid: 12, b: 'ho'}}
      */
     merge?: boolean;
-}
+    /**
+     * Pass a custom filter function which will be run in O(n) while iterating
+     */
+    filter_fn?: (el: T) => boolean;
+};
 /**
  * Map an object array into a kv-object by passing a common key that exists on the objects. Objects for
  * which the key doesn't exist will be filtered out automatically
@@ -23,9 +27,9 @@ interface mapOptions {
  *
  * @param {Record<string,any>[]} val - Array to map
  * @param {string} key - Key to map by
- * @param {mapOptions?} opts - Options object to override built-in defaults
+ * @param {MapOptions?} opts - Options object to override built-in defaults
  *
  * @returns {Record<string, T>} KV-Map object
  */
-declare function mapKey<T extends Record<string, any>>(arr: T[], key: string, opts?: mapOptions): Record<string, T>;
+declare function mapKey<T extends Record<string, any>>(arr: T[], key: string, opts?: MapOptions<T>): Record<string, T>;
 export { mapKey, mapKey as default };

package/array/mapKey.js

@@ -2,15 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapKey = mapKey;
 exports.default = mapKey;
+const merge_1 = require("../object/merge");
 function mapKey(arr, key, opts) {
     if (!Array.isArray(arr) || typeof key !== 'string')
         return {};
-    const key_s = key.trim();
-    if (!key_s.length)
-        return {};
     const len = arr.length;
     if (!len)
         return {};
+    const key_s = key.trim();
+    if (!key_s.length)
+        return {};
+    const FILTER_FN = opts?.filter_fn;
     const MERGE = opts?.merge === true;
     const map = {};
     for (let i = 0; i < len; i++) {
@@ -18,7 +20,9 @@ function mapKey(arr, key, opts) {
         const el_key = el?.[key_s];
         if (el_key === undefined)
             continue;
-        map[el_key] = MERGE && el_key in map ? { ...map[el_key], ...el } : el;
+        if (FILTER_FN && !FILTER_FN(el))
+            continue;
+        map[el_key] = (MERGE && el_key in map ? (0, merge_1.merge)(map[el_key], el, { union: true }) : el);
     }
     return map;
 }

package/array/mapPrimitive.d.ts

@@ -1,4 +1,4 @@
-interface mapOptions {
+type MapOptions = {
     /**
      * Automatically trim all string values
      * (default=false)
@@ -18,7 +18,11 @@ interface mapOptions {
      * eg: mapPrimitive([5.432, 5.4, 5.43, 4.2, 4.1], {keyround: true}) -> {5: 5.43, 4: 4.1}
      */
     keyround?: boolean;
-}
+    /**
+     * Pass a custom filter function which will be run in O(n) while iterating
+     */
+    filter_fn?: (el: unknown) => boolean;
+};
 type mapReturn = Record<string, string | number>;
 /**
  * Map an array of primitive values (numbers/strings) into a kv-object
@@ -30,7 +34,7 @@ type mapReturn = Record<string, string | number>;
  *  {hello: 'hello', foo: 'foo', bar: 'bar'}
  *
  * @param {unknown[]} val - Array to map
- * @param {mapOptions?} opts - Options object to override built-in defaults
+ * @param {MapOptions?} opts - Options object to override built-in defaults
  */
-declare function mapPrimitive(arr: unknown[], opts?: mapOptions): mapReturn;
+declare function mapPrimitive(arr: unknown[], opts?: MapOptions): mapReturn;
 export { mapPrimitive, mapPrimitive as default };

package/array/mapPrimitive.js

@@ -10,23 +10,26 @@ function mapPrimitive(arr, opts = {}) {
     const VALTRIM = opts?.valtrim === true;
     const VALROUND = (0, isIntegerAboveOrEqual_1.isIntegerAboveOrEqual)(opts?.valround, 0)
         ? opts?.valround
-        : opts?.valround === true;
+        : opts?.valround === true
+            ? 0
+            : null;
     const KEYROUND = opts?.keyround === true;
+    const FILTER_FN = opts?.filter_fn;
     const map = {};
     for (let i = 0; i < arr.length; i++) {
         const el = arr[i];
+        if (FILTER_FN && !FILTER_FN(el))
+            continue;
         if (typeof el === 'string') {
             const trimmed = el.trim();
-            if (!trimmed.length)
+            if (!trimmed)
                 continue;
             map[trimmed] = VALTRIM ? trimmed : el;
         }
-        else if (typeof el === 'number' && Number.isFinite(el)) {
-            map[`${KEYROUND ? Math.round(el) : el}`] = VALROUND === false
+        else if (Number.isFinite(el)) {
+            map[`${KEYROUND ? Math.round(el) : el}`] = VALROUND === null
                 ? el
-                : VALROUND === true
-                    ? Math.round(el)
-                    : (0, round_1.round)(el, VALROUND);
+                : (0, round_1.round)(el, VALROUND);
         }
     }
     return map;

package/date/addUTC.d.ts

@@ -2,9 +2,9 @@ export type AddUTCKey = 'years' | 'year' | 'months' | 'month' | 'days' | 'day' |
 /**
  * Adds the provided amount of a specific key to the provided date
  *
- * @param {Date} val - Date to set to end of
+ * @param {Date|string} val - Date to set to end of
  * @param {number} amount - (default=0) Amount of key to add
  * @param {AddUTCKey} key - (default='millisecond') Key to set
  */
-declare function addUTC(val: Date, amt?: number, key?: AddUTCKey): Date;
+declare function addUTC(val: Date | string, amt?: number, key?: AddUTCKey): Date;
 export { addUTC, addUTC as default };

package/date/addUTC.js

@@ -2,19 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addUTC = addUTC;
 exports.default = addUTC;
-const is_1 = require("./is");
+const convertToDate_1 = require("./convertToDate");
 function addUTC(val, amt = 0, key = 'millisecond') {
-    if (!(0, is_1.isDate)(val))
-        throw new TypeError('addUTC requires a date object');
     if (!Number.isInteger(amt))
         throw new TypeError('Amount needs to be an integer');
-    const year = val.getUTCFullYear();
-    const month = val.getUTCMonth();
-    const date = val.getUTCDate();
-    const hour = val.getUTCHours();
-    const min = val.getUTCMinutes();
-    const sec = val.getUTCSeconds();
-    const ms = val.getUTCMilliseconds();
+    const n_val = (0, convertToDate_1.convertToDate)(val);
+    if (n_val === null)
+        throw new TypeError('addUTC requires a date object');
+    const year = n_val.getUTCFullYear();
+    const month = n_val.getUTCMonth();
+    const date = n_val.getUTCDate();
+    const hour = n_val.getUTCHours();
+    const min = n_val.getUTCMinutes();
+    const sec = n_val.getUTCSeconds();
+    const ms = n_val.getUTCMilliseconds();
     switch (key) {
         case 'years':
         case 'year':

package/date/convertToDate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert a value to a Date object if possible, handles Date objects and strings
+ *
+ * @param {Date|string} val - Value to convert
+ */
+declare function convertToDate(val: Date | string | number): Date | null;
+export { convertToDate, convertToDate as default };

package/date/convertToDate.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertToDate = convertToDate;
+exports.default = convertToDate;
+const is_1 = require("./is");
+function convertToDate(val) {
+    if ((0, is_1.isDate)(val)) {
+        return val;
+    }
+    else if (typeof val === 'string') {
+        const date = new Date(val);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}

package/date/diff.d.ts

@@ -2,9 +2,9 @@ export type DiffKey = 'week' | 'weeks' | 'day' | 'days' | 'hour' | 'hours' | 'mi
 /**
  * Compute the diff between two dates in the provided key
  *
- * @param {Date} val_a - Date to diff against
- * @param {Date} val_b - Date to diff with
+ * @param {Date|string} val_a - Date to diff against
+ * @param {Date|string} val_b - Date to diff with
  * @param {DiffKey} key - (default='millisecond') Key to diff in
  */
-declare function diff(val_a: Date, val_b: Date, key?: DiffKey): number;
+declare function diff(val_a: Date | string, val_b: Date | string, key?: DiffKey): number;
 export { diff, diff as default };

package/date/diff.js

@@ -2,17 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diff = diff;
 exports.default = diff;
-const is_1 = require("./is");
+const convertToDate_1 = require("./convertToDate");
 const SECOND_IN_MILLISECONDS = 1000;
 const MINUTE_IN_MILLISECONDS = SECOND_IN_MILLISECONDS * 60;
 const HOUR_IN_MILLISECONDS = MINUTE_IN_MILLISECONDS * 60;
 const DAY_IN_MILLISECONDS = HOUR_IN_MILLISECONDS * 24;
 const WEEK_IN_MILLISECONDS = DAY_IN_MILLISECONDS * 7;
 function diff(val_a, val_b, key = 'millisecond') {
-    if (!(0, is_1.isDate)(val_a) ||
-        !(0, is_1.isDate)(val_b))
+    const n_val_a = (0, convertToDate_1.convertToDate)(val_a);
+    const n_val_b = (0, convertToDate_1.convertToDate)(val_b);
+    if (n_val_a === null ||
+        n_val_b === null)
         throw new TypeError('Diff requires date objects for both values');
-    const diff_in_ms = val_a.valueOf() - val_b.valueOf();
+    const diff_in_ms = n_val_a.valueOf() - n_val_b.valueOf();
     switch (key) {
         case 'week':
         case 'weeks':

package/date/endOfUTC.d.ts

@@ -2,8 +2,8 @@ export type EndOfUTCKey = 'year' | 'quarter' | 'month' | 'week' | 'week_sun' | '
 /**
  * Sets the provided date to end of UTC of provided key
  *
- * @param {Date} val - Date to set to end of
+ * @param {Date|string} val - Date to set to end of
  * @param {EndOfUTCKey} key - (default='millisecond') Key to set
  */
-declare function endOfUTC(val: Date, key?: EndOfUTCKey): Date;
+declare function endOfUTC(val: Date | string, key?: EndOfUTCKey): Date;
 export { endOfUTC, endOfUTC as default };

package/date/endOfUTC.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.endOfUTC = endOfUTC;
 exports.default = endOfUTC;
-const is_1 = require("./is");
+const convertToDate_1 = require("./convertToDate");
 const WEEK_END = new Map([
     ['week', 0],
     ['week_sun', 6],
@@ -14,17 +14,19 @@ const WEEK_END = new Map([
     ['week_sat', 5],
 ]);
 function endOfUTC(val, key = 'millisecond') {
-    if (!(0, is_1.isDate)(val))
+    const n_val = (0, convertToDate_1.convertToDate)(val);
+    if (n_val === null)
         throw new TypeError('endOfUTC requires a date object');
+    const year = n_val.getUTCFullYear();
     switch (key) {
         case 'year':
-            return new Date(Date.UTC(val.getUTCFullYear(), 11, 31, 23, 59, 59, 999));
+            return new Date(Date.UTC(year, 11, 31, 23, 59, 59, 999));
         case 'quarter': {
-            const UTC_MONTH = val.getUTCMonth();
-            return new Date(Date.UTC(val.getUTCFullYear(), (UTC_MONTH - (UTC_MONTH % 3)) + 3, 0, 23, 59, 59, 999));
+            const UTC_MONTH = n_val.getUTCMonth();
+            return new Date(Date.UTC(year, (UTC_MONTH - (UTC_MONTH % 3)) + 3, 0, 23, 59, 59, 999));
         }
         case 'month':
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth() + 1, 0, 23, 59, 59, 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth() + 1, 0, 23, 59, 59, 999));
         case 'week':
         case 'week_sun':
         case 'week_mon':
@@ -33,19 +35,19 @@ function endOfUTC(val, key = 'millisecond') {
         case 'week_thu':
         case 'week_fri':
         case 'week_sat': {
-            const UTC_DAY = val.getUTCDay();
+            const UTC_DAY = n_val.getUTCDay();
             const UTC_EOD = WEEK_END.get(key);
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate() + (UTC_DAY <= UTC_EOD ? UTC_EOD - UTC_DAY : (7 - UTC_DAY) + UTC_EOD), 23, 59, 59, 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate() + (UTC_DAY <= UTC_EOD ? UTC_EOD - UTC_DAY : (7 - UTC_DAY) + UTC_EOD), 23, 59, 59, 999));
         }
         case 'day':
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), 23, 59, 59, 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate(), 23, 59, 59, 999));
         case 'hour':
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), val.getUTCHours(), 59, 59, 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate(), n_val.getUTCHours(), 59, 59, 999));
         case 'minute':
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), val.getUTCHours(), val.getUTCMinutes(), 59, 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate(), n_val.getUTCHours(), n_val.getUTCMinutes(), 59, 999));
         case 'second':
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), val.getUTCHours(), val.getUTCMinutes(), val.getUTCSeconds(), 999));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate(), n_val.getUTCHours(), n_val.getUTCMinutes(), n_val.getUTCSeconds(), 999));
         default:
-            return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), val.getUTCHours(), val.getUTCMinutes(), val.getUTCSeconds(), val.getUTCMilliseconds()));
+            return new Date(Date.UTC(year, n_val.getUTCMonth(), n_val.getUTCDate(), n_val.getUTCHours(), n_val.getUTCMinutes(), n_val.getUTCSeconds(), n_val.getUTCMilliseconds()));
     }
 }

package/date/format.d.ts

@@ -7,14 +7,14 @@ export type WEEK_START = keyof typeof WEEK_STARTS;
 /**
  * Formats the provided date according to a specific spec
  *
- * @param {Date} val - Date to format
+ * @param {Date|string} val - Date to format
  * @param {string} spec - Spec to format the date to
  * @param {string} locale - Locale to format the date in (only used in certain tokens such as dddd and MMMM)
  * @param {string} zone - (default=current timezone) Pass the timezone to convert into. If not passed no conversion will happen
  * @param {string} sow - (default='mon') Start of week (only useful when working with the 'W' and 'w' tokens for week numbers
  * @throws {TypeError} When provided invalid payload
  */
-declare function format(val: Date, spec: string, locale?: string, zone?: string, sow?: WEEK_START): string;
+declare function format(val: Date | string, spec: string, locale?: string, zone?: string, sow?: WEEK_START): string;
 declare namespace format {
     var getLocale: () => string;
     var setLocale: (locale: string) => void;

package/date/format.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.format = format;
 exports.default = format;
-const is_1 = require("./is");
+const convertToDate_1 = require("./convertToDate");
 const WEEK_STARTS = {
     mon: 'mon',
     sun: 'sun',
@@ -14,7 +14,7 @@ let DEFAULT_SOW = 'mon';
 try {
     DEFAULT_TZ = Intl.DateTimeFormat().resolvedOptions().timeZone;
 }
-catch (err) {
+catch {
 }
 finally {
     if (typeof DEFAULT_TZ !== 'string')
@@ -25,17 +25,17 @@ const intl_formatters = Object.create(null);
 const spec_cache = Object.create(null);
 const zone_offset_cache = Object.create(null);
 function WeekNr(d, sow) {
-    const date = new Date(d.valueOf());
     switch (sow) {
         case 'sun':
         case 'sat': {
             const OFFSET = sow === 'sat' ? 1 : 0;
-            const jan1 = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
-            const near = new Date(date.getTime() - (((date.getDay() + OFFSET) % 7) * 86400000));
+            const jan1 = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+            const near = new Date(d.getTime() - (((d.getDay() + OFFSET) % 7) * 86400000));
             const first = new Date(jan1.getTime() - (((jan1.getDay() + OFFSET) % 7) * 86400000));
             return 1 + Math.floor((near.valueOf() - first.valueOf()) / 604800000);
         }
         default: {
+            const date = new Date(d.valueOf());
             date.setDate(date.getDate() - ((d.getDay() + 6) % 7) + 3);
             const date_thu = date.valueOf();
             date.setMonth(0, 1);
@@ -59,9 +59,9 @@ function toZone(d, zone) {
         return new Date(time + zone_offset_cache[ckey]);
     let zone_time = null;
     try {
-        zone_time = new Date(d.toLocaleString(DEFAULT_LOCALE, { timeZone: zone })).getTime();
+        zone_time = new Date(d.toLocaleString(DEFAULT_LOCALE, { timeZone: zone })).getTime() + d.getMilliseconds();
     }
-    catch (err) {
+    catch {
         throw new Error(`format: Invalid zone passed - ${zone}`);
     }
     const offset = zone_time - time;
@@ -76,7 +76,7 @@ function runIntl(loc, token, props, val) {
             formatter = new Intl.DateTimeFormat(loc, props);
             intl_formatters[hash] = formatter;
         }
-        catch (err) {
+        catch {
             throw new Error(`format: Failed to run conversion for ${token} with locale ${loc}`);
         }
     }
@@ -149,7 +149,7 @@ function getSpecChain(spec) {
     let repl_len = 0;
     if (base.indexOf('[') >= 0) {
         base = base.replace(ESCAPE_RGX, match => {
-            const escape_token = '$R' + repl_len++ + '$';
+            const escape_token = '$' + repl_len++ + '$';
             repl.push([escape_token, match.slice(1, -1)]);
             return escape_token;
         });
@@ -176,7 +176,8 @@ function getSpecChain(spec) {
     return result;
 }
 function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ, sow = DEFAULT_SOW) {
-    if (!(0, is_1.isDate)(val))
+    const n_val = (0, convertToDate_1.convertToDate)(val);
+    if (n_val === null)
         throw new TypeError('format: val must be a Date');
     if (typeof spec !== 'string')
         throw new TypeError('format: spec must be a string');
@@ -186,8 +187,8 @@ function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ, sow = DEF
         throw new TypeError('format: zone must be a string');
     const n_spec = getSpecChain(spec);
     if (!n_spec)
-        return val.toISOString();
-    const d = toZone(val, zone);
+        return n_val.toISOString();
+    const d = toZone(n_val, zone);
     let base = n_spec.base;
     const { chain_len, chain, repl_len, repl } = n_spec;
     for (let i = 0; i < chain_len; i++) {