@naturalcycles/js-lib 15.85.0 → 15.86.1

package/dist/ua/ua.d.ts

@@ -0,0 +1,183 @@
+/// <reference lib="dom" preserve="true" />
+export type UADeviceType = 'console' | 'mobile' | 'tablet' | 'smarttv' | 'wearable' | 'embedded';
+/**
+ * Popular OS names as produced by the parser, for convenient comparisons
+ * (`os.name === UAOSName.iOS`) without magic strings.
+ *
+ * Not exhaustive - the parser emits many more names; compare against a string for the rest.
+ */
+export declare enum UAOSName {
+    iOS = "iOS",
+    Android = "Android",
+    MacOS = "Mac OS",
+    Windows = "Windows",
+    Linux = "Linux",
+    ChromiumOS = "Chromium OS",
+    WatchOS = "watchOS"
+}
+/**
+ * Popular browser names as produced by the parser, for convenient comparisons
+ * (`browser.name === UABrowserName.Safari`) without magic strings.
+ *
+ * Not exhaustive - the parser emits many more names; compare against a string for the rest.
+ */
+export declare enum UABrowserName {
+    Chrome = "Chrome",
+    ChromeWebView = "Chrome WebView",
+    ChromeHeadless = "Chrome Headless",
+    Safari = "Safari",
+    MobileSafari = "Mobile Safari",
+    Firefox = "Firefox",
+    Edge = "Edge",
+    Opera = "Opera",
+    SamsungInternet = "Samsung Internet",
+    Facebook = "Facebook",
+    Instagram = "Instagram",
+    /**
+     * Bare WebKit UA without a Safari token, typically an iOS in-app webview (e.g. WKWebView).
+     */
+    WebKit = "WebKit"
+}
+export interface UABrowser {
+    /**
+     * E.g Chrome, Edge, Firefox, Safari, Mobile Safari, Opera, IE, UCBrowser, WeChat, ...
+     * Popular values are available as `UABrowserName`.
+     */
+    name: string | undefined;
+    version: string | undefined;
+    /**
+     * Major version, e.g. '20' for version '20.0.1090.0'.
+     */
+    major: string | undefined;
+}
+export interface UACpu {
+    /**
+     * E.g 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64,
+     * pa-risc, ppc, sparc, sparc64.
+     */
+    architecture: string | undefined;
+}
+export interface UADevice {
+    /**
+     * E.g Apple, Samsung, Huawei, Xiaomi, Google, Sony, LG, Microsoft, Amazon, ...
+     */
+    vendor: string | undefined;
+    model: string | undefined;
+    /**
+     * Undefined means "desktop-like" (no specific device type detected).
+     */
+    type: UADeviceType | undefined;
+}
+export interface UAEngine {
+    /**
+     * E.g Blink, Gecko, WebKit, EdgeHTML, Presto, Trident, ...
+     */
+    name: string | undefined;
+    version: string | undefined;
+}
+export interface UAOS {
+    /**
+     * E.g Windows, iOS, Mac OS, Android, Linux, Chromium OS, ...
+     * Popular values are available as `UAOSName`.
+     */
+    name: string | undefined;
+    version: string | undefined;
+}
+export interface UAResult {
+    ua: string;
+    browser: UABrowser;
+    engine: UAEngine;
+    os: UAOS;
+    device: UADevice;
+    cpu: UACpu;
+}
+export type UAMapperFn = (match: string) => string | undefined;
+export type UAStrMap = Record<string, string | string[]>;
+/**
+ * Describes how a regex capture group is assigned to a result property:
+ * - `prop` - assign the raw match
+ * - `[prop, value]` - assign a fixed value (ignore the match)
+ * - `[prop, fn]` - assign `fn(match)`
+ * - `[prop, regex, replacement]` - assign `match.replace(regex, replacement)`
+ * - `[prop, fn, map]` - assign `fn(match, map)` (string-map lookup)
+ * - `[prop, regex, replacement, fn]` - assign `fn(match.replace(regex, replacement))`
+ */
+export type UAAction = string | readonly [string, string] | readonly [string, UAMapperFn] | readonly [string, RegExp, string] | readonly [string, (str: string, map: UAStrMap) => string | undefined, UAStrMap] | readonly [string, RegExp, string, UAMapperFn];
+/**
+ * Alternating sequence of regex-list and action-list:
+ * `[RegExp[], UAAction[], RegExp[], UAAction[], ...]`.
+ * The regexes are tried in order; the first match wins and its capture groups
+ * are assigned via the following action-list.
+ */
+export type UARegexMapEntry = RegExp[] | UAAction[];
+/**
+ * Custom regexes to extend the built-in ones.
+ * Extension regexes are tried before the built-in regexes of the same category.
+ */
+export interface UAParserExtensions {
+    browser?: UARegexMapEntry[];
+    cpu?: UARegexMapEntry[];
+    device?: UARegexMapEntry[];
+    engine?: UARegexMapEntry[];
+    os?: UARegexMapEntry[];
+}
+/**
+ * Parses the given User-Agent string into browser, engine, os, device and cpu information.
+ *
+ * When `ua` is not provided and running in a browser - `navigator.userAgent` is used
+ * (with client-hints-based refinements, e.g. Brave and iPadOS detection).
+ */
+export declare function parseUserAgent(userAgent?: string, extensions?: UAParserExtensions): UAResult;
+export declare function uaParser(userAgent?: string, extensions?: UAParserExtensions): UAParser;
+/**
+ * User-Agent parser.
+ *
+ * Compared to `parseUserAgent()`, the class allows parsing only the needed parts
+ * (e.g `getBrowser()` alone is much cheaper than `getResult()`),
+ * and reusing the compiled extensions across multiple `setUA()` calls.
+ */
+export declare class UAParser {
+    constructor(ua?: string, extensions?: UAParserExtensions);
+    private ua;
+    private readonly nav;
+    private readonly rgxMap;
+    private readonly isSelfNav;
+    private cachedBrowser?;
+    private cachedOs?;
+    private cachedDevice?;
+    getBrowser(): UABrowser;
+    getCPU(): UACpu;
+    getDevice(): UADevice;
+    getEngine(): UAEngine;
+    getOS(): UAOS;
+    getResult(): UAResult;
+    getUA(): string;
+    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
+     * (except when parsing the browser's own UA, where client-hints refinements apply).
+     */
+    isIos(): boolean;
+    isAndroid(): boolean;
+    isMacOs(): boolean;
+    isWindows(): boolean;
+    /**
+     * True for 'Chrome', 'Chrome WebView' and 'Chrome Headless' (not for Chromium).
+     */
+    isChrome(): boolean;
+    /**
+     * True for 'Safari' and 'Mobile Safari' (not for bare-WebKit iOS in-app webviews).
+     */
+    isSafari(): boolean;
+    isFirefox(): boolean;
+    isEdge(): boolean;
+    /**
+     * True if the device type is 'mobile' (phones; tablets are 'tablet' - see isTablet).
+     */
+    isMobile(): boolean;
+    isTablet(): boolean;
+    private browser;
+    private os;
+    private device;
+}