execifmain v0.0.2

execIfMain

execIfMain helps you gradually create more modular and reusable Node.js scripts that can be used as both libraries and executables.

Basic usage

If foo.js contains

const { execIfMain } = require('execifmain');

export function foo() { … }
function main() { … }

execIfMain(main, module);

then execIfMain will only run main() if foo.js is the main script called with node foo.js.

If foo.js is only being loaded because some other code does require("foo") to use it as a library or run some tests against it, main() won’t run.

In ESM code, pass import.meta instead of module:

import { execIfMain } from 'execifmain';

export function foo() { … }
function main() { … }

execIfMain(main, import.meta);

Why

Doing this is common in many programming languages. Python has its if __name__ == '__main__': idiom, Ruby has if __FILE__ == $PROGRAM_NAME, Java lets you put a static main() method in any class, and there are even idioms for shell scripts.

While Node.js does have if (require.main === module), the extra code needed to handle promises, return codes, and ES modules all mean that your code can be much simpler while handling more edge cases if you delegate that work to this package which encapsulates the required logic.

For an example of where if (require.main === module) breaks down, in Node <= 14 the following code prints a warning but exits with a return code of zero.

async function main() {
  throw new Error("oops");
}
if (require.main === module) {
  main();
}

While you could add a .catch(…) handler that calls console.error() and process.exit(), calling execIfMain is shorter and will do a better job.

Features

Supports async main functions

You can use execIfMain with async functions. execIfMain will set up a catch() handler to exit with error code 1 on promise rejection.

const { execIfMain } = require('execifmain');

async function main() { … }

execIfMain(main, module);

Return values becomes exit codes

If execIfMain runs a function that returns a number, that number becomes the exit code of the process. This also works for async code that returns a promise that resolves to a number.

That means that this code:

import { execIfMain } from 'execifmain';

function main() {
    ⋮
    if (!options.valid()) {
        options.print_help();
        return 64; // EX_USAGE from sysexits(3)
    }
    ⋮
}

execIfMain(main, import.meta);

will return error code 64 to the shell on invalid options.

Run alternate code if not main

execIfMain returns false if it does not run the provided function, allowing you to take extra actions when in library mode.

import { execIfMain } from 'execifmain';

function main() { … }

execIfMain(main, import.meta) || doLibraryModeSpecificInitialization();

Things not yet supported

execIfMain is known not to detect that it should exec main when parcel v1 is used to create bundled script files, as in parcel build --target=node main.js.

Other bundlers have not been tested and are expected not to work yet.

Internal development notes

Some things to know if coding on the execIfMain project itself:

• enable debug output with DEBUG=execifmain

• The integration test uses the compiled file, so make sure you are running yarn babel:watch.