node/pathUtils.js

  1. const path = require('path');
  2. const { providerCreator } = require('../shared/jimpleFns');
  3. /**
  4.  * @module node/pathUtils
  5.  */
  7. /**
  8.  * @typedef {import('../shared/jimpleFns').ProviderCreator<O>} ProviderCreator
  9.  * @template O
  10.  */
  12. /**
  13.  * @typedef {Object} PathUtilsProviderOptions
  14.  * @property {string} serviceName  The name that will be used to register an instance of
  15.  *                                 {@link PathUtils}. Its default value is `pathUtils`.
  16.  * @property {string} [home]       The path to the new home location.
  17.  * @parent module:node/pathUtils
  18.  */
  20. /**
  21.  * A utility services to manage paths on a project. It allows for path building relatives
  22.  * to the project root or from where the app executable is located.
  23.  *
  24.  * @parent module:node/pathUtils
  25.  * @tutorial pathUtils
  26.  */
  27. class PathUtils {
  28.   /**
  29.    * @param {string} [home='']  The location of the project's `home`(root) directory. By
  30.    *                            default it uses `process.cwd()`.
  31.    */
  32.   constructor(home = '') {
  33.     /**
  34.      * The root path from where the app is being executed.
  35.      *
  36.      * @type {string}
  37.      * @access protected
  38.      * @ignore
  39.      */
  40.     this._path = process.cwd();
  41.     /**
  42.      * A dictionary of different path locations.
  43.      *
  44.      * @type {Object.<string, string>}
  45.      * @access protected
  46.      * @ignore
  47.      */
  48.     this._locations = {};
  50.     this._addAppLocation();
  51.     this.addLocation('home', home || this.path);
  52.   }
  53.   /**
  54.    * Adds a new location.
  55.    *
  56.    * @param {string} name          The reference name.
  57.    * @param {string} locationPath  The path of the location. It must be inside the path
  58.    *                               from the app is being executed.
  59.    */
  60.   addLocation(name, locationPath) {
  61.     let location = locationPath;
  62.     /**
  63.      * If it doesn't starts with the root location, then prefix it with it. The project should
  64.      * never attempt to access a location outside its directory.
  65.      */
  66.     if (location !== this.path && !location.startsWith(this.path)) {
  67.       location = path.join(this.path, location);
  68.     }
  69.     // Fix it so all the locations will end with a separator.
  70.     if (!location.endsWith(path.sep)) {
  71.       location = `${location}${path.sep}`;
  72.     }
  73.     // Add it to the dictionary.
  74.     this.locations[name] = location;
  75.   }
  76.   /**
  77.    * Gets a location path by its name.
  78.    *
  79.    * @param {string} name  The location name.
  80.    * @returns {string}
  81.    * @throws {Error} If there location hasn't been added.
  82.    */
  83.   getLocation(name) {
  84.     const location = this.locations[name];
  85.     if (!location) {
  86.       throw new Error(`There's no location with the following name: ${name}`);
  87.     }
  89.     return location;
  90.   }
  91.   /**
  92.    * Alias to `joinFrom` that uses the `home` location by default.
  93.    *
  94.    * @param {...string} paths  The rest of the path components to join.
  95.    * @returns {string}
  96.    */
  97.   join(...paths) {
  98.     return this.joinFrom('home', ...paths);
  99.   }
  100.   /**
  101.    * Builds a path using a location path as base.
  102.    *
  103.    * @param {string}    location  The location name.
  104.    * @param {...string} paths     The rest of the path components to join.
  105.    * @returns {string}
  106.    */
  107.   joinFrom(location, ...paths) {
  108.     const locationPath = this.getLocation(location);
  109.     return path.join(locationPath, ...paths);
  110.   }
  111.   /**
  112.    * The path to the directory where the app executable is located.
  113.    *
  114.    * @type {string}
  115.    */
  116.   get app() {
  117.     return this.getLocation('app');
  118.   }
  119.   /**
  120.    * The project root path.
  121.    *
  122.    * @type {string}
  123.    */
  124.   get home() {
  125.     return this.getLocation('home');
  126.   }
  127.   /**
  128.    * A dictionary of different path locations.
  129.    *
  130.    * @type {Object.<string, string>}
  131.    * @access protected
  132.    * @ignore
  133.    */
  134.   get locations() {
  135.     return this._locations;
  136.   }
  137.   /**
  138.    * The root path from where the app is being executed.
  139.    *
  140.    * @type {string}
  141.    * @access protected
  142.    * @ignore
  143.    */
  144.   get path() {
  145.     return this._path;
  146.   }
  147.   /**
  148.    * Finds and register the location for the app executable directory.
  149.    *
  150.    * @access protected
  151.    * @ignore
  152.    */
  153.   _addAppLocation() {
  154.     let current = module;
  155.     while (current.parent && current.parent.filename !== current.filename) {
  156.       current = current.parent;
  157.     }
  159.     this.addLocation('app', path.dirname(current.filename));
  160.   }
  161. }
  163. /**
  164.  * The service provider to register an instance of {@link PathUtils} on the container.
  165.  *
  166.  * @type {ProviderCreator<PathUtilsProviderOptions>}
  167.  * @tutorial pathUtils
  168.  */
  169. const pathUtils = providerCreator((options = {}) => (app) => {
  170.   app.set(options.serviceName || 'pathUtils', () => new PathUtils(options.home));
  171. });
  173. module.exports.PathUtils = PathUtils;
  174. module.exports.pathUtils = pathUtils;