tessl/npm-mlly

Missing ECMAScript module utils for Node.js

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Syntax Detection

Name: tessl/npm-mlly
Author: tessl

Utilities for detecting ECMAScript module syntax, CommonJS syntax, and validating whether imports are safe for dynamic import() calls in Node.js. Uses heuristic-based pattern matching for fast analysis.

Capabilities

Has ESM Syntax

Determines if a given code string contains ECMAScript module syntax.

/**
 * Determines if a given code string contains ECMAScript module syntax
 * @param code - The source code to analyse
 * @param opts - Options for syntax detection
 * @returns `true` if the code contains ESM syntax, otherwise `false`
 */
function hasESMSyntax(code: string, opts?: DetectSyntaxOptions): boolean;

Usage Examples:

import { hasESMSyntax } from "mlly";

console.log(hasESMSyntax("export default foo = 123")); // true
console.log(hasESMSyntax("import { bar } from 'baz'")); // true
console.log(hasESMSyntax("const x = require('y')")); // false

Has CJS Syntax

Determines if a given string of code contains CommonJS syntax.

/**
 * Determines if a given string of code contains CommonJS syntax
 * @param code - The source code to analyse
 * @param opts - Options for syntax detection
 * @returns `true` if the code contains CommonJS syntax, `false` otherwise
 */
function hasCJSSyntax(code: string, opts?: DetectSyntaxOptions): boolean;

Usage Examples:

import { hasCJSSyntax } from "mlly";

console.log(hasCJSSyntax("module.exports = {}")); // true
console.log(hasCJSSyntax("exports.foo = 'bar'")); // true
console.log(hasCJSSyntax("const x = require('y')")); // true
console.log(hasCJSSyntax("export default foo")); // false

Detect Syntax

Analyses the supplied code to determine if it contains ECMAScript module syntax, CommonJS syntax, or both.

/**
 * Analyses the supplied code to determine if it contains ECMAScript module syntax, CommonJS syntax, or both
 * @param code - The source code to analyse
 * @param opts - Options for syntax detection
 * @returns An object indicating the presence of ESM syntax (`hasESM`), CJS syntax (`hasCJS`) and whether both syntaxes are present (`isMixed`)
 */
function detectSyntax(code: string, opts?: DetectSyntaxOptions): {
  hasESM: boolean;
  hasCJS: boolean;
  isMixed: boolean;
};

Usage Example:

import { detectSyntax } from "mlly";

// Mixed syntax (common in legacy packages)
const result = detectSyntax('export default require("lodash")');
console.log(result); // { hasESM: true, hasCJS: true, isMixed: true }

// Pure ESM
const esmResult = detectSyntax('export const foo = "bar"');
console.log(esmResult); // { hasESM: true, hasCJS: false, isMixed: false }

Is Valid Node Import

Validates whether a given identifier represents a valid node import, based on its protocol, file extension, and optionally its contents.

/**
 * Validates whether a given identifier represents a valid node import, based on its protocol, file extension, and optionally its contents
 * @param id - The identifier or URL of the import to validate
 * @param options - Options for resolving and validating the import
 * @returns A promise that resolves to `true` if the import is valid, otherwise `false`
 */
function isValidNodeImport(id: string, options?: ValidNodeImportOptions): Promise<boolean>;

Usage Examples:

import { isValidNodeImport } from "mlly";

// Check if safe to use dynamic import()
const isValid = await isValidNodeImport("some-package");
if (isValid) {
  const module = await import("some-package");
} else {
  // Need to use CommonJS require or bundler transform
  console.log("This import requires special handling");
}

// Built-in modules are always valid
console.log(await isValidNodeImport("fs")); // true
console.log(await isValidNodeImport("node:path")); // true

// Data URLs are valid
console.log(await isValidNodeImport("data:text/javascript,export default 42")); // true

Algorithm:

The isValidNodeImport function uses the following validation steps:

Protocol Check - If is data: return true (✅ valid) - If is not node:, file: or data:, return false (❌ invalid)
Resolve Path - Use Node.js Resolution algorithm to resolve full path
Extension Check - If is .mjs, .cjs, .node or .wasm, return true (✅ valid) - If is not .js, return false (❌ invalid) - If matches known mixed syntax patterns (.esm.js, .es.js, etc) return false (❌ invalid)
Package.json Check - Read closest package.json file - If type: 'module' field is set, return true (✅ valid)
Source Analysis - Read source code of resolved path - Try to detect CommonJS syntax usage - If yes, return true (✅ valid) - Try to detect ESM syntax usage - If yes, return false (❌ invalid)

Types

interface DetectSyntaxOptions {
  /** Indicates whether comments should be stripped from the code before syntax checking */
  stripComments?: boolean;
}

interface ValidNodeImportOptions extends ResolveOptions {
  /** The contents of the import, which may be analyzed to see if it contains CJS or ESM syntax as a last step in checking whether it is a valid import */
  code?: string;
  /** Protocols that are allowed as valid node imports */
  allowedProtocols?: Array<string>;
  /** Whether to strip comments from the code before checking for ESM syntax */
  stripComments?: boolean;
}