Hello World
\",\n});\n\n// Subscribe to events\nemail.on(\"email.sent\", async (event) => {\n console.log(\"Email sent:\", event.data.messageId);\n});\n```\n\n## Modules\n\n### RPC\n\nRequest-response communication between services.\n\n```typescript\nimport {\n RpcClient,\n RpcServer,\n createRpcClient,\n createRpcServer,\n EmbeddedTransport,\n HttpTransport,\n} from \"@parsrun/service/rpc\";\n\n// Create server\nconst server = createRpcServer({\n service: \"email\",\n handlers: {\n send: async (input, ctx) => {\n // Handle request\n return { success: true, messageId: \"123\" };\n },\n },\n});\n\n// Create client\nconst client = createRpcClient({\n service: \"email\",\n transport: new EmbeddedTransport(server),\n});\n\n// Call method\nconst result = await client.call(\"send\", {\n to: \"user@example.com\",\n subject: \"Hello\",\n html: \"Hello
\",\n});\n```\n\n### Events\n\nAsynchronous event-driven communication.\n\n```typescript\nimport {\n EventEmitter,\n createEventEmitter,\n MemoryEventTransport,\n createMemoryEventTransport,\n} from \"@parsrun/service/events\";\n\n// Create transport\nconst transport = createMemoryEventTransport();\n\n// Create emitter\nconst emitter = createEventEmitter({\n service: \"email\",\n transport,\n});\n\n// Emit event\nawait emitter.emit(\"email.sent\", {\n messageId: \"123\",\n to: \"user@example.com\",\n});\n\n// Subscribe to events\ntransport.subscribe(\"email.*\", async (event, ctx) => {\n console.log(\"Event received:\", event.type, event.data);\n});\n```\n\n### Resilience\n\nPatterns for building resilient systems.\n\n```typescript\nimport {\n CircuitBreaker,\n Bulkhead,\n withRetry,\n withTimeout,\n TimeoutExceededError,\n} from \"@parsrun/service/resilience\";\n\n// Circuit Breaker\nconst cb = new CircuitBreaker({\n failureThreshold: 5,\n resetTimeout: 30000,\n successThreshold: 2,\n});\n\nconst result = await cb.execute(async () => {\n return await fetch(\"https://api.example.com/data\");\n});\n\n// Bulkhead (concurrency limiting)\nconst bulkhead = new Bulkhead({\n maxConcurrent: 10,\n maxQueue: 100,\n});\n\nawait bulkhead.execute(async () => {\n // Limited concurrent execution\n});\n\n// Retry with backoff\nconst fetchWithRetry = withRetry(\n async () => fetch(\"https://api.example.com/data\"),\n {\n attempts: 3,\n backoff: \"exponential\",\n initialDelay: 100,\n maxDelay: 5000,\n shouldRetry: (error) => error.retryable !== false,\n }\n);\n\n// Timeout\nconst fetchWithTimeout = withTimeout(\n async () => fetch(\"https://api.example.com/data\"),\n 5000\n);\n```\n\n### Tracing\n\nW3C Trace Context compatible distributed tracing.\n\n```typescript\nimport {\n Tracer,\n createTracer,\n ConsoleExporter,\n OtlpExporter,\n} from \"@parsrun/service/tracing\";\n\n// Create tracer\nconst tracer = createTracer({\n serviceName: \"email-service\",\n serviceVersion: \"1.0.0\",\n exporter: new ConsoleExporter(),\n});\n\n// Trace an operation\nconst result = await tracer.trace(\"send-email\", async (span) => {\n span?.attributes[\"email.to\"] = \"user@example.com\";\n // ... send email\n return { success: true };\n});\n\n// Manual span management\nconst span = tracer.startSpan(\"process-webhook\", { kind: \"server\" });\ntry {\n // Process webhook\n tracer.endSpan(span);\n} catch (error) {\n tracer.endSpan(span, error);\n throw error;\n}\n```\n\n### Cloudflare Transports\n\nNative Cloudflare Workers integration.\n\n```typescript\nimport {\n WorkerRpcTransport,\n DurableObjectTransport,\n QueueEventTransport,\n} from \"@parsrun/service/transports/cloudflare\";\n\n// Service Binding (Worker-to-Worker RPC)\nconst transport = new WorkerRpcTransport({\n binding: env.EMAIL_SERVICE, // Service binding\n});\n\n// Durable Object RPC\nconst doTransport = new DurableObjectTransport({\n namespace: env.EMAIL_DO,\n idGenerator: (req) => req.tenantId,\n});\n\n// Queue-based Events\nconst queueTransport = new QueueEventTransport({\n queue: env.EVENTS_QUEUE,\n});\n```\n\n## Configuration\n\n```typescript\nimport { mergeConfig, createDevConfig, createProdConfig } from \"@parsrun/service\";\n\n// Development config\nconst devConfig = createDevConfig({\n resilience: {\n circuitBreaker: { enabled: false }, // Disable for debugging\n },\n tracing: {\n enabled: true,\n sampler: \"always\", // Trace everything\n },\n});\n\n// Production config\nconst prodConfig = createProdConfig({\n resilience: {\n circuitBreaker: {\n failureThreshold: 5,\n resetTimeout: 30000,\n },\n bulkhead: {\n maxConcurrent: 100,\n },\n },\n tracing: {\n enabled: true,\n sampler: { ratio: 0.1 }, // Sample 10% of requests\n },\n});\n```\n\n## Sub-path Imports\n\n```typescript\n// Main entry (everything)\nimport { defineService, useService } from \"@parsrun/service\";\n\n// Specific modules\nimport { RpcClient, RpcServer } from \"@parsrun/service/rpc\";\nimport { EventEmitter, MemoryEventTransport } from \"@parsrun/service/events\";\nimport { CircuitBreaker, withRetry } from \"@parsrun/service/resilience\";\nimport { Tracer, createTracer } from \"@parsrun/service/tracing\";\nimport { jsonSerializer } from \"@parsrun/service/serialization\";\nimport { WorkerRpcTransport } from \"@parsrun/service/transports/cloudflare\";\n```\n\n## API Reference\n\n### Core\n\n| Export | Description |\n|--------|-------------|\n| `defineService(def)` | Define a service with queries, mutations, events |\n| `useService(name, options?)` | Get a service client |\n| `ServiceRegistry` | Manage multiple service instances |\n\n### RPC\n\n| Export | Description |\n|--------|-------------|\n| `RpcClient` | Client for making RPC calls |\n| `RpcServer` | Server for handling RPC requests |\n| `EmbeddedTransport` | In-process transport (testing/monolith) |\n| `HttpTransport` | HTTP-based transport |\n| `createHttpHandler(server)` | Create HTTP request handler |\n\n### Events\n\n| Export | Description |\n|--------|-------------|\n| `EventEmitter` | Emit CloudEvents-compatible events |\n| `EventHandlerRegistry` | Register event handlers |\n| `MemoryEventTransport` | In-memory transport |\n| `GlobalEventBus` | Cross-service event bus |\n| `DeadLetterQueue` | Store failed events |\n\n### Resilience\n\n| Export | Description |\n|--------|-------------|\n| `CircuitBreaker` | Fail fast when service is unhealthy |\n| `Bulkhead` | Limit concurrent requests |\n| `withRetry(fn, options)` | Retry failed operations |\n| `withTimeout(fn, ms)` | Add timeout to operations |\n| `TimeoutExceededError` | Timeout error class |\n\n### Tracing\n\n| Export | Description |\n|--------|-------------|\n| `Tracer` | Main tracing class |\n| `createTraceContext()` | Create W3C trace context |\n| `ConsoleExporter` | Export spans to console |\n| `OtlpExporter` | Export spans to OTLP endpoint |\n| `SpanAttributes` | Standard span attribute names |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}