@valkyriestudios/utils 12.11.0 → 12.13.0

package/README.md

@@ -404,6 +404,10 @@ Available tokens for usage in spec:
 | `SSS` | Milliseconds as 3-digit | 000 001 ... 998 999 |
 | `A` | Uppercase AM/PM | AM ... PM |
 | `a` | Lowercase AM/PM | am ... pm |
+| `l` | Locale-specific short Date | 15/07/2024 |
+| `L` | Locale-Specific date | 15 jul 2024 |
+| `t` | Locale-specific short time | 10:28 AM |
+| `T` | Locale-specific time with seconds | 10:28:30 AM |
 
 ```typescript
 format(new Date('2023-01-10T14:30:00Z'), '[Today is] dddd, MMMM D, YYYY [at] h:mm A', 'en', 'Europe/Brussels');
@@ -431,6 +435,19 @@ Returns the current unix timestamp in seconds
 - **nowUnixMs()**
 Returns the current unix timestamp in milliseconds
 
+- **setTimeUTC(val:Date, props:{hour?:number;minute?:number;second?:number;millisecond?:number})**
+Take the incoming date and return a date where the time portion is set to the values in the provided props
+
+Note: Does not touch the date object passed
+```typescript
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {hour: 5}); // new Date("2023-05-04T05:04:27.432Z")
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {hour: 5, minute: 30}); // new Date("2023-05-04T05:30:27.432Z")
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {hour: 5, minute: 30, second: 0}); // new Date("2023-05-04T05:30:00.432Z")
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {hour: 5, minute: 30, second: 0, millisecond: 0}); // new Date("2023-05-04T05:30:00.000Z")
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {minute: 30, second: 0, millisecond: 0}); // new Date("2023-05-04T12:30:00.000Z")
+setTimeUTC(new Date("2023-05-04T12:04:27.432Z"), {second: 9, millisecond: 0}); // new Date("2023-05-04T12:04:09.000Z")
+```
+
 - **startOfUTC(val:Date, key:string)**
 Take the incoming date and return a date set to the start of passed key. Possible key options(year,quarter,month,week,week_sun,week_mon,week_tue,week_wed,week_thu,week_fri,week_sat,day,hour,minute,second).
 

package/array/sort.d.ts

@@ -17,7 +17,14 @@ interface sortOptions {
 }
 type sortByFunction = (el: Record<string, any>) => string;
 /**
- * Sort an array of objects, uses an implementation of Tony Hoare's quicksort
+ * Sort an array of objects.
+ *
+ * The internals of this function swap between insertion and quicksort depending on the use-case.
+ * Insertion sort is used for smaller arrays and quicksort is used for larger arrays.
+ *
+ * The threshold for insertion sort is 10 elements.
+ *
+ * The quicksort implementation is based on Tony Hoare's quicksort
  * (https://cs.stanford.edu/people/eroberts/courses/soco/projects/2008-09/tony-hoare/quicksort.html)
  *
  * Example:
@@ -43,10 +50,10 @@ type sortByFunction = (el: Record<string, any>) => string;
  * Output:
  *  [{test: 'Pony'}, {test: 'Peter'}, {test: 'JOHn'}, {test: 'Joe'}]
  *
- * @param val - Array to sort
- * @param by - Either a string (key) or a function
- * @param dir - (default='asc') Direction to sort in (asc or desc)
- * @param opts - Sort options
+ * @param {Array} val - Array to sort
+ * @param {string|sortByFunction} by - Either a string (key) or a function
+ * @param {'desc'|'asc'} dir - (default='asc') Direction to sort in (asc or desc)
+ * @param {sortOptions} opts - Sort options
  *
  * @returns Sorted array
  * @throws {Error}

package/array/sort.js

@@ -3,100 +3,97 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sort = sort;
 exports.default = sort;
 const isNotEmpty_1 = require("../object/isNotEmpty");
-function partition(arr, start_ix, end_ix) {
-    const pivot_val = arr[Math.floor((start_ix + end_ix) / 2)].t;
-    while (start_ix <= end_ix) {
-        while (arr[start_ix].t < pivot_val) {
-            start_ix++;
+const INSERTION_SORT_THRESHOLD = 10;
+function partition(arr, low, high) {
+    const pivot = arr[Math.floor((low + high) / 2)][0];
+    let i = low;
+    let j = high;
+    while (i <= j) {
+        while (arr[i][0] < pivot) {
+            i++;
         }
-        while (arr[end_ix].t > pivot_val) {
-            end_ix--;
+        while (arr[j][0] > pivot) {
+            j--;
         }
-        if (start_ix <= end_ix) {
-            const temp = arr[start_ix];
-            arr[start_ix] = arr[end_ix];
-            arr[end_ix] = temp;
-            start_ix++;
-            end_ix--;
+        if (i <= j) {
+            [arr[i], arr[j]] = [arr[j], arr[i]];
+            i++;
+            j--;
         }
     }
-    return start_ix;
+    return i;
 }
-function quickSort(arr, start_ix = 0, end_ix = arr.length - 1) {
-    if (start_ix < end_ix) {
-        const ix = partition(arr, start_ix, end_ix);
-        quickSort(arr, start_ix, ix - 1);
-        quickSort(arr, ix, end_ix);
+function quickSort(arr) {
+    const stack = [{ low: 0, high: arr.length - 1 }];
+    while (stack.length) {
+        const { low, high } = stack.pop();
+        if (high - low <= INSERTION_SORT_THRESHOLD) {
+            for (let i = low + 1; i <= high; i++) {
+                const key = arr[i];
+                let j = i - 1;
+                while (j >= low && arr[j][0] > key[0]) {
+                    arr[j + 1] = arr[j];
+                    j--;
+                }
+                arr[j + 1] = key;
+            }
+        }
+        else {
+            const p = partition(arr, low, high);
+            if (p - 1 > low)
+                stack.push({ low, high: p - 1 });
+            if (p < high)
+                stack.push({ low: p, high });
+        }
     }
     return arr;
 }
 function sort(arr, by, dir = 'asc', opts) {
     if (!Array.isArray(arr) || !arr.length)
         return [];
-    if (dir !== 'asc' && dir !== 'desc')
-        throw new Error('Direction should be either asc or desc');
-    let NOKEY_HIDE = false;
-    let NOKEY_AT_END = true;
+    const NOKEY_HIDE = opts?.nokey_hide === true;
+    const NOKEY_AT_END = opts?.nokey_atend !== false;
     let FILTER_FN = isNotEmpty_1.isNotEmptyObject;
-    if (opts && Object.prototype.toString.call(opts) === '[object Object]') {
-        if (opts.nokey_hide === true)
-            NOKEY_HIDE = true;
-        if (opts.nokey_atend === false)
-            NOKEY_AT_END = false;
-        if (typeof opts.filter_fn === 'function') {
-            const fn = opts.filter_fn;
-            FILTER_FN = (el => (0, isNotEmpty_1.isNotEmptyObject)(el) && fn(el));
-        }
+    if (typeof opts?.filter_fn === 'function') {
+        const fn = opts.filter_fn;
+        FILTER_FN = (el => (0, isNotEmpty_1.isNotEmptyObject)(el) && fn(el));
     }
-    const prepared_arr = [];
-    const nokey_arr = [];
+    let getKey;
     if (typeof by === 'string') {
         const by_s = by.trim();
         if (!by_s.length)
             throw new Error('Sort by as string should contain content');
-        for (let i = 0; i < arr.length; i++) {
-            const el = arr[i];
-            if (!FILTER_FN(el))
-                continue;
-            if (el?.[by_s] === undefined) {
-                nokey_arr.push(el);
-            }
-            else {
-                prepared_arr.push({ t: el[by_s], el });
-            }
-        }
+        getKey = (el) => el[by_s];
     }
     else if (typeof by === 'function') {
-        let key;
-        for (let i = 0; i < arr.length; i++) {
-            const el = arr[i];
-            if (!FILTER_FN(el))
-                continue;
-            key = by(el);
-            if (key === undefined) {
-                nokey_arr.push(el);
-            }
-            else {
-                prepared_arr.push({ t: key, el });
-            }
-        }
+        getKey = by;
     }
     else {
         throw new Error('Sort by should either be a string with content or a function');
     }
+    const prepared_arr = [];
+    const nokey_arr = [];
+    for (let i = 0; i < arr.length; i++) {
+        const el = arr[i];
+        if (!FILTER_FN(el))
+            continue;
+        const key = getKey(el);
+        if (key === undefined) {
+            nokey_arr.push(el);
+        }
+        else {
+            prepared_arr.push([key, el]);
+        }
+    }
     quickSort(prepared_arr);
     if (dir === 'desc')
         prepared_arr.reverse();
     const rslt = [];
-    if (!NOKEY_HIDE && !NOKEY_AT_END) {
-        for (let i = 0; i < nokey_arr.length; i++)
-            rslt.push(nokey_arr[i]);
-    }
+    if (!NOKEY_HIDE && !NOKEY_AT_END)
+        rslt.push(...nokey_arr);
     for (let i = 0; i < prepared_arr.length; i++)
-        rslt.push(prepared_arr[i].el);
-    if (!NOKEY_HIDE && NOKEY_AT_END) {
-        for (let i = 0; i < nokey_arr.length; i++)
-            rslt.push(nokey_arr[i]);
-    }
+        rslt.push(prepared_arr[i][1]);
+    if (!NOKEY_HIDE && NOKEY_AT_END)
+        rslt.push(...nokey_arr);
     return rslt;
 }

package/date/format.js

@@ -36,21 +36,21 @@ function toZone(date, zone) {
         throw new Error(`format: Invalid zone passed - ${zone}`);
     const offset = zone_time - client_time;
     zone_offset_cache.set(ckey, offset);
-    return new Date(date.getTime() + offset);
+    return new Date(client_time + offset);
 }
 function runIntl(loc, token, props, val) {
     const hash = `${loc}:${token}`;
     let formatter = intl_formatters.get(hash);
-    if (formatter)
-        return formatter.format(val);
-    try {
-        formatter = new Intl.DateTimeFormat(loc, props);
-        intl_formatters.set(hash, formatter);
-        return formatter.format(val);
-    }
-    catch (err) {
-        throw new Error(`format: Failed to run conversion for ${token} with locale ${loc}`);
+    if (!formatter) {
+        try {
+            formatter = new Intl.DateTimeFormat(loc, props);
+            intl_formatters.set(hash, formatter);
+        }
+        catch (err) {
+            throw new Error(`format: Failed to run conversion for ${token} with locale ${loc}`);
+        }
     }
+    return formatter.format(val);
 }
 const Tokens = [
     ['YYYY', d => d.getFullYear()],
@@ -74,6 +74,10 @@ const Tokens = [
     ['SSS', d => `${d.getMilliseconds()}`.padStart(3, '0')],
     ['A', d => d.getHours() < 12 ? 'AM' : 'PM'],
     ['a', d => d.getHours() < 12 ? 'am' : 'pm'],
+    ['l', (d, loc) => runIntl(loc, 'l', { dateStyle: 'short' }, d)],
+    ['L', (d, loc) => runIntl(loc, 'L', { dateStyle: 'medium' }, d)],
+    ['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]]);
@@ -83,11 +87,13 @@ function getSpecChain(spec) {
         return spec_chain;
     spec_chain = [];
     let cursor;
+    let spec_cursor = spec;
     for (let i = 0; i < Tokens.length; i++) {
         cursor = Tokens[i];
-        if (spec.indexOf(cursor[0]) < 0)
+        if (spec_cursor.indexOf(cursor[0]) < 0)
             continue;
         spec_chain.push(cursor);
+        spec_cursor = spec_cursor.replace(cursor[1], '');
     }
     if (spec_chain.length === 0)
         return false;

package/date/index.d.ts

@@ -5,7 +5,8 @@ import { format } from './format';
 import { isDate } from './is';
 import { nowUnix } from './nowUnix';
 import { nowUnixMs } from './nowUnixMs';
+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, startOfUTC, toUnix, toUTC };
+export { addUTC, diff, endOfUTC, format, 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.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.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");
@@ -16,6 +16,8 @@ const nowUnix_1 = require("./nowUnix");
 Object.defineProperty(exports, "nowUnix", { enumerable: true, get: function () { return nowUnix_1.nowUnix; } });
 const nowUnixMs_1 = require("./nowUnixMs");
 Object.defineProperty(exports, "nowUnixMs", { enumerable: true, get: function () { return nowUnixMs_1.nowUnixMs; } });
+const setTimeUTC_1 = require("./setTimeUTC");
+Object.defineProperty(exports, "setTimeUTC", { enumerable: true, get: function () { return setTimeUTC_1.setTimeUTC; } });
 const startOfUTC_1 = require("./startOfUTC");
 Object.defineProperty(exports, "startOfUTC", { enumerable: true, get: function () { return startOfUTC_1.startOfUTC; } });
 const toUnix_1 = require("./toUnix");

package/date/setTimeUTC.d.ts

@@ -0,0 +1,15 @@
+export type TimeProps = {
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+};
+/**
+ * Sets the time on a provided date object and returns it
+ *
+ * @param {Date} val - Date to set the time for
+ * @param {Time} props - Time props to set the time to
+ * @returns {Date} New date with provided amount of key added
+ */
+declare function setTimeUTC(val: Date, props: TimeProps): Date;
+export { setTimeUTC, setTimeUTC as default };

package/date/setTimeUTC.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setTimeUTC = setTimeUTC;
+exports.default = setTimeUTC;
+const is_1 = require("./is");
+const isIntegerBetween_1 = require("../number/isIntegerBetween");
+function setTimeUTC(val, props) {
+    if (!(0, is_1.isDate)(val))
+        throw new TypeError('setTimeUTC requires a date object');
+    return new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), (0, isIntegerBetween_1.isIntegerBetween)(props?.hour, 0, 23) ? props.hour : val.getUTCHours(), (0, isIntegerBetween_1.isIntegerBetween)(props?.minute, 0, 59) ? props?.minute : val.getUTCMinutes(), (0, isIntegerBetween_1.isIntegerBetween)(props?.second, 0, 59) ? props?.second : val.getUTCSeconds(), (0, isIntegerBetween_1.isIntegerBetween)(props?.millisecond, 0, 999) ? props?.millisecond : val.getUTCMilliseconds()));
+}

package/index.d.ts

@@ -146,6 +146,20 @@ declare module "date/nowUnixMs" {
     function nowUnixMs(): number;
     export { nowUnixMs, nowUnixMs as default };
 }
+declare module "number/isIntegerBetween" {
+    function isIntegerBetween(val: unknown, min: number, max: number): val is number;
+    export { isIntegerBetween, isIntegerBetween as default };
+}
+declare module "date/setTimeUTC" {
+    export type TimeProps = {
+        hour?: number;
+        minute?: number;
+        second?: number;
+        millisecond?: number;
+    };
+    function setTimeUTC(val: Date, props: TimeProps): Date;
+    export { setTimeUTC, setTimeUTC as default };
+}
 declare module "date/startOfUTC" {
     function startOfUTC(val: Date, key?: 'year' | 'quarter' | 'month' | 'week' | 'week_sun' | 'week_mon' | 'week_tue' | 'week_wed' | 'week_thu' | 'week_fri' | 'week_sat' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'): Date;
     export { startOfUTC, startOfUTC as default };
@@ -166,10 +180,11 @@ declare module "date/index" {
     import { isDate } from "date/is";
     import { nowUnix } from "date/nowUnix";
     import { nowUnixMs } from "date/nowUnixMs";
+    import { setTimeUTC } from "date/setTimeUTC";
     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, startOfUTC, toUnix, toUTC };
+    export { addUTC, diff, endOfUTC, format, isDate, isDate as is, nowUnix, nowUnixMs, setTimeUTC, startOfUTC, toUnix, toUTC };
 }
 declare module "formdata/is" {
     function isFormData(val: unknown): val is FormData;
@@ -319,10 +334,6 @@ declare module "number/isIntegerBelowOrEqual" {
     function isIntegerBelowOrEqual(val: unknown, ref: number): val is number;
     export { isIntegerBelowOrEqual, isIntegerBelowOrEqual as default };
 }
-declare module "number/isIntegerBetween" {
-    function isIntegerBetween(val: unknown, min: number, max: number): val is number;
-    export { isIntegerBetween, isIntegerBetween as default };
-}
 declare module "number/randomBetween" {
     function randomBetween(min?: number, max?: number): number;
     export { randomBetween, randomBetween as default };

package/package.json

@@ -1 +1 @@
-{ "name": "@valkyriestudios/utils", "version": "12.11.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.13.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" }