Initial work for docs using VitePress

docs/v2/api/idata/is.md

@@ -0,0 +1,67 @@
+# is(value:string):boolean
+
+This method returns `true` if the passed value matches with the value of one of the properties of current object, `false` otherwise.
+
+::: info
+* `device` properties are checked in this particular order: `type`, `model`, `vendor`.
+* When checking for browser, any `Browser` suffix will be ignored.
+* When checking for OS, any `OS` suffix will be ignored.
+* The comparison is case-insensitive, thus `is("firefox") == is("Firefox")`.
+:::
+
+## Code Example
+
+```js
+// is() is just a shorthand comparison
+// so that instead of write it using `==` operator like this:
+
+const ua = UAParser();
+const device = ua.device;
+const os = ua.os;
+
+if (device.type == "mobile" && os.name != "iOS") {}
+if (device.type == "smarttv" || device.vendor == "Samsung") {}
+
+// we can also write the comparison above into as follow:
+
+if (device.is("mobile") && !os.is("iOS")) {}
+if (device.is("SmartTV") || device.is("SaMsUnG")) {}
+```
+
+```js
+// Another examples:
+
+const uap = new UAParser('Mozilla/5.0 (Mobile; Windows Phone 8.1; Android 4.0; ARM; Trident/7.0; Touch; rv:11.0; IEMobile/11.0; NOKIA; Lumia 635) like iPhone OS 7_0_3 Mac OS X AppleWebKit/537 (KHTML, like Gecko) Mobile Safari/537');
+
+uap.getBrowser().name;              // "IEMobile"
+uap.getBrowser().is("IEMobile");    // true
+uap.getCPU().is("ARM");             // true
+
+uap.getOS().name;                   // "Windows Phone"
+uap.getOS().is("Windows Phone");    // true
+
+uap.getDevice();                    // { vendor: "Nokia", model: "Lumia 635", type: "mobile" }
+uap.getResult().device;             // { vendor: "Nokia", model: "Lumia 635", type: "mobile" }
+
+const device = uap.getDevice();
+device.is("mobile");                // true
+device.is("Lumia 635");             // true
+device.is("Nokia");                 // true
+device.is("iPhone");                // false
+uap.getResult().device.is("Nokia"); // true
+uap.getResult().device.model;       // "Lumia 635"
+
+uap.setUA("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36");
+
+const browser = uap.getBrowser();
+browser.is("IEMobile");             // false 
+browser.is("Chrome");               // true
+
+uap.getResult().browser.is("Edge"); // false
+uap.getResult().os.name             // "Mac OS"
+uap.getResult().os.is("Mac OS");    // true
+uap.getResult().os.version;         // "10.6.8"
+
+const engine = uap.getEngine();
+engine.is("Blink");                 // true
+```

docs/v2/api/idata/to-string.md

@@ -0,0 +1,42 @@
+# `toString():string`
+
+Retrieve full-name values as a string
+
+::: info
+Values will be concatenated following this pattern:
+* browser : `name` + `version`
+* cpu : `architecture`
+* device : `vendor` + `model`
+* engine : `name` + `version`
+* os : `name` + `version`
+:::
+
+## Code Example
+
+```js
+// Usage examples
+
+let uap = new UAParser('Mozilla/5.0 (Mobile; Windows Phone 8.1; Android 4.0; ARM; Trident/7.0; Touch; rv:11.0; IEMobile/11.0; NOKIA; Lumia 635) like iPhone OS 7_0_3 Mac OS X AppleWebKit/537 (KHTML, like Gecko) Mobile Safari/537');
+
+uap.getDevice();                    // { 
+                                    //    vendor: "Nokia", 
+                                    //    model: "Lumia 635", 
+                                    //    type: "mobile"
+                                    // }
+uap.getDevice().toString();         // "Nokia Lumia 635"
+
+uap.getResult().os.name;            // "Windows Phone"
+uap.getResult().os.version;         // "8.1"
+uap.getResult().os.toString();      // "Windows Phone 8.1"
+
+uap.setUA("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36");
+uap.getBrowser().name;              // "Chrome"
+uap.getBrowser().version;           // "28.0.1500.95"
+uap.getBrowser().major;             // "28"
+uap.getBrowser().toString();        // "Chrome 28.0.1500.95"
+
+let engine = uap.getEngine();
+engine.name;                        // "Blink"
+engine.version;                     // "28.0.1500.95"
+engine.toString();                  // "Blink 28.0.1500.95"
+```

docs/v2/api/idata/with-client-hints.md

@@ -0,0 +1,74 @@
+# `withClientHints():Promise<IData>|Thenable<IData>|IData`
+
+Recently, Chrome limits the information that exposed through user-agent and introduces a new experimental set of data called ["Client Hints"↗](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API). 
+
+Chrome also sends this client-hints data by default under `Sec-CH-UA-*` HTTP headers in each request, along with the legacy `User-Agent` HTTP header. In server-side development, you can capture this extra information by passing the `req.headers` to `UAParser()` (see examples below). 
+
+In browser-environment, obtaining the client-hints data via JavaScript must be done in an asynchronous way. You can chain the result object from `get*` method with `withClientHints()` to also read the client-hints data from the browser which will return the updated data in a `Promise`.
+
+::: info 
+In Node.js or in browser-environment without client-hints support (basically anything that's not Chromium-based), `withClientHints()` will return the updated data as a new object instead of as a `Promise`.
+:::
+
+## Code Example
+
+### Client-side Example
+
+```js
+(async function () {  
+    const ua = new UAParser();
+
+    // get browser data from user-agent only :
+    let browser = ua.getBrowser();
+    console.log('Using User-Agent: ', browser);
+
+    // get browser data from client-hints 
+    // (with user-agent as a fallback) :
+    browser = await ua.getBrowser().withClientHints();
+    console.log('Using Client-Hints: ', browser);
+})();
+```
+```js
+// alternatively without async-await:
+const ua = new UAParser();
+
+ua.getBrowser().withClientHints().then(function (browser) {
+    console.log('Using Client-Hints: ', browser);
+});
+```
+
+### Server-side Example
+
+```js
+// Suppose we got a request having these HTTP headers: 
+const request = {
+    headers : {
+        'user-agent' : 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36',
+
+        'sec-ch-ua-mobile' : '?1',
+        'sec-ch-ua-model' : 'Galaxy S3 Marketing',
+        'sec-ch-ua-platform' : 'Android'
+    }
+};
+
+// parse only "user-agent" header
+const result1 = UAParser(request.headers);
+
+// also use "sec-ch-ua" headers, in addition to "user-agent"
+const result2 = UAParser(request.headers).withClientHints();    
+
+console.log(result1.os.name);       // "Linux"
+console.log(result1.device.type);   // undefined
+console.log(result1.device.model);  // undefined
+
+console.log(result2.os.name);       // "Android"
+console.log(result2.device.type);   // "mobile"
+console.log(result2.device.model);  // "Galaxy S3 Marketing"
+
+new UAParser(request.headers)
+        .getBrowser()
+        .withClientHints()
+        .then((browser) => {
+    console.log(browser.toString());    // Chrome 110.0.0.0 
+});
+```

docs/v2/api/idata/with-feature-check.md

@@ -0,0 +1,19 @@
+# withFeatureCheck():IData`
+
+This method allows us to examine other features beyond `navigator.userAgent`. Currently this further improve the detection of the following:
+
+- browser : 
+    - Brave (check for `navigator.isBrave`)
+- device  : 
+    - iPad (check for `navigator.standalone` & `navigator.maxTouchPoints`)
+
+## Code Example
+
+```js
+// suppose this code runs on iPad
+const withoutFeatureCheck = UAParser();
+const withFeatureCheck = UAParser().withFeatureCheck();
+
+console.log(withoutFeatureCheck.device); // { vendor : "Apple", model : "Macintosh", type : undefined }
+console.log(withFeatureCheck.device);    // { vendor : "Apple", model : "iPad", type : "tablet" }
+```

docs/v2/api/ua-parser-js/get-browser.md

@@ -0,0 +1,55 @@
+# getBrowser():IData
+
+Get browser name, full version, & major version from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ name: '', version: '', major: '' }
+```
+
+## `name:string`
+
+```sh
+# List of possible `browser.name`:
+2345Explorer, 360 Browser, Amaya, Android Browser, Arora, 
+Avant, Avast, AVG, BIDUBrowser, Baidu, Basilisk, Blazer, 
+Bolt, Brave, Bowser, Camino, Chimera, [Mobile] Chrome 
+[Headless/WebView], Chromium, Cobalt, Comodo Dragon, 
+Dillo, Dolphin, Doris, DuckDuckGo, Edge, Electron, 
+Epiphany, Facebook, Falkon, Fennec, Firebird, [Mobile] 
+Firefox [Focus/Reality], Flock, Flow, GSA, GoBrowser, 
+HeyTap, Huawei Browser, ICE Browser, IE, IEMobile, 
+IceApe, IceCat, IceDragon, Iceweasel, Instagram, Iridium, 
+Iron, Jasmine, Kakao[Story/Talk], K-Meleon, Kindle, Klar, 
+Konqueror, LBBROWSER, Line, LinkedIn, Links, Lunascape, 
+Lynx, MIUI Browser, Maemo Browser, Maemo, Maxthon, MetaSr,
+Midori, Minimo, Mosaic, Mozilla, NetFront, NetSurf, 
+Netfront, Netscape, NokiaBrowser, Obigo, Oculus Browser, 
+OmniWeb, Opera Coast, Opera [Mini/Mobi/Tablet], PaleMoon, 
+PhantomJS, Phoenix, Polaris, Puffin, QQ, QQBrowser, 
+QQBrowserLite, Quark, QupZilla, RockMelt, [Mobile] Safari, 
+Sailfish Browser, Samsung Browser, SeaMonkey, Silk, 
+Skyfire, Sleipnir, Slim, SlimBrowser, Swiftfox, Tesla, 
+TikTok, Tizen Browser, UCBrowser, UP.Browser, Viera, Vivaldi, 
+Waterfox, WeChat, Weibo, Yandex, baidu, iCab, w3m, 
+Whale Browser, ...
+```
+
+## `version:string`
+
+Determined dynamically
+
+## `major:string`
+
+Major number of `version` following [semver↗](https://semver.org/), eg: if we have version `5.1.21214` the major would be `5`.
+
+
+## Code Example
+
+```js
+const operamini = 'Opera/9.80 (J2ME/MIDP; Opera Mini/5.1.21214/19.916; U; en) Presto/2.5.25'
+const parser = new UAParser(operamini);
+
+console.log(parser.getBrowser());
+// { name : "Opera Mini", version : "5.1.21214", major : "5" }
+```

docs/v2/api/ua-parser-js/get-cpu.md

@@ -0,0 +1,30 @@
+# getCPU():IData
+
+Get type of CPU architecture from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ architecture: '' }
+```
+
+## `architecture:string`
+
+```sh
+# List of possible values for `cpu.architecture`
+68k, amd64, arm[64/hf], avr, ia[32/64], irix[64], 
+mips[64], pa-risc, ppc, sparc[64]
+```
+
+::: info
+Our convention here for 32-bit version of **'x86'** is referred as `ia32`, while its 64-bit extension (also known as **'x86-64'** or simply **'x64'**) is referred as `amd64`.
+:::
+
+## Code Example
+
+```js
+const powerpc = 'Mozilla/4.0 (compatible; MSIE 5.17; Mac_PowerPC Mac OS; en)'
+const parser = new UAParser(powerpc);
+
+console.log(parser.getCPU());
+// { architecture : "ppc" }
+```

docs/v2/api/ua-parser-js/get-device.md

@@ -0,0 +1,47 @@
+# getDevice():IData
+
+Get details of device information (type, vendor, model) from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ type: '', vendor: '', model: '' }
+```
+
+## `type:string`
+
+```sh
+# List of possible values for `device.type`:
+mobile, tablet, smarttv, console, wearable, embedded
+```
+
+::: info
+If you wish to detect desktop devices, you must handle the logic yourself, since `UAParser` only reports info that is directly available from user-agent string. Read more about this issue [here↗](https://github.com/faisalman/ua-parser-js/issues/182)
+:::
+
+## `vendor:string`
+
+```sh
+# List of possible `device.vendor`:
+Acer, Alcatel, Amazon, Apple, Archos, ASUS, AT&T, BenQ,
+BlackBerry, Dell, Essential, Facebook, Fairphone, GeeksPhone,
+Google, HP, HTC, Huawei, Jolla, Kobo, Lenovo, LG, Meizu,
+Microsoft, Motorola, Nexian, Nintendo, Nokia, Nvidia, OnePlus, 
+OPPO, Ouya, Palm, Panasonic, Pebble, Polytron, Realme, RIM, 
+Roku, Samsung, Sharp, Siemens, Sony[Ericsson], Sprint, Tesla, 
+Vivo, Vodafone, Xbox, Xiaomi, Zebra, ZTE, ...
+```
+
+## `model:string`
+
+Determined dynamically
+
+## Code Example
+
+```js
+
+const galaxytabs8 = 'Mozilla/5.0 (Linux; Android 12; SM-X706B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36'
+const parser = new UAParser(galaxytabs8);
+
+console.log(parser.getDevice());
+// { type : "tablet", vendor : "Samsung", model : "SM-X706B" }
+```

docs/v2/api/ua-parser-js/get-engine.md

@@ -0,0 +1,31 @@
+# getEngine():IData
+
+Get layout rendering engine name & version from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ name: '', version: '' }
+```
+
+## `name:string`
+
+```sh
+# List of possible value of `engine.name`
+Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, 
+KHTML, LibWeb, Links, Lynx, NetFront, NetSurf, 
+Presto, Tasman, Trident, w3m, WebKit
+```
+
+## `version:string`
+
+Determined dynamically
+
+## Code Example
+
+```js
+const operamini = 'Opera/9.80 (J2ME/MIDP; Opera Mini/5.1.21214/19.916; U; en) Presto/2.5.25'
+const parser = new UAParser(operamini);
+
+console.log(parser.getEngine());
+// { name : "Presto", version : "2.5.25" }
+```

docs/v2/api/ua-parser-js/get-os.md

@@ -0,0 +1,38 @@
+# getOS():IData
+
+Get operating system name & version from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ name: '', version: '' }
+```
+
+## `name:string`
+
+```sh
+# List of possible values for `os.name`
+AIX, Amiga OS, Android[-x86], Arch, Bada, BeOS, BlackBerry, CentOS, Chromium OS,
+Contiki, Fedora, Firefox OS, FreeBSD, Debian, Deepin, DragonFly, elementary OS, 
+Fuchsia, Gentoo, GhostBSD, GNU, Haiku, HarmonyOS, HP-UX, Hurd, iOS, Joli, KaiOS, 
+Linpus, Linspire,Linux, Mac OS, Maemo, Mageia, Mandriva, Manjaro, MeeGo, Minix, 
+Mint, Morph OS, NetBSD, NetRange, NetTV, Nintendo, OpenBSD, OpenVMS, OS/2, Palm, 
+PC-BSD, PCLinuxOS, Plan9, PlayStation, QNX, Raspbian, RedHat, RIM Tablet OS, 
+RISC OS, Sabayon, Sailfish, SerenityOS, Series40, Slackware, Solaris, SUSE, Symbian, 
+Tizen, Ubuntu, Unix, VectorLinux, Viera, watchOS, WebOS, Windows [Phone/Mobile], 
+Zenwalk, ...
+```
+
+## `version:string` 
+
+Determined dynamically
+
+## Code Example
+
+```js
+
+const galaxytabs8 = 'Mozilla/5.0 (Linux; Android 12; SM-X706B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36'
+const parser = new UAParser(galaxytabs8);
+
+console.log(parser.getOS());
+// { name : "Android", version : "12" }
+```

docs/v2/api/ua-parser-js/get-result.md

@@ -0,0 +1,90 @@
+# getResult():IData
+
+Get all information regarding browser, CPU, device, engine, & OS from user-agent string.
+
+```js
+// Result object is structured as follow:
+{ 
+    ua: "", 
+    browser: { 
+        name: "", 
+        version: "",
+        major: ""
+    }, 
+    cpu: {
+        architecture: ""
+    }, 
+    device: {
+        type: "",
+        vendor: "",
+        model: ""
+    }, 
+    engine: {
+        name: "",
+        version: ""
+    }, 
+    os: {
+        name: "",
+        version: ""
+    }
+}
+```
+
+## `ua:string`
+
+The user-agent string value of current instance.
+
+## [`browser:IData`](/api/ua-parser-js/get-browser)
+
+Object that contains the value of browser name, full version, & major version.
+
+## [`cpu:IData`](/api/ua-parser-js/get-cpu)
+
+Object that contains the value of type of CPU architecture.
+
+## [`device:IData`](/api/ua-parser-js/get-device)
+
+Object that contains the value of device details: type, vendor, model.
+
+## [`engine:IData`](/api/ua-parser-js/get-engine)
+
+Object that contains the value of layout rendering engine name & version.
+
+## [`os:IData`](/api/ua-parser-js/get-os)
+
+Object that contains the value of operating system name & version.
+
+## Code Example
+
+```js
+const galaxytabs8 = 'Mozilla/5.0 (Linux; Android 12; SM-X706B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36'
+const parser = new UAParser(galaxytabs8);
+
+console.log(parser.getResult());
+/*
+{ 
+    ua: "Mozilla/5.0 (Linux; Android 12; SM-X706B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36", 
+    browser: { 
+        name: "Chrome", 
+        version: "103.0.5060.53",
+        major: "103"
+    }, 
+    cpu: {
+        architecture: undefined
+    }, 
+    device: {
+        type: "mobile",
+        vendor: "Huawei",
+        model: "SM-X706B"
+    },
+    engine: {
+        name: "Blink",
+        version: "103.0.5060.53"
+    }, 
+    os: {
+        name: "Android",
+        version: "12"
+    }
+}
+*/
+```

docs/v2/api/ua-parser-js/get-ua.md

@@ -0,0 +1,19 @@
+# getUA():string
+
+Get user-agent string of current instance
+
+## Code Example
+
+```js
+// Try to run this code on a browser
+const parser = new UAParser();
+
+// This will print the user-agent of current browser
+console.log(parser.getUA());
+
+// Replace the user-agent value
+parser.setUA('Mozilla/5.0 MyBrowser/1.0');
+
+parser.getUA();
+// "Mozilla/5.0 MyBrowser/1.0"
+```

docs/v2/api/ua-parser-js/overview.md

@@ -0,0 +1,90 @@
+# UAParser Class Overview
+
+## Constructor
+
+### `new UAParser([user-agent:string][,extensions:object][,headers:object]):UAParser`
+
+When called with the `new` keyword, it will return a new instance of `UAParser`.
+
+```js
+const parser = new UAParser("your user-agent here"); // you need to pass the user-agent for nodejs
+console.log(parser); 
+/* 
+    {}
+*/
+
+const parserResults = parser.getResult();
+console.log(parserResults);
+/* 
+    {
+        ua      : "",
+        browser : {},
+        engine  : {},
+        os      : {},
+        device  : {},
+        cpu     : {}
+    }
+*/
+```
+
+### `UAParser([user-agent:string][,extensions:object][,headers:object]):IData`
+
+When called without the `new` keyword, it will directly return the results of `getResult()`:
+
+```js
+const parser = UAParser("your user-agent here");
+console.log(parser);
+/* 
+    {
+        ua      : "",
+        browser : {},
+        engine  : {},
+        os      : {},
+        device  : {},
+        cpu     : {}
+    }
+*/
+```
+
+::: tip
+In **browser** environment you don't need to pass the user-agent string, as it should automatically get the string from the current `window.navigator.userAgent`.
+:::
+
+::: tip
+In **Node.js** environment, user-agent string must be passed in order for the function to work. Usually you can find it in: `request.headers["user-agent"]`.
+:::
+
+## Methods
+The methods are self explanatory, here's a small overview of available methods:
+
+### [`getBrowser():IData`](/api/ua-parser-js/get-browser)
+ 
+returns the browser name, version, and major.
+
+### [`getCPU():IData`](/api/ua-parser-js/get-cpu)
+ 
+returns CPU architectural design name.
+
+### [`getDevice():IData`](/api/ua-parser-js/get-device)
+ 
+returns the device model, type, vendor.
+ 
+### [`getEngine():IData`](/api/ua-parser-js/get-engine)
+ 
+returns the browser engine name and version.
+ 
+### [`getOS():IData`](/api/ua-parser-js/get-os)
+ 
+returns the operating system name and version.
+ 
+### [`getResult():IData`](/api/ua-parser-js/get-result)
+ 
+returns all function object calls, user-agent string, browser info, cpu, device, engine, os.
+
+### [`getUA():string`](/api/ua-parser-js/get-ua)
+ 
+returns the user-agent string.
+ 
+### [`setUA(ua:string):UAParser`](/api/ua-parser-js/set-ua)
+ 
+set a custom user-agent string to be parsed.

docs/v2/api/ua-parser-js/set-ua.md

@@ -0,0 +1,19 @@
+# setUA(ua:string):UAParser
+
+Set user-agent string to be parsed, returns current instance
+
+## Code Example
+
+```js
+// Try to run this code on a browser
+const parser = new UAParser();
+
+// This will print the user-agent of current browser
+console.log(parser.getUA());
+
+// Replace the user-agent value
+parser.setUA('Mozilla/5.0 MyBrowser/1.0');
+
+parser.getUA();
+// "Mozilla/5.0 MyBrowser/1.0"
+```