baseline-browser-mapping - npm Package Compare versions

Comparing version 2.10.38 to 2.11.0-beta.0

dist/types.d.ts

+export type BrowserVersion = {
+    browser: string;
+    version: string;
+    release_date?: string;
+    engine?: string;
+    engine_version?: string;
+};
+export type Options = {
+    /**
+     * Whether to include only the minimum compatible browser versions or all compatible versions.
+     * Defaults to `false`.
+     */
+    listAllCompatibleVersions?: boolean;
+    /**
+     * Whether to include browsers that use the same engines as a core Baseline browser.
+     * Defaults to `false`.
+     */
+    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.
+     * > NOTE: cannot be used with `targetYear`.
+     */
+    widelyAvailableOnDate?: string | number;
+    /**
+     * Pass a year between 2015 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;
+    /**
+     * Pass a boolean that determines whether KaiOS is included in browser mappings.  KaiOS implements
+     * the Gecko engine used in Firefox.  However, KaiOS also has a different interaction paradigm to
+     * other browsers and requires extra consideration beyond simple feature compatibility to provide
+     * an optimal user experience.  Defaults to `false`.
+     */
+    includeKaiOS?: boolean;
+    overrideLastUpdated?: number;
+    /**
+     * Pass a boolean to suppress the warning about stale data.
+     * Defaults to `false`.
+     */
+    suppressWarnings?: boolean;
+};
+export type AllVersionsOptions = {
+    /**
+     * Whether to return the output as a JavaScript `Array` (`"array"`), `Object` (`"object"`) 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;
+    /**
+     * Whether to use the new "supports" property in place of "wa_compatible"
+     * Defaults to `false`
+     */
+    useSupports?: boolean;
+    /**
+     * Whether to include KaiOS in the output. KaiOS implements the Gecko engine used in Firefox.
+     * However, KaiOS also has a different interaction paradigm to other browsers and requires extra
+     * consideration beyond simple feature compatibility to provide an optimal user experience.
+     */
+    includeKaiOS?: boolean;
+    /**
+     * Pass a boolean to suppress the warning about old data.
+     * Defaults to `false`.
+     */
+    suppressWarnings?: boolean;
+};
+export interface AllBrowsersBrowserVersion extends BrowserVersion {
+    year: number | string;
+    supports?: string;
+    wa_compatible?: boolean;
+}
+export type NestedBrowserVersions = {
+    [browser: string]: {
+        [version: string]: AllBrowsersBrowserVersion;
+    };
+};
+export type TimelineOptions = {
+    /**
+     * Whether to return the timeline as a chronologically sorted array of events grouped by date ("date"),
+     * or as an object grouped by browser with their respective history of version changes ("browser").
+     * Defaults to "date".
+     */
+    groupBy?: "date" | "browser";
+    /**
+     * Whether to include all compatible browsers in each timeline event,
+     * or only the browsers that changed on that date.
+     * Only applicable when groupBy is "date".
+     * Defaults to `false`.
+     */
+    listAllBrowsers?: boolean;
+    /**
+     * Whether to include browsers that use the same engines as a core Baseline browser.
+     * Defaults to `false`.
+     */
+    includeDownstreamBrowsers?: boolean;
+    /**
+     * Whether to include KaiOS in the timeline.
+     * Defaults to `false`.
+     */
+    includeKaiOS?: boolean;
+};
+export type TimelineEvent = {
+    date: string;
+    browsers: BrowserVersion[];
+};
+export type BrowserTimelineEntry = {
+    date: string;
+    version: string;
+    release_date?: string;
+    engine?: string;
+    engine_version?: string;
+};
+export type BrowserTimeline = {
+    [browser: string]: BrowserTimelineEntry[];
+};

dist/utils.d.ts

+export declare const compareVersions: (nextVersion: string, prevVersion: string) => 1 | 0 | -1;

dist/index.d.ts

@@ -0,56 +1,3 @@
+import { BrowserVersion, Options, AllVersionsOptions, AllBrowsersBrowserVersion, NestedBrowserVersions, TimelineOptions, TimelineEvent, BrowserTimeline } from "./types.js";
 export declare function _resetHasWarned(): void;
-type BrowserVersion = {
-    browser: string;
-    version: string;
-    release_date?: string;
-    engine?: string;
-    engine_version?: string;
-};
-interface AllBrowsersBrowserVersion extends BrowserVersion {
-    year: number | string;
-    supports?: string;
-    wa_compatible?: boolean;
-}
-type NestedBrowserVersions = {
-    [browser: string]: {
-        [version: string]: AllBrowsersBrowserVersion;
-    };
-};
-type Options = {
-    /**
-     * Whether to include only the minimum compatible browser versions or all compatible versions.
-     * Defaults to `false`.
-     */
-    listAllCompatibleVersions?: boolean;
-    /**
-     * Whether to include browsers that use the same engines as a core Baseline browser.
-     * Defaults to `false`.
-     */
-    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.
-     * > NOTE: cannot be used with `targetYear`.
-     */
-    widelyAvailableOnDate?: string | number;
-    /**
-     * Pass a year between 2015 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;
-    /**
-     * Pass a boolean that determines whether KaiOS is included in browser mappings.  KaiOS implements
-     * the Gecko engine used in Firefox.  However, KaiOS also has a different interaction paradigm to
-     * other browsers and requires extra consideration beyond simple feature compatibility to provide
-     * an optimal user experience.  Defaults to `false`.
-     */
-    includeKaiOS?: boolean;
-    overrideLastUpdated?: number;
-    /**
-     * Pass a boolean to suppress the warning about stale data.
-     * Defaults to `false`.
-     */
-    suppressWarnings?: boolean;
-};
 /**
@@ -67,30 +14,2 @@ * Returns browser versions compatible with specified Baseline targets.
 export declare function getCompatibleVersions(userOptions?: Options): BrowserVersion[];
-type AllVersionsOptions = {
-    /**
-     * Whether to return the output as a JavaScript `Array` (`"array"`), `Object` (`"object"`) 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;
-    /**
-     * Whether to use the new "supports" property in place of "wa_compatible"
-     * Defaults to `false`
-     */
-    useSupports?: boolean;
-    /**
-     * Whether to include KaiOS in the output. KaiOS implements the Gecko engine used in Firefox.
-     * However, KaiOS also has a different interaction paradigm to other browsers and requires extra
-     * consideration beyond simple feature compatibility to provide an optimal user experience.
-     */
-    includeKaiOS?: boolean;
-    /**
-     * Pass a boolean to suppress the warning about old data.
-     * Defaults to `false`.
-     */
-    suppressWarnings?: boolean;
-};
 /**
@@ -105,2 +24,7 @@ * Returns all browser versions known to this module with their level of Baseline support as a JavaScript `Array` (`"array"`), `Object` (`"object"`) or a CSV string (`"csv"`).
 export declare function getAllVersions(userOptions?: AllVersionsOptions): AllBrowsersBrowserVersion[] | NestedBrowserVersions | string;
-export {};
+export declare function getTimeline(userOptions?: TimelineOptions & {
+    groupBy?: "date";
+}): TimelineEvent[];
+export declare function getTimeline(userOptions: TimelineOptions & {
+    groupBy: "browser";
+}): BrowserTimeline;

package.json

 {
   "name": "baseline-browser-mapping",
   "main": "./dist/index.cjs",
-  "version": "2.10.38",
+  "version": "2.11.0-beta.0",
   "description": "A library for obtaining browser versions with their maximum supported Baseline feature set and Widely Available status.",
@@ -43,12 +43,12 @@ "exports": {
     "refresh-static": "npx tsx scripts/refresh-static.ts",
-    "update-data-file": "npx tsx scripts/update-data-file.ts; npx prettier ./src/data/data.js --write",
+    "update-timeline": "npx tsx scripts/create-timeline.ts; npx prettier ./src/data/timeline.js --write",
     "update-data-dependencies": "npm i @mdn/browser-compat-data@latest web-features@latest -D",
-    "check-data-changes": "git diff --name-only | grep -q '^src/data/data.js$' && echo 'changes-available=TRUE' || echo 'changes-available=FALSE'"
+    "check-timeline-changes": "git diff --name-only | grep -q '^src/data/timeline.js$' && echo 'changes-available=TRUE' || echo 'changes-available=FALSE'"
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@mdn/browser-compat-data": "^8.0.3",
+    "@mdn/browser-compat-data": "^8.0.4",
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.3",
-    "@types/node": "^22.15.17",
+    "@types/node": "^22.19.21",
     "eslint-plugin-new-with-error": "^5.0.0",
@@ -63,3 +63,3 @@ "jasmine": "^5.8.0",
     "typescript-eslint": "^8.35.0",
-    "web-features": "^3.30.0"
+    "web-features": "^3.31.0"
   },
@@ -66,0 +66,0 @@ "repository": {

README.md

@@ -44,3 +44,3 @@ # [`baseline-browser-mapping`](https://github.com/web-platform-dx/web-features/packages/baseline-browser-mapping)
 
-This module exposes two functions: `getCompatibleVersions()` and `getAllVersions()`, both which can be imported directly from `baseline-browser-mapping`:
+This module exposes three functions: `getCompatibleVersions()`, `getAllVersions()`, and `getTimeline()`, all of which can be imported directly from `baseline-browser-mapping`:
 
@@ -51,2 +51,3 @@ ```javascript
   getAllVersions,
+  getTimeline,
 } from "baseline-browser-mapping";
@@ -62,2 +63,3 @@ ```
     getAllVersions,
+    getTimeline,
   } from "https://cdn.jsdelivr.net/npm/baseline-browser-mapping";
@@ -411,2 +413,78 @@ </script>
 
+## Get timeline of browser version compatibility bumps
+
+To calculate compatible browser versions on custom/arbitrary dates completely client-side without loading the full `@mdn/browser-compat-data` database, you can call the `getTimeline()` function. It returns the timeline of minimum version requirements as a chronologically sorted array of change events:
+
+```javascript
+import { getTimeline } from "baseline-browser-mapping";
+
+const timeline = getTimeline();
+```
+
+It returns an `Array` of events, where each event has a `date` and an array of `browsers` representing the compatibility changes on that date:
+
+```javascript
+[
+  {
+    date: "2015-07-29",
+    browsers: [
+      { browser: "chrome", version: "38", release_date: "2014-10-07" },
+      { browser: "chrome_android", version: "38", release_date: "2014-10-08" },
+      { browser: "edge", version: "12", release_date: "2015-07-29" },
+      { browser: "firefox", version: "38", release_date: "2015-05-12" },
+      { browser: "firefox_android", version: "38", release_date: "2015-05-12" },
+      { browser: "safari", version: "11", release_date: "2017-09-19" },
+      { browser: "safari_ios", version: "11", release_date: "2017-09-19" }
+    ]
+  },
+  {
+    date: "2015-09-22",
+    browsers: [
+      { browser: "firefox", version: "41", release_date: "2015-09-22" },
+      { browser: "firefox_android", version: "41", release_date: "2015-09-22" }
+    ]
+  },
+  ...
+]
+```
+
+### Options
+
+`getTimeline()` accepts an optional configuration `Object` with the following properties:
+
+- `groupBy` (`"date"` by default):
+  - If `"date"` (default), it returns a chronologically sorted `Array` of events, where each event represents a date on which a browser's Baseline requirements changed.
+  - If `"browser"`, it returns an `Object` where keys are browser names and values are arrays of version change events for that specific browser:
+    ```javascript
+    {
+      chrome: [
+        { date: "2015-07-29", version: "38", release_date: "2014-10-07" },
+        { date: "2016-03-02", version: "49", release_date: "2016-03-02" },
+        ...
+      ],
+      safari: [
+        { date: "2015-09-30", version: "9", release_date: "2015-09-30" },
+        ...
+      ],
+      ...
+    }
+    ```
+- `listAllBrowsers` (`false` by default):
+  - If `false`, the `browsers` array for each event (when `groupBy` is `"date"`) contains _only_ the browsers that changed on that specific date.
+  - If `true`, the `browsers` array for each event will contain the state of _all_ active compatible browsers at that point in time (showing the versions they had on that date).
+  - _Note: Only applicable when `groupBy` is `"date"` (or when `groupBy` is `"browser"`, this lists every date in the timeline for each browser)._
+- `includeDownstreamBrowsers` (`false` by default): Whether to include downstream browsers that share the same engine as a core browser.
+- `includeKaiOS` (`false` by default): Whether to include KaiOS (requires `includeDownstreamBrowsers: true`).
+
+```javascript
+// Get a complete view of all core browsers at every timeline event
+const fullTimeline = getTimeline({ listAllBrowsers: true });
+
+// Get the timeline grouped by browser instead of by date
+const browserTimeline = getTimeline({ groupBy: "browser" });
+
+// Include downstream browsers in the timeline of changes
+const downstreamTimeline = getTimeline({ includeDownstreamBrowsers: true });
+```
+
 ## CLI
@@ -413,0 +491,0 @@

New alerts

Obfuscated code

Supply chain risk

Obfuscated files are intentionally packed to hide their behavior. This could be a sign of malware.

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Fixed alerts

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Improved metrics

Number of package files

9

28.57%

Number of low quality alerts

3

-25%

Number of lines in readme file

546

16.67%

Worsened metrics

Total package byte prevSize

139302

-51.68%

Lines of code

513

-52.06%

Number of high supply chain risk alerts

2

Infinity%

Number of low supply chain risk alerts

9

28.57%

Number of medium supply chain risk alerts

1

Infinity%

No dependency changes