@naturalcycles/js-lib 14.257.0 → 14.258.0

package/dist/deviceIdService.d.ts

@@ -0,0 +1,65 @@
+/// <reference lib="dom" preserve="true" />
+/**
+ * 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 declare class DeviceIdService {
+    constructor(cfg?: DeviceIdServiceCfg);
+    cfg: Required<DeviceIdServiceCfg>;
+    /**
+     * `deviceId` is null only in anomalous cases, e.g when localStorage is not available (due to e.g "out of disk space" on device).
+     * In all other cases it should be defined and stable (persisted indefinitely between multiple visits).
+     *
+     * It is null if the service is run on the server side.
+     */
+    deviceId: string | null;
+    /**
+     * 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: number): boolean;
+    /**
+     * Deletes the persisted deviceId.
+     * Keeps it in the service.
+     * To remove it from the service, assign deviceIdService.deviceId = null.
+     */
+    clearPersistence(): void;
+    /**
+     * Generates a stable Device id if it wasn't previously generated on this device.
+     * Otherwise, reads a Device id from persistent storage.
+     */
+    private init;
+    private debug;
+}
+export interface DeviceIdServiceCfg {
+    /**
+     * Default: deviceId
+     */
+    localStorageKey?: string;
+    /**
+     * Set to true to enable debug logging.
+     */
+    debug?: boolean;
+}

package/dist/deviceIdService.js

@@ -0,0 +1,109 @@
+"use strict";
+/// <reference lib="dom" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceIdService = void 0;
+const env_1 = require("./env");
+const nanoid_1 = require("./nanoid");
+const hash_util_1 = require("./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
+ */
+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 (0, hash_util_1.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 ((0, env_1.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 = (0, nanoid_1.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);
+    }
+}
+exports.DeviceIdService = DeviceIdService;

package/dist/index.d.ts

@@ -27,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';
@@ -52,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/index.js

@@ -31,6 +31,7 @@ tslib_1.__exportStar(require("./decorators/memoFnAsync"), exports);
 tslib_1.__exportStar(require("./decorators/retry.decorator"), exports);
 tslib_1.__exportStar(require("./decorators/timeout.decorator"), exports);
 tslib_1.__exportStar(require("./define"), exports);
+tslib_1.__exportStar(require("./deviceIdService"), exports);
 tslib_1.__exportStar(require("./enum.util"), exports);
 tslib_1.__exportStar(require("./env"), exports);
 tslib_1.__exportStar(require("./env/buildInfo"), exports);
@@ -56,6 +57,7 @@ tslib_1.__exportStar(require("./log/commonLogger"), exports);
 tslib_1.__exportStar(require("./math/math.util"), exports);
 tslib_1.__exportStar(require("./math/sma"), exports);
 tslib_1.__exportStar(require("./math/stack.util"), exports);
+tslib_1.__exportStar(require("./nanoid"), exports);
 tslib_1.__exportStar(require("./number/createDeterministicRandom"), exports);
 tslib_1.__exportStar(require("./number/number.util"), exports);
 tslib_1.__exportStar(require("./object/deepEquals"), exports);

package/dist/nanoid.d.ts

@@ -0,0 +1,7 @@
+/// <reference lib="dom" preserve="true" />
+/**
+ * Function that takes a length (defaults to 21) and generates a random string id of that length.
+ */
+export type NanoidFunction = (length?: number) => string;
+export declare function nanoidBrowser(length?: number): string;
+export declare function nanoidBrowserCustomAlphabet(alphabet: string, length?: number): NanoidFunction;

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-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/index.js

@@ -27,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';
@@ -52,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.257.0",
+  "version": "14.258.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/deviceIdService.ts

@@ -0,0 +1,137 @@
+/// <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: DeviceIdServiceCfg = {}) {
+    this.cfg = {
+      localStorageKey: 'deviceId',
+      debug: false,
+      ...cfg,
+    }
+
+    this.init()
+  }
+
+  cfg: Required<DeviceIdServiceCfg>
+
+  /**
+   * `deviceId` is null only in anomalous cases, e.g when localStorage is not available (due to e.g "out of disk space" on device).
+   * In all other cases it should be defined and stable (persisted indefinitely between multiple visits).
+   *
+   * It is null if the service is run on the server side.
+   */
+  deviceId!: string | null
+
+  /**
+   * 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: number): boolean {
+    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(): void {
+    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.
+   */
+  private init(): void {
+    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
+      }
+    }
+  }
+
+  private debug(...args: any[]): void {
+    if (this.cfg.debug) console.log('[DeviceIdService]', ...args)
+  }
+}
+
+export interface DeviceIdServiceCfg {
+  /**
+   * Default: deviceId
+   */
+  localStorageKey?: string
+
+  /**
+   * Set to true to enable debug logging.
+   */
+  debug?: boolean
+}

package/src/index.ts

@@ -27,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'
@@ -52,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/src/nanoid.ts

@@ -0,0 +1,79 @@
+// 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'
+
+/**
+ * Function that takes a length (defaults to 21) and generates a random string id of that length.
+ */
+export type NanoidFunction = (length?: number) => string
+
+type NanoidRandomFunction = (bytes: number) => Uint8Array
+
+export function nanoidBrowser(length = 21): string {
+  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: NanoidRandomFunction = (bytes: number) =>
+  globalThis.crypto.getRandomValues(new Uint8Array(bytes))
+
+export function nanoidBrowserCustomAlphabet(alphabet: string, length = 21): NanoidFunction {
+  return customRandom(alphabet, length, defaultRandomFunction)
+}
+
+function customRandom(
+  alphabet: string,
+  defaultSize: number,
+  getRandom: NanoidRandomFunction,
+): NanoidFunction {
+  // 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/src/number/createDeterministicRandom.ts

@@ -1,12 +1,17 @@
 /* eslint-disable no-bitwise */
 
+/**
+ * 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 function _createDeterministicRandom(): () => number {
-  let seed = 0x2f6e2b1
+export function _createDeterministicRandom(seed = 0x2f6e2b1): RandomFunction {
   return () => {
     // Robert Jenkins’ 32 bit integer hash function
     seed = (seed + 0x7ed55d16 + (seed << 12)) & 0xffffffff

package/src/string/hash.util.ts

@@ -11,7 +11,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/src/web.ts

@@ -7,6 +7,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 class InMemoryWebStorage implements Storage {