@naturalcycles/js-lib 14.255.0 → 14.257.0

package/cfg/frontend/tsconfig.json

@@ -0,0 +1,67 @@
+//
+// @naturalcycles/js-lib/cfg/frontend/tsconfig.json
+//
+// Shared tsconfig for Frontend applications
+//
+{
+  "compilerOptions": {
+    // Target/module
+    "target": "es2020", // es2020+ browsers, adjust to your requirements!
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "module": "esnext",
+    "moduleResolution": "node",
+    "moduleDetection": "force",
+    // specifying these explicitly for better IDE compatibility (but they're on by default with module=nodenext)
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    // Faster compilation in general
+    // Support for external compilers (e.g esbuild)
+    // Speedup in Jest by using "isolatedModules" in 'ts-jest' config
+    "isolatedModules": true,
+
+    // Emit
+    "sourceMap": false,
+    "declaration": false,
+    // Otherwise since es2022 it defaults to true
+    // and starts to produce different/unexpected behavior
+    // https://angular.schule/blog/2022-11-use-define-for-class-fields
+    "useDefineForClassFields": false,
+    "importHelpers": true,
+
+    // Strictness
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "suppressImplicitAnyIndexErrors": false,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitOverride": true,
+
+    // Enabled should be faster, but will catch less errors
+    // "skipLibCheck": true,
+
+    // Disabled because of https://github.com/Microsoft/TypeScript/issues/29172
+    // Need to be specified in the project tsconfig
+    // "outDir": "dist",
+    // "rootDir": "./src",
+    //  "baseUrl": "./",
+    //  "paths": {
+    //    "@src/*": ["src/*"]
+    //  },
+    // "typeRoots": [
+    //   "node_modules/@types",
+    //   "src/@types"
+    // ],
+
+    // Other
+    "jsx": "preserve",
+    "pretty": true,
+    "newLine": "lf",
+    "experimentalDecorators": true,
+    // "emitDecoratorMetadata": true // use if needed
+  },
+  // Need to be specified in the project tsconfig
+  // "include": ["src"],
+  // "exclude": ["**/__exclude", "**/@linked"]
+}

package/dist/bot.d.ts

@@ -0,0 +1,60 @@
+export interface BotDetectionServiceCfg {
+    /**
+     * Defaults to false.
+     * If true - the instance will memoize (remember) the results of the detection
+     * and won't re-run it.
+     */
+    memoizeResults?: boolean;
+    /**
+     * Defaults to false.
+     * If set to true: `getBotReason()` would return BotReason.CDP if CDP is detected.
+     * Otherwise - `getBotReason()` will not perform the CDP check.
+     */
+    treatCDPAsBotReason?: boolean;
+}
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export declare class BotDetectionService {
+    cfg: BotDetectionServiceCfg;
+    constructor(cfg?: BotDetectionServiceCfg);
+    private botReason;
+    private cdp;
+    isBotOrCDP(): boolean;
+    isBot(): boolean;
+    /**
+     * Returns null if it's not a Bot,
+     * otherwise a truthy BotReason.
+     */
+    getBotReason(): BotReason | null;
+    private detectBotReason;
+    /**
+     * CDP stands for Chrome DevTools Protocol.
+     * This function tests if the current environment is a CDP environment.
+     * If it's true - it's one of:
+     *
+     * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+     * 2. Developer with Chrome DevTools open.
+     *
+     * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+     * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+     *
+     * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+     */
+    isCDP(): boolean;
+    private detectCDP;
+}
+export declare enum BotReason {
+    NoNavigator = 1,
+    NoUserAgent = 2,
+    UserAgent = 3,
+    WebDriver = 4,
+    EmptyLanguages = 6,
+    /**
+     * This is when CDP is considered to be a reason to be a Bot.
+     * By default it's not.
+     */
+    CDP = 8
+}

package/dist/bot.js

@@ -0,0 +1,129 @@
+"use strict";
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotReason = exports.BotDetectionService = void 0;
+const env_1 = require("./env");
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+class BotDetectionService {
+    constructor(cfg = {}) {
+        this.cfg = cfg;
+    }
+    isBotOrCDP() {
+        return !!this.getBotReason() || this.isCDP();
+    }
+    isBot() {
+        return !!this.getBotReason();
+    }
+    /**
+     * Returns null if it's not a Bot,
+     * otherwise a truthy BotReason.
+     */
+    getBotReason() {
+        if (this.cfg.memoizeResults && this.botReason !== undefined) {
+            return this.botReason;
+        }
+        this.botReason = this.detectBotReason();
+        return this.botReason;
+    }
+    detectBotReason() {
+        // SSR - not a bot
+        if ((0, env_1.isServerSide)())
+            return null;
+        const { navigator } = globalThis;
+        if (!navigator)
+            return BotReason.NoNavigator;
+        const { userAgent } = navigator;
+        if (!userAgent)
+            return BotReason.NoUserAgent;
+        if (/bot|headless|electron|phantom|slimer/i.test(userAgent)) {
+            return BotReason.UserAgent;
+        }
+        if (navigator.webdriver) {
+            return BotReason.WebDriver;
+        }
+        // Kirill: commented out, as it's no longer seems reliable,
+        // e.g generates false positives with latest Android clients (e.g. Chrome 129)
+        // if (navigator.plugins?.length === 0) {
+        //   return BotReason.ZeroPlugins // Headless Chrome
+        // }
+        if (navigator.languages === '') {
+            return BotReason.EmptyLanguages; // Headless Chrome
+        }
+        // isChrome is true if the browser is Chrome, Chromium or Opera
+        // this is "the chrome test" from https://intoli.com/blog/not-possible-to-block-chrome-headless/
+        // this property is for some reason not present by default in headless chrome
+        // Kirill: criterium removed due to false positives with Android
+        // if (userAgent.includes('Chrome') && !(globalThis as any).chrome) {
+        //   return BotReason.ChromeWithoutChrome // Headless Chrome
+        // }
+        if (this.cfg.treatCDPAsBotReason && this.detectCDP()) {
+            return BotReason.CDP;
+        }
+        return null;
+    }
+    /**
+     * CDP stands for Chrome DevTools Protocol.
+     * This function tests if the current environment is a CDP environment.
+     * If it's true - it's one of:
+     *
+     * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+     * 2. Developer with Chrome DevTools open.
+     *
+     * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+     * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+     *
+     * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+     */
+    isCDP() {
+        if (this.cfg.memoizeResults && this.cdp !== undefined) {
+            return this.cdp;
+        }
+        this.cdp = this.detectCDP();
+        return this.cdp;
+    }
+    detectCDP() {
+        if ((0, env_1.isServerSide)())
+            return false;
+        let cdpCheck1 = false;
+        try {
+            /* eslint-disable */
+            // biome-ignore lint/suspicious/useErrorMessage: ok
+            const e = new window.Error();
+            window.Object.defineProperty(e, 'stack', {
+                configurable: false,
+                enumerable: false,
+                // biome-ignore lint/complexity/useArrowFunction: ok
+                get: function () {
+                    cdpCheck1 = true;
+                    return '';
+                },
+            });
+            // This is part of the detection and shouldn't be deleted
+            window.console.debug(e);
+            /* eslint-enable */
+        }
+        catch { }
+        return cdpCheck1;
+    }
+}
+exports.BotDetectionService = BotDetectionService;
+var BotReason;
+(function (BotReason) {
+    BotReason[BotReason["NoNavigator"] = 1] = "NoNavigator";
+    BotReason[BotReason["NoUserAgent"] = 2] = "NoUserAgent";
+    BotReason[BotReason["UserAgent"] = 3] = "UserAgent";
+    BotReason[BotReason["WebDriver"] = 4] = "WebDriver";
+    // ZeroPlugins = 5,
+    BotReason[BotReason["EmptyLanguages"] = 6] = "EmptyLanguages";
+    // ChromeWithoutChrome = 7,
+    /**
+     * This is when CDP is considered to be a reason to be a Bot.
+     * By default it's not.
+     */
+    BotReason[BotReason["CDP"] = 8] = "CDP";
+})(BotReason || (exports.BotReason = BotReason = {}));

package/dist/browser/adminService.d.ts

@@ -0,0 +1,69 @@
+import { Promisable } from '../typeFest';
+export interface AdminModeCfg {
+    /**
+     * Function (predicate) to detect if needed keys are pressed.
+     *
+     * @example
+     * predicate: e => e.ctrlKey && e.key === 'L'
+     *
+     * @default
+     * Detects Ctrl+Shift+L
+     */
+    predicate?: (e: KeyboardEvent) => boolean;
+    /**
+     * Called when RedDot is clicked. Implies that AdminMode is enabled.
+     */
+    onRedDotClick?: () => any;
+    /**
+     * Called when AdminMode was changed.
+     */
+    onChange?: (adminMode: boolean) => any;
+    /**
+     * Called BEFORE entering AdminMode.
+     * Serves as a predicate that can cancel entering AdminMode if false is returned.
+     * Return true to allow.
+     * Function is awaited before proceeding.
+     */
+    beforeEnter?: () => Promisable<boolean>;
+    /**
+     * Called BEFORE exiting AdminMode.
+     * Serves as a predicate that can cancel exiting AdminMode if false is returned.
+     * Return true to allow.
+     * Function is awaited before proceeding.
+     */
+    beforeExit?: () => Promisable<boolean>;
+    /**
+     * @default true
+     * If true - it will "persist" the adminMode state in LocalStorage
+     */
+    persistToLocalStorage?: boolean;
+    /**
+     * The key for LocalStorage persistence.
+     *
+     * @default '__adminMode__'
+     */
+    localStorageKey?: string;
+}
+/**
+ * @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 declare class AdminService {
+    constructor(cfg?: AdminModeCfg);
+    cfg: Required<AdminModeCfg>;
+    adminMode: boolean;
+    private listening;
+    /**
+     * Start listening to keyboard events to toggle AdminMode when detected.
+     */
+    startListening(): void;
+    stopListening(): void;
+    private keydownListener;
+    toggleRedDot(): Promise<void>;
+    private toggleRedDotVisibility;
+    private getRedDotElement;
+}

package/dist/browser/adminService.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminService = void 0;
+const tslib_1 = require("tslib");
+const memo_decorator_1 = require("../decorators/memo.decorator");
+const env_1 = require("../env");
+const stringify_1 = require("../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
+ */
+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 || (0, env_1.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 ((0, env_1.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((0, stringify_1._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;
+    }
+}
+exports.AdminService = AdminService;
+tslib_1.__decorate([
+    (0, memo_decorator_1._Memo)()
+], AdminService.prototype, "getRedDotElement", null);

package/dist/browser/analytics.util.d.ts

@@ -0,0 +1,12 @@
+declare global {
+    interface Window {
+        dataLayer: any[];
+        gtag: (...args: any[]) => void;
+    }
+}
+/**
+ * Pass enabled = false to only init window.gtag, but not load actual gtag script (e.g in dev mode).
+ */
+export declare function loadGTag(gtagId: string, enabled?: boolean): Promise<void>;
+export declare function loadGTM(gtmId: string, enabled?: boolean): Promise<void>;
+export declare function loadHotjar(hjid: number): void;

package/dist/browser/analytics.util.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGTag = loadGTag;
+exports.loadGTM = loadGTM;
+exports.loadHotjar = loadHotjar;
+const js_lib_1 = require("@naturalcycles/js-lib");
+const script_util_1 = require("./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).
+ */
+async function loadGTag(gtagId, enabled = true) {
+    if ((0, js_lib_1.isServerSide)())
+        return;
+    window.dataLayer ||= [];
+    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 (0, script_util_1.loadScript)(`https://www.googletagmanager.com/gtag/js?id=${gtagId}`);
+}
+async function loadGTM(gtmId, enabled = true) {
+    if ((0, js_lib_1.isServerSide)())
+        return;
+    window.dataLayer ||= [];
+    window.dataLayer.push({
+        'gtm.start': Date.now(),
+        event: 'gtm.js',
+    });
+    if (!enabled)
+        return;
+    await (0, script_util_1.loadScript)(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`);
+}
+function loadHotjar(hjid) {
+    if ((0, js_lib_1.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/browser/i18n/fetchTranslationLoader.d.ts

@@ -0,0 +1,13 @@
+import { Fetcher } from '../../http/fetcher';
+import { StringMap } from '../../types';
+import { TranslationLoader } from './translation.service';
+/**
+ * Use `baseUrl` to prefix your language files.
+ * Example URL structure:
+ * ${baseUrl}/${locale}.json
+ */
+export declare class FetchTranslationLoader implements TranslationLoader {
+    fetcher: Fetcher;
+    constructor(fetcher: Fetcher);
+    load(locale: string): Promise<StringMap>;
+}

package/dist/browser/i18n/fetchTranslationLoader.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchTranslationLoader = void 0;
+/**
+ * Use `baseUrl` to prefix your language files.
+ * Example URL structure:
+ * ${baseUrl}/${locale}.json
+ */
+class FetchTranslationLoader {
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    async load(locale) {
+        return await this.fetcher.get(`${locale}.json`);
+    }
+}
+exports.FetchTranslationLoader = FetchTranslationLoader;

package/dist/browser/i18n/translation.service.d.ts

@@ -0,0 +1,53 @@
+import { StringMap } from '../../types';
+export type MissingTranslationHandler = (key: string, params?: StringMap<any>) => string;
+export declare const defaultMissingTranslationHandler: MissingTranslationHandler;
+export interface TranslationServiceCfg {
+    defaultLocale: string;
+    supportedLocales: string[];
+    /**
+     * It is allowed to set it later. Will default to `defaultLocale` in that case.
+     */
+    currentLocale?: string;
+    translationLoader: TranslationLoader;
+    /**
+     * Defaults to `defaultMissingTranslationHandler` that returns `[${key}]` and emits console warning.
+     */
+    missingTranslationHandler?: MissingTranslationHandler;
+}
+export interface TranslationServiceCfgComplete extends TranslationServiceCfg {
+    missingTranslationHandler: MissingTranslationHandler;
+}
+export interface TranslationLoader {
+    load: (locale: string) => Promise<StringMap>;
+}
+export declare class TranslationService {
+    constructor(cfg: TranslationServiceCfg, preloadedLocales?: StringMap<StringMap>);
+    cfg: TranslationServiceCfgComplete;
+    /**
+     * Cache of loaded locales
+     */
+    locales: StringMap<StringMap>;
+    currentLocale: string;
+    /**
+     * Manually set locale data, bypassing the TranslationLoader.
+     */
+    setLocale(localeName: string, locale: StringMap): void;
+    getLocale(locale: string): StringMap | undefined;
+    /**
+     * Loads locale(s) (if not already cached) via configured TranslationLoader.
+     * Resolves promise when done (ready to be used).
+     */
+    loadLocale(locale: string | string[]): Promise<void>;
+    /**
+     * 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: string, params?: StringMap): string;
+    /**
+     * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+     */
+    translateIfExists(key: string, _params?: StringMap): string | undefined;
+}

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

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslationService = exports.defaultMissingTranslationHandler = void 0;
+const pMap_1 = require("../../promise/pMap");
+const defaultMissingTranslationHandler = key => {
+    console.warn(`[tr] missing: ${key}`);
+    return `[${key}]`;
+};
+exports.defaultMissingTranslationHandler = defaultMissingTranslationHandler;
+class TranslationService {
+    constructor(cfg, preloadedLocales = {}) {
+        this.cfg = {
+            ...cfg,
+            missingTranslationHandler: exports.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 (0, pMap_1.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];
+    }
+}
+exports.TranslationService = TranslationService;