@valkyriestudios/utils 12.18.0 → 12.20.0

package/README.md

@@ -1,9 +1,9 @@
 # @valkyriestudios/utils
 
-[![CodeCov](https://codecov.io/gh/ValkyrieStudios/utils/branch/master/graph/badge.svg)](https://codecov.io/gh/ValkyrieStudios/utils)
-[![Test](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml)
-[![Lint](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml)
-[![CodeQL](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql/badge.svg?branch=master)](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql)
+[![CodeCov](https://codecov.io/gh/ValkyrieStudios/utils/branch/main/graph/badge.svg)](https://codecov.io/gh/ValkyrieStudios/utils)
+[![Test](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml)
+[![Lint](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml)
+[![CodeQL](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql)
 [![npm](https://img.shields.io/npm/v/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
 [![npm](https://img.shields.io/npm/dm/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
 
@@ -15,14 +15,14 @@ Zero-dependency collection of single-function utilities for common tasks
 ## Available Functions
 
 ### array
-- **isArray(val:any)**
+- **isArray(val:unknown)**
 Check if a variable is of type Array
 ```typescript
 isArray({a:1}); // FALSE
 isArray([]); // TRUE
 ```
 
-- **isNotEmptyArray(val:any)**
+- **isNotEmptyArray(val:unknown)**
 Check if a variable a non-empty array
 ```typescript
 isNotEmptyArray({a:1}); // FALSE
@@ -365,13 +365,44 @@ await memoized('123456'); /* Original function will be called and re-cached */
 ```
 
 ### date
-- **isDate(val:any)**
+- **isDate(val:unknown)**
 Check if a variable is of type Date
 ```typescript
 isDate(new Date('December 17, 1995 03:24:00')); // TRUE
 isDate('December 17, 1995 03:24:00'); // FALSE
 ```
 
+- **isFormat(val:unknown, spec:string)**
+Check if a variable is a string in a particular date format
+```typescript
+isFormat('2024-02-07', 'YYYY-MM-DD'); // TRUE
+isFormat('2024-2-07', 'YYYY-MM-DD'); // FALSE
+isFormat('12:30 AM', 'HH:mm A'); // TRUE
+isFormat('2024-Q4', 'YYYY-[Q]Q'); // TRUE
+isFormat('2024-Q5', 'YYYY-[Q]Q'); // FALSE (there is no such thing as a fifth quarter)
+isFormat('2024-02-29T12:30:00.000Z', 'ISO'); // TRUE
+isFormat('2023-02-29T12:30:00.000Z', 'ISO'); // FALSE (leap year)
+```
+
+Available tokens for usage in spec:
+| Token     | Description               | Example       |
+|:---------|:--------------------------|:---------------|
+| `YYYY` | Full Year | 2021 |
+| `Q` | Quarters of the year | 1 2 3 4 |
+| `MM` | Month as 2 char | 01 02 .. 11 12 |
+| `DD` | Day of month as 2 char | 01 02 .. 30 31 |
+| `HH` | Hours as 2-char | 00 01 .. 22 23 |
+| `mm` | Minutes as 2-char | 00 01 .. 58 59 |
+| `ss` | Seconds as 2-char | 00 01 .. 58 59 |
+| `SSS` | Milliseconds as 3-digit | 000 001 ... 998 999 |
+| `A` | Uppercase AM/PM | AM ... PM |
+| `a` | Lowercase AM/PM | am ... pm |
+| `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`
+Note: You can escape characters by surrounding them with `[...]` in your spec, eg: `YYYY-[Q]Q` would check for example `2024-Q1`
+
 - **diff(val_a:Date, val_b:Date, key:string)**
 Take two incoming dates and return the difference between them in a certain unit. Possible key options(week,day,hour,minute,second,millisecond).
 
@@ -385,6 +416,7 @@ diff(new Date("2022-10-05T13:12:11+02:00"), new Date("2022-10-05T17:43:09.344+06
 diff(new Date("2022-10-05T13:12:11+02:00"), new Date("2022-10-05T17:43:09.344+06:00"), 'millisecond'); // -1858344
 diff(new Date("2022-11-05T13:12:11+06:00"), new Date("2022-10-05T13:25:43.898+02:00")); // 2663187102
 ```
+
 - **format(val:Date, spec:string, locale?:string, zone?:string):string**
 Format a date according to a spec/locale and zone
 
@@ -392,6 +424,8 @@ Note: The locale is by default set to 'en-US'
 
 Note: The zone is by default detected as the zone of the client
 
+Note: You can escape characters by surrounding them with `[...]` in your spec, eg: `YYYY-[Q]Q` would for example become `2024-Q1`
+
 Available tokens for usage in spec:
 | Token     | Description               | Example       |
 |:---------|:--------------------------|:---------------|
@@ -670,7 +704,7 @@ Generate a unique identifier (guid) according to RFC4122
 guid(); // 245caf1a-86af-11e7-bb31-be2e44b06b34
 ```
 
-- **fnv1A(val:any)**
+- **fnv1A(val:unknown)**
 Generate a fnv1A hash from an object, using a 32-bit prime/offset
 ```typescript
 fnv1A('hello world'); // -2023343616
@@ -681,7 +715,7 @@ fnv1A(new Date('2012-02-02')); // 1655579136
 ```
 
 ### number
-- **isNumber(val:any)**
+- **isNumber(val:unknown)**
 Check if a variable is a number
 ```typescript
 isNumber('foo'); // FALSE
@@ -735,7 +769,7 @@ isNumberBetween(0, 0, 1); // TRUE
 isNumberBetween(-1, 0, 1); // FALSE
 ```
 
-- **isInteger(val:any)**
+- **isInteger(val:unknown)**
 Check if a variable is an integer
 ```typescript
 isInteger('foo'); // FALSE
@@ -791,7 +825,7 @@ isIntegerBetween(0, 0, 1); // TRUE
 isIntegerBetween(-1, 0, 1); // FALSE
 ```
 
-- **isNumericalNaN(val:any)**
+- **isNumericalNaN(val:unknown)**
 Check if a variable is a numerical nan ( a number that is a NaN, this distinguishment is made since both a string or a number can be NaN)
 ```typescript
 isNumericalNaN('foo'); // FALSE
@@ -829,14 +863,14 @@ randomIntBetween(25, 100); // Will generate a random between 25 and 100 (100 not
 ```
 
 ### object
-- **isObject(val:any)**
+- **isObject(val:unknown)**
 Check if a variable is of type Object
 ```typescript
 isObject({a: 1}); // TRUE
 isObject(1); // FALSE
 ```
 
-- **isNotEmptyObject(val:any)**
+- **isNotEmptyObject(val:unknown)**
 Check if a variable a non-empty object
 ```typescript
 isNotEmptyObject({a:1}); // TRUE
@@ -851,12 +885,17 @@ Copies the keys passed in the 'keys' array from the passed object to a new objec
 pick({a: 1, b: 2, c: 3}, ['a','b']); // {a: 1, b: 2}
 ```
 
-- **merge(target:Object={},obj:Object={})**
+- **merge(target:Object={},obj:Object|Object[]={}, opts?:{union?:boolean})**
 Merges two objects together, with the preference over the second object.
 ```typescript
-merge({a: 1, b: false}, {a: 900, c: 50}); // {a: 900, b: false, c: 50}
+merge({a: 1, b: false}, {a: 900, c: 50}, {union: true}); // {a: 900, b: false, c: 50}
+merge({a: 1, b: false}, {a: 900, c: 50}, {union: false}); // {a: 900, b: false}
+merge({a: 1, c: {bar: 'foo'}}, [{b: 2}, {c: {foo: 'bar'}}], {union: true}); // {a: 1, b: 2, c: {bar: 'foo', foo: 'bar'}}
 ```
 
+Take Note: The default behavior is to not have union, this means that ONLY the keys in the target object
+are going to be available in the response of this function.
+
 - **define(props:Object, obj:Object={})**
 Creates an object with the passed accessors set on it
 ```typescript
@@ -882,7 +921,7 @@ define({
 ```
 
 ### regexp
-- **isRegExp(val:any)**
+- **isRegExp(val:unknown)**
 Check if a variable is an instance of RegExp
 ```typescript
 isRegExp('foo'); // FALSE
@@ -898,7 +937,7 @@ sanitizeRegExp('contact@valkyriestudios.be'); // contact@valkyriestudios\\.be
 ```
 
 ### string
-- **isString(val:any)**
+- **isString(val:unknown)**
 Check if a variable is a string
 ```typescript
 isString('foo'); // TRUE
@@ -916,7 +955,7 @@ isStringBetween('    Joe', 1, 3); // TRUE
 isStringBetween('    Joe', 1, 3, false); // FALSE
 ```
 
-- **isNotEmptyString(val:any, trimmed:boolean=true)**
+- **isNotEmptyString(val:unknown, trimmed:boolean=true)**
 Check if a variable a non-empty string
 ```typescript
 isNotEmptyString({a:1}); // FALSE
@@ -926,7 +965,7 @@ isNotEmptyString(' ', false); // TRUE
 isNotEmptyString('Hi'); // TRUE
 ```
 
-- **shorten(val:any, length:integer, postfix:string=..., truncate_words=true)**
+- **shorten(val:string, length:integer, postfix:string=..., truncate_words=true)**
 Shorten a string and add a postfix if string went over length
 ```typescript
 shorten('To the moon and beyond', 11, '..'); // 'To the moon..'

package/array/dedupe.d.ts

@@ -1,4 +1,7 @@
 type DedupeOptions<T> = {
+    /**
+     * Pass a custom filter function which will be run in O(n) while deduping is going on
+     */
     filter_fn?: (el: T) => boolean;
 };
 /**

package/date/format.js

@@ -15,36 +15,35 @@ finally {
         DEFAULT_TZ = 'UTC';
 }
 const escape_rgx = /\[[\s\S]+?]/g;
-const intl_formatters = new Map();
-const spec_cache = new Map();
-const zone_offset_cache = new Map();
+const intl_formatters = Object.create(null);
+const spec_cache = Object.create(null);
+const zone_offset_cache = Object.create(null);
 function DOY(d) {
     return ((d - new Date(d.getFullYear(), 0, 0)) / 86400000) | 0;
 }
 function toZone(date, zone) {
     const ckey = `${zone}:${date.getUTCFullYear()}${DOY(date)}`;
-    if (zone_offset_cache.has(ckey))
-        return new Date(date.getTime() + zone_offset_cache.get(ckey));
+    if (zone_offset_cache[ckey] !== undefined)
+        return new Date(date.getTime() + zone_offset_cache[ckey]);
     const client_time = date.getTime();
-    let zone_time = false;
+    let zone_time = null;
     try {
         zone_time = new Date(date.toLocaleString(DEFAULT_LOCALE, { timeZone: zone })).getTime();
     }
     catch (err) {
-    }
-    if (!Number.isInteger(zone_time))
         throw new Error(`format: Invalid zone passed - ${zone}`);
+    }
     const offset = zone_time - client_time;
-    zone_offset_cache.set(ckey, offset);
+    zone_offset_cache[ckey] = offset;
     return new Date(client_time + offset);
 }
 function runIntl(loc, token, props, val) {
-    const hash = `${loc}:${token}`;
-    let formatter = intl_formatters.get(hash);
+    const hash = loc + ':' + token;
+    let formatter = intl_formatters[hash];
     if (!formatter) {
         try {
             formatter = new Intl.DateTimeFormat(loc, props);
-            intl_formatters.set(hash, formatter);
+            intl_formatters[hash] = formatter;
         }
         catch (err) {
             throw new Error(`format: Failed to run conversion for ${token} with locale ${loc}`);
@@ -57,21 +56,46 @@ const Tokens = [
     ['Q', d => ((d.getMonth() + 3) / 3) | 0],
     ['MMMM', (d, loc) => runIntl(loc, 'MMMM', { month: 'long' }, d)],
     ['MMM', (d, loc) => runIntl(loc, 'MMM', { month: 'short' }, d)],
-    ['MM', d => `${d.getMonth() + 1}`.padStart(2, '0')],
+    ['MM', d => {
+            const val = d.getMonth() + 1;
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['M', d => d.getMonth() + 1],
-    ['DD', d => `${d.getDate()}`.padStart(2, '0')],
+    ['DD', d => {
+            const val = d.getDate();
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['D', d => d.getDate()],
     ['dddd', (d, loc) => runIntl(loc, 'dddd', { weekday: 'long' }, d)],
     ['ddd', (d, loc) => runIntl(loc, 'ddd', { weekday: 'short' }, d)],
-    ['HH', d => `${d.getHours()}`.padStart(2, '0')],
+    ['HH', d => {
+            const val = d.getHours();
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['H', d => d.getHours()],
-    ['hh', d => `${((d.getHours() + 11) % 12) + 1}`.padStart(2, '0')],
+    ['hh', d => {
+            const val = ((d.getHours() + 11) % 12) + 1;
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['h', d => ((d.getHours() + 11) % 12) + 1],
-    ['mm', d => `${d.getMinutes()}`.padStart(2, '0')],
+    ['mm', d => {
+            const val = d.getMinutes();
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['m', d => d.getMinutes()],
-    ['ss', d => `${d.getSeconds()}`.padStart(2, '0')],
+    ['ss', d => {
+            const val = d.getSeconds();
+            return (val < 10 ? '0' : '') + val;
+        }],
     ['s', d => d.getSeconds()],
-    ['SSS', d => `${d.getMilliseconds()}`.padStart(3, '0')],
+    ['SSS', d => {
+            const val = d.getMilliseconds();
+            return val < 10
+                ? '00' + val
+                : val < 100
+                    ? '0' + val
+                    : val;
+        }],
     ['A', d => d.getHours() < 12 ? 'AM' : 'PM'],
     ['a', d => d.getHours() < 12 ? 'am' : 'pm'],
     ['l', (d, loc) => runIntl(loc, 'l', { dateStyle: 'short' }, d)],
@@ -79,42 +103,46 @@ const Tokens = [
     ['t', (d, loc) => runIntl(loc, 't', { timeStyle: 'short' }, d)],
     ['T', (d, loc) => runIntl(loc, 'T', { timeStyle: 'medium' }, d)],
 ]
-    .sort((a, b) => a[0].length > b[0].length ? -1 : 1)
-    .map((el) => [el[0], new RegExp(el[0], 'g'), el[1]]);
+    .sort((a, b) => a[0].length > b[0].length ? -1 : 1);
 function getSpecChain(spec) {
-    let spec_chain = spec_cache.get(spec);
-    if (spec_chain)
-        return spec_chain;
-    spec_chain = [];
-    let cursor;
-    let spec_cursor = spec;
+    if (spec_cache[spec] !== undefined)
+        return spec_cache[spec];
+    const spec_chain = [];
+    const matched_positions = new Set();
     for (let i = 0; i < Tokens.length; i++) {
-        cursor = Tokens[i];
-        if (spec_cursor.indexOf(cursor[0]) < 0)
-            continue;
-        spec_chain.push(cursor);
-        spec_cursor = spec_cursor.replace(cursor[1], '');
+        const [token] = Tokens[i];
+        let pos = spec.indexOf(token);
+        const token_len = token.length;
+        while (pos !== -1) {
+            if (!matched_positions.has(pos)) {
+                spec_chain.push(Tokens[i]);
+                for (let j = 0; j < token_len; j++) {
+                    matched_positions.add(pos + j);
+                }
+            }
+            pos = spec.indexOf(token, pos + 1);
+        }
     }
-    if (spec_chain.length === 0)
-        return false;
-    spec_cache.set(spec, spec_chain);
-    return spec_chain;
+    const result = spec_chain.length ? spec_chain : null;
+    spec_cache[spec] = result;
+    return result;
 }
 function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ) {
     if (!(0, is_1.isDate)(val))
         throw new TypeError('format: val must be a Date');
-    if (typeof spec !== 'string' || !spec.trim().length)
-        throw new TypeError('format: spec must be a non-empty string');
-    if (typeof locale !== 'string' || !locale.trim().length)
-        throw new TypeError('format: locale must be a non-empty string');
-    if (typeof zone !== 'string' || !zone.trim().length)
-        throw new TypeError('format: zone must be a non-empty string');
+    if (typeof spec !== 'string')
+        throw new TypeError('format: spec must be a string');
+    if (typeof locale !== 'string')
+        throw new TypeError('format: locale must be a string');
+    if (typeof zone !== 'string')
+        throw new TypeError('format: zone must be a string');
     let formatted_string = spec;
     const escaped_acc = [];
+    let escaped_count = 0;
     if (formatted_string.indexOf('[') >= 0) {
         formatted_string = formatted_string.replace(escape_rgx, match => {
-            const escape_token = `$R${escaped_acc.length}$`;
-            escaped_acc.push([escape_token, match.replace('[', '').replace(']', '')]);
+            const escape_token = '$R' + escaped_count++ + '$';
+            escaped_acc.push([escape_token, match.slice(1, -1)]);
             return escape_token;
         });
     }
@@ -123,11 +151,17 @@ function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ) {
         return val.toISOString();
     const d = toZone(val, zone);
     for (let i = 0; i < spec_chain.length; i++) {
-        const el = spec_chain[i];
-        formatted_string = formatted_string.replace(el[1], el[2](d, locale));
+        const [token, formatter] = spec_chain[i];
+        let pos = formatted_string.indexOf(token);
+        while (pos !== -1) {
+            formatted_string = formatted_string.slice(0, pos) +
+                formatter(d, locale) +
+                formatted_string.slice(pos + token.length);
+            pos = formatted_string.indexOf(token, pos + token.length);
+        }
     }
-    if (escaped_acc.length) {
-        for (let i = 0; i < escaped_acc.length; i++) {
+    if (escaped_count) {
+        for (let i = 0; i < escaped_count; i++) {
             const escape_token = escaped_acc[i];
             formatted_string = formatted_string.replace(escape_token[0], escape_token[1]);
         }

package/date/index.d.ts

@@ -2,6 +2,7 @@ import { addUTC } from './addUTC';
 import { diff } from './diff';
 import { endOfUTC } from './endOfUTC';
 import { format } from './format';
+import { isDateFormat } from './isFormat';
 import { isDate } from './is';
 import { nowUnix } from './nowUnix';
 import { nowUnixMs } from './nowUnixMs';
@@ -9,4 +10,4 @@ import { setTimeUTC } from './setTimeUTC';
 import { startOfUTC } from './startOfUTC';
 import { toUnix } from './toUnix';
 import { toUTC } from './toUTC';
-export { addUTC, diff, endOfUTC, format, isDate, isDate as is, nowUnix, nowUnixMs, setTimeUTC, startOfUTC, toUnix, toUTC };
+export { addUTC, diff, endOfUTC, format, isDateFormat as isFormat, isDateFormat, isDate, isDate as is, nowUnix, nowUnixMs, setTimeUTC, startOfUTC, toUnix, toUTC };

package/date/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toUTC = exports.toUnix = exports.startOfUTC = exports.setTimeUTC = exports.nowUnixMs = exports.nowUnix = exports.is = exports.isDate = exports.format = exports.endOfUTC = exports.diff = exports.addUTC = void 0;
+exports.toUTC = exports.toUnix = exports.startOfUTC = exports.setTimeUTC = exports.nowUnixMs = exports.nowUnix = exports.is = exports.isDate = exports.isDateFormat = exports.isFormat = exports.format = exports.endOfUTC = exports.diff = exports.addUTC = void 0;
 const addUTC_1 = require("./addUTC");
 Object.defineProperty(exports, "addUTC", { enumerable: true, get: function () { return addUTC_1.addUTC; } });
 const diff_1 = require("./diff");
@@ -9,6 +9,9 @@ const endOfUTC_1 = require("./endOfUTC");
 Object.defineProperty(exports, "endOfUTC", { enumerable: true, get: function () { return endOfUTC_1.endOfUTC; } });
 const format_1 = require("./format");
 Object.defineProperty(exports, "format", { enumerable: true, get: function () { return format_1.format; } });
+const isFormat_1 = require("./isFormat");
+Object.defineProperty(exports, "isFormat", { enumerable: true, get: function () { return isFormat_1.isDateFormat; } });
+Object.defineProperty(exports, "isDateFormat", { enumerable: true, get: function () { return isFormat_1.isDateFormat; } });
 const is_1 = require("./is");
 Object.defineProperty(exports, "isDate", { enumerable: true, get: function () { return is_1.isDate; } });
 Object.defineProperty(exports, "is", { enumerable: true, get: function () { return is_1.isDate; } });

package/date/isFormat.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks if a given string is in a particular format
+ * Eg:
+ *  isDateFormat('2024-02-09', 'YYYY-MM-DD'); // true
+ *  isDateFormat('2024-02-09T14:30', 'YYYY-MM-DD'); // false
+ *
+ * @param {unknown} input - String to format (eg: '2024-08-01')
+ * @param {string} spec - Spec to validate (Eg: 'YYYY-MM-DD')
+ * @returns {boolean} Whether or not the input is valid according to the spec
+ */
+declare function isDateFormat(input: unknown, spec: string): input is string;
+export { isDateFormat, isDateFormat as default };

package/date/isFormat.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDateFormat = isDateFormat;
+exports.default = isDateFormat;
+const SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
+const TOKENS = [
+    ['YYYY', /\d{4}/.source, (raw, context) => {
+            context.year = parseInt(raw, 10);
+            return context.year > 0;
+        }],
+    ['MM', /(?:0[1-9]|1[0-2])/.source, (raw, context) => {
+            context.month = parseInt(raw, 10);
+            return context.month >= 1 && context.month <= 12;
+        }],
+    ['DD', /(?:0[1-9]|[12][0-9]|3[01])/.source, (raw, context) => {
+            context.day = parseInt(raw, 10);
+            return context.day >= 1 && context.day <= 31;
+        }],
+    ['HH', /(?:[01][0-9]|2[0-3])/.source, (raw, context) => {
+            context.hour = parseInt(raw, 10);
+            return context.hour >= 0 && context.hour <= 23;
+        }],
+    ['mm', /[0-5][0-9]/.source, () => true],
+    ['ss', /[0-5][0-9]/.source, () => true],
+    ['SSS', /\d{3}/.source, () => true],
+    ['Q', /[1-4]/.source, () => true],
+    ['A', /(?:AM|PM)/.source, (raw, context) => {
+            context.is12 = 1;
+            return raw === 'AM' || raw === 'PM';
+        }],
+    ['a', /(?:am|pm)/.source, (raw, context) => {
+            context.is12 = 1;
+            return raw === 'am' || raw === 'pm';
+        }],
+    ['Z', /Z|[+-](?:0[0-9]|1[0-4]):[0-5][0-9]/.source, raw => {
+            if (raw === 'Z')
+                return true;
+            let hour = parseInt(raw[1] + raw[2], 10);
+            if (raw[0] === '-')
+                hour = -hour;
+            const minutes = parseInt(raw[4] + raw[5], 10);
+            if (hour === 14 || hour === -12)
+                return minutes === 0;
+            return hour >= -11 && hour < 14 && [0, 15, 30, 45].indexOf(minutes) >= 0;
+        }],
+];
+const SPEC_ALIASES = {
+    ISO: 'YYYY-MM-DDTHH:mm:ss.SSSZ',
+};
+const spec_pat_cache = {};
+function compileSpec(spec) {
+    if (spec in spec_pat_cache)
+        return spec_pat_cache[spec];
+    const tokens = [];
+    let pat = '';
+    let cursor = 0;
+    while (cursor < spec.length) {
+        if (spec[cursor] === '[') {
+            const end_idx = spec.indexOf(']', cursor);
+            if (end_idx === -1)
+                throw new Error('isDateFormat: Unmatched [ in format string');
+            pat += spec.slice(cursor + 1, end_idx).replace(SPECIAL_CHARS, '\\$&');
+            cursor = end_idx + 1;
+        }
+        else {
+            const token_idx = TOKENS.findIndex(([token_key]) => spec.startsWith(token_key, cursor));
+            if (token_idx >= 0) {
+                const [token_key, token_rgx] = TOKENS[token_idx];
+                pat += '(' + token_rgx + ')';
+                tokens.push(token_idx);
+                cursor += token_key.length;
+            }
+            else {
+                pat += spec[cursor].replace(SPECIAL_CHARS, '\\$&');
+                cursor++;
+            }
+        }
+    }
+    spec_pat_cache[spec] = { rgx: RegExp('^' + pat + '$'), tokens };
+    return spec_pat_cache[spec];
+}
+function isDateFormat(input, spec) {
+    if (typeof input !== 'string' || input.trim().length === 0) {
+        throw new TypeError('isDateFormat: input must be a non-empty string');
+    }
+    if (typeof spec !== 'string') {
+        throw new TypeError('isDateFormat: spec must be a string');
+    }
+    const { tokens, rgx } = compileSpec(SPEC_ALIASES[spec] || spec);
+    if (!tokens.length)
+        return false;
+    const patMatch = rgx.exec(input);
+    if (!patMatch)
+        return false;
+    const matches = patMatch.slice(1);
+    const context = {};
+    for (let i = 0; i < matches.length; i++) {
+        if (!TOKENS[tokens[i]][2](matches[i], context))
+            return false;
+    }
+    const { is12, day, month, year } = context;
+    if (day && month) {
+        const date = new Date(year || 2024, month - 1, day);
+        if (date.getDate() !== day || date.getMonth() !== month - 1)
+            return false;
+    }
+    if (is12 && 'hour' in context && context.hour > 11)
+        return false;
+    return true;
+}

package/deep/freeze.js

@@ -4,8 +4,8 @@ exports.deepFreeze = deepFreeze;
 exports.default = deepFreeze;
 function deep(obj) {
     if (Array.isArray(obj)) {
-        for (const el of obj)
-            deep(el);
+        for (let i = 0; i < obj.length; i++)
+            deep(obj[i]);
     }
     else {
         for (const key in obj) {

package/deep/get.d.ts

@@ -2,16 +2,16 @@
  * Get a property's value deep inside the structure of an array/object
  *
  * Example:
- *  const myObj = {
- *      a: 2,
- *      b: [
- *          {price : 2},
- *          {price : 4},
- *      ],
- *  };
- *  deepGet(myObj, 'b[0].price');
+ * const myObj = {
+ *  a: 2,
+ *  b: [
+ *   {price : 2},
+ *   {price : 4},
+ *  ],
+ * };
+ * deepGet(myObj, 'b[0].price');
  * Output:
- *  2
+ * 2
  *
  * @param val - Object/Array to get the value from
  * @param path - Path string to deeply get the value at
@@ -20,9 +20,10 @@
  * @returns Value stored at property or undefined
  * @throws {TypeError}
  */
-declare function deepGet(obj: {
+type ObjectType = {
     [key: string]: any;
-} | {
-    [key: string]: any;
-}[] | any[], path: string, get_parent?: boolean): any | undefined;
+};
+type ArrayType = any[];
+type DeepGetResult<T extends ObjectType | ArrayType, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? T[Key] extends ObjectType | ArrayType ? DeepGetResult<T[Key], Rest> : undefined : T extends ArrayType ? number extends keyof T ? DeepGetResult<T[number], Rest> : undefined : undefined : P extends `${infer Key}[${infer Index}]` ? Key extends keyof T ? T[Key] extends ArrayType ? Index extends `${number}` ? DeepGetResult<T[Key][number], ''> : undefined : undefined : T extends ArrayType ? number extends keyof T ? DeepGetResult<T[number], `[${Index}]`> : undefined : undefined : P extends keyof T ? T[P] : T extends ArrayType ? number extends keyof T ? T[number] : undefined : undefined;
+declare function deepGet<T extends ObjectType | ArrayType, P extends string>(obj: T, path: P, get_parent?: boolean): DeepGetResult<T, P> | undefined;
 export { deepGet, deepGet as default };

package/deep/get.js

@@ -9,34 +9,56 @@ function deepGet(obj, path, get_parent = false) {
     if (typeof path !== 'string')
         throw new TypeError('No path was given');
     const path_s = path.trim();
-    if (!path_s.length)
+    const path_len = path_s.length;
+    if (!path_len)
         throw new TypeError('No path was given');
-    const parts = path_s
-        .replace(/\[/g, '.')
-        .replace(/(\.){2,}/g, '.')
-        .replace(/(^\.|\.$|\])/g, '')
-        .split('.');
-    if (!parts.length || (parts.length === 1 && get_parent))
+    const parts = [];
+    let cursor_part = '';
+    let in_bracket = false;
+    for (let i = 0; i < path_len; i++) {
+        const char = path_s[i];
+        if (char === '[' || char === ']') {
+            in_bracket = !in_bracket;
+            if (cursor_part) {
+                parts.push(cursor_part);
+                cursor_part = '';
+            }
+        }
+        else if (char === '.' && !in_bracket) {
+            if (cursor_part) {
+                parts.push(cursor_part);
+                cursor_part = '';
+            }
+        }
+        else {
+            cursor_part += char;
+        }
+    }
+    if (cursor_part)
+        parts.push(cursor_part);
+    let len = parts.length;
+    if (!len || (len === 1 && get_parent))
         return obj;
-    if (get_parent)
+    if (get_parent) {
         parts.pop();
+        len -= 1;
+    }
     let cursor = obj;
-    while (parts.length) {
+    for (let i = 0; i < len; i++) {
         if (Array.isArray(cursor)) {
-            const ix = parseInt(parts.shift());
-            if (!Number.isInteger(ix) || ix < 0 || ix > (cursor.length - 1))
+            const ix = parseInt(parts[i], 10);
+            if (ix < 0 || ix > cursor.length - 1)
                 return undefined;
             cursor = cursor[ix];
         }
         else if (Object.prototype.toString.call(cursor) === '[object Object]') {
-            const key = parts.shift();
-            if (cursor[key] === undefined)
+            cursor = cursor[parts[i]];
+            if (cursor === undefined)
                 return undefined;
-            cursor = cursor[key];
         }
-        if ((!Array.isArray(cursor) && Object.prototype.toString.call(cursor) !== '[object Object]') &&
-            parts.length)
+        else {
             return undefined;
+        }
     }
     return cursor;
 }

package/deep/seal.js

@@ -4,8 +4,8 @@ exports.deepSeal = deepSeal;
 exports.default = deepSeal;
 function deep(obj) {
     if (Array.isArray(obj)) {
-        for (const el of obj)
-            deep(el);
+        for (let i = 0; i < obj.length; i++)
+            deep(obj[i]);
     }
     else {
         for (const key in obj) {

package/equal.js

@@ -4,9 +4,10 @@ exports.equal = equal;
 exports.default = equal;
 const isNumericalNaN_1 = require("./number/isNumericalNaN");
 function isArrayEqual(a, b) {
-    if (a.length !== b.length)
+    const a_len = a.length;
+    if (a_len !== b.length)
         return false;
-    for (let i = a.length - 1; i >= 0; i--) {
+    for (let i = a_len - 1; i >= 0; i--) {
         if (equal(a[i], b[i]))
             continue;
         return false;
@@ -15,9 +16,10 @@ function isArrayEqual(a, b) {
 }
 function isObjectEqual(a, b) {
     const keys_a = Object.keys(a);
-    if (keys_a.length !== Object.keys(b).length)
+    const keys_a_len = keys_a.length;
+    if (keys_a_len !== Object.keys(b).length)
         return false;
-    for (let i = keys_a.length - 1; i >= 0; i--) {
+    for (let i = keys_a_len - 1; i >= 0; i--) {
         if (equal(a[keys_a[i]], b[keys_a[i]]))
             continue;
         return false;

package/hash/fnv1A.js

@@ -28,11 +28,11 @@ function fnv1A(data, offset = FNV_32) {
             if (data === null) {
                 sanitized = REPL_NULL;
             }
-            else if (Array.isArray(data) || data.toString() === '[object Object]') {
+            else if (Array.isArray(data) || Object.prototype.toString.call(data) === '[object Object]') {
                 sanitized = JSON.stringify(data);
             }
             else if (data instanceof RegExp) {
-                sanitized = data.toString();
+                sanitized = String(data);
             }
             else if (data instanceof Date) {
                 sanitized = String(data.getTime());

package/index.d.ts

@@ -147,6 +147,10 @@ declare module "date/format" {
     function format(val: Date, spec: string, locale?: string, zone?: string): string;
     export { format, format as default };
 }
+declare module "date/isFormat" {
+    function isDateFormat(input: unknown, spec: string): input is string;
+    export { isDateFormat, isDateFormat as default };
+}
 declare module "date/nowUnix" {
     function nowUnix(): number;
     export { nowUnix, nowUnix as default };
@@ -186,6 +190,7 @@ declare module "date/index" {
     import { diff } from "date/diff";
     import { endOfUTC } from "date/endOfUTC";
     import { format } from "date/format";
+    import { isDateFormat } from "date/isFormat";
     import { isDate } from "date/is";
     import { nowUnix } from "date/nowUnix";
     import { nowUnixMs } from "date/nowUnixMs";
@@ -193,7 +198,7 @@ declare module "date/index" {
     import { startOfUTC } from "date/startOfUTC";
     import { toUnix } from "date/toUnix";
     import { toUTC } from "date/toUTC";
-    export { addUTC, diff, endOfUTC, format, isDate, isDate as is, nowUnix, nowUnixMs, setTimeUTC, startOfUTC, toUnix, toUTC };
+    export { addUTC, diff, endOfUTC, format, isDateFormat as isFormat, isDateFormat, isDate, isDate as is, nowUnix, nowUnixMs, setTimeUTC, startOfUTC, toUnix, toUTC };
 }
 declare module "formdata/is" {
     function isFormData(val: unknown): val is FormData;
@@ -272,35 +277,29 @@ declare module "object/define" {
     export { define, define as default };
 }
 declare module "object/merge" {
-    function merge(target: {
-        [key: string]: any;
-    }, source?: {
-        [key: string]: any;
-    }): {
-        [key: string]: any;
+    type MergeOptions = {
+        union?: boolean;
     };
+    function merge(target: Record<string, any>, source?: Record<string, any> | Record<string, any>[], opts?: MergeOptions): Record<string, any>;
     export { merge, merge as default };
 }
 declare module "deep/get" {
-    function deepGet(obj: {
-        [key: string]: any;
-    } | {
+    type ObjectType = {
         [key: string]: any;
-    }[] | any[], path: string, get_parent?: boolean): any | undefined;
+    };
+    type ArrayType = any[];
+    type DeepGetResult<T extends ObjectType | ArrayType, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? T[Key] extends ObjectType | ArrayType ? DeepGetResult<T[Key], Rest> : undefined : T extends ArrayType ? number extends keyof T ? DeepGetResult<T[number], Rest> : undefined : undefined : P extends `${infer Key}[${infer Index}]` ? Key extends keyof T ? T[Key] extends ArrayType ? Index extends `${number}` ? DeepGetResult<T[Key][number], ''> : undefined : undefined : T extends ArrayType ? number extends keyof T ? DeepGetResult<T[number], `[${Index}]`> : undefined : undefined : P extends keyof T ? T[P] : T extends ArrayType ? number extends keyof T ? T[number] : undefined : undefined;
+    function deepGet<T extends ObjectType | ArrayType, P extends string>(obj: T, path: P, get_parent?: boolean): DeepGetResult<T, P> | undefined;
     export { deepGet, deepGet as default };
 }
-declare module "deep/set" {
-    function deepSet(obj: {
-        [key: string]: any;
-    } | {
-        [key: string]: any;
-    }[] | any[], path: string, value: any, define?: boolean): boolean;
-    export { deepSet, deepSet as default };
-}
 declare module "object/pick" {
-    function pick(obj: {
+    type ObjectType = {
         [key: string]: any;
-    }, keys: string[]): {
+    };
+    type DottedKeys<T> = (T extends ObjectType ? {
+        [K in keyof T & string]: T[K] extends ObjectType ? K | `${K}.${DottedKeys<T[K]>}` : K;
+    }[keyof T & string] : string) & string;
+    function pick<T extends Record<string, any>, K extends DottedKeys<T>>(obj: T, keys: K[]): {
         [key: string]: any;
     };
     export { pick, pick as default };
@@ -525,6 +524,14 @@ declare module "deep/seal" {
     function deepSeal<T extends deepInput>(obj: T): Sealed<T>;
     export { deepSeal, deepSeal as default };
 }
+declare module "deep/set" {
+    function deepSet(obj: {
+        [key: string]: any;
+    } | {
+        [key: string]: any;
+    }[] | any[], path: string, value: any, define?: boolean): boolean;
+    export { deepSet, deepSet as default };
+}
 declare module "deep/index" {
     import { deepFreeze } from "deep/freeze";
     import { deepGet } from "deep/get";

package/object/merge.d.ts

@@ -1,3 +1,10 @@
+type MergeOptions = {
+    /**
+     * Defaults to false, when passed as true it ensures all keys from both objects
+     * are available in the merged object
+     */
+    union?: boolean;
+};
 /**
  * Deep merge two objects together while ensuring nested objects also get merged,
  * take note: this does not merge onto passed objects by reference but instead
@@ -8,11 +15,5 @@
  *
  * @returns Combined target and source objects
  */
-declare function merge(target: {
-    [key: string]: any;
-}, source?: {
-    [key: string]: any;
-}): {
-    [key: string]: any;
-};
+declare function merge(target: Record<string, any>, source?: Record<string, any> | Record<string, any>[], opts?: MergeOptions): Record<string, any>;
 export { merge, merge as default };

package/object/merge.js

@@ -3,19 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.merge = merge;
 exports.default = merge;
 const PROTO_OBJ = '[object Object]';
-function merge(target, source = {}) {
-    if (Object.prototype.toString.call(target) !== PROTO_OBJ ||
-        Object.prototype.toString.call(source) !== PROTO_OBJ)
-        throw new TypeError('Please pass a target and object to merge');
-    const acc = {};
-    for (const key in target) {
-        if (Object.prototype.toString.call(target[key]) === PROTO_OBJ &&
-            Object.prototype.toString.call(source[key]) === PROTO_OBJ) {
-            acc[key] = merge(target[key], source[key]);
+function innerMerge(target, source, UNION) {
+    const origin = UNION ? source : target;
+    for (const key in origin) {
+        const t_key = target[key];
+        const s_key = source[key];
+        if (Object.prototype.toString.call(t_key) === PROTO_OBJ &&
+            Object.prototype.toString.call(s_key) === PROTO_OBJ) {
+            target[key] = innerMerge({ ...t_key }, s_key, UNION);
         }
         else {
-            acc[key] = source[key] !== undefined ? source[key] : target[key];
+            target[key] = s_key !== undefined ? s_key : t_key;
         }
     }
+    return target;
+}
+function merge(target, source = {}, opts = {}) {
+    if (Object.prototype.toString.call(target) !== PROTO_OBJ)
+        throw new Error('object/merge: Please ensure valid target/source is passed');
+    const union = opts?.union === true;
+    const sources = Array.isArray(source) ? source : [source];
+    let acc = { ...target };
+    for (let i = 0; i < sources.length; i++) {
+        const el = sources[i];
+        if (Object.prototype.toString.call(el) !== PROTO_OBJ) {
+            throw new Error('object/merge: Please ensure valid target/source is passed');
+        }
+        acc = innerMerge(acc, el, union);
+    }
     return acc;
 }

package/object/pick.d.ts

@@ -1,3 +1,9 @@
+type ObjectType = {
+    [key: string]: any;
+};
+type DottedKeys<T> = (T extends ObjectType ? {
+    [K in keyof T & string]: T[K] extends ObjectType ? K | `${K}.${DottedKeys<T[K]>}` : K;
+}[keyof T & string] : string) & string;
 /**
  * Returns a new object with the keys picked from the passed object
  *
@@ -6,9 +12,7 @@
  *
  * @returns Object containing the picked keys from source object
  */
-declare function pick(obj: {
-    [key: string]: any;
-}, keys: string[]): {
+declare function pick<T extends Record<string, any>, K extends DottedKeys<T>>(obj: T, keys: K[]): {
     [key: string]: any;
 };
 export { pick, pick as default };

package/object/pick.js

@@ -3,8 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pick = pick;
 exports.default = pick;
 const get_1 = require("../deep/get");
-const set_1 = require("../deep/set");
-const RGX_DEEP = /(\.|\[)/;
 function pick(obj, keys) {
     if (Object.prototype.toString.call(obj) !== '[object Object]' ||
         !Array.isArray(keys) ||
@@ -20,11 +18,20 @@ function pick(obj, keys) {
         sanitized = key.trim();
         if (!sanitized.length)
             continue;
-        if (RGX_DEEP.test(sanitized)) {
+        if (sanitized.indexOf('.') >= 0) {
             val = (0, get_1.deepGet)(obj, sanitized);
             if (val === undefined)
                 continue;
-            (0, set_1.deepSet)(map, sanitized, val);
+            const parts = key.split('.');
+            const parts_len = parts.length;
+            let cursor = map;
+            for (let y = 0; y < parts_len - 1; y++) {
+                const part = parts[y].trim();
+                if (!cursor[part])
+                    cursor[part] = {};
+                cursor = cursor[part];
+            }
+            cursor[parts[parts_len - 1].trim()] = val;
         }
         else if (obj[sanitized] !== undefined) {
             map[sanitized] = obj[sanitized];

package/package.json

@@ -1 +1 @@
-{ "name": "@valkyriestudios/utils", "version": "12.18.0", "description": "A collection of single-function utilities for common tasks", "author": { "name": "Peter Vermeulen", "url": "https://www.linkedin.com/in/petervermeulen1/" }, "keywords": [ "utility", "library", "javascript", "js", "node", "bun" ], "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/ValkyrieStudios/utils.git" }, "bugs": { "url": "https://github.com/ValkyrieStudios/utils/issues" }, "homepage": "https://github.com/ValkyrieStudios/utils#readme", "types": "index.d.ts" }
+{ "name": "@valkyriestudios/utils", "version": "12.20.0", "description": "A collection of single-function utilities for common tasks", "author": { "name": "Peter Vermeulen", "url": "https://www.linkedin.com/in/petervermeulen1/" }, "keywords": [ "utility", "library", "javascript", "js", "node", "bun" ], "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/ValkyrieStudios/utils.git" }, "bugs": { "url": "https://github.com/ValkyrieStudios/utils/issues" }, "homepage": "https://github.com/ValkyrieStudios/utils#readme", "types": "index.d.ts" }

package/string/humanizeBytes.js

@@ -3,21 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.humanizeBytes = humanizeBytes;
 exports.default = humanizeBytes;
 const humanizeNumber_1 = require("./humanizeNumber");
-const isIntegerAboveOrEqual_1 = require("../number/isIntegerAboveOrEqual");
+const DEFAULT_UNITS = [' bytes', ' KB', ' MB', ' GB', ' TB', ' PB', ' EB', ' ZB', ' YB'];
 function humanizeBytes(val, options = {}) {
     return (0, humanizeNumber_1.humanizeNumber)(val, {
-        delim: typeof options?.delim === 'string'
-            ? options.delim
-            : ',',
-        separator: typeof options?.separator === 'string' && options.separator.trim().length
-            ? options.separator
-            : '.',
-        precision: (0, isIntegerAboveOrEqual_1.isIntegerAboveOrEqual)(options?.precision, 0)
-            ? options.precision
-            : 2,
+        delim: 'delim' in options ? options.delim : ',',
+        separator: 'separator' in options ? options.separator : '.',
+        precision: 'precision' in options ? options.precision : 2,
         units: Array.isArray(options?.units) && options.units.length
             ? options.units
-            : [' bytes', ' KB', ' MB', ' GB', ' TB', ' PB', ' EB', ' ZB', ' YB'],
+            : DEFAULT_UNITS,
         divider: 1024,
         real: true,
     });

package/string/humanizeNumber.js

@@ -16,31 +16,29 @@ function humanizeNumber(val, options = {}) {
         : options?.units === false
             ? false
             : DEFAULT_UNITS;
-    let normalized = 0;
-    if (typeof val === 'string') {
-        normalized = REAL ? parseInt(val.trim(), 10) : parseFloat(val);
-    }
-    else if (Number.isFinite(val)) {
-        normalized = REAL ? Math.round(val) : val;
-    }
+    let normalized = typeof val === 'string' ? parseFloat(val.trim()) : val;
     if (!Number.isFinite(normalized) || normalized === 0)
         return UNITS ? `0${UNITS[0]}` : '0';
+    if (REAL)
+        normalized = Math.round(normalized);
     const sign = normalized < 0 ? '-' : '';
     normalized = Math.abs(normalized);
     let unit_ix = 0;
     if (UNITS) {
-        for (unit_ix; normalized >= DIVIDER && unit_ix < UNITS.length - 1; unit_ix++) {
+        while (normalized >= DIVIDER && unit_ix < UNITS.length - 1) {
             normalized /= DIVIDER;
+            unit_ix++;
         }
     }
     const humanized = `${(0, round_1.round)(normalized, PRECISION)}`.split('.', 2);
-    const integerPart = humanized[0];
+    const integer_part = humanized[0];
+    const integer_part_len = integer_part.length;
     let formattedIntegerPart = '';
-    for (let i = 0; i < integerPart.length; i++) {
-        if (i > 0 && (integerPart.length - i) % 3 === 0) {
+    for (let i = 0; i < integer_part_len; i++) {
+        if (i > 0 && (integer_part_len - i) % 3 === 0) {
             formattedIntegerPart += DELIM;
         }
-        formattedIntegerPart += integerPart[i];
+        formattedIntegerPart += integer_part[i];
     }
-    return `${sign}${formattedIntegerPart}${humanized[1] ? SEPARATOR + humanized[1] : ''}${UNITS ? UNITS[unit_ix] : ''}`;
+    return sign + formattedIntegerPart + (humanized[1] ? SEPARATOR + humanized[1] : '') + (UNITS ? UNITS[unit_ix] : '');
 }

package/string/shorten.js

@@ -17,8 +17,5 @@ function shorten(val, length, postfix = '...', truncate_words = true) {
     while (end > 0 && sanitized[end] !== ' ' && sanitized[end - 1] !== ' ') {
         end--;
     }
-    if (end === 0) {
-        return sanitized.substring(0, length) + postfix;
-    }
     return sanitized.substring(0, end).trim() + postfix;
 }