@parsrun/service 0.1.29 → 0.1.30

package/dist/{handler-CmiDUWZv.d.ts → handler-eCIZLODd.d.ts}

@@ -1,11 +1,15 @@
 import { Logger } from '@parsrun/core';
-import { P as ParsEvent, e as EventHandlerOptions, j as EventHandler, U as Unsubscribe } from './types-n4LLSPQU.js';
+import { P as ParsEvent, e as EventHandlerOptions, j as EventHandler, U as Unsubscribe } from './types-DHZaZwAt.js';
 
 /**
  * @parsrun/service - Dead Letter Queue
  * Storage for failed events
  */
 
+/**
+ * Entry stored in the dead letter queue.
+ * Contains the failed event and metadata about the failure.
+ */
 interface DeadLetterEntry {
     /** Unique ID */
     id: string;
@@ -22,6 +26,9 @@ interface DeadLetterEntry {
     /** Optional metadata */
     metadata?: Record<string, unknown>;
 }
+/**
+ * Options for creating a dead letter queue.
+ */
 interface DeadLetterQueueOptions {
     /** Maximum entries to keep */
     maxSize?: number;
@@ -36,6 +43,9 @@ interface DeadLetterQueueOptions {
     /** Logger */
     logger?: Logger;
 }
+/**
+ * Options for adding an entry to the dead letter queue.
+ */
 interface AddEntryOptions {
     /** Original event */
     event: ParsEvent;
@@ -115,7 +125,19 @@ declare class DeadLetterQueue {
     import(entries: DeadLetterEntry[]): void;
 }
 /**
- * Create a dead letter queue
+ * Create a dead letter queue for storing failed events.
+ *
+ * @param options - DLQ configuration options
+ * @returns A new dead letter queue instance
+ *
+ * @example
+ * ```typescript
+ * const dlq = createDeadLetterQueue({
+ *   maxSize: 1000,
+ *   alertThreshold: 50,
+ *   onThreshold: (count) => alert(`DLQ has ${count} entries`),
+ * });
+ * ```
  */
 declare function createDeadLetterQueue(options?: DeadLetterQueueOptions): DeadLetterQueue;
 
@@ -134,6 +156,9 @@ interface ResolvedHandlerOptions {
     onExhausted: "alert" | "log" | "discard";
     deadLetter?: string;
 }
+/**
+ * Registration entry for an event handler.
+ */
 interface HandlerRegistration {
     /** Event type pattern (supports wildcards) */
     pattern: string;
@@ -142,6 +167,9 @@ interface HandlerRegistration {
     /** Handler options */
     options: ResolvedHandlerOptions;
 }
+/**
+ * Options for creating an event handler registry.
+ */
 interface EventHandlerRegistryOptions {
     /** Logger */
     logger?: Logger;
@@ -197,7 +225,21 @@ declare class EventHandlerRegistry {
     clear(): void;
 }
 /**
- * Create an event handler registry
+ * Create an event handler registry for managing event subscriptions.
+ *
+ * @param options - Registry configuration options
+ * @returns A new event handler registry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createEventHandlerRegistry({
+ *   deadLetterQueue: dlq,
+ *   defaultOptions: { retries: 3 },
+ * });
+ * registry.register('subscription.*', async (event, ctx) => {
+ *   console.log('Received event:', event.type);
+ * });
+ * ```
  */
 declare function createEventHandlerRegistry(options?: EventHandlerRegistryOptions): EventHandlerRegistry;
 

package/dist/{index-CVOAoJjZ.d.ts → index-reEpIe1R.d.ts}

@@ -1,5 +1,5 @@
-import { s as RpcTransport, S as ServiceConfig, i as RpcMetadata, m as TraceContext, f as RpcRequest, g as RpcResponse } from './types-n4LLSPQU.js';
-import { R as RpcServer } from './server-DFE8n2Sx.js';
+import { s as RpcTransport, S as ServiceConfig, i as RpcMetadata, m as TraceContext, f as RpcRequest, g as RpcResponse } from './types-DHZaZwAt.js';
+import { R as RpcServer } from './server-BB9AbnkP.js';
 import { Serializer } from './serialization/index.js';
 import { ParsError } from '@parsrun/core';
 
@@ -8,6 +8,9 @@ import { ParsError } from '@parsrun/core';
  * Client for making RPC calls to services
  */
 
+/**
+ * Options for creating an RPC client.
+ */
 interface RpcClientOptions {
     /** Service name */
     service: string;
@@ -58,7 +61,8 @@ declare class RpcClient {
     close(): Promise<void>;
 }
 /**
- * Call options
+ * Options for individual RPC calls.
+ * Allows overriding default client settings per-call.
  */
 interface CallOptions {
     /** Timeout in ms */
@@ -78,7 +82,20 @@ interface CallOptions {
     };
 }
 /**
- * Create an RPC client
+ * Create an RPC client for making service calls.
+ *
+ * @param options - Client configuration options
+ * @returns A new RPC client instance
+ *
+ * @example
+ * ```typescript
+ * const client = createRpcClient({
+ *   service: 'payments',
+ *   transport: httpTransport,
+ *   config: { resilience: { timeout: 5000 } },
+ * });
+ * const result = await client.query('getSubscription', { id: '123' });
+ * ```
  */
 declare function createRpcClient(options: RpcClientOptions): RpcClient;
 
@@ -99,7 +116,17 @@ declare class EmbeddedTransport implements RpcTransport {
     close(): Promise<void>;
 }
 /**
- * Create an embedded transport
+ * Create an embedded transport for direct function calls.
+ * Used when the service is in the same process.
+ *
+ * @param server - The RPC server to call directly
+ * @returns A new embedded transport instance
+ *
+ * @example
+ * ```typescript
+ * const transport = createEmbeddedTransport(rpcServer);
+ * const client = createRpcClient({ service: 'payments', transport });
+ * ```
  */
 declare function createEmbeddedTransport(server: RpcServer): EmbeddedTransport;
 /**
@@ -145,7 +172,17 @@ declare class EmbeddedRegistry {
     static reset(): void;
 }
 /**
- * Get the global embedded registry
+ * Get the global embedded registry singleton.
+ * Provides access to the shared registry for service discovery.
+ *
+ * @returns The global embedded registry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = getEmbeddedRegistry();
+ * registry.register('payments', paymentsServer);
+ * const transport = registry.createTransport('payments');
+ * ```
  */
 declare function getEmbeddedRegistry(): EmbeddedRegistry;
 
@@ -154,6 +191,9 @@ declare function getEmbeddedRegistry(): EmbeddedRegistry;
  * HTTP-based transport for distributed services
  */
 
+/**
+ * Options for creating an HTTP transport.
+ */
 interface HttpTransportOptions {
     /** Base URL of the service */
     baseUrl: string;
@@ -167,7 +207,8 @@ interface HttpTransportOptions {
     timeout?: number;
 }
 /**
- * HTTP transport for RPC calls
+ * HTTP transport for RPC calls over HTTP/HTTPS.
+ * Makes POST requests to /rpc endpoint with serialized request body.
  */
 declare class HttpTransport implements RpcTransport {
     readonly name = "http";
@@ -181,18 +222,48 @@ declare class HttpTransport implements RpcTransport {
     close(): Promise<void>;
 }
 /**
- * Create an HTTP transport
+ * Create an HTTP transport for RPC calls.
+ *
+ * @param options - Transport configuration options
+ * @returns A new HTTP transport instance
+ *
+ * @example
+ * ```typescript
+ * const transport = createHttpTransport({
+ *   baseUrl: 'https://api.example.com',
+ *   timeout: 5000,
+ * });
+ * ```
  */
 declare function createHttpTransport(options: HttpTransportOptions): HttpTransport;
 
 /**
- * Parse W3C traceparent header
+ * Parse W3C traceparent header to extract trace context.
+ *
+ * @param header - The traceparent header value
+ * @returns Parsed trace context or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const ctx = parseTraceparent('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+ * // { traceId: '0af7651916cd43dd8448eb211c80319c', spanId: 'b7ad6b7169203331', traceFlags: 1 }
+ * ```
  */
 declare function parseTraceparent(header: string): TraceContext | null;
 
 /**
- * Create HTTP request handler for RPC server
- * Can be used with Hono, Express, or any HTTP framework
+ * Create HTTP request handler for RPC server.
+ * Can be used with Hono, Express, or any HTTP framework.
+ *
+ * @param server - The RPC server to handle requests
+ * @returns Request handler function for HTTP frameworks
+ *
+ * @example
+ * ```typescript
+ * const handler = createHttpHandler(rpcServer);
+ * // With Hono
+ * app.post('/rpc', (c) => handler(c.req.raw));
+ * ```
  */
 declare function createHttpHandler(server: RpcServer): (request: Request) => Promise<Response>;
 

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { S as ServiceConfig, E as EventFormatConfig, a as SerializationConfig, T as TracingConfig, V as VersioningConfig, R as ResilienceConfig, D as DeadLetterConfig } from './types-n4LLSPQU.js';
-export { B as BulkheadConfig, u as CircuitBreakerConfig, C as CompactEvent, I as EventData, c as EventDefinition, j as EventHandler, k as EventHandlerContext, d as EventHandlerDefinition, e as EventHandlerOptions, l as EventLogger, t as EventTransport, F as Fetcher, M as MutationDefinition, G as MutationInput, H as MutationOutput, P as ParsEvent, Q as QueryDefinition, z as QueryInput, A as QueryOutput, v as RetryConfig, h as RpcErrorData, i as RpcMetadata, f as RpcRequest, g as RpcResponse, s as RpcTransport, x as ServiceClient, w as ServiceClientOptions, b as ServiceDefinition, y as ServiceInstance, n as Span, q as SpanAttributeValue, r as SpanEvent, o as SpanKind, p as SpanStatus, m as TraceContext, U as Unsubscribe } from './types-n4LLSPQU.js';
+import { S as ServiceConfig, E as EventFormatConfig, a as SerializationConfig, T as TracingConfig, V as VersioningConfig, R as ResilienceConfig, D as DeadLetterConfig } from './types-DHZaZwAt.js';
+export { B as BulkheadConfig, u as CircuitBreakerConfig, C as CompactEvent, I as EventData, c as EventDefinition, j as EventHandler, k as EventHandlerContext, d as EventHandlerDefinition, e as EventHandlerOptions, l as EventLogger, t as EventTransport, F as Fetcher, M as MutationDefinition, G as MutationInput, H as MutationOutput, P as ParsEvent, Q as QueryDefinition, z as QueryInput, A as QueryOutput, v as RetryConfig, h as RpcErrorData, i as RpcMetadata, f as RpcRequest, g as RpcResponse, s as RpcTransport, x as ServiceClient, w as ServiceClientOptions, b as ServiceDefinition, y as ServiceInstance, n as Span, q as SpanAttributeValue, r as SpanEvent, o as SpanKind, p as SpanStatus, m as TraceContext, U as Unsubscribe } from './types-DHZaZwAt.js';
 export { defineService, getMethodTimeout, getServiceEvents, getServiceMethods, isMethodDeprecated, satisfiesVersion } from './define.js';
 export { ServiceRegistry, createServiceRegistry, useService, useTypedService } from './client.js';
-export { B as BulkheadRejectedError, C as CallOptions, i as CircuitOpenError, b as EmbeddedRegistry, E as EmbeddedTransport, H as HttpTransport, f as HttpTransportOptions, M as MethodNotFoundError, R as RpcClient, h as RpcError, k as SerializationError, S as ServiceNotFoundError, T as TimeoutError, j as TransportError, V as VersionMismatchError, a as createEmbeddedTransport, e as createHttpHandler, d as createHttpTransport, c as createRpcClient, g as getEmbeddedRegistry, p as parseTraceparent, t as toRpcError } from './index-CVOAoJjZ.js';
-export { a as RpcHandler, e as RpcHandlerContext, b as RpcHandlers, d as RpcMiddleware, R as RpcServer, c as createRpcServer, l as loggingMiddleware, t as tenantMiddleware, v as validationMiddleware } from './server-DFE8n2Sx.js';
+export { B as BulkheadRejectedError, C as CallOptions, i as CircuitOpenError, b as EmbeddedRegistry, E as EmbeddedTransport, H as HttpTransport, f as HttpTransportOptions, M as MethodNotFoundError, R as RpcClient, h as RpcError, k as SerializationError, S as ServiceNotFoundError, T as TimeoutError, j as TransportError, V as VersionMismatchError, a as createEmbeddedTransport, e as createHttpHandler, d as createHttpTransport, c as createRpcClient, g as getEmbeddedRegistry, p as parseTraceparent, t as toRpcError } from './index-reEpIe1R.js';
+export { a as RpcHandler, e as RpcHandlerContext, b as RpcHandlers, d as RpcMiddleware, R as RpcServer, c as createRpcServer, l as loggingMiddleware, t as tenantMiddleware, v as validationMiddleware } from './server-BB9AbnkP.js';
 export { EmitOptions, EventEmitter, EventEmitterOptions, GlobalEventBus, MemoryEventTransport, MemoryEventTransportOptions, ScopedEmitter, TypedEventEmitter, createEvent, createEventEmitter, createMemoryEventTransport, createTypedEmitter, formatEventType, fromCompactEvent, getGlobalEventBus, matchEventType, parseEventType, toCloudEvent, toCompactEvent, validateCompactEvent, validateEvent } from './events/index.js';
-export { A as AddEntryOptions, d as DeadLetterEntry, D as DeadLetterQueue, e as DeadLetterQueueOptions, E as EventHandlerRegistry, a as EventHandlerRegistryOptions, H as HandlerRegistration, b as createDeadLetterQueue, c as createEventHandlerRegistry } from './handler-CmiDUWZv.js';
+export { A as AddEntryOptions, d as DeadLetterEntry, D as DeadLetterQueue, e as DeadLetterQueueOptions, E as EventHandlerRegistry, a as EventHandlerRegistryOptions, H as HandlerRegistration, b as createDeadLetterQueue, c as createEventHandlerRegistry } from './handler-eCIZLODd.js';
 export { Bulkhead, BulkheadOptions, CircuitBreaker, CircuitBreakerOptions, CircuitState, RetryOptions, TimeoutExceededError, createRetryWrapper, createTimeoutWrapper, executeWithDeadline, executeWithRetry, executeWithTimeout, raceWithTimeout, withRetry, withTimeout } from './resilience/index.js';
 export { ConsoleExporter, ConsoleExporterOptions, ExporterOptions, OtlpExporter, OtlpExporterOptions, Sampler, SpanAttributes, SpanExporter, SpanManager, SpanOptions, TraceContextManager, Tracer, TracerOptions, createChildContext, createConsoleExporter, createOtlpExporter, createRpcTracing, createSpan, createTraceContext, createTracer, createTracingMiddleware, formatTraceparent, formatTracestate, generateSpanId, generateTraceId, getGlobalTracer, getSpanDuration, isSpanCompleted, parseTracestate, resetGlobalTracer, setGlobalTracer, shouldSample, spanToLogObject } from './tracing/index.js';
 export { Serializer, createSerializer, getSerializer, jsonSerializer, msgpackSerializer } from './serialization/index.js';
@@ -16,27 +16,71 @@ import '@parsrun/core';
  * Default configuration and config utilities
  */
 
+/**
+ * Default event format configuration.
+ * Uses CloudEvents format with compact internal communication.
+ */
 declare const DEFAULT_EVENT_CONFIG: Required<EventFormatConfig>;
+/**
+ * Default serialization configuration.
+ * Uses JSON format for data encoding.
+ */
 declare const DEFAULT_SERIALIZATION_CONFIG: Required<SerializationConfig>;
+/**
+ * Default tracing configuration.
+ * Enables tracing with 10% sampling ratio and console exporter.
+ */
 declare const DEFAULT_TRACING_CONFIG: Required<TracingConfig>;
+/**
+ * Default versioning configuration.
+ * Uses header-based versioning with "1.x" as the default version.
+ */
 declare const DEFAULT_VERSIONING_CONFIG: Required<VersioningConfig>;
+/**
+ * Default resilience configuration.
+ * Configures circuit breaker, bulkhead, timeout, and retry settings.
+ */
 declare const DEFAULT_RESILIENCE_CONFIG: Required<ResilienceConfig>;
+/**
+ * Default dead letter queue configuration.
+ * Enables DLQ with 30-day retention and alerting at 10 messages.
+ */
 declare const DEFAULT_DEAD_LETTER_CONFIG: Required<DeadLetterConfig>;
+/**
+ * Default complete service configuration.
+ * Combines all default sub-configurations.
+ */
 declare const DEFAULT_SERVICE_CONFIG: Required<ServiceConfig>;
 /**
- * Merge user config with defaults
+ * Merge user config with defaults.
+ * Deep merges the user configuration with default values.
+ *
+ * @param userConfig - Optional partial service configuration
+ * @returns Complete service configuration with all required fields
  */
 declare function mergeConfig(userConfig?: Partial<ServiceConfig>): Required<ServiceConfig>;
 /**
- * Create config for development
+ * Create configuration optimized for development.
+ * Enables full tracing, disables circuit breaker, and uses longer timeouts.
+ *
+ * @param overrides - Optional configuration overrides
+ * @returns Complete service configuration for development
  */
 declare function createDevConfig(overrides?: Partial<ServiceConfig>): Required<ServiceConfig>;
 /**
- * Create config for production
+ * Create configuration optimized for production.
+ * Uses 10% sampling ratio, OTLP exporter, and enables circuit breaker.
+ *
+ * @param overrides - Optional configuration overrides
+ * @returns Complete service configuration for production
  */
 declare function createProdConfig(overrides?: Partial<ServiceConfig>): Required<ServiceConfig>;
 /**
- * Validate config
+ * Validate service configuration.
+ * Checks for valid ranges and values in the configuration.
+ *
+ * @param config - Service configuration to validate
+ * @returns Object containing validation result and any error messages
  */
 declare function validateConfig(config: ServiceConfig): {
     valid: boolean;

package/dist/index.js

@@ -669,6 +669,7 @@ function createRetryWrapper(defaultOptions) {
 
 // src/resilience/timeout.ts
 var TimeoutExceededError = class extends Error {
+  /** The timeout value in milliseconds that was exceeded */
   timeout;
   constructor(timeout) {
     super(`Operation timed out after ${timeout}ms`);