YDR Utilities - @wider/utils_require

Introduction

To assist conversion of legacy commonJS to ES modules, this re-establishes the full set of features of nodeJS require()

May be used in an ES5+ Module or a commonJS module under nodeJS.

The tool can be used in code exactly the same as require() in nodeJS commonJS retaining same properties and methods and behaviours even when called from an ES Module.

Supports the following file types

• .js delivers a javascript commonjs module
• .json delivers a parsed JSON object
• .node delivers a node-gyp object

You may optionally use the following extensions

• to return a Promise
• to load ANY file extension directly into your handler (sync or async) - eg to load .md files directly npm into your chosen markdown handler object
• load a default substitute for a file if the requested file is missing

Documentation

Full Documentation

Install

npm install "@wider/utils_require"

Use

See also Examples

This provides a function customised to your module, that mostly appears to behave as the original nodeJS.

// if this is an ES Module under nodejs use ...
import path from "path";
import Module from "module";
import Require from "@wider/utils_require";
const require = new Require(Module, {
	path: path
});

// if this is a commonJS Module under nodejs use the following instead of the three lines above
require = require("@wider/utils_require")(module);

// Examples
const { v2, v2, v3 } = require("./jsonFilePath.JSON"); // synchronous load of a JSON object 
const myModule = require("@wider/aPackageName"); // loads the default module for the named package
const myDefaultModule = require("."); // Error because ./index/js is not a commonjs module
const myPackage = require("./package.json") // your own package.json
const mainPackage = require(path.join(require.mainFolder, "./package.json")) // the main app's package.json
const upThere = require("../..");  // might be the parent package's main index.js

Optional extensions

You can use the require method to load non javascript/JSON files that are found using the same path search that is used for conventional require processing. If you wish to do this you must enable it, otherwise attempts to access such files will fail as per the normal require response.

You may also designate an alternative file id where the default value of a file might be found if the requested one is missing.

See Optional Extensions

Optional asynchronous call

If your code is in an asynchronous function, you can ask for require to act asynchronously.

require.async(...) is a promisified version of require(...)

Warnings

• This builds off the standard require function that is only available in nodeJS commonJS modules. The version via ES .createRequire is not the same in all respects.

• There may be non standard behaviours or undocumented features of require() that we have not emulated.

• This package delivers a require object that is custom to your ES Module, do not share this object with another module - create it again in the other module if you need to.

• You will get an error if you try and load an ES Module via this tool. If you need to load ES modules, import them into your own ES Module and use this tool from there as need be.

• import and commonJS require and @wider.require all use the same cache covering your entire application for javascript and where supported for json and node files. However, revising require.cache() entries is not assured to affect ES import() under all circumstances now or in the future. We recommend that you do not access the original commonJS require.cache()

• The value of require.main is not defined in nodeJS require when the outermost module is an ES Module. We backfill the value with a guess as to what is the main module path. We recommend that the first ever call to create the @wider.Require says uses the setting { isMain : true } explicitly that it is the main application and that this is obtained as your first import of your main program. We also recommend that you set this when calling from a commonJS

  To ensure the guess is correct, we recommend that this package is the first import of your main package before all others - even if you do not use it there. If it is not convenient to do this, then use require(Module).main = Module using the Module of the main module before making any use of require()

• All files are fetched as utf-8 by default unless another format is defined via the required object (such as in an xml source file)

• Methods provided are as follows: please see nodeJS documentation.

    require(id [, defaultIdOrFunction ]) // Function - returns JSON or JS object or Error, or other objects if extensions are used
    require.cache // Object - read write
    require.extensions // Object - read write deprecated by nodeJS
    require.main // String - read only optionally write once be before calling require()
    require.resolve(id) // Function - searches for your file location
    require.resolve.paths // Object - read only object contents editable

• the following additional methods are provided

    require.async() // promisified version of require
    require.extensionHandlers() // enable require to handle additional file extensions
    require.main
    require.main.path
    require.main.filename

Comparison of objects

This section compares the features of require and import in comparison with the legacy node commonjs solution when used under nodeJS

Supplementary feature

We have enabled this package to be used under commonJS. If you wish to try out features before conversion to an ES Module you can initiate the tool as below. If you dislike reassigning require then choose an alternative name.

'use strict';
require = require(".")(module, settings);

• settings.isMain {Boolean} when true forces this module to be regarded as the main package that is running. Errors will be thrown if this property is set on modules that are in different packages If this is missing, we will guess which is the main package but since imports are asynchronous we cannot guarantee the default will always work.
• settings.extensionHandlers {Object} enable require load additional file types. Extension handlers add to a common set of extension handlers that span all instances of new Require() You can restate a given extension handler but you cannot morph

You may be interested in these ES Modules

• @wider/utils_require-json loads a JSON file and configures it to your technical environment
• @wider/utils_markup that can markup your strings and objects including formulae and built in common markups