@irpclib/irpc 1.0.0-beta.22 → 1.0.0-beta.23

package/dist/module.js

@@ -1,7 +1,11 @@
 import { IRPCCacher } from "./cache.js";
+import { IRPC_STATUS } from "./enum.js";
 import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
 import { RemoteState } from "./state.js";
+import { IRPCReader } from "./reader.js";
 import { IRPCTransport } from "./transport.js";
+import { IRPC_STORE } from "./store.js";
+import { anchor, createObserver, isBrowser, microtask, onCleanup, replay, uuid } from "@anchorlib/core";
 
 //#region src/module.ts
 const DEFAULT_TIMEOUT = 2e4;
@@ -17,6 +21,7 @@ var IRPCPackage = class {
 	* A map storing all IRPC specifications by their names
 	*/
 	specs = /* @__PURE__ */ new Map();
+	hooks = /* @__PURE__ */ new Map();
 	/**
 	* A weak map linking stub functions to their corresponding specifications
 	*/
@@ -63,6 +68,7 @@ var IRPCPackage = class {
 	*/
 	constructor(config) {
 		this.configure(config ?? {});
+		IRPC_STORE.register(this);
 	}
 	/**
 	* Declares a new IRPC specification and creates a corresponding stub function
@@ -71,17 +77,67 @@ var IRPCPackage = class {
 	* @throws Error if an IRPC with the same name already exists
 	*/
 	declare(options) {
-		if (this.specs.has(options.name)) throw new Error(`IRPC ${options.name} already exists.`);
-		const spec = { ...options };
+		const $options = options;
+		if (this.specs.has($options.name)) throw new Error(`IRPC ${$options.name} already exists.`);
+		const spec = {
+			init: () => void 0,
+			...$options
+		};
 		const calls = /* @__PURE__ */ new Map();
 		const caches = new IRPCCacher();
 		const stub = ((...args) => {
+			return execute(args, new IRPCReader(uuid(), spec.init()));
+		});
+		/** Browser only stub for single immediate execution **/
+		stub.once = (...args) => {
+			return prepare(() => args);
+		};
+		stub.with = (getArgs, debounce) => {
+			return prepare(typeof getArgs === "function" ? getArgs : () => getArgs, false, debounce);
+		};
+		stub.when = (getArgs, debounce) => {
+			return prepare(typeof getArgs === "function" ? getArgs : () => getArgs, true, debounce);
+		};
+		/**
+		* A preparation utility to generate and schedule call on the browser environment.
+		*
+		* @param getArgs - A function that returns the arguments for the call.
+		* @param deferred - A flag indicating whether the call should be deferred.
+		* @param debounce - The debounce time in milliseconds.
+		* @returns {IRPCReader<IRPCData>} - The reader for the call.
+		*/
+		function prepare(getArgs, deferred, debounce = 0) {
+			const reader = new IRPCReader(uuid(), spec.init(), deferred ? IRPC_STATUS.IDLE : IRPC_STATUS.PENDING);
+			if (isBrowser()) {
+				const observer = createObserver(() => {
+					observer.reset();
+					dispatch();
+				});
+				const [schedule, cancel] = microtask(debounce);
+				const dispatch = (coalesce = true) => {
+					const args = observer.run(getArgs);
+					if (!coalesce) return execute(args, reader);
+					schedule(() => {
+						execute(args, reader);
+					});
+				};
+				if (deferred) observer.run(getArgs);
+				else dispatch(false);
+				onCleanup(() => {
+					cancel();
+					observer.destroy();
+				});
+			}
+			return reader;
+		}
+		const execute = (args, reader) => {
 			if (!this.transport && typeof spec.handler !== "function") return Promise.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_MISSING]));
+			reader.status = IRPC_STATUS.PENDING;
 			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 { timeout, maxRetries, retryDelay, retryMode } = {
+			const { timeout, maxRetries, retryDelay, retryMode, init } = {
 				...this.config,
 				...spec
 			};
@@ -89,19 +145,25 @@ var IRPCPackage = class {
 				timeout,
 				maxRetries,
 				retryDelay,
-				retryMode
+				retryMode,
+				init
 			};
-			const call = typeof spec.handler === "function" ? spec.handler(...args) : this.transport.call(spec, args, config);
+			const hooks = this.hooks.get(spec);
+			if (hooks) hooks.forEach((hook) => hook({
+				name: spec.name,
+				args
+			}));
+			const call = typeof spec.handler === "function" ? intercept(spec, args, reader) : this.transport.call(spec, args, config, reader);
 			calls.set(callKey, call);
 			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(options.name, spec);
+			onCleanup(() => call.close());
+			call.finally(() => calls.delete(callKey)).catch((err) => IRPC_STORE.error(err, [{ name: spec.name }]));
+			return reader;
+		};
+		this.specs.set($options.name, spec);
 		this.stubs.set(stub, spec);
 		this.cache.set(stub, caches);
+		this.hooks.set(spec, /* @__PURE__ */ new Set());
 		return stub;
 	}
 	/**
@@ -132,6 +194,35 @@ var IRPCPackage = class {
 		return this;
 	}
 	/**
+	* Registers a hook function for a specific stub function
+	* @param stub - The stub function created by declare()
+	* @param handler - The hook function to register
+	* @returns This IRPCPackage instance for chaining
+	* @throws Error if the stub is invalid or if no IRPC exists for the stub
+	*/
+	hook(stub, handler) {
+		if (!this.stubs.has(stub)) {
+			const error = new Error(ERROR_MESSAGE[ERROR_CODE.NOT_FOUND]);
+			IRPC_STORE.error(error);
+			return this;
+		}
+		const spec = this.stubs.get(stub);
+		this.hooks.get(spec).add(handler);
+		return this;
+	}
+	/**
+	* Resolves and executes all registered hooks for a given request
+	* @param req - The request containing the IRPC name and arguments
+	* @returns A promise that resolves when all hooks have been executed
+	* @throws Error if no IRPC exists for the request or if the hooks are not registered
+	*/
+	async resolveHooks(req) {
+		const spec = this.specs.get(req.name);
+		if (!spec || !this.hooks.has(spec)) throw new Error(ERROR_MESSAGE[ERROR_CODE.NOT_FOUND]);
+		const hooks = this.hooks.get(spec);
+		for (const hook of hooks) await hook(req);
+	}
+	/**
 	* Sets the transport mechanism for this package
 	* @param transport - The transport instance to use for remote calls
 	* @returns This IRPCPackage instance for chaining
@@ -183,6 +274,45 @@ var IRPCPackage = class {
 function createPackage(config) {
 	return new IRPCPackage(config);
 }
+/**
+* Intercepts local function call to get an instant response without remote execution.
+*
+* @param reader - The reader object to intercept.
+* @param spec - The IRPC specification for the function call.
+* @param args - The arguments to be passed to the function.
+* @returns {IRPCReader<IRPCData>} - The IRPCReader object for consumer.
+*/
+function intercept(spec, args, reader) {
+	try {
+		const result = spec.handler(...args);
+		if (!(result instanceof Promise)) {
+			reader.accept(result);
+			return reader;
+		}
+		if (!(result instanceof RemoteState)) {
+			result.then((value) => {
+				reader.accept(value);
+			}).catch((err) => {
+				reader.reject(err);
+			});
+			return reader;
+		}
+		anchor.assign(reader.state, result.state);
+		const unsubscribe = result.subscribe((_, event) => {
+			if (event.type === "init") return;
+			const [rootKey] = event.keys;
+			if (rootKey === "status") {
+				reader.status = event.value;
+				if (reader.status === IRPC_STATUS.SUCCESS) unsubscribe();
+				return;
+			}
+			replay(reader.state, event);
+		});
+	} catch (error) {
+		reader.reject(error);
+	}
+	return reader;
+}
 
 //#endregion
-export { IRPCPackage, createPackage };
+export { IRPCPackage, createPackage, intercept };

package/dist/packet.d.ts

@@ -0,0 +1,32 @@
+import { IRPCFileMeta, IRPCFileStream } from "./file.js";
+import { IRPCData } from "./types.js";
+
+//#region src/packet.d.ts
+declare const IRPC_FILE_IDENTIFIER: "IRPC_PACKET_FILE";
+type IRPCFilePointer = {
+  id: string;
+  type: typeof IRPC_FILE_IDENTIFIER;
+  meta: IRPCFileMeta;
+};
+type IRPCFileQueue = {
+  file: IRPCFilePointer;
+  data: Blob;
+};
+type IRPCPacketJson = {
+  data: IRPCData;
+  files: IRPCFilePointer[];
+};
+type IRPCPacketQueues = {
+  json: IRPCPacketJson;
+  queues: IRPCFileQueue[];
+};
+type PacketStream = {
+  data: IRPCData;
+  files: Map<string, IRPCFileStream>;
+  resolved: number;
+};
+declare function isFilePointer(data: IRPCData): boolean;
+declare function encode(data: IRPCData): IRPCPacketQueues;
+declare function decode(packet: IRPCPacketJson): PacketStream;
+//#endregion
+export { IRPCFilePointer, IRPCFileQueue, IRPCPacketJson, IRPCPacketQueues, IRPC_FILE_IDENTIFIER, PacketStream, decode, encode, isFilePointer };

package/dist/packet.js

@@ -0,0 +1,100 @@
+import { IRPCFile, IRPCFileStream } from "./file.js";
+import { isArray, isObject, uuid } from "@anchorlib/core";
+
+//#region src/packet.ts
+const IRPC_FILE_IDENTIFIER = "IRPC_PACKET_FILE";
+function isFilePointer(data) {
+	return isObject(data) && data.type === IRPC_FILE_IDENTIFIER;
+}
+function encode(data) {
+	const json = {
+		data,
+		files: []
+	};
+	const packet = {
+		json,
+		queues: []
+	};
+	if (data instanceof IRPCFile) {
+		const { pointer, queue } = createPointer(data);
+		json.data = pointer;
+		json.files.push(pointer);
+		packet.queues.push(queue);
+	} else if (isObject(data) || isArray(data)) encodePointers(data, json.files, packet.queues);
+	return packet;
+}
+function decode(packet) {
+	const files = packet.files.map((file) => {
+		return [file.id, new IRPCFileStream(file.meta)];
+	});
+	const stream = {
+		data: packet.data,
+		files: new Map(files),
+		resolved: 0
+	};
+	if (isFilePointer(packet.data)) {
+		const { id } = packet.data;
+		stream.data = stream.files.get(id);
+	} else if (isObject(packet.data) || isArray(packet.data)) decodePointers(packet.data, stream.files);
+	return stream;
+}
+function createPointer(file) {
+	const pointer = {
+		id: uuid(),
+		meta: file.meta,
+		type: IRPC_FILE_IDENTIFIER
+	};
+	return {
+		pointer,
+		queue: {
+			file: pointer,
+			data: file.data
+		}
+	};
+}
+/**
+* Replace all IRPCFile inside an object with IRPCPacketFile.
+* @param {Record<string, unknown> | unknown[]} data - The object to encode.
+* @param {IRPCFilePointer[]} pointers - The array of IRPCPacketFile to replace.
+* @param {IRPCFileQueue[]} queues - The array of IRPCPacketFileQueue to replace.
+*/
+function encodePointers(data, pointers, queues) {
+	if (isArray(data)) data.forEach((item, i) => {
+		if (item instanceof IRPCFile) {
+			const { pointer, queue } = createPointer(item);
+			data[i] = pointer;
+			pointers.push(pointer);
+			queues.push(queue);
+		} else if (isObject(item) || isArray(item)) encodePointers(item, pointers, queues);
+	});
+	else if (isObject(data)) Object.entries(data).forEach(([key, value]) => {
+		if (value instanceof IRPCFile) {
+			const { pointer, queue } = createPointer(value);
+			data[key] = pointer;
+			pointers.push(pointer);
+			queues.push(queue);
+		} else if (isObject(value) || isArray(value)) encodePointers(value, pointers, queues);
+	});
+}
+/**
+* Replace all IRPCPacketFile inside an object with IRPCFileStream.
+* @param data - The object to decode.
+* @param files - The map of IRPCFileStream to replace.
+*/
+function decodePointers(data, files) {
+	if (isArray(data)) data.forEach((item, i) => {
+		if (isFilePointer(item)) {
+			const { id } = item;
+			data[i] = files.get(id);
+		} else if (isObject(item) || isArray(item)) decodePointers(item, files);
+	});
+	else if (isObject(data)) Object.entries(data).forEach(([key, value]) => {
+		if (isFilePointer(value)) {
+			const { id } = value;
+			data[key] = files.get(id);
+		} else if (isObject(value) || isArray(value)) decodePointers(value, files);
+	});
+}
+
+//#endregion
+export { IRPC_FILE_IDENTIFIER, decode, encode, isFilePointer };

package/dist/reader.d.ts

@@ -1,4 +1,4 @@
-import { IRPCData, IRPCPacketStream } from "./types.js";
+import { IRPCData, IRPCPacketStream, IRPCStatus } from "./types.js";
 import { RemoteState } from "./state.js";
 
 //#region src/reader.d.ts
@@ -10,8 +10,15 @@ import { RemoteState } from "./state.js";
  */
 declare class IRPCReader<T extends IRPCData> extends RemoteState<T> {
   id: string;
-  packets: Set<IRPCPacketStream<T>>;
-  constructor(id: string, init?: T);
+  onClose?: () => void;
+  /**
+   * Initializes a new RemoteState with an optional initial payload.
+   *
+   * @param id - The unique identifier for this state instance.
+   * @param init - An optional starting value for the data payload.
+   * @param status - The initial status of the state (PENDING, SUCCESS, ERROR).
+   */
+  constructor(id: string, init?: T, status?: IRPCStatus);
   /**
    * Pushes incoming network packets into this reader, evaluating payload data
    * and subsequently updating the core state values locally.
@@ -19,6 +26,12 @@ declare class IRPCReader<T extends IRPCData> extends RemoteState<T> {
    * @param packet - The incoming unified Stream Packet structure (`ANSWER`, `EVENT`, or `CLOSE`).
    */
   push(packet: IRPCPacketStream<T>): void;
+  close(): void;
+  /**
+   * Ensures that chained Promise operations return standard Promises
+   * rather than instantiating new RemoteState subclasses.
+   */
+  static get [Symbol.species](): PromiseConstructor;
 }
 //#endregion
 export { IRPCReader };

package/dist/reader.js

@@ -9,9 +9,16 @@ import { replay } from "@anchorlib/core";
 * @template T - The type of data yielded by the stream.
 */
 var IRPCReader = class extends RemoteState {
-	packets = /* @__PURE__ */ new Set();
-	constructor(id, init) {
-		super(init);
+	onClose;
+	/**
+	* Initializes a new RemoteState with an optional initial payload.
+	*
+	* @param id - The unique identifier for this state instance.
+	* @param init - An optional starting value for the data payload.
+	* @param status - The initial status of the state (PENDING, SUCCESS, ERROR).
+	*/
+	constructor(id, init, status = IRPC_STATUS.PENDING) {
+		super(init, status);
 		this.id = id;
 	}
 	/**
@@ -22,7 +29,6 @@ var IRPCReader = class extends RemoteState {
 	*/
 	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);
@@ -31,6 +37,18 @@ var IRPCReader = class extends RemoteState {
 		}
 		this.status = packet.status;
 	}
+	close() {
+		this.status = IRPC_STATUS.SUCCESS;
+		super.close();
+		this.onClose?.();
+	}
+	/**
+	* Ensures that chained Promise operations return standard Promises
+	* rather than instantiating new RemoteState subclasses.
+	*/
+	static get [Symbol.species]() {
+		return Promise;
+	}
 };
 
 //#endregion

package/dist/resolver.js

@@ -70,6 +70,11 @@ var IRPCResolver = class {
 	*/
 	async forward({ id, name, args }, schema) {
 		try {
+			await this.module.resolveHooks({
+				id,
+				name,
+				args
+			});
 			const result = this.module.resolve({
 				id,
 				name,

package/dist/router.d.ts

@@ -0,0 +1,42 @@
+import { IRPCTransport } from "./transport.js";
+import { IRPCRequest } from "./types.js";
+import { IRPCPackage } from "./module.js";
+
+//#region src/router.d.ts
+type IRPCHook = () => void | Promise<void>;
+declare class IRPCRouter {
+  module: IRPCPackage;
+  transport: IRPCTransport;
+  /** Array of middleware functions to be executed */
+  hooks: IRPCHook[];
+  /**
+   * Creates a new Router instance
+   * @param {IRPCPackage} module - The IRPC package module to resolve requests against
+   * @param {IRPCTransport} transport - The transport mechanism to use for resolving requests
+   */
+  constructor(module: IRPCPackage, transport: IRPCTransport);
+  /**
+   * Adds a hook function to the router
+   * @param hook - The hook function to add
+   * @returns The current Router instance for chaining
+   */
+  use(hook: IRPCHook): this;
+  /**
+   * Resolves hook functions for a given request
+   * @param req - The IRPC request to process hook for
+   * @returns An error response if hook fails, undefined otherwise
+   */
+  protected resolveHooks(req: IRPCRequest): Promise<{
+    id: string;
+    name: string;
+    type: "close";
+    status: "error";
+    error: {
+      code: string;
+      message: string;
+    };
+    createdAt: number;
+  } | undefined>;
+}
+//#endregion
+export { IRPCHook, IRPCRouter };

package/dist/router.js

@@ -0,0 +1,59 @@
+import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
+import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { IRPC_STORE } from "./store.js";
+
+//#region src/router.ts
+var IRPCRouter = class {
+	/** Array of middleware functions to be executed */
+	hooks = [];
+	/**
+	* Creates a new Router instance
+	* @param {IRPCPackage} module - The IRPC package module to resolve requests against
+	* @param {IRPCTransport} transport - The transport mechanism to use for resolving requests
+	*/
+	constructor(module, transport) {
+		this.module = module;
+		this.transport = transport;
+		IRPC_STORE.route(this);
+	}
+	/**
+	* Adds a hook function to the router
+	* @param hook - The hook function to add
+	* @returns The current Router instance for chaining
+	*/
+	use(hook) {
+		if (typeof hook !== "function") {
+			const error = new Error(ERROR_MESSAGE[ERROR_CODE.INVALID_HOOK]);
+			IRPC_STORE.error(error);
+			return this;
+		}
+		this.hooks.push(hook);
+		return this;
+	}
+	/**
+	* Resolves hook functions for a given request
+	* @param req - The IRPC request to process hook for
+	* @returns An error response if hook fails, undefined otherwise
+	*/
+	async resolveHooks(req) {
+		for (const hook of this.hooks) try {
+			await hook();
+		} catch (error) {
+			IRPC_STORE.error(error, [req.id, req.name]);
+			return {
+				id: req.id,
+				name: req.name,
+				type: IRPC_PACKET_TYPE.CLOSE,
+				status: IRPC_STATUS.ERROR,
+				error: {
+					code: ERROR_CODE.UNKNOWN,
+					message: ERROR_MESSAGE[ERROR_CODE.UNKNOWN]
+				},
+				createdAt: Date.now()
+			};
+		}
+	}
+};
+
+//#endregion
+export { IRPCRouter };

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/server/index.js

@@ -0,0 +1,15 @@
+import { setAsyncScope, setReactive } from "@anchorlib/core";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/server/index.ts
+var AnchorASL = class extends AsyncLocalStorage {
+	store = /* @__PURE__ */ new Map();
+	getStore() {
+		return super.getStore() ?? this.store;
+	}
+};
+setAsyncScope(new AnchorASL());
+setReactive(false);
+
+//#endregion
+export {  };

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { IRPCReadable, IRPCStatus } from "./types.js";
+import { IRPCReadable, IRPCStatus, StreamConstructor } from "./types.js";
 import * as _anchorlib_core0 from "@anchorlib/core";
 import { StateSubscriber } from "@anchorlib/core";
 
@@ -14,9 +14,8 @@ import { StateSubscriber } from "@anchorlib/core";
  * @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;
+  #private;
+  get state(): IRPCReadable<T>;
   /**
    * The current data payload of the state.
    */
@@ -37,8 +36,12 @@ declare class RemoteState<T> extends Promise<T> {
    * Initializes a new RemoteState with an optional initial payload.
    *
    * @param init - An optional starting value for the data payload.
+   * @param status - The initial status of the state (PENDING, SUCCESS, ERROR).
    */
-  constructor(init?: T);
+  constructor(init?: T, status?: IRPCStatus);
+  accept(value?: T): void;
+  reject(error?: Error): void;
+  abort(): void;
   /**
    * Subscribes to changes emitted by the internal state.
    *
@@ -46,6 +49,10 @@ declare class RemoteState<T> extends Promise<T> {
    * @returns An unsubscribe function to terminate the listener.
    */
   subscribe(handler: StateSubscriber<IRPCReadable<T>>): _anchorlib_core0.StateUnsubscribe;
+  /**
+   * Closes the reactive state and terminates the underlying Promise.
+   */
+  close(): void;
   /**
    * Destroys the reactive state bindings.
    */
@@ -56,17 +63,6 @@ declare class RemoteState<T> extends Promise<T> {
    */
   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
@@ -79,4 +75,4 @@ type StreamConstructor<T> = (data: T, resolve: (value?: T) => void, reject: (err
  */
 declare function stream<T>(construct: StreamConstructor<T>, init?: T): RemoteState<T>;
 //#endregion
-export { RemoteState, StreamConstructor, stream };
+export { RemoteState, stream };