@nascentdigital/funnel-core 4.4.4

package/dist/utils/DateUtils.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateUtils = void 0;
+const date_fns_1 = require("date-fns");
+// extension
+var DateUtils;
+(function (DateUtils) {
+    // constants
+    DateUtils.minute = 60;
+    DateUtils.hour = DateUtils.minute * 60;
+    DateUtils.day = DateUtils.hour * 24;
+    // helpers
+    function ageInSeconds(from, to) {
+        return (0, date_fns_1.differenceInSeconds)(to !== null && to !== void 0 ? to : Date.now(), from, { roundingMethod: 'round' });
+    }
+    DateUtils.ageInSeconds = ageInSeconds;
+    function ageInWeeks(from, to) {
+        return (0, date_fns_1.differenceInCalendarWeeks)(to !== null && to !== void 0 ? to : Date.now(), from, { weekStartsOn: 1 });
+    }
+    DateUtils.ageInWeeks = ageInWeeks;
+    function format(time, { variant = 'datetime' } = {}) {
+        switch (variant) {
+            case 'full-numeric':
+                return (0, date_fns_1.format)(time, 'yyyy-MM-dd');
+            case 'date':
+                return (0, date_fns_1.format)(time, 'MMM d, yyyy');
+            default:
+                return (0, date_fns_1.format)(time, 'MMM d, yyyy \'at\' H:mmaaa');
+        }
+    }
+    DateUtils.format = format;
+    function formatAge(from, resolution = 'second') {
+        // determine the number of seconds
+        const to = Date.now();
+        const seconds = ageInSeconds(from, to);
+        // handle sub-minute timing
+        if (seconds < 60) {
+            return resolution !== 'second' || seconds < 10
+                ? 'Just now'
+                : `${seconds}s ago`;
+        }
+        // handle sub-hour timing
+        const minutes = Math.floor(seconds / 60);
+        if (minutes === 1) {
+            return '1 min ago';
+        }
+        else if (minutes < 60) {
+            return `${minutes} mins ago`;
+        }
+        // handle sub-day timing
+        const hours = Math.floor(minutes / 60);
+        if (hours === 1) {
+            return '1 hour ago';
+        }
+        else if (hours < 60) {
+            return `${hours} hours ago`;
+        }
+        // handle sub-week timing
+        const days = Math.floor(hours / 24);
+        if (days === 1) {
+            return '1 day ago';
+        }
+        else if (days < 7) {
+            return `${days} days ago`;
+        }
+        // handle sub-month timing
+        const weeks = (0, date_fns_1.differenceInCalendarWeeks)(to, from, { weekStartsOn: 1 });
+        if (weeks <= 1) {
+            return '1 week ago';
+        }
+        else if (weeks < 5) {
+            return `${weeks} weeks ago`;
+        }
+        // handle sub-year timing
+        const months = (0, date_fns_1.differenceInCalendarMonths)(to, from);
+        if (months <= 1) {
+            return 'Last month';
+        }
+        else if (months < 12) {
+            return `${months} months ago`;
+        }
+        // handle sub-century timing
+        const years = (0, date_fns_1.differenceInYears)(to, from);
+        if (years < 2) {
+            return '1 year ago';
+        }
+        else if (years < 100) {
+            return `${years} years ago`;
+        }
+        // handle centuries
+        const centuries = Math.floor(years / 100);
+        if (centuries === 1) {
+            return '1 century ago';
+        }
+        else {
+            return `${centuries} centuries ago`;
+        }
+    }
+    DateUtils.formatAge = formatAge;
+})(DateUtils || (exports.DateUtils = DateUtils = {}));

package/dist/utils/Deferral.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Provides shared access to resolve a `Promise`.
+ */
+export declare class Deferral<TResult> {
+    private readonly _options;
+    private _promise;
+    private _state;
+    private _resolve?;
+    private _resolveValue?;
+    private _reject?;
+    private _rejectValue?;
+    constructor(options?: Deferral.Options);
+    get promise(): Promise<TResult>;
+    get state(): State;
+    get isComplete(): boolean;
+    get isResolved(): boolean;
+    resolve(value: TResult): void;
+    reject(value: any): void;
+    reset(): void;
+}
+export declare namespace Deferral {
+    type Options = {
+        ignoreRepeats?: boolean;
+        resetOnReject?: boolean;
+    };
+}
+type State = 'unresolved' | 'resolved' | 'rejected';
+export {};

package/dist/utils/Deferral.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deferral = void 0;
+const errors_1 = require("../errors");
+/**
+ * Provides shared access to resolve a `Promise`.
+ */
+class Deferral {
+    constructor(options = {}) {
+        // initialize options
+        this._options = Object.assign({ ignoreRepeats: false, resetOnReject: false }, options);
+        this._state = 'unresolved';
+        // reset (creates initial promise)
+        this.reset();
+    }
+    get promise() {
+        return this._promise;
+    }
+    get state() {
+        return this._state;
+    }
+    get isComplete() {
+        return this._state !== 'unresolved';
+    }
+    get isResolved() {
+        return this._state === 'resolved';
+    }
+    resolve(value) {
+        // short-circuit if already complete
+        const resolve = this._resolve;
+        if (this.isComplete) {
+            // ignore if it's not a problem
+            if (this._options.ignoreRepeats) {
+                return;
+            }
+            // or throw
+            else {
+                throw new errors_1.InvalidOperationError('Attempt to access resolver that is already completed.');
+            }
+        }
+        // mark as resolved
+        this._state = 'resolved';
+        // invoke resolver if it's set
+        if (resolve) {
+            resolve(value);
+        }
+        // otherwise, queue value
+        else {
+            this._resolveValue = { value };
+        }
+    }
+    reject(value) {
+        // short-circuit if already complete
+        const reject = this._reject;
+        if (this.isComplete) {
+            // reset if required
+            if (this._options.resetOnReject) {
+                this.reset();
+                return;
+            }
+            // ignore if it's not a problem
+            else if (this._options.ignoreRepeats) {
+                return;
+            }
+            // or throw
+            else {
+                throw new errors_1.InvalidOperationError('Attempt to access reject that is already resolved.');
+            }
+        }
+        // mark as complete
+        this._state = 'rejected';
+        // invoke resolver if it's set
+        if (reject) {
+            reject(value);
+        }
+        // otherwise, queue value
+        else {
+            this._rejectValue = { value };
+        }
+    }
+    reset() {
+        // clear resolve/reject
+        this._state = 'unresolved';
+        delete this._resolve;
+        delete this._resolveValue;
+        delete this._reject;
+        delete this._rejectValue;
+        // create promise
+        this._promise = new Promise((resolve, reject) => {
+            // capture resolver
+            this._resolve = resolve;
+            // capture reject
+            this._reject = reject;
+            // resolve/reject immediately if complete
+            const { _state, _resolveValue, _rejectValue } = this;
+            if (_state !== 'unresolved') {
+                if (_resolveValue) {
+                    resolve(_resolveValue.value);
+                }
+                else {
+                    reject(_rejectValue === null || _rejectValue === void 0 ? void 0 : _rejectValue.value);
+                }
+            }
+        });
+    }
+}
+exports.Deferral = Deferral;

package/dist/utils/Duration.d.ts

@@ -0,0 +1,7 @@
+import { StringValue } from 'ms';
+export type Duration = StringValue;
+export declare namespace Duration {
+    function toMilliseconds(duration: Duration): number;
+    function toSeconds(duration: Duration): number;
+    function formatSeconds(timeInSeconds: number): string;
+}

package/dist/utils/Duration.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Duration = void 0;
+const ms_1 = __importDefault(require("ms"));
+// extension
+var Duration;
+(function (Duration) {
+    // methods
+    function toMilliseconds(duration) {
+        return (0, ms_1.default)(duration);
+    }
+    Duration.toMilliseconds = toMilliseconds;
+    function toSeconds(duration) {
+        return toMilliseconds(duration) / 1000;
+    }
+    Duration.toSeconds = toSeconds;
+    function formatSeconds(timeInSeconds) {
+        // compute seconds
+        let normalizedTime = Math.floor(timeInSeconds);
+        const seconds = normalizedTime % 60;
+        // compute minutes + hours
+        normalizedTime = Math.floor(normalizedTime / 60);
+        const minutes = normalizedTime % 60;
+        const hours = Math.floor(normalizedTime / 60);
+        // return time (include hours if any)
+        const time = `${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+        return hours
+            ? `${hours.toString()}:${time}`
+            : time;
+    }
+    Duration.formatSeconds = formatSeconds;
+})(Duration || (exports.Duration = Duration = {}));

package/dist/utils/Fn.d.ts

@@ -0,0 +1,14 @@
+export declare namespace Fn {
+    function NoOp(): undefined;
+    function Identity<T>(value: T): T;
+    function True(): boolean;
+    function False(): boolean;
+    function Null(): null;
+    namespace Async {
+        function NoOp(): Promise<undefined>;
+        function Identity<T>(value: T): Promise<T>;
+        function True(): Promise<boolean>;
+        function False(): Promise<boolean>;
+        function Null(): Promise<null>;
+    }
+}

package/dist/utils/Fn.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Fn = void 0;
+// namespace
+var Fn;
+(function (Fn) {
+    // helpers
+    function NoOp() {
+        return undefined;
+    }
+    Fn.NoOp = NoOp;
+    function Identity(value) {
+        return value;
+    }
+    Fn.Identity = Identity;
+    function True() {
+        return true;
+    }
+    Fn.True = True;
+    function False() {
+        return false;
+    }
+    Fn.False = False;
+    function Null() {
+        return null;
+    }
+    Fn.Null = Null;
+    // async helpers
+    let Async;
+    (function (Async) {
+        async function NoOp() {
+            return undefined;
+        }
+        Async.NoOp = NoOp;
+        async function Identity(value) {
+            return value;
+        }
+        Async.Identity = Identity;
+        async function True() {
+            return true;
+        }
+        Async.True = True;
+        async function False() {
+            return false;
+        }
+        Async.False = False;
+        async function Null() {
+            return null;
+        }
+        Async.Null = Null;
+    })(Async = Fn.Async || (Fn.Async = {}));
+})(Fn || (exports.Fn = Fn = {}));

package/dist/utils/ObjectUtils.d.ts

@@ -0,0 +1,89 @@
+import { Transform } from '../types';
+import { Value } from './Value';
+export declare namespace ObjectUtils {
+    function hasKeys<TKey extends string>(object: object, ...keys: TKey[]): object is Record<TKey, any>;
+    function hasStringKeys<TKey extends string>(object: object, ...keys: TKey[]): object is Record<TKey, string>;
+    type CreateSeriesArgs<TKey extends string = string, TValue = number> = {
+        start: number;
+        end: number;
+        step?: number;
+        getKey?: (value: number) => TKey;
+        getValue?: (value: number) => TValue;
+    };
+    function createSeries<TKey extends string = string, TValue = number>({ start, end, step, getKey, getValue }: CreateSeriesArgs<TKey, TValue>): Record<TKey, TValue>;
+    type SplitProps<TProps extends object, TSubKey extends keyof Required<TProps>> = {
+        splitProps: Pick<TProps, TSubKey>;
+        props: Omit<TProps, TSubKey>;
+    };
+    function splitProps<TProps extends object, TSubKey extends keyof Required<TProps>>(mixedProps: TProps, keys: ReadonlyArray<TSubKey>): SplitProps<TProps, TSubKey>;
+    function slice<TProps extends object, TSubKey extends keyof Required<TProps>>(mixedProps: TProps, ...keys: ReadonlyArray<TSubKey>): Pick<TProps, TSubKey>;
+    /**
+     * Creates a new object with the updated entry (adding it if required)
+     * @param object - the existing object to copy + change
+     * @param key - the key of the entry to update/add
+     * @param value - the value of the entry to update/add
+     */
+    function upsert<T extends object, TKey extends keyof T>(object: T, key: TKey, value: T[TKey]): T & {
+        [key]: T[TKey];
+    };
+    function clone<T>(value: T): T;
+    function walk(value: any, onWalk: walk.OnWalk): void;
+    namespace walk {
+        type OnWalk = Transform<WalkerArgs, boolean | undefined | void>;
+        type WalkerArgs = ObjectArgs | ArrayArgs | StringArgs | NumberArgs | BigIntArgs | BooleanArgs | NullableArgs;
+        type ObjectArgs = {
+            __type: 'object';
+            value: object;
+        };
+        type ArrayArgs = {
+            __type: 'array';
+            value: any[];
+        };
+        type StringArgs = {
+            __type: 'string';
+            value: string;
+        };
+        type NumberArgs = {
+            __type: 'number';
+            value: number;
+        };
+        type BigIntArgs = {
+            __type: 'bigint';
+            value: bigint;
+        };
+        type BooleanArgs = {
+            __type: 'boolean';
+            value: boolean;
+        };
+        type NullableArgs = {
+            __type: 'nullable';
+            value: null | undefined;
+        };
+    }
+    function transform<TOut = any>({ value, transform, recurse }: transform.Args): TOut;
+    namespace transform {
+        type Args = {
+            value: any;
+            transform: Transform<Node, any>;
+            recurse?: boolean | Transform<Node, boolean>;
+        };
+        type Node = Node.Undefined | Node.Null | Node.Boolean | Node.String | Node.Number | Node.BigInt | Node.Symbol | Node.Object | Node.Array | Node.Fn;
+        namespace Node {
+            type Base<T extends Value.TypeOf, V> = {
+                type: T;
+                value: V;
+                index?: string | number;
+            };
+            type Undefined = Base<'undefined', undefined>;
+            type Null = Base<'null', null>;
+            type Boolean = Base<'boolean', boolean>;
+            type String = Base<'string', string>;
+            type Number = Base<'number', number>;
+            type BigInt = Base<'bigint', bigint>;
+            type Symbol = Base<'symbol', symbol>;
+            type Object = Base<'object', object>;
+            type Array = Base<'array', unknown[]>;
+            type Fn = Base<'function', any>;
+        }
+    }
+}

package/dist/utils/ObjectUtils.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectUtils = void 0;
+const clone_deep_1 = __importDefault(require("clone-deep"));
+const Value_1 = require("./Value");
+// namespace
+var ObjectUtils;
+(function (ObjectUtils) {
+    // guards
+    function hasKeys(object, ...keys) {
+        return keys.every(key => Object.hasOwn(object, key));
+    }
+    ObjectUtils.hasKeys = hasKeys;
+    function hasStringKeys(object, ...keys) {
+        const value = object;
+        return keys.every(key => key in value && typeof value[key] === 'string');
+    }
+    ObjectUtils.hasStringKeys = hasStringKeys;
+    function createSeries({ start, end, step = 1, getKey = (key) => key.toString(), getValue = (value) => value }) {
+        // iterate over range and build object
+        const generated = {};
+        for (let i = start; i <= end; i += step) {
+            generated[getKey(i)] = getValue(i);
+        }
+        // return generated
+        return generated;
+    }
+    ObjectUtils.createSeries = createSeries;
+    function splitProps(mixedProps, keys) {
+        console.debug('[splitProps] splitting', { mixedProps, keys });
+        // split props
+        const splitProps = {};
+        const props = {};
+        for (const [key, value] of Object.entries(mixedProps)) {
+            if (keys.includes(key)) {
+                splitProps[key] = value;
+            }
+            else {
+                props[key] = value;
+            }
+        }
+        // and return them
+        return { splitProps, props };
+    }
+    ObjectUtils.splitProps = splitProps;
+    function slice(mixedProps, ...keys) {
+        return splitProps(mixedProps, keys).splitProps;
+    }
+    ObjectUtils.slice = slice;
+    /**
+     * Creates a new object with the updated entry (adding it if required)
+     * @param object - the existing object to copy + change
+     * @param key - the key of the entry to update/add
+     * @param value - the value of the entry to update/add
+     */
+    function upsert(object, key, value) {
+        return Object.assign(Object.assign({}, object), { [key]: value });
+    }
+    ObjectUtils.upsert = upsert;
+    function clone(value) {
+        return (0, clone_deep_1.default)(value);
+    }
+    ObjectUtils.clone = clone;
+    function walk(value, onWalk) {
+        // helper
+        function walker(value) {
+            var _a, _b;
+            // handle nullables
+            if (value === undefined || value === null) {
+                onWalk({ __type: 'nullable', value });
+            }
+            // handle arrays
+            else if (Array.isArray(value)) {
+                // walk array
+                const recurse = (_a = onWalk({ __type: 'array', value })) !== null && _a !== void 0 ? _a : false;
+                // walk items if required
+                if (recurse) {
+                    value.forEach(value => walker(value));
+                }
+            }
+            // or transform leaf node
+            else {
+                switch (typeof value) {
+                    case 'object': {
+                        // walk object
+                        const recurse = (_b = onWalk({ __type: 'object', value })) !== null && _b !== void 0 ? _b : false;
+                        // walk entries (if required)
+                        if (recurse) {
+                            Object.values(value).forEach(value => walker(value));
+                        }
+                        break;
+                    }
+                    case 'string':
+                        onWalk({ __type: 'string', value });
+                        break;
+                    case 'number':
+                        onWalk({ __type: 'number', value });
+                        break;
+                    case 'bigint':
+                        onWalk({ __type: 'bigint', value });
+                        break;
+                    case 'boolean':
+                        onWalk({ __type: 'boolean', value });
+                        break;
+                }
+            }
+        }
+        // start walking
+        walker(value);
+    }
+    ObjectUtils.walk = walk;
+    function transform({ value, transform, recurse = true }) {
+        // helpers
+        const shouldWalk = typeof recurse === 'boolean'
+            ? () => recurse
+            : recurse;
+        const onTransform = (node) => {
+            const value = transform(node);
+            return value === node
+                ? node.value
+                : value;
+        };
+        // create helpers
+        function walk(value, index) {
+            // process based on type
+            const type = Value_1.Value.typeOf(value);
+            const node = { type, value, index };
+            switch (type) {
+                // handle walkable objects
+                case 'array':
+                case 'object':
+                    // ignore if restricted from walking value
+                    if (!shouldWalk(node)) {
+                        return onTransform(node);
+                    }
+                    // or walk arrays
+                    else if (type === 'array') {
+                        return value.map((value, index) => walk(value, index));
+                    }
+                    // or walk object
+                    else {
+                        return Object.entries(value).reduce((object, [key, value]) => {
+                            object[key] = walk(value, key);
+                            return object;
+                        }, {});
+                    }
+                // or transform other nodes
+                default:
+                    return onTransform(node);
+            }
+        }
+        // start walking
+        return walk(value);
+    }
+    ObjectUtils.transform = transform;
+})(ObjectUtils || (exports.ObjectUtils = ObjectUtils = {}));

package/dist/utils/Random.d.ts

@@ -0,0 +1,15 @@
+export declare namespace Random {
+    type Randomizer = () => number;
+    function createRandomizer(seed: string): Randomizer;
+    function boolean(odds?: number, randomizer?: Randomizer): boolean;
+    function negate(value: number, odds?: number, randomizer?: Randomizer): number;
+    function number(max: number, min?: number, randomizer?: Randomizer): number;
+    function int(max: number, min?: number, randomizer?: Randomizer): number;
+    function intInclusive(max: number, min?: number, randomizer?: Randomizer): number;
+    function easeInCubic(randomizer?: Randomizer): number;
+    function easeInOutQuint(randomizer?: Randomizer): number;
+    function array<T>(array: ReadonlyArray<T>, randomizer?: Randomizer): T[];
+    function element<T>(array: ReadonlyArray<T>, randomizer?: Randomizer): T;
+    function addRandomElement<T>(array: Array<T>, element: T, randomizer?: Randomizer): void;
+    function removeRandomElement<T>(array: Array<T>, randomizer?: Randomizer): T;
+}

package/dist/utils/Random.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Random = void 0;
+const seedrandom_1 = __importDefault(require("seedrandom"));
+// namespace
+var Random;
+(function (Random) {
+    // randomizer factory
+    function createRandomizer(seed) {
+        return (0, seedrandom_1.default)(seed);
+    }
+    Random.createRandomizer = createRandomizer;
+    // methods
+    function boolean(odds = 0.5, randomizer = Math.random) {
+        return randomizer() < odds;
+    }
+    Random.boolean = boolean;
+    function negate(value, odds = 0.5, randomizer = Math.random) {
+        return randomizer() < odds ? value : -value;
+    }
+    Random.negate = negate;
+    function number(max, min = 0, randomizer = Math.random) {
+        return Math.floor(randomizer() * (max - min) + min);
+    }
+    Random.number = number;
+    function int(max, min = 0, randomizer = Math.random) {
+        min = Math.ceil(min);
+        max = Math.floor(max);
+        return Math.floor(randomizer() * (max - min)) + min;
+    }
+    Random.int = int;
+    function intInclusive(max, min = 0, randomizer = Math.random) {
+        min = Math.ceil(min);
+        max = Math.floor(max);
+        return Math.floor(randomizer() * (max - min + 1)) + min;
+    }
+    Random.intInclusive = intInclusive;
+    function easeInCubic(randomizer = Math.random) {
+        const x = randomizer();
+        return x * x * x;
+    }
+    Random.easeInCubic = easeInCubic;
+    function easeInOutQuint(randomizer = Math.random) {
+        const x = randomizer();
+        return x < 0.5 ? 16 * x * x * x * x * x : 1 - Math.pow(-2 * x + 2, 5) / 2;
+    }
+    Random.easeInOutQuint = easeInOutQuint;
+    function array(array, randomizer = Math.random) {
+        const original = Array.from(array);
+        const randomized = new Array();
+        while (original.length > 0) {
+            randomized.push(removeRandomElement(original));
+        }
+        return randomized;
+    }
+    Random.array = array;
+    function element(array, randomizer = Math.random) {
+        return array[int(array.length, 0, randomizer)];
+    }
+    Random.element = element;
+    function addRandomElement(array, element, randomizer = Math.random) {
+        array.splice(int(array.length), 0, element);
+    }
+    Random.addRandomElement = addRandomElement;
+    function removeRandomElement(array, randomizer = Math.random) {
+        return array.splice(int(array.length, 0, randomizer), 1)[0];
+    }
+    Random.removeRandomElement = removeRandomElement;
+})(Random || (exports.Random = Random = {}));