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

package/dist/state.d.ts

@@ -0,0 +1,82 @@
+import { IRPCReadable, IRPCStatus } from "./types.js";
+import * as _anchorlib_core0 from "@anchorlib/core";
+import { StateSubscriber } from "@anchorlib/core";
+
+//#region src/state.d.ts
+
+/**
+ * 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);
+  /**
+   * 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;
+  /**
+   * 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, StreamConstructor, stream };

package/dist/state.js

@@ -0,0 +1,126 @@
+import { IRPC_STATUS } from "./enum.js";
+import { anchor, mutable, subscribe } from "@anchorlib/core";
+
+//#region src/state.ts
+/**
+* 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.
+*/
+var RemoteState = class extends Promise {
+	state;
+	accept;
+	reject;
+	/**
+	* The current data payload of the state.
+	*/
+	get data() {
+		return this.state.data;
+	}
+	set data(data) {
+		this.state.data = data;
+	}
+	/**
+	* The current error encountered by the state, if any.
+	*/
+	get error() {
+		return this.state.error;
+	}
+	set error(error) {
+		this.state.error = error;
+	}
+	/**
+	* 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() {
+		return this.state.status;
+	}
+	set status(status) {
+		this.state.status = status;
+		if (this.status === IRPC_STATUS.ERROR) {
+			this.reject(new Error(this.error.message));
+			this.destroy();
+		} else if (this.status === IRPC_STATUS.SUCCESS) {
+			this.accept(this.data);
+			this.destroy();
+		}
+	}
+	/**
+	* Initializes a new RemoteState with an optional initial payload.
+	*
+	* @param init - An optional starting value for the data payload.
+	*/
+	constructor(init) {
+		let acceptFn;
+		let rejectFn;
+		super((resolve, reject) => {
+			acceptFn = resolve;
+			rejectFn = reject;
+		});
+		this.accept = acceptFn;
+		this.reject = rejectFn;
+		this.state = mutable({
+			data: init,
+			error: void 0,
+			status: IRPC_STATUS.PENDING
+		});
+	}
+	/**
+	* 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) {
+		return subscribe(this.state, handler);
+	}
+	/**
+	* Destroys the reactive state bindings.
+	*/
+	destroy() {
+		anchor.destroy(this.state);
+	}
+	/**
+	* Ensures that chained Promise operations return standard Promises
+	* rather than instantiating new RemoteState subclasses.
+	*/
+	static get [Symbol.species]() {
+		return Promise;
+	}
+};
+/**
+* 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.
+*/
+function stream(construct, init) {
+	const state = new RemoteState(init);
+	const accept = ((...values) => {
+		if (values.length > 0) state.data = values[0];
+		state.status = IRPC_STATUS.SUCCESS;
+	});
+	const reject = (error) => {
+		state.error = error;
+		state.status = IRPC_STATUS.ERROR;
+	};
+	try {
+		const result = construct(state.data, accept, reject);
+		if (result instanceof Promise) result.catch(reject);
+	} catch (error) {
+		reject(error);
+	}
+	return state;
+}
+
+//#endregion
+export { RemoteState, stream };

package/dist/stream.d.ts

@@ -0,0 +1,57 @@
+import { IRPCData, IRPCError, IRPCPacketStream, IRPCResponse, IRPCStatus } from "./types.js";
+
+//#region src/stream.d.ts
+
+/**
+ * A server-side producer that normalizes and serializes RPC outputs into standard transport packets.
+ *
+ * Supports both standard asynchronous responses and reactive streams. When handling a continuous stream,
+ * it intercepts state mutations and emits sequential network packets (`ANSWER`, `EVENT`, `CLOSE`).
+ *
+ * @template T - The type of data yielded by the stream.
+ */
+declare class IRPCStream<T extends IRPCData> {
+  private id;
+  private name;
+  private initializer;
+  private pipeHandlers;
+  private closeHandlers;
+  private errorHandlers;
+  value?: T;
+  error?: IRPCError;
+  status: IRPCStatus;
+  /**
+   * Initializes a stream wrapping an asynchronous RPC execution.
+   *
+   * @param id - The unique identifier of the RPC request.
+   * @param name - The name of the specification processing the execution.
+   * @param initializer - An execution callback that yields an IRPCResponse.
+   */
+  constructor(id: string, name: string, initializer: () => Promise<IRPCResponse>);
+  /**
+   * Evaluates the underlying initializer and propagates standard transport packets
+   * to all bound pipe handlers based on the output lifecycle.
+   */
+  private start;
+  /**
+   * Binds a handler to receive the outbound stream packets.
+   * If invoked after the stream has fulfilled or rejected natively, it automatically plays back the conclusive packet.
+   *
+   * @param handler - A callback function to receive packets.
+   */
+  pipe(handler: (event: IRPCPacketStream<T>) => void): void;
+  /**
+   * Binds a handler to trap any internal runtime failures independently.
+   *
+   * @param handler - A callback function to receive stream errors.
+   */
+  catch(handler: (error: IRPCError) => void): void;
+  /**
+   * Binds a handler triggered upon terminal completion of the stream process (success or error).
+   *
+   * @param handler - A callback function invoked at stream completion.
+   */
+  close(handler: () => void): void;
+}
+//#endregion
+export { IRPCStream };

package/dist/stream.js

@@ -0,0 +1,204 @@
+import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
+import { ERROR_CODE } from "./error.js";
+import { RemoteState } from "./state.js";
+
+//#region src/stream.ts
+/**
+* A server-side producer that normalizes and serializes RPC outputs into standard transport packets.
+*
+* Supports both standard asynchronous responses and reactive streams. When handling a continuous stream,
+* it intercepts state mutations and emits sequential network packets (`ANSWER`, `EVENT`, `CLOSE`).
+*
+* @template T - The type of data yielded by the stream.
+*/
+var IRPCStream = class {
+	pipeHandlers = /* @__PURE__ */ new Set();
+	closeHandlers = /* @__PURE__ */ new Set();
+	errorHandlers = /* @__PURE__ */ new Set();
+	value;
+	error;
+	status = IRPC_STATUS.IDLE;
+	/**
+	* Initializes a stream wrapping an asynchronous RPC execution.
+	*
+	* @param id - The unique identifier of the RPC request.
+	* @param name - The name of the specification processing the execution.
+	* @param initializer - An execution callback that yields an IRPCResponse.
+	*/
+	constructor(id, name, initializer) {
+		this.id = id;
+		this.name = name;
+		this.initializer = initializer;
+	}
+	/**
+	* Evaluates the underlying initializer and propagates standard transport packets
+	* to all bound pipe handlers based on the output lifecycle.
+	*/
+	async start() {
+		if (this.status !== IRPC_STATUS.IDLE) return;
+		this.status = IRPC_STATUS.PENDING;
+		const { id, name } = this;
+		try {
+			const { result } = await this.initializer();
+			if (result instanceof RemoteState) {
+				this.value = result.data;
+				if (result.status === IRPC_STATUS.SUCCESS || result.status === IRPC_STATUS.ERROR) {
+					if (result.status === IRPC_STATUS.ERROR) {
+						this.error = {
+							code: ERROR_CODE.STREAM_ERROR,
+							message: result.error.message
+						};
+						this.status = IRPC_STATUS.ERROR;
+					} else this.status = IRPC_STATUS.SUCCESS;
+					const packet = {
+						id,
+						name,
+						type: IRPC_PACKET_TYPE.ANSWER,
+						data: this.value,
+						error: this.error,
+						status: this.status,
+						createdAt: Date.now()
+					};
+					this.pipeHandlers.forEach((handler) => handler(packet));
+					this.errorHandlers.forEach((handler) => handler(this.error));
+					this.closeHandlers.forEach((handler) => handler());
+					return;
+				}
+				this.pipeHandlers.forEach((handler) => {
+					handler({
+						id,
+						name,
+						type: IRPC_PACKET_TYPE.ANSWER,
+						data: result.data,
+						status: result.status,
+						createdAt: Date.now()
+					});
+				});
+				const unsubscribe = result.subscribe((state, { type, keys, value }) => {
+					if (type === "init") return;
+					const [rootKey] = keys;
+					if (rootKey === "data") this.pipeHandlers.forEach((handler) => {
+						handler({
+							id,
+							name,
+							type: IRPC_PACKET_TYPE.EVENT,
+							status: state.status,
+							data: {
+								type,
+								keys,
+								value
+							},
+							createdAt: Date.now()
+						});
+					});
+					else if (rootKey === "status") {
+						if (state.status !== IRPC_STATUS.SUCCESS && state.status !== IRPC_STATUS.ERROR) return;
+						this.status = state.status;
+						if (state.status === IRPC_STATUS.ERROR) {
+							this.error = {
+								code: ERROR_CODE.STREAM_ERROR,
+								message: state.error.message
+							};
+							this.errorHandlers.forEach((handler) => handler(this.error));
+						}
+						this.pipeHandlers.forEach((handler) => {
+							handler({
+								id,
+								name,
+								type: IRPC_PACKET_TYPE.CLOSE,
+								error: this.error,
+								status: this.status,
+								createdAt: Date.now()
+							});
+						});
+						this.closeHandlers.forEach((handler) => handler());
+						unsubscribe();
+					}
+				});
+			} else {
+				this.value = result;
+				this.status = IRPC_STATUS.SUCCESS;
+				const packet = {
+					id,
+					name,
+					type: IRPC_PACKET_TYPE.ANSWER,
+					status: IRPC_STATUS.SUCCESS,
+					data: this.value,
+					createdAt: Date.now()
+				};
+				this.pipeHandlers.forEach((handler) => handler(packet));
+				this.closeHandlers.forEach((handler) => handler());
+			}
+		} catch (error) {
+			this.error = {
+				code: ERROR_CODE.STREAM_ERROR,
+				message: error.message
+			};
+			this.status = IRPC_STATUS.ERROR;
+			this.pipeHandlers.forEach((handler) => {
+				handler({
+					id,
+					name,
+					type: IRPC_PACKET_TYPE.ANSWER,
+					status: IRPC_STATUS.ERROR,
+					error,
+					createdAt: Date.now()
+				});
+			});
+			this.errorHandlers.forEach((handler) => handler(this.error));
+			this.closeHandlers.forEach((handler) => handler());
+			return;
+		}
+	}
+	/**
+	* Binds a handler to receive the outbound stream packets.
+	* If invoked after the stream has fulfilled or rejected natively, it automatically plays back the conclusive packet.
+	*
+	* @param handler - A callback function to receive packets.
+	*/
+	pipe(handler) {
+		if (this.status === IRPC_STATUS.SUCCESS || this.status === IRPC_STATUS.ERROR) {
+			handler({
+				id: this.id,
+				name: this.name,
+				type: IRPC_PACKET_TYPE.ANSWER,
+				data: this.value,
+				error: this.error,
+				status: this.status,
+				createdAt: Date.now()
+			});
+			return;
+		}
+		this.pipeHandlers.add(handler);
+		this.start().catch(() => {});
+	}
+	/**
+	* Binds a handler to trap any internal runtime failures independently.
+	*
+	* @param handler - A callback function to receive stream errors.
+	*/
+	catch(handler) {
+		if (this.status === IRPC_STATUS.ERROR) {
+			handler(this.error);
+			return;
+		}
+		this.errorHandlers.add(handler);
+		this.start().catch(() => {});
+	}
+	/**
+	* Binds a handler triggered upon terminal completion of the stream process (success or error).
+	*
+	* @param handler - A callback function invoked at stream completion.
+	*/
+	close(handler) {
+		if (this.status === IRPC_STATUS.SUCCESS || this.status === IRPC_STATUS.ERROR) {
+			handler();
+			return;
+		}
+		this.closeHandlers.add(handler);
+		this.start().catch(() => {});
+	}
+};
+
+//#endregion
+export { IRPCStream };

package/dist/transport.d.ts

@@ -1,4 +1,5 @@
-import { IRPCData, IRPCInputs, IRPCOutput, IRPCSpec, TransportConfig } from "./types.js";
+import { IRPCCallConfig, IRPCData, IRPCInputs, IRPCOutput, IRPCSpec, TransportConfig } from "./types.js";
+import { IRPCReader } from "./reader.js";
 import { IRPCCall } from "./call.js";
 
 //#region src/transport.d.ts
@@ -22,16 +23,16 @@ declare class IRPCTransport {
    * Initiates an RPC call with the given specification and arguments.
    * @param spec - The RPC specification defining the method to call.
    * @param args - An array of arguments to pass to the RPC method.
-   * @param timeout - Optional timeout value for the RPC call.
+   * @param config - Optional call configuration, including timeout, retry settings, and more.
    * @returns A promise that resolves with the RPC response data or rejects with an error.
    */
-  call(spec: IRPCSpec<IRPCInputs, IRPCOutput>, args: IRPCData[], timeout?: number | undefined): Promise<IRPCData>;
+  call(spec: IRPCSpec<IRPCInputs, IRPCOutput>, args: IRPCData[], config?: IRPCCallConfig): IRPCReader<IRPCData>;
   /**
    * Schedules an RPC call for execution, implementing debouncing logic.
    * Queued calls will be dispatched after the configured debounce delay.
    * @param call - The RPC call to schedule.
    */
-  protected schedule(call: IRPCCall): void;
+  schedule(call: IRPCCall): void;
   /**
    * Dispatches a batch of RPC calls. This base implementation rejects all calls
    * with a "not implemented" error. Subclasses should override this method to

package/dist/transport.js

@@ -1,5 +1,6 @@
-import { IRPCCall } from "./call.js";
+import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
 import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { IRPCCall } from "./call.js";
 
 //#region src/transport.ts
 /**
@@ -22,27 +23,26 @@ var IRPCTransport = class {
 	* Initiates an RPC call with the given specification and arguments.
 	* @param spec - The RPC specification defining the method to call.
 	* @param args - An array of arguments to pass to the RPC method.
-	* @param timeout - Optional timeout value for the RPC call.
+	* @param config - Optional call configuration, including timeout, retry settings, and more.
 	* @returns A promise that resolves with the RPC response data or rejects with an error.
 	*/
-	call(spec, args, timeout = this.config?.timeout) {
+	call(spec, args, config) {
 		const payload = {
 			name: spec.name,
 			args
 		};
-		return new Promise((resolve, reject) => {
-			const timer = timeout ? setTimeout(() => {
-				call.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TIMEOUT]));
-			}, timeout) : void 0;
-			const call = new IRPCCall(payload, (value) => {
-				resolve(value);
-				clearTimeout(timer);
-			}, (reason) => {
-				reject(reason);
-				clearTimeout(timer);
-			}, timeout);
-			this.schedule(call);
+		const { timeout, maxRetries, retryMode, retryDelay } = {
+			...this.config,
+			...config
+		};
+		const call = new IRPCCall(this, payload, {
+			timeout,
+			maxRetries,
+			retryMode,
+			retryDelay
 		});
+		this.schedule(call);
+		return call.reader;
 	}
 	/**
 	* Schedules an RPC call for execution, implementing debouncing logic.
@@ -50,10 +50,18 @@ var IRPCTransport = class {
 	* @param call - The RPC call to schedule.
 	*/
 	schedule(call) {
-		if (!this.queue.size) setTimeout(() => {
-			this.dispatch(Array.from(this.queue));
+		const { debounce } = this.config ?? {};
+		if (debounce === false) {
+			this.dispatch([call]).finally(() => {}).catch(() => {});
+			return;
+		}
+		const timeout = typeof debounce === "number" && !Number.isNaN(debounce) ? debounce : 0;
+		const dispatch = () => {
+			this.dispatch(Array.from(this.queue)).finally(() => {}).catch(() => {});
 			this.queue.clear();
-		}, this.config?.debounce ?? 0);
+		};
+		if (!this.queue.size) if (timeout === 0) queueMicrotask(dispatch);
+		else setTimeout(dispatch, timeout);
 		this.queue.add(call);
 	}
 	/**
@@ -65,7 +73,17 @@ var IRPCTransport = class {
 	*/
 	async dispatch(calls) {
 		calls.forEach((call) => {
-			call.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]));
+			call.enqueue({
+				id: call.id,
+				name: call.payload.name,
+				type: IRPC_PACKET_TYPE.CLOSE,
+				status: IRPC_STATUS.ERROR,
+				error: {
+					code: ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED,
+					message: ERROR_MESSAGE[ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]
+				},
+				createdAt: Date.now()
+			});
 		});
 	}
 };