@orpc/shared 0.0.0-next.dd4e882 → 0.0.0-next.dd8de86

package/README.md

@@ -1,8 +1,3 @@
-> [!WARNING]
->
-> `@orpc/shared` is an internal dependency of oRPC packages. It does not follow semver and may change at any time without notice.
-> Please do not use it in your project.
-
 <div align="center">
   <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
 </div>
@@ -35,7 +30,8 @@
 - **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
 - **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
 - **📝 Contract-First Development**: Optionally define your API contract before implementation.
-- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte), Pinia Colada, and more.
+- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), Pinia Colada, and more.
 - **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
 - **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
 - **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
@@ -43,7 +39,6 @@
 - **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
 - **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
 - **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
-- **🛡️ Reliability**: Well-tested, TypeScript-based, production-ready, and MIT licensed.
 
 ## Documentation
 
@@ -54,14 +49,13 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
-- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with NestJS.
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
 - [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
-- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
-- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
-- [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
-- [@orpc/svelte-query](https://www.npmjs.com/package/@orpc/svelte-query): Integration with [Svelte Query](https://tanstack.com/query/latest/docs/framework/svelte/overview).
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
 - [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
-- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
 - [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
 - [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
 - [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Promisable } from 'type-fest';
-export { IsEqual, IsNever, PartialDeep, Promisable } from 'type-fest';
+export { IsEqual, IsNever, JsonValue, PartialDeep, Promisable } from 'type-fest';
+import { Tracer, TraceAPI, ContextAPI, PropagationAPI, SpanOptions, Context, Span, AttributeValue, Exception } from '@opentelemetry/api';
 export { group, guard, mapEntries, mapValues, omit } from 'radash';
 
 type MaybeOptionalOptions<TOptions> = Record<never, never> extends TOptions ? [options?: TOptions] : [options: TOptions];
@@ -8,6 +9,13 @@ declare function resolveMaybeOptionalOptions<T>(rest: MaybeOptionalOptions<T>):
 declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
 declare function splitInHalf<T>(arr: readonly T[]): [T[], T[]];
 
+/**
+ * Converts Request/Response/Blob/File/.. to a buffer (ArrayBuffer or Uint8Array).
+ *
+ * Prefers the newer `.bytes` method when available as it more efficient but not widely supported yet.
+ */
+declare function readAsBuffer(source: Pick<Blob, 'arrayBuffer' | 'bytes'>): Promise<ArrayBuffer | Uint8Array>;
+
 type AnyFunction = (...args: any[]) => any;
 declare function once<T extends () => any>(fn: T): () => ReturnType<T>;
 declare function sequential<A extends any[], R>(fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
@@ -20,6 +28,18 @@ type OmitChainMethodDeep<T extends object, K extends keyof any> = {
     [P in keyof Omit<T, K>]: T[P] extends AnyFunction ? ((...args: Parameters<T[P]>) => OmitChainMethodDeep<ReturnType<T[P]>, K>) : T[P];
 };
 
+declare const ORPC_NAME = "orpc";
+declare const ORPC_SHARED_PACKAGE_NAME = "@orpc/shared";
+declare const ORPC_SHARED_PACKAGE_VERSION = "0.0.0-next.dd8de86";
+
+/**
+ * Error thrown when an operation is aborted.
+ * Uses the standardized 'AbortError' name for consistency with JavaScript APIs.
+ */
+declare class AbortError extends Error {
+    constructor(...rest: ConstructorParameters<typeof Error>);
+}
+
 interface EventPublisherOptions {
     /**
      * Maximum number of events to buffer for async iterator subscribers.
@@ -80,8 +100,8 @@ declare class EventPublisher<T extends Record<PropertyKey, any>> {
 }
 
 declare class SequentialIdGenerator {
-    private nextId;
-    generate(): number;
+    private index;
+    generate(): string;
 }
 
 type SetOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
@@ -134,15 +154,108 @@ declare function onFinish<T, TOptions extends {
 }, TRest extends any[]>(callback: NoInfer<(state: OnFinishState<Awaited<ReturnType<TOptions['next']>>, ReturnType<TOptions['next']> extends PromiseWithError<any, infer E> ? E : ThrowableError>, options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
 declare function intercept<TOptions extends InterceptableOptions, TResult>(interceptors: Interceptor<TOptions, TResult>[], options: NoInfer<TOptions>, main: NoInfer<(options: TOptions) => TResult>): TResult;
 
+/**
+ * Only import types from @opentelemetry/api to avoid runtime dependencies.
+ */
+
+interface OtelConfig {
+    tracer: Tracer;
+    trace: TraceAPI;
+    context: ContextAPI;
+    propagation: PropagationAPI;
+}
+/**
+ * Sets the global OpenTelemetry config.
+ * Call this once at app startup. Use `undefined` to disable tracing.
+ */
+declare function setGlobalOtelConfig(config: OtelConfig | undefined): void;
+/**
+ * Gets the global OpenTelemetry config.
+ * Returns `undefined` if OpenTelemetry is not configured, initialized, or enabled.
+ */
+declare function getGlobalOtelConfig(): OtelConfig | undefined;
+/**
+ * Starts a new OpenTelemetry span with the given name and options.
+ *
+ * @returns The new span, or `undefined` if no tracer is set.
+ */
+declare function startSpan(name: string, options?: SpanOptions, context?: Context): Span | undefined;
+interface SetSpanErrorOptions {
+    /**
+     * Span error status is not set if error is due to cancellation by the signal.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Records and sets the error status on the given span.
+ * If the span is `undefined`, it does nothing.
+ */
+declare function setSpanError(span: Span | undefined, error: unknown, options?: SetSpanErrorOptions): void;
+declare function setSpanAttribute(span: Span | undefined, key: string, value: AttributeValue | undefined): void;
+/**
+ * Converts an error to an OpenTelemetry Exception.
+ */
+declare function toOtelException(error: unknown): Exclude<Exception, string>;
+/**
+ * Converts a value to a string suitable for OpenTelemetry span attributes.
+ */
+declare function toSpanAttributeValue(data: unknown): string;
+interface RunWithSpanOptions extends SpanOptions, SetSpanErrorOptions {
+    /**
+     * The name of the span to create.
+     */
+    name: string;
+    /**
+     * Context to use for the span.
+     */
+    context?: Context;
+}
+/**
+ * Runs a function within the context of a new OpenTelemetry span.
+ * The span is ended automatically, and errors are recorded to the span.
+ */
+declare function runWithSpan<T>({ name, context, ...options }: RunWithSpanOptions, fn: (span?: Span) => Promisable<T>): Promise<T>;
+/**
+ * Runs a function within the context of an existing OpenTelemetry span.
+ */
+declare function runInSpanContext<T>(span: Span | undefined, fn: () => Promisable<T>): Promise<T>;
+
 declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
-interface CreateAsyncIteratorObjectCleanupFn {
+interface AsyncIteratorClassNextFn<T, TReturn> {
+    (): Promise<IteratorResult<T, TReturn>>;
+}
+interface AsyncIteratorClassCleanupFn {
     (reason: 'return' | 'throw' | 'next' | 'dispose'): Promise<void>;
 }
-declare function createAsyncIteratorObject<T, TReturn, TNext>(next: () => Promise<IteratorResult<T, TReturn>>, cleanup: CreateAsyncIteratorObjectCleanupFn): AsyncIteratorObject<T, TReturn, TNext> & AsyncGenerator<T, TReturn, TNext>;
-declare function replicateAsyncIterator<T, TReturn, TNext>(source: AsyncIterator<T, TReturn, TNext>, count: number): (AsyncIteratorObject<T, TReturn, TNext> & AsyncGenerator<T, TReturn, TNext>)[];
+declare const fallbackAsyncDisposeSymbol: unique symbol;
+declare const asyncDisposeSymbol: typeof Symbol extends {
+    asyncDispose: infer T;
+} ? T : typeof fallbackAsyncDisposeSymbol;
+declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implements AsyncIteratorObject<T, TReturn, TNext>, AsyncGenerator<T, TReturn, TNext> {
+    #private;
+    constructor(next: AsyncIteratorClassNextFn<T, TReturn>, cleanup: AsyncIteratorClassCleanupFn);
+    next(): Promise<IteratorResult<T, TReturn>>;
+    return(value?: any): Promise<IteratorResult<T, TReturn>>;
+    throw(err: any): Promise<IteratorResult<T, TReturn>>;
+    /**
+     * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+     */
+    [asyncDisposeSymbol](): Promise<void>;
+    [Symbol.asyncIterator](): this;
+}
+declare function replicateAsyncIterator<T, TReturn, TNext>(source: AsyncIterator<T, TReturn, TNext>, count: number): (AsyncIteratorClass<T, TReturn, TNext>)[];
+interface AsyncIteratorWithSpanOptions extends SetSpanErrorOptions {
+    /**
+     * The name of the span to create.
+     */
+    name: string;
+}
+declare function asyncIteratorWithSpan<T, TReturn, TNext>({ name, ...options }: AsyncIteratorWithSpanOptions, iterator: AsyncIterator<T, TReturn, TNext>): AsyncIteratorClass<T, TReturn, TNext>;
 
 declare function parseEmptyableJSON(text: string | null | undefined): unknown;
-declare function stringifyJSON<T>(value: T): undefined extends T ? undefined | string : string;
+declare function stringifyJSON<T>(value: T | {
+    toJSON(): T;
+}): undefined extends T ? undefined | string : string;
 
 type Segment = string | number;
 declare function findDeepMatches(check: (value: unknown) => boolean, payload: unknown, segments?: Segment[], maps?: Segment[][], values?: unknown[]): {
@@ -158,14 +271,21 @@ declare function isObject(value: unknown): value is Record<PropertyKey, unknown>
  */
 declare function isTypescriptObject(value: unknown): value is object & Record<PropertyKey, unknown>;
 declare function clone<T>(value: T): T;
-declare function get(object: object, path: readonly string[]): unknown;
+declare function get(object: unknown, path: readonly string[]): unknown;
 declare function isPropertyKey(value: unknown): value is PropertyKey;
 declare const NullProtoObj: ({
     new <T extends Record<PropertyKey, unknown>>(): T;
 });
 
+/**
+ * Prevents objects from being awaitable by intercepting the `then` method
+ * when called by the native await mechanism. This is useful for preventing
+ * accidental awaiting of objects that aren't meant to be promises.
+ */
+declare function preventNativeAwait<T extends object>(target: T): T;
+
 interface AsyncIdQueueCloseOptions {
-    id?: number;
+    id?: string;
     reason?: unknown;
 }
 declare class AsyncIdQueue<T> {
@@ -173,16 +293,21 @@ declare class AsyncIdQueue<T> {
     private readonly items;
     private readonly pendingPulls;
     get length(): number;
-    open(id: number): void;
-    isOpen(id: number): boolean;
-    push(id: number, item: T): void;
-    pull(id: number): Promise<T>;
+    open(id: string): void;
+    isOpen(id: string): boolean;
+    push(id: string, item: T): void;
+    pull(id: string): Promise<T>;
     close({ id, reason }?: AsyncIdQueueCloseOptions): void;
-    assertOpen(id: number): void;
+    assertOpen(id: string): void;
 }
 
+declare function streamToAsyncIteratorClass<T>(stream: ReadableStream<T>): AsyncIteratorClass<T>;
+declare function asyncIteratorToStream<T>(iterator: AsyncIterator<T>): ReadableStream<T>;
+
+declare function tryDecodeURIComponent(value: string): string;
+
 type Value<T, TArgs extends any[] = []> = T | ((...args: TArgs) => T);
 declare function value<T, TArgs extends any[]>(value: Value<T, TArgs>, ...args: NoInfer<TArgs>): T extends Value<infer U, any> ? U : never;
 
-export { AsyncIdQueue, EventPublisher, NullProtoObj, SequentialIdGenerator, clone, createAsyncIteratorObject, defer, findDeepMatches, get, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, replicateAsyncIterator, resolveMaybeOptionalOptions, sequential, splitInHalf, stringifyJSON, toArray, value };
-export type { AnyFunction, AsyncIdQueueCloseOptions, CreateAsyncIteratorObjectCleanupFn, EventPublisherOptions, EventPublisherSubscribeIteratorOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OmitChainMethodDeep, OnFinishState, PromiseWithError, Registry, Segment, SetOptional, ThrowableError, Value };
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, EventPublisher, NullProtoObj, ORPC_NAME, ORPC_SHARED_PACKAGE_NAME, ORPC_SHARED_PACKAGE_VERSION, SequentialIdGenerator, asyncIteratorToStream, asyncIteratorWithSpan, clone, defer, findDeepMatches, get, getGlobalOtelConfig, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, preventNativeAwait, readAsBuffer, replicateAsyncIterator, resolveMaybeOptionalOptions, runInSpanContext, runWithSpan, sequential, setGlobalOtelConfig, setSpanAttribute, setSpanError, splitInHalf, startSpan, streamToAsyncIteratorClass, stringifyJSON, toArray, toOtelException, toSpanAttributeValue, tryDecodeURIComponent, value };
+export type { AnyFunction, AsyncIdQueueCloseOptions, AsyncIteratorClassCleanupFn, AsyncIteratorClassNextFn, AsyncIteratorWithSpanOptions, EventPublisherOptions, EventPublisherSubscribeIteratorOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OmitChainMethodDeep, OnFinishState, OtelConfig, PromiseWithError, Registry, RunWithSpanOptions, Segment, SetOptional, SetSpanErrorOptions, ThrowableError, Value };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Promisable } from 'type-fest';
-export { IsEqual, IsNever, PartialDeep, Promisable } from 'type-fest';
+export { IsEqual, IsNever, JsonValue, PartialDeep, Promisable } from 'type-fest';
+import { Tracer, TraceAPI, ContextAPI, PropagationAPI, SpanOptions, Context, Span, AttributeValue, Exception } from '@opentelemetry/api';
 export { group, guard, mapEntries, mapValues, omit } from 'radash';
 
 type MaybeOptionalOptions<TOptions> = Record<never, never> extends TOptions ? [options?: TOptions] : [options: TOptions];
@@ -8,6 +9,13 @@ declare function resolveMaybeOptionalOptions<T>(rest: MaybeOptionalOptions<T>):
 declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
 declare function splitInHalf<T>(arr: readonly T[]): [T[], T[]];
 
+/**
+ * Converts Request/Response/Blob/File/.. to a buffer (ArrayBuffer or Uint8Array).
+ *
+ * Prefers the newer `.bytes` method when available as it more efficient but not widely supported yet.
+ */
+declare function readAsBuffer(source: Pick<Blob, 'arrayBuffer' | 'bytes'>): Promise<ArrayBuffer | Uint8Array>;
+
 type AnyFunction = (...args: any[]) => any;
 declare function once<T extends () => any>(fn: T): () => ReturnType<T>;
 declare function sequential<A extends any[], R>(fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
@@ -20,6 +28,18 @@ type OmitChainMethodDeep<T extends object, K extends keyof any> = {
     [P in keyof Omit<T, K>]: T[P] extends AnyFunction ? ((...args: Parameters<T[P]>) => OmitChainMethodDeep<ReturnType<T[P]>, K>) : T[P];
 };
 
+declare const ORPC_NAME = "orpc";
+declare const ORPC_SHARED_PACKAGE_NAME = "@orpc/shared";
+declare const ORPC_SHARED_PACKAGE_VERSION = "0.0.0-next.dd8de86";
+
+/**
+ * Error thrown when an operation is aborted.
+ * Uses the standardized 'AbortError' name for consistency with JavaScript APIs.
+ */
+declare class AbortError extends Error {
+    constructor(...rest: ConstructorParameters<typeof Error>);
+}
+
 interface EventPublisherOptions {
     /**
      * Maximum number of events to buffer for async iterator subscribers.
@@ -80,8 +100,8 @@ declare class EventPublisher<T extends Record<PropertyKey, any>> {
 }
 
 declare class SequentialIdGenerator {
-    private nextId;
-    generate(): number;
+    private index;
+    generate(): string;
 }
 
 type SetOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
@@ -134,15 +154,108 @@ declare function onFinish<T, TOptions extends {
 }, TRest extends any[]>(callback: NoInfer<(state: OnFinishState<Awaited<ReturnType<TOptions['next']>>, ReturnType<TOptions['next']> extends PromiseWithError<any, infer E> ? E : ThrowableError>, options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
 declare function intercept<TOptions extends InterceptableOptions, TResult>(interceptors: Interceptor<TOptions, TResult>[], options: NoInfer<TOptions>, main: NoInfer<(options: TOptions) => TResult>): TResult;
 
+/**
+ * Only import types from @opentelemetry/api to avoid runtime dependencies.
+ */
+
+interface OtelConfig {
+    tracer: Tracer;
+    trace: TraceAPI;
+    context: ContextAPI;
+    propagation: PropagationAPI;
+}
+/**
+ * Sets the global OpenTelemetry config.
+ * Call this once at app startup. Use `undefined` to disable tracing.
+ */
+declare function setGlobalOtelConfig(config: OtelConfig | undefined): void;
+/**
+ * Gets the global OpenTelemetry config.
+ * Returns `undefined` if OpenTelemetry is not configured, initialized, or enabled.
+ */
+declare function getGlobalOtelConfig(): OtelConfig | undefined;
+/**
+ * Starts a new OpenTelemetry span with the given name and options.
+ *
+ * @returns The new span, or `undefined` if no tracer is set.
+ */
+declare function startSpan(name: string, options?: SpanOptions, context?: Context): Span | undefined;
+interface SetSpanErrorOptions {
+    /**
+     * Span error status is not set if error is due to cancellation by the signal.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Records and sets the error status on the given span.
+ * If the span is `undefined`, it does nothing.
+ */
+declare function setSpanError(span: Span | undefined, error: unknown, options?: SetSpanErrorOptions): void;
+declare function setSpanAttribute(span: Span | undefined, key: string, value: AttributeValue | undefined): void;
+/**
+ * Converts an error to an OpenTelemetry Exception.
+ */
+declare function toOtelException(error: unknown): Exclude<Exception, string>;
+/**
+ * Converts a value to a string suitable for OpenTelemetry span attributes.
+ */
+declare function toSpanAttributeValue(data: unknown): string;
+interface RunWithSpanOptions extends SpanOptions, SetSpanErrorOptions {
+    /**
+     * The name of the span to create.
+     */
+    name: string;
+    /**
+     * Context to use for the span.
+     */
+    context?: Context;
+}
+/**
+ * Runs a function within the context of a new OpenTelemetry span.
+ * The span is ended automatically, and errors are recorded to the span.
+ */
+declare function runWithSpan<T>({ name, context, ...options }: RunWithSpanOptions, fn: (span?: Span) => Promisable<T>): Promise<T>;
+/**
+ * Runs a function within the context of an existing OpenTelemetry span.
+ */
+declare function runInSpanContext<T>(span: Span | undefined, fn: () => Promisable<T>): Promise<T>;
+
 declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
-interface CreateAsyncIteratorObjectCleanupFn {
+interface AsyncIteratorClassNextFn<T, TReturn> {
+    (): Promise<IteratorResult<T, TReturn>>;
+}
+interface AsyncIteratorClassCleanupFn {
     (reason: 'return' | 'throw' | 'next' | 'dispose'): Promise<void>;
 }
-declare function createAsyncIteratorObject<T, TReturn, TNext>(next: () => Promise<IteratorResult<T, TReturn>>, cleanup: CreateAsyncIteratorObjectCleanupFn): AsyncIteratorObject<T, TReturn, TNext> & AsyncGenerator<T, TReturn, TNext>;
-declare function replicateAsyncIterator<T, TReturn, TNext>(source: AsyncIterator<T, TReturn, TNext>, count: number): (AsyncIteratorObject<T, TReturn, TNext> & AsyncGenerator<T, TReturn, TNext>)[];
+declare const fallbackAsyncDisposeSymbol: unique symbol;
+declare const asyncDisposeSymbol: typeof Symbol extends {
+    asyncDispose: infer T;
+} ? T : typeof fallbackAsyncDisposeSymbol;
+declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implements AsyncIteratorObject<T, TReturn, TNext>, AsyncGenerator<T, TReturn, TNext> {
+    #private;
+    constructor(next: AsyncIteratorClassNextFn<T, TReturn>, cleanup: AsyncIteratorClassCleanupFn);
+    next(): Promise<IteratorResult<T, TReturn>>;
+    return(value?: any): Promise<IteratorResult<T, TReturn>>;
+    throw(err: any): Promise<IteratorResult<T, TReturn>>;
+    /**
+     * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+     */
+    [asyncDisposeSymbol](): Promise<void>;
+    [Symbol.asyncIterator](): this;
+}
+declare function replicateAsyncIterator<T, TReturn, TNext>(source: AsyncIterator<T, TReturn, TNext>, count: number): (AsyncIteratorClass<T, TReturn, TNext>)[];
+interface AsyncIteratorWithSpanOptions extends SetSpanErrorOptions {
+    /**
+     * The name of the span to create.
+     */
+    name: string;
+}
+declare function asyncIteratorWithSpan<T, TReturn, TNext>({ name, ...options }: AsyncIteratorWithSpanOptions, iterator: AsyncIterator<T, TReturn, TNext>): AsyncIteratorClass<T, TReturn, TNext>;
 
 declare function parseEmptyableJSON(text: string | null | undefined): unknown;
-declare function stringifyJSON<T>(value: T): undefined extends T ? undefined | string : string;
+declare function stringifyJSON<T>(value: T | {
+    toJSON(): T;
+}): undefined extends T ? undefined | string : string;
 
 type Segment = string | number;
 declare function findDeepMatches(check: (value: unknown) => boolean, payload: unknown, segments?: Segment[], maps?: Segment[][], values?: unknown[]): {
@@ -158,14 +271,21 @@ declare function isObject(value: unknown): value is Record<PropertyKey, unknown>
  */
 declare function isTypescriptObject(value: unknown): value is object & Record<PropertyKey, unknown>;
 declare function clone<T>(value: T): T;
-declare function get(object: object, path: readonly string[]): unknown;
+declare function get(object: unknown, path: readonly string[]): unknown;
 declare function isPropertyKey(value: unknown): value is PropertyKey;
 declare const NullProtoObj: ({
     new <T extends Record<PropertyKey, unknown>>(): T;
 });
 
+/**
+ * Prevents objects from being awaitable by intercepting the `then` method
+ * when called by the native await mechanism. This is useful for preventing
+ * accidental awaiting of objects that aren't meant to be promises.
+ */
+declare function preventNativeAwait<T extends object>(target: T): T;
+
 interface AsyncIdQueueCloseOptions {
-    id?: number;
+    id?: string;
     reason?: unknown;
 }
 declare class AsyncIdQueue<T> {
@@ -173,16 +293,21 @@ declare class AsyncIdQueue<T> {
     private readonly items;
     private readonly pendingPulls;
     get length(): number;
-    open(id: number): void;
-    isOpen(id: number): boolean;
-    push(id: number, item: T): void;
-    pull(id: number): Promise<T>;
+    open(id: string): void;
+    isOpen(id: string): boolean;
+    push(id: string, item: T): void;
+    pull(id: string): Promise<T>;
     close({ id, reason }?: AsyncIdQueueCloseOptions): void;
-    assertOpen(id: number): void;
+    assertOpen(id: string): void;
 }
 
+declare function streamToAsyncIteratorClass<T>(stream: ReadableStream<T>): AsyncIteratorClass<T>;
+declare function asyncIteratorToStream<T>(iterator: AsyncIterator<T>): ReadableStream<T>;
+
+declare function tryDecodeURIComponent(value: string): string;
+
 type Value<T, TArgs extends any[] = []> = T | ((...args: TArgs) => T);
 declare function value<T, TArgs extends any[]>(value: Value<T, TArgs>, ...args: NoInfer<TArgs>): T extends Value<infer U, any> ? U : never;
 
-export { AsyncIdQueue, EventPublisher, NullProtoObj, SequentialIdGenerator, clone, createAsyncIteratorObject, defer, findDeepMatches, get, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, replicateAsyncIterator, resolveMaybeOptionalOptions, sequential, splitInHalf, stringifyJSON, toArray, value };
-export type { AnyFunction, AsyncIdQueueCloseOptions, CreateAsyncIteratorObjectCleanupFn, EventPublisherOptions, EventPublisherSubscribeIteratorOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OmitChainMethodDeep, OnFinishState, PromiseWithError, Registry, Segment, SetOptional, ThrowableError, Value };
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, EventPublisher, NullProtoObj, ORPC_NAME, ORPC_SHARED_PACKAGE_NAME, ORPC_SHARED_PACKAGE_VERSION, SequentialIdGenerator, asyncIteratorToStream, asyncIteratorWithSpan, clone, defer, findDeepMatches, get, getGlobalOtelConfig, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, preventNativeAwait, readAsBuffer, replicateAsyncIterator, resolveMaybeOptionalOptions, runInSpanContext, runWithSpan, sequential, setGlobalOtelConfig, setSpanAttribute, setSpanError, splitInHalf, startSpan, streamToAsyncIteratorClass, stringifyJSON, toArray, toOtelException, toSpanAttributeValue, tryDecodeURIComponent, value };
+export type { AnyFunction, AsyncIdQueueCloseOptions, AsyncIteratorClassCleanupFn, AsyncIteratorClassNextFn, AsyncIteratorWithSpanOptions, EventPublisherOptions, EventPublisherSubscribeIteratorOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OmitChainMethodDeep, OnFinishState, OtelConfig, PromiseWithError, Registry, RunWithSpanOptions, Segment, SetOptional, SetSpanErrorOptions, ThrowableError, Value };

package/dist/index.mjs

@@ -12,6 +12,24 @@ function splitInHalf(arr) {
   return [arr.slice(0, half), arr.slice(half)];
 }
 
+function readAsBuffer(source) {
+  if (typeof source.bytes === "function") {
+    return source.bytes();
+  }
+  return source.arrayBuffer();
+}
+
+const ORPC_NAME = "orpc";
+const ORPC_SHARED_PACKAGE_NAME = "@orpc/shared";
+const ORPC_SHARED_PACKAGE_VERSION = "0.0.0-next.dd8de86";
+
+class AbortError extends Error {
+  constructor(...rest) {
+    super(...rest);
+    this.name = "AbortError";
+  }
+}
+
 function once(fn) {
   let cached;
   return () => {
@@ -40,6 +58,99 @@ function defer(callback) {
   }
 }
 
+const SPAN_ERROR_STATUS = 2;
+const GLOBAL_OTEL_CONFIG_KEY = `__${ORPC_SHARED_PACKAGE_NAME}@${ORPC_SHARED_PACKAGE_VERSION}/otel/config__`;
+function setGlobalOtelConfig(config) {
+  globalThis[GLOBAL_OTEL_CONFIG_KEY] = config;
+}
+function getGlobalOtelConfig() {
+  return globalThis[GLOBAL_OTEL_CONFIG_KEY];
+}
+function startSpan(name, options = {}, context) {
+  const tracer = getGlobalOtelConfig()?.tracer;
+  return tracer?.startSpan(name, options, context);
+}
+function setSpanError(span, error, options = {}) {
+  if (!span) {
+    return;
+  }
+  const exception = toOtelException(error);
+  span.recordException(exception);
+  if (!options.signal?.aborted || options.signal.reason !== error) {
+    span.setStatus({
+      code: SPAN_ERROR_STATUS,
+      message: exception.message
+    });
+  }
+}
+function setSpanAttribute(span, key, value) {
+  if (!span || value === void 0) {
+    return;
+  }
+  span.setAttribute(key, value);
+}
+function toOtelException(error) {
+  if (error instanceof Error) {
+    const exception = {
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    };
+    if ("code" in error && (typeof error.code === "string" || typeof error.code === "number")) {
+      exception.code = error.code;
+    }
+    return exception;
+  }
+  return { message: String(error) };
+}
+function toSpanAttributeValue(data) {
+  if (data === void 0) {
+    return "undefined";
+  }
+  try {
+    return JSON.stringify(data, (_, value) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      if (value instanceof Map || value instanceof Set) {
+        return Array.from(value);
+      }
+      return value;
+    });
+  } catch {
+    return String(data);
+  }
+}
+async function runWithSpan({ name, context, ...options }, fn) {
+  const tracer = getGlobalOtelConfig()?.tracer;
+  if (!tracer) {
+    return fn();
+  }
+  const callback = async (span) => {
+    try {
+      return await fn(span);
+    } catch (e) {
+      setSpanError(span, e, options);
+      throw e;
+    } finally {
+      span.end();
+    }
+  };
+  if (context) {
+    return tracer.startActiveSpan(name, options, context, callback);
+  } else {
+    return tracer.startActiveSpan(name, options, callback);
+  }
+}
+async function runInSpanContext(span, fn) {
+  const otelConfig = getGlobalOtelConfig();
+  if (!span || !otelConfig) {
+    return fn();
+  }
+  const ctx = otelConfig.trace.setSpan(otelConfig.context.active(), span);
+  return otelConfig.context.with(ctx, fn);
+}
+
 class AsyncIdQueue {
   openIds = /* @__PURE__ */ new Set();
   items = /* @__PURE__ */ new Map();
@@ -120,63 +231,70 @@ function isAsyncIteratorObject(maybe) {
   if (!maybe || typeof maybe !== "object") {
     return false;
   }
-  return Symbol.asyncIterator in maybe && typeof maybe[Symbol.asyncIterator] === "function";
+  return "next" in maybe && typeof maybe.next === "function" && Symbol.asyncIterator in maybe && typeof maybe[Symbol.asyncIterator] === "function";
 }
-function createAsyncIteratorObject(next, cleanup) {
-  let isExecuteComplete = false;
-  let isDone = false;
-  const iterator = {
-    next: sequential(async () => {
-      if (isDone) {
+const fallbackAsyncDisposeSymbol = Symbol.for("asyncDispose");
+const asyncDisposeSymbol = Symbol.asyncDispose ?? fallbackAsyncDisposeSymbol;
+class AsyncIteratorClass {
+  #isDone = false;
+  #isExecuteComplete = false;
+  #cleanup;
+  #next;
+  constructor(next, cleanup) {
+    this.#cleanup = cleanup;
+    this.#next = sequential(async () => {
+      if (this.#isDone) {
         return { done: true, value: void 0 };
       }
       try {
         const result = await next();
         if (result.done) {
-          isDone = true;
+          this.#isDone = true;
         }
         return result;
       } catch (err) {
-        isDone = true;
+        this.#isDone = true;
         throw err;
       } finally {
-        if (isDone && !isExecuteComplete) {
-          isExecuteComplete = true;
-          await cleanup("next");
+        if (this.#isDone && !this.#isExecuteComplete) {
+          this.#isExecuteComplete = true;
+          await this.#cleanup("next");
         }
       }
-    }),
-    async return(value) {
-      isDone = true;
-      if (!isExecuteComplete) {
-        isExecuteComplete = true;
-        await cleanup("return");
-      }
-      return { done: true, value };
-    },
-    async throw(err) {
-      isDone = true;
-      if (!isExecuteComplete) {
-        isExecuteComplete = true;
-        await cleanup("throw");
-      }
-      throw err;
-    },
-    /**
-     * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
-     */
-    async [Symbol.asyncDispose ?? Symbol.for("asyncDispose")]() {
-      isDone = true;
-      if (!isExecuteComplete) {
-        isExecuteComplete = true;
-        await cleanup("dispose");
-      }
-    },
-    [Symbol.asyncIterator]() {
-      return iterator;
+    });
+  }
+  next() {
+    return this.#next();
+  }
+  async return(value) {
+    this.#isDone = true;
+    if (!this.#isExecuteComplete) {
+      this.#isExecuteComplete = true;
+      await this.#cleanup("return");
     }
-  };
-  return iterator;
+    return { done: true, value };
+  }
+  async throw(err) {
+    this.#isDone = true;
+    if (!this.#isExecuteComplete) {
+      this.#isExecuteComplete = true;
+      await this.#cleanup("throw");
+    }
+    throw err;
+  }
+  /**
+   * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+   */
+  async [asyncDisposeSymbol]() {
+    this.#isDone = true;
+    if (!this.#isExecuteComplete) {
+      this.#isExecuteComplete = true;
+      await this.#cleanup("dispose");
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
 }
 function replicateAsyncIterator(source, count) {
   const queue = new AsyncIdQueue();
@@ -187,8 +305,8 @@ function replicateAsyncIterator(source, count) {
       while (true) {
         const item = await source.next();
         for (let id = 0; id < count; id++) {
-          if (queue.isOpen(id)) {
-            queue.push(id, item);
+          if (queue.isOpen(id.toString())) {
+            queue.push(id.toString(), item);
           }
         }
         if (item.done) {
@@ -200,12 +318,12 @@ function replicateAsyncIterator(source, count) {
     }
   });
   for (let id = 0; id < count; id++) {
-    queue.open(id);
-    replicated.push(createAsyncIteratorObject(
+    queue.open(id.toString());
+    replicated.push(new AsyncIteratorClass(
       () => {
         start();
         return new Promise((resolve, reject) => {
-          queue.pull(id).then(resolve).catch(reject);
+          queue.pull(id.toString()).then(resolve).catch(reject);
           defer(() => {
             if (error) {
               reject(error.value);
@@ -214,9 +332,9 @@ function replicateAsyncIterator(source, count) {
         });
       },
       async (reason) => {
-        queue.close({ id });
+        queue.close({ id: id.toString() });
         if (reason !== "next") {
-          if (replicated.every((_, id2) => !queue.isOpen(id2))) {
+          if (replicated.every((_, id2) => !queue.isOpen(id2.toString()))) {
             await source?.return?.();
           }
         }
@@ -225,6 +343,34 @@ function replicateAsyncIterator(source, count) {
   }
   return replicated;
 }
+function asyncIteratorWithSpan({ name, ...options }, iterator) {
+  let span;
+  return new AsyncIteratorClass(
+    async () => {
+      span ??= startSpan(name);
+      try {
+        const result = await runInSpanContext(span, () => iterator.next());
+        span?.addEvent(result.done ? "completed" : "yielded");
+        return result;
+      } catch (err) {
+        setSpanError(span, err, options);
+        throw err;
+      }
+    },
+    async (reason) => {
+      try {
+        if (reason !== "next") {
+          await runInSpanContext(span, () => iterator.return?.());
+        }
+      } catch (err) {
+        setSpanError(span, err, options);
+        throw err;
+      } finally {
+        span?.end();
+      }
+    }
+  );
+}
 
 class EventPublisher {
   #listenersMap = /* @__PURE__ */ new Map();
@@ -263,6 +409,7 @@ class EventPublisher {
     }
     const signal = listenerOrOptions?.signal;
     const maxBufferedEvents = listenerOrOptions?.maxBufferedEvents ?? this.#maxBufferedEvents;
+    signal?.throwIfAborted();
     const bufferedEvents = [];
     const pullResolvers = [];
     const unsubscribe = this.subscribe(event, (payload) => {
@@ -283,7 +430,7 @@ class EventPublisher {
       bufferedEvents.length = 0;
     };
     signal?.addEventListener("abort", abortListener, { once: true });
-    return createAsyncIteratorObject(async () => {
+    return new AsyncIteratorClass(async () => {
       if (signal?.aborted) {
         throw signal.reason;
       }
@@ -304,13 +451,11 @@ class EventPublisher {
 }
 
 class SequentialIdGenerator {
-  nextId = 0;
+  index = BigInt(0);
   generate() {
-    if (this.nextId === Number.MAX_SAFE_INTEGER) {
-      this.nextId = 0;
-      return Number.MAX_SAFE_INTEGER;
-    }
-    return this.nextId++;
+    const id = this.index.toString(32);
+    this.index++;
+    return id;
   }
 }
 
@@ -436,6 +581,73 @@ const NullProtoObj = /* @__PURE__ */ (() => {
   return e;
 })();
 
+function preventNativeAwait(target) {
+  return new Proxy(target, {
+    get(target2, prop, receiver) {
+      const value = Reflect.get(target2, prop, receiver);
+      if (prop !== "then" || typeof value !== "function") {
+        return value;
+      }
+      return new Proxy(value, {
+        apply(targetFn, thisArg, args) {
+          if (args.length !== 2 || args.some((arg) => !isNativeFunction(arg))) {
+            return Reflect.apply(targetFn, thisArg, args);
+          }
+          let shouldOmit = true;
+          args[0].call(thisArg, preventNativeAwait(new Proxy(target2, {
+            get: (target3, prop2, receiver2) => {
+              if (shouldOmit && prop2 === "then") {
+                shouldOmit = false;
+                return void 0;
+              }
+              return Reflect.get(target3, prop2, receiver2);
+            }
+          })));
+        }
+      });
+    }
+  });
+}
+const NATIVE_FUNCTION_REGEX = /^\s*function\s*\(\)\s*\{\s*\[native code\]\s*\}\s*$/;
+function isNativeFunction(fn) {
+  return typeof fn === "function" && NATIVE_FUNCTION_REGEX.test(fn.toString());
+}
+
+function streamToAsyncIteratorClass(stream) {
+  const reader = stream.getReader();
+  return new AsyncIteratorClass(
+    async () => {
+      return reader.read();
+    },
+    async () => {
+      await reader.cancel();
+    }
+  );
+}
+function asyncIteratorToStream(iterator) {
+  return new ReadableStream({
+    async pull(controller) {
+      const { done, value } = await iterator.next();
+      if (done) {
+        controller.close();
+      } else {
+        controller.enqueue(value);
+      }
+    },
+    async cancel() {
+      await iterator.return?.();
+    }
+  });
+}
+
+function tryDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
 function value(value2, ...args) {
   if (typeof value2 === "function") {
     return value2(...args);
@@ -443,4 +655,4 @@ function value(value2, ...args) {
   return value2;
 }
 
-export { AsyncIdQueue, EventPublisher, NullProtoObj, SequentialIdGenerator, clone, createAsyncIteratorObject, defer, findDeepMatches, get, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, replicateAsyncIterator, resolveMaybeOptionalOptions, sequential, splitInHalf, stringifyJSON, toArray, value };
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, EventPublisher, NullProtoObj, ORPC_NAME, ORPC_SHARED_PACKAGE_NAME, ORPC_SHARED_PACKAGE_VERSION, SequentialIdGenerator, asyncIteratorToStream, asyncIteratorWithSpan, clone, defer, findDeepMatches, get, getGlobalOtelConfig, intercept, isAsyncIteratorObject, isObject, isPropertyKey, isTypescriptObject, onError, onFinish, onStart, onSuccess, once, parseEmptyableJSON, preventNativeAwait, readAsBuffer, replicateAsyncIterator, resolveMaybeOptionalOptions, runInSpanContext, runWithSpan, sequential, setGlobalOtelConfig, setSpanAttribute, setSpanError, splitInHalf, startSpan, streamToAsyncIteratorClass, stringifyJSON, toArray, toOtelException, toSpanAttributeValue, tryDecodeURIComponent, value };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/shared",
   "type": "module",
-  "version": "0.0.0-next.dd4e882",
+  "version": "0.0.0-next.dd8de86",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -23,14 +23,23 @@
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "radash": "^12.1.0",
+    "radash": "^12.1.1",
     "type-fest": "^4.39.1"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "arktype": "2.1.20",
     "valibot": "^1.1.0",
-    "zod": "^3.25.49"
+    "zod": "^4.0.17"
   },
   "scripts": {
     "build": "unbuild",