@fest-lib/uniform 0.1.11 → 0.1.13

package/README.md

@@ -1,384 +1,46 @@
-# Fest/Uniform - Advanced Web Worker Communication Library
+# Uniform.TS
 
-**Fest/Uniform** is an experimental web worker communication library that provides seamless, inline-like function calls across worker boundaries using advanced reflection and proxy techniques.
+`@fest-lib/uniform` — cross-context channels for fest-lib. One API over dedicated workers, SharedWorker, Service Worker, MessagePort, BroadcastChannel, WebSocket, Chrome extension ports, SharedArrayBuffer/Atomics, and WebRTC data channels.
 
-## Features
+Canonical runtime: `UnifiedChannel` / `createUnifiedChannel`. Invoker (`Requestor` / `Responder`) gives request/response across those transports. Legacy `createWorkerChannel` helpers remain under `src/original` and `src/newer/next/utils`.
 
-- **Seamless API**: Call worker functions as if they were local
-- **Automatic Serialization**: Handles complex data types and transferables
-- **Optimized Protocol**: Batching, timeouts, and error recovery
-- **Type Safety**: Full TypeScript support with reflection
-- **Performance**: Efficient message passing with minimal overhead
+## Install
 
-## Quick Start
-
-### Basic Usage
-
-```typescript
-import { createWorkerChannel } from 'fest/uniform';
-
-// Create a worker channel
-const worker = await createWorkerChannel({
-    name: 'my-worker',
-    script: './my-worker.uniform.worker.ts'
-});
-
-// Call worker functions seamlessly
-const result = await worker.request('processData', { data: 'hello' });
-```
-
-### Queued Channels (Recommended)
-
-```typescript
-import { createQueuedWorkerChannel } from 'fest/uniform';
-
-// Create queued channel - operations queue until worker is ready
-const worker = new QueuedWorkerChannel({
-    name: 'my-worker',
-    script: './my-worker.uniform.worker.ts'
-}, (channel) => {
-    console.log('Worker channel ready!');
-});
-
-// Operations will queue until the channel connects
-const result = await worker.request('processData', { data: 'hello' });
-```
-
-### Optimized Protocol
-
-```typescript
-import { createOptimizedWorkerChannel } from 'fest/uniform';
-
-// Create optimized channel with advanced features
-const worker = await createOptimizedWorkerChannel({
-    name: 'my-worker',
-    script: './my-worker.uniform.worker.ts'
-}, {
-    timeout: 10000,
-    retries: 3,
-    batching: true,
-    compression: false
-});
-
-// Request with automatic batching and retry
-const result = await worker.request('processData', { data: 'hello' });
-
-// Fire-and-forget notifications
-worker.notify('logMessage', 'Processing complete');
-```
-
-### Queued Optimized Channels
-
-```typescript
-import { createQueuedOptimizedWorkerChannel } from 'fest/uniform';
-
-// Best of both worlds: queuing + optimization
-const worker = createQueuedOptimizedWorkerChannel({
-    name: 'my-worker',
-    script: './my-worker.uniform.worker.ts'
-}, {
-    timeout: 10000,
-    retries: 3,
-    batching: true
-}, (channel) => {
-    console.log('Optimized worker channel ready!');
-});
-
-// Operations queue until ready, then use optimized protocol
-const result = await worker.request('processData', { data: 'hello' });
-```
-
-### Context-Specific Usage
-
-#### Service Worker Context
-```typescript
-import { detectExecutionContext, createServiceWorkerChannel } from 'fest/uniform';
-
-if (detectExecutionContext() === 'service-worker') {
-    // In service worker, use BroadcastChannel communication
-    const channel = await createServiceWorkerChannel({
-        name: 'sw-cache-worker',
-        script: './cache-worker.js'
-    });
-
-    // Communicate through BroadcastChannel
-    const result = await channel.request('cacheData', { data: 'important' });
-}
-```
-
-#### Chrome Extension Context
-```typescript
-import { createChromeExtensionChannel } from 'fest/uniform';
-
-const worker = await createChromeExtensionChannel({
-    name: 'extension-worker',
-    script: 'workers/processor.js' // Will be resolved with chrome.runtime.getURL()
-});
-
-// Automatic extension URL resolution
-const result = await worker.request('processExtensionData', data);
-```
-
-## Worker Implementation
-
-### Basic Worker
-
-```typescript
-// my-worker.uniform.worker.ts
-import { registerWorkerAPI } from 'fest/uniform';
-
-const workerAPI = {
-    async processData(payload: { data: string }) {
-        // Process the data
-        return payload.data.toUpperCase();
-    },
-
-    async logMessage(message: string) {
-        console.log('[Worker]', message);
-    }
-};
-
-registerWorkerAPI(workerAPI);
-```
-
-### Advanced Worker with Optimized Protocol
-
-```typescript
-// my-worker.uniform.worker.ts
-import { registerWorkerAPI } from 'fest/uniform';
-import { MessageEnvelope } from 'fest/uniform/src/optimized-protocol';
-
-const workerAPI = {
-    async processData(payload: { data: string }) {
-        return payload.data.toUpperCase();
-    }
-};
-
-// Handle optimized protocol messages
-const processMessage = async (envelope: MessageEnvelope) => {
-    if (envelope.type === 'batch') {
-        const results = [];
-        for (const msg of envelope.payload) {
-            results.push(await processSingleMessage(msg));
-        }
-        return results;
-    }
-    return await processSingleMessage(envelope);
-};
-
-const processSingleMessage = async (envelope: MessageEnvelope) => {
-    const handler = workerAPI[envelope.type as keyof typeof workerAPI];
-    if (!handler) {
-        throw new Error(`Unknown message type: ${envelope.type}`);
-    }
-    return await handler(envelope.payload);
-};
-
-// Register API and message processor
-registerWorkerAPI(workerAPI);
-(globalThis as any).processMessage = processMessage;
-```
-
-## API Reference
-
-### Core Functions
-
-#### `createWorkerChannel(config: WorkerConfig): Promise<WorkerChannel>`
-
-Creates a basic worker channel.
-
-**Parameters:**
-- `config.name`: Unique channel name
-- `config.script`: Path to worker script
-- `config.options`: Worker options
-
-#### `createOptimizedWorkerChannel(config: WorkerConfig, options?: ProtocolOptions): Promise<OptimizedWorkerChannel>`
-
-Creates an optimized worker channel with advanced features.
-
-**Protocol Options:**
-- `timeout`: Request timeout in milliseconds (default: 30000)
-- `retries`: Number of retry attempts (default: 3)
-- `batching`: Enable message batching (default: true)
-- `compression`: Enable payload compression (default: false)
-
-### WorkerChannel Methods
-
-#### `request(method: string, args: any[]): Promise<any>`
-
-Call a worker method and wait for response.
-
-#### `close(): void`
-
-Close the worker channel.
-
-### OptimizedWorkerChannel Methods
-
-#### `request(type: string, payload: any, options?: Partial<ProtocolOptions>): Promise<any>`
-
-Send request with optimization features.
-
-#### `notify(type: string, payload: any): void`
-
-Send fire-and-forget message.
-
-#### `stream(type: string, data: any[]): AsyncGenerator<any>`
-
-Stream data with backpressure handling.
-
-## Advanced Features
-
-### Message Batching
-
-Automatically batches multiple messages to reduce overhead:
-
-```typescript
-const worker = await createOptimizedWorkerChannel(config, { batching: true });
-
-// These calls will be batched automatically
-await Promise.all([
-    worker.request('method1', data1),
-    worker.request('method2', data2),
-    worker.request('method3', data3)
-]);
+```bash
+npm install @fest-lib/uniform
 ```
 
-### Error Handling and Retries
-
-```typescript
-const worker = await createOptimizedWorkerChannel(config, {
-    retries: 3,
-    timeout: 5000
-});
+```ts
+import {
+  createUnifiedChannel,
+  createInvoker,
+  detectContextType
+} from "@fest-lib/uniform";
 
-try {
-    const result = await worker.request('unreliableMethod', data);
-} catch (error) {
-    console.error('All retries failed:', error);
-}
+const channel = createUnifiedChannel({ name: "opfs" });
+const invoker = createInvoker(channel);
 ```
 
-### Streaming Data
+Worker-style (queued until ready):
 
-```typescript
-const worker = await createOptimizedWorkerChannel(config);
+```ts
+import { createQueuedWorkerChannel } from "@fest-lib/uniform";
 
-// Stream large datasets
-for await (const result of worker.stream('processChunk', largeDataArray)) {
-    console.log('Processed chunk:', result);
-}
+const worker = createQueuedWorkerChannel(
+  { name: "my-worker", script: "./my-worker.uniform.worker.ts" },
+  () => { /* connected */ }
+);
+const result = await worker.request("processData", { data: "hello" });
 ```
 
-## Integration Examples
-
-### OPFS Worker (Real Example)
-
-```typescript
-// From fest/lure OPFS implementation
-import { createOptimizedWorkerChannel } from 'fest/uniform';
-
-const workerChannel = await createOptimizedWorkerChannel({
-    name: "opfs-worker",
-    script: "./OPFS.uniform.worker.ts"
-}, {
-    timeout: 10000,
-    batching: true
-});
-
-// Use like a regular function call
-const result = await workerChannel.request('readFile', {
-    rootId: 'user',
-    path: '/data.json'
-});
-```
-
-## Performance Benefits
-
-- **Reduced Latency**: Message batching minimizes round trips
-- **Better Throughput**: Optimized serialization and transfer handling
-- **Automatic Retry**: Built-in error recovery
-- **Memory Efficient**: Proper transferable object handling
-- **Type Safe**: Full TypeScript support across worker boundaries
-
-## Migration from postMessage
-
-### Before (Traditional)
-
-```typescript
-const worker = new Worker('./worker.js');
-
-worker.postMessage({ type: 'process', data });
-
-worker.onmessage = (e) => {
-    const { result, error } = e.data;
-    if (error) handleError(error);
-    else handleResult(result);
-};
-```
-
-### After (Uniform)
-
-```typescript
-const worker = await createWorkerChannel({
-    name: 'my-worker',
-    script: './worker.uniform.worker.ts'
-});
-
-try {
-    const result = await worker.request('process', data);
-    handleResult(result);
-} catch (error) {
-    handleError(error);
-}
-```
-
-## Execution Context Support
-
-Fest/Uniform automatically adapts to different JavaScript execution contexts:
-
-### Main Thread Context
-- Full dedicated worker support
-- MessageChannel communication
-- All optimization features available
-
-### Service Worker Context
-- BroadcastChannel-based communication
-- No dedicated worker creation (not supported)
-- Queued operations with fallback handling
-
-### Chrome Extension Context
-- Dedicated worker support with extension URL resolution
-- Automatic detection of extension environment
-- Fallback communication patterns
-
-### Context Detection
-```typescript
-import { detectExecutionContext, supportsDedicatedWorkers } from 'fest/uniform';
-
-const context = detectExecutionContext(); // 'main' | 'service-worker' | 'chrome-extension' | 'unknown'
-const hasWorkers = supportsDedicatedWorkers(); // boolean
-```
-
-## Browser Support
-
-Requires modern browsers with:
-- ES2020 modules
-- MessageChannel API (main thread)
-- BroadcastChannel API (service workers)
-- Proxy API
-- WeakRef (optional)
-
-Compatible with all Chromium-based browsers and modern Firefox/Safari.
-
-## Examples
-
-- [Service Worker Integration](./examples/service-worker-integration.ts) - Using uniform channels in service worker context
-- [Chrome Extension Integration](./examples/chrome-extension-integration.ts) - Chrome extension worker communication
-
-## Contributing
-
-This library is experimental and evolving. Contributions welcome!
+## Layout
 
-## License
+| Path | Role |
+| --- | --- |
+| `src/newer/next/channel/UnifiedChannel.ts` | primary channel |
+| `src/newer/next/proxy/Invoker.ts` | request/response |
+| `src/newer/core/TransportCore.ts` | transport factory |
+| `src/newer/messaging/*` | queues / protocol |
+| `src/original/*` | older worker helpers |
 
-MIT License
+Peer: `@fest-lib/core`. Build: `npm run build`. Publish: `npm run publish`.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@fest-lib/uniform",
-    "description": "Universal worker and channel helpers (fest-lib)",
-    "version": "0.1.11",
+    "description": "fest-lib UnifiedChannel: workers, ports, BroadcastChannel, Chrome, Atomics, WebRTC",
+    "version": "0.1.13",
     "license": "MIT",
     "type": "module",
     "sideEffects": true,