@irpclib/irpc 1.0.0-beta.20 → 1.0.0-beta.21

package/dist/call.d.ts

@@ -1,16 +1,18 @@
-import { IRPCPayload, IRPCStatus } from "./types.js";
+import { IRPCTransport } from "./transport.js";
+import { IRPCCallConfig, IRPCData, IRPCPacketStream, IRPCPayload, IRPCStatus } from "./types.js";
+import { IRPCReader } from "./reader.js";
 
 //#region src/call.d.ts
-
+declare const DEFAULT_RETRY_MODE = "exponential";
+declare const DEFAULT_RETRY_DELAY = 1000;
 /**
  * Represents an RPC call with promise-like behavior for handling asynchronous operations.
  * Each call has a unique identifier and manages its own resolution state.
  */
 declare class IRPCCall {
+  transport: IRPCTransport;
   payload: IRPCPayload;
-  private resolver;
-  private rejector;
-  timeout?: number | undefined;
+  options: IRPCCallConfig;
   /**
    * Unique identifier for this RPC call, generated using shortId().
    */
@@ -37,26 +39,31 @@ declare class IRPCCall {
    */
   value?: unknown;
   error?: Error;
+  private readonly timerId?;
+  private retries;
+  private retryReasons;
+  reader: IRPCReader<IRPCData>;
   /**
    * Creates a new IRPCCall instance.
+   * @param transport
    * @param payload - The RPC payload containing method and parameters
-   * @param resolver - Function to resolve the associated promise with a value
-   * @param rejector - Function to reject the associated promise with an error
-   * @param timeout - Optional timeout value in milliseconds
+   * @param options - Options for the call, such as timeout, maxRetries, etc.
    */
-  constructor(payload: IRPCPayload, resolver: (value: unknown) => void, rejector: (reason?: Error) => void, timeout?: number | undefined);
+  constructor(transport: IRPCTransport, payload: IRPCPayload, options: IRPCCallConfig);
+  enqueue(packet: IRPCPacketStream<IRPCData>): void;
   /**
    * Resolves the RPC call with the provided value.
    * If the call is already resolved, this method does nothing.
    * @param value - The value to resolve the promise with
    */
-  resolve(value: unknown): void;
+  resolve(value: IRPCData): void;
   /**
    * Rejects the RPC call with the provided reason.
    * If the call is already resolved, this method does nothing.
    * @param reason - Optional error reason for rejecting the promise
+   * @param retriable - Flag indicating whether to retry the call
    */
-  reject(reason?: Error): void;
+  reject(reason?: Error, retriable?: boolean): void;
 }
 //#endregion
-export { IRPCCall };
+export { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, IRPCCall };

package/dist/call.js

@@ -1,7 +1,11 @@
-import { IRPC_STATUS } from "./enum.js";
+import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
+import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { IRPCReader } from "./reader.js";
 import { uuid } from "./uuid.js";
 
 //#region src/call.ts
+const DEFAULT_RETRY_MODE = "exponential";
+const DEFAULT_RETRY_DELAY = 1e3;
 /**
 * Represents an RPC call with promise-like behavior for handling asynchronous operations.
 * Each call has a unique identifier and manages its own resolution state.
@@ -33,18 +37,40 @@ var IRPCCall = class {
 	*/
 	value;
 	error;
+	timerId;
+	retries = 0;
+	retryReasons = /* @__PURE__ */ new Set();
+	reader;
 	/**
 	* Creates a new IRPCCall instance.
+	* @param transport
 	* @param payload - The RPC payload containing method and parameters
-	* @param resolver - Function to resolve the associated promise with a value
-	* @param rejector - Function to reject the associated promise with an error
-	* @param timeout - Optional timeout value in milliseconds
+	* @param options - Options for the call, such as timeout, maxRetries, etc.
 	*/
-	constructor(payload, resolver, rejector, timeout) {
+	constructor(transport, payload, options) {
+		this.transport = transport;
 		this.payload = payload;
-		this.resolver = resolver;
-		this.rejector = rejector;
-		this.timeout = timeout;
+		this.options = options;
+		if (options.timeout) this.timerId = setTimeout(() => {
+			this.reader.push({
+				id: this.id,
+				name: this.payload.name,
+				type: IRPC_PACKET_TYPE.CLOSE,
+				status: IRPC_STATUS.ERROR,
+				error: {
+					code: ERROR_CODE.TIMEOUT,
+					message: ERROR_MESSAGE[ERROR_CODE.TIMEOUT]
+				},
+				createdAt: Date.now()
+			});
+			this.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TIMEOUT]), false);
+		}, options.timeout);
+		this.reader = new IRPCReader(this.id);
+	}
+	enqueue(packet) {
+		this.reader.push(packet);
+		if (this.reader.status === IRPC_STATUS.SUCCESS) this.resolve(this.reader.data);
+		else if (this.reader.status === IRPC_STATUS.ERROR) this.reject(this.reader.error);
 	}
 	/**
 	* Resolves the RPC call with the provided value.
@@ -57,22 +83,38 @@ var IRPCCall = class {
 		this.status = IRPC_STATUS.SUCCESS;
 		this.resolved = true;
 		this.finishedAt = Date.now();
-		this.resolver(value);
+		clearTimeout(this.timerId);
 	}
 	/**
 	* Rejects the RPC call with the provided reason.
 	* If the call is already resolved, this method does nothing.
 	* @param reason - Optional error reason for rejecting the promise
+	* @param retriable - Flag indicating whether to retry the call
 	*/
-	reject(reason) {
+	reject(reason, retriable = true) {
 		if (this.resolved) return;
-		this.error = reason;
-		this.status = IRPC_STATUS.ERROR;
-		this.resolved = true;
-		this.finishedAt = Date.now();
-		this.rejector(reason);
+		const { maxRetries, retryMode = DEFAULT_RETRY_MODE, retryDelay = DEFAULT_RETRY_DELAY } = this.options;
+		if (maxRetries && retriable) {
+			if (reason) this.retryReasons.add(reason);
+			if (this.retries >= maxRetries) {
+				console.error(ERROR_MESSAGE[ERROR_CODE.CALL_MAX_RETRIES_REACHED], this.retryReasons);
+				this.reject(reason, false);
+				return;
+			}
+			const delay = retryMode === "linear" ? retryDelay : retryDelay * 2 ** this.retries;
+			setTimeout(() => {
+				this.retries++;
+				this.transport.schedule(this);
+			}, delay);
+		} else {
+			this.error = reason;
+			this.status = IRPC_STATUS.ERROR;
+			this.resolved = true;
+			this.finishedAt = Date.now();
+			clearTimeout(this.timerId);
+		}
 	}
 };
 
 //#endregion
-export { IRPCCall };
+export { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, IRPCCall };

package/dist/enum.d.ts

@@ -2,6 +2,7 @@
 declare const IRPC_PACKET_TYPE: {
   readonly CALL: "call";
   readonly EVENT: "event";
+  readonly CLOSE: "close";
   readonly ANSWER: "answer";
   readonly REQUEST: "request";
   readonly RESPONSE: "response";

package/dist/enum.js

@@ -2,6 +2,7 @@
 const IRPC_PACKET_TYPE = {
 	CALL: "call",
 	EVENT: "event",
+	CLOSE: "close",
 	ANSWER: "answer",
 	REQUEST: "request",
 	RESPONSE: "response"

package/dist/error.d.ts

@@ -22,6 +22,8 @@ declare const ERROR_CODE: {
   RESOLVER_NOT_IMPLEMENTED: string;
   RESOLVER_NOT_FOUND: string;
   RESOLVER_NOT_SUPPORTED: string;
+  STREAM_ERROR: string;
+  CALL_MAX_RETRIES_REACHED: string;
 };
 type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
 declare const ERROR_MESSAGE: {
@@ -41,10 +43,13 @@ declare const ERROR_MESSAGE: {
   [ERROR_CODE.TRANSPORT_INVALID]: string;
   [ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]: string;
   [ERROR_CODE.STUB_INVALID]: string;
+  [ERROR_CODE.STREAM_ERROR]: string;
   [ERROR_CODE.STUB_NOT_IMPLEMENTED]: string;
   [ERROR_CODE.RESOLVER_MISSING]: string;
   [ERROR_CODE.RESOLVER_NOT_IMPLEMENTED]: string;
   [ERROR_CODE.RESOLVER_NOT_FOUND]: string;
+  [ERROR_CODE.RESOLVER_NOT_SUPPORTED]: string;
+  [ERROR_CODE.CALL_MAX_RETRIES_REACHED]: string;
 };
 //#endregion
 export { ERROR_CODE, ERROR_MESSAGE, ErrorCode };

package/dist/error.js

@@ -21,7 +21,9 @@ const ERROR_CODE = {
 	RESOLVER_MISSING: "resolver_missing",
 	RESOLVER_NOT_IMPLEMENTED: "resolver_not_implemented",
 	RESOLVER_NOT_FOUND: "resolver_not_found",
-	RESOLVER_NOT_SUPPORTED: "resolver_not_supported"
+	RESOLVER_NOT_SUPPORTED: "resolver_not_supported",
+	STREAM_ERROR: "stream_error",
+	CALL_MAX_RETRIES_REACHED: "call_max_retries_reached"
 };
 const ERROR_MESSAGE = {
 	[ERROR_CODE.UNKNOWN]: "IRPC: Unknown error",
@@ -40,10 +42,13 @@ const ERROR_MESSAGE = {
 	[ERROR_CODE.TRANSPORT_INVALID]: "IRPC: Transport invalid error",
 	[ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]: "IRPC: Transport not implemented error",
 	[ERROR_CODE.STUB_INVALID]: "IRPC: Stub invalid error",
+	[ERROR_CODE.STREAM_ERROR]: "IRPC: Stream error",
 	[ERROR_CODE.STUB_NOT_IMPLEMENTED]: "IRPC: Stub not implemented error",
 	[ERROR_CODE.RESOLVER_MISSING]: "IRPC: Resolver missing error",
 	[ERROR_CODE.RESOLVER_NOT_IMPLEMENTED]: "IRPC: Resolver not implemented error",
-	[ERROR_CODE.RESOLVER_NOT_FOUND]: "IRPC: Resolver not found error"
+	[ERROR_CODE.RESOLVER_NOT_FOUND]: "IRPC: Resolver not found error",
+	[ERROR_CODE.RESOLVER_NOT_SUPPORTED]: "IRPC: Resolver not supported error",
+	[ERROR_CODE.CALL_MAX_RETRIES_REACHED]: "IRPC: Call max retries reached error"
 };
 
 //#endregion

package/dist/index.d.ts

@@ -2,9 +2,12 @@ import { IRPCCacheEntry, IRPCCacher } from "./cache.js";
 import { IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
 import { ERROR_CODE, ERROR_MESSAGE, ErrorCode } from "./error.js";
 import { IRPCTransport } from "./transport.js";
-import { IRPCArraySchema, IRPCCache, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCError, IRPCEventType, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCPacket, IRPCPacketAnswer, IRPCPacketCall, IRPCPacketData, IRPCPacketEvent, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStubStore, TransportConfig } from "./types.js";
-import { IRPCCall } from "./call.js";
+import { IRPCArraySchema, IRPCCallConfig, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCDeclareInit, IRPCError, IRPCEventType, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCPacketAnswer, IRPCPacketBase, IRPCPacketCall, IRPCPacketClose, IRPCPacketData, IRPCPacketEvent, IRPCPacketStream, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCRequest, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStubStore, TransportConfig } from "./types.js";
+import { RemoteState, StreamConstructor, stream } from "./state.js";
+import { IRPCReader } from "./reader.js";
+import { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, IRPCCall } from "./call.js";
 import { createContext, getContext, setContext, setContextProvider, withContext } from "./context.js";
 import { IRPCPackage, createPackage } from "./module.js";
 import { IRPCResolver } from "./resolver.js";
-export { ERROR_CODE, ERROR_MESSAGE, ErrorCode, IRPCArraySchema, IRPCCache, IRPCCacheEntry, IRPCCacher, IRPCCall, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCError, IRPCEventType, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackage, IRPCPackageConfig, IRPCPackageInfo, IRPCPacket, IRPCPacketAnswer, IRPCPacketCall, IRPCPacketData, IRPCPacketEvent, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCRequest, IRPCResolver, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStubStore, IRPCTransport, IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS, TransportConfig, createContext, createPackage, getContext, setContext, setContextProvider, withContext };
+import { IRPCStream } from "./stream.js";
+export { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, ERROR_CODE, ERROR_MESSAGE, ErrorCode, IRPCArraySchema, IRPCCacheEntry, IRPCCacher, IRPCCall, IRPCCallConfig, IRPCContext, IRPCContextProvider, IRPCData, IRPCDataSchema, IRPCDataType, IRPCDeclareInit, IRPCError, IRPCEventType, IRPCHandler, IRPCInit, IRPCInputs, IRPCObject, IRPCObjectSchema, IRPCOutput, IRPCPackage, IRPCPackageConfig, IRPCPackageInfo, IRPCPacketAnswer, IRPCPacketBase, IRPCPacketCall, IRPCPacketClose, IRPCPacketData, IRPCPacketEvent, IRPCPacketStream, IRPCPacketType, IRPCParseResult, IRPCPayload, IRPCPrimitive, IRPCPrimitiveSchema, IRPCReadable, IRPCReader, IRPCRequest, IRPCResolver, IRPCResponse, IRPCSchema, IRPCSpec, IRPCSpecStore, IRPCStatus, IRPCStream, IRPCStubStore, IRPCTransport, IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS, RemoteState, StreamConstructor, TransportConfig, createContext, createPackage, getContext, setContext, setContextProvider, stream, withContext };

package/dist/index.js

@@ -1,10 +1,13 @@
 import { IRPCCacher } from "./cache.js";
 import { IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
-import { IRPCCall } from "./call.js";
-import { createContext, getContext, setContext, setContextProvider, withContext } from "./context.js";
 import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { RemoteState, stream } from "./state.js";
+import { IRPCReader } from "./reader.js";
+import { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, IRPCCall } from "./call.js";
+import { createContext, getContext, setContext, setContextProvider, withContext } from "./context.js";
 import { IRPCTransport } from "./transport.js";
 import { IRPCPackage, createPackage } from "./module.js";
 import { IRPCResolver } from "./resolver.js";
+import { IRPCStream } from "./stream.js";
 
-export { ERROR_CODE, ERROR_MESSAGE, IRPCCacher, IRPCCall, IRPCPackage, IRPCResolver, IRPCTransport, IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS, createContext, createPackage, getContext, setContext, setContextProvider, withContext };
+export { DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MODE, ERROR_CODE, ERROR_MESSAGE, IRPCCacher, IRPCCall, IRPCPackage, IRPCReader, IRPCResolver, IRPCStream, IRPCTransport, IRPC_DATA_TYPE, IRPC_EVENT_TYPE, IRPC_PACKET_TYPE, IRPC_STATUS, RemoteState, createContext, createPackage, getContext, setContext, setContextProvider, stream, withContext };

package/dist/module.d.ts

@@ -1,6 +1,7 @@
 import { IRPCCacher } from "./cache.js";
 import { IRPCTransport } from "./transport.js";
-import { IRPCData, IRPCHandler, IRPCInit, IRPCInputs, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCRequest, IRPCSpec, IRPCSpecStore, IRPCStubStore } from "./types.js";
+import { IRPCData, IRPCDeclareInit, IRPCHandler, IRPCInputs, IRPCOutput, IRPCPackageConfig, IRPCPackageInfo, IRPCRequest, IRPCSpec, IRPCSpecStore, IRPCStubStore } from "./types.js";
+import { RemoteState } from "./state.js";
 
 //#region src/module.d.ts
 
@@ -46,18 +47,18 @@ declare class IRPCPackage {
   constructor(config?: Partial<IRPCPackageConfig>);
   /**
    * Declares a new IRPC specification and creates a corresponding stub function
-   * @param init - The initialization object containing the IRPC specification
+   * @param options - The initialization object containing the IRPC specification
    * @returns A stub function that can be used to call the IRPC
    * @throws Error if an IRPC with the same name already exists
    */
-  declare<F, I extends IRPCInputs = IRPCInputs, O extends IRPCOutput = IRPCOutput>(init: IRPCInit<I, O>): F;
+  declare<F, I extends IRPCInputs = IRPCInputs, O extends IRPCOutput = IRPCOutput>(options: IRPCDeclareInit<F, I, O>): F;
   /**
    * Resolves and executes an IRPC call based on a request object
    * @param req - The request containing the IRPC name and arguments
    * @returns The result of the IRPC execution
    * @throws Error if the IRPC doesn't exist or doesn't have an implementation
    */
-  resolve(req: IRPCRequest): Promise<IRPCData>;
+  resolve(req: IRPCRequest): IRPCData | Promise<IRPCData> | RemoteState<IRPCData>;
   /**
    * Associates a handler function with a stub function
    * @param stub - The stub function created by declare()

package/dist/module.js

@@ -1,5 +1,6 @@
 import { IRPCCacher } from "./cache.js";
 import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { RemoteState } from "./state.js";
 import { IRPCTransport } from "./transport.js";
 
 //#region src/module.ts
@@ -65,33 +66,40 @@ var IRPCPackage = class {
 	}
 	/**
 	* Declares a new IRPC specification and creates a corresponding stub function
-	* @param init - The initialization object containing the IRPC specification
+	* @param options - The initialization object containing the IRPC specification
 	* @returns A stub function that can be used to call the IRPC
 	* @throws Error if an IRPC with the same name already exists
 	*/
-	declare(init) {
-		if (this.specs.has(init.name)) throw new Error(`IRPC ${init.name} already exists.`);
-		const spec = { ...init };
+	declare(options) {
+		if (this.specs.has(options.name)) throw new Error(`IRPC ${options.name} already exists.`);
+		const spec = { ...options };
 		const calls = /* @__PURE__ */ new Map();
 		const caches = new IRPCCacher();
-		const timeout = spec.timeout ?? this.config.timeout;
-		const stub = (async (...args) => {
-			if (!this.transport && typeof spec.handler !== "function") throw new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_MISSING]);
+		const stub = ((...args) => {
+			if (!this.transport && typeof spec.handler !== "function") return Promise.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_MISSING]));
 			const callKey = JSON.stringify(args);
 			const cached = caches.get(callKey);
 			if (cached) return cached.value;
 			if (spec.coalesce !== false && calls.has(callKey)) return calls.get(callKey);
-			const call = typeof spec.handler === "function" ? spec.handler(...args) : this.transport.call(spec, args, timeout);
+			const { timeout, maxRetries, retryDelay, retryMode } = {
+				...this.config,
+				...spec
+			};
+			const config = {
+				timeout,
+				maxRetries,
+				retryDelay,
+				retryMode
+			};
+			const call = typeof spec.handler === "function" ? spec.handler(...args) : this.transport.call(spec, args, config);
 			calls.set(callKey, call);
-			try {
-				const data = await call;
-				if (spec.maxAge) caches.set(callKey, data, spec.maxAge);
-				return data;
-			} finally {
-				calls.delete(callKey);
-			}
+			if (spec.maxAge) caches.set(callKey, call, spec.maxAge);
+			if (typeof spec.init === "function" && call instanceof RemoteState && typeof call.data === "undefined") call.data = spec.init();
+			if (call instanceof Promise) call.finally(() => calls.delete(callKey)).catch(() => {});
+			else calls.delete(callKey);
+			return call;
 		});
-		this.specs.set(init.name, spec);
+		this.specs.set(options.name, spec);
 		this.stubs.set(stub, spec);
 		this.cache.set(stub, caches);
 		return stub;
@@ -102,11 +110,11 @@ var IRPCPackage = class {
 	* @returns The result of the IRPC execution
 	* @throws Error if the IRPC doesn't exist or doesn't have an implementation
 	*/
-	async resolve(req) {
+	resolve(req) {
 		const spec = this.specs.get(req.name);
 		if (!spec) return Promise.reject(/* @__PURE__ */ new Error(`IRPC ${req.name} does not exist.`));
 		if (typeof spec.handler !== "function") return Promise.reject(/* @__PURE__ */ new Error(`IRPC ${req.name} does not have an implementation.`));
-		return await spec.handler(...req.args);
+		return spec.handler(...req.args);
 	}
 	/**
 	* Associates a handler function with a stub function

package/dist/reader.d.ts

@@ -0,0 +1,24 @@
+import { IRPCData, IRPCPacketStream } from "./types.js";
+import { RemoteState } from "./state.js";
+
+//#region src/reader.d.ts
+
+/**
+ * A client-side consumer that hydrates `RemoteState` instances from network stream packets.
+ *
+ * @template T - The type of data yielded by the stream.
+ */
+declare class IRPCReader<T extends IRPCData> extends RemoteState<T> {
+  id: string;
+  packets: Set<IRPCPacketStream<T>>;
+  constructor(id: string, init?: T);
+  /**
+   * Pushes incoming network packets into this reader, evaluating payload data
+   * and subsequently updating the core state values locally.
+   *
+   * @param packet - The incoming unified Stream Packet structure (`ANSWER`, `EVENT`, or `CLOSE`).
+   */
+  push(packet: IRPCPacketStream<T>): void;
+}
+//#endregion
+export { IRPCReader };

package/dist/reader.js

@@ -0,0 +1,37 @@
+import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
+import { RemoteState } from "./state.js";
+import { replay } from "@anchorlib/core";
+
+//#region src/reader.ts
+/**
+* A client-side consumer that hydrates `RemoteState` instances from network stream packets.
+*
+* @template T - The type of data yielded by the stream.
+*/
+var IRPCReader = class extends RemoteState {
+	packets = /* @__PURE__ */ new Set();
+	constructor(id, init) {
+		super(init);
+		this.id = id;
+	}
+	/**
+	* Pushes incoming network packets into this reader, evaluating payload data
+	* and subsequently updating the core state values locally.
+	*
+	* @param packet - The incoming unified Stream Packet structure (`ANSWER`, `EVENT`, or `CLOSE`).
+	*/
+	push(packet) {
+		packet.arrivedAt = Date.now();
+		this.packets.add(packet);
+		if (packet.type === IRPC_PACKET_TYPE.ANSWER) if (packet.status === IRPC_STATUS.ERROR) this.error = new Error(packet.error.message);
+		else this.data = packet.data;
+		else if (packet.type === IRPC_PACKET_TYPE.EVENT) replay(this.state, packet.data);
+		else if (packet.type === IRPC_PACKET_TYPE.CLOSE) {
+			if (packet.error) this.error = new Error(packet.error.message);
+		}
+		this.status = packet.status;
+	}
+};
+
+//#endregion
+export { IRPCReader };

package/dist/resolver.d.ts

@@ -1,4 +1,4 @@
-import { IRPCDataSchema, IRPCError, IRPCInputs, IRPCOutput, IRPCRequest, IRPCResponse, IRPCSpec } from "./types.js";
+import { IRPCDataSchema, IRPCInputs, IRPCOutput, IRPCRequest, IRPCResponse, IRPCSpec } from "./types.js";
 import { IRPCPackage } from "./module.js";
 
 //#region src/resolver.d.ts
@@ -45,17 +45,7 @@ declare class IRPCResolver {
     id,
     name,
     args
-  }: IRPCRequest, schema?: IRPCOutput): Promise<{
-    id: string;
-    name: string;
-    result: string | number | boolean | IRPCDataSchema | Record<string, unknown> | (string | number | boolean | Record<string, unknown> | null | undefined)[] | null | undefined;
-    error?: undefined;
-  } | {
-    id: string;
-    name: string;
-    error: IRPCError;
-    result?: undefined;
-  }>;
+  }: IRPCRequest, schema?: IRPCOutput): Promise<IRPCResponse>;
 }
 //#endregion
 export { IRPCResolver };

package/dist/resolver.js

@@ -1,4 +1,5 @@
 import { ERROR_CODE } from "./error.js";
+import { RemoteState } from "./state.js";
 
 //#region src/resolver.ts
 /**
@@ -69,11 +70,28 @@ var IRPCResolver = class {
 	*/
 	async forward({ id, name, args }, schema) {
 		try {
-			const output = parseOutput(await this.module.resolve({
+			const result = this.module.resolve({
 				id,
 				name,
 				args
-			}), schema);
+			});
+			if (result instanceof RemoteState) {
+				const output$1 = parseOutput(result.data, schema);
+				if (!output$1.success) return {
+					id,
+					name,
+					error: {
+						code: ERROR_CODE.INVALID_OUTPUT,
+						message: output$1.error?.message
+					}
+				};
+				return {
+					id,
+					name,
+					result
+				};
+			}
+			const output = parseOutput(await result, schema);
 			if (output.success) return {
 				id,
 				name,

package/dist/state.d.ts

@@ -3,17 +3,80 @@ import * as _anchorlib_core0 from "@anchorlib/core";
 import { StateSubscriber } from "@anchorlib/core";
 
 //#region src/state.d.ts
-declare class RemoteState<T> {
-  #private;
+
+/**
+ * A reactive state wrapper that implements the standard Promise interface.
+ *
+ * RemoteState acts as a dual-layer abstraction:
+ * 1. For asynchronous execution, it operates as a `Promise<T>` that resolves upon completion or rejects upon failure.
+ * 2. For reactive environments, it exposes an `.subscribe()` method to react to intermediate data mutations.
+ *
+ * @template T - The type of data held by the state.
+ */
+declare class RemoteState<T> extends Promise<T> {
+  protected readonly state: IRPCReadable<T>;
+  protected readonly accept: (value: T) => void;
+  protected readonly reject: (error: Error) => void;
+  /**
+   * The current data payload of the state.
+   */
   get data(): T;
   set data(data: T);
+  /**
+   * The current error encountered by the state, if any.
+   */
   get error(): Error | undefined;
   set error(error: Error | undefined);
+  /**
+   * The execution status of the state (PENDING, SUCCESS, ERROR).
+   * Transitioning to a terminal status (SUCCESS or ERROR) will automatically resolve or reject the underlying Promise.
+   */
   get status(): IRPCStatus;
   set status(status: IRPCStatus);
-  constructor(init: T);
+  /**
+   * Initializes a new RemoteState with an optional initial payload.
+   *
+   * @param init - An optional starting value for the data payload.
+   */
+  constructor(init?: T);
+  /**
+   * Subscribes to changes emitted by the internal state.
+   *
+   * @param handler - A callback function invoked whenever the state mutates.
+   * @returns An unsubscribe function to terminate the listener.
+   */
   subscribe(handler: StateSubscriber<IRPCReadable<T>>): _anchorlib_core0.StateUnsubscribe;
-  destroy(): void;
+  /**
+   * Destroys the reactive state bindings.
+   */
+  protected destroy(): void;
+  /**
+   * Ensures that chained Promise operations return standard Promises
+   * rather than instantiating new RemoteState subclasses.
+   */
+  static get [Symbol.species](): PromiseConstructor;
 }
+/**
+ * A callback function type used to natively construct and drive a reactive stream.
+ * It provides the initial reactive data reference and terminal resolution hooks
+ * without forcing strict async/await boundaries, securely yielding stream operations.
+ *
+ * @template T - The type of data yielded globally by the stream.
+ * @param data - The mutable data payload natively tracked by RemoteState.
+ * @param resolve - Callback to statically mark the stream as successfully completed, optionally with a resolved value.
+ * @param reject - Callback to forcefully throw a runtime error into the stream structure.
+ */
+type StreamConstructor<T> = (data: T, resolve: (value?: T) => void, reject: (error: Error) => void) => void | Promise<void>;
+/**
+ * A utility factory to structurally instantiate an active `RemoteState` pipeline natively
+ * decoupled from standard Promise chains. This elegantly captures constructor functions
+ * pushing events into the state before terminating mechanically via secure internal hooks.
+ *
+ * @template T - The type of the streamed payload data.
+ * @param construct - The isolated stream constructor callback that natively operates the pipeline.
+ * @param init - An optional initial value to prime the state payload inherently.
+ * @returns A fully active RemoteState inherently bound to the callbacks executing natively.
+ */
+declare function stream<T>(construct: StreamConstructor<T>, init?: T): RemoteState<T>;
 //#endregion
-export { RemoteState };
+export { RemoteState, StreamConstructor, stream };