@naturalcycles/js-lib 14.276.0 → 15.0.0

package/dist-esm/datetime/timeInterval.js

@@ -1,88 +0,0 @@
-import { localTime } from './localTime';
-/**
- * Class that supports an "interval of time" between 2 timestamps - start and end.
- * Example: `1649267185/1649267187`.
- *
- * @experimental
- */
-export class TimeInterval {
-    constructor($start, $end) {
-        this.$start = $start;
-        this.$end = $end;
-    }
-    static of(start, end) {
-        return new TimeInterval(localTime.fromInput(start).unix, localTime.fromInput(end).unix);
-    }
-    get start() {
-        return this.$start;
-    }
-    get end() {
-        return this.$end;
-    }
-    get startTime() {
-        return localTime(this.$start);
-    }
-    get endTime() {
-        return localTime(this.$end);
-    }
-    /**
-     * Parses string like `1649267185/1649267187` into a TimeInterval.
-     */
-    static parse(d) {
-        if (d instanceof TimeInterval)
-            return d;
-        const [start, end] = d.split('/').map(Number);
-        if (!end || !start) {
-            throw new Error(`Cannot parse "${d}" into TimeInterval`);
-        }
-        return new TimeInterval(start, end);
-    }
-    isSame(d) {
-        return this.cmp(d) === 0;
-    }
-    isBefore(d, inclusive = false) {
-        const r = this.cmp(d);
-        return r === -1 || (r === 0 && inclusive);
-    }
-    isSameOrBefore(d) {
-        return this.cmp(d) <= 0;
-    }
-    isAfter(d, inclusive = false) {
-        const r = this.cmp(d);
-        return r === 1 || (r === 0 && inclusive);
-    }
-    isSameOrAfter(d) {
-        return this.cmp(d) >= 0;
-    }
-    includes(d, incl = '[)') {
-        d = localTime.fromInput(d).unix;
-        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-        if (d < this.$start || (d === this.$start && incl[0] === '('))
-            return false;
-        if (d > this.$end || (d === this.$end && incl[1] === ')'))
-            return false;
-        return true;
-    }
-    /**
-     * TimeIntervals compare by start date.
-     * If it's the same - then by end date.
-     */
-    cmp(d) {
-        d = TimeInterval.parse(d);
-        if (this.$start > d.$start)
-            return 1;
-        if (this.$start < d.$start)
-            return -1;
-        if (this.$end > d.$end)
-            return 1;
-        if (this.$end < d.$end)
-            return -1;
-        return 0;
-    }
-    toString() {
-        return [this.$start, this.$end].join('/');
-    }
-    toJSON() {
-        return this.toString();
-    }
-}

package/dist-esm/datetime/wallTime.js

@@ -1,70 +0,0 @@
-import { LocalDate } from './localDate';
-import { localTime } from './localTime';
-/**
- * Representation of a "time on the wall clock",
- * which means "local time, regardless of timezone".
- *
- * Experimental simplified container object to hold
- * date and time components as numbers.
- * No math or manipulation is possible here.
- * Can be pretty-printed as Date, Time or DateAndTime.
- */
-export class WallTime {
-    constructor(obj) {
-        Object.assign(this, obj);
-    }
-    toLocalDate() {
-        return new LocalDate(this.year, this.month, this.day);
-    }
-    /**
-     * Example:
-     * WallTime is 1984-06-21 17:56:21
-     * .toLocalTime() will return a LocalTime Date instance
-     * holding that time in the local timezone.
-     */
-    toLocalTime() {
-        return localTime.fromDateTimeObject(this);
-    }
-    toJSON() {
-        return this.toISODateTime();
-    }
-    toString() {
-        return this.toISODateTime();
-    }
-    /**
-     * Returns e.g: `1984-06-21 17:56:21`
-     * or (if seconds=false):
-     * `1984-06-21 17:56`
-     */
-    toPretty(seconds = true) {
-        return this.toISODate() + ' ' + this.toISOTime(seconds);
-    }
-    /**
-     * Returns e.g: `1984-06-21T17:56:21`
-     */
-    toISODateTime() {
-        return (this.toISODate() + 'T' + this.toISOTime());
-    }
-    /**
-     * Returns e.g: `1984-06-21`, only the date part of DateTime
-     */
-    toISODate() {
-        return [
-            String(this.year).padStart(4, '0'),
-            String(this.month).padStart(2, '0'),
-            String(this.day).padStart(2, '0'),
-        ].join('-');
-    }
-    /**
-     * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
-     */
-    toISOTime(seconds = true) {
-        return [
-            String(this.hour).padStart(2, '0'),
-            String(this.minute).padStart(2, '0'),
-            seconds && String(this.second).padStart(2, '0'),
-        ]
-            .filter(Boolean)
-            .join(':');
-    }
-}

package/dist-esm/decorators/asyncMemo.decorator.js

@@ -1,111 +0,0 @@
-import { _assert, _assertTypeOf } from '../error/assert';
-import { _objectAssign, MISS } from '../types';
-import { _getTargetMethodSignature } from './decorator.util';
-import { jsonMemoSerializer } from './memo.util';
-/**
- * Like @_Memo, but allowing async MemoCache implementation.
- *
- * Implementation is more complex than @_Memo, because it needs to handle "in-flight" Promises
- * while waiting for cache to resolve, to prevent "async swarm" issue.
- *
- * @experimental consider normal @_Memo for most of the cases, it's stable and predictable
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const _AsyncMemo = (opt) => (target, key, descriptor) => {
-    _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
-    const originalFn = descriptor.value;
-    // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
-    const instanceCache = new Map();
-    // Cache from Instance to Map<key, Promise>
-    // This cache is temporary, with only one purpose - to prevent "async swarm"
-    // It only holds values that are "in-flight", until Promise is resolved
-    // After it's resolved - it's evicted from the cache and moved to the "proper" `instanceCache`
-    const instancePromiseCache = new Map();
-    const { logger = console, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt;
-    const keyStr = String(key);
-    const methodSignature = _getTargetMethodSignature(target, keyStr);
-    // eslint-disable-next-line @typescript-eslint/promise-function-async
-    descriptor.value = function (...args) {
-        const ctx = this;
-        const cacheKey = cacheKeyFn(args);
-        let cache = instanceCache.get(ctx);
-        let promiseCache = instancePromiseCache.get(ctx);
-        if (!cache) {
-            cache = cacheFactory();
-            instanceCache.set(ctx, cache);
-            // here, no need to check the cache. It's definitely a miss, because the cacheLayers is just created
-            // UPD: no! AsyncMemo supports "persistent caches" (e.g Database-backed cache)
-        }
-        if (!promiseCache) {
-            promiseCache = new Map();
-            instancePromiseCache.set(ctx, promiseCache);
-        }
-        let promise = promiseCache.get(cacheKey);
-        // If there's already "in-flight" cache request - return that, to avoid "async swarm"
-        if (promise) {
-            // console.log('return promise', promiseCache.size)
-            return promise;
-        }
-        promise = cache.get(cacheKey).then(async (value) => {
-            if (value !== MISS) {
-                // console.log('hit', promiseCache.size)
-                promiseCache.delete(cacheKey);
-                return value;
-            }
-            // Miss
-            // console.log('miss', promiseCache.size)
-            return await onMiss();
-        }, async (err) => {
-            // Log the cache error and proceed "as cache Miss"
-            logger.error(err);
-            return await onMiss();
-        });
-        promiseCache.set(cacheKey, promise);
-        return promise;
-        //
-        async function onMiss() {
-            try {
-                const value = await originalFn.apply(ctx, args);
-                // Save the value in the Cache, in parallel,
-                // not to slow down the main function execution
-                // and not to fail on possible cache issues
-                void (async () => {
-                    try {
-                        await cache.set(cacheKey, value);
-                    }
-                    catch (err) {
-                        logger.error(err); // log and ignore the error
-                    }
-                    finally {
-                        // Clear the "in-flight" promise cache entry, as we now have a "permanent" cache entry
-                        promiseCache.delete(cacheKey);
-                        // console.log('cache set and cleared', promiseCache!.size)
-                    }
-                })();
-                return value;
-            }
-            catch (err) {
-                promiseCache.delete(cacheKey);
-                throw err;
-            }
-        }
-    };
-    _objectAssign(descriptor.value, {
-        clear: async () => {
-            logger.log(`${methodSignature} @_AsyncMemo.clear()`);
-            await Promise.all([...instanceCache.values()].map(c => c.clear()));
-            instanceCache.clear();
-        },
-        getInstanceCache: () => instanceCache,
-        getCache: instance => instanceCache.get(instance),
-    });
-    return descriptor;
-};
-/**
- Call it on a method that is decorated with `@_AsyncMemo` to get access to additional functions,
- e.g `clear` to clear the cache, or get its underlying data.
- */
-export function _getAsyncMemo(method) {
-    _assert(typeof method?.getInstanceCache === 'function', 'method is not an AsyncMemo instance');
-    return method;
-}

package/dist-esm/decorators/createPromiseDecorator.js

@@ -1,82 +0,0 @@
-import { _getTargetMethodSignature } from './decorator.util';
-/**
- * @example
- * // decorators.ts
- * export const BlockingLoader = () => _createPromiseDecorator({
- *   decoratorName: 'BlockingLoader',
- *   beforeFn: () => store.commit('setBlockingLoader'),
- *   finallyFn: () => store.commit('setBlockingLoader', false),
- * })
- *
- * @experimental
- */
-export function _createPromiseDecorator(cfg, decoratorParams = {}) {
-    const { decoratorName } = cfg;
-    return function decoratorFunction(target, propertyKey, pd) {
-        // console.log(`@Decorator.${cfg.decoratorName} called: ` + propertyKey, pd, target)
-        const originalMethod = pd.value;
-        const key = String(propertyKey);
-        const methodSignature = _getTargetMethodSignature(target, key);
-        pd.value = async function (...args) {
-            // console.log(`@${cfg.decoratorName} called inside function`)
-            const started = Date.now();
-            try {
-                // Before function
-                // console.log(`@${cfg.decoratorName} Before`)
-                if (cfg.beforeFn) {
-                    await cfg.beforeFn({
-                        decoratorParams,
-                        args,
-                        key,
-                        target,
-                        decoratorName,
-                        started,
-                    });
-                }
-                // Original function
-                let res = await originalMethod.apply(this, args);
-                // console.log(`${cfg.decoratorName} After`)
-                const resp = {
-                    decoratorParams,
-                    args,
-                    key,
-                    target,
-                    decoratorName,
-                    started,
-                };
-                if (cfg.thenFn) {
-                    res = cfg.thenFn({
-                        ...resp,
-                        res,
-                    });
-                }
-                cfg.finallyFn?.(resp);
-                return res;
-            }
-            catch (err) {
-                console.error(`@${decoratorName} ${methodSignature} catch:`, err);
-                const resp = {
-                    decoratorParams,
-                    args,
-                    key,
-                    target,
-                    decoratorName,
-                    started,
-                };
-                let handled = false;
-                if (cfg.catchFn) {
-                    cfg.catchFn({
-                        ...resp,
-                        err,
-                    });
-                    handled = true;
-                }
-                cfg.finallyFn?.(resp);
-                if (!handled) {
-                    throw err; // rethrow
-                }
-            }
-        };
-        return pd;
-    };
-}

package/dist-esm/decorators/debounce.decorator.js

@@ -1,17 +0,0 @@
-import { _debounce, _throttle } from './debounce';
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export function _Debounce(wait, opt = {}) {
-    return (_target, _key, descriptor) => {
-        const originalFn = descriptor.value;
-        descriptor.value = _debounce(originalFn, wait, opt);
-        return descriptor;
-    };
-}
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export function _Throttle(wait, opt = {}) {
-    return (_target, _key, descriptor) => {
-        const originalFn = descriptor.value;
-        descriptor.value = _throttle(originalFn, wait, opt);
-        return descriptor;
-    };
-}

package/dist-esm/decorators/debounce.js

@@ -1,114 +0,0 @@
-export function _debounce(func, wait, opt = {}) {
-    let lastArgs;
-    let lastThis;
-    let result;
-    let timerId;
-    let lastCallTime;
-    let lastInvokeTime = 0;
-    const maxing = 'maxWait' in opt;
-    const { leading = false, trailing = true } = opt;
-    const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait;
-    function invokeFunc(time) {
-        const args = lastArgs;
-        const thisArg = lastThis;
-        lastArgs = lastThis = undefined;
-        lastInvokeTime = time;
-        result = func.apply(thisArg, args);
-        return result;
-    }
-    function startTimer(pendingFunc, wait) {
-        return setTimeout(pendingFunc, wait);
-    }
-    function cancelTimer(id) {
-        clearTimeout(id);
-    }
-    function leadingEdge(time) {
-        // Reset any `maxWait` timer.
-        lastInvokeTime = time;
-        // Start the timer for the trailing edge.
-        timerId = startTimer(timerExpired, wait);
-        // Invoke the leading edge.
-        return leading ? invokeFunc(time) : result;
-    }
-    function remainingWait(time) {
-        const timeSinceLastCall = time - lastCallTime;
-        const timeSinceLastInvoke = time - lastInvokeTime;
-        const timeWaiting = wait - timeSinceLastCall;
-        return maxing ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke) : timeWaiting;
-    }
-    function shouldInvoke(time) {
-        const timeSinceLastCall = time - lastCallTime;
-        const timeSinceLastInvoke = time - lastInvokeTime;
-        // Either this is the first call, activity has stopped and we're at the
-        // trailing edge, the system time has gone backwards and we're treating
-        // it as the trailing edge, or we've hit the `maxWait` limit.
-        return (lastCallTime === undefined ||
-            timeSinceLastCall >= wait ||
-            timeSinceLastCall < 0 ||
-            (maxing && timeSinceLastInvoke >= maxWait));
-    }
-    function timerExpired() {
-        const time = Date.now();
-        if (shouldInvoke(time)) {
-            return trailingEdge(time);
-        }
-        // Restart the timer.
-        timerId = startTimer(timerExpired, remainingWait(time));
-    }
-    function trailingEdge(time) {
-        timerId = undefined;
-        // Only invoke if we have `lastArgs` which means `func` has been
-        // debounced at least once.
-        if (trailing && lastArgs) {
-            return invokeFunc(time);
-        }
-        lastArgs = lastThis = undefined;
-        return result;
-    }
-    function cancel() {
-        if (timerId !== undefined) {
-            cancelTimer(timerId);
-        }
-        lastInvokeTime = 0;
-        lastArgs = lastCallTime = lastThis = timerId = undefined;
-    }
-    function flush() {
-        return timerId === undefined ? result : trailingEdge(Date.now());
-    }
-    function pending() {
-        return timerId !== undefined;
-    }
-    function debounced(...args) {
-        const time = Date.now();
-        const isInvoking = shouldInvoke(time);
-        lastArgs = args;
-        lastThis = this;
-        lastCallTime = time;
-        if (isInvoking) {
-            if (timerId === undefined) {
-                return leadingEdge(lastCallTime);
-            }
-            if (maxing) {
-                // Handle invocations in a tight loop.
-                timerId = startTimer(timerExpired, wait);
-                return invokeFunc(lastCallTime);
-            }
-        }
-        if (timerId === undefined) {
-            timerId = startTimer(timerExpired, wait);
-        }
-        return result;
-    }
-    debounced.cancel = cancel;
-    debounced.flush = flush;
-    debounced.pending = pending;
-    return debounced;
-}
-export function _throttle(func, wait, opt = {}) {
-    return _debounce(func, wait, {
-        leading: true,
-        trailing: true,
-        ...opt,
-        maxWait: wait,
-    });
-}

package/dist-esm/decorators/decorator.util.js

@@ -1,31 +0,0 @@
-/**
- * @returns
- * e.g `NameOfYourClass.methodName`
- * or `NameOfYourClass(instanceId).methodName`
- */
-export function _getMethodSignature(ctx, keyStr) {
-    const { instanceId } = ctx;
-    return `${ctx.constructor.name}${instanceId ? `#${instanceId}` : ''}.${keyStr}`;
-}
-/**
- * @returns `NameOfYourClass.methodName`
- */
-export function _getTargetMethodSignature(target, keyStr) {
-    return `${target.constructor.name}.${keyStr}`;
-}
-/**
- * @example
- * e.g for method (a: string, b: string, c: string)
- * returns:
- * a, b, c
- */
-export function _getArgsSignature(args = [], logArgs = true) {
-    if (!logArgs)
-        return '';
-    return args
-        .map(arg => {
-        const s = arg && typeof arg === 'object' ? JSON.stringify(arg) : String(arg);
-        return s.length > 30 ? '...' : s;
-    })
-        .join(', ');
-}

package/dist-esm/decorators/logMethod.decorator.js

@@ -1,85 +0,0 @@
-import { _assert, _stringify, SimpleMovingAverage } from '..';
-import { _ms } from '../time/time.util';
-import { _getArgsSignature, _getMethodSignature } from './decorator.util';
-/**
- * Console-logs when method had started, when it finished, time taken and if error happened.
- * Supports both sync and async methods.
- * Awaits if method returns a Promise.
- *
- * @example output:
- *
- * >> syncMethodSuccess()
- * << syncMethodSuccess() took 124 ms
- *
- * >> asyncMethod()
- * << asyncMethodThrow() took 10 ms ERROR: MyError
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export function _LogMethod(opt = {}) {
-    return (target, key, descriptor) => {
-        _assert(typeof descriptor.value === 'function', '@_LogMethod can be applied only to methods');
-        const originalFn = descriptor.value;
-        const keyStr = String(key);
-        const { avg, logArgs = true, logStart, logResult, logResultLength = true, logger = console, } = opt;
-        let { logResultFn } = opt;
-        if (!logResultFn) {
-            if (logResult) {
-                logResultFn = r => ['result:', _stringify(r)];
-            }
-            else if (logResultLength) {
-                logResultFn = r => (Array.isArray(r) ? [`result: ${r.length} items`] : []);
-            }
-        }
-        const sma = avg ? new SimpleMovingAverage(avg) : undefined;
-        let count = 0;
-        descriptor.value = function (...args) {
-            const started = Date.now();
-            const ctx = this;
-            // e.g `NameOfYourClass.methodName`
-            // or `NameOfYourClass(instanceId).methodName`
-            const methodSignature = _getMethodSignature(ctx, keyStr);
-            const argsStr = _getArgsSignature(args, logArgs);
-            const callSignature = `${methodSignature}(${argsStr}) #${++count}`;
-            if (logStart)
-                logger.log(`>> ${callSignature}`);
-            try {
-                const res = originalFn.apply(ctx, args);
-                if (res && typeof res.then === 'function') {
-                    // Result is a Promise, will wait for resolution or rejection
-                    return res
-                        .then((r) => {
-                        logFinished(logger, callSignature, started, sma, logResultFn, r);
-                        return r;
-                    })
-                        .catch((err) => {
-                        logFinished(logger, callSignature, started, sma, logResultFn, undefined, err);
-                        throw err;
-                    });
-                }
-                // not a Promise
-                logFinished(logger, callSignature, started, sma, logResultFn, res);
-                return res;
-            }
-            catch (err) {
-                logFinished(logger, callSignature, started, sma, logResultFn, undefined, err);
-                throw err; // rethrow
-            }
-        };
-        return descriptor;
-    };
-}
-// eslint-disable-next-line max-params
-function logFinished(logger, callSignature, started, sma, logResultFn, res, err) {
-    const millis = Date.now() - started;
-    const t = ['<<', callSignature, 'took', _ms(millis)];
-    if (sma) {
-        t.push(`(avg ${_ms(sma.pushGetAvg(millis))})`);
-    }
-    if (err !== undefined) {
-        t.push('ERROR:', err);
-    }
-    else if (logResultFn) {
-        t.push(...logResultFn(res));
-    }
-    logger.log(...t.filter(Boolean));
-}

package/dist-esm/decorators/memo.decorator.js

@@ -1,80 +0,0 @@
-import { _assert, _assertTypeOf } from '../error/assert';
-import { _objectAssign } from '../types';
-import { _getTargetMethodSignature } from './decorator.util';
-import { jsonMemoSerializer, MapMemoCache } from './memo.util';
-/**
- * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
- * of the cache is the same. Key, by defaul, is calculated as `JSON.stringify(...args)`.
- * Cache is stored indefinitely in the internal Map.
- *
- * If origin function throws an Error - it is NOT cached.
- * So, error-throwing functions will be called multiple times.
- * Therefor, if the origin function can possibly throw - it should try to be idempotent.
- *
- * Cache is stored **per instance** - separate cache for separate instances of the class.
- * If you don't want it that way - you can use a static method, then there will be only one "instance".
- *
- * Supports dropping it's cache by calling .clear() method of decorated function (useful in unit testing).
- *
- * Based on:
- * https://github.com/mgechev/memo-decorator/blob/master/index.ts
- * http://decodize.com/blog/2012/08/27/javascript-memoization-caching-results-for-better-performance/
- * http://inlehmansterms.net/2015/03/01/javascript-memoization/
- * https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const _Memo = (opt = {}) => (target, key, descriptor) => {
-    _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
-    const originalFn = descriptor.value;
-    // Map<ctx => MemoCache<cacheKey, result>>
-    //
-    // Internal map is from cacheKey to result
-    // External map (instanceCache) is from ctx (instance of class) to Internal map
-    // External map is Weak to not cause memory leaks, to allow ctx objects to be garbage collected
-    // UPD: tests show that normal Map also doesn't leak (to be tested further)
-    // Normal Map is needed to allow .clear()
-    const instanceCache = new Map();
-    const { logger = console, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
-    const keyStr = String(key);
-    const methodSignature = _getTargetMethodSignature(target, keyStr);
-    descriptor.value = function (...args) {
-        const ctx = this;
-        const cacheKey = cacheKeyFn(args);
-        let cache = instanceCache.get(ctx);
-        if (!cache) {
-            cache = cacheFactory();
-            instanceCache.set(ctx, cache);
-        }
-        if (cache.has(cacheKey)) {
-            // Hit
-            return cache.get(cacheKey);
-        }
-        // Miss
-        const value = originalFn.apply(ctx, args);
-        try {
-            cache.set(cacheKey, value);
-        }
-        catch (err) {
-            logger.error(err);
-        }
-        return value;
-    };
-    _objectAssign(descriptor.value, {
-        clear: () => {
-            logger.log(`${methodSignature} @_Memo.clear()`);
-            instanceCache.forEach(memoCache => memoCache.clear());
-            instanceCache.clear();
-        },
-        getInstanceCache: () => instanceCache,
-        getCache: instance => instanceCache.get(instance),
-    });
-    return descriptor;
-};
-/**
- Call it on a method that is decorated with `@_Memo` to get access to additional functions,
- e.g `clear` to clear the cache, or get its underlying data.
- */
-export function _getMemo(method) {
-    _assert(typeof method?.getInstanceCache === 'function', 'method is not a Memo instance');
-    return method;
-}