CLAUDE.md

1# JavaScript Builtins in Bun
2 
3Write JS builtins for Bun's Node.js compatibility and APIs. Run `bun bd` after changes.
4 
5## Directory Structure
6 
7- `builtins/` - Individual functions (`*CodeGenerator(vm)` in C++)
8- `node/` - Node.js modules (`node:fs`, `node:path`)
9- `bun/` - Bun modules (`bun:ffi`, `bun:sqlite`)
10- `thirdparty/` - NPM replacements (`ws`, `node-fetch`)
11- `internal/` - Internal modules
12 
13## Writing Modules
14 
15Modules are NOT ES modules:
16 
17```typescript
18const EventEmitter = require("node:events"); // String literals only
19const { validateFunction } = require("internal/validators");
20 
21export default {
22  myFunction() {
23    if (!$isCallable(callback)) {
24      throw $ERR_INVALID_ARG_TYPE("cb", "function", callback);
25    }
26  },
27};
28```
29 
30## Writing Builtin Functions
31 
32```typescript
33// Fifo.ts
34export function createFIFO<T>(): Dequeue<T> {
35  const Dequeue = require("internal/fifo");
36  return new Dequeue();
37}
38```
39 
40C++ access:
41 
42```cpp
43object->putDirectBuiltinFunction(vm, globalObject, identifier,
44  fifoCreateFIFOCodeGenerator(vm), 0);
45```
46 
47## $ Globals and Special Syntax
48 
49**CRITICAL**: Use `.$call` and `.$apply`, never `.call` or `.apply`:
50 
51```typescript
52// ✗ WRONG - User can tamper
53callback.call(undefined, arg1);
54fn.apply(undefined, args);
55 
56// ✓ CORRECT - Tamper-proof
57callback.$call(undefined, arg1);
58fn.$apply(undefined, args);
59 
60// $ prefix for private APIs
61const arr = $Array.from(...);           // Private globals
62map.$set(key, value);                   // Private methods
63const newArr = $newArrayWithSize(5);    // JSC intrinsics
64$debug("Module loaded:", name);         // Debug (stripped in release)
65$assert(condition, "message");          // Assertions (stripped in release)
66```
67 
68**Platform detection**: `process.platform` and `process.arch` are inlined and dead-code eliminated
69 
70## Validation and Errors
71 
72```typescript
73const { validateFunction } = require("internal/validators");
74 
75function myAPI(callback) {
76  if (!$isCallable(callback)) {
77    throw $ERR_INVALID_ARG_TYPE("callback", "function", callback);
78  }
79}
80```
81 
82## Build Process
83 
84`Source TS/JS → Preprocessor → Bundler → C++ Headers`
85 
861. Assign numeric IDs (A-Z sorted)
872. Replace `$` with `__intrinsic__`, `require("x")` with `$requireId(n)`
883. Bundle, convert `export default` to `return`
894. Replace `__intrinsic__` with `@`, inline into C++
90 
91ModuleLoader.rs loads modules by numeric ID via `InternalModuleRegistry.cpp`.
92 
93## Key Rules
94 
95- Use `.$call`/`.$apply` not `.call`/`.apply`
96- String literal `require()` only
97- Export via `export default {}`
98- Use JSC intrinsics for performance
99- Run `bun bd` after changes
100