refactor: convert env to a class

Because we now share `env` by passing it around, not by relying on the module cache.

packages/jsdoc-core/index.js

@@ -13,6 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 /**
  * Core functionality for JSDoc.
  *
@@ -20,9 +21,9 @@
  */
 import * as config from './lib/config.js';
 import Dependencies from './lib/dependencies.js';
-import env from './lib/env.js';
+import Env from './lib/env.js';
 import * as name from './lib/name.js';
 import * as plugins from './lib/plugins.js';
 
-export { config, Dependencies, env, name, plugins };
+export { config, Dependencies, Env, name, plugins };
-export default { config, Dependencies, env, name, plugins };
+export default { config, Dependencies, Env, name, plugins };

packages/jsdoc-core/lib/env.js

@@ -13,64 +13,66 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 /**
  * Data about the environment in which JSDoc is running, including the configuration settings that
  * were used to run JSDoc.
  *
- * @alias @jsdoc/core.env
+ * @alias @jsdoc/core.Env
  */
-export default {
+export default class Env {
-  /**
+  constructor() {
-   * The times at which JSDoc started and finished.
+    /**
-   *
+     * The times at which JSDoc started and finished.
-   * @type {Object}
+     *
-   * @property {Date} start - The time at which JSDoc started running.
+     * @type {Object}
-   * @property {Date} finish - The time at which JSDoc finished running.
+     * @property {Date} start - The time at which JSDoc started running.
-   */
+     * @property {Date} finish - The time at which JSDoc finished running.
-  run: {
+     */
-    start: new Date(),
+    this.run = {
-    finish: null,
+      start: new Date(),
-  },
+      finish: null,
+    };
 
-  /**
+    /**
-   * The command-line arguments passed to JSDoc.
+     * The command-line arguments passed to JSDoc.
-   *
+     *
-   * @type {Array<*>}
+     * @type {Array<*>}
-   */
+     */
-  args: [],
+    this.args = [];
 
-  /**
+    /**
-   * The data parsed from JSDoc's configuration file.
+     * The data parsed from JSDoc's configuration file.
-   *
+     *
-   * @type Object<string, *>
+     * @type Object<string, *>
-   */
+     */
-  conf: {},
+    this.conf = {};
 
-  /**
+    /**
-   * The command-line arguments, parsed into a key/value hash.
+     * The command-line arguments, parsed into a key/value hash.
-   *
+     *
-   * @type {Object}
+     * @type {Object}
-   * @example if (global.env.opts.help) { console.log('Helpful message.'); }
+     * @example if (global.env.opts.help) { console.log('Helpful message.'); }
-   */
+     */
-  opts: {},
+    this.opts = {};
 
-  /**
+    /**
-   * The source files that JSDoc will parse.
+     * The source files that JSDoc will parse.
-   *
+     *
-   * @type {Array<string>}
+     * @type {Array<string>}
-   * @memberof env
+     */
-   */
+    this.sourceFiles = [];
-  sourceFiles: [],
 
-  /**
+    /**
-   * The JSDoc version number and revision date.
+     * The JSDoc version number and revision date.
-   *
+     *
-   * @type {Object<string, string>}
+     * @type {Object<string, string>}
-   * @property {string} number - The JSDoc version number.
+     * @property {string} number - The JSDoc version number.
-   * @property {string} revision - The JSDoc revision number, expressed as a UTC date string.
+     * @property {string} revision - The JSDoc revision number, expressed as a UTC date string.
-   */
+     */
-  version: {
+    this.version = {
-    number: null,
+      number: null,
-    revision: null,
+      revision: null,
-  },
+    };
-};
+  }
+}

packages/jsdoc-core/test/specs/index.js

@@ -13,10 +13,11 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 import core from '../../index.js';
 import * as config from '../../lib/config.js';
 import Dependencies from '../../lib/dependencies.js';
-import env from '../../lib/env.js';
+import Env from '../../lib/env.js';
 import * as name from '../../lib/name.js';
 import * as plugins from '../../lib/plugins.js';
 
@@ -33,9 +34,9 @@ describe('@jsdoc/core', () => {
     });
   });
 
-  describe('env', () => {
+  describe('Env', () => {
     it('is lib/env', () => {
-      expect(core.env).toEqual(env);
+      expect(core.Env).toEqual(Env);
     });
   });
 

packages/jsdoc-core/test/specs/lib/env.js

@@ -13,38 +13,47 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
-import env from '../../../lib/env.js';
 
-describe('@jsdoc/core.env', () => {
+import Env from '../../../lib/env.js';
-  it('exists', () => {
+
-    expect(env).toBeObject();
+describe('@jsdoc/core.Env', () => {
+  it('is a constructor', () => {
+    function factory() {
+      return new Env();
+    }
+
+    expect(factory).not.toThrow();
   });
 
-  it('has an `args` property', () => {
+  describe('properties', () => {
-    expect(env.args).toBeArray();
+    const env = new Env();
-  });
 
-  it('has a `conf` property', () => {
+    it('has an `args` property', () => {
-    expect(env.conf).toBeObject();
+      expect(env.args).toBeArray();
-  });
+    });
 
-  it('has an `opts` property', () => {
+    it('has a `conf` property', () => {
-    expect(env.opts).toBeObject();
+      expect(env.conf).toBeObject();
-  });
+    });
 
-  it('has a `run` object with `start` and `finish` properties', () => {
+    it('has an `opts` property', () => {
-    expect(env.run).toBeObject();
+      expect(env.opts).toBeObject();
-    expect(env.run.finish).toBeNull();
+    });
-    expect(env.run.start).toBeInstanceOf(Date);
-  });
 
-  it('has a `sourceFiles` property', () => {
+    it('has a `run` object with `start` and `finish` properties', () => {
-    expect(env.sourceFiles).toBeArray();
+      expect(env.run).toBeObject();
-  });
+      expect(env.run.finish).toBeNull();
+      expect(env.run.start).toBeInstanceOf(Date);
+    });
 
-  it('has a `version` object with `number` and `revision` properties', () => {
+    it('has a `sourceFiles` property', () => {
-    expect(env.version).toBeObject();
+      expect(env.sourceFiles).toBeArray();
-    expect(Object.hasOwn(env.version, 'number')).toBeTrue();
+    });
-    expect(Object.hasOwn(env.version, 'revision')).toBeTrue();
+
+    it('has a `version` object with `number` and `revision` properties', () => {
+      expect(env.version).toBeObject();
+      expect(Object.hasOwn(env.version, 'number')).toBeTrue();
+      expect(Object.hasOwn(env.version, 'revision')).toBeTrue();
+    });
   });
 });

packages/jsdoc/jsdoc.js

@@ -14,11 +14,13 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
-import { env } from '@jsdoc/core';
+import { Env } from '@jsdoc/core';
 
 import cli from './cli.js';
 
 (async () => {
+  const env = new Env();
+
   env.args = process.argv.slice(2);
   cli.setEnv(env).setVersionInfo();
   await cli.loadConfig();