@naturalcycles/js-lib 14.254.0 → 14.256.0

package/dist/array/array.util.d.ts

@@ -161,11 +161,15 @@ export declare function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[];
  */
 export declare function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean;
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export declare function _difference<T>(source: T[], ...diffs: T[][]): T[];
+export declare function _difference<T>(a1: T[], a2: T[] | Set<T>): T[];
 /**
  * Returns the sum of items, or 0 for empty array.
  */

package/dist/array/array.util.js

@@ -318,16 +318,17 @@ function _intersectsWith(a1, a2) {
     return a1.some(v => a2set.has(v));
 }
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-function _difference(source, ...diffs) {
-    let a = source;
-    for (const b of diffs) {
-        a = a.filter(c => !b.includes(c));
-    }
-    return a;
+function _difference(a1, a2) {
+    const a2set = a2 instanceof Set ? a2 : new Set(a2);
+    return a1.filter(v => !a2set.has(v));
 }
 /**
  * Returns the sum of items, or 0 for empty array.

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/error/tryCatch.js

@@ -29,7 +29,7 @@ function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError((0, index_1._anyToError)(err)); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError((0, index_1._anyToError)(err));
                 }
                 catch { }
             }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './abort';
 export * from './array/array.util';
 export * from './array/range';
+export * from './bot';
 export * from './datetime/dateInterval';
 export * from './datetime/localDate';
 export * from './datetime/localTime';

package/dist/index.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./abort"), exports);
 tslib_1.__exportStar(require("./array/array.util"), exports);
 tslib_1.__exportStar(require("./array/range"), exports);
+tslib_1.__exportStar(require("./bot"), exports);
 tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
 tslib_1.__exportStar(require("./datetime/localDate"), exports);
 tslib_1.__exportStar(require("./datetime/localTime"), exports);

package/dist/types.d.ts

@@ -1,4 +1,18 @@
 import type { Promisable } from './typeFest';
+declare const __brand: unique symbol;
+interface Brand<B> {
+    [__brand]: B;
+}
+/**
+ * Helper to create "Branded" types.
+ *
+ * Example:
+ * export type MyId = Branded<string, 'MyId'>
+ *
+ * MyId can be assigned to a string,
+ * but string cannot be assigned to MyId without casting it (`as MyId`).
+ */
+export type Branded<T, B> = T & Brand<B>;
 /**
  * Map from String to String (or <T>).
  *
@@ -292,3 +306,4 @@ export interface CommonClient extends AsyncDisposable {
     disconnect: () => Promise<void>;
     ping: () => Promise<void>;
 }
+export {};

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

@@ -277,16 +277,17 @@ export function _intersectsWith(a1, a2) {
     return a1.some(v => a2set.has(v));
 }
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _difference(source, ...diffs) {
-    let a = source;
-    for (const b of diffs) {
-        a = a.filter(c => !b.includes(c));
-    }
-    return a;
+export function _difference(a1, a2) {
+    const a2set = a2 instanceof Set ? a2 : new Set(a2);
+    return a1.filter(v => !a2set.has(v));
 }
 /**
  * Returns the sum of items, or 0 for empty array.

package/dist-esm/bot.js

@@ -0,0 +1,125 @@
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+import { isServerSide } from './env';
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export 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 (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 (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;
+    }
+}
+export 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 || (BotReason = {}));

package/dist-esm/error/tryCatch.js

@@ -25,7 +25,7 @@ export function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError(_anyToError(err)); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError(_anyToError(err));
                 }
                 catch { }
             }

package/dist-esm/index.js

@@ -1,6 +1,7 @@
 export * from './abort';
 export * from './array/array.util';
 export * from './array/range';
+export * from './bot';
 export * from './datetime/dateInterval';
 export * from './datetime/localDate';
 export * from './datetime/localTime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.254.0",
+  "version": "14.256.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/array/array.util.ts

@@ -331,16 +331,17 @@ export function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean {
 }
 
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _difference<T>(source: T[], ...diffs: T[][]): T[] {
-  let a = source
-  for (const b of diffs) {
-    a = a.filter(c => !b.includes(c))
-  }
-  return a
+export function _difference<T>(a1: T[], a2: T[] | Set<T>): T[] {
+  const a2set = a2 instanceof Set ? a2 : new Set(a2)
+  return a1.filter(v => !a2set.has(v))
 }
 
 /**

package/src/bot.ts

@@ -0,0 +1,155 @@
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+
+import { isServerSide } from './env'
+
+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 class BotDetectionService {
+  constructor(public cfg: BotDetectionServiceCfg = {}) {}
+
+  // memoized results
+  private botReason: BotReason | null | undefined
+  private cdp: boolean | undefined
+
+  isBotOrCDP(): boolean {
+    return !!this.getBotReason() || this.isCDP()
+  }
+
+  isBot(): boolean {
+    return !!this.getBotReason()
+  }
+
+  /**
+   * Returns null if it's not a Bot,
+   * otherwise a truthy BotReason.
+   */
+  getBotReason(): BotReason | null {
+    if (this.cfg.memoizeResults && this.botReason !== undefined) {
+      return this.botReason
+    }
+
+    this.botReason = this.detectBotReason()
+    return this.botReason
+  }
+
+  private detectBotReason(): BotReason | null {
+    // SSR - not a bot
+    if (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 as any) === '') {
+      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(): boolean {
+    if (this.cfg.memoizeResults && this.cdp !== undefined) {
+      return this.cdp
+    }
+
+    this.cdp = this.detectCDP()
+    return this.cdp
+  }
+
+  private detectCDP(): boolean {
+    if (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
+  }
+}
+
+export enum BotReason {
+  NoNavigator = 1,
+  NoUserAgent = 2,
+  UserAgent = 3,
+  WebDriver = 4,
+  // ZeroPlugins = 5,
+  EmptyLanguages = 6,
+  // ChromeWithoutChrome = 7,
+  /**
+   * This is when CDP is considered to be a reason to be a Bot.
+   * By default it's not.
+   */
+  CDP = 8,
+}

package/src/error/tryCatch.ts

@@ -56,7 +56,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
 
       if (onError) {
         try {
-          return await onError(_anyToError(err)) // eslint-disable-line @typescript-eslint/return-await
+          return await onError(_anyToError(err))
         } catch {}
       }
       // returns undefined, but doesn't rethrow

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './abort'
 export * from './array/array.util'
 export * from './array/range'
+export * from './bot'
 export * from './datetime/dateInterval'
 export * from './datetime/localDate'
 export * from './datetime/localTime'

package/src/types.ts

@@ -1,5 +1,22 @@
 import type { Promisable } from './typeFest'
 
+declare const __brand: unique symbol
+
+interface Brand<B> {
+  [__brand]: B
+}
+
+/**
+ * Helper to create "Branded" types.
+ *
+ * Example:
+ * export type MyId = Branded<string, 'MyId'>
+ *
+ * MyId can be assigned to a string,
+ * but string cannot be assigned to MyId without casting it (`as MyId`).
+ */
+export type Branded<T, B> = T & Brand<B>
+
 /**
  * Map from String to String (or <T>).
  *