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

Module Evaluation

Name: tessl/npm-mlly
Author: tessl

Safe module evaluation using data: URLs with automatic import resolution and stack trace preservation. Includes transformation utilities for JSON modules and import.meta.url rewriting.

Capabilities

Load Module

Loads a module by resolving its identifier to a URL, fetching the module's code and evaluating it.

/**
 * Loads a module by resolving its identifier to a URL, fetching the module's code and evaluating it
 * @param id - The identifier of the module to load
 * @param options - Optional parameters to resolve and load the module
 * @returns A promise to resolve to the evaluated module
 */
function loadModule(id: string, options?: EvaluateOptions): Promise<any>;

Usage Examples:

import { loadModule } from "mlly";

// Load a module by path
const utils = await loadModule("./utils.mjs", { url: import.meta.url });

// Load with custom resolution options
const config = await loadModule("./config.json", {
  url: import.meta.url,
  extensions: [".json", ".mjs"]
});

Eval Module

Evaluates JavaScript code as a module using a dynamic import from a data URL.

/**
 * Evaluates JavaScript code as a module using a dynamic import from a data URL
 * @param code - The code of the module to evaluate
 * @param options - Includes the original URL of the module for better error mapping
 * @returns A promise that resolves to the evaluated module or throws an error if the evaluation fails
 */
function evalModule(code: string, options?: EvaluateOptions): Promise<any>;

Usage Examples:

import { evalModule } from "mlly";

// Evaluate simple module code
const result = await evalModule(`
  export const greeting = "Hello World!";
  export default function() { return 42; }
`);

console.log(result.greeting); // "Hello World!"
console.log(result.default()); // 42

// Evaluate with import resolution
const moduleWithImports = await evalModule(`
  import { join } from 'path';
  export const fullPath = join('/home', 'user', 'file.txt');
`, { url: import.meta.url });

Transform Module

Transform module code to handle specific scenarios, such as converting JSON to a module or rewriting import.meta.url.

/**
 * Transform module code to handle specific scenarios, such as converting JSON to a module or rewriting import.meta.url
 * @param code - The code of the module to transform
 * @param options - Options to control how the code is transformed
 * @returns A promise that resolves to the transformed code
 */
function transformModule(code: string, options?: EvaluateOptions): Promise<string>;

Usage Examples:

import { transformModule } from "mlly";

// Transform JSON to module
const jsonModule = await transformModule('{"name": "test"}', {
  url: "file:///project/data.json"
});
console.log(jsonModule); // "export default {"name": "test"}"

// Transform import.meta.url references
const transformed = await transformModule(
  `console.log(import.meta.url)`,
  { url: "file:///project/module.mjs" }
);
console.log(transformed); // `console.log('file:///project/module.mjs')`

Resolve Imports

Resolves all import URLs found within the provided code to their absolute URLs, based on the given options.

/**
 * Resolves all import URLs found within the provided code to their absolute URLs, based on the given options
 * @param code - The code containing the import directives to resolve
 * @param options - Options to use for resolving imports
 * @returns A promise that resolves to the code, replacing import URLs with resolved URLs
 */
function resolveImports(code: string, options?: EvaluateOptions): Promise<string>;

Usage Example:

import { resolveImports } from "mlly";

const code = `
import foo from './utils.mjs';
import { bar } from '../config.json';
export const baz = await import('./dynamic.mjs');
`;

const resolved = await resolveImports(code, { url: import.meta.url });
// All relative imports are resolved to absolute file:// URLs

Types

interface EvaluateOptions extends ResolveOptions {
  /** The URL of the module, which can be specified to override the URL resolved from the module identifier */
  url?: string;
}

Key Features

Automatic Import Resolution

The module evaluation system automatically resolves relative imports to absolute URLs before evaluation:

Relative imports like ./module.mjs are resolved based on the url option
JSON files are automatically transformed to export default modules
Import resolution respects the same options as the resolve functions

Stack Trace Preservation

When modules are evaluated using data URLs, stack traces are rewritten to show the original module URL instead of the data URL, making debugging easier.

JSON Module Support

JSON files are automatically detected by extension and transformed into ES modules that export the JSON data as the default export:

// Original JSON file content: {"name": "test", "version": "1.0.0"}
// Transformed to: export default {"name": "test", "version": "1.0.0"}

Import.meta.url Rewriting

The import.meta.url references in the code are automatically replaced with the actual module URL provided in options, ensuring proper context for module evaluation.