0
# Node API Support
1
2
Node.js API compatibility validation utilities for ensuring proper engine type selection based on platform capabilities. This module provides functions to validate Node API support and generate platform-specific library names.
3
4
## Capabilities
5
6
### Assert Node API Support
7
8
Validates whether Node API is supported on the current platform and throws an error if not supported.
9
10
```typescript { .api }
11
/**
12
* Determines whether Node API is supported on the current platform and throws if not
13
* @throws Error if Node API is not supported (specifically on 32-bit platforms)
14
*/
15
function assertNodeAPISupported(): void;
16
```
17
18
**Usage Examples:**
19
20
```typescript
21
import { assertNodeAPISupported } from "@prisma/get-platform";
22
23
try {
24
assertNodeAPISupported();
25
console.log("Node API is supported on this platform");
26
// Proceed with Node API engine type
27
} catch (error) {
28
console.error("Node API not supported:", error.message);
29
// Fall back to binary engine type
30
}
31
```
32
33
**Error Conditions:**
34
35
The function throws an error in the following cases:
36
37
- **32-bit Node.js**: When `process.arch === 'ia32'` and no custom library path is set
38
- **Custom library missing**: When `PRISMA_QUERY_ENGINE_LIBRARY` is set but the file doesn't exist
39
40
**Error Message:**
41
```
42
The default query engine type (Node-API, "library") is currently not supported for 32bit Node. Please set `engineType = "binary"` in the "generator" block of your "schema.prisma" file (or use the environment variables "PRISMA_CLIENT_ENGINE_TYPE=binary" and/or "PRISMA_CLI_QUERY_ENGINE_TYPE=binary".)
43
```
44
45
### Get Node API Library Name
46
47
Gets the Node-API library filename based on the binary target and intended usage (filesystem or URL).
48
49
```typescript { .api }
50
/**
51
* Gets Node-API Library name depending on the binary target
52
* @param binaryTarget - The target platform identifier
53
* @param type - 'fs' for filesystem usage, 'url' for S3 download URLs
54
* @returns Platform-specific library filename
55
*/
56
function getNodeAPIName(binaryTarget: BinaryTarget, type: 'url' | 'fs'): string;
57
```
58
59
**Usage Examples:**
60
61
```typescript
62
import { getNodeAPIName, getBinaryTargetForCurrentPlatform } from "@prisma/get-platform";
63
64
const target = await getBinaryTargetForCurrentPlatform();
65
66
// Get filename for filesystem usage
67
const fsName = getNodeAPIName(target, 'fs');
68
console.log(fsName);
69
// Examples:
70
// "libquery_engine-darwin-arm64.dylib.node" (macOS ARM64)
71
// "libquery_engine-debian-openssl-1.1.x.so.node" (Linux)
72
// "query_engine-windows.dll.node" (Windows)
73
74
// Get filename for download URLs
75
const urlName = getNodeAPIName(target, 'url');
76
console.log(urlName);
77
// Examples:
78
// "libquery_engine.dylib.node" (macOS)
79
// "libquery_engine.so.node" (Linux)
80
// "query_engine.dll.node" (Windows)
81
```
82
83
**Platform-Specific Naming:**
84
85
The function generates names based on platform conventions:
86
87
**Windows platforms** (`target.includes('windows')`):
88
- **Filesystem**: `query_engine-${binaryTarget}.dll.node`
89
- **URL**: `query_engine.dll.node`
90
91
**macOS platforms** (`target.includes('darwin')`):
92
- **Filesystem**: `libquery_engine-${binaryTarget}.dylib.node`
93
- **URL**: `libquery_engine.dylib.node`
94
95
**Linux and other platforms**:
96
- **Filesystem**: `libquery_engine-${binaryTarget}.so.node`
97
- **URL**: `libquery_engine.so.node`
98
99
## Environment Variables
100
101
The Node API support system recognizes these environment variables:
102
103
### PRISMA_QUERY_ENGINE_LIBRARY
104
105
Path to a custom query engine library file. When set and the file exists, Node API support validation is bypassed.
106
107
```bash
108
export PRISMA_QUERY_ENGINE_LIBRARY="/path/to/custom/libquery_engine.so.node"
109
```
110
111
**Usage in validation:**
112
113
```typescript
114
const customLibraryPath = process.env.PRISMA_QUERY_ENGINE_LIBRARY;
115
const customLibraryExists = customLibraryPath && fs.existsSync(customLibraryPath);
116
117
if (!customLibraryExists && process.arch === 'ia32') {
118
throw new Error(/* ... */);
119
}
120
```
121
122
### Engine Type Selection Variables
123
124
While not directly used by this module, these environment variables control engine type selection:
125
126
- **`PRISMA_CLIENT_ENGINE_TYPE`**: Controls client engine type ("library" or "binary")
127
- **`PRISMA_CLI_QUERY_ENGINE_TYPE`**: Controls CLI engine type ("library" or "binary")
128
129
When Node API is not supported, these should be set to "binary".
130
131
## Integration with Platform Detection
132
133
Node API support works together with platform detection:
134
135
```typescript
136
import {
137
assertNodeAPISupported,
138
getNodeAPIName,
139
getBinaryTargetForCurrentPlatform
140
} from "@prisma/get-platform";
141
142
async function setupQueryEngine() {
143
try {
144
// Check if Node API is supported
145
assertNodeAPISupported();
146
147
// Get the binary target for current platform
148
const binaryTarget = await getBinaryTargetForCurrentPlatform();
149
150
// Generate the appropriate library name
151
const libraryName = getNodeAPIName(binaryTarget, 'fs');
152
153
console.log(`Using Node API library: ${libraryName}`);
154
return { engineType: 'library', libraryName };
155
156
} catch (error) {
157
console.warn("Node API not supported, falling back to binary engine");
158
return { engineType: 'binary', libraryName: null };
159
}
160
}
161
```
162
163
## Compatibility Notes
164
165
- **32-bit Node.js**: Not supported for Node API engines due to technical limitations
166
- **Custom engines**: Can bypass validation by setting `PRISMA_QUERY_ENGINE_LIBRARY`
167
- **Platform coverage**: Node API libraries are available for all supported binary targets
168
- **Filename consistency**: URL names are simplified for S3 distribution, filesystem names include full target specification