@naturalcycles/js-lib 14.256.0 → 14.258.0

package/dist-esm/deviceIdService.js

@@ -0,0 +1,105 @@
+/// <reference lib="dom" preserve="true" />
+import { isServerSide } from './env';
+import { nanoidBrowser } from './nanoid';
+import { hashCode } from './string/hash.util';
+// This is in sync with the default length in Nanoid.
+const deviceIdLength = 21;
+/**
+ * Service to generate, maintain, persist a stable "device id".
+ *
+ * It's called "device id" and not userId/visitorId, to indicate that it only identifies a device,
+ * and has nothing to do with user identification.
+ * User might be logged in or not.
+ * User id can be the same on multiple devices.
+ * DeviceId is unique per device, same User or not.
+ *
+ * Service provides methods to deterministically select fraction of devices.
+ * For example, select 10% of devices that visit the website to be tracked by Analytics
+ * (to reduce Analytics quota usage).
+ * DeviceId persistence will ensure that recurring visits from the same device will yield the same
+ * DeviceId, and same "selection assignment" (like an assignment in an AB test).
+ *
+ * @experimental
+ */
+export class DeviceIdService {
+    constructor(cfg = {}) {
+        this.cfg = {
+            localStorageKey: 'deviceId',
+            debug: false,
+            ...cfg,
+        };
+        this.init();
+    }
+    /**
+     * Selects this device based on "deterministic random selection", according to the defined `rate`.
+     * Rate is a floating number between 0 and 1.
+     * E.g rate of 0.1 means 10% chance of being selected.
+     *
+     * Selection is based on deviceId, which is generated random and persisted between visits.
+     * Persistence ensures that the selection (similar to an AB-test assignment) "sticks" to the device.
+     *
+     * If deviceId failed to be generated, e.g due to Device running out-of-space to save a string to localStorage,
+     * it will NOT be selected.
+     *
+     * @returns true if the device is selected.
+     */
+    select(rate) {
+        if (!this.deviceId) {
+            this.debug(`deviceId is null, skipping selection`);
+            return false;
+        }
+        const mod = Math.trunc(rate * 1000);
+        // console.log('hash: ', hashCode(this.deviceId)) // todo
+        return hashCode(this.deviceId) % 1000 < mod;
+    }
+    /**
+     * Deletes the persisted deviceId.
+     * Keeps it in the service.
+     * To remove it from the service, assign deviceIdService.deviceId = null.
+     */
+    clearPersistence() {
+        try {
+            globalThis.localStorage.removeItem(this.cfg.localStorageKey);
+        }
+        catch (err) {
+            console.log(err);
+        }
+    }
+    /**
+     * Generates a stable Device id if it wasn't previously generated on this device.
+     * Otherwise, reads a Device id from persistent storage.
+     */
+    init() {
+        this.deviceId = null;
+        if (isServerSide())
+            return;
+        try {
+            this.deviceId = globalThis.localStorage.getItem(this.cfg.localStorageKey);
+            if (this.deviceId)
+                this.debug(`loaded deviceId: ${this.deviceId}`);
+        }
+        catch (err) {
+            console.log(err);
+            this.deviceId = null;
+        }
+        if (this.deviceId && this.deviceId.length !== deviceIdLength) {
+            console.warn(`[DeviceIdService] unexpected deviceIdLength (${this.deviceId.length}), will re-generate the id`, { deviceId: this.deviceId });
+            this.deviceId = null;
+        }
+        if (!this.deviceId) {
+            try {
+                this.deviceId = nanoidBrowser(deviceIdLength);
+                this.debug(`generated new deviceId: ${this.deviceId}`);
+                globalThis.localStorage.setItem(this.cfg.localStorageKey, this.deviceId);
+            }
+            catch (err) {
+                console.log(err);
+                this.deviceId = null;
+            }
+        }
+    }
+    debug(...args) {
+        if (this.cfg.debug)
+            console.log('[DeviceIdService]', ...args);
+    }
+}

package/dist-esm/error/assert.js

@@ -1,4 +1,6 @@
-import { _deepEquals, _isBackendErrorResponseObject, _isErrorObject, _stringify, AssertionError, } from '..';
+import { _deepEquals } from '../object/deepEquals';
+import { _stringify } from '../string/stringify';
+import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util';
 /**
  * Evaluates the `condition` (casts it to Boolean).
  * Expects it to be truthy, otherwise throws AppError.

package/dist-esm/error/error.util.js

@@ -1,4 +1,7 @@
-import { _jsonParseIfPossible, _stringify, _truncate, _truncateMiddle, isServerSide } from '..';
+import { isServerSide } from '../env';
+import { _jsonParseIfPossible } from '../string/json.util';
+import { _truncate, _truncateMiddle } from '../string/string.util';
+import { _stringify } from '../string/stringify';
 /**
  * Useful to ensure that error in `catch (err) { ... }`
  * is indeed an Error (and not e.g `string` or `undefined`).

package/dist-esm/index.js

@@ -2,6 +2,13 @@ export * from './abort';
 export * from './array/array.util';
 export * from './array/range';
 export * from './bot';
+export * from './browser/adminService';
+export * from './browser/analytics.util';
+export * from './browser/i18n/fetchTranslationLoader';
+export * from './browser/i18n/translation.service';
+export * from './browser/imageFitter';
+export * from './browser/script.util';
+export * from './browser/topbar';
 export * from './datetime/dateInterval';
 export * from './datetime/localDate';
 export * from './datetime/localTime';
@@ -20,6 +27,7 @@ export * from './decorators/memoFnAsync';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
 export * from './define';
+export * from './deviceIdService';
 export * from './enum.util';
 export * from './env';
 export * from './env/buildInfo';
@@ -45,6 +53,7 @@ export * from './log/commonLogger';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './math/stack.util';
+export * from './nanoid';
 export * from './number/createDeterministicRandom';
 export * from './number/number.util';
 export * from './object/deepEquals';

package/dist-esm/nanoid.js

@@ -0,0 +1,57 @@
+// 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
+/// <reference lib="dom" preserve="true" />
+/* eslint-disable no-bitwise */
+// "0-9a-zA-Z-_", same as base64url alphabet
+const urlAlphabet = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+export 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));
+export 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-esm/number/createDeterministicRandom.js

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

package/dist-esm/string/hash.util.js

@@ -8,7 +8,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-esm/web.js

@@ -4,6 +4,12 @@
  * 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 class InMemoryWebStorage {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.256.0",
+  "version": "14.258.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",
@@ -36,6 +36,7 @@
   "files": [
     "dist",
     "dist-esm",
+    "cfg",
     "src",
     "!src/test",
     "!src/**/*.test.*",

package/src/browser/adminService.ts

@@ -0,0 +1,157 @@
+import { _Memo } from '../decorators/memo.decorator'
+import { isServerSide } from '../env'
+import { _stringify } from '../string/stringify'
+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
+}
+
+const RED_DOT_ID = '__red-dot__'
+const NOOP = (): void => {}
+
+/**
+ * @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?: AdminModeCfg) {
+    this.cfg = {
+      predicate: e => e.ctrlKey && e.key === 'L',
+      persistToLocalStorage: true,
+      localStorageKey: '__adminMode__',
+      onRedDotClick: NOOP,
+      onChange: NOOP,
+      beforeEnter: () => true,
+      beforeExit: () => true,
+      ...cfg,
+    }
+  }
+
+  cfg: Required<AdminModeCfg>
+
+  adminMode = false
+
+  private listening = false
+
+  /**
+   * Start listening to keyboard events to toggle AdminMode when detected.
+   */
+  startListening(): void {
+    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(): void {
+    if (isServerSide()) return
+    document.removeEventListener('keydown', this.keydownListener)
+    this.listening = false
+  }
+
+  private async keydownListener(e: KeyboardEvent): Promise<void> {
+    // console.log(e)
+    if (!this.cfg.predicate(e)) return
+    await this.toggleRedDot()
+  }
+
+  async toggleRedDot(): Promise<void> {
+    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)
+  }
+
+  private toggleRedDotVisibility(): void {
+    this.getRedDotElement().style.display = this.adminMode ? 'block' : 'none'
+  }
+
+  @_Memo()
+  private getRedDotElement(): HTMLElement {
+    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
+  }
+}

package/src/browser/analytics.util.ts

@@ -0,0 +1,68 @@
+import { isServerSide } from '@naturalcycles/js-lib'
+import { loadScript } from './script.util'
+
+declare global {
+  interface Window {
+    dataLayer: any[]
+    gtag: (...args: any[]) => void
+  }
+}
+
+/* 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: string, enabled = true): Promise<void> {
+  if (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 loadScript(`https://www.googletagmanager.com/gtag/js?id=${gtagId}`)
+}
+
+export async function loadGTM(gtmId: string, enabled = true): Promise<void> {
+  if (isServerSide()) return
+
+  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: number): void {
+  if (isServerSide()) return
+
+  /* eslint-disable */
+  // prettier-ignore
+  ;
+  ;((h: any, o, t, j, a?: any, r?: any) => {
+    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/src/browser/i18n/fetchTranslationLoader.ts

@@ -0,0 +1,16 @@
+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 class FetchTranslationLoader implements TranslationLoader {
+  constructor(public fetcher: Fetcher) {}
+
+  async load(locale: string): Promise<StringMap> {
+    return await this.fetcher.get(`${locale}.json`)
+  }
+}

package/src/browser/i18n/translation.service.ts

@@ -0,0 +1,102 @@
+import { pMap } from '../../promise/pMap'
+import { StringMap } from '../../types'
+
+export type MissingTranslationHandler = (key: string, params?: StringMap<any>) => string
+
+export const defaultMissingTranslationHandler: MissingTranslationHandler = key => {
+  console.warn(`[tr] missing: ${key}`)
+  return `[${key}]`
+}
+
+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 // non-optional
+}
+
+export interface TranslationLoader {
+  load: (locale: string) => Promise<StringMap>
+}
+
+export class TranslationService {
+  constructor(cfg: TranslationServiceCfg, preloadedLocales: StringMap<StringMap> = {}) {
+    this.cfg = {
+      ...cfg,
+      missingTranslationHandler: defaultMissingTranslationHandler,
+    }
+
+    this.locales = {
+      ...preloadedLocales,
+    }
+
+    this.currentLocale = cfg.currentLocale || cfg.defaultLocale
+  }
+
+  cfg: TranslationServiceCfgComplete
+
+  /**
+   * Cache of loaded locales
+   */
+  locales: StringMap<StringMap>
+
+  currentLocale: string
+
+  /**
+   * Manually set locale data, bypassing the TranslationLoader.
+   */
+  setLocale(localeName: string, locale: StringMap): void {
+    this.locales[localeName] = locale
+  }
+
+  getLocale(locale: string): StringMap | undefined {
+    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: string | string[]): Promise<void> {
+    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: string, params?: StringMap): string {
+    return this.translateIfExists(key, params) || this.cfg.missingTranslationHandler(key, params)
+  }
+
+  /**
+   * Does NOT invoke `missingTranslationHandler`, returns `undefined` instead.
+   */
+  translateIfExists(key: string, _params?: StringMap): string | undefined {
+    // todo: support params
+    return this.locales[this.currentLocale]?.[key] || this.locales[this.cfg.defaultLocale]?.[key]
+  }
+}