0
# @node-rs/helper
1

2
@node-rs/helper is a TypeScript utility library that provides a robust solution for loading native Node.js bindings (.node files) in node-rs projects. It dynamically resolves and loads platform-specific native modules based on the current system architecture and platform, with comprehensive error reporting and support for multiple loading strategies.
3

4
## Package Information
5

6
- **Package Name**: @node-rs/helper
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @node-rs/helper`
10

11
## Core Imports
12

13
```typescript
14
import { loadBinding } from "@node-rs/helper";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { loadBinding } = require("@node-rs/helper");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { loadBinding } from "@node-rs/helper";
27

28
// Load binding from local directory (common case)
29
const nativeModule = loadBinding(__dirname, 'mymodule', '@my-package/core');
30

31
// Simple usage with just directory and filename
32
const simpleModule = loadBinding(__dirname, 'index');
33

34
// Use the loaded native module
35
nativeModule.someNativeFunction();
36
```
37

38
## Architecture
39

40
@node-rs/helper implements a two-stage binding resolution strategy:
41

42
1. **Package-based Loading**: Attempts to resolve bindings from node_modules using platform-specific package naming
43
2. **Local File Loading**: Falls back to loading from local files using platform-specific file naming
44
3. **Platform Detection**: Uses @napi-rs/triples to determine the current platform's architecture triple
45
4. **Error Aggregation**: Collects and reports detailed information about all failed loading attempts
46

47
The library supports multiple platform architectures including Windows (x64, ia32, arm64), macOS (x64, arm64), Linux (x64, arm64, armv7), FreeBSD, Android, and other platforms.
48

49
## Capabilities
50

51
### Native Binding Loading
52

53
Dynamically loads platform-specific native Node.js bindings with automatic platform detection and fallback strategies.
54

55
```typescript { .api }
56
/**
57
 * Load native binding file from dirname with platform-specific resolution
58
 * @param dirname - Directory path where the .node binding file is located
59
 * @param filename - Optional filename (defaults to 'index'), should match napi.name in package.json
60
 * @param packageName - Optional package name (e.g., '@swc/core'), should match name in package.json
61
 * @returns The loaded native module
62
 * @throws Error with detailed message if no compatible binding can be loaded
63
 */
64
function loadBinding(dirname: string, filename?: string = 'index', packageName?: string): any;
65
```
66

67
**Parameters:**
68
- `dirname: string` - The directory where the native binding file is located
69
- `filename?: string = 'index'` - The base filename for the native binding (without platform suffix and .node extension)
70
- `packageName?: string` - The package name used for node_modules resolution (e.g., '@swc/core')
71

72
**Returns:**
73
- `any` - The loaded native module object with its exported functions and properties
74

75
**Loading Strategy:**
76
1. **Node Modules Resolution**: If `packageName` is provided, attempts to load `${packageName}-${platformArchABI}` from node_modules
77
2. **Local File Resolution**: Attempts to load `${filename}.${platformArchABI}.node` from the specified directory
78
3. **Platform Detection**: Uses @napi-rs/triples to determine platform-specific architecture identifiers
79

80
**Error Handling:**
81
Throws a detailed Error if loading fails, including:
82
- List of attempted file paths and package names
83
- Specific error messages from failed require attempts
84
- List of available packages in node_modules when packageName is provided
85
- Platform architecture information for debugging
86

87
**Platform Support:**
88
- **Windows**: win32-x64, win32-ia32, win32-arm64
89
- **macOS**: darwin-x64, darwin-arm64
90
- **Linux**: linux-x64, linux-arm64, linux-arm, linux-armv7, etc.
91
- **FreeBSD**: freebsd-x64
92
- **Android**: android-arm64, android-arm
93
- Additional platforms supported by @napi-rs/triples
94

95
**Usage Examples:**
96

97
```typescript
98
import { loadBinding } from "@node-rs/helper";
99

100
// Load with package name for node_modules resolution
101
try {
102
  const swcModule = loadBinding(__dirname, 'swc', '@swc/core');
103
  console.log('SWC native module loaded successfully');
104
} catch (error) {
105
  console.error('Failed to load SWC:', error.message);
106
}
107

108
// Load from local file only
109
try {
110
  const localModule = loadBinding(__dirname, 'my-native', undefined);
111
  const result = localModule.processData('input');
112
} catch (error) {
113
  console.error('Failed to load local binding:', error.message);
114
}
115

116
// Typical usage in a package's main entry point
117
module.exports = loadBinding(__dirname, 'package-name', '@my-org/package-name');
118
```
119

120
## Error Scenarios
121

122
The `loadBinding` function provides comprehensive error reporting for common failure scenarios:
123

124
**Missing Platform-Specific Packages:**
125
```
126
Can not load bindings
127
Installed packages: [package-name-win32-x64, package-name-linux-x64]
128
```
129

130
**File Exists But Load Failed:**
131
```
132
Can not load bindings, file: /path/to/binding.linux-x64.node existed but error occurred while require it: Error message
133
```
134

135
**No Compatible Bindings Found:**
136
```
137
Can not load bindings
138
```
139

140