baseline-browser-mapping 2.1.1 → 2.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 By the [W3C WebDX Community Group](https://www.w3.org/community/webdx/) and contributors.
 
-`baseline-browser-mapping` exposes arrays of browsers compatible with Baseline Widely Available and specified Baseline year feature sets.
+`baseline-browser-mapping` exposes arrays of browsers compatible with Baseline Widely available and specified Baseline year feature sets.
 You can use `baseline-browser-mapping` to help you determine minimum browser version support for your chosen Baseline feature set.
 
 ## Prerequisites
@@ -25,11 +25,9 @@ To install the package, run:
 ]
 ```
 
-## Usage
+## Get Baseline Widely available browser versions or Baseline year browser versions
 
-### Get Baseline Widely Available browser versions
-
-To get the current list of minimum browser versions compatible with Baseline Widely Available features from the core browser set, call the `getCompatibleVersions()` function with:
+To get the current list of minimum browser versions compatible with Baseline Widely available features from the core browser set, call the `getCompatibleVersions()` function:
 
 ```javascript
 import { getCompatibleVersions } from "baseline-browser-mapping";
@@ -64,9 +62,9 @@ Executed on 7th March 2025, the above code returns the following browser version
 ```
 
 > [!NOTE]  
-> The minimum versions of each browser are not strictly the final release before the Widely Available cutoff date of `TODAY - 30 MONTHS`. Some earlier versions will have supported the full Widely Available feature set.
+> The minimum versions of each browser are not strictly the final release before the Widely available cutoff date of `TODAY - 30 MONTHS`. Some earlier versions will have supported the full Widely available feature set.
 
-### Configuration options
+### `getCompatibleVersions()` configuration options
 
 `getCompatibleVersions()` accepts an `Object` as an argument with configuration options. The defaults are as follows:
 
@@ -81,7 +79,7 @@ Executed on 7th March 2025, the above code returns the following browser version
 
 #### `targetYear`
 
-The `targetYear` option returns the minimum browser versions compatible with all interoperable features at the end of the specific calendar year. For example, calling:
+The `targetYear` option returns the minimum browser versions compatible with all **Baseline Newly available** features at the end of the specified calendar year. For example, calling:
 
 ```javascript
 getCompatibleVersions({
@@ -118,7 +116,7 @@ Returns the following versions:
 
 #### `widelyAvailableOnDate`
 
-The `widelyAvailableOnDate` options returns the minimum versions compatible with Baseline Widely Available on a specified date in the formay `YYYY-MM-DD`:
+The `widelyAvailableOnDate` option returns the minimum versions compatible with Baseline Widely available on a specified date in the formay `YYYY-MM-DD`:
 
 ```javascript
 getCompatibleVersions({
@@ -127,7 +125,7 @@ getCompatibleVersions({
 ```
 
 > [!TIP]  
-> This can be particularly useful if you provide a versioned library that target Baseline Widely Available on each version's release date and want to provide a table of minimum supported browsers in your documentation.
+> This option is useful if you provide a versioned library that targets Baseline Widely available on each version's release date and you need to provide a statement on minimum supported browser versions in your documentation.
 
 #### `includeDownstreamBrowsers`
 
@@ -143,7 +141,7 @@ For more information on downstream browsers, see [the section on downstream brow
 
 #### `listAllCompatibleVersions`
 
-If you need a list of all compatible versions, pass an object with the `listAllCompatibleVersions` :
+Setting `listAllCompatibleVersions` to true will include the minimum versions of each compatible browser, and all the subsequent versions:
 
 ```javascript
 getCompatibleVersions({
@@ -151,6 +149,150 @@ getCompatibleVersions({
 });
 ```
 
+## Get data for all browser versions
+
+You may want to obtain data on all the browser versions available in this module for use in an analytics solution or dashboard. To get details of each browser version's level of Baseline support, call the `getAllVersions()` function:
+
+```javascript
+import { getAllVersions } from "baseline-browser-mapping";
+
+getAllVersions();
+```
+
+By default, this function returns an `Array` of `Objects` and excludes downstream browsers:
+
+```javascript
+[
+  ...
+  {
+    browser: 'chrome_android', // Browser name
+    version: '68', // Browser version as a string
+    release_date: '2018-07-24', // Release date
+    year: 2019, //Baseline year feature set the version supports
+    waCompatible: false // Boolean indicating whether the version is compatible with Baseline Widely available
+  },
+  ...
+]
+```
+
+### `getAllVersions()` Configuration options
+
+`getAllVersions()` accepts an `Object` as an argument with configuration options. The defaults are as follows:
+
+```javascript
+{
+  includeDownstreamBrowsers: false,
+  outputFormat: "array"
+}
+```
+
+#### `includeDownstreamBrowsers` (in `getAllVersions()` output)
+
+As with `getCompatibleVersions()`, you can set `includeDownstreamBrowsers` to `true` to include the Chromium downstream browsers [listed below](#list-of-downstream-browsers).
+
+```javascript
+getAllVersions({
+  includeDownstreamBrowsers: true,
+});
+```
+
+Downstream browsers include the same properties as core browsers, as well as the `engine`they use and `engine_version`, for example:
+
+```javascript
+[
+  ...
+  {
+    "browser": "samsunginternet_android",
+    "version": "18.0",
+    "release_date": "2022-08-08",
+    "engine": "Blink",
+    "engine_version": "99",
+    "year": 2021,
+    "waCompatible": false
+  },
+  ...
+]
+```
+
+#### `outputFormat`
+
+By default, this function returns an `Array` of `Objects` which can be manipulated in Javascript or output to JSON.
+
+To return an `Object` that nests keys , set `outputFormat` to `object`:
+
+```javascript
+getAllVersions({
+  outputFormat: "object",
+});
+```
+
+In thise case, `getAllVersions()` returns a nested object with the browser [IDs listed below](#list-of-downstream-browsers) as keys, and versions as keys within them:
+
+```javascript
+{
+  "chrome": {
+    "53": {
+      "year": 2016,
+      "wa_compatible": false,
+      "release_date": "2016-09-07"
+    },
+    ...
+}
+```
+
+Downstream browsers will include extra fields for `engine` and `engine_versions`
+
+```javascript
+{
+  ...
+  "webview_android": {
+    "53": {
+      "year": 2016,
+      "waCompatible": false,
+      "release_date": "2016-09-07",
+      "engine": "Blink",
+      "engine_version": "53"
+    },
+  ...
+}
+```
+
+To return a `String` in CSV format, set `outputFormat` to `csv`:
+
+```javascript
+getAllVersions({
+  outputFormat: "csv",
+});
+```
+
+`getAllVersions` returns a `String` with a header row and comma-separated values for each browser version that you can write to a file or pass to another service. Core browsers will have "NULL" as the value for their `engine` and `engine_version`:
+
+```csv
+"browser","version","year","wa_compatible","release_date","engine","engine_version"
+"chrome","53","2016","false","2016-09-07","NULL","NULL"
+...
+"ya_android","20.12","2020","false","2020-12-20","Blink","87"
+...
+```
+
+> [!NOTE]
+> The above example uses `"includeDownstreamBrowsers": true`
+
+### Static resources
+
+The outputs of `getAllVersions()` are available as JSON or CSV files generated on a daily basis and hosted on GitHub pages:
+
+- Core browsers only
+  - [Array](https://web-platform-dx.github.io/baseline-browser-mapping/all_versions_array.json)
+  - [Object](https://web-platform-dx.github.io/baseline-browser-mapping/all_versions_object.json)
+  - [CSV](https://web-platform-dx.github.io/baseline-browser-mapping/all_versions.csv)
+- Including downstream browsers
+  - [Array](https://web-platform-dx.github.io/baseline-browser-mapping/with_downstream/all_versions_array.json)
+  - [Object](https://web-platform-dx.github.io/baseline-browser-mapping/with_downstream/all_versions_object.json)
+  - [CSV](https://web-platform-dx.github.io/baseline-browser-mapping/with_downstream/all_versions.csv)
+
+These files are updated on a daily basis.
+
 ## Downstream browsers
 
 ### Limitations
@@ -170,7 +312,7 @@ Shows UC Browser Mobile 13.8 implementing Chromium 100, and:
 
 `Mozilla/5.0 (Linux; arm_64; Android 11; Redmi Note 8 Pro) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.6613.123 YaBrowser/24.10.2.123.00 SA/3 Mobile Safari/537.36`
 
-Shows Yandex Browser Mobile 24.10 implementing Chromium 128. The Chromium version from this string is mapped to the main Chrome version from MDN `browser-compat-data`.
+Shows Yandex Browser Mobile 24.10 implementing Chromium 128. The Chromium version from this string is mapped to the corresponding Chrome version from MDN `browser-compat-data`.
 
 > [!NOTE]  
 > Where possible, approximate release dates have been included based on useragents.io "first seen" data. useragents.io does not have "first seen" dates prior to June 2020. However, these browsers' Baseline compatibility is determined by their Chromium version, so their release dates are more informative than critical.
@@ -198,7 +340,3 @@ This data is updated on a daily basis using a [script](https://github.com/web-pl
 
 > [!NOTE]  
 > All the non-core browsers currently included implement Chromium. Their inclusion in any of the above methods is based on the Baseline feature set supported by the Chromium version they implement, not their release date.
-
-## Contributing
-
-`baseline-browser-mapping` is part of the W3C WebDX Community Group's web-features project. To learn more about contributing to this module, see [CONTRIBUTING](/CONTRIBUTING.md).

package/dist/data/downstream-browsers.json

@@ -995,6 +995,12 @@
                     "engine_version": "100",
                     "status": "unknown",
                     "release_date": "2025-02-26"
+                },
+                "17.5": {
+                    "engine": "Blink",
+                    "engine_version": "100",
+                    "status": "unknown",
+                    "release_date": "2025-04-08"
                 }
             }
         },
@@ -1498,5 +1504,5 @@
             }
         }
     },
-    "lastUpdated": "2025-02-26T14:04:04.566Z"
+    "lastUpdated": "2025-04-09T14:12:33.205Z"
 }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { getCompatibleVersions } from "./scripts/baseline-browser-versions.js";
-export { getCompatibleVersions };
+import { getCompatibleVersions, getAllVersions } from "./scripts/baseline-browser-versions.js";
+export { getCompatibleVersions, getAllVersions };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { getCompatibleVersions } from "./scripts/baseline-browser-versions.js";
-export { getCompatibleVersions };
+import { getCompatibleVersions, getAllVersions, } from "./scripts/baseline-browser-versions.js";
+export { getCompatibleVersions, getAllVersions };

package/dist/scripts/baseline-browser-versions.d.ts

@@ -5,6 +5,21 @@ type BrowserVersion = {
     engine?: string;
     engine_version?: string;
 };
+interface AllBrowsersBrowserVersion extends BrowserVersion {
+    year: number;
+    wa_compatible: boolean;
+}
+type NestedBrowserVersions = {
+    [browser: string]: {
+        [version: string]: {
+            year: number;
+            wa_compatible: boolean;
+            release_date?: string;
+            engine?: string;
+            engine_version?: string;
+        };
+    };
+};
 type Options = {
     /**
      * Whether to include only the minimum compatible browser versions or all compatible versions.
@@ -18,14 +33,44 @@ type Options = {
     includeDownstreamBrowsers?: boolean;
     /**
      * Pass a date in the format 'YYYY-MM-DD' to get versions compatible with Widely available on the specified date.
-     * If left undefined and a `targetYear` is not passed, defaults to Widely Available as of the current date.
+     * If left undefined and a `targetYear` is not passed, defaults to Widely available as of the current date.
+     * > NOTE: cannot be used with `targetYear`.
      */
     widelyAvailableOnDate?: string | number;
     /**
      * Pass a year between 2016 and the current year to get browser versions compatible with all
      * Newly Available features as of the end of the year specified.
+     * > NOTE: cannot be used with `widelyAvailableOnDate`.
      */
     targetYear?: number;
 };
-export declare function getCompatibleVersions(userOptions: Options): BrowserVersion[];
+/**
+ * Returns browser versions compatible with specified Baseline targets.
+ * Defaults to returning the minimum versions of the core browser set that support Baseline Widely available.
+ * Takes an optional configuraation object `Object` with four optional properties:
+ * - `listAllCompatibleVersions`: `false` (default) or `false`
+ * - `includeDownstreamBrowsers`: `false` (default) or `false`
+ * - `widelyAvailableOnDate`: date in format `YYYY-MM-DD`
+ * - `targetYear`: year in format `YYYY`
+ */
+export declare function getCompatibleVersions(userOptions?: Options): BrowserVersion[];
+type AllVersionsOptions = {
+    /**
+     * Whether to return the output as a Javascript `Array` (`array`) or a CSV string (`csv`).
+     * Defaults to `array`.
+     */
+    outputFormat?: string;
+    /**
+     * Whether to include browsers that use the same engines as a core Baseline browser.
+     * Defaults to `false`.
+     */
+    includeDownstreamBrowsers?: boolean;
+};
+/**
+ * Returns all browser versions known to this module with their level of Baseline support either as an `Array` or a `String` CSV.
+ * Takes an object as an argument with two optional properties:
+ * - `includeDownstreamBrowsers`: `true` (default) or `false`
+ * - `outputFormat`: `array` (default), `object` or `csv`
+ */
+export declare function getAllVersions(userOptions?: AllVersionsOptions): AllBrowsersBrowserVersion[] | NestedBrowserVersions | string;
 export {};

package/dist/scripts/baseline-browser-versions.js

@@ -34,6 +34,9 @@ const stripLTEPrefix = (str) => {
     return str.slice(1);
 };
 const compareVersions = (incomingVersionString, previousVersionString) => {
+    if (incomingVersionString === previousVersionString) {
+        return 0;
+    }
     let [incomingVersionStringMajor, incomingVersionStringMinor] = incomingVersionString.split(".");
     let [previousVersionStringMajor, previousVersionStringMinor] = previousVersionString.split(".");
     if (!incomingVersionStringMajor || !previousVersionStringMajor) {
@@ -55,7 +58,7 @@ const compareVersions = (incomingVersionString, previousVersionString) => {
             return 1;
         }
     }
-    return 0;
+    return -1;
 };
 const getCompatibleFeaturesByDate = (date) => {
     const compatibleFeatures = new Array();
@@ -133,8 +136,8 @@ const getSubsequentVersions = (minimumVersions) => {
     return subsequentVersions;
 };
 const getCoreVersionsByDate = (date, listAllCompatibleVersions = false) => {
-    if (date.getFullYear() < 2015) {
-        throw new Error("There are no browser versions compatible with Baseline before 2015");
+    if (date.getFullYear() < 2016) {
+        throw new Error("There are no browser versions compatible with Baseline before 2016");
     }
     if (date.getFullYear() > new Date().getFullYear()) {
         throw new Error("There are no browser versions compatible with Baseline in the future");
@@ -195,25 +198,33 @@ const getDownstreamBrowsers = (inputArray = [], listAllCompatibleVersions = true
             const versionEntry = sortedAndFilteredVersions[i];
             if (versionEntry) {
                 const [versionNumber, versionData] = versionEntry;
-                let outputObject = {
+                let outputArray = {
                     browser: browserName,
                     version: versionNumber,
                     release_date: versionData.release_date ?? "unknown",
                 };
                 if (versionData.engine && versionData.engine_version) {
-                    outputObject.engine = versionData.engine;
-                    outputObject.engine_version = versionData.engine_version;
+                    outputArray.engine = versionData.engine;
+                    outputArray.engine_version = versionData.engine_version;
                 }
-                downstreamArray.push(outputObject);
+                downstreamArray.push(outputArray);
                 if (!listAllCompatibleVersions) {
                     break;
                 }
             }
         }
     });
-    let outputArray = [...inputArray, ...downstreamArray];
-    return outputArray;
+    return downstreamArray;
 };
+/**
+ * Returns browser versions compatible with specified Baseline targets.
+ * Defaults to returning the minimum versions of the core browser set that support Baseline Widely available.
+ * Takes an optional configuraation object `Object` with four optional properties:
+ * - `listAllCompatibleVersions`: `false` (default) or `false`
+ * - `includeDownstreamBrowsers`: `false` (default) or `false`
+ * - `widelyAvailableOnDate`: date in format `YYYY-MM-DD`
+ * - `targetYear`: year in format `YYYY`
+ */
 export function getCompatibleVersions(userOptions) {
     let incomingOptions = userOptions ?? {};
     let options = {
@@ -238,13 +249,137 @@ export function getCompatibleVersions(userOptions) {
     }
     // Sets a cutoff date for feature interoperability 30 months before the stated date
     if (options.widelyAvailableOnDate || options.targetYear === undefined) {
-        targetDate.setMonth(new Date().getMonth() - 30);
+        targetDate.setMonth(targetDate.getMonth() - 30);
     }
     let coreBrowserArray = getCoreVersionsByDate(targetDate, options.listAllCompatibleVersions);
     if (options.includeDownstreamBrowsers === false) {
         return coreBrowserArray;
     }
     else {
-        return getDownstreamBrowsers(coreBrowserArray, options.listAllCompatibleVersions);
+        return [
+            ...coreBrowserArray,
+            ...getDownstreamBrowsers(coreBrowserArray, options.listAllCompatibleVersions),
+        ];
+    }
+}
+/**
+ * Returns all browser versions known to this module with their level of Baseline support either as an `Array` or a `String` CSV.
+ * Takes an object as an argument with two optional properties:
+ * - `includeDownstreamBrowsers`: `true` (default) or `false`
+ * - `outputFormat`: `array` (default), `object` or `csv`
+ */
+export function getAllVersions(userOptions) {
+    let incomingOptions = userOptions ?? {};
+    let options = {
+        outputFormat: incomingOptions.outputFormat ?? "array",
+        includeDownstreamBrowsers: incomingOptions.includeDownstreamBrowsers ?? false,
+    };
+    let nextYear = new Date().getFullYear() + 1;
+    const yearArray = [...Array(nextYear).keys()].slice(2016);
+    const yearMinimumVersions = {};
+    yearArray.forEach((year) => {
+        yearMinimumVersions[year] = {};
+        getCompatibleVersions({ targetYear: year }).forEach((version) => {
+            if (yearMinimumVersions[year])
+                yearMinimumVersions[year][version.browser] = version;
+        });
+    });
+    const waMinimumVersions = getCompatibleVersions({});
+    const waObject = {};
+    waMinimumVersions.forEach((version) => {
+        waObject[version.browser] = version;
+    });
+    const allVersions = getCompatibleVersions({
+        targetYear: 2016,
+        listAllCompatibleVersions: true,
+    });
+    const outputArray = new Array();
+    bcdCoreBrowserNames.forEach((browserName) => {
+        let thisBrowserAllVersions = allVersions
+            .filter((version) => version.browser == browserName)
+            .sort((a, b) => {
+            return compareVersions(a.version, b.version);
+        });
+        let waVersion = waObject[browserName]?.version ?? "0";
+        yearArray.forEach((year) => {
+            if (yearMinimumVersions[year]) {
+                let minBrowserVersionInfo = yearMinimumVersions[year][browserName] ?? {
+                    version: "0",
+                };
+                let minBrowserVersion = minBrowserVersionInfo.version;
+                let sliceIndex = thisBrowserAllVersions.findIndex((element) => compareVersions(element.version, minBrowserVersion) === 0);
+                let subArray = year === nextYear - 1
+                    ? thisBrowserAllVersions
+                    : thisBrowserAllVersions.slice(0, sliceIndex);
+                subArray.forEach((version) => {
+                    let iswa_compatible = compareVersions(version.version, waVersion) >= 0 ? true : false;
+                    outputArray.push({
+                        ...version,
+                        year: year - 1,
+                        wa_compatible: iswa_compatible,
+                    });
+                });
+                thisBrowserAllVersions = thisBrowserAllVersions.slice(sliceIndex, thisBrowserAllVersions.length);
+            }
+        });
+    });
+    if (options.includeDownstreamBrowsers) {
+        let downstreamBrowsers = getDownstreamBrowsers(outputArray);
+        downstreamBrowsers.forEach((version) => {
+            let correspondingChromiumVersion = outputArray.find((upstreamVersion) => upstreamVersion.browser === "chrome" &&
+                upstreamVersion.version === version.engine_version);
+            if (correspondingChromiumVersion) {
+                outputArray.push({
+                    ...version,
+                    year: correspondingChromiumVersion.year,
+                    wa_compatible: correspondingChromiumVersion.wa_compatible,
+                });
+            }
+        });
     }
+    outputArray.sort((a, b) => {
+        if (a.year < b.year) {
+            return -1;
+        }
+        else if (a.browser > b.browser) {
+            return 1;
+        }
+        else {
+            return compareVersions(a.version, b.version);
+        }
+    });
+    if (options.outputFormat === "object") {
+        const outputObject = {};
+        outputArray.forEach((version) => {
+            if (!outputObject[version.browser]) {
+                outputObject[version.browser] = {};
+            }
+            //@ts-ignore
+            outputObject[version.browser][version.version] = {
+                year: version.year,
+                wa_compatible: version.wa_compatible,
+                release_date: version.release_date,
+                engine: version.engine,
+                engine_version: version.engine_version,
+            };
+        });
+        return outputObject ?? {};
+    }
+    if (options.outputFormat === "csv") {
+        let outputString = `"browser","version","year","wa_compatible","release_date","engine","engine_version"`;
+        outputArray.forEach((version) => {
+            let outputs = {
+                browser: version.browser,
+                version: version.version,
+                year: version.year,
+                wa_compatible: version.wa_compatible,
+                release_date: version.release_date ?? "NULL",
+                engine: version.engine ?? "NULL",
+                engine_version: version.engine_version ?? "NULL",
+            };
+            outputString += `\n"${outputs.browser}","${outputs.version}","${outputs.year}","${outputs.wa_compatible}","${outputs.release_date}","${outputs.engine}","${outputs.engine_version}"`;
+        });
+        return outputString;
+    }
+    return outputArray;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baseline-browser-mapping",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "A library for obtaining browser versions with their maximum supported Baseline feature set and Widely Available status.",
   "exports": {
     ".": "./dist/index.js"
@@ -16,7 +16,8 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "prepare": "rm -rf dist; prettier . --write; tsc",
-    "refresh-downstream": "npx tsx scripts/refresh-downstream.ts"
+    "refresh-downstream": "npx tsx scripts/refresh-downstream.ts",
+    "refresh-static": "npx tsx scripts/refresh-static.ts"
   },
   "license": "Apache-2.0",
   "dependencies": {