procxy 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -17,7 +17,7 @@ Run class instances in isolated child processes while interacting with them as i
 ## ✨ Features
 
 - **🎯 Type-Safe** - Full TypeScript support with IntelliSense autocomplete
-- **🪄 Automagic Module Resolution** - Zero-config import path detection from your source code
+- **🪄 Automatic Module Resolution** - Zero-config import path detection from your source code
 - **⚡ Fast** - <10ms overhead per method call
 - **🔄 Events & Callbacks** - Transparent EventEmitter forwarding and bidirectional callback support
 - **🏠 Properties** - Read-only properties on parent, full read/write on child
@@ -66,6 +66,7 @@ const calc2 = await procxy(Calculator, './calculator.js');
 ### Using Disposables (Recommended)
 
 ```typescript
+import { procxy } from 'procxy';
 import { Calculator } from './calculator.js';
 
 // Automatic cleanup with await using
@@ -77,22 +78,22 @@ const result = await calc.add(5, 3);
 ### Constructor Arguments
 
 ```typescript
+import { procxy } from 'procxy';
 import { Worker } from './worker.js';
 
-class Worker {
-  constructor(public name: string, public threads: number) {}
-
-  async process(data: string[]): Promise<string[]> {
-    // Heavy processing in isolated process
-    return data.map(s => s.toUpperCase());
-  }
-}
+// Worker class (in worker.ts):
+// class Worker {
+//   constructor(public name: string, public threads: number) {}
+//
+//   async process(data: string[]): Promise<string[]> {
+//     return data.map(s => s.toUpperCase());
+//   }
+// }
 
 // Pass constructor arguments after options
 const worker = await procxy(
   Worker,
-  './worker.js',  // Can be omitted if Worker is imported
-  undefined,      // options (or omit)
+  undefined,      // options (or omit entirely)
   'MyWorker',     // name argument
   4               // threads argument
 );
@@ -103,9 +104,9 @@ const result = await worker.process(['hello', 'world']);
 await worker.$terminate();
 ```
 
-## 🪄 Automagic Module Resolution
+## 🪄 Automatic Module Resolution
 
-One of procxy's most convenient features is **automatic module path detection**. You don't need to manually specify where your class is located—procxy figures it out by parsing your import statements at runtime.
+One of procxy's most convenient features is **automatic module path detection**. You don't need to manually specify where your class is located - procxy will figure it out by parsing your import statements at runtime.
 
 ### How It Works
 
@@ -186,8 +187,10 @@ Creates a process-based proxy for a class instance.
 
 **Parameters:**
 
-- `Class: Constructor<T>` - The class constructor to instantiate
-- `modulePath?: string` - **Optional** path to the module containing the class (auto-detected if omitted)
+- `Class: Constructor<T>` - The class constructor to instantiate (must be a named class)
+- `modulePath?: string` - **Optional** - Path to the module containing the class
+  - **Omit this parameter** when using static imports (automatic resolution)
+  - **Provide explicitly** for dynamic imports or complex re-exports
 - `options?: ProcxyOptions` - Optional configuration
 - `...constructorArgs` - Arguments for the class constructor
 
@@ -195,64 +198,68 @@ Creates a process-based proxy for a class instance.
 
 **Module Path Auto-Detection:**
 
-procxy can automatically detect the module path by parsing your source file's import statements:
-
-```typescript
-import { Worker } from './worker.js';  // procxy detects this!
+When `modulePath` is omitted, procxy automatically detects the module path by:
+1. Inspecting the call stack to find where procxy was called
+2. Reading and parsing the source file for import/require statements
+3. Matching the class name to find the corresponding import path
 
-// No modulePath needed
-const worker = await procxy(Worker);
-```
-
-The module path is auto-detected from:
-- ESM named imports: `import { Class } from './path'`
-- ESM default imports: `import Class from './path'`
-- CommonJS imports: `const { Class } = require('./path')`
-- Class definitions in the same file
-
-**When to provide explicit modulePath:**
-- Dynamic imports: `const { Worker } = await import('./worker')`
-- Ambiguous import scenarios
-- When importing from multiple locations
-
-**Example:**
-
-```typescript
-const worker = await procxy(Worker, './worker.js', {
-  timeout: 60000,  // 60s per method call
-  retries: 3,      // Retry 3 times on failure
-  env: { NODE_ENV: 'production' },
-  cwd: '/tmp'
-});
-```
+This works with ESM imports, CommonJS requires, and classes defined in the same file. See [Automatic Module Resolution](#-automatic-module-resolution) for details.
 
 ### `Procxy<T>` Type
 
 The proxy type that wraps your class instance:
 
 - **Methods**: All methods become `async` and return `Promise<ReturnType>`
-- **Properties**: Public properties available as read-only on the parent proxy (updated from child)
-- **Callbacks**: Function parameters are automatically proxied across process boundaries
-- **Filtering**: Only JSON-serializable methods and properties are included
+- **Properties**: Public properties are read-only on the parent (synchronized from child after method calls)
+- **Callbacks**: Function parameters are automatically proxied bidirectionally across processes
+- **Events**: EventEmitter events flow from child to parent transparently
 - **Lifecycle Methods**:
-  - `$terminate(): Promise<void>` - Terminate the child process
-  - `$process: ChildProcess` - Access the underlying process
-- **Disposable**: Supports `using` and `await using` for automatic cleanup
+  - `$terminate(): Promise<void>` - Gracefully terminate the child process
+  - `$process: ChildProcess` - Access the underlying Node.js child process
+- **Disposable Protocol**: Supports `using` and `await using` for automatic cleanup
+- **Type Safety**: Full TypeScript IntelliSense and autocomplete support
 
 ### `ProcxyOptions`
 
-Configuration options:
+Configuration options for customizing child process behavior:
 
 ```typescript
 interface ProcxyOptions {
-  timeout?: number;      // Timeout per method call (default: 30000ms)
-  retries?: number;      // Retry attempts (default: 3)
-  env?: Record<string, string>;  // Custom environment variables
-  cwd?: string;          // Working directory for child process
-  args?: Jsonifiable[];  // Command line arguments
+  modulePath?: string;               // Path to module (optional if using static imports)
+  timeout?: number;                  // Timeout per method call in ms (default: 30000)
+  retries?: number;                  // Number of retry attempts on failure (default: 3)
+  env?: Record<string, string>;      // Custom environment variables for child process
+  cwd?: string;                      // Working directory for child process
+  args?: Jsonifiable[];              // Additional command line arguments
+  serialization?: 'json' | 'advanced'; // Serialization mode (default: 'json')
+  supportHandles?: boolean;          // Enable handle passing for sockets (advanced mode only)
 }
 ```
 
+**Examples:**
+
+```typescript
+import { procxy } from 'procxy';
+import { HeavyWorker } from './heavy-worker.js';
+import { APIClient } from './api-client.js';
+import { FileProcessor } from './file-processor.js';
+import { BinaryProcessor } from './binary-processor.js';
+
+// Long-running operations
+await procxy(HeavyWorker, { timeout: 300000 });  // 5 minutes
+
+// Custom environment
+await procxy(APIClient, {
+  env: { API_KEY: process.env.API_KEY }
+});
+
+// Isolated working directory
+await procxy(FileProcessor, { cwd: '/tmp/workspace' });
+
+// Advanced serialization for binary data
+await procxy(BinaryProcessor, { serialization: 'advanced' });
+```
+
 ## 🎯 Use Cases
 
 ### CPU-Intensive Tasks
@@ -260,13 +267,10 @@ interface ProcxyOptions {
 Offload heavy computations without blocking the event loop:
 
 ```typescript
-class ImageProcessor {
-  async resize(image: Buffer, width: number): Promise<Buffer> {
-    // Heavy image processing
-  }
-}
+import { procxy } from 'procxy';
+import { ImageProcessor } from './image-processor.js';
 
-await using processor = await procxy(ImageProcessor, './image-processor.js');
+await using processor = await procxy(ImageProcessor);
 const resized = await processor.resize(imageData, 800);
 ```
 
@@ -275,13 +279,10 @@ const resized = await processor.resize(imageData, 800);
 Run untrusted code in isolated processes:
 
 ```typescript
-class SandboxedRunner {
-  async execute(code: string): Promise<any> {
-    // Execute in isolated environment
-  }
-}
+import { procxy } from 'procxy';
+import { SandboxedRunner } from './sandbox.js';
 
-const sandbox = await procxy(SandboxedRunner, './sandbox.js', {
+const sandbox = await procxy(SandboxedRunner, {
   timeout: 5000,  // Kill after 5s
   env: { NODE_ENV: 'sandbox' }
 });
@@ -292,16 +293,18 @@ const sandbox = await procxy(SandboxedRunner, './sandbox.js', {
 Classes extending EventEmitter work transparently:
 
 ```typescript
+import { procxy } from 'procxy';
 import { EventEmitter } from 'events';
+import { DataStream } from './stream.js';
 
-class DataStream extends EventEmitter {
-  async start(): Promise<void> {
-    // Stream data and emit events
-    this.emit('data', { chunk: 'example' });
-  }
-}
+// DataStream class (in stream.ts):
+// class DataStream extends EventEmitter {
+//   async start(): Promise<void> {
+//     this.emit('data', { chunk: 'example' });
+//   }
+// }
 
-const stream = await procxy(DataStream, './stream.js');
+const stream = await procxy(DataStream);
 
 stream.on('data', (chunk) => {
   console.log('Received:', chunk);
@@ -315,21 +318,25 @@ await stream.start();
 Pass callbacks as function parameters and they'll be transparently proxied across the process boundary:
 
 ```typescript
-class AsyncWorker {
-  async processWithCallback(
-    data: string[],
-    onProgress: (current: number, total: number) => void
-  ): Promise<string[]> {
-    const result = [];
-    for (let i = 0; i < data.length; i++) {
-      result.push(data[i].toUpperCase());
-      onProgress(i + 1, data.length);  // Invokes callback in parent
-    }
-    return result;
-  }
-}
-
-const worker = await procxy(AsyncWorker, './async-worker.js');
+import { procxy } from 'procxy';
+import { AsyncWorker } from './async-worker.js';
+
+// AsyncWorker class (in async-worker.ts):
+// class AsyncWorker {
+//   async processWithCallback(
+//     data: string[],
+//     onProgress: (current: number, total: number) => void
+//   ): Promise<string[]> {
+//     const result = [];
+//     for (let i = 0; i < data.length; i++) {
+//       result.push(data[i].toUpperCase());
+//       onProgress(i + 1, data.length);  // Invokes callback in parent
+//     }
+//     return result;
+//   }
+// }
+
+const worker = await procxy(AsyncWorker);
 
 const result = await worker.processWithCallback(
   ['hello', 'world'],
@@ -352,47 +359,72 @@ const result = await worker.processWithCallback(
 
 ### Properties Support
 
-Public properties are accessible as read-only on the parent and can be read/modified on the child:
+Public properties are accessible with different capabilities on parent vs. child:
+
+**Parent Process (Read-Only):**
+- **Get**: Synchronous property reads from local property store
+- Properties are automatically synced after each method call
+
+**Child Process (Read/Write):**
+- **Get**: Direct property access (no IPC overhead)
+- **Set**: Modifies property and syncs to parent
 
 ```typescript
+// counter.ts
+import { procxy } from 'procxy';
+
 class Counter {
   public count: number = 0;
   public name: string = '';
 
   increment(): void {
+    // Child can SET properties directly
     this.count++;
   }
 
   setName(newName: string): void {
+    // Child can SET properties
     this.name = newName;
   }
 
   getCount(): number {
+    // Child can GET properties directly (no IPC)
     return this.count;
   }
+
+  getName(): string {
+    // Child can GET properties directly
+    return this.name;
+  }
 }
 
-const counter = await procxy(Counter, './counter.js');
+// main.ts
+import { procxy } from 'procxy';
+import { Counter } from './counter.js';
+
+const counter = await procxy(Counter);
 
-// Properties are read-only on parent
-console.log(counter.count);  // 0 - synchronous read from property store
-console.log(counter.name);   // '' - synchronous read
+// Parent can GET properties (synchronous read from property store)
+console.log(counter.count);  // 0 - no IPC, reads from local store
+console.log(counter.name);   // '' - synchronous
 
-// Modify via child methods
+// Modify via child methods (parent CANNOT set directly)
 await counter.increment();
 await counter.setName('MyCounter');
 
-// Parent reads updated values
-console.log(counter.count);  // 1 - automatically synced from child
-console.log(counter.name);   // 'MyCounter' - automatically synced
+// Parent GETs updated values (automatically synced from child)
+console.log(counter.count);  // 1 - synced after increment()
+console.log(counter.name);   // 'MyCounter' - synced after setName()
+
+// Parent cannot SET properties (read-only)
+// counter.count = 5;  // ❌ Throws error: properties are read-only on parent
 ```
 
 **Property Synchronization:**
 - Parent maintains a property store synchronized from the child
-- Child can read properties directly (no IPC needed)
-- Child can set properties (sends update to parent)
-- Property updates are automatically synced after method calls
-- Parent can only read properties (attempting to set throws an error)
+- Child can **get** and **set** properties directly (no IPC needed for reads)
+- Property updates are automatically synced to parent after method calls
+- Parent can only **get** properties (attempting to set throws an error)
 - No race conditions: only the child can modify properties
 
 ## 🛡️ Error Handling
@@ -430,7 +462,10 @@ try {
 ### Timeouts and Retries
 
 ```typescript
-const worker = await procxy(Worker, './worker.js', {
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
+const worker = await procxy(Worker, {
   timeout: 60000,  // 60 seconds per call
   retries: 5       // Retry 5 times before failing
 });
@@ -439,7 +474,10 @@ const worker = await procxy(Worker, './worker.js', {
 ### Custom Environment
 
 ```typescript
-const worker = await procxy(Worker, './worker.js', {
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
+const worker = await procxy(Worker, {
   env: {
     NODE_ENV: 'production',
     API_KEY: process.env.API_KEY,
@@ -451,17 +489,253 @@ const worker = await procxy(Worker, './worker.js', {
 ### Working Directory
 
 ```typescript
-const worker = await procxy(Worker, './worker.js', {
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
+const worker = await procxy(Worker, {
   cwd: '/tmp/workspace'
 });
 ```
 
+## 🎨 Advanced Serialization (V8 Structured Clone)
+
+By default, procxy uses JSON serialization for IPC messages. However, you can enable **advanced serialization mode** to support additional data types using V8's structured clone algorithm.
+
+### Supported Types in Advanced Mode
+
+When using `serialization: 'advanced'`, you can pass these additional types:
+
+- **Binary Data**: `Buffer`, `ArrayBuffer`, `TypedArray` (Uint8Array, Int32Array, Float32Array, etc.)
+- **Collections**: `Map`, `Set` with full fidelity (not converted to arrays)
+- **Large Numbers**: `BigInt` values
+- **Built-in Objects**: `Date`, `RegExp`, `Error` instances with all properties preserved
+
+### Usage
+
+```typescript
+import { procxy } from 'procxy';
+import { ImageProcessor } from './image-processor.js';
+
+// Enable advanced serialization
+await using processor = await procxy(ImageProcessor, {
+  serialization: 'advanced'  // 👈 Enable V8 structured clone
+});
+
+// Now you can pass Buffer, TypedArray, Map, Set, BigInt, etc.
+const imageBuffer = Buffer.from(imageData);
+const processed = await processor.processImage(imageBuffer);
+
+// Use Map for caching
+const cache = new Map([
+  ['key1', Buffer.from('data1')],
+  ['key2', Buffer.from('data2')]
+]);
+await processor.bulkCache(cache);
+
+// Use BigInt for large numbers
+const timestamp = BigInt(Date.now()) * BigInt(1000000);
+await processor.recordTimestamp(timestamp);
+
+// TypedArray for binary protocols
+const binaryData = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
+await processor.sendBinary(binaryData);
+
+// Set for unique collections
+const uniqueIds = new Set([1, 2, 3, 4, 5]);
+await processor.processIds(uniqueIds);
+```
+
+### Example: Binary Data Processing
+
+```typescript
+// binary-processor.ts
+export class BinaryProcessor {
+  // Process Buffer data
+  processBuffer(data: Buffer): Buffer {
+    const result = Buffer.alloc(data.length);
+    for (let i = 0; i < data.length; i++) {
+      result[i] = data[i] ^ 0xFF;  // XOR transformation
+    }
+    return result;
+  }
+
+  // Work with TypedArray
+  sumFloat32Array(arr: Float32Array): number {
+    return arr.reduce((sum, val) => sum + val, 0);
+  }
+
+  // Use Map for caching
+  private cache = new Map<string, Buffer>();
+
+  cacheData(key: string, data: Buffer): void {
+    this.cache.set(key, data);
+  }
+
+  getAllCache(): Map<string, Buffer> {
+    return new Map(this.cache);  // Returns actual Map, not array
+  }
+
+  // Process BigInt
+  multiplyBigInt(a: bigint, b: bigint): bigint {
+    return a * b;
+  }
+}
+
+// main.ts
+import { procxy } from 'procxy';
+import { BinaryProcessor } from './binary-processor.js';
+
+await using processor = await procxy(BinaryProcessor, {
+  serialization: 'advanced'
+});
+
+// Process binary data
+const input = Buffer.from([0x00, 0x11, 0x22, 0x33]);
+const output = await processor.processBuffer(input);
+// Buffer: [0xFF, 0xEE, 0xDD, 0xCC]
+
+// Work with TypedArray
+const floats = new Float32Array([1.1, 2.2, 3.3]);
+const sum = await processor.sumFloat32Array(floats);  // 6.6
+
+// Use Map
+await processor.cacheData('key1', Buffer.from('data1'));
+const cache = await processor.getAllCache();  // Returns Map, not array
+console.log(cache instanceof Map);  // true
+console.log(cache.get('key1')?.toString());  // 'data1'
+
+// BigInt support
+const result = await processor.multiplyBigInt(BigInt(123), BigInt(456));
+console.log(result);  // 56088n
+```
+
+### JSON vs Advanced Mode Comparison
+
+| Feature | JSON Mode (default) | Advanced Mode |
+|---------|-------------------|---------------|
+| Primitives (string, number, boolean) | ✅ | ✅ |
+| Objects & Arrays | ✅ | ✅ |
+| null & undefined | ✅ | ✅ |
+| Buffer | ❌ | ✅ |
+| TypedArray | ❌ | ✅ |
+| Map | ❌ | ✅ |
+| Set | ❌ | ✅ |
+| BigInt | ❌ | ✅ |
+| Date | ⚠️ (as string) | ✅ (as Date) |
+| RegExp | ⚠️ (as object) | ✅ (as RegExp) |
+| Error | ⚠️ (partial) | ✅ (full props) |
+| Handle Passing (sockets) | ❌ | ✅ (with `supportHandles`) |
+| Performance | Faster for simple objects | Slightly slower |
+
+### Handle Passing
+
+Advanced serialization mode also enables **handle passing** - the ability to transfer network sockets and server handles between processes.
+
+```typescript
+import { procxy } from 'procxy';
+import * as net from 'net';
+
+class SocketHandler {
+  registerConnection(id: string, socket: net.Socket): void {
+    socket.on('data', (data) => {
+      console.log(`Received on ${id}:`, data.toString());
+    });
+  }
+}
+
+// Enable handle passing
+const handler = await procxy(SocketHandler, {
+  serialization: 'advanced',
+  supportHandles: true  // Required for handle passing
+} as const);  // Use 'as const' for type inference
+
+// Create a server and accept connections
+const server = net.createServer((socket) => {
+  // Transfer the socket to the child process
+  handler.$sendHandle(socket, 'connection-1');  // TypeScript knows $sendHandle is available!
+
+  // Register it in the child
+  handler.registerConnection('connection-1', socket);
+});
+
+server.listen(8080);
+```
+
+**Platform Support:**
+- ✅ **Unix/Linux/macOS**: Full support for socket transfer
+- ⚠️ **Windows**: Limited support - some handle types may not work correctly
+
+See [examples/advanced-serialization/socket-transfer.ts](./examples/advanced-serialization/socket-transfer.ts) for a complete example.
+
+### When to Use Advanced Mode
+
+**Use JSON mode (default) when:**
+- Working with simple data structures (objects, arrays, primitives)
+- Maximum performance is critical for simple types
+- No need for binary data or collections
+
+**Use Advanced mode when:**
+- Processing binary data (images, files, network protocols)
+- Working with Map/Set collections
+- Handling large numbers with BigInt
+- Need to preserve Date/RegExp/Error objects with full fidelity
+- Transferring TypedArray data between processes
+- **Passing network sockets between processes** (requires `supportHandles: true`)
+
+### More Examples
+
+See [examples/advanced-serialization/](./examples/advanced-serialization/) for comprehensive examples:
+- [Buffer Processing](./examples/advanced-serialization/buffer-processing.ts) - Image data processing with Buffers
+- [BigInt Calculations](./examples/advanced-serialization/bigint-calculations.ts) - Large number operations
+- [Collection Processing](./examples/advanced-serialization/collection-processing.ts) - Map and Set usage
+- [Socket Transfer](./examples/advanced-serialization/socket-transfer.ts) - Handle passing with network sockets
+- [Error Preservation](./examples/advanced-serialization/error-preservation.ts) - Full Error object preservation
+- [Migration Guide](./examples/advanced-serialization/migration-guide.md) - Step-by-step migration from JSON mode
+
+### Performance Considerations
+
+Advanced serialization has a small overhead compared to JSON for simple objects, but enables much broader type support. See [Performance Benchmarks](#-performance) for detailed comparisons.
+
+```typescript
+// Benchmark results (see benchmark/serialization-comparison.ts)
+// Simple object (100 calls):
+//   JSON mode: 0.12ms average
+//   Advanced mode: 0.15ms average (~25% slower)
+//
+// Buffer data (100 calls):
+//   JSON mode: Not supported
+//   Advanced mode: 0.18ms average
+//
+// Map with 100 entries (100 calls):
+//   JSON mode: Not supported
+//   Advanced mode: 0.25ms average
+```
+
 ## 🔍 Limitations
 
-1. **JSON Serialization** - Method arguments and return values must be JSON-serializable (functions are proxied as callbacks)
-2. **Properties Read-Only on Parent** - Parent can only read properties, modifications must be done via child methods
-3. **One-Way Events** - EventEmitter events only flow from child to parent (emit only works in child)
-4. **Callback Context** - Callbacks are invoked with serialized arguments (e.g., no `this` binding)
+Understanding these constraints will help you use procxy effectively:
+
+1. **Serialization Requirements**
+   - **JSON mode (default)**: Method arguments and return values must be JSON-serializable
+   - **Advanced mode**: Supports V8 structured clone types (Buffer, Map, Set, BigInt, etc.)
+   - Functions are automatically proxied as callbacks (no manual serialization needed)
+   - **JSON mode**: Circular references and symbols are not supported
+   - **Advanced mode**: Circular references are supported via V8 structured clone; symbols are not supported
+
+2. **Parent Properties Are Read-Only**
+   - Parent process can only **read** properties (via local synchronized store)
+   - Child process can **read and write** properties
+   - Modifications must be done via child methods, not direct assignment on parent
+
+3. **One-Way Event Flow**
+   - EventEmitter events flow from child → parent only
+   - Parent can listen to events, but cannot emit events to the child
+   - The child process owns the EventEmitter instance
+
+4. **Callback Context Limitations**
+   - Callbacks are invoked with serialized arguments
+   - No `this` binding preservation across process boundaries
+   - Callback functions cannot access closure variables from the other process
 
 ## 🧪 Testing
 
@@ -487,27 +761,96 @@ pnpm test tests/integration/basic-invocation.test.ts
 
 ### Module Resolution Errors
 
-If you get `ModuleResolutionError`, ensure the `modulePath` argument points to the correct file:
+If you get `ModuleResolutionError`, ensure you have a static import or provide an explicit `modulePath`:
 
 ```typescript
-// ✅ Correct - explicit path
+// ✅ Best - automatic resolution with static import
+import { Worker } from './worker.js';
+await procxy(Worker);
+
+// ✅ Also works - explicit path
 await procxy(Worker, './worker.js');
-await procxy(Worker, '/absolute/path/to/worker.js');
 
-// ❌ Wrong - missing module path
-await procxy(Worker);  // Error!
+// ❌ Won't work - dynamic import without explicit path
+const { Worker } = await import('./worker.js');
+await procxy(Worker);  // Error: Cannot resolve module path!
+
+// ✅ Fix - provide explicit path with dynamic import
+const { Worker } = await import('./worker.js');
+await procxy(Worker, './worker.js');
 ```
 
 ### Serialization Errors
 
-Ensure all arguments and return values are JSON-serializable:
+Ensure all arguments and return values are serializable for your chosen mode:
 
+**JSON Mode:**
 ```typescript
 // ✅ OK
 await proxy.process({ name: 'test', count: 42 });
 
 // ❌ Not OK - contains function
 await proxy.process({ name: 'test', fn: () => {} });
+
+// ❌ Not OK - Buffer requires advanced mode
+await proxy.processImage(Buffer.from('data'));
+```
+
+**Advanced Mode:**
+```typescript
+// Enable advanced mode
+const proxy = await procxy<Worker, 'advanced'>(
+  Worker,
+  { serialization: 'advanced' }
+);
+
+// ✅ Now OK - Buffer is supported
+await proxy.processImage(Buffer.from('data'));
+
+// ✅ OK - Map and Set supported
+await proxy.processMap(new Map([['key', 'value']]));
+await proxy.processSet(new Set([1, 2, 3]));
+
+// ✅ OK - BigInt supported
+await proxy.calculate(123456789n);
+```
+
+### Type Inference Issues
+
+When using advanced serialization, ensure the type parameter matches the option:
+
+```typescript
+// ✅ Correct - type parameter matches serialization option
+const worker = await procxy<Worker, 'advanced'>(
+  Worker,
+  { serialization: 'advanced' }
+);
+
+// ❌ Wrong - type mismatch will cause TypeScript errors
+const worker = await procxy<Worker, 'json'>(
+  Worker,
+  { serialization: 'advanced' }  // TypeScript error!
+);
+```
+
+### Handle Passing Issues
+
+If handle passing doesn't work:
+
+```typescript
+// ✅ Ensure both advanced mode AND supportHandles are enabled with 'as const'
+const handler = await procxy(Handler, {
+  serialization: 'advanced',
+  supportHandles: true  // Required!
+} as const);  // 'as const' ensures TypeScript infers supportHandles: true
+
+// ✅ Now $sendHandle is available in TypeScript autocomplete
+await handler.$sendHandle(socket);
+
+// ✅ Check platform - Windows has limited support
+if (process.platform === 'win32') {
+  console.warn('Handle passing may not work on Windows');
+}
 ```
 
 ### Timeout Issues
@@ -515,7 +858,10 @@ await proxy.process({ name: 'test', fn: () => {} });
 Increase timeout for long-running methods:
 
 ```typescript
-const worker = await procxy(Worker, './worker.js', {
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
+const worker = await procxy(Worker, {
   timeout: 300000  // 5 minutes
 });
 ```
@@ -589,17 +935,10 @@ class Task extends EventEmitter<Events> {
 ### Data Processing Pipeline
 
 ```typescript
-class ImageProcessor {
-  async resize(data: Buffer, width: number): Promise<Buffer> {
-    // Heavy computation in isolated process
-  }
-
-  async compress(data: Buffer, quality: number): Promise<Buffer> {
-    // Another heavy operation
-  }
-}
+import { procxy } from 'procxy';
+import { ImageProcessor } from './image-processor.js';
 
-await using processor = await procxy(ImageProcessor, './image-processor.js');
+await using processor = await procxy(ImageProcessor);
 
 let image = await processor.resize(imageData, 800);
 image = await processor.compress(image, 85);
@@ -610,12 +949,15 @@ console.log('Processed:', image.length, 'bytes');
 ### Worker Pool Pattern
 
 ```typescript
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
 class WorkerPool {
   private workers: any[] = [];
 
   async initialize(poolSize: number): Promise<void> {
     for (let i = 0; i < poolSize; i++) {
-      this.workers.push(await procxy(Worker, './worker.js'));
+      this.workers.push(await procxy(Worker));
     }
   }
 
@@ -633,13 +975,10 @@ class WorkerPool {
 ### Real-Time Data Streaming
 
 ```typescript
-class DataStream extends EventEmitter {
-  async startStream(filter: (x: any) => boolean): Promise<void> {
-    // Start streaming data
-  }
-}
+import { procxy } from 'procxy';
+import { DataStream } from './stream.js';
 
-const stream = await procxy(DataStream, './stream.js');
+const stream = await procxy(DataStream);
 
 let dataCount = 0;
 stream.on('data', (chunk) => {
@@ -657,27 +996,10 @@ await stream.startStream(x => x.value > 100);
 ### Batch Processing with Progress
 
 ```typescript
-class BatchProcessor {
-  async processBatch(
-    items: string[],
-    onProgress: (processed: number, total: number, item: string) => void
-  ): Promise<string[]> {
-    const results = [];
-    for (let i = 0; i < items.length; i++) {
-      const result = await this.heavyProcess(items[i]);
-      results.push(result);
-      onProgress(i + 1, items.length, items[i]);
-    }
-    return results;
-  }
-
-  private async heavyProcess(item: string): Promise<string> {
-    // CPU-intensive work
-    return item.toUpperCase();
-  }
-}
+import { procxy } from 'procxy';
+import { BatchProcessor } from './batch-processor.js';
 
-const processor = await procxy(BatchProcessor, './batch-processor.js');
+const processor = await procxy(BatchProcessor);
 
 const results = await processor.processBatch(
   ['item1', 'item2', 'item3'],
@@ -694,26 +1016,12 @@ console.log('Results:', results);
 Use static factory methods or wrapper functions for cleaner initialization:
 
 ```typescript
-class Database {
-  private connectionString: string = '';
-  private connected: boolean = false;
-
-  async connect(url: string): Promise<void> {
-    this.connectionString = url;
-    this.connected = true;
-    // Simulate connection setup
-    await new Promise(r => setTimeout(r, 100));
-  }
-
-  async query(sql: string): Promise<any[]> {
-    if (!this.connected) throw new Error('Not connected');
-    return [{ result: 'example' }];
-  }
-}
+import { procxy } from 'procxy';
+import { Database } from './database.js';
 
 // Factory function for cleaner API
 async function createDatabase(url: string) {
-  const db = await procxy(Database, './database.js');
+  const db = await procxy(Database);
   await db.connect(url);
   return db;
 }
@@ -729,27 +1037,32 @@ await db.$terminate();
 Build complex instances with fluent API and async setup:
 
 ```typescript
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
 class WorkerBuilder {
   private name: string = 'Worker';
   private threads: number = 1;
   private timeout: number = 30000;
 
-  setName(name: string): void {
+  setName(name: string): this {
     this.name = name;
+    return this;
   }
 
-  setThreads(threads: number): void {
+  setThreads(threads: number): this {
     this.threads = threads;
+    return this;
   }
 
-  setTimeout(ms: number): void {
+  setTimeout(ms: number): this {
     this.timeout = ms;
+    return this;
   }
 
   async build(): Promise<Procxy<Worker>> {
     const worker = await procxy(
       Worker,
-      './worker.js',
       { timeout: this.timeout },
       this.name,
       this.threads
@@ -776,6 +1089,9 @@ await worker.processImage(imageData);
 Manage a pool of async-initialized resources:
 
 ```typescript
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
 class AsyncResourcePool<T> {
   private available: Procxy<T>[] = [];
   private inUse = new Set<Procxy<T>>();
@@ -813,7 +1129,7 @@ class AsyncResourcePool<T> {
 
 // Usage
 async function createWorker() {
-  return await procxy(Worker, './worker.js');
+  return await procxy(Worker);
 }
 
 const pool = new AsyncResourcePool<Worker>();
@@ -836,13 +1152,16 @@ await pool.shutdown();
 Create and cache instances on first use:
 
 ```typescript
+import { procxy } from 'procxy';
+import { Worker } from './worker.js';
+
 class LazyWorkerSingleton {
   private static instance: Procxy<Worker> | null = null;
 
   static async getInstance(): Promise<Procxy<Worker>> {
     if (!this.instance) {
       console.log('Initializing worker...');
-      this.instance = await procxy(Worker, './worker.js');
+      this.instance = await procxy(Worker);
 
       // Set up cleanup on process exit
       process.on('exit', async () => {
@@ -876,6 +1195,10 @@ await LazyWorkerSingleton.reset();
 Resolve dependencies asynchronously before using proxies:
 
 ```typescript
+import { procxy } from 'procxy';
+import { Database } from './database.js';
+import { Cache } from './cache.js';
+
 class ServiceContainer {
   private services = new Map<string, any>();
 
@@ -902,13 +1225,8 @@ class ServiceContainer {
 // Setup
 const container = new ServiceContainer();
 
-await container.register('database', () =>
-  procxy(Database, './database.js')
-);
-
-await container.register('cache', () =>
-  procxy(Cache, './cache.js')
-);
+await container.register('database', () => procxy(Database));
+await container.register('cache', () => procxy(Cache));
 
 // Usage with injected dependencies
 const db = container.get<Database>('database');