Crate caniuse_serde [] [src]

caniuse-serde

A Rust library crate for working with the https://caniuse.com database of browser (agent) features and regional usage data. Comes with a version if the database embedded, and can also be used with external copies (JSON files).

Getting Going

To get started

extern crate caniuse_serde;
use ::caniuse_serde::{EmbeddedCanIUseDatabase, AgentName, FeatureName};

To look up an agent's details

let agent = AgentName::MozillaFirefox.agent(EmbeddedCanIUseDatabase).unwrap();

To look up a feature's details

let feature = "transform3d".into().feature(EmbeddedCanIUseDatabase).unwrap();

Regional Usage

  • Use the constants in the regional_usage module to get regional, continental and world-wide usage data.
  • To replicate the functionality of 'browserlist', use the query() method on RegionalUsage.
  • Or read below for a more useful approach.
  • Use the enum RegionalUsages with the method regional_usage() to obtain a reference to an embedded RegionalUsage database.

A strategy for using the caniuse database with browserlist like behaviour

The concept of version is differently understood by the browser vendors (eg IE vs Chrome, say), and so just saying 'last 2 versions' isn't particularly useful. In practice, a combination of selection rules is needed to identify a set of browser and browser versions to support, using the data in the database. These selection rules are likely to be stable for months and years, but not in the long term.

I've identified my own selection rules for a professional, international consultant's website written in English with translations to Spanish, French and Italian. I've added this as code to this crate to make sure that the API I've written around the caniuse.com database is actually usable.

To make use of my choices

The quickest way is with either sensible_choices() or sensible_choices_default():-

extern crate caniuse_serde;
use ::caniuse_serde::*;
use ::caniuse_serde::regional_usage::*;

let (can_i_use, choices) = sensible_choices_default();

let feature_name = FeatureName("css-focus-ring".to_owned());
let mut unique_prefixes = HashSet::new();
choices.support_for_a_feature(&can_i_use, &feature_name, |agent, version, support| {
    if support.requires_prefix() {
        unique_prefixes.insert(agent.prefix(version).clone());
    }
});

assert!(unique_prefixes.contains(&Prefix::moz));
assert_eq!(unique_prefixes.len(), 1);

My selection rules

  1. Obsolete Browsers still in use
    • We need to support the last version of these until its percentage usage falls below X%
    • The percentage usage should be for a sub-set of the world (ie target audience continents or countries)
    • These browsers are:-
      • IE (at version 11)
      • Blackberry Browser (at version 10)
      • IE Mobile (MS has dropped Windows Phone)
  2. Browsers with major change of rendering engine
    • This effectively makes the last version with the old rendering engine obsolete
    • Rules as for Obsolete Browsers, but selection needs to be aware that there are 'later' versions
    • These browsers are:-
      • Android Browser (at 4.4.4)
      • Opera with Presto
  3. Automatically Updated Browsers
    • These browsers have short-lived, sub-yearly versions
    • They are probably best discovered by matching for all released versions after a specific release date (eg 2 years ago)
    • Using a percentage isn't wise as usage of each version will change rapidly (from near zero to a few percentage points, then to near zero again), and certainly likely to change more rapidly than static website rebuilds
    • These browsers are:-
      • Firefox
      • Safari
      • Microsoft Edge
      • Chrome
      • Opera with Webkit Rendering Engine
  4. Long-Term Releases of Automatically Updated Browsers
    • These browsers have occasional long-term releases which are intended to be supported for a year or more
    • Usage percentages for these may be very low globally, and they may be 9 or more release versions 'out-of-date', but they represent an important audience
    • In practice the length of time each long term release is supported for changes with each release, even though vendors have 'long term release policies'
    • This is because policies change in the long interval between long-term releases
    • These browsers are problematic to identify as the caniuse.com database omits them
    • Some long-term release versions differ slightly in supported features, particularly those of a more experimental nature, to their related short-term release cousins (even though they may share the same major version number)
    • For Firefox, ESR releases are supposedly for one year (actually, 54 weeks, '9-cycles', with a 12-week ('2-cycle') overlap between releases (a cycle is a Firefox release cycle, typically 6 weeks), but, as always for these sorts of releases, the policy has changed several times.
    • These browsers are:-
      • Firefox
  5. Regionally significant, occasionally automatically updated browsers
    • Support of these browsers is particularly important for the Indian and Asian markets
    • Many cheaper smart phones come with them (I've used them, too)
    • Vendors frequently don't upgrade old firmware installed versions and some older versions may persist and have higher usage for some time than newer ones
    • All of them currently are just more dated versions of the Webkit rendering engine than Chrome
    • These browsers are probably best supported with a 'above X% rule', where X is for any version
    • These browsers are:-
      • UC Browser
      • Samsung Internet
      • QQ Browser
      • Baidu Browser
  6. Very different from mainstream and unsupportable
    • Opera Mini is an excellent product, but unless one is explicitly targeting its users' demographic, it is not useful to support
    • If one is targeting its users demographic, its lack of modern features (making it the lowest common denominator) means website development would not make use of caniuse.com data; it's too different.

Modules

regional_usage

Support for Agent regional, continental and world-wide usage by version. Use the RegionalUsages enum preferably.

Structs

Agent

An agent is effectively a browser. It is not a rendering engine, although it is closely related

AgentNameAndVersionSet

Encapsulates choices of Agent and Version of that agent

AgentNameIterator

A struct that exists to workaround Rust's lack (yet) of 'impl Trait'

Bug

A Bug is a text note. Not often used by the caniuse.com database.

CanIUse

A database of data relating to caniuse.com Not used directly, but references should be passed to methods on AgentName, FeatureName, EraName, and, less usefully, Status and ParentCategory.

EmbeddedCanIUseDatabase

The up-to-date version of the caniuse.com database shipped embedded in this crate.

Feature

A feature is a HTML, CSS or like feature that agents may not have support for.

FeatureName

A feature name is a lower case, possibly hyphenated string representing a particular HTML, CSS or like feature that agents may not have support for.

FeatureNameIterator

A struct that exists to workaround Rust's lack (yet) of 'impl Trait'

Link

A Link is an URL and its title, representing a link to a specification document or subsection

ParentCategoryIterator

A struct that exists to workaround Rust's lack (yet) of 'impl Trait'

StatusIterator

A struct that exists to workaround Rust's lack (yet) of 'impl Trait'

Support

Represents details of support

SupportRangeIterator

A struct that exists to workaround Rust's lack (yet) of 'impl Trait'

UsagePercentage

A simple 'newtype' wrapper that represents a percentage

Version

Version "3" and "3.0" are not considered equal; "3.0" is greater than "3". Opera and iOS Safari have hyphenation ranges of versions, eg "4.0-4.2". These are converted to a version matching the lower of the range, eg "4.0". Safari also has "TP" for its latest version, which is not stable across time and is converted to the VersionPart::TechnologyPreview, and Opera Mini just has "all"; it is effectively unversioned.

VersionDetail

Details about a particular version, of which only the release_date is particularly useful. The era is a relative value which can change with releases of the caniuse.com database, and the global_usage can differ to that available in RegionalUsage::WorldWide.

Enums

AgentName

The name of this agent

AgentType

Represents whether an agent is used primarily of the desktop or a mobile device

Category

One or more categories are associated with each Feature

ParentCategory

A ParentCategory is used in the caniuse.com UI. It is of limited use otherwise.

Prefix

The prefix put before at-rules, property names and property values

Status

A Status reflects the 'standardisation' of a feature

SupportMaturity

Represents the maturity of support in an agent

Functions

sensible_choices

Obtain (CanIUse, AgentNameAndVersionSet) for, say, autoprefix_stylesheet() in the css-autoprefix crate.

sensible_choices_default

Obtain (CanIUse, AgentNameAndVersionSet) for, say, autoprefix_stylesheet() in the css-autoprefix crate.