@parsrun/service 0.1.0

package/dist/types-n4LLSPQU.d.ts

@@ -0,0 +1,473 @@
+/**
+ * @parsrun/service - Core Types
+ * Type definitions for the unified service layer
+ */
+/**
+ * Query method definition
+ * Synchronous request-response pattern
+ */
+interface QueryDefinition<TInput = unknown, TOutput = unknown> {
+    /** Input schema/type */
+    input?: TInput;
+    /** Output schema/type */
+    output?: TOutput;
+    /** Version when this query was added */
+    since?: string;
+    /** Version when deprecated */
+    deprecated?: string;
+    /** Replacement method name */
+    replacement?: string;
+    /** Description for documentation */
+    description?: string;
+    /** Timeout override in ms */
+    timeout?: number;
+}
+/**
+ * Mutation method definition
+ * Synchronous request-response pattern that modifies state
+ */
+interface MutationDefinition<TInput = unknown, TOutput = unknown> {
+    /** Input schema/type */
+    input?: TInput;
+    /** Output schema/type */
+    output?: TOutput;
+    /** Version when this mutation was added */
+    since?: string;
+    /** Version when deprecated */
+    deprecated?: string;
+    /** Replacement method name */
+    replacement?: string;
+    /** Description for documentation */
+    description?: string;
+    /** Timeout override in ms */
+    timeout?: number;
+    /** Whether this mutation is idempotent */
+    idempotent?: boolean;
+}
+/**
+ * Event definition
+ */
+interface EventDefinition<TData = unknown> {
+    /** Event data schema/type */
+    data?: TData;
+    /** Delivery guarantee */
+    delivery?: "at-most-once" | "at-least-once";
+    /** Version when this event was added */
+    since?: string;
+    /** Description for documentation */
+    description?: string;
+}
+/**
+ * Event handler definition
+ */
+interface EventHandlerDefinition {
+    /** Event type to handle */
+    event: string;
+    /** Handler options */
+    options?: EventHandlerOptions;
+}
+/**
+ * Event handler options
+ */
+interface EventHandlerOptions {
+    /** Number of retry attempts */
+    retries?: number;
+    /** Backoff strategy */
+    backoff?: "linear" | "exponential";
+    /** Maximum delay between retries in ms */
+    maxDelay?: number;
+    /** Dead letter queue name */
+    deadLetter?: string;
+    /** Action when retries exhausted */
+    onExhausted?: "alert" | "log" | "discard";
+}
+/**
+ * Complete service definition
+ */
+interface ServiceDefinition<TQueries extends Record<string, QueryDefinition> = Record<string, QueryDefinition>, TMutations extends Record<string, MutationDefinition> = Record<string, MutationDefinition>, TEmits extends Record<string, EventDefinition> = Record<string, EventDefinition>, THandles extends string[] = string[]> {
+    /** Unique service name */
+    name: string;
+    /** Service version (semver) */
+    version: string;
+    /** Service description */
+    description?: string;
+    /** Query methods (read-only, sync) */
+    queries?: TQueries;
+    /** Mutation methods (write, sync) */
+    mutations?: TMutations;
+    /** Events this service emits */
+    events?: {
+        emits?: TEmits;
+        handles?: THandles;
+    };
+}
+/**
+ * RPC request envelope
+ */
+interface RpcRequest<T = unknown> {
+    /** Request ID for correlation */
+    id: string;
+    /** Service name */
+    service: string;
+    /** Method name */
+    method: string;
+    /** Method type */
+    type: "query" | "mutation";
+    /** Client version requirement */
+    version?: string;
+    /** Request payload */
+    input: T;
+    /** Trace context */
+    traceContext?: TraceContext;
+    /** Request metadata */
+    metadata?: RpcMetadata;
+}
+/**
+ * RPC response envelope
+ */
+interface RpcResponse<T = unknown> {
+    /** Correlation ID */
+    id: string;
+    /** Whether request succeeded */
+    success: boolean;
+    /** Service version that handled the request */
+    version: string;
+    /** Response payload (if success) */
+    output?: T;
+    /** Error details (if failure) */
+    error?: RpcErrorData;
+    /** Trace context */
+    traceContext?: TraceContext;
+    /** Response metadata */
+    metadata?: RpcMetadata;
+}
+/**
+ * RPC error data structure (in RPC response)
+ */
+interface RpcErrorData {
+    /** Error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Additional details */
+    details?: Record<string, unknown>;
+    /** Whether client should retry */
+    retryable?: boolean;
+    /** Suggested retry delay in ms */
+    retryAfter?: number;
+}
+/**
+ * RPC metadata
+ */
+interface RpcMetadata {
+    /** Tenant ID */
+    tenantId?: string;
+    /** User ID */
+    userId?: string;
+    /** Request ID */
+    requestId?: string;
+    /** Custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * CloudEvents-compatible event structure
+ */
+interface ParsEvent<T = unknown> {
+    /** CloudEvents spec version */
+    specversion: "1.0";
+    /** Event type (e.g., "subscription.created") */
+    type: string;
+    /** Event source (service name/path) */
+    source: string;
+    /** Unique event ID */
+    id: string;
+    /** Event timestamp (ISO 8601) */
+    time: string;
+    /** Content type */
+    datacontenttype?: string;
+    /** Subject (optional context) */
+    subject?: string;
+    /** Tenant ID */
+    parstenantid?: string;
+    /** Request ID for correlation */
+    parsrequestid?: string;
+    /** Trace context (W3C format) */
+    parstracecontext?: string;
+    /** Delivery guarantee */
+    parsdelivery?: "at-most-once" | "at-least-once";
+    /** Event payload */
+    data: T;
+}
+/**
+ * Compact internal event format (for service bindings)
+ */
+interface CompactEvent<T = unknown> {
+    /** Event type */
+    e: string;
+    /** Source service */
+    s: string;
+    /** Event ID */
+    i: string;
+    /** Timestamp (unix ms) */
+    t: number;
+    /** Trace context */
+    ctx?: string;
+    /** Tenant ID */
+    tid?: string;
+    /** Data */
+    d: T;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler<T = unknown> = (event: ParsEvent<T>, context: EventHandlerContext) => Promise<void>;
+/**
+ * Event handler context
+ */
+interface EventHandlerContext {
+    /** Logger instance */
+    logger: EventLogger;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Maximum attempts */
+    maxAttempts: number;
+    /** Whether this is a retry */
+    isRetry: boolean;
+    /** Trace context */
+    traceContext?: TraceContext;
+}
+/**
+ * Minimal logger interface for event handlers
+ */
+interface EventLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+}
+/**
+ * W3C Trace Context
+ */
+interface TraceContext {
+    /** Trace ID (32 hex chars) */
+    traceId: string;
+    /** Span ID (16 hex chars) */
+    spanId: string;
+    /** Trace flags */
+    traceFlags: number;
+    /** Trace state (vendor-specific) */
+    traceState?: string;
+}
+/**
+ * Span for tracing
+ */
+interface Span {
+    /** Span name */
+    name: string;
+    /** Span kind */
+    kind: SpanKind;
+    /** Trace context */
+    traceContext: TraceContext;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Start time (unix ms) */
+    startTime: number;
+    /** End time (unix ms) */
+    endTime?: number;
+    /** Span status */
+    status: SpanStatus;
+    /** Span attributes */
+    attributes: Record<string, SpanAttributeValue>;
+    /** Span events */
+    events: SpanEvent[];
+}
+type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+type SpanStatus = "unset" | "ok" | "error";
+type SpanAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+interface SpanEvent {
+    name: string;
+    time: number;
+    attributes?: Record<string, SpanAttributeValue>;
+}
+/**
+ * RPC transport interface
+ */
+interface RpcTransport {
+    /** Transport name */
+    readonly name: string;
+    /** Send RPC request and get response */
+    call<TInput, TOutput>(request: RpcRequest<TInput>): Promise<RpcResponse<TOutput>>;
+    /** Close transport connection */
+    close?(): Promise<void>;
+}
+/**
+ * Event transport interface
+ */
+interface EventTransport {
+    /** Transport name */
+    readonly name: string;
+    /** Emit an event */
+    emit<T>(event: ParsEvent<T>): Promise<void>;
+    /** Subscribe to events */
+    subscribe(eventType: string, handler: EventHandler, options?: EventHandlerOptions): Unsubscribe;
+    /** Close transport connection */
+    close?(): Promise<void>;
+}
+/**
+ * Unsubscribe function
+ */
+type Unsubscribe = () => void;
+/**
+ * Service configuration
+ */
+interface ServiceConfig {
+    /** Event format options */
+    events?: EventFormatConfig;
+    /** Serialization options */
+    serialization?: SerializationConfig;
+    /** Tracing options */
+    tracing?: TracingConfig;
+    /** Versioning options */
+    versioning?: VersioningConfig;
+    /** Resilience options */
+    resilience?: ResilienceConfig;
+    /** Dead letter queue options */
+    deadLetter?: DeadLetterConfig;
+}
+interface EventFormatConfig {
+    /** Use CloudEvents format (default: true) */
+    format?: "cloudevents" | "compact";
+    /** Use compact format for internal communication */
+    internalCompact?: boolean;
+}
+interface SerializationConfig {
+    /** Serialization format */
+    format?: "json" | "msgpack";
+}
+interface TracingConfig {
+    /** Enable tracing */
+    enabled?: boolean;
+    /** Sampling strategy */
+    sampler?: "always" | "never" | {
+        ratio: number;
+    };
+    /** Exporter type */
+    exporter?: "otlp" | "console" | "none";
+    /** OTLP endpoint */
+    endpoint?: string;
+    /** Service name for traces */
+    serviceName?: string;
+}
+interface VersioningConfig {
+    /** Versioning strategy */
+    strategy?: "header" | "url" | "none";
+    /** Default version to use */
+    defaultVersion?: string;
+}
+interface ResilienceConfig {
+    /** Circuit breaker config */
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Bulkhead config */
+    bulkhead?: BulkheadConfig;
+    /** Default timeout in ms */
+    timeout?: number;
+    /** Retry config */
+    retry?: RetryConfig;
+}
+interface CircuitBreakerConfig {
+    /** Enable circuit breaker */
+    enabled?: boolean;
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Time to wait before half-open state (ms) */
+    resetTimeout?: number;
+    /** Number of successes in half-open to close circuit */
+    successThreshold?: number;
+}
+interface BulkheadConfig {
+    /** Maximum concurrent requests */
+    maxConcurrent?: number;
+    /** Maximum queue size */
+    maxQueue?: number;
+}
+interface RetryConfig {
+    /** Number of retry attempts */
+    attempts?: number;
+    /** Backoff strategy */
+    backoff?: "linear" | "exponential";
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+}
+interface DeadLetterConfig {
+    /** Enable DLQ */
+    enabled?: boolean;
+    /** Retention period */
+    retention?: string;
+    /** Action on DLQ write */
+    onFail?: "alert" | "log" | "none";
+    /** Alert threshold (number of messages) */
+    alertThreshold?: number;
+}
+/**
+ * Service client options
+ */
+interface ServiceClientOptions {
+    /** Transport mode */
+    mode?: "embedded" | "binding" | "http";
+    /** HTTP base URL (for http mode) */
+    baseUrl?: string;
+    /** Cloudflare service binding (for binding mode) */
+    binding?: Fetcher;
+    /** Embedded service instance (for embedded mode) */
+    instance?: ServiceInstance;
+    /** Service configuration */
+    config?: ServiceConfig;
+    /** Custom RPC transport */
+    rpcTransport?: RpcTransport;
+    /** Custom event transport */
+    eventTransport?: EventTransport;
+}
+/**
+ * Cloudflare Fetcher interface (service binding)
+ */
+interface Fetcher {
+    fetch(input: string | Request | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Service instance (for embedded mode)
+ */
+interface ServiceInstance {
+    /** Handle RPC request */
+    handleRpc<TInput, TOutput>(request: RpcRequest<TInput>): Promise<RpcResponse<TOutput>>;
+    /** Handle event */
+    handleEvent<T>(event: ParsEvent<T>): Promise<void>;
+}
+/**
+ * Service client interface
+ */
+interface ServiceClient<TDef extends ServiceDefinition = ServiceDefinition> {
+    /** Service name */
+    readonly name: string;
+    /** Execute a query */
+    query<K extends keyof TDef["queries"]>(method: K, input: QueryInput<TDef["queries"], K>): Promise<QueryOutput<TDef["queries"], K>>;
+    /** Execute a mutation */
+    mutate<K extends keyof TDef["mutations"]>(method: K, input: MutationInput<TDef["mutations"], K>): Promise<MutationOutput<TDef["mutations"], K>>;
+    /** Emit an event */
+    emit<K extends keyof NonNullable<TDef["events"]>["emits"]>(eventType: K, data: EventData<NonNullable<TDef["events"]>["emits"], K>): Promise<void>;
+    /** Subscribe to events */
+    on<T = unknown>(eventType: string, handler: EventHandler<T>, options?: EventHandlerOptions): Unsubscribe;
+}
+/** Extract input type from queries record */
+type QueryInput<TQueries extends Record<string, QueryDefinition> | undefined, K extends keyof NonNullable<TQueries>> = NonNullable<TQueries>[K] extends QueryDefinition<infer TInput, unknown> ? TInput : never;
+/** Extract output type from queries record */
+type QueryOutput<TQueries extends Record<string, QueryDefinition> | undefined, K extends keyof NonNullable<TQueries>> = NonNullable<TQueries>[K] extends QueryDefinition<unknown, infer TOutput> ? TOutput : never;
+/** Extract input type from mutations record */
+type MutationInput<TMutations extends Record<string, MutationDefinition> | undefined, K extends keyof NonNullable<TMutations>> = NonNullable<TMutations>[K] extends MutationDefinition<infer TInput, unknown> ? TInput : never;
+/** Extract output type from mutations record */
+type MutationOutput<TMutations extends Record<string, MutationDefinition> | undefined, K extends keyof NonNullable<TMutations>> = NonNullable<TMutations>[K] extends MutationDefinition<unknown, infer TOutput> ? TOutput : never;
+/** Extract data type from events record */
+type EventData<TEvents extends Record<string, EventDefinition> | undefined, K extends keyof NonNullable<TEvents>> = NonNullable<TEvents>[K] extends EventDefinition<infer TData> ? TData : never;
+
+export type { QueryOutput as A, BulkheadConfig as B, CompactEvent as C, DeadLetterConfig as D, EventFormatConfig as E, Fetcher as F, MutationInput as G, MutationOutput as H, EventData as I, MutationDefinition as M, ParsEvent as P, QueryDefinition as Q, ResilienceConfig as R, ServiceConfig as S, TracingConfig as T, Unsubscribe as U, VersioningConfig as V, SerializationConfig as a, ServiceDefinition as b, EventDefinition as c, EventHandlerDefinition as d, EventHandlerOptions as e, RpcRequest as f, RpcResponse as g, RpcErrorData as h, RpcMetadata as i, EventHandler as j, EventHandlerContext as k, EventLogger as l, TraceContext as m, Span as n, SpanKind as o, SpanStatus as p, SpanAttributeValue as q, SpanEvent as r, RpcTransport as s, EventTransport as t, CircuitBreakerConfig as u, RetryConfig as v, ServiceClientOptions as w, ServiceClient as x, ServiceInstance as y, QueryInput as z };

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@parsrun/service",
+  "version": "0.1.0",
+  "description": "Unified service layer for extracted microservices - RPC + Events",
+  "keywords": [
+    "pars",
+    "service",
+    "microservices",
+    "rpc",
+    "events",
+    "edge",
+    "cloudflare"
+  ],
+  "homepage": "https://pars.run",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parsrun/pars",
+    "directory": "packages/service"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc/index.d.ts",
+      "import": "./dist/rpc/index.js"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "import": "./dist/events/index.js"
+    },
+    "./resilience": {
+      "types": "./dist/resilience/index.d.ts",
+      "import": "./dist/resilience/index.js"
+    },
+    "./tracing": {
+      "types": "./dist/tracing/index.d.ts",
+      "import": "./dist/tracing/index.js"
+    },
+    "./serialization": {
+      "types": "./dist/serialization/index.d.ts",
+      "import": "./dist/serialization/index.js"
+    },
+    "./transports/cloudflare": {
+      "types": "./dist/transports/cloudflare/index.d.ts",
+      "import": "./dist/transports/cloudflare/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist node_modules"
+  },
+  "dependencies": {
+    "@parsrun/core": "workspace:*",
+    "@parsrun/types": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "arktype": "^2.0.0"
+  },
+  "peerDependencies": {
+    "arktype": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "arktype": {
+      "optional": true
+    }
+  }
+}