@naturalcycles/js-lib 15.86.1 → 15.87.0

package/dist/analytics/analytics.model.d.ts

@@ -0,0 +1,76 @@
+import type { AnyObject, Branded, StringMap, UnixTimestampMillis } from '../types.js';
+/** Identity an event is attributed to: a generated device id, or an app-provided user id. */
+export type AnalyticsDistinctId = Branded<string, 'AnalyticsDistinctId'>;
+/** Emitted when the identity changes, naming the anonymous id the events so far belong to. */
+export declare const ANALYTICS_IDENTIFY_EVENT_NAME = "identify";
+/** Cap applied by `truncateAnalyticsProperty`. Event properties are passed through as given. */
+export declare const MAX_ANALYTICS_PROPERTY_LENGTH = 255;
+/**
+ * Caps a string property at the limit. Counts code points, because a plain
+ * slice(0, N) counts UTF-16 code units and can cut a surrogate pair in half.
+ */
+export declare function truncateAnalyticsProperty(value: string): string;
+/**
+ * POST body of the ingestion endpoint - a client-batched analytics event envelope.
+ *
+ * Sent as a JSON string with `text/plain` content-type,
+ * to keep the request CORS-simple (no preflight).
+ */
+export interface AnalyticsBatchInput {
+    /**
+     * Client-side unix timestamp (ms) of when this request was sent.
+     * Kept as envelope timing metadata. It must not be used to adjust `event.ts`,
+     * because it changes between delivery attempts.
+     */
+    sentAt: UnixTimestampMillis;
+    /**
+     * Client that sends the events. Allow-listed by the destination.
+     */
+    clientId: number;
+    /**
+     * @deprecated Use `AnalyticsClientEvent.userId`, which is stamped when the event is tracked
+     * rather than when the batch is sent. Still sent for clients that predate the per-event id.
+     */
+    userId: AnalyticsDistinctId;
+    events: AnalyticsClientEvent[];
+}
+export interface AnalyticsClientEvent {
+    /**
+     * Unique event id, used for deduplication. Alphanumeric-only, so it can be
+     * forwarded as a dedupe key without conversion.
+     */
+    id: string;
+    /**
+     * Event name, e.g `WebClick`.
+     */
+    name: string;
+    /**
+     * Client-side unix timestamp (ms) of when the event was tracked (not when it was sent).
+     * Stable across delivery attempts, because a deduplication key may include it.
+     */
+    ts: UnixTimestampMillis;
+    /**
+     * Event properties.
+     */
+    props?: AnyObject;
+    /**
+     * Identity this event was tracked under
+     * TODO: make required
+     */
+    userId?: AnalyticsDistinctId;
+}
+/** Canonical utm parameters. */
+export declare const CANONICAL_UTM_PARAMS: string[];
+/** Keyed by `initial_<canonical utm param>`, to avoid permanently saving non-standard ones. */
+export type FirstTouchUtms = StringMap<string | null>;
+/**
+ * Properties that will be "set once" on a user profile. Meaning they are not changed by subsequent
+ * saves on the user profile. Keyed by `initial_referrer` and the first-touch utms.
+ */
+export type SetOnceUserProperties = StringMap<string | null>;
+/** Body of the first-touch endpoint, posted once per pageload. */
+export interface FirstTouchInput {
+    clientId: number;
+    userId: AnalyticsDistinctId;
+    props: SetOnceUserProperties;
+}

package/dist/analytics/analytics.model.js

@@ -0,0 +1,26 @@
+/** Emitted when the identity changes, naming the anonymous id the events so far belong to. */
+export const ANALYTICS_IDENTIFY_EVENT_NAME = 'identify';
+/** Cap applied by `truncateAnalyticsProperty`. Event properties are passed through as given. */
+export const MAX_ANALYTICS_PROPERTY_LENGTH = 255;
+/**
+ * Caps a string property at the limit. Counts code points, because a plain
+ * slice(0, N) counts UTF-16 code units and can cut a surrogate pair in half.
+ */
+export function truncateAnalyticsProperty(value) {
+    if (value.length <= MAX_ANALYTICS_PROPERTY_LENGTH)
+        return value;
+    return Array.from(value).slice(0, MAX_ANALYTICS_PROPERTY_LENGTH).join('');
+}
+/** Canonical utm parameters. */
+export const CANONICAL_UTM_PARAMS = [
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_content',
+    'utm_term',
+    'utm_id',
+    'utm_source_platform',
+    'utm_campaign_id',
+    'utm_creative_format',
+    'utm_marketing_tactic',
+];

package/dist/analytics/index.d.ts

@@ -0,0 +1 @@
+export * from './analytics.model.js';

package/dist/analytics/index.js

@@ -0,0 +1 @@
+export * from './analytics.model.js';

package/dist/datetime/localDate.js

@@ -21,7 +21,11 @@ export class LocalDate {
         this.day = day;
     }
     get(unit) {
-        return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day;
+        if (unit === 'year')
+            return this.year;
+        if (unit === 'month')
+            return this.month;
+        return this.day;
     }
     set(unit, v, opt = {}) {
         const t = opt.mutate ? this : this.clone();

package/dist/error/error.util.js

@@ -174,24 +174,49 @@ export function _errorSnippet(err, opt = {}) {
             .join(': ');
     }
 }
+// These duck-typing checks read properties of an arbitrary object, which may invoke its
+// property getters, which may throw (e.g a stateful getter, a Proxy trap).
+// A type guard should never throw - an object whose properties cannot even be read safely
+// is, by definition, not a well-behaved Error-like - hence try/catch returning false.
+// try/catch is free in V8 unless it actually catches, so there's no performance penalty.
 export function _isBackendErrorResponseObject(o) {
-    return _isErrorObject(o?.error);
+    try {
+        return _isErrorObject(o?.error);
+    }
+    catch {
+        return false;
+    }
 }
 export function _isHttpRequestErrorObject(o) {
-    return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string';
+    try {
+        return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string';
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Note: any instance of AppError is also automatically an ErrorObject
  */
 export function _isErrorObject(o) {
-    return (!!o &&
-        typeof o === 'object' &&
-        typeof o.name === 'string' &&
-        typeof o.message === 'string' &&
-        typeof o.data === 'object');
+    try {
+        return (!!o &&
+            typeof o === 'object' &&
+            typeof o.name === 'string' &&
+            typeof o.message === 'string' &&
+            typeof o.data === 'object');
+    }
+    catch {
+        return false;
+    }
 }
 export function _isErrorLike(o) {
-    return !!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string';
+    try {
+        return (!!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string');
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Convenience function to safely add properties to Error's `data` object

package/dist/number/number.util.js

@@ -40,7 +40,11 @@ export function _isBetween(x, min, max, incl) {
     return true;
 }
 export function _clamp(x, minIncl, maxIncl) {
-    return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x;
+    if (x <= minIncl)
+        return minIncl;
+    if (x >= maxIncl)
+        return maxIncl;
+    return x;
 }
 /**
  * Same as .toFixed(), but conveniently casts the output to Number.

package/dist/qr/qr.js

@@ -560,8 +560,11 @@ function getLengthInBits(mode, type) {
     const bits = LENGTH_BITS[mode];
     if (!bits)
         throw new Error(`qr: bad mode: ${mode}`);
-    const range = type < 10 ? 0 : type < 27 ? 1 : 2;
-    return bits[range];
+    if (type < 10)
+        return bits[0];
+    if (type < 27)
+        return bits[1];
+    return bits[2];
 }
 // --- Reed-Solomon polynomials over GF(256) ---------------------------------
 /** Drop leading zeros, then right-pad with `shift` zeros. */

package/dist/semver.js

@@ -147,5 +147,9 @@ export function _quickSemverCompare(a, b) {
     const s2 = _range(3)
         .map(i => (t2[i] || '').padStart(5))
         .join('');
-    return s1 < s2 ? -1 : s1 > s2 ? 1 : 0;
+    if (s1 < s2)
+        return -1;
+    if (s1 > s2)
+        return 1;
+    return 0;
 }

package/dist/string/leven.js

@@ -63,14 +63,13 @@ export function _leven(first, second, limit) {
         for (index = 0; index < firstLength; index++) {
             temporary2 = bCharacterCode === characterCodeCache[index] ? temporary : temporary + 1;
             temporary = array[index];
-            result = array[index] =
-                temporary > result
-                    ? temporary2 > result
-                        ? result + 1
-                        : temporary2
-                    : temporary2 > temporary
-                        ? temporary + 1
-                        : temporary2;
+            if (temporary > result) {
+                result = temporary2 > result ? result + 1 : temporary2;
+            }
+            else {
+                result = temporary2 > temporary ? temporary + 1 : temporary2;
+            }
+            array[index] = result;
         }
     }
     return result;

package/dist/ua/ua.d.ts

@@ -152,7 +152,7 @@ export declare class UAParser {
     getOS(): UAOS;
     getResult(): UAResult;
     getUA(): string;
-    setUA(ua: string | undefined): this;
+    setUA(ua?: string | undefined): this;
     /**
      * True if the OS is iOS.
      * Note: desktop-mode iPads send a Mac-like UA and are not detected as iOS

package/dist/ua/ua.js

@@ -146,8 +146,7 @@ export class UAParser {
     getUA() {
         return this.ua;
     }
-    setUA(ua) {
-        ua ||= '';
+    setUA(ua = '') {
         this.ua = ua.length > UA_MAX_LENGTH ? ua.replace(/^\s\s*/, '').slice(0, UA_MAX_LENGTH) : ua;
         this.cachedBrowser = this.cachedOs = this.cachedDevice = undefined;
         return this;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.86.1",
+  "version": "15.87.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -14,14 +14,16 @@
     }
   },
   "devDependencies": {
+    "@naturalcycles/dev-lib": "0.0.0",
     "@types/node": "^26",
     "@types/semver": "^7",
     "typescript": "^7",
-    "dayjs": "^1",
-    "@naturalcycles/dev-lib": "0.0.0"
+    "dayjs": "^1"
   },
   "exports": {
     ".": "./dist/index.js",
+    "./analytics": "./dist/analytics/index.js",
+    "./analytics/*.js": "./dist/analytics/*.js",
     "./array": "./dist/array/index.js",
     "./array/*.js": "./dist/array/*.js",
     "./browser": "./dist/browser/index.js",

package/src/analytics/analytics.model.ts

@@ -0,0 +1,100 @@
+import type { AnyObject, Branded, StringMap, UnixTimestampMillis } from '../types.js'
+
+/** Identity an event is attributed to: a generated device id, or an app-provided user id. */
+export type AnalyticsDistinctId = Branded<string, 'AnalyticsDistinctId'>
+
+/** Emitted when the identity changes, naming the anonymous id the events so far belong to. */
+export const ANALYTICS_IDENTIFY_EVENT_NAME = 'identify'
+
+/** Cap applied by `truncateAnalyticsProperty`. Event properties are passed through as given. */
+export const MAX_ANALYTICS_PROPERTY_LENGTH = 255
+
+/**
+ * Caps a string property at the limit. Counts code points, because a plain
+ * slice(0, N) counts UTF-16 code units and can cut a surrogate pair in half.
+ */
+export function truncateAnalyticsProperty(value: string): string {
+  if (value.length <= MAX_ANALYTICS_PROPERTY_LENGTH) return value
+  return Array.from(value).slice(0, MAX_ANALYTICS_PROPERTY_LENGTH).join('')
+}
+
+/**
+ * POST body of the ingestion endpoint - a client-batched analytics event envelope.
+ *
+ * Sent as a JSON string with `text/plain` content-type,
+ * to keep the request CORS-simple (no preflight).
+ */
+export interface AnalyticsBatchInput {
+  /**
+   * Client-side unix timestamp (ms) of when this request was sent.
+   * Kept as envelope timing metadata. It must not be used to adjust `event.ts`,
+   * because it changes between delivery attempts.
+   */
+  sentAt: UnixTimestampMillis
+  /**
+   * Client that sends the events. Allow-listed by the destination.
+   */
+  clientId: number
+  /**
+   * @deprecated Use `AnalyticsClientEvent.userId`, which is stamped when the event is tracked
+   * rather than when the batch is sent. Still sent for clients that predate the per-event id.
+   */
+  userId: AnalyticsDistinctId
+  events: AnalyticsClientEvent[]
+}
+
+export interface AnalyticsClientEvent {
+  /**
+   * Unique event id, used for deduplication. Alphanumeric-only, so it can be
+   * forwarded as a dedupe key without conversion.
+   */
+  id: string
+  /**
+   * Event name, e.g `WebClick`.
+   */
+  name: string
+  /**
+   * Client-side unix timestamp (ms) of when the event was tracked (not when it was sent).
+   * Stable across delivery attempts, because a deduplication key may include it.
+   */
+  ts: UnixTimestampMillis
+  /**
+   * Event properties.
+   */
+  props?: AnyObject
+  /**
+   * Identity this event was tracked under
+   * TODO: make required
+   */
+  userId?: AnalyticsDistinctId
+}
+
+/** Canonical utm parameters. */
+export const CANONICAL_UTM_PARAMS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_content',
+  'utm_term',
+  'utm_id',
+  'utm_source_platform',
+  'utm_campaign_id',
+  'utm_creative_format',
+  'utm_marketing_tactic',
+]
+
+/** Keyed by `initial_<canonical utm param>`, to avoid permanently saving non-standard ones. */
+export type FirstTouchUtms = StringMap<string | null>
+
+/**
+ * Properties that will be "set once" on a user profile. Meaning they are not changed by subsequent
+ * saves on the user profile. Keyed by `initial_referrer` and the first-touch utms.
+ */
+export type SetOnceUserProperties = StringMap<string | null>
+
+/** Body of the first-touch endpoint, posted once per pageload. */
+export interface FirstTouchInput {
+  clientId: number
+  userId: AnalyticsDistinctId
+  props: SetOnceUserProperties
+}

package/src/analytics/index.ts

@@ -0,0 +1 @@
+export * from './analytics.model.js'

package/src/datetime/localDate.ts

@@ -40,7 +40,9 @@ export class LocalDate {
   ) {}
 
   get(unit: LocalDateUnitStrict): number {
-    return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day
+    if (unit === 'year') return this.year
+    if (unit === 'month') return this.month
+    return this.day
   }
 
   set(unit: LocalDateUnitStrict, v: number, opt: MutateOptions = {}): LocalDate {

package/src/error/error.util.ts

@@ -226,12 +226,26 @@ export function _errorSnippet(err: any, opt: ErrorSnippetOptions = {}): string {
   }
 }
 
+// These duck-typing checks read properties of an arbitrary object, which may invoke its
+// property getters, which may throw (e.g a stateful getter, a Proxy trap).
+// A type guard should never throw - an object whose properties cannot even be read safely
+// is, by definition, not a well-behaved Error-like - hence try/catch returning false.
+// try/catch is free in V8 unless it actually catches, so there's no performance penalty.
+
 export function _isBackendErrorResponseObject(o: any): o is BackendErrorResponseObject {
-  return _isErrorObject(o?.error)
+  try {
+    return _isErrorObject(o?.error)
+  } catch {
+    return false
+  }
 }
 
 export function _isHttpRequestErrorObject(o: any): o is ErrorObject<HttpRequestErrorData> {
-  return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string'
+  try {
+    return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string'
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -240,17 +254,27 @@ export function _isHttpRequestErrorObject(o: any): o is ErrorObject<HttpRequestE
 export function _isErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
   o: any,
 ): o is ErrorObject<DATA_TYPE> {
-  return (
-    !!o &&
-    typeof o === 'object' &&
-    typeof o.name === 'string' &&
-    typeof o.message === 'string' &&
-    typeof o.data === 'object'
-  )
+  try {
+    return (
+      !!o &&
+      typeof o === 'object' &&
+      typeof o.name === 'string' &&
+      typeof o.message === 'string' &&
+      typeof o.data === 'object'
+    )
+  } catch {
+    return false
+  }
 }
 
 export function _isErrorLike(o: any): o is ErrorLike {
-  return !!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string'
+  try {
+    return (
+      !!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string'
+    )
+  } catch {
+    return false
+  }
 }
 
 /**

package/src/number/number.util.ts

@@ -50,7 +50,9 @@ export function _isBetween<T extends number | string>(
 }
 
 export function _clamp(x: number, minIncl: number, maxIncl: number): number {
-  return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x
+  if (x <= minIncl) return minIncl
+  if (x >= maxIncl) return maxIncl
+  return x
 }
 
 /**

package/src/qr/qr.ts

@@ -684,8 +684,9 @@ function getLengthInBits(mode: number, type: number): number {
   if (type < 1 || type > 40) throw new Error(`qr: bad type number: ${type}`)
   const bits = LENGTH_BITS[mode]
   if (!bits) throw new Error(`qr: bad mode: ${mode}`)
-  const range = type < 10 ? 0 : type < 27 ? 1 : 2
-  return bits[range]
+  if (type < 10) return bits[0]
+  if (type < 27) return bits[1]
+  return bits[2]
 }
 
 // --- Reed-Solomon polynomials over GF(256) ---------------------------------

package/src/semver.ts

@@ -171,5 +171,7 @@ export function _quickSemverCompare(a: string, b: string): -1 | 0 | 1 {
   const s2 = _range(3)
     .map(i => (t2[i] || '').padStart(5))
     .join('')
-  return s1 < s2 ? -1 : s1 > s2 ? 1 : 0
+  if (s1 < s2) return -1
+  if (s1 > s2) return 1
+  return 0
 }

package/src/string/leven.ts

@@ -76,14 +76,12 @@ export function _leven(first: string, second: string, limit?: number): number {
       temporary2 = bCharacterCode === characterCodeCache[index] ? temporary : temporary + 1
       temporary = array[index]!
 
-      result = array[index] =
-        temporary > result
-          ? temporary2 > result
-            ? result + 1
-            : temporary2
-          : temporary2 > temporary
-            ? temporary + 1
-            : temporary2
+      if (temporary > result) {
+        result = temporary2 > result ? result + 1 : temporary2
+      } else {
+        result = temporary2 > temporary ? temporary + 1 : temporary2
+      }
+      array[index] = result
     }
   }
 

package/src/ua/ua.ts

@@ -266,8 +266,7 @@ export class UAParser {
     return this.ua
   }
 
-  setUA(ua: string | undefined): this {
-    ua ||= ''
+  setUA(ua: string | undefined = ''): this {
     this.ua = ua.length > UA_MAX_LENGTH ? ua.replace(/^\s\s*/, '').slice(0, UA_MAX_LENGTH) : ua
     this.cachedBrowser = this.cachedOs = this.cachedDevice = undefined
     return this