@naturalcycles/js-lib 14.256.0 → 14.258.0

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/error/assert.ts

@@ -1,14 +1,8 @@
-import {
-  _deepEquals,
-  _isBackendErrorResponseObject,
-  _isErrorObject,
-  _stringify,
-  AssertionError,
-  BackendErrorResponseObject,
-  Class,
-  ErrorData,
-  ErrorObject,
-} from '..'
+import { _deepEquals } from '../object/deepEquals'
+import { _stringify } from '../string/stringify'
+import type { Class } from '../typeFest'
+import type { BackendErrorResponseObject, ErrorData, ErrorObject } from './error.model'
+import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util'
 
 /**
  * Evaluates the `condition` (casts it to Boolean).

package/src/error/error.util.ts

@@ -6,7 +6,10 @@ import type {
   ErrorObject,
   HttpRequestErrorData,
 } from '..'
-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) { ... }`

package/src/index.ts

@@ -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/src/json-schema/jsonSchemaBuilder.ts

@@ -131,38 +131,47 @@ export class JsonSchemaAnyBuilder<T = unknown, SCHEMA_TYPE extends JsonSchema<T>
     Object.assign(this.schema, { $schema })
     return this
   }
+
   $schemaDraft7(): this {
     this.$schema('http://json-schema.org/draft-07/schema#')
     return this
   }
+
   $id($id: string): this {
     Object.assign(this.schema, { $id })
     return this
   }
+
   title(title: string): this {
     Object.assign(this.schema, { title })
     return this
   }
+
   description(description: string): this {
     Object.assign(this.schema, { description })
     return this
   }
+
   deprecated(deprecated = true): this {
     Object.assign(this.schema, { deprecated })
     return this
   }
+
   type(type: string): this {
     Object.assign(this.schema, { type })
     return this
   }
+
   default(v: any): this {
     Object.assign(this.schema, { default: v })
     return this
   }
+
   oneOf(schemas: JsonSchema[]): this {
     Object.assign(this.schema, { oneOf: schemas })
     return this
   }
+
   allOf(schemas: JsonSchema[]): this {
     Object.assign(this.schema, { allOf: schemas })
     return this
@@ -211,18 +220,22 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder<number, JsonSc
     Object.assign(this.schema, { multipleOf })
     return this
   }
+
   min(minimum: number): this {
     Object.assign(this.schema, { minimum })
     return this
   }
+
   exclusiveMin(exclusiveMinimum: number): this {
     Object.assign(this.schema, { exclusiveMinimum })
     return this
   }
+
   max(maximum: number): this {
     Object.assign(this.schema, { maximum })
     return this
   }
+
   exclusiveMax(exclusiveMaximum: number): this {
     Object.assign(this.schema, { exclusiveMaximum })
     return this
@@ -264,14 +277,17 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder<string, JsonSc
     Object.assign(this.schema, { pattern })
     return this
   }
+
   min(minLength: number): this {
     Object.assign(this.schema, { minLength })
     return this
   }
+
   max(maxLength: number): this {
     Object.assign(this.schema, { maxLength })
     return this
   }
+
   length(minLength: number, maxLength: number): this {
     Object.assign(this.schema, { minLength, maxLength })
     return this
@@ -358,10 +374,12 @@ export class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyB
     Object.assign(this.schema, { minProperties })
     return this
   }
+
   maxProps(maxProperties: number): this {
     Object.assign(this.schema, { maxProperties })
     return this
   }
+
   additionalProps(additionalProperties: boolean): this {
     Object.assign(this.schema, { additionalProperties })
     return this
@@ -400,10 +418,12 @@ export class JsonSchemaArrayBuilder<ITEM> extends JsonSchemaAnyBuilder<
     Object.assign(this.schema, { minItems })
     return this
   }
+
   max(maxItems: number): this {
     Object.assign(this.schema, { maxItems })
     return this
   }
+
   unique(uniqueItems: number): this {
     Object.assign(this.schema, { uniqueItems })
     return this

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/semver.ts

@@ -28,9 +28,11 @@ export class Semver {
   get major(): number {
     return this.tokens[0]
   }
+
   get minor(): number {
     return this.tokens[1]
   }
+
   get patch(): number {
     return this.tokens[2]
   }

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 {

package/src/zod/zod.util.ts

@@ -1,4 +1,4 @@
-import { ZodError, ZodIssue, ZodSchema } from 'zod'
+import { ZodError, type ZodIssue, type ZodSchema } from 'zod'
 import { _stringify } from '../string/stringify'
 
 export interface ZodErrorResult<T> {