From 399d64a5a8b7085e30ab5360256030229a4b3270 Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Tue, 8 Jan 2019 11:32:06 +0100 Subject: [PATCH 1/6] Added typings for v2 --- index.d.ts | 317 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 index.d.ts diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 00000000..54482897 --- /dev/null +++ b/index.d.ts @@ -0,0 +1,317 @@ +// Type definitions for Bowser v2 +// Project: https://github.com/lancedikson/bowser +// Definitions by: Alexander P. Cerutti + +declare module "bowser" { + /** + * Bowser class. + * Keep it simple as much as it can be. + * It's supposed to work with collections of {@link Parser} instances + * rather then solve one-instance problems. + * All the one-instance stuff is located in Parser class. + */ + class Bowser { + constructor(); + + /** + * Creates a {@link module:parser:Parser} instance + * + * @param {String} UA UserAgent string + * @param {Boolean} [skipParsing=false] same as skipParsing for {@link Parser} + * @returns {Parser} + * @throws {Error} when UA is not a String + * + * @example + * const parser = Bowser.getParser(window.navigator.userAgent); + * const result = parser.getResult(); + */ + static getParser(UA: string, skipParsing?: boolean): Parser + + /** + * Creates a {@link Parser} instance and runs {@link Parser.getResult} immediately + * + * @param UA + * @return {ParsedResult} + * + * @example + * const result = Bowser.parse(window.navigator.userAgent); + */ + static parse(UA: string): Parser.ParsedResult + } + + /** + * The main class that arranges the whole parsing process. + */ + + class Parser { + constructor(UA: string, skipParsing?: boolean); + + /** + * Get parsed browser object + * @return {Parser.BrowserDetails} Browser's details + */ + + getBrowser(): Parser.BrowserDetails; + + /** + * Get browser's name + * @return {String} Browser's name or an empty string + */ + + getBrowserName(): string; + + /** + * Get browser's version + * @return {String} version of browser + */ + + getBrowserVersion(): string; + + /** + * Get OS + * @return {Parser.OSDetails} - OS Details + * + * @example + * this.getOS(); // { + * // name: 'macOS', + * // version: '10.11.12', + * // } + */ + + getOS(): Parser.OSDetails; + + /** + * Get OS name + * @param {Boolean} [toLowerCase] return lower-cased value + * @return {String} name of the OS — macOS, Windows, Linux, etc. + */ + + getOSName(toLowerCase?: boolean): string; + + /** + * Get OS version + * @return {String} full version with dots ('10.11.12', '5.6', etc) + */ + + getOSVersion(): string; + + /** + * Get parsed platform + * @returns {Parser.PlatformDetails} + */ + + getPlatform(): Parser.PlatformDetails; + + /** + * Get platform name + * @param {boolean} toLowerCase + */ + + getPlatformType(toLowerCase?: boolean): string; + + /** + * Get parsed engine + * @returns {Parser.EngineDetails} + */ + + getEngine(): Parser.EngineDetails; + + /** + * Get parsed result + * @return {Parser.ParsedResult} + */ + + getResult(): Parser.ParsedResult; + + /** + * Get UserAgent string of current Parser instance + * @return {String} User-Agent String of the current object + */ + + getUA(): string; + + /** + * Is anything? Check if the browser is called "anything", + * the OS called "anything" or the platform called "anything" + * @param {String} anything + * @returns {Boolean} + */ + + is(anything: any): boolean; + + /** + * Parse full information about the browser + */ + + parse(): void; + + /** + * Get parsed browser object + * @returns {Parser.BrowserDetails} + */ + + parseBrowser(): Parser.BrowserDetails; + + /** + * Get parsed engine + * @returns {Parser.EngineDetails} + */ + + parseEngine(): Parser.EngineDetails; + + /** + * Parse OS and save it to this.parsedResult.os + * @returns {Parser.OSDetails} + */ + + parseOS(): Parser.OSDetails; + + /** + * Get parsed platform + * @returns {Parser.PlatformDetails} + */ + + parsePlatform(): Parser.PlatformDetails; + + /** + * Check if parsed browser matches certain conditions + * + * @param {Parser.checkTree} checkTree It's one or two layered object, + * which can include a platform or an OS on the first layer + * and should have browsers specs on the bottom-laying layer + * + * @returns {Boolean|undefined} Whether the browser satisfies the set conditions or not. + * Returns `undefined` when the browser is no described in the checkTree object. + * + * @example + * const browser = new Bowser(UA); + * if (browser.check({chrome: '>118.01.1322' })) + * // or with os + * if (browser.check({windows: { chrome: '>118.01.1322' } })) + * // or with platforms + * if (browser.check({desktop: { chrome: '>118.01.1322' } })) + */ + + satisfies(checkTree: Parser.checkTree): boolean | undefined; + + /** + * Check if any of the given values satifies `.is(anything)` + * @param {string[]} anythings + * @returns {boolean} true if at least one condition is satisfied, false otherwise. + */ + + some(anythings: string[]): boolean | undefined; + + /** + * Test a UA string for a regexp + * @param regex + * @returns {boolean} true if the regex matches the UA, false otherwise. + */ + + test(regex: RegExp): boolean + } + + namespace Parser { + interface ParsedResult { + browser: Details; + os: OSDetails; + platform: PlatformDetails; + engine: Details; + } + + interface Details { + name?: string; + version?: Array<{index: number, input: string} | boolean | string | any>; + } + + interface OSDetails extends Details { + versionName?: string; + } + + interface PlatformDetails { + type?: string; + vendor?: string; + model?: string; + } + + type BrowserDetails = Details; + type EngineDetails = Details; + + interface checkTree { + [key: string]: any; + } + } + + class Utils { + /** + * Get first matched item for a string + * @param {RegExp} regexp + * @param {String} ua + * @return {Array|{index: number, input: string}|*|boolean|string} + */ + static getFirstMatch(regexp: RegExp, ua: string): Array<{index: number, input: string} | boolean | string | any>; + /** + * Get second matched item for a string + * @param regexp + * @param {String} ua + * @return {Array|{index: number, input: string}|*|boolean|string} + */ + static getSecondMatch(regexp: RegExp, ua: string): Array<{index: number, input: string} | boolean | string | any>; + + /** + * Match a regexp and return a constant or undefined + * @param {RegExp} regexp + * @param {String} ua + * @param {*} _const Any const that will be returned if regexp matches the string + * @return {*} + */ + static matchAndReturnConst(regexp: RegExp, ua: string, _const: any): any | undefined; + + /** + * Retrieves Windows commercial name from NT Core version name + * @param {string} version + * @returns {string | undefined} + */ + static getWindowsVersionName(version: string): string | undefined; + + /** + * Get version precisions count + * + * @example + * getVersionPrecision("1.10.3") // 3 + * + * @param {string} version + * @return {number} + */ + static getVersionPrecision(version: string): number + + /** + * Calculate browser version weight + * + * @example + * compareVersions('1.10.2.1', '1.8.2.1.90') // 1 + * compareVersions('1.010.2.1', '1.09.2.1.90'); // 1 + * compareVersions('1.10.2.1', '1.10.2.1'); // 0 + * compareVersions('1.10.2.1', '1.0800.2'); // -1 + * compareVersions('1.10.2.1', '1.10', true); // 0 + * + * @param {String} versionA versions versions to compare + * @param {String} versionB versions versions to compare + * @param {boolean} [isLoose] enable loose comparison + * @return {Number} comparison result: -1 when versionA is lower, + * 1 when versionA is bigger, 0 when both equal + */ + static compareVersions(versionA: string, versionB: string, isLoose?: boolean): number; + + /** + * Array::map polyfill + * + * @param {Array} arr + * @param {Function} iterator + * @return {Array} + */ + static map(arr: Array, iterator: Function): Array + } + + export = Bowser; +} From 2c13c9a528e2cff36c98b9dce21d100c7e6942c1 Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Thu, 10 Jan 2019 00:07:06 +0100 Subject: [PATCH 2/6] Update package.json Issue #229 about npm deprecation note fix --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 3187dabf..2b24c078 100644 --- a/package.json +++ b/package.json @@ -64,7 +64,7 @@ }, "scripts": { "build": "webpack --config webpack.config.js", - "prepublish": "npm run build", + "prepublishOnly": "npm run build", "lint": "eslint ./src", "testem": "testem", "test": "nyc --reporter=html --reporter=text ava", From 3d63c268f488259fa542d7dda47dd66928af4644 Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Thu, 10 Jan 2019 00:34:21 +0100 Subject: [PATCH 3/6] Update .travis.yml Updated travis.yml to execute run-script build --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index c8d60f2c..b97350fa 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,5 +4,5 @@ node_js: - "8.4.0" script: - npm run lint -- npm build +- npm run build - npm test From e17180a6a8ad8ca5e7e38ee79f9bc074faa93ca1 Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Fri, 11 Jan 2019 23:41:59 +0100 Subject: [PATCH 4/6] Updated Readme to include typescript import --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1af61bed..7e966409 100644 --- a/README.md +++ b/README.md @@ -20,14 +20,15 @@ The upcoming 2.0 version has drastically changed API. All available methods can # Use cases -First of all, require the library: +First of all, require the library. This is a UMD Module, so it will work for AMD, Typescript and CommonJS module systems. ```javascript -const bowser = require('bowser'); +const Bowser = require('bowser'); // CommonJS + +import Bowser = require('bowser'); // Typescript ``` -By default, `require('bowser')` requires the *ES5 version of files*, which -**do not** include any polyfills. +By default, the exported version is the *ES5 transpiled version*, which **do not** include any polyfills. In case you don't use your own `babel-polyfill` you may need to have pre-built bundle with all needed polyfills. So, for you it's suitable to require bowser like this: `require('bowser/bundled')`. @@ -63,6 +64,7 @@ or const browser = bowser.getParser(window.navigator.userAgent); impression.userTechData = browser.parse(); console.log(impression.userTechData); + // outputs { browser: { From 93e1ff52aad922c1b1bca97682655b2916c95e8b Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Tue, 15 Jan 2019 09:42:23 +0100 Subject: [PATCH 5/6] Added a definitive-working definition for v2 --- index.d.ts | 247 +++++++++++++++++------------------------------------ 1 file changed, 77 insertions(+), 170 deletions(-) diff --git a/index.d.ts b/index.d.ts index 54482897..78108b92 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,84 +1,66 @@ // Type definitions for Bowser v2 // Project: https://github.com/lancedikson/bowser -// Definitions by: Alexander P. Cerutti +// Definitions by: Alexander P. Cerutti , + +export = Bowser; +export as namespace Bowser; + +declare namespace Bowser { -declare module "bowser" { /** - * Bowser class. - * Keep it simple as much as it can be. - * It's supposed to work with collections of {@link Parser} instances - * rather then solve one-instance problems. - * All the one-instance stuff is located in Parser class. + * Creates a Parser instance + * @param {string} UA - User agent string + * @param {boolean} skipParsing */ - class Bowser { - constructor(); - /** - * Creates a {@link module:parser:Parser} instance - * - * @param {String} UA UserAgent string - * @param {Boolean} [skipParsing=false] same as skipParsing for {@link Parser} - * @returns {Parser} - * @throws {Error} when UA is not a String - * - * @example - * const parser = Bowser.getParser(window.navigator.userAgent); - * const result = parser.getResult(); - */ - static getParser(UA: string, skipParsing?: boolean): Parser - - /** - * Creates a {@link Parser} instance and runs {@link Parser.getResult} immediately - * - * @param UA - * @return {ParsedResult} - * - * @example - * const result = Bowser.parse(window.navigator.userAgent); - */ - static parse(UA: string): Parser.ParsedResult - } + function getParser(UA: string, skipParsing?: boolean): Parser.Parser; /** - * The main class that arranges the whole parsing process. + * Creates a Parser instance and runs Parser.getResult immediately + * @param UA - User agent string + * @returns {Parser.ParsedResult} */ + function parse(UA: string): Parser.ParsedResult; +} + +declare namespace Parser { class Parser { - constructor(UA: string, skipParsing?: boolean); + constructor(UA: string, skipParsing?: boolean); /** * Get parsed browser object - * @return {Parser.BrowserDetails} Browser's details + * @return {BrowserDetails} Browser's details */ - getBrowser(): Parser.BrowserDetails; + getBrowser(): BrowserDetails; /** * Get browser's name * @return {String} Browser's name or an empty string */ - getBrowserName(): string; + getBrowserName(): string; /** * Get browser's version * @return {String} version of browser */ - getBrowserVersion(): string; + getBrowserVersion(): string; /** * Get OS - * @return {Parser.OSDetails} - OS Details + * @return {OSDetails} - OS Details * * @example * this.getOS(); // { - * // name: 'macOS', - * // version: '10.11.12', + * // name: 'macOS', + * // version: '10.11.12', * // } */ - getOS(): Parser.OSDetails; + getOS(): OSDetails; /** * Get OS name @@ -86,49 +68,49 @@ declare module "bowser" { * @return {String} name of the OS — macOS, Windows, Linux, etc. */ - getOSName(toLowerCase?: boolean): string; + getOSName(toLowerCase?: boolean): string; /** * Get OS version * @return {String} full version with dots ('10.11.12', '5.6', etc) */ - getOSVersion(): string; + getOSVersion(): string; /** * Get parsed platform - * @returns {Parser.PlatformDetails} + * @returns {PlatformDetails} */ - getPlatform(): Parser.PlatformDetails; + getPlatform(): PlatformDetails; /** * Get platform name * @param {boolean} toLowerCase */ - getPlatformType(toLowerCase?: boolean): string; + getPlatformType(toLowerCase?: boolean): string; /** * Get parsed engine - * @returns {Parser.EngineDetails} + * @returns {EngineDetails} */ - getEngine(): Parser.EngineDetails; + getEngine(): EngineDetails; /** * Get parsed result - * @return {Parser.ParsedResult} + * @return {ParsedResult} */ - getResult(): Parser.ParsedResult; + getResult(): ParsedResult; /** * Get UserAgent string of current Parser instance * @return {String} User-Agent String of the current object */ - getUA(): string; + getUA(): string; /** * Is anything? Check if the browser is called "anything", @@ -137,46 +119,46 @@ declare module "bowser" { * @returns {Boolean} */ - is(anything: any): boolean; + is(anything: any): boolean; /** * Parse full information about the browser */ - parse(): void; + parse(): void; /** * Get parsed browser object - * @returns {Parser.BrowserDetails} + * @returns {BrowserDetails} */ - parseBrowser(): Parser.BrowserDetails; + parseBrowser(): BrowserDetails; /** * Get parsed engine - * @returns {Parser.EngineDetails} + * @returns {EngineDetails} */ - parseEngine(): Parser.EngineDetails; + parseEngine(): EngineDetails; /** * Parse OS and save it to this.parsedResult.os - * @returns {Parser.OSDetails} + * @returns {OSDetails} */ - parseOS(): Parser.OSDetails; + parseOS(): OSDetails; /** * Get parsed platform - * @returns {Parser.PlatformDetails} + * @returns {PlatformDetails} */ - parsePlatform(): Parser.PlatformDetails; + parsePlatform(): PlatformDetails; /** * Check if parsed browser matches certain conditions * - * @param {Parser.checkTree} checkTree It's one or two layered object, + * @param {checkTree} checkTree It's one or two layered object, * which can include a platform or an OS on the first layer * and should have browsers specs on the bottom-laying layer * @@ -192,7 +174,7 @@ declare module "bowser" { * if (browser.check({desktop: { chrome: '>118.01.1322' } })) */ - satisfies(checkTree: Parser.checkTree): boolean | undefined; + satisfies(checkTree: checkTree): boolean | undefined; /** * Check if any of the given values satifies `.is(anything)` @@ -200,7 +182,7 @@ declare module "bowser" { * @returns {boolean} true if at least one condition is satisfied, false otherwise. */ - some(anythings: string[]): boolean | undefined; + some(anythings: string[]): boolean | undefined; /** * Test a UA string for a regexp @@ -208,110 +190,35 @@ declare module "bowser" { * @returns {boolean} true if the regex matches the UA, false otherwise. */ - test(regex: RegExp): boolean - } + test(regex: RegExp): boolean; + } - namespace Parser { - interface ParsedResult { - browser: Details; - os: OSDetails; - platform: PlatformDetails; - engine: Details; - } - - interface Details { - name?: string; - version?: Array<{index: number, input: string} | boolean | string | any>; - } - - interface OSDetails extends Details { - versionName?: string; - } - - interface PlatformDetails { - type?: string; - vendor?: string; - model?: string; - } - - type BrowserDetails = Details; - type EngineDetails = Details; - - interface checkTree { - [key: string]: any; - } - } + interface ParsedResult { + browser: BrowserDetails; + os: OSDetails; + platform: PlatformDetails; + engine: EngineDetails; + } - class Utils { - /** - * Get first matched item for a string - * @param {RegExp} regexp - * @param {String} ua - * @return {Array|{index: number, input: string}|*|boolean|string} - */ - static getFirstMatch(regexp: RegExp, ua: string): Array<{index: number, input: string} | boolean | string | any>; - /** - * Get second matched item for a string - * @param regexp - * @param {String} ua - * @return {Array|{index: number, input: string}|*|boolean|string} - */ - static getSecondMatch(regexp: RegExp, ua: string): Array<{index: number, input: string} | boolean | string | any>; - - /** - * Match a regexp and return a constant or undefined - * @param {RegExp} regexp - * @param {String} ua - * @param {*} _const Any const that will be returned if regexp matches the string - * @return {*} - */ - static matchAndReturnConst(regexp: RegExp, ua: string, _const: any): any | undefined; - - /** - * Retrieves Windows commercial name from NT Core version name - * @param {string} version - * @returns {string | undefined} - */ - static getWindowsVersionName(version: string): string | undefined; - - /** - * Get version precisions count - * - * @example - * getVersionPrecision("1.10.3") // 3 - * - * @param {string} version - * @return {number} - */ - static getVersionPrecision(version: string): number - - /** - * Calculate browser version weight - * - * @example - * compareVersions('1.10.2.1', '1.8.2.1.90') // 1 - * compareVersions('1.010.2.1', '1.09.2.1.90'); // 1 - * compareVersions('1.10.2.1', '1.10.2.1'); // 0 - * compareVersions('1.10.2.1', '1.0800.2'); // -1 - * compareVersions('1.10.2.1', '1.10', true); // 0 - * - * @param {String} versionA versions versions to compare - * @param {String} versionB versions versions to compare - * @param {boolean} [isLoose] enable loose comparison - * @return {Number} comparison result: -1 when versionA is lower, - * 1 when versionA is bigger, 0 when both equal - */ - static compareVersions(versionA: string, versionB: string, isLoose?: boolean): number; - - /** - * Array::map polyfill - * - * @param {Array} arr - * @param {Function} iterator - * @return {Array} - */ - static map(arr: Array, iterator: Function): Array - } + interface Details { + name?: string; + version?: string; + } + + interface OSDetails extends Details { + versionName?: string; + } + + interface PlatformDetails { + type?: string; + vendor?: string; + model?: string; + } - export = Bowser; + type BrowserDetails = Details; + type EngineDetails = Details; + + interface checkTree { + [key: string]: any; + } } From 35814130fd8793acb94f65592818d2a7e56af2ba Mon Sep 17 00:00:00 2001 From: Alexander Cerutti Date: Tue, 15 Jan 2019 09:43:08 +0100 Subject: [PATCH 6/6] Updated Readme upon the changes to typings --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7e966409..9e29590d 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,9 @@ The upcoming 2.0 version has drastically changed API. All available methods can First of all, require the library. This is a UMD Module, so it will work for AMD, Typescript and CommonJS module systems. ```javascript -const Bowser = require('bowser'); // CommonJS +const Bowser = require("bowser"); // CommonJS -import Bowser = require('bowser'); // Typescript +import * as Bowser from "bowser" // Typescript ``` By default, the exported version is the *ES5 transpiled version*, which **do not** include any polyfills.