65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
thread-stream is a library for streaming data to a Node.js Worker Thread. It uses SharedArrayBuffer and Atomics for efficient inter-thread communication, enabling high-performance data streaming to worker threads.
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
npm test # Run linting (standard), type checking, and all tests
|
|
npm run build # Type check only (tsc --noEmit)
|
|
npm run test:ci # CI-specific test run
|
|
|
|
# Run a single test file
|
|
node --test test/<filename>.test.js
|
|
node --test test/<filename>.test.ts # For TypeScript tests
|
|
|
|
# Lint
|
|
npx standard
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
- **index.js**: Main `ThreadStream` class extending EventEmitter. Manages shared memory buffers, worker lifecycle, and provides stream-like write/flush/end API.
|
|
|
|
- **lib/worker.js**: Runs inside the Worker Thread. Loads the user-provided destination module, reads from shared buffer, and writes to the destination stream.
|
|
|
|
- **lib/indexes.js**: Defines shared buffer index constants (`WRITE_INDEX`, `READ_INDEX`) used for Atomics-based synchronization.
|
|
|
|
- **lib/wait.js**: Provides `wait()` and `waitDiff()` utilities for async waiting on Atomics state changes with exponential backoff.
|
|
|
|
### Shared Memory Communication
|
|
|
|
The main thread and worker communicate via two SharedArrayBuffers:
|
|
1. **stateBuf**: Int32Array for READ_INDEX and WRITE_INDEX positions
|
|
2. **dataBuf**: Buffer for actual string data (default 4MB)
|
|
|
|
Write flow: Main thread writes to dataBuf, updates WRITE_INDEX, worker reads data between READ_INDEX and WRITE_INDEX, updates READ_INDEX when consumed.
|
|
|
|
### Worker Module Interface
|
|
|
|
User-provided worker modules must export an async function that receives `workerData` and returns a writable stream:
|
|
|
|
```js
|
|
async function run(opts) {
|
|
const stream = fs.createWriteStream(opts.dest)
|
|
await once(stream, 'open')
|
|
return stream
|
|
}
|
|
module.exports = run
|
|
```
|
|
|
|
### Sync vs Async Modes
|
|
|
|
- `sync: true`: Blocking writes using flushSync, waits for worker to consume
|
|
- `sync: false` (default): Non-blocking writes with drain events when buffer fills
|
|
|
|
## Code Style
|
|
|
|
Uses [Standard](https://standardjs.com/) for linting. Test files in `test/ts/**/*` and `test/syntax-error.mjs` are excluded from linting.
|