fix: small fixes to the types and implement cjs2esm

Merge pull request #70 from homer0/homer0_fixes

.jsdoc.js

@@ -33,11 +33,22 @@ module.exports = {
       'Tutorials',
     ],
     collapse: true,
-    menu: {
-      'GitHub': {
-        href: `https://github.com/${packageJson.repository}`,
-        target: '_blank',
+    refLinks: [
+      {
+        title: 'View the package on Yarn',
+        url: `https://yarnpkg.com/package/${packageJson.name}`,
+        type: 'yarn',
       },
-    },
+      {
+        title: 'Go to the GitHub repository',
+        url: `https://github.com/${packageJson.repository}`,
+        type: 'github',
+      },
+      {
+        title: 'View the package on NPM',
+        url: `https://www.npmjs.com/package/${packageJson.name}`,
+        type: 'npm',
+      },
+    ],
   },
 };

README.md

@@ -150,7 +150,6 @@ Since the next LTS to become "the oldest" is 12, which still uses the flag, I st
 | `docs`     | Generates the project documentation. |
 | `lint`     | Lints the staged files.              |
 | `lint:all` | Lints the entire project code.       |
-| `prepare`  | Generates the project ESM version.   |
 | `test`     | Runs the project unit tests.         |
 | `todo`     | Lists all the pending to-do's.       |
 

node/appConfiguration.js

@@ -12,8 +12,7 @@ const { providerCreator } = require('../shared/jimpleFns');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -423,7 +422,7 @@ class AppConfiguration {
 /**
  * The service provider to register an instance of {@link AppConfiguration} on the container.
  *
- * @type {ProviderCreatorWithOptions<AppConfigurationProviderOptions>}
+ * @type {ProviderCreator<AppConfigurationProviderOptions>}
  * @tutorial appConfiguration
  */
 const appConfiguration = providerCreator((options = {}) => (app) => {

node/environmentUtils.js

@@ -4,8 +4,7 @@ const { providerCreator } = require('../shared/jimpleFns');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -131,7 +130,7 @@ class EnvironmentUtils {
 /**
  * The service provider to register an instance of {@link EnvironmentUtils} on the container.
  *
- * @type {ProviderCreatorWithOptions<EnvironmentUtilsProviderOptions>}
+ * @type {ProviderCreator<EnvironmentUtilsProviderOptions>}
  * @tutorial environmentUtils
  */
 const environmentUtils = providerCreator((options = {}) => (app) => {

node/errorHandler.js

@@ -9,8 +9,7 @@ const { deepAssignWithShallowMerge } = require('../shared/deepAssign');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -142,7 +141,7 @@ class ErrorHandler {
  *
  * @throws {Error} If `services.logger` specifies a service that doesn't exist or if it's a falsy
  *                 value.
- * @type {ProviderCreatorWithOptions<ErrorHandlerProviderOptions>}
+ * @type {ProviderCreator<ErrorHandlerProviderOptions>}
  * @tutorial errorHandler
  */
 const errorHandler = providerCreator((options = {}) => (app) => {

node/logger.js

@@ -6,8 +6,7 @@ const { deepAssign } = require('../shared/deepAssign');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -265,7 +264,7 @@ class Logger {
 /**
  * The service provider to register an instance of {@link Logger} on the container.
  *
- * @type {ProviderCreatorWithOptions<LoggerProviderOptions>}
+ * @type {ProviderCreator<LoggerProviderOptions>}
  * @tutorial logger
  */
 const logger = providerCreator((options = {}) => (app) => {
@@ -278,7 +277,7 @@ const logger = providerCreator((options = {}) => (app) => {
  * The service provider to register an instance of {@link Logger} with the package name as
  * messages prefix on the container.
  *
- * @type {ProviderCreatorWithOptions<AppLoggerProviderOptions>}
+ * @type {ProviderCreator<AppLoggerProviderOptions>}
  * @tutorial logger
  */
 const appLogger = providerCreator((options = {}) => (app) => {

node/packageInfo.js

@@ -10,8 +10,7 @@ const { deepAssign } = require('../shared/deepAssign');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -46,7 +45,7 @@ const packageInfo = (pathUtils) => fs.readJsonSync(pathUtils.join('package.json'
  * The service provider that once registered on the app container will set the result of
  * {@link module:node/packageInfo~packageInfo|packageInfo} as a service.
  *
- * @type {ProviderCreatorWithOptions<PackageInfoProviderOptions>}
+ * @type {ProviderCreator<PackageInfoProviderOptions>}
  * @tutorial packageInfo
  */
 const packageInfoProvider = providerCreator((options = {}) => (app) => {

node/pathUtils.js

@@ -5,8 +5,7 @@ const { providerCreator } = require('../shared/jimpleFns');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -167,7 +166,7 @@ class PathUtils {
 /**
  * The service provider to register an instance of {@link PathUtils} on the container.
  *
- * @type {ProviderCreatorWithOptions<PathUtilsProviderOptions>}
+ * @type {ProviderCreator<PathUtilsProviderOptions>}
  * @tutorial pathUtils
  */
 const pathUtils = providerCreator((options = {}) => (app) => {

node/rootRequire.js

@@ -9,8 +9,7 @@ const { deepAssign } = require('../shared/deepAssign');
  */
 
 /**
- * @typedef {import('../shared/jimpleFns').ProviderCreatorWithOptions<O>}
- * ProviderCreatorWithOptions
+ * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  * @template O
  */
 
@@ -56,7 +55,7 @@ const rootRequire = (pathUtils) => (path) =>
  * The service provider that once registered on the app container will set the result of
  * {@link module:node/rootRequire~rootRequire|rootRequire} as a service.
  *
- * @type {ProviderCreatorWithOptions<RootRequireProviderOptions>}
+ * @type {ProviderCreator<RootRequireProviderOptions>}
  * @tutorial rootRequire
  */
 const rootRequireProvider = providerCreator((options = {}) => (app) => {

package.json

@@ -14,22 +14,20 @@
     "extend": "^3.0.2"
   },
   "devDependencies": {
-    "@babel/core": "^7.10.5",
-    "@babel/preset-env": "^7.10.4",
     "@semantic-release/changelog": "^5.0.1",
     "@semantic-release/git": "^9.0.0",
-    "5to6-codemod": "1.8.0",
+    "cjs2esm": "^1.1.0",
     "commitizen": "^4.1.2",
     "cz-conventional-changelog": "^3.2.0",
-    "eslint": "^7.4.0",
-    "eslint-plugin-homer0": "^5.0.0",
+    "eslint": "^7.6.0",
+    "eslint-plugin-homer0": "^5.0.2",
     "husky": "^4.2.5",
-    "jest": "^26.1.0",
-    "jscodeshift": "0.10.0",
-    "jsdoc": "^3.6.4",
+    "jest": "^26.2.2",
+    "jimple": "^1.5.0",
+    "jsdoc": "^3.6.5",
     "jsdoc-ts-utils": "^1.0.0",
-    "docdash": "homer0/docdash#semver:^2.0.0",
-    "leasot": "^11.0.0",
+    "docdash": "homer0/docdash#semver:^2.1.0",
+    "leasot": "^11.1.0",
     "lint-staged": "^10.2.11",
     "semantic-release": "^17.1.1"
   },
@@ -48,14 +46,17 @@
     "*.js": "eslint"
   },
   "scripts": {
-    "prepare": "./utils/scripts/prepare",
+    "prepublishOnly": "./utils/scripts/prepublishOnly",
     "test": "./utils/scripts/test",
     "lint": "./utils/scripts/lint",
     "lint:all": "./utils/scripts/lint-all",
     "docs": "./utils/scripts/docs",
     "todo": "./utils/scripts/todo"
   },
   "config": {
+    "cjs2esm": {
+      "input": ["browser", "node", "shared"]
+    },
     "commitizen": {
       "path": "cz-conventional-changelog"
     }

shared/extendPromise.js

@@ -60,6 +60,18 @@ class PromiseExtender {
     }
 
     return new Proxy(promise, {
+      /**
+       * This is a trap for when something is trying to read/access a property for the promise.
+       * The function first validates if it's one of the functions (`then`/`catch`/`finally`) in
+       * order to return a proxied function; then, if it's another function (one that doesn't
+       * return another promise), it just calls the original; finally, before doing a fallback to
+       * the original promise, it checks if it's one of the custom properties that exented the
+       * promise.
+       *
+       * @param {Promise} target The original promise.
+       * @param {string}  name   The name of the property.
+       * @returns {*}
+       */
       get: (target, name) => {
         let result;
         if (['then', 'catch', 'finally'].includes(name)) {
@@ -89,6 +101,17 @@ class PromiseExtender {
    */
   _extendFunction(fn, properties) {
     return new Proxy(fn, {
+      /**
+       * This is a trap for when a function gets called (remember this gets used for `then`/
+       * `catch`/`finally`); it processes the result using the oringinal function and since promise
+       * methods return a promise, instead of returning the original result, it returns an
+       * _extended_ version of it.
+       *
+       * @param {Function} target  The original function.
+       * @param {Promise}  thisArg The promise the function belongs to.
+       * @param {Array}    args    The list of arguments sent to the trap.
+       * @returns {Promise}
+       */
       apply: (target, thisArg, args) => {
         const value = target.bind(thisArg)(...args);
         return this._extend(value, properties);

shared/jimpleFns.js

@@ -19,20 +19,68 @@
  * @property {ProviderRegisterFn} register The method that gets called when registering the
  *                                         provider.
  * @parent module:shared/jimpleFns
+ * @example
+ * container.register(myProvider);
  */
 
 /**
+ * A function called in order to generate a {@link Provider}. They usually have different options
+ * that will be sent to the provider creation.
+ *
  * @callback ProviderCreatorFn
  * @returns {Provider}
  * @parent module:shared/jimpleFns
  */
 
 /**
- * @callback ProviderCreatorWithOptions
+ * A special kind of {@link Provider} that can be used as a regular provider, or it can also be
+ * called as a function with custom options in order to obtain a "configured {@link Provider}".
+ *
+ * @callback ProviderCreator
  * @param {Partial<O>} [options={}] The options to create the provider.
  * @returns {Provider}
  * @template O
+ * @property {ProviderRegisterFn} register The method that gets called when registering the
+ *                                         provider.
  * @parent module:shared/jimpleFns
+ * @example
+ * // Register it with its default options.
+ * container.register(myProvider);
+ * // Register it with custom options.
+ * container.register(myProvider({ enabled: true }));
+ */
+
+/**
+ * @typedef {Object.<string,Provider>} ProvidersDictionary
+ */
+
+/**
+ * @typedef {ProvidersDictionary & ProvidersProperties} Providers
+ */
+
+/**
+ * @typedef {Object} ProvidersProperties
+ * @property {ProviderRegisterFn} register The function that will register all the providers on the
+ *                                         container.
+ * @augments ProvidersDictionary
+ */
+
+/**
+ * Generates a collection of {@link Provider} objects that can be used to register all of them
+ * at once.
+ *
+ * @example
+ * // Generate the collection
+ * const myProviders = providers({ oneProvider, otherProvider });
+ * // Register all of them
+ * container.register(myProviders);
+ * // Register only one
+ * container.register(myProviders.otherProvider);
+ *
+ * @callback ProvidersCreator
+ * @param {Object.<string,Provider>} providers The dictionary of providers to add to the
+ *                                             collection.
+ * @returns {Providers}
  */
 
 /**
@@ -80,7 +128,7 @@
  * make use of.
  *
  * @example
- * <caption>The `provider` shorthand functino is an _entity_ with a `register` function:</caption>
+ * <caption>The `provider` shorthand function is an _entity_ with a `register` function:</caption>
  * const someProvider = resource('provider', 'register', (app) => {
  *   // ...
  * });
@@ -231,24 +279,45 @@ const resourcesCollection = (name, key, fn = null) => (items) => {
   };
 };
 /**
- * Creates a provider resource.
+ * Creates a resource provider.
+ *
+ * @example
+ * // Define the provider
+ * const myService = provider((app) => {
+ *   app.set('myService', () => new MyService());
+ * });
+ *
+ * // Register it on the container
+ * container.register(myService);
  *
  * @param {ProviderRegisterFn} registerFn The function the container will call in order to
  *                                        register the provider.
  * @returns {Provider}
  */
 const provider = (registerFn) => resource('provider', 'register', registerFn);
 /**
- * Creates a configurable provider.
+ * Creates a configurable provider. It's configurable because the creator, instead of just
+ * being sent to the container to register, it can also be called as a function with custom
+ * options and generate a new provider.
  *
- * @param {ProviderCreatorFn} creatorFn The function that will be used to create the provider.
- * @returns {ResourceCreator}
+ * @example
+ * // Define the provider creator
+ * const myProvider = providerCreator((options = {}) => (app) => {
+ *   app.set('myService', () => new MyService(options));
+ * });
+ * // Register it with the default options
+ * container.register(myProvider);
+ * // Register it with custom options
+ * container.register(myProvider({ enabled: true }));
+ *
+ * @param {ProviderCreatorFn} creatorFn The function that generates the provider.
+ * @returns {ProviderCreator<*>}
  */
 const providerCreator = (creatorFn) => resourceCreator('provider', 'register', creatorFn);
 /**
  * Creates a collection of providers.
  *
- * @type {ResourcesCollectionCreator<Provider>}
+ * @type {ProvidersCreator}
  */
 const providers = resourcesCollection('providers', 'register');