Merge pull request #13399 from meteor/feature/docs-setMinimumBrowserVersions

Docs page for modern-browsers

packages/modern-browsers/modern.js

@@ -42,28 +42,32 @@ const browserAliases = {
   safari: ['appleMail'],
 };
 
-// Expand the given minimum versions by reusing chrome versions for
-// chromeMobile (according to browserAliases above).
+/**
+ * Expand the given minimum versions by reusing chrome versions for
+ * chromeMobile (according to browserAliases above).
+ * @param versions {object}
+ * @return {any}
+ */
 function applyAliases(versions) {
   const lowerCaseVersions = Object.create(null);
 
-  Object.keys(versions).forEach(browser => {
+  for (const browser of Object.keys(versions)) {
     lowerCaseVersions[browser.toLowerCase()] = versions[browser];
-  });
+  }
 
-  Object.keys(browserAliases).forEach(original => {
+  for (let original of Object.keys(browserAliases)) {
     const aliases = browserAliases[original];
     original = original.toLowerCase();
 
     if (hasOwn.call(lowerCaseVersions, original)) {
-      aliases.forEach(alias => {
+      for (let alias of aliases) {
         alias = alias.toLowerCase();
         if (!hasOwn.call(lowerCaseVersions, alias)) {
           lowerCaseVersions[alias] = lowerCaseVersions[original];
         }
-      });
+      }
     }
-  });
+  }
 
   return lowerCaseVersions;
 }
@@ -71,9 +75,15 @@ function applyAliases(versions) {
 // TODO Should it be possible for callers to setMinimumBrowserVersions to
 // forbid any version of a particular browser?
 
-// Given a { name, major, minor, patch } object like the one provided by
-// webapp via request.browser, return true if that browser qualifies as
-// "modern" according to all requested version constraints.
+/**
+ * @name ModernBrowsers.isModern
+ * @summary Given a { name, major, minor, patch } object like the one provided by
+ * webapp via request.browser, return true if that browser qualifies as
+ * "modern" according to all requested version constraints.
+ * @locus server
+ * @param [browser] {object} { name: string, major: number, minor?: number, patch?: number }
+ * @return {boolean}
+ */
 function isModern(browser) {
   const lowerCaseName =
     browser && typeof browser.name === 'string' && browser.name.toLowerCase();
@@ -88,29 +98,44 @@ function isModern(browser) {
   );
 }
 
-// Any package that depends on the modern-browsers package can call this
-// function to communicate its expectations for the minimum browser
-// versions that qualify as "modern." The final decision between
-// web.browser.legacy and web.browser will be based on the maximum of all
-// requested minimum versions for each browser.
+/**
+ * @name ModernBrowsers.setMinimumBrowserVersions
+ * @summary Any package that depends on the modern-browsers package can call this
+ * function to communicate its expectations for the minimum browser
+ * versions that qualify as "modern." The final decision between
+ * web.browser.legacy and web.browser builds will be based on the maximum of all
+ * requested minimum versions for each browser.
+ * @locus server
+ * @param versions {object} Name of the browser engine and minimum version for at which it is considered modern. For example: {
+ *   chrome: 49,
+ *   edge: 12,
+ *   ie: 12,
+ *   firefox: 45,
+ *   mobileSafari: 10,
+ *   opera: 38,
+ *   safari: 10,
+ *   electron: [1, 6],
+ * }
+ * @param source {function} Name of the capability that requires these minimums.
+ */
 function setMinimumBrowserVersions(versions, source) {
   const lowerCaseVersions = applyAliases(versions);
 
-  Object.keys(lowerCaseVersions).forEach(lowerCaseName => {
+  for (const lowerCaseName of Object.keys(lowerCaseVersions)) {
     const version = lowerCaseVersions[lowerCaseName];
 
     if (
       hasOwn.call(minimumVersions, lowerCaseName) &&
       !greaterThan(version, minimumVersions[lowerCaseName].version)
     ) {
-      return;
+      continue;
     }
 
     minimumVersions[lowerCaseName] = {
       version: copy(version),
       source: source || getCaller('setMinimumBrowserVersions'),
     };
-  });
+  }
 }
 
 function getCaller(calleeName) {
@@ -127,12 +152,23 @@ function getCaller(calleeName) {
   return caller;
 }
 
+/**
+ * @name ModernBrowsers.getMinimumBrowserVersions
+ * @summary Returns an object that lists supported browser engines and their minimum versions to be considered modern for Meteor.
+ * @locus server
+ * @return {object}
+ */
 function getMinimumBrowserVersions() { return minimumVersions; }
 
 Object.assign(exports, {
   isModern,
   setMinimumBrowserVersions,
   getMinimumBrowserVersions,
+  /**
+   * @name ModernBrowsers.calculateHashOfMinimumVersions
+   * @summary Creates a hash of the object of minimum browser versions.
+   * @return {string}
+   */
   calculateHashOfMinimumVersions() {
     const { createHash } = require('crypto');
     return createHash('sha1')

v3-docs/docs/.vitepress/config.mts

@@ -338,6 +338,10 @@ export default defineConfig({
             text: "markdown",
             link: "/packages/markdown",
           },
+          {
+            text: "modern-browsers",
+            link: "/packages/modern-browsers",
+          },
           {
             text: "modules",
             link: "/packages/modules",

v3-docs/docs/api/packages-listing.md

@@ -105,6 +105,7 @@
 ### [mongo-dev-server](https://github.com/meteor/meteor/tree/devel/packages/mongo-dev-server) {#mongo-dev-server}
 ### [mongo-id](https://github.com/meteor/meteor/tree/devel/packages/mongo-id) {#mongo-id}
 ### [mongo-livedata](https://github.com/meteor/meteor/tree/devel/packages/mongo-livedata) {#mongo-livedata}
+### [npm-bcrypt](https://github.com/meteor/meteor/tree/devel/packages/npm-bcrypt) {#npm-bcrypt}
 ### [npm-mongo](https://github.com/meteor/meteor/tree/devel/packages/npm-mongo) {#npm-mongo}
 ### [oauth](https://github.com/meteor/meteor/tree/devel/packages/oauth) {#oauth}
 ### [oauth-encryption](https://github.com/meteor/meteor/tree/devel/packages/oauth-encryption) {#oauth-encryption}

v3-docs/docs/history.md

@@ -11,7 +11,6 @@ This is a complete history of changes for Meteor releases.
 [//]: # (go to meteor/docs/generators/changelog/docs)
 
 
-
 ## v3.1.1, 2025-01-15
 
 ### Highlights
@@ -83,6 +82,7 @@ N/A
 - [@quyetdgroup](https://github.com/quyetdgroup)
 
 ✨✨✨
+
 ## v3.1.0, 2024-11-20
 
 ### Highlights

v3-docs/docs/packages/modern-browsers.md

@@ -0,0 +1,19 @@
+# Modern-browsers
+
+
+API for defining the boundary between modern and legacy JavaScript clients.
+
+You can use this package to define the minimum browser versions for which
+a browser engine will be considered modern. All browsers that do not meet
+the threshold will receive the legacy bundle. This way you can easily keep
+on using modern features that you need.
+
+You can read more about this in [Meteor 1.7 announcement blog](https://blog.meteor.com/meteor-1-7-and-the-evergreen-dream-a8c1270b0901).
+
+<ApiBox name="ModernBrowsers.isModern" />
+
+<ApiBox name="ModernBrowsers.setMinimumBrowserVersions" />
+
+<ApiBox name="ModernBrowsers.getMinimumBrowserVersions" />
+
+<ApiBox name="ModernBrowsers.calculateHashOfMinimumVersions" />