feat(schemas): add index to published browser release objects

lint/linter/test-browsers-data.js

@@ -8,12 +8,12 @@ const { browsers } = bcd;
 
 /** @import {Linter, LinterData} from '../types.js' */
 /** @import {Logger} from '../utils.js' */
-/** @import {BrowserStatement, BrowserName} from '../../types/index.js' */
+/** @import {InternalBrowserStatement, BrowserName} from '../../types/index.js' */
 
 /**
  * Process and test the data
  * @param {BrowserName} browser The name of the browser
- * @param {BrowserStatement} data The browser statement
+ * @param {InternalBrowserStatement} data The browser statement
  * @param {Logger} logger The logger to output errors to
  * @returns {void}
  */
@@ -91,7 +91,7 @@ export default {
   check: (logger, { data, path: { browser } }) => {
     processData(
       /** @type {BrowserName} */ (browser),
-      /** @type {BrowserStatement} */ (data),
+      /** @type {InternalBrowserStatement} */ (data),
       logger,
     );
   },

lint/linter/test-browsers-data.test.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {BrowserStatement} from '../../types/index.js' */
+/** @import {InternalBrowserStatement} from '../../types/index.js' */
 
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -22,7 +22,7 @@ describe('test-browsers-data', () => {
 
   it('should log an error if a browser has multiple current releases', async () => {
     const browser = 'nodejs';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Node.js',
       type: 'server',
@@ -49,7 +49,7 @@ describe('test-browsers-data', () => {
 
   it('should log an error if a browser has multiple nightly releases', async () => {
     const browser = 'firefox';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Firefox',
       type: 'desktop',
@@ -69,7 +69,7 @@ describe('test-browsers-data', () => {
 
   it('should not log an error if a server engine has multiple nightly releases', async () => {
     const browser = 'nodejs';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Node.js',
       type: 'server',
@@ -89,7 +89,7 @@ describe('test-browsers-data', () => {
 
   it('should log an error if the upstream for a browser is set to itself', async () => {
     const browser = 'safari_ios';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Safari iOS',
       type: 'mobile',
@@ -108,7 +108,7 @@ describe('test-browsers-data', () => {
 
   it('should log an error if the upstream for a browser is an unknown browser', async () => {
     const browser = 'safari_ios';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Safari iOS',
       type: 'mobile',
@@ -127,7 +127,7 @@ describe('test-browsers-data', () => {
 
   it('should log an error if a retired or current release has no release date', async () => {
     const browser = 'opera';
-    /** @type {BrowserStatement} */
+    /** @type {InternalBrowserStatement} */
     const data = {
       name: 'Opera',
       type: 'desktop',

schemas/browsers.schema.json

@@ -55,24 +55,24 @@
       "enum": ["retired", "current", "beta", "nightly", "esr", "planned"]
     },
 
-    "browsers": {
+    "internal_browsers": {
       "type": "object",
       "propertyNames": {
         "$ref": "#/definitions/browser_name"
       },
       "additionalProperties": {
-        "$ref": "#/definitions/browser_statement"
+        "$ref": "#/definitions/internal_browser_statement"
       },
       "minProperties": 1,
       "maxProperties": 1,
       "errorMessage": {
         "minProperties": "A browser must be described within the file.",
         "maxProperties": "Each browser JSON file may only describe one browser."
       },
-      "tsType": "Record<BrowserName, BrowserStatement>"
+      "tsType": "Record<BrowserName, InternalBrowserStatement>"
     },
 
-    "browser_statement": {
+    "internal_browser_statement": {
       "type": "object",
       "properties": {
         "name": {
@@ -110,9 +110,11 @@
         },
         "releases": {
           "type": "object",
-          "additionalProperties": { "$ref": "#/definitions/release_statement" },
+          "additionalProperties": {
+            "$ref": "#/definitions/internal_release_statement"
+          },
           "description": "Releases of this browser.",
-          "tsType": "{ [version: string]: ReleaseStatement };"
+          "tsType": "{ [version: string]: InternalReleaseStatement };"
         }
       },
       "required": [
@@ -125,7 +127,7 @@
       "additionalProperties": false
     },
 
-    "release_statement": {
+    "internal_release_statement": {
       "type": "object",
       "properties": {
         "release_date": {
@@ -165,7 +167,7 @@
   "title": "BrowserDataFile",
   "type": "object",
   "properties": {
-    "browsers": { "$ref": "#/definitions/browsers" }
+    "browsers": { "$ref": "#/definitions/internal_browsers" }
   },
   "additionalProperties": false
 }

schemas/public.schema.json

@@ -142,6 +142,11 @@
     "release_statement": {
       "type": "object",
       "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "0-based position of this release in version-sorted order (ascending)."
+        },
         "release_date": {
           "type": "string",
           "format": "date",
@@ -164,7 +169,7 @@
           "description": "Engine version used in this release."
         }
       },
-      "required": ["status"],
+      "required": ["index", "status"],
       "dependencies": {
         "engine": ["engine_version"]
       },

schemas/public.schema.md

@@ -22,6 +22,7 @@ Below is a simplified example of the published data:
       "accepts_webextensions": true,
       "releases": {
         "1.5": {
+          "index": 0,
           "release_date": "2005-11-29",
           "release_notes": "https://developer.mozilla.org/Firefox/Releases/1.5",
           "status": "retired",
@@ -357,6 +358,7 @@ The published data differs from the [source data](./compat-data-schema.md) in th
 - All `"mirror"` support statements are resolved to concrete support objects with real version numbers. The string `"mirror"` never appears in published data.
 - A `source_file` property is added to every `__compat` object.
 - A `version_last` property is added to every support statement that has a `version_removed`.
+- A 0-based `index` property is added to every release object, ordered ascending by version. Consumers can use it to construct an ordered array of releases without parsing version strings.
 - Markdown formatting in `description` and `notes` fields is converted to HTML.
 
 ## Exports

scripts/build/index.js

@@ -21,7 +21,7 @@ import mirrorSupport from './mirror.js';
 
 /**
  * @import { BrowserName, InternalCompatData, InternalIdentifier, InternalSupportStatement, VersionValue } from '../../types/index.js'
- * @import { CompatData, MetaBlock } from '../../types/public.js'
+ * @import { CompatData, MetaBlock, ReleaseStatement } from '../../types/public.js'
  * @import { WalkOutput } from '../../utils/walk.js'
  */
 
@@ -206,14 +206,31 @@ const addIE = (feature) => {
 };
 
 /**
- * Apply build-time transforms in place: resolve `"mirror"` statements, add
- * `version_last`, convert Markdown notes/descriptions to HTML, and add
- * missing `ie` entries.
+ * Add a 0-based `index` to every release, ordered ascending by version
+ * (matching `compareVersions` order).
+ * @param {InternalCompatData} data - BCD data whose release objects will receive an `index` property.
+ * @returns {void}
+ */
+export const addReleaseIndex = (data) => {
+  for (const { releases } of Object.values(data.browsers)) {
+    const sorted = Object.keys(releases).sort(compareVersions);
+    sorted.forEach((version, i) => {
+      /** @type {ReleaseStatement} */ (releases[version]).index = i;
+    });
+  }
+};
+
+/**
+ * Apply build-time transforms in place: add a release `index`, resolve
+ * `"mirror"` statements, add `version_last`, convert Markdown notes and
+ * descriptions to HTML, and add missing `ie` entries.
  * @param {InternalCompatData} data - The data to apply transforms to.
  * @returns {asserts data is Omit<CompatData, '__meta'>} Narrows `data` to the
  *   public `CompatData` shape (without `__meta`).
  */
 export const applyTransforms = (data) => {
+  addReleaseIndex(data);
+
   const walker = walk(undefined, data);
 
   for (const feature of walker) {

scripts/build/index.test.js

@@ -9,6 +9,7 @@ import { walk } from '../../utils/index.js';
 import {
   generateMeta,
   applyMirroring,
+  addReleaseIndex,
   addVersionLast,
   createManifest,
 } from './index.js';
@@ -102,6 +103,29 @@ describe('Build functions', () => {
     assert.equal(data.feature.__compat.support.safari.version_last, 'preview');
     assert.equal(data.feature.__compat.support.edge.version_last, true);
   });
+  it('addReleaseIndex', () => {
+    /** @type {*} */
+    const data = {
+      browsers: {
+        example: {
+          releases: {
+            10: { status: 'current' },
+            1: { status: 'retired' },
+            2.5: { status: 'retired' },
+            2: { status: 'retired' },
+          },
+        },
+      },
+    };
+
+    addReleaseIndex(data);
+
+    assert.equal(data.browsers.example.releases['1'].index, 0);
+    assert.equal(data.browsers.example.releases['2'].index, 1);
+    assert.equal(data.browsers.example.releases['2.5'].index, 2);
+    assert.equal(data.browsers.example.releases['10'].index, 3);
+  });
+
   it('createManifest', () => {
     const manifest = createManifest();
     assert.ok(manifest.main);

scripts/lib/stringify-and-order-properties.js

@@ -3,7 +3,7 @@
 
 import { compareVersions } from 'compare-versions';
 
-/** @import {InternalCompatStatement, InternalSimpleSupportStatement, InternalStatusBlock, BrowserStatement, ReleaseStatement} from '../../types/index.js' */
+/** @import {InternalCompatStatement, InternalSimpleSupportStatement, InternalStatusBlock, InternalBrowserStatement, InternalReleaseStatement} from '../../types/index.js' */
 
 const propOrder = {
   browsers: {
@@ -74,7 +74,7 @@ const doOrder = (value, order) => {
  * prefix and suffix added, which will be removed after performing JSON
  * stringification. This is important because JavaScript wants to move object
  * entries with a floating point as the key to the very end of the list.
- * @param {Record<string, ReleaseStatement>} releases The release data
+ * @param {Record<string, InternalReleaseStatement>} releases The release data
  * @returns {string} The stringified releases
  */
 export const stringifyReleases = (releases) => {
@@ -153,13 +153,15 @@ export const orderProperties = (key, value) => {
       const browser = Object.keys(value.browsers)[0];
 
       value.browsers[browser] = doOrder(
-        /** @type {BrowserStatement} */ (value.browsers[browser]),
+        /** @type {InternalBrowserStatement} */ (value.browsers[browser]),
         propOrder.browsers.browser,
       );
 
       for (const r of Object.keys(value.browsers[browser].releases)) {
         value.browsers[browser].releases[r] = doOrder(
-          /** @type {ReleaseStatement} */ (value.browsers[browser].releases[r]),
+          /** @type {InternalReleaseStatement} */ (
+            value.browsers[browser].releases[r]
+          ),
           propOrder.browsers.release,
         );
       }

scripts/update-browser-releases/bun.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {Browsers, InternalCompatData} from '../../types/index.js' */
+/** @import {InternalBrowsers, InternalCompatData} from '../../types/index.js' */
 
 /**
  * @typedef {object} BunVersionsResponse
@@ -287,9 +287,8 @@ export const updateBunReleases = async (options) => {
       rel.release_notes,
     );
 
-    const entry = /** @type {Browsers} */ (data.browsers)[browser].releases[
-      rel.version
-    ];
+    const entry = /** @type {InternalBrowsers} */ (data.browsers)[browser]
+      .releases[rel.version];
 
     if (entry) {
       const { webkitRev } = await getBunInfoFromVersionData(rel);

scripts/update-browser-releases/firefox.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {ReleaseStatement} from '../../types/index.js' */
+/** @import {InternalReleaseStatement} from '../../types/index.js' */
 
 import * as fs from 'node:fs';
 
@@ -129,7 +129,7 @@ export const updateFirefoxReleases = async (options) => {
 
   // Replace all old entries with 'retired' or 'esr'
   Object.entries(
-    /** @type {Record<string, ReleaseStatement>} */ (
+    /** @type {Record<string, InternalReleaseStatement>} */ (
       firefoxBCD.browsers[options.bcdBrowserName].releases
     ),
   ).forEach(([key, entry]) => {
@@ -164,7 +164,7 @@ export const updateFirefoxReleases = async (options) => {
   // Avoid duplicate Nightly release.
   //
   const nightlyReleases = Object.entries(
-    /** @type {Record<string, ReleaseStatement>} */ (
+    /** @type {Record<string, InternalReleaseStatement>} */ (
       firefoxBCD.browsers[options.bcdBrowserName].releases
     ),
   )
@@ -173,7 +173,9 @@ export const updateFirefoxReleases = async (options) => {
 
   if (nightlyReleases.length > 1) {
     const [nightlyVersion, nightlyRelease] =
-      /** @type {[string, ReleaseStatement]} */ (nightlyReleases.shift());
+      /** @type {[string, InternalReleaseStatement]} */ (
+        nightlyReleases.shift()
+      );
     data[options.nightlyBranch].version = nightlyVersion;
     data[options.nightlyBranch].releaseDate = nightlyRelease.release_date;
 

scripts/update-browser-releases/utils.js

@@ -1,7 +1,7 @@
 /* This file is a part of @mdn/browser-compat-data
  * See LICENSE file for more information. */
 
-/** @import {BrowserName, Browsers, BrowserStatus, InternalCompatData} from '../../types/index.js' */
+/** @import {BrowserName, InternalBrowsers, BrowserStatus, InternalCompatData} from '../../types/index.js' */
 
 /**
  * @typedef {object} RSSItem
@@ -168,9 +168,8 @@ export const createOrUpdateBrowserEntry = (
  * @returns {string} Text describing what has been updated
  */
 export const setBrowserReleaseStatus = (json, browser, version, status) => {
-  const release = /** @type {Browsers} */ (json.browsers)[browser].releases[
-    version
-  ];
+  const release = /** @type {InternalBrowsers} */ (json.browsers)[browser]
+    .releases[version];
 
   if (release.status === status) {
     return '';