CommonJS Context

Utilities for creating CommonJS-compatible context within ECMAScript modules, providing __dirname, __filename, and require functionality that is missing in ESM environments.

Capabilities

Create CommonJS

Creates a CommonJS context for a given module URL, enabling require, __filename and __dirname support similar to Node.js.

/**
 * Creates a CommonJS context for a given module URL, enabling `require`, `__filename` and `__dirname` support similar to Node.js
 * @param url - The URL of the module file to create a context for
 * @returns A context object containing `__filename`, `__dirname` and a custom `require` function
 */
function createCommonJS(url: string): CommonjsContext;

Usage Examples:

import { createCommonJS } from "mlly";

// Create CommonJS context for current module
const { __dirname, __filename, require } = createCommonJS(import.meta.url);

console.log(__filename); // "/path/to/current/module.mjs"
console.log(__dirname);  // "/path/to/current"

// Use require to load CommonJS modules
const fs = require("fs");
const lodash = require("lodash");

// Use require.resolve
const modulePath = require.resolve("some-package");

Interop Default

Return the default export of a module at the top-level, alongside any other named exports. Handles interoperability between ESM and CommonJS modules.

/**
 * Return the default export of a module at the top-level, alongside any other named exports
 * @param sourceModule - The module object to process
 * @param opts - Options for controlling interop behavior
 * @returns The processed module with default export interop applied
 */
function interopDefault(
  sourceModule: any,
  opts?: { preferNamespace?: boolean }
): any;

Usage Examples:

import { interopDefault } from "mlly";

// Assuming a module with shape: { default: { foo: 'bar' }, baz: 'qux' }
const myModule = await import("my-module");

// Returns { foo: 'bar', baz: 'qux' }
const processed = interopDefault(myModule);

// With preferNamespace option
const namespace = interopDefault(myModule, { preferNamespace: true });

Options:

• preferNamespace: In case that default value exists but is not extendable (when is string for example), return input as-is (default is false, meaning default's value is preferred even if cannot be extended)

Types

interface CommonjsContext {
  /** The absolute path to the current module file */
  __filename: string;
  /** The directory name of the current module */
  __dirname: string;
  /** A function to require modules as in CommonJS */
  require: NodeRequire;
}

Key Features

Lazy Require Implementation

The require function created by createCommonJS is implemented lazily - it only creates the actual Node.js require function when first called. This improves performance by avoiding unnecessary initialization.

Full Require Compatibility

The generated require function supports all standard Node.js require features:

• Module Loading: require("module-name") loads CommonJS modules
• Resolution: require.resolve("module-name") resolves module paths
• JSON Loading: Automatically parses JSON files
• Built-in Modules: Supports Node.js built-in modules

Path Resolution

The __filename and __dirname variables are correctly resolved from the provided URL:

• __filename contains the absolute file path of the current module
• __dirname contains the directory path containing the current module
• Both paths use the platform-appropriate path separators

ESM to CommonJS Bridge

This functionality enables ESM modules to seamlessly interact with CommonJS ecosystems:

• Load CommonJS dependencies that don't support ESM
• Use tools and libraries that expect CommonJS context
• Maintain compatibility with existing CommonJS-based codebases
• Access file system paths in a familiar way