baseline-browser-mapping 2.11.13: getTimeline

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify baseline-browser-mapping.getTimeline in pkg:npm/baseline-browser-mapping@2.11.13
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/baseline-browser-mapping@2.11.13
Demonstrate these symbols/APIs:
  - baseline-browser-mapping.getTimeline

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:e1b58df3523967889c103ddeb72decee234155c77a62e855e841b2776e258acb","constraints":{"executionContext":"node"},"contract":["getTimeline returns chronologically ordered timeline events with date and changed browsers by default","getTimeline returns all compatible browsers for each event when listAllBrowsers is true","getTimeline returns browser history mapping when groupBy is browser","getTimeline includes downstream browser engines when includeDownstreamBrowsers is true","getTimeline includes KaiOS when includeKaiOS and includeDownstreamBrowsers are true","getTimeline throws error when includeKaiOS is enabled without downstream browsers"],"goal":"verify baseline-browser-mapping.getTimeline in pkg:npm/baseline-browser-mapping@2.11.13","kind":"HOW","packages":["pkg:npm/baseline-browser-mapping@2.11.13"],"schemaVersion":1,"symbols":["baseline-browser-mapping.getTimeline"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/baseline-browser-mapping@2.11.13"],"schemaVersion":1,"subject":"pkg:npm/baseline-browser-mapping@2.11.13","symbols":["baseline-browser-mapping.getTimeline"],"verifierAdapter":"node-typescript@1"}

{
  "name": "baseline-browser-mapping-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "baseline-browser-mapping-sample",
      "version": "1.0.0",
      "dependencies": {
        "baseline-browser-mapping": "2.11.13"
      }
    },
    "node_modules/baseline-browser-mapping": {
      "version": "2.11.13",
      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.13.tgz",
      "integrity": "sha512-k9HNuUVMlqVjQ9UHzfPjIqiDbWw7WqT1AoT7GL8VwvF3r0ZfArtgiSPAlmupyNquNgOJHTuH4CKYf8ttMTWBTQ==",
      "license": "Apache-2.0",
      "bin": {
        "baseline-browser-mapping": "dist/cli.cjs"
      },
      "engines": {
        "node": ">=6.0.0"
      }
    }
  }
}

{
  "name": "baseline-browser-mapping-sample",
  "version": "1.0.0",
  "dependencies": {
    "baseline-browser-mapping": "2.11.13"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify baseline-browser-mapping.getTimeline in pkg:npm/baseline-browser-mapping@2.11.13",
  "kind": "HOW",
  "packages": [
    "pkg:npm/baseline-browser-mapping@2.11.13"
  ],
  "symbols": [
    "baseline-browser-mapping.getTimeline"
  ]
}

const { getTimeline } = require('baseline-browser-mapping');

/**
 * Retrieves timeline events or browser timelines based on baseline availability data.
 *
 * @param {import('baseline-browser-mapping/dist/types.js').TimelineOptions} [options]
 * @returns {any}
 */
function fetchTimeline(options = {}) {
  return getTimeline(options);
}

module.exports = {
  fetchTimeline,
  getTimeline,
};

const assert = require('node:assert/strict');
const {
  fetchTimeline,
  getTimeline,
} = require('../src/index.js');

// Contract 1: getTimeline returns chronologically ordered timeline events with date and changed browsers by default
{
  const timeline = fetchTimeline();
  assert.ok(Array.isArray(timeline), 'getTimeline should return an array by default');
  assert.ok(timeline.length > 0, 'timeline should have events');
  const firstEvent = timeline[0];
  assert.strictEqual(typeof firstEvent.date, 'string');
  assert.match(firstEvent.date, /^\d{4}-\d{2}-\d{2}$/);
  assert.ok(Array.isArray(firstEvent.browsers), 'event browsers should be an array');
  assert.strictEqual(firstEvent.browsers.length, 7, 'first baseline event contains 7 core browsers');
  const chrome = firstEvent.browsers.find((b) => b.browser === 'chrome');
  assert.ok(chrome, 'chrome should be present in initial event');
  assert.strictEqual(chrome.version, '38');
  assert.strictEqual(chrome.release_date, '2014-10-07');

  const secondEvent = timeline[1];
  assert.strictEqual(secondEvent.date, '2015-09-22');
  assert.strictEqual(secondEvent.browsers.length, 2, 'second event only contains changed browsers');
  const browserNames = secondEvent.browsers.map((b) => b.browser);
  assert.deepStrictEqual(browserNames, ['firefox', 'firefox_android']);
}

// Contract 2: getTimeline returns all compatible browsers for each event when listAllBrowsers is true
{
  const timeline = fetchTimeline({ listAllBrowsers: true });
  assert.ok(Array.isArray(timeline));
  const secondEvent = timeline[1];
  assert.strictEqual(secondEvent.date, '2015-09-22');
  assert.strictEqual(secondEvent.browsers.length, 7, 'should include all 7 core browsers when listAllBrowsers is true');
  const chrome = secondEvent.browsers.find((b) => b.browser === 'chrome');
  const firefox = secondEvent.browsers.find((b) => b.browser === 'firefox');
  assert.ok(chrome && firefox);
  assert.strictEqual(chrome.version, '38');
  assert.strictEqual(firefox.version, '41');
}

// Contract 3: getTimeline returns browser history mapping when groupBy is browser
{
  const browserMap = fetchTimeline({ groupBy: 'browser' });
  assert.strictEqual(typeof browserMap, 'object');
  assert.ok(!Array.isArray(browserMap));
  const coreBrowsers = ['chrome', 'chrome_android', 'edge', 'firefox', 'firefox_android', 'safari', 'safari_ios'];
  for (const b of coreBrowsers) {
    assert.ok(Array.isArray(browserMap[b]), `browserMap should contain history array for ${b}`);
    assert.ok(browserMap[b].length > 0, `history for ${b} should not be empty`);
    const firstEntry = browserMap[b][0];
    assert.strictEqual(typeof firstEntry.date, 'string');
    assert.strictEqual(typeof firstEntry.version, 'string');
    assert.ok('release_date' in firstEntry);
  }
}

// Contract 4: getTimeline includes downstream browser engines when includeDownstreamBrowsers is true
{
  const timeline = fetchTimeline({ includeDownstreamBrowsers: true });
  assert.ok(Array.isArray(timeline));
  const firstEvent = timeline[0];
  assert.ok(firstEvent.browsers.length > 7, 'first event should include downstream browsers');
  const opera = firstEvent.browsers.find((b) => b.browser === 'opera');
  assert.ok(opera, 'opera should be included in downstream browsers');
  assert.strictEqual(opera.engine, 'Blink');
  assert.strictEqual(typeof opera.engine_version, 'string');

  const browserMap = fetchTimeline({ groupBy: 'browser', includeDownstreamBrowsers: true });
  assert.ok(Array.isArray(browserMap.opera));
  assert.ok(Array.isArray(browserMap.samsunginternet_android));
  assert.ok(Array.isArray(browserMap.webview_android));
}

// Contract 5: getTimeline includes KaiOS when includeKaiOS and includeDownstreamBrowsers are true
{
  const browserMap = fetchTimeline({
    includeDownstreamBrowsers: true,
    includeKaiOS: true,
    groupBy: 'browser',
  });
  assert.ok(Array.isArray(browserMap.kai_os), 'kai_os should be present when includeKaiOS is true');
  assert.ok(browserMap.kai_os.length > 0);
  const firstKai = browserMap.kai_os[0];
  assert.strictEqual(firstKai.version, '2.0');
  assert.strictEqual(firstKai.engine, 'Gecko');
}

// Contract 6: getTimeline throws error when includeKaiOS is enabled without downstream browsers
{
  assert.throws(
    () => {
      fetchTimeline({
        includeKaiOS: true,
        includeDownstreamBrowsers: false,
      });
    },
    /KaiOS is a downstream browser and can only be included if you include other downstream browsers/,
    'Should throw when includeKaiOS is true without includeDownstreamBrowsers'
  );
}

console.log('All pkg:npm/baseline-browser-mapping@2.11.13 baseline-browser-mapping.getTimeline contracts passed successfully.');