Reduce frequency of data staleness warnings (#108)

* Data staleness warnings are now only shown if the `getCompatibleVersions()` or `getAllVersions()` functions are called - previously they were shown whenever the module was loaded, which meant many `browserslist` consumers were seeing the warning despite not targeting Baseline, especially those who were consuming `browserslist` in a pre-compiled format via `next.js`.
* Adds new conditions for these warnings to be displayed which should only warn users for whom data freshness is critical:
  * The feature cut off data must be within the last two months, i.e. `widelyAvailableOnDate: today + >2 years and 4 months` or `newly available` in a `browserslist` query.
  * The module data must be more than 2 months old.
  * None of the suppression mechanisms below are in use.
* Introduces suppression options for these warning via the `options` objects and environment variables:
  * Adds a new `suppressWarnings` boolean to the `getCompatibleVersions()` and `getAllVersions()` 
  * Respects the existing [`BROWSERSLIST_IGNORE_OLD_DATA`](browserslist/browserslist@0ae7155) environment variable.
  * Respects a new `BASELINE_BROWSER_MAPPING_IGNORE_OLD_DATA` environment variable.
* Adds explanatory text to the docs for how to avoid such warnings when reproducible builds are a requirement.
* Change warning text to be package manager agnostic and mention the possibility of pre-compiled data.

Fixes: #105 #107 #109

Author: tonypconway

.gitignore

@@ -6,4 +6,5 @@ baseline-browser-mapping-*.tgz
 .idx/
 .vscode/
 .idea/
-.DS_Store
+.DS_Store
+.env

README.md

@@ -23,10 +23,18 @@ To install the package, run:
 ]
 ```
 
-If your installed version of `baseline-browser-mapping` is greater than 2 months old, you will receive a console warning advising you to update to the latest version.
-
 The minimum supported NodeJS version for `baseline-browser-mapping` is v8 in alignment with `browserslist`. For NodeJS versions earlier than v13.2, the [`require('baseline-browser-mapping')`](https://nodejs.org/api/modules.html#requireid) syntax should be used to import the module.
 
+## Keeping `baseline-browser-mapping` up to date
+
+If you are only using this module to generate minimum browser versions for Baseline Widely available or Baseline year feature sets, you don't need to update this module frequently, as the backward looking data is reasonably stable.
+
+However, if you are targeting Newly available, using the [`getAllVersions()`](#get-data-for-all-browser-versions) function or heavily relying on the data for downstream browsers, you should update this module more frequently. If you target a feature cut off date within the last two months and your installed version of `baseline-browser-mapping` has data that is more than 2 months old, you will receive a console warning advising you to update to the latest version when you call `getCompatibleVersions()` or `getAllVersions()`.
+
+If you want to suppress these warnings you can use the `suppressWarnings: true` option in the configuration object passed to `getCompatibleVersions()` or `getAllVersions()`. Alternatively, you can use the `BASELINE_BROWSER_MAPPING_IGNORE_OLD_DATA=true` environment variable when running your build process. This module also respects the `BROWSERSLIST_IGNORE_OLD_DATA=true` environment variable. Environment variables can also be provided in a `.env` file from Node 20 onwards.
+
+If you want to ensure [reproducible builds](https://www.wikiwand.com/en/articles/Reproducible_builds), we strongly recommend using the `widelyAvailableOnDate` option to fix the Widely available date on a per build basis to ensure dependent tools provide the same output and you do not produce data staleness warnings. If you are using [`browserslist`](https://github.com/browserslist/browserslist) to target Baseline Widely available, consider automatically updating your `browserslist` configuration in `package.json` or `.browserslistrc` to `baseline widely available on {YYYY-MM-DD}` as part of your build process to ensure the same or sufficiently similar list of minimum browsers is reproduced for historical builds.
+
 ## Importing `baseline-browser-mapping`
 
 This module exposes two functions: `getCompatibleVersions()` and `getAllVersions()`, both which can be imported directly from `baseline-browser-mapping`:
@@ -95,7 +103,8 @@ Executed on 7th March 2025, the above code returns the following browser version
   targetYear: undefined,
   widelyAvailableOnDate: undefined,
   includeDownstreamBrowsers: false,
-  listAllCompatibleVersions: false
+  listAllCompatibleVersions: false,
+  suppressWarnings: false
 }
 ```
 
@@ -185,6 +194,16 @@ getCompatibleVersions({
 });
 ```
 
+#### `suppressWarnings`
+
+Setting `suppressWarnings` to `true` will suppress the console warning about old data:
+
+```javascript
+getCompatibleVersions({
+  suppressWarnings: true,
+});
+```
+
 ## Get data for all browser versions
 
 You may want to obtain data on all the browser versions available in this module for use in an analytics solution or dashboard. To get details of each browser version's level of Baseline support, call the `getAllVersions()` function:
@@ -237,7 +256,8 @@ Browser versions that do not support Widely or Newly available will not include
 ```javascript
 {
   includeDownstreamBrowsers: false,
-  outputFormat: "array"
+  outputFormat: "array",
+  suppressWarnings: false
 }
 ```
 
@@ -280,6 +300,16 @@ getAllVersions({
 });
 ```
 
+#### `suppressWarnings` (in `getAllVersions()` output)
+
+As with `getCompatibleVersions()`, you can set `suppressWarnings` to `true` to suppress the console warning about old data:
+
+```javascript
+getAllVersions({
+  suppressWarnings: true,
+});
+```
+
 #### `outputFormat`
 
 By default, this function returns an `Array` of `Objects` which can be manipulated in Javascript or output to JSON.