feature(@jsdoc/core): add simple inversion of control (IoC) tool

Currently unused. Intended to be used for JSDoc core dependencies that must be available everywhere, such as the config and the event bus.

packages/jsdoc-core/index.js

@@ -5,9 +5,11 @@
  */
 
 const config = require('./lib/config');
+const dependencies = require('./lib/dependencies');
 const name = require('./lib/name');
 
 module.exports = {
   config,
+  dependencies,
   name,
 };

packages/jsdoc-core/lib/dependencies.js

@@ -0,0 +1,42 @@
+const yaioc = require('yaioc');
+
+let dependencies;
+
+/**
+ * Container for JSDoc classes, objects, and values that can be injected into other modules.
+ *
+ * @alias module:@jsdoc/core.deps
+ */
+class Dependencies {
+  constructor() {
+    // This class provides a lightweight facade for the `yaioc` package.
+    this._container = yaioc.container();
+  }
+
+  get(name) {
+    const dep = this._container.get(name);
+
+    if (dep === undefined) {
+      throw new Error(`No dependency registered for the name "${name}"`);
+    }
+
+    return dep;
+  }
+
+  registerClass(klass, opts = {}) {
+    if (opts.singleton) {
+      this._container.cache().register(klass);
+    } else {
+      this._container.register(klass);
+    }
+  }
+
+  registerValue(name, value) {
+    this._container.register(name, value);
+  }
+}
+
+dependencies = new Dependencies();
+dependencies.Dependencies = Dependencies;
+
+module.exports = dependencies;

packages/jsdoc-core/package-lock.json

@@ -13,7 +13,8 @@
         "escape-string-regexp": "^4.0.0",
         "lodash": "^4.17.21",
         "strip-bom": "^4.0.0",
-				"strip-json-comments": "^3.1.1"
+        "strip-json-comments": "^3.1.1",
+        "yaioc": "^1.10.0"
       },
       "engines": {
         "node": ">=v14.17.6"
@@ -67,6 +68,20 @@
         "node": ">=4"
       }
     },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
     "node_modules/callsites": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -109,6 +124,11 @@
       "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz",
       "integrity": "sha1-p9BVi9icQveV3UIyj3QIMcpTvCU="
     },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s="
+    },
     "node_modules/cosmiconfig": {
       "version": "7.0.1",
       "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.0.1.tgz",
@@ -143,6 +163,30 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8="
+    },
+    "node_modules/glob": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
+      "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==",
+      "dependencies": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.0.4",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      },
+      "engines": {
+        "node": "*"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/has-flag": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz",
@@ -166,6 +210,20 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "dependencies": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
+    },
     "node_modules/is-arrayish": {
       "version": "0.2.1",
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
@@ -191,6 +249,25 @@
       "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
       "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="
     },
+    "node_modules/minimatch": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+      "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -219,6 +296,14 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/path-type": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
@@ -265,6 +350,19 @@
         "node": ">=4"
       }
     },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
+    },
+    "node_modules/yaioc": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/yaioc/-/yaioc-1.10.0.tgz",
+      "integrity": "sha512-IyMkzCVmHX9Iw9ogVS3MRAMbPtYJmzG6/lQbILYmveDFBqtPakzUiKZnsv2DSHJqO0rR437LaDzaBrsM4L+7+w==",
+      "dependencies": {
+        "glob": "^7.1.2"
+      }
+    },
     "node_modules/yaml": {
       "version": "1.10.2",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
@@ -311,6 +409,20 @@
         "color-convert": "^1.9.0"
       }
     },
+    "balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
+    },
+    "brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "requires": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
     "callsites": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -346,6 +458,11 @@
       "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz",
       "integrity": "sha1-p9BVi9icQveV3UIyj3QIMcpTvCU="
     },
+    "concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s="
+    },
     "cosmiconfig": {
       "version": "7.0.1",
       "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.0.1.tgz",
@@ -371,6 +488,24 @@
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
       "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="
     },
+    "fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8="
+    },
+    "glob": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
+      "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==",
+      "requires": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.0.4",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      }
+    },
     "has-flag": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz",
@@ -385,6 +520,20 @@
         "resolve-from": "^4.0.0"
       }
     },
+    "inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "requires": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
+    },
     "is-arrayish": {
       "version": "0.2.1",
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
@@ -410,6 +559,22 @@
       "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
       "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="
     },
+    "minimatch": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+      "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+      "requires": {
+        "brace-expansion": "^1.1.7"
+      }
+    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "requires": {
+        "wrappy": "1"
+      }
+    },
     "parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -429,6 +594,11 @@
         "lines-and-columns": "^1.1.6"
       }
     },
+    "path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18="
+    },
     "path-type": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
@@ -457,6 +627,19 @@
         "has-flag": "^3.0.0"
       }
     },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
+    },
+    "yaioc": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/yaioc/-/yaioc-1.10.0.tgz",
+      "integrity": "sha512-IyMkzCVmHX9Iw9ogVS3MRAMbPtYJmzG6/lQbILYmveDFBqtPakzUiKZnsv2DSHJqO0rR437LaDzaBrsM4L+7+w==",
+      "requires": {
+        "glob": "^7.1.2"
+      }
+    },
     "yaml": {
       "version": "1.10.2",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",

packages/jsdoc-core/package.json

@@ -26,7 +26,8 @@
     "escape-string-regexp": "^4.0.0",
     "lodash": "^4.17.21",
     "strip-bom": "^4.0.0",
-    "strip-json-comments": "^3.1.1"
+    "strip-json-comments": "^3.1.1",
+    "yaioc": "^1.10.0"
   },
   "engines": {
     "node": ">=v14.17.6"

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

@@ -13,6 +13,14 @@ describe('@jsdoc/core', () => {
     });
   });
 
+  describe('dependencies', () => {
+    it('is lib/dependencies', () => {
+      const dependencies = require('../../lib/dependencies');
+
+      expect(core.dependencies).toBe(dependencies);
+    });
+  });
+
   describe('name', () => {
     it('is lib/name', () => {
       const name = require('../../lib/name');

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

@@ -0,0 +1,100 @@
+const dependencies = require('../../../lib/dependencies');
+
+describe('@jsdoc/core/lib/dependencies', () => {
+  let container;
+
+  beforeEach(() => {
+    container = new dependencies.Dependencies();
+  });
+
+  it('is an object', () => {
+    expect(dependencies).toBeObject();
+  });
+
+  describe('Dependencies', () => {
+    it('is the constructor of the dependencies object', () => {
+      expect(dependencies.Dependencies).toBe(dependencies.constructor);
+    });
+  });
+
+  describe('get', () => {
+    it('throws an error if the name is missing', () => {
+      expect(() => container.get()).toThrowError();
+    });
+
+    it('throws an error if the name is unrecognized', () => {
+      expect(() => container.get('foo')).toThrowError();
+    });
+
+    it('returns an instance of classes', () => {
+      class Foo {}
+
+      let instance;
+
+      container.registerClass(Foo);
+      instance = container.get('foo');
+
+      expect(instance).toBeInstanceOf(Foo);
+    });
+
+    it('passes dependencies to instance constructors', () => {
+      class Foo {
+        constructor(bar) {
+          this.bar = bar;
+        }
+      }
+
+      class Bar {}
+
+      let instance;
+
+      container.registerClass(Foo);
+      container.registerClass(Bar);
+      instance = container.get('foo');
+
+      expect(instance.bar).toBeInstanceOf(Bar);
+    });
+
+    it('returns the same instance every time for singletons', () => {
+      class Foo {}
+
+      let instance1;
+      let instance2;
+
+      container.registerClass(Foo, { singleton: true });
+      instance1 = container.get('foo');
+      instance2 = container.get('foo');
+
+      expect(instance2).toBe(instance1);
+    });
+
+    it('returns static values', () => {
+      const value = new Set();
+
+      container.registerValue('foo', value);
+
+      expect(container.get('foo')).toBe(value);
+    });
+  });
+
+  describe('registerClass', () => {
+    // The tests for `get()` also test the behavior of these methods more extensively.
+    it('accepts a constructor', () => {
+      class Foo {}
+
+      expect(() => container.registerClass(Foo)).not.toThrow();
+    });
+
+    it('accepts a `singleton` option', () => {
+      class Foo {}
+
+      expect(() => container.registerClass(Foo, { singleton: true })).not.toThrow();
+    });
+  });
+
+  describe('registerValue', () => {
+    it('accepts a name and value', () => {
+      expect(() => container.registerValue('name', new Set())).not.toThrow();
+    });
+  });
+});