0
# Rechoir
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: rechoir
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install rechoir`
10

11
## Core Imports
12

13
```javascript
14
const rechoir = require('rechoir');
15
```
16

17
ESM:
18

19
```javascript
20
import rechoir from 'rechoir';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const config = require('interpret').extensions;
27
const rechoir = require('rechoir');
28

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

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

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

41
const script = require('./script.ts');
42
```
43

44
## Capabilities
45

46
### Environment Preparation
47

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

50
```javascript { .api }
51
/**
52
 * Prepare Node environment to require files with different extensions
53
 * @param {Object} extensions - interpret-like configuration object mapping extensions to loaders
54
 * @param {string} filepath - file path whose type should be registered for loading  
55
 * @param {string} [cwd] - directory to start searching for required modules (defaults to directory of filepath)
56
 * @param {boolean} [nothrow] - if true, method returns error instead of throwing
57
 * @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
58
 */
59
function prepare(extensions, filepath, cwd, nothrow);
60
```
61

62
**Parameters:**
63

64
- `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.
65
- `filepath` (string): Path to the file whose extension should be prepared for requiring. Used to determine which extension configuration to apply.
66
- `cwd` (string, optional): Directory to start searching for the required module loaders. If not provided, defaults to the directory containing `filepath`.
67
- `nothrow` (boolean, optional): If `true`, the function returns errors instead of throwing them. If `false` or omitted, errors are thrown.
68

69
**Return Values:**
70

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

76
**Error Handling:**
77

78
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:
79

80
- `moduleName` (string): Name of the module that was attempted
81
- `module` (any|null): The loaded module if successful, null if failed  
82
- `error` (Error|null): Error object if loading failed, null if successful
83

84
**Usage Examples:**
85

86
```javascript
87
const rechoir = require('rechoir');
88

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

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

99
// Using nothrow option
100
const result = rechoir.prepare(config, './unknown.xyz', null, true);
101
if (result instanceof Error) {
102
  console.log('Failed to prepare:', result.message);
103
  console.log('Failed attempts:', result.failures);
104
} else if (result === undefined) {  
105
  console.log('No loader configuration found');
106
} else if (result === true) {
107
  console.log('Extension already registered');
108
} else {
109
  console.log('Successfully registered:', result);
110
}
111

112
// Specifying custom cwd
113
rechoir.prepare({
114
  '.ts': 'ts-node/register'
115
}, 'src/app.ts', '/project/root');
116
```
117

118
## Types
119

120
```javascript { .api }
121
// Extension configuration can be:
122
// - String: module name
123
// - Object: { module: string, register?: function }  
124
// - Array: array of strings or objects to try in order
125

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

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

139
/**
140
 * Error with loader failures
141
 * @typedef {Error} LoaderError
142
 * @property {LoaderAttempt[]} failures - Array of loader attempt objects
143
 */
144
```