@naturalcycles/js-lib 15.85.0 → 15.86.0

package/dist/ua/ua.d.ts

@@ -0,0 +1,113 @@
+/// <reference lib="dom" preserve="true" />
+export type UADeviceType = 'console' | 'mobile' | 'tablet' | 'smarttv' | 'wearable' | 'embedded';
+export interface UABrowser {
+    /**
+     * E.g Chrome, Edge, Firefox, Safari, Mobile Safari, Opera, IE, UCBrowser, WeChat, ...
+     */
+    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, ...
+     */
+    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;
+/**
+ * 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);
+    constructor(extensions: UAParserExtensions);
+    private ua;
+    private readonly nav;
+    private readonly rgxMap;
+    private readonly isSelfNav;
+    getBrowser(): UABrowser;
+    getCPU(): UACpu;
+    getDevice(): UADevice;
+    getEngine(): UAEngine;
+    getOS(): UAOS;
+    getResult(): UAResult;
+    getUA(): string;
+    setUA(ua: string | undefined): this;
+}