@naturalcycles/js-lib 14.256.0 → 14.258.0

package/dist/nanoid.js

@@ -0,0 +1,61 @@
+"use strict";
+// Vendored from https://github.com/ai/nanoid/blob/main/index.browser.js
+// All credit to nanoid authors: https://github.com/ai/nanoid
+// Reason for vendoring: (still) cannot import esm, and Nanoid went ESM-only since 4.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nanoidBrowser = nanoidBrowser;
+exports.nanoidBrowserCustomAlphabet = nanoidBrowserCustomAlphabet;
+/// <reference lib="dom" preserve="true" />
+/* eslint-disable no-bitwise */
+// "0-9a-zA-Z-_", same as base64url alphabet
+const urlAlphabet = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+function nanoidBrowser(length = 21) {
+    let id = '';
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(length));
+    while (length--) {
+        // Using the bitwise AND operator to "cap" the value of
+        // the random byte from 255 to 63, in that way we can make sure
+        // that the value will be a valid index for the "chars" string.
+        id += urlAlphabet[bytes[length] & 63];
+    }
+    return id;
+}
+const defaultRandomFunction = (bytes) => globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+function nanoidBrowserCustomAlphabet(alphabet, length = 21) {
+    return customRandom(alphabet, length, defaultRandomFunction);
+}
+function customRandom(alphabet, defaultSize, getRandom) {
+    // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+    // values closer to the alphabet size. The bitmask calculates the closest
+    // `2^31 - 1` number, which exceeds the alphabet size.
+    // For example, the bitmask for the alphabet size 30 is 31 (00011111).
+    // `Math.clz32` is not used, because it is not available in browsers.
+    const mask = (2 << Math.log2(alphabet.length - 1)) - 1;
+    // Though, the bitmask solution is not perfect since the bytes exceeding
+    // the alphabet size are refused. Therefore, to reliably generate the ID,
+    // the random bytes redundancy has to be satisfied.
+    // Note: every hardware random generator call is performance expensive,
+    // because the system call for entropy collection takes a lot of time.
+    // So, to avoid additional system calls, extra bytes are requested in advance.
+    // Next, a step determines how many random bytes to generate.
+    // The number of random bytes gets decided upon the ID size, mask,
+    // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+    // according to benchmarks).
+    // `-~f => Math.ceil(f)` if f is a float
+    // `-~i => i + 1` if i is an integer
+    const step = -~((1.6 * mask * defaultSize) / alphabet.length);
+    return (size = defaultSize) => {
+        let id = '';
+        while (true) {
+            const bytes = getRandom(step);
+            // A compact alternative for `for (var i = 0; i < step; i++)`.
+            let j = step;
+            while (j--) {
+                // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
+                id += alphabet[bytes[j] & mask] || '';
+                if (id.length === size)
+                    return id;
+            }
+        }
+    };
+}

package/dist/number/createDeterministicRandom.d.ts

@@ -1,6 +1,11 @@
+/**
+ * Function that returns a random number between 0 and 1.
+ * Exactly same signature as Math.random function.
+ */
+export type RandomFunction = () => number;
 /**
  * Returns a "deterministic Math.random() function"
  *
  * Based on: https://gist.github.com/mathiasbynens/5670917
  */
-export declare function _createDeterministicRandom(): () => number;
+export declare function _createDeterministicRandom(seed?: number): RandomFunction;

package/dist/number/createDeterministicRandom.js

@@ -7,8 +7,7 @@ exports._createDeterministicRandom = _createDeterministicRandom;
  *
  * Based on: https://gist.github.com/mathiasbynens/5670917
  */
-function _createDeterministicRandom() {
-    let seed = 0x2f6e2b1;
+function _createDeterministicRandom(seed = 0x2f6e2b1) {
     return () => {
         // Robert Jenkins’ 32 bit integer hash function
         seed = (seed + 0x7ed55d16 + (seed << 12)) & 0xffffffff;

package/dist/string/hash.util.d.ts

@@ -6,7 +6,7 @@ import { Integer } from '../types';
  *
  * 1. Performance
  * 2. For non-cryptographic use (where accidental collision is not the end-of-the-world)
- * 3. Compact size (32 bits max, versus 128 in md5; presented in less string json-safe characters)
+ * 3. Compact size (32 bits max, versus 128 in md5; presented in smaller number of string json-safe characters)
  *
  * Basically, these functions are as simple as they can be, but still "random enough" for
  * normal non-cryptographic use cases.

package/dist/string/hash.util.js

@@ -14,7 +14,7 @@ const BASE64URL = BASE62 + '-_';
  *
  * 1. Performance
  * 2. For non-cryptographic use (where accidental collision is not the end-of-the-world)
- * 3. Compact size (32 bits max, versus 128 in md5; presented in less string json-safe characters)
+ * 3. Compact size (32 bits max, versus 128 in md5; presented in smaller number of string json-safe characters)
  *
  * Basically, these functions are as simple as they can be, but still "random enough" for
  * normal non-cryptographic use cases.

package/dist/web.d.ts

@@ -5,6 +5,12 @@ import { StringMap } from './types';
  * Implements WebStorage API by using in-memory storage.
  * Can be useful in SSR environment or unit tests.
  *
+ * This is how localStorage can be mocked in Node:
+ *
+ * Object.assign(globalThis, {
+ *  localStorage: new InMemoryWebStorage(),
+ * })
+ *
  * @experimental
  */
 export declare class InMemoryWebStorage implements Storage {

package/dist/web.js

@@ -7,6 +7,12 @@ exports.InMemoryWebStorage = void 0;
  * Implements WebStorage API by using in-memory storage.
  * Can be useful in SSR environment or unit tests.
  *
+ * This is how localStorage can be mocked in Node:
+ *
+ * Object.assign(globalThis, {
+ *  localStorage: new InMemoryWebStorage(),
+ * })
+ *
  * @experimental
  */
 class InMemoryWebStorage {

package/dist/zod/zod.util.d.ts

@@ -1,4 +1,4 @@
-import { ZodError, ZodIssue, ZodSchema } from 'zod';
+import { ZodError, type ZodIssue, type ZodSchema } from 'zod';
 export interface ZodErrorResult<T> {
     success: false;
     data?: T;

package/dist-esm/browser/adminService.js

@@ -0,0 +1,94 @@
+import { __decorate } from "tslib";
+import { _Memo } from '../decorators/memo.decorator';
+import { isServerSide } from '../env';
+import { _stringify } from '../string/stringify';
+const RED_DOT_ID = '__red-dot__';
+const NOOP = () => { };
+/**
+ * @experimental
+ *
+ * Allows to listen for AdminMode keypress combination (Ctrl+Shift+L by default) to toggle AdminMode,
+ * indicated by RedDot DOM element.
+ *
+ * todo: help with Authentication
+ */
+export class AdminService {
+    constructor(cfg) {
+        this.adminMode = false;
+        this.listening = false;
+        this.cfg = {
+            predicate: e => e.ctrlKey && e.key === 'L',
+            persistToLocalStorage: true,
+            localStorageKey: '__adminMode__',
+            onRedDotClick: NOOP,
+            onChange: NOOP,
+            beforeEnter: () => true,
+            beforeExit: () => true,
+            ...cfg,
+        };
+    }
+    /**
+     * Start listening to keyboard events to toggle AdminMode when detected.
+     */
+    startListening() {
+        if (this.listening || isServerSide())
+            return;
+        this.adminMode = !!localStorage.getItem(this.cfg.localStorageKey);
+        if (this.adminMode)
+            this.toggleRedDotVisibility();
+        document.addEventListener('keydown', this.keydownListener.bind(this), { passive: true });
+        this.listening = true;
+    }
+    stopListening() {
+        if (isServerSide())
+            return;
+        document.removeEventListener('keydown', this.keydownListener);
+        this.listening = false;
+    }
+    async keydownListener(e) {
+        // console.log(e)
+        if (!this.cfg.predicate(e))
+            return;
+        await this.toggleRedDot();
+    }
+    async toggleRedDot() {
+        try {
+            const allow = await this.cfg[this.adminMode ? 'beforeExit' : 'beforeEnter']();
+            if (!allow)
+                return; // no change
+        }
+        catch (err) {
+            console.error(err);
+            // ok to show alert to Admins, it's not user-facing
+            alert(_stringify(err));
+            return; // treat as "not allowed"
+        }
+        this.adminMode = !this.adminMode;
+        this.toggleRedDotVisibility();
+        if (this.cfg.persistToLocalStorage) {
+            const { localStorageKey } = this.cfg;
+            if (this.adminMode) {
+                localStorage.setItem(localStorageKey, '1');
+            }
+            else {
+                localStorage.removeItem(localStorageKey);
+            }
+        }
+        this.cfg.onChange(this.adminMode);
+    }
+    toggleRedDotVisibility() {
+        this.getRedDotElement().style.display = this.adminMode ? 'block' : 'none';
+    }
+    getRedDotElement() {
+        const el = document.createElement('div');
+        el.id = RED_DOT_ID;
+        el.style.cssText =
+            'position:fixed;width:24px;height:24px;margin-top:-12px;background-color:red;opacity:0.5;top:50%;left:0;z-index:9999999;cursor:pointer;border-radius:0 3px 3px 0';
+        el.addEventListener('click', () => this.cfg.onRedDotClick());
+        document.body.append(el);
+        return el;
+    }
+}
+__decorate([
+    _Memo()
+], AdminService.prototype, "getRedDotElement", null);

package/dist-esm/browser/analytics.util.js

@@ -0,0 +1,54 @@
+import { isServerSide } from '@naturalcycles/js-lib';
+import { loadScript } from './script.util';
+/* eslint-disable unicorn/prefer-global-this */
+/**
+ * Pass enabled = false to only init window.gtag, but not load actual gtag script (e.g in dev mode).
+ */
+export async function loadGTag(gtagId, enabled = true) {
+    if (isServerSide())
+        return;
+    window.dataLayer || (window.dataLayer = []);
+    window.gtag || (window.gtag = function gtag() {
+        // biome-ignore lint/complexity/useArrowFunction: ok
+        // biome-ignore lint/style/noArguments: ok
+        window.dataLayer.push(arguments);
+    });
+    window.gtag('js', new Date());
+    window.gtag('config', gtagId);
+    if (!enabled)
+        return;
+    await loadScript(`https://www.googletagmanager.com/gtag/js?id=${gtagId}`);
+}
+export async function loadGTM(gtmId, enabled = true) {
+    if (isServerSide())
+        return;
+    window.dataLayer || (window.dataLayer = []);
+    window.dataLayer.push({
+        'gtm.start': Date.now(),
+        event: 'gtm.js',
+    });
+    if (!enabled)
+        return;
+    await loadScript(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`);
+}
+export function loadHotjar(hjid) {
+    if (isServerSide())
+        return;
+    ;
+    ((h, o, t, j, a, r) => {
+        h.hj =
+            h.hj ||
+                function hj() {
+                    // biome-ignore lint/style/noArguments: ok
+                    ;
+                    (h.hj.q = h.hj.q || []).push(arguments);
+                };
+        h._hjSettings = { hjid, hjsv: 6 };
+        a = o.querySelectorAll('head')[0];
+        r = o.createElement('script');
+        r.async = 1;
+        r.src = t + h._hjSettings.hjid + j + h._hjSettings.hjsv;
+        a.append(r);
+    })(window, document, 'https://static.hotjar.com/c/hotjar-', '.js?sv=');
+    /* eslint-enable */
+}

package/dist-esm/browser/i18n/fetchTranslationLoader.js

@@ -0,0 +1,13 @@
+/**
+ * Use `baseUrl` to prefix your language files.
+ * Example URL structure:
+ * ${baseUrl}/${locale}.json
+ */
+export class FetchTranslationLoader {
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    async load(locale) {
+        return await this.fetcher.get(`${locale}.json`);
+    }
+}

package/dist-esm/browser/i18n/translation.service.js

@@ -0,0 +1,56 @@
+import { pMap } from '../../promise/pMap';
+export const defaultMissingTranslationHandler = key => {
+    console.warn(`[tr] missing: ${key}`);
+    return `[${key}]`;
+};
+export class TranslationService {
+    constructor(cfg, preloadedLocales = {}) {
+        this.cfg = {
+            ...cfg,
+            missingTranslationHandler: defaultMissingTranslationHandler,
+        };
+        this.locales = {
+            ...preloadedLocales,
+        };
+        this.currentLocale = cfg.currentLocale || cfg.defaultLocale;
+    }
+    /**
+     * Manually set locale data, bypassing the TranslationLoader.
+     */
+    setLocale(localeName, locale) {
+        this.locales[localeName] = locale;
+    }
+    getLocale(locale) {
+        return this.locales[locale];
+    }
+    /**
+     * Loads locale(s) (if not already cached) via configured TranslationLoader.
+     * Resolves promise when done (ready to be used).
+     */
+    async loadLocale(locale) {
+        const locales = Array.isArray(locale) ? locale : [locale];
+        await pMap(locales, async (locale) => {
+            if (this.locales[locale])
+                return; // already loaded
+            this.locales[locale] = await this.cfg.translationLoader.load(locale);
+            // console.log(`[tr] locale loaded: ${locale}`)
+        });
+    }
+    /**
+     * Will invoke `missingTranslationHandler` on missing tranlation.
+     *
+     * Does NOT do any locale loading. The locale needs to be loaded beforehand:
+     * either pre-loaded and passed to the constructor,
+     * or `await loadLocale(locale)`.
+     */
+    translate(key, params) {
+        return this.translateIfExists(key, params) || this.cfg.missingTranslationHandler(key, params);
+    }
+    /**
+     * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+     */
+    translateIfExists(key, _params) {
+        // todo: support params
+        return this.locales[this.currentLocale]?.[key] || this.locales[this.cfg.defaultLocale]?.[key];
+    }
+}

package/dist-esm/browser/imageFitter.js

@@ -0,0 +1,65 @@
+/**
+ * Calculates the width/height of the images to fit in the layout.
+ *
+ * Currently does not mutate the cfg.images array, but DOES mutate individual images with .fitWidth, .fitHeight properties.
+ *
+ * @experimental
+ */
+export class ImageFitter {
+    constructor(cfg) {
+        this.containerWidth = -1;
+        this.cfg = {
+            maxHeight: 300,
+            margin: 8,
+            ...cfg,
+        };
+        this.resizeObserver = new ResizeObserver(entries => this.update(entries));
+        this.resizeObserver.observe(cfg.containerElement);
+    }
+    stop() {
+        this.resizeObserver.disconnect();
+    }
+    update(entries) {
+        const width = Math.floor(entries[0].contentRect.width);
+        if (width === this.containerWidth)
+            return; // we're only interested in width changes
+        this.containerWidth = width;
+        console.log(`resize ${width}`);
+        this.doLayout(this.cfg.images);
+        this.cfg.onChange(this.cfg.images);
+    }
+    doLayout(imgs) {
+        if (imgs.length === 0)
+            return; // nothing to do
+        const { maxHeight } = this.cfg;
+        let imgNodes = imgs.slice(0);
+        w: while (imgNodes.length > 0) {
+            let slice;
+            let h;
+            for (let i = 1; i <= imgNodes.length; i++) {
+                slice = imgNodes.slice(0, i);
+                h = this.getHeigth(slice);
+                if (h < maxHeight) {
+                    this.setHeight(slice, h);
+                    imgNodes = imgNodes.slice(i);
+                    continue w;
+                }
+            }
+            this.setHeight(slice, Math.min(maxHeight, h));
+            break;
+        }
+    }
+    getHeigth(images) {
+        const width = this.containerWidth - images.length * this.cfg.margin;
+        let r = 0;
+        images.forEach(img => (r += img.aspectRatio));
+        return width / r; // have to round down because Firefox will automatically roundup value with number of decimals > 3
+    }
+    // mutates/sets images' fitWidth, fitHeight properties
+    setHeight(images, height) {
+        images.forEach(img => {
+            img.fitWidth = Math.floor(height * img.aspectRatio);
+            img.fitHeight = Math.floor(height);
+        });
+    }
+}

package/dist-esm/browser/script.util.js

@@ -0,0 +1,46 @@
+import { isServerSide } from '../env';
+import { _objectAssign } from '../types';
+/**
+ * opt.async defaults to `true`.
+ * No other options are set by default.
+ */
+export async function loadScript(src, opt) {
+    if (isServerSide())
+        return;
+    return await new Promise((resolve, reject) => {
+        const s = _objectAssign(document.createElement('script'), {
+            src,
+            async: true,
+            ...opt,
+            onload: resolve,
+            onerror: (_event, _source, _lineno, _colno, err) => {
+                reject(err || new Error(`loadScript failed: ${src}`));
+            },
+        });
+        document.head.append(s);
+    });
+}
+/**
+ * Default options:
+ * rel: 'stylesheet'
+ *
+ * No other options are set by default.
+ */
+export async function loadCSS(href, opt) {
+    if (isServerSide())
+        return;
+    return await new Promise((resolve, reject) => {
+        const link = _objectAssign(document.createElement('link'), {
+            href,
+            rel: 'stylesheet',
+            // type seems to be unnecessary: https://stackoverflow.com/a/5409146/4919972
+            // type: 'text/css',
+            ...opt,
+            onload: resolve,
+            onerror: (_event, _source, _lineno, _colno, err) => {
+                reject(err || new Error(`loadCSS failed: ${href}`));
+            },
+        });
+        document.head.append(link);
+    });
+}

package/dist-esm/browser/topbar.js

@@ -0,0 +1,134 @@
+// Modified version of topbar:
+// http://buunguyen.github.io/topbar
+/* eslint-disable */
+const browser = typeof window !== 'undefined';
+let canvas;
+let progressTimerId;
+let fadeTimerId;
+let currentProgress;
+let showing;
+const addEvent = (elem, type, handler) => {
+    if (elem.addEventListener)
+        elem.addEventListener(type, handler, false);
+    else if (elem.attachEvent)
+        elem.attachEvent('on' + type, handler);
+    else
+        elem['on' + type] = handler;
+};
+const options = {
+    autoRun: true,
+    barThickness: 5,
+    barColors: {
+        '0': 'rgba(26,  188, 156, .9)',
+        '.25': 'rgba(52,  152, 219, .9)',
+        '.50': 'rgba(241, 196, 15,  .9)',
+        '.75': 'rgba(230, 126, 34,  .9)',
+        '1.0': 'rgba(211, 84,  0,   .9)',
+    },
+    shadowBlur: 10,
+    shadowColor: 'rgba(0,   0,   0,   .6)',
+};
+const repaint = () => {
+    canvas.width = window.innerWidth;
+    canvas.height = options.barThickness * 5; // need space for shadow
+    const ctx = canvas.getContext('2d');
+    ctx.shadowBlur = options.shadowBlur;
+    ctx.shadowColor = options.shadowColor;
+    const lineGradient = ctx.createLinearGradient(0, 0, canvas.width, 0);
+    for (const stop in options.barColors) {
+        // @ts-ignore
+        lineGradient.addColorStop(stop, options.barColors[stop]);
+    }
+    ctx.lineWidth = options.barThickness;
+    ctx.beginPath();
+    ctx.moveTo(0, options.barThickness / 2);
+    ctx.lineTo(Math.ceil(currentProgress * canvas.width), options.barThickness / 2);
+    ctx.strokeStyle = lineGradient;
+    ctx.stroke();
+};
+const createCanvas = () => {
+    canvas = document.createElement('canvas');
+    const style = canvas.style;
+    style.position = 'fixed';
+    style.top = style.left = style.right = style.margin = style.padding = 0;
+    style.zIndex = 100001;
+    style.display = 'none';
+    document.body.appendChild(canvas);
+    addEvent(window, 'resize', repaint);
+};
+export const topbar = {
+    config(opts) {
+        for (const key in opts) {
+            if (options.hasOwnProperty(key)) {
+                // @ts-ignore
+                options[key] = opts[key];
+            }
+        }
+    },
+    set(show, opts) {
+        if (show) {
+            topbar.show(opts);
+        }
+        else {
+            topbar.hide();
+        }
+    },
+    show(opts) {
+        if (!browser)
+            return; // ssr protection
+        if (opts)
+            topbar.config(opts);
+        if (showing)
+            return;
+        showing = true;
+        if (fadeTimerId !== null) {
+            window.cancelAnimationFrame(fadeTimerId);
+        }
+        if (!canvas)
+            createCanvas();
+        canvas.style.opacity = 1;
+        canvas.style.display = 'block';
+        topbar.progress(0);
+        if (options.autoRun) {
+            ;
+            (function loop() {
+                progressTimerId = window.requestAnimationFrame(loop);
+                topbar.progress('+' + 0.05 * (1 - Math.sqrt(currentProgress)) ** 2);
+            })();
+        }
+    },
+    progress(to) {
+        if (!browser)
+            return; // ssr protection
+        if (typeof to === 'undefined') {
+            return currentProgress;
+        }
+        if (typeof to === 'string') {
+            to = (to.indexOf('+') >= 0 || to.indexOf('-') >= 0 ? currentProgress : 0) + parseFloat(to);
+        }
+        currentProgress = to > 1 ? 1 : to;
+        repaint();
+        return currentProgress;
+    },
+    hide() {
+        if (!showing || !browser)
+            return;
+        showing = false;
+        if (progressTimerId != null) {
+            window.cancelAnimationFrame(progressTimerId);
+            progressTimerId = null;
+        }
+        ;
+        (function loop() {
+            if (topbar.progress('+.1') >= 1) {
+                canvas.style.opacity -= 0.05;
+                if (canvas.style.opacity <= 0.05) {
+                    canvas.style.display = 'none';
+                    fadeTimerId = null;
+                    return;
+                }
+            }
+            fadeTimerId = window.requestAnimationFrame(loop);
+        })();
+    },
+};

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

@@ -1,4 +1,6 @@
-import { _isPrimitive, MISS, pDelay } from '..';
+import { _isPrimitive } from '../is.util';
+import { pDelay } from '../promise/pDelay';
+import { MISS } from '../types';
 export const jsonMemoSerializer = args => {
     if (args.length === 0)
         return undefined;

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

@@ -0,0 +1,38 @@
+import { _getTargetMethodSignature } from './decorator.util';
+/**
+ * Prevents "swarm" of async calls to the same method.
+ * Allows max 1 in-flight promise to exist.
+ * If more calls appear, while Promise is not resolved yet - same Promise is returned.
+ *
+ * Does not support `cacheKey`.
+ * So, the same Promise is returned, regardless of the arguments.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const _SwarmSafe = () => (target, key, descriptor) => {
+    if (typeof descriptor.value !== 'function') {
+        throw new TypeError('@_SwarmSafe can be applied only to methods');
+    }
+    const originalFn = descriptor.value;
+    const keyStr = String(key);
+    const methodSignature = _getTargetMethodSignature(target, keyStr);
+    const instanceCache = new Map();
+    console.log('SwarmSafe constructor called', { key, methodSignature });
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    descriptor.value = function (...args) {
+        console.log('SwarmSafe method called', { key, methodSignature, args });
+        const ctx = this;
+        let inFlightPromise = instanceCache.get(ctx);
+        if (inFlightPromise) {
+            console.log(`SwarmSafe: returning in-flight promise`);
+            return inFlightPromise;
+        }
+        console.log(`SwarmSafe: first-time call, creating in-flight promise`);
+        inFlightPromise = originalFn.apply(ctx, args);
+        instanceCache.set(ctx, inFlightPromise);
+        void inFlightPromise.finally(() => {
+            console.log(`SwarmSafe: in-flight promise resolved`);
+            instanceCache.delete(ctx);
+        });
+        return inFlightPromise;
+    };
+};