Proposal: "Active” BCD API for exploring browser and feature data

[ddbeck]

Summary

BCD ought to have an API to make it easier to resolve questions across data contained within BCD, such as comparing specific browsers releases against feature support data. This will unburden BCD consumers of having to hold top-to-bottom knowledge of BCD’s schema and its many concrete permutations.

Problem statement

While BCD is a rich data source, it has a complicated structure and schema that makes it difficult to consume BCD in ways that aren’t not already lined up with its hierarchical, feature-focused structure.

For example, as a consumer, I have to write new code to do any of the following tasks with BCD:

• Look up data for a specific, known feature
• Check whether a browser supports a feature
• Check whether the version of a browser that supports a feature is stable, shipping release
• Check the date a browser first supported a feature
• Compare the results of any of the above inquiries between browsers

None of this requires data external to BCD, yet the tasks can be remarkably complicated. Generalized consumer code must be able to handle:

• Features without data for a particular browser
• Features with multiple support statements for a single browser, where some support statements may be concurrent (e.g., prefixed and unprefixed), sequential (e.g., added, removed, and reinstated), or both
• Support statements that are closed-ended (previously supported), open-ended (currently supported)
• Support statements that use version numbers, booleans, or unversioned preview markers
• Support statements that are flagged for prefixes, partial implementations, and notes

To do comparative analysis of a feature’s support (e.g., to compare one browser to another or one feature to another) adds additional complexity that often goes against the grain of BCD’s structure, which was designed to facilitate tabular, version-number oriented reports (i.e., the compat tables on MDN).

This is an active barrier to concrete work consuming BCD for the benefit of web developer audiences. For example, my work with the WebDX CG's feature-set repo is partly blocked by the question of where and how we'll maintain the code for consuming BCD. We anticipate complexity and somewhat strong coupling with BCD, which has caused some of the work to be deferred.

In all other cases, BCD is a passive, complicated data source. But one with immense promise, owing to its detail and quality.

Proposal

To help ameliorate some of the pains I’ve just described, I propose implementing a consumer API—a suite of functions, classes, and methods—that support consumers in the following tasks:

• Readily accessing specific features
• Selecting specific browser releases
• Comparing releases against features (and vice versa) for simplified support queries

(See the Technical vignette section for more information on a possible shape for this API.)

Expose the API as (preferred) a named export form the BCD package (to support co-versioning with BCD’s schema) or (less preferred) a companion package versioned against BCD’s schema.

Key questions

Key questions remain to be answered before proceeding:

• Is such an API something that the BCD’s owner group is willing to accept and maintain, through a series of PRs?
• Is such an API something that the BCD’s owner group is willing to include in @mdn/browser-compat-data (or, alternatively, a parallel package to BCD)?
• If the answers to the above questions are yes, what does the owner’s group think of the overall direction of the API? (Understandably, there will be specifics to work through in PRs, but I’m keen to get overall feedback on the general idiom of the API.)

Technical vignette

I understand that it’s hard to accept a vague proposal, so here I’d like to offer an illustration of what that API might look like. Please remember that this is for illustrative purposes, to characterize the overall flavor of such an API—I expect the review of PRs to determine the actual working API.

But consider this non-working code snippet:

let b = browser("safari");
const currentSafari = b.releaseAt(0);
currentSafari.release_date;
// ⮐ "2023-01-23"

let currentChrome /* = … */;
let currentFirefox /* = … */;

const containerAtRule = feature("css.at-rules.container");
containerAtRule.supportedBy(currentSafari);
// ⮐ true

containerAtRule.supportedBy(currentSafari, currentChrome, currentFirefox);
// ⮐ true

// And so on…
containerAtRule.supportedBy(...browser("safari").releasesSince("2022-01-01"))

Briefly, the API would consist of:

• The browser() factory function, which returns Browser objects
• The feature() factory function, which returns Feature objects
• A Browser class, representing a browser and its collection of releases, offering methods such as:
  • toArray() returning a sequence of Release objects
  • releaseOn() returning the Release closest the date
  • releasesSince() returning a sequence of Release objects on after a specific date
  • releaseAt() returning a Release by its index (e.g., 2 releases since the most recent, or the 2nd release)
• A Release class, representing individual browser-version pairs
• A Feature class, representing a single BCD feature, offering methods such as:
  • supportedBy(release) returning a simplified support status value (e.g. boolean | prefixed | partial)
  • notesFor(release) returning a sequence of Note objects corresponding to that release
  • supportDefailsFor(releases) returning a Map of releases to specific support statuses and notes
• A Note class, representing a single note
• A SupportStatement class, representing a single support statement, offering methods such as:
  • getters to normalize version_removed, notes, partial_implementation, and other optional fields
  • toReleases() to convert a support statement to a sequence of applicable releases
  • has(release) to check whether a given release is represented by the range of releases in the support statement

I’ve put together a TypeScript declaration that provides a more detailed specification of the API described above. Do keep in mind that it’s far from final (and a great many details depend on the implementation, rather than the interface declaration).

[ddbeck]

@queengooborg, @Elchi3: This is a follow on from our chat last week.

cc: @foolip write up continues the TS declaration you've seen previously

[Elchi3]

Maintainers of https://github.com/mdn/bcd-utils, what do you think?

@fiji-flo @caugner @LeoMcA @Guyzeroth

[ddbeck]

In a chat earlier today, @Elchi3 asked a great question: how would this impact semantic versioning? BCD took a long time to achieve some consistency around semver, so it's good to think about how this might affect that.

I think there's two plausible routes and I prefer the first:

1. Initially, declare the API as experimental and not subject to semver. If possible, emit a warning when you explicitly import the API (I think this is possible with a named export). After we achieve stability, add the API to the semver contract. I expect that, once stable, the API and schema would change together, so it would be rare to have a semver major release caused by API-only changes.

2. Publish the API as a standalone package, versioned to mirror the BCD schema version (e.g., use the BCD version plus build metadata as in 5.2.36+utils-1.0.0). This is workable, but less convenient: it requires a peer dependency with BCD and—depending on the versioning scheme—doesn't play as nicely with package management tools.

There's also a third route, which is option 1 with extra steps: develop as a standalone package and merge into the main BCD package at a later date (i.e., when the API is "1.0.0"-ready).

A fourth route that I considered and think we ought to reject is letting the API and data diverge. Testing an API in a matrix with multiple versions of BCD (even within the same semver major range) is intrinsically more complicated. I don't think it's a good use of contributors' time and attention to build or maintain such a thing.