functions/partials/loadPeer.mjsjavascript
import { createRequire } from 'node:module'
import path from 'node:path'
import { pathToFileURL } from 'node:url'
// Several dependencies ship ESM-only (standard, gulp-ts-compile, typedoc), but this package also publishes a CommonJS
// build (dist/*.js) whose babel transform would turn even a dynamic import() into a require() that cannot load an ES
// module. Hiding the import() inside a Function constructor keeps it a genuine dynamic import that works from either
// build, because babel cannot see (and so cannot rewrite) an import expression which only exists as a runtime string.
// eslint-disable-next-line no-new-func -- deliberate, see above
const dynamicImport = new Function('specifier', 'return import(specifier)')
/**
* Import an ES module (or any module) with a real dynamic import(), whichever build (ESM or CommonJS) this runs from.
* @memberOf module:partials
* @param {string} specifier - The package name, or the URL of a file.
* @returns {Promise<Object>} The module namespace.
*/
export const importModule = specifier => dynamicImport(specifier)
const isMissing = (error, name) => error.code === 'MODULE_NOT_FOUND' && error.message.includes(`'${name}'`)
const notInstalled = (name, { task, installHint }) => new Error(
`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`
)
/**
* Load an optional peer dependency (one which is only needed once a task runs, so projects which never use that task
* do not have to install it) with require(), from the project being built rather than from this package. When it is
* missing the error explains how to install it.
* @memberOf module:partials
* @param {string} name - The package name.
* @param {Object} options
* @param {string} options.task - The task which needs the package, for the error message.
* @param {string} options.installHint - How to install it, for the error message.
* @param {string} [options.esmOnlyMessage] - The error message when the package turns out to be ESM-only (it cannot be require()d).
* @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
* @returns {*} Whatever the package exports.
* @throws {Error} With install instructions when the package is not installed.
*/
export const requirePeer = (name, { task, installHint, esmOnlyMessage, projectPath = process.cwd() }) => {
try {
return createRequire(path.join(projectPath, 'package.json'))(name)
} catch (error) {
if (isMissing(error, name)) {
throw notInstalled(name, { task, installHint })
}
if (error.code === 'ERR_REQUIRE_ESM' && esmOnlyMessage) {
throw new Error(esmOnlyMessage)
}
throw error
}
}
/**
* Import an optional peer dependency which ships ESM-only, from the project being built. See {@link requirePeer}.
* @memberOf module:partials
* @param {string} name - The package name.
* @param {Object} options
* @param {string} options.task - The task which needs the package, for the error message.
* @param {string} options.installHint - How to install it, for the error message.
* @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
* @returns {Promise<Object>} The module namespace.
* @throws {Error} With install instructions when the package is not installed.
*/
export const importPeer = async (name, { task, installHint, projectPath = process.cwd() }) => {
let resolved
try {
resolved = createRequire(path.join(projectPath, 'package.json')).resolve(name)
} catch (error) {
if (isMissing(error, name)) {
throw notInstalled(name, { task, installHint })
}
throw error
}
return importModule(pathToFileURL(resolved).href)
}