@require-transpile/core

For on-the-fly transpiling similar to @babel/register, but without hooking into your global require, and with a generic transpiling method.

Word of warning:

This module seems to work for me, but as of writing this, I do not have a thorough understanding of nodejs internals. So, here be dragons.

License, donations

GPL-3.0. If you want to support my work, you can:

Example

This shows the generic API, if you want to use this with babel, look at @require-transpile/babel.

see example.js in the repo:

"use strict";
const fs = require("fs");
const requireTranspile = require("@require-transpile/core");

function transpiler(_path) {
	// normally some kind of readFileSync:
	// let input = fs.readFileSync(path, 'utf8');
	let input = `module.exports = () => {console.log("my input")}`;
	let modified = input.replace("input", "transpiled output");
	return modified;
}

let cache = new Map();

console.log("simple require and transpile:");
const example = requireTranspile("./example", transpiler, {
	cache
});
example(); // my transpiled output

const withDeps = requireTranspile("./examples/a", fs.readFileSync, {
	cache,
	withDependencies: true,
});
console.log("circular dependencies, with list of dependencies:", withDeps);

function dateTranspiler(_path) {
	return `module.exports = () => {console.log("transpiled at ${new Date().getTime()}")}`;
}

console.log("Method that is loaded, executed, invalidated and loaded again:");
let newCache = new Map();

const first = requireTranspile("./examples/a", dateTranspiler, {cache: newCache});
first();

let resolved = requireTranspile.resolve("./examples/a");
requireTranspile.invalidate(newCache, resolved);

const second = requireTranspile("./examples/a", dateTranspiler, {cache: newCache});
second(); // will log a later timestamp

API

requireTranspile(filepath, transpiler, [options])

Returns the module found at filepath, transpiling it, and it's dependencies, with transpiler.

• filepath: the path to the module you want to load
• transpiler: function(path) that should return either the transpiled code, or {code, map} if a sourcemap is to be used in errors
• options: optional object with:
  • includeNodeModules: default: false, apply transpiler to modules loaded from node_modules as well.
  • extensions: default: [], additional extensions to search for, as require.resolve defaults to just .js.
  • cache: default: {}, object used for module caching, can be reused across babelTranspile calls as long as files don't change.
  • entryFile: default: module.parent.filename, used as basepath to resolve filepath from.
  • withDependencies: default: false, if true returns {mod, dependencies} where dependencies is an array of all transpiled files.
  • overrideScope: default: {}, object with variables to inject/override in module scopes
  • overrideHook: function(path) {} to short-circuit require calls, if it returns a non-null value it is returned instead of normal require logic

requireTranspile.resolve(path, [options])

Resolve similarly to require.resolve, but with custome extensions

• path: the path to resolve
• options: optional object with:
  • exts: non-default extensions to look for, like ".jsx", or an array of strings for more options
  • paths: paths to look in, defaults as relative from __filename where you are calling this

requireTranspile.invalidate(cache, fullpath)

Invalidate a cache entry, for livereloading dependencies with surgical precision.
It will delete fullpath from the cache, and mark all it's parents as invalid, which will re-execute their code upon require returns Set of invalidated entries

• cache: cache Map that contains an entry for the key fullpath
• fullpath: entry to invalidate

Changelog

v0.4.2 (August 25, 2022)

• add option to inject/override variables into module scope

v0.4.1 (July 1, 2020)

• return Set of invalidated paths

v0.4.0 (🏳️‍🌈 June 29, 2020)

• better mimic standard Module objects, keeping track of dependency structures
• expose resolve function with custom extensions
• support partial cache invalidation
• cache is now a Map

v0.3.5 (🏳️‍🌈 June 16, 2020)

• add overrideHook option

v0.3.4 (🏳️‍🌈 June 7, 2020)

• properly cache dependency trees

v0.3.2 (🏳️‍🌈 June 2, 2020)

• dependency loaded from cache will still be added to dependency array

v0.3.0 (May 31, 2020)

• make dependency array returnal optional, return just module by default
• allow passing in entryFile, to use for initial base path

v0.2.2 (May 30, 2020)

• don't treat path starting with / as node_module

v0.2.1 (May 30, 2020)

• allow passing cache object

v0.2.0 (May 30, 2020)

• exclude node_modules by default
• define module object, bring exports in scope