🏁 isMain & runIfMain

hbh-nodes provides utility functions to detect if a module is the main entry point and to execute code only when the module is run directly, not when imported. This is especially useful for libraries that can be both imported and executed as scripts.

---

Import

CommonJS

          
            1const { isMain, runIfMain } = require("hbh-nodes");
          
        

ES Modules

          
            1import { isMain, runIfMain } from "hbh-nodes";
          
        

---

isMain(importMetaUrl, cjsModule, mainModule)

Determines if the current module is being executed as the main script.

Parameters

Returns

• true → If the module is the main entry point.
• false → If the module is imported or parameters are invalid.

Behavior

1. CommonJS Detection:

             
               1if (typeof mainModule !== "undefined" && cjsModule === mainModule) {2    return require.main === mainModule;3}
             
           

   Checks if the current module is the main script.

2. ES Module Detection:

             
               1const filename = fileURLToPath(importMetaUrl);2return filename === process.argv[1];
             
           

   Converts import.meta.url to a path and compares with the Node.js entry file.

3. Safe Fallback: Returns false for unknown or invalid inputs.

Example

          
            1const { isMain } = require("./mainCheck");3if (isMain(null, module, require.main)) {4  console.log("This module is running directly!");5}
          
        

Edge Cases

• Works for both ES modules and CommonJS.
• Returns false when the module is imported.
• Handles invalid inputs gracefully.
• In ESM, require is unavailable, so CommonJS checks are skipped.

---

runIfMain(importMetaUrl, cjsModule, mainModule, fn)

Executes a function only if the current module is the main script.

Parameters

Returns

• Returns the result of fn() if executed.
• Returns undefined if the module is imported.

Behavior

• Calls isMain() internally to determine if the module is the main entry point.
• Executes the provided function fn() only when the module is running directly.
• Safe for mixed ESM + CommonJS environments.

Example

CommonJS

          
            1const { runIfMain } = require("./mainCheck");3function main() {4  console.log("Running directly as a script!");5}7runIfMain(null, module, require.main, main);
          
        

ES Module

          
            1import { runIfMain } from "./mainCheck.mjs";3runIfMain(import.meta.url, null, null, () => {4  console.log("Running directly in ESM!");5});
          
        

Edge Cases

• Does nothing if the module is imported.
• Safely handles invalid inputs.
• Useful for CLI scripts or libraries with optional initialization.

---

Best Practices

1. Always pass the correct module references in CommonJS (module and require.main).
2. For ESM, pass import.meta.url and null for the CommonJS parameters.
3. Wrap all startup code or CLI logic inside runIfMain to avoid side effects on import.
4. Use isMain if you need conditional checks without running a function.

---

Advanced / Deep Dive Usage

Example: CLI Script with Arguments

          
            1runIfMain(import.meta.url, module, require.main, () => {2  const args = process.argv.slice(2);3  console.log("CLI arguments:", args);4  // Start your CLI logic here5});
          
        

---