or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rechoir

Prepare a node environment to require files with different extensions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rechoir@0.8.x

To install, run

npx @tessl/cli install tessl/npm-rechoir@0.8.0

index.mddocs/

Rechoir

Rechoir prepares a Node.js environment to require files with different extensions by dynamically loading and registering appropriate transpilers and module loaders. It works in conjunction with interpret-like configuration objects to register any filetype that has a module loader available in the npm ecosystem.

Package Information

  • Package Name: rechoir
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install rechoir

Core Imports

const rechoir = require('rechoir');

ESM:

import rechoir from 'rechoir';

Basic Usage

const config = require('interpret').extensions;
const rechoir = require('rechoir');

// Prepare environment to require CoffeeScript files
rechoir.prepare(config, './app.coffee');

// Now you can require CoffeeScript files directly
const app = require('./app.coffee');

// Prepare environment with custom configuration
rechoir.prepare({
  '.ts': ['ts-node/register'],
  '.coffee': ['coffeescript/register']
}, './script.ts');

const script = require('./script.ts');

Capabilities

Environment Preparation

Prepares the Node.js environment to require files with different extensions by dynamically loading and registering appropriate module loaders.

/**
 * Prepare Node environment to require files with different extensions
 * @param {Object} extensions - interpret-like configuration object mapping extensions to loaders
 * @param {string} filepath - file path whose type should be registered for loading  
 * @param {string} [cwd] - directory to start searching for required modules (defaults to directory of filepath)
 * @param {boolean} [nothrow] - if true, method returns error instead of throwing
 * @returns {boolean|Array|undefined|Error} - true if already registered, Array of attempts if successful, undefined if nothrow=true and extension not found, Error if nothrow=true and all loaders failed
 */
function prepare(extensions, filepath, cwd, nothrow);

Parameters:

  • extensions (Object): Configuration object mapping file extensions to module loaders. Each key is a file extension (e.g., '.coffee', '.ts') and each value is either a string (module name) or array of strings/objects with module loader configurations.
  • filepath (string): Path to the file whose extension should be prepared for requiring. Used to determine which extension configuration to apply.
  • cwd (string, optional): Directory to start searching for the required module loaders. If not provided, defaults to the directory containing filepath.
  • nothrow (boolean, optional): If true, the function returns errors instead of throwing them. If false or omitted, errors are thrown.

Return Values:

  • true: If a loader is already registered for the file's extension
  • Array: Array of loader attempt objects if registration was successful, each containing moduleName, module, and error properties
  • undefined: If nothrow is true and no configuration found for the file extension
  • Error: If nothrow is true and all configured loaders failed to load

Error Handling:

When all configured loaders fail, an Error is thrown (or returned if nothrow=true) with a failures property containing an array of attempt objects. Each attempt object includes:

  • moduleName (string): Name of the module that was attempted
  • module (any|null): The loaded module if successful, null if failed
  • error (Error|null): Error object if loading failed, null if successful

Usage Examples:

const rechoir = require('rechoir');

// Basic usage with interpret configuration
const config = require('interpret').extensions;
rechoir.prepare(config, './script.coffee');

// Custom configuration
rechoir.prepare({
  '.ts': ['ts-node/register'],
  '.coffee': ['coffeescript/register', 'coffee-script/register']
}, './app.ts');

// Using nothrow option
const result = rechoir.prepare(config, './unknown.xyz', null, true);
if (result instanceof Error) {
  console.log('Failed to prepare:', result.message);
  console.log('Failed attempts:', result.failures);
} else if (result === undefined) {  
  console.log('No loader configuration found');
} else if (result === true) {
  console.log('Extension already registered');
} else {
  console.log('Successfully registered:', result);
}

// Specifying custom cwd
rechoir.prepare({
  '.ts': 'ts-node/register'
}, 'src/app.ts', '/project/root');

Types

// Extension configuration can be:
// - String: module name
// - Object: { module: string, register?: function }  
// - Array: array of strings or objects to try in order

/**
 * Extension configuration object
 * @typedef {Object.<string, (string|object|Array<string|object>)>} ExtensionConfig
 */

/**
 * Loader attempt result object
 * @typedef {Object} LoaderAttempt
 * @property {string} moduleName - Name of the module that was attempted
 * @property {any|null} module - The loaded module if successful, null if failed
 * @property {Error|null} error - Error object if loading failed, null if successful
 */

/**
 * Error with loader failures
 * @typedef {Error} LoaderError
 * @property {LoaderAttempt[]} failures - Array of loader attempt objects
 */