@irpclib/irpc 0.0.1 → 1.0.0-beta.16

package/dist/module.js

@@ -1,156 +1,176 @@
-import { batch } from "./batch.js";
-import { IRPCCall } from "./call.js";
+import { IRPCCacher } from "./cache.js";
+import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+import { IRPCTransport } from "./transport.js";
 
 //#region src/module.ts
 const DEFAULT_TIMEOUT = 2e4;
+const NAME_CONSTRAINT = /^[a-zA-Z0-9_]+$/;
+const VERSION_CONSTRAINT = /^[0-9]+\.[0-9]+\.[0-9]+$/;
 /**
-* Creates an IRPC module with the given configuration.
-*
-* This function initializes a new IRPC module with a store for tracking RPC calls,
-* a registry for mapping functions to their specifications, and various methods
-* for managing and executing remote procedure calls.
-*
-* @param config - Optional partial configuration for the IRPC module, excluding 'submit' and 'transport'
-* @returns An IRPC factory function with attached utility methods
+* IRPCPackage represents a package containing multiple IRPC (Isomorphic-RPC) specifications
+* and their corresponding stubs. It manages the configuration, transport, and execution
+* of remote procedure calls.
 */
-function createModule(config) {
-	const store = /* @__PURE__ */ new Map();
-	const registry = /* @__PURE__ */ new WeakMap();
-	const module = {
-		name: "irpc",
+var IRPCPackage = class {
+	/**
+	* A map storing all IRPC specifications by their names
+	*/
+	specs = /* @__PURE__ */ new Map();
+	/**
+	* A weak map linking stub functions to their corresponding specifications
+	*/
+	stubs = /* @__PURE__ */ new WeakMap();
+	/**
+	* A map storing caches for each IRPC Entry
+	*/
+	cache = /* @__PURE__ */ new WeakMap();
+	/**
+	* Configuration object for the IRPC package
+	*/
+	config = {
+		name: "global",
 		version: "1.0.0",
-		timeout: DEFAULT_TIMEOUT,
-		...config
+		timeout: DEFAULT_TIMEOUT
 	};
 	/**
-	* Factory function that creates IRPC handlers based on specifications.
-	* Each handler can either execute a local function or make a remote call.
+	* Gets the href URL for this package in the format "name/version"
 	*/
-	const factory = ((spec) => {
-		const host = { ...spec };
-		store.set(host.name, host);
-		const fn = ((...args) => {
-			if (typeof host.handler === "function") return host.handler(...args);
-			else return remoteCall(module, host, ...args);
-		});
-		registry.set(fn, host);
-		return fn;
-	});
+	get href() {
+		return [this.config.name, this.config.version].join("/");
+	}
 	/**
-	* Returns the namespace information of the module (name and version).
+	* Gets the package information (name, version, and optional description)
 	*/
-	Object.defineProperty(factory, "namespace", { get: () => ({
-		name: module.name,
-		version: module.version
-	}) });
+	get info() {
+		const { name, version, description } = this.config;
+		return {
+			name,
+			version,
+			description
+		};
+	}
 	/**
-	* Associates a handler function with an IRPC specification.
-	* @param irpc - The IRPC function to construct
-	* @param handler - The actual implementation of the IRPC function
+	* Gets the transport mechanism used for remote calls
 	*/
-	factory.construct = ((irpc, handler) => {
-		if (typeof irpc !== "function") throw new Error("Invalid IRPC.");
-		const host = registry.get(irpc);
-		if (!host) throw new Error("IRPC can not be found.");
-		host.handler = handler;
-	});
+	get transport() {
+		return this.config.transport;
+	}
 	/**
-	* Sets the transport mechanism for the module.
-	* @param transport - The transport layer to use for remote calls
+	* Creates a new IRPCPackage instance
+	* @param config - Optional partial configuration for the package
+	* @throws Error if the package name or version doesn't match the required format
 	*/
-	factory.use = ((transport) => {
-		if (typeof transport?.send !== "function") throw new Error("Invalid transport.");
-		module.transport = transport;
-	});
+	constructor(config) {
+		this.configure(config ?? {});
+	}
 	/**
-	* Retrieves an IRPC specification by name.
-	* @param name - The name of the IRPC to retrieve
-	* @returns The IRPC specification or undefined if not found
+	* Declares a new IRPC specification and creates a corresponding stub function
+	* @param init - 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
 	*/
-	factory.get = ((name) => {
-		return store.get(name);
-	});
+	declare(init) {
+		if (this.specs.has(init.name)) throw new Error(`IRPC ${init.name} already exists.`);
+		const spec = { ...init };
+		const caches = new IRPCCacher();
+		const timeout = spec.timeout ?? this.config.timeout;
+		const stub = (async (...args) => {
+			if (typeof spec.handler === "function") return spec.handler(...args);
+			if (!this.transport) throw new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_MISSING]);
+			if (spec.maxAge) {
+				const key = JSON.stringify(args);
+				const cache = caches.get(key);
+				if (cache) return cache.value;
+				const data = await this.transport.call(spec, args, timeout);
+				caches.set(key, data, spec.maxAge);
+				return data;
+			}
+			return await this.transport.call(spec, args, timeout);
+		});
+		this.specs.set(init.name, spec);
+		this.stubs.set(stub, spec);
+		this.cache.set(stub, caches);
+		return stub;
+	}
 	/**
-	* Updates the module configuration.
-	* @param config - Configuration properties to update
+	* 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
 	*/
-	factory.configure = ((config$1) => {
-		Object.assign(module, { ...config$1 });
-	});
+	async 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);
+	}
 	/**
-	* Retrieves information about an IRPC by its request details.
-	* @param req - Request containing the name of the IRPC to look up
+	* Associates a handler function with a stub function
+	* @param stub - The stub function created by declare()
+	* @param handler - The actual implementation function
+	* @returns This IRPCPackage instance for chaining
+	* @throws Error if the stub or handler is invalid, or if no IRPC exists for the stub
+	*/
+	construct(stub, handler) {
+		if (typeof stub !== "function") throw new Error(ERROR_MESSAGE[ERROR_CODE.STUB_INVALID]);
+		if (typeof handler !== "function") throw new Error(ERROR_MESSAGE[ERROR_CODE.INVALID_HANDLER]);
+		const spec = this.stubs.get(stub);
+		if (!spec?.name) throw new Error(ERROR_MESSAGE[ERROR_CODE.NOT_FOUND]);
+		spec.handler = handler;
+		return this;
+	}
+	/**
+	* Sets the transport mechanism for this package
+	* @param transport - The transport instance to use for remote calls
+	* @returns This IRPCPackage instance for chaining
+	* @throws Error if the transport is not a valid Transport instance
+	*/
+	use(transport) {
+		if (!(transport instanceof IRPCTransport)) throw new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_INVALID]);
+		this.config.transport = transport;
+		return this;
+	}
+	/**
+	* Retrieves an IRPC specification by name or request object
+	* @param query - Either a string name or an IRPCRequest object
 	* @returns The IRPC specification or undefined if not found
 	*/
-	factory.info = ((req) => {
-		return store.get(req.name);
-	});
+	get(query) {
+		if (typeof query === "string") return this.specs.get(query);
+		return this.specs.get(query.name);
+	}
 	/**
-	* Resolves and executes an IRPC call with the provided arguments.
-	* @param req - Request containing the name and arguments for the IRPC call
-	* @returns The result of executing the IRPC handler
+	* Updates the package configuration
+	* @param config - Partial configuration object with properties to update
+	* @returns This IRPCPackage instance for chaining
+	* @throws Error if the provided name or version is invalid
 	*/
-	factory.resolve = ((req) => {
-		const host = store.get(req.name);
-		if (!host) throw new Error("IRPC can not be found.");
-		if (!host.handler) throw new Error("IRPC handler can not be found.");
-		return host.handler(...req.args);
-	});
+	configure(config) {
+		if (config.name && !NAME_CONSTRAINT.test(config.name)) throw new Error(`Invalid IRPC name: ${config.name}`);
+		if (config.version && !VERSION_CONSTRAINT.test(config.version)) throw new Error(`Invalid IRPC version: ${config.version}`);
+		Object.assign(this.config, config);
+		return this;
+	}
 	/**
-	* Submits a batch of IRPC calls for execution via the transport layer.
-	* @param calls - Array of IRPC calls to submit
+	* Invalidates the cache for a specific stub and arguments combination
+	* @param stub - The IRPC stub function whose cache needs to be invalidated
+	* @param args - The arguments array used as cache key
 	*/
-	module.submit = ((calls) => {
-		try {
-			const promise = module.transport.send(calls);
-			if (promise instanceof Promise) promise.catch((reason) => {
-				calls.forEach((call) => {
-					call.reject(reason);
-				});
-			});
-		} catch (error) {
-			calls.forEach((call) => {
-				call.reject(error);
-			});
-		}
-	});
-	return factory;
-}
+	invalidate(stub, ...args) {
+		const caches = this.cache.get(stub);
+		if (!caches) return;
+		if (args.length) caches.delete(JSON.stringify(args));
+		else caches.clear();
+	}
+};
 /**
-* Executes a remote procedure call through the configured transport layer.
-*
-* This function creates an IRPC call payload and sends it through the module's transport mechanism.
-* It handles timeouts and promise resolution/rejection based on the response.
-*
-* @param module - The IRPC module containing transport and configuration
-* @param spec - The IRPC specification defining the remote procedure
-* @param args - Arguments to pass to the remote procedure
-* @returns A promise that resolves with the remote call result or rejects with an error
-* @throws Error if no transport is configured or if the call times out
+* Creates a new IRPCPackage instance with the given configuration
+* @param config - Optional partial configuration for the package
+* @returns A new IRPCPackage instance
 */
-function remoteCall(module, spec, ...args) {
-	const payload = {
-		name: spec.name,
-		args
-	};
-	return new Promise((resolve, reject) => {
-		if (!module.transport) {
-			reject(/* @__PURE__ */ new Error("IRPC transport can not be found."));
-			return;
-		}
-		const timeout = module.timeout ? setTimeout(() => {
-			call.reject(/* @__PURE__ */ new Error("IRPC timeout."));
-		}, module.timeout) : void 0;
-		const call = new IRPCCall(payload, (value) => {
-			resolve(value);
-			clearTimeout(timeout);
-		}, (reason) => {
-			reject(reason);
-			clearTimeout(timeout);
-		});
-		batch(call, module.submit);
-	});
+function createPackage(config) {
+	return new IRPCPackage(config);
 }
 
 //#endregion
-export { createModule };
+export { IRPCPackage, createPackage };

package/dist/resolver.d.ts

@@ -0,0 +1,61 @@
+import { IRPCDataSchema, IRPCError, IRPCInputs, IRPCOutput, IRPCRequest, IRPCResponse, IRPCSpec } from "./types.js";
+import { IRPCPackage } from "./module.js";
+
+//#region src/resolver.d.ts
+
+/**
+ * Resolver class for handling IRPC requests
+ *
+ * This class is responsible for resolving IRPC requests by validating inputs,
+ * executing the requested method, and formatting the response.
+ */
+declare class IRPCResolver {
+  req: IRPCRequest;
+  module: IRPCPackage;
+  /**
+   * Getter for the specification of the RPC method
+   *
+   * Retrieves the specification of the RPC method from the module based on the request
+   */
+  get spec(): IRPCSpec<IRPCInputs, IRPCDataSchema> | undefined;
+  /**
+   * Creates a new IRPCResolver instance
+   *
+   * @param req - The IRPC request object containing id, name and arguments
+   * @param module - The IRPC package module that contains the method to be executed
+   */
+  constructor(req: IRPCRequest, module: IRPCPackage);
+  /**
+   * Resolves an IRPC request
+   *
+   * This method validates the request, parses inputs according to the schema,
+   * and forwards the request to the appropriate handler.
+   *
+   * @returns A promise that resolves to an IRPC response with either the result or an error
+   */
+  resolve(): Promise<IRPCResponse>;
+  /**
+   * Forwards a validated request to the module's resolver
+   *
+   * @param req - The validated IRPC request object
+   * @param schema - Optional output schema for result validation
+   * @returns A promise that resolves to an IRPC response with the result or an error
+   */
+  forward({
+    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;
+  }>;
+}
+//#endregion
+export { IRPCResolver };

package/dist/resolver.js

@@ -0,0 +1,143 @@
+import { ERROR_CODE } from "./error.js";
+
+//#region src/resolver.ts
+/**
+* Resolver class for handling IRPC requests
+*
+* This class is responsible for resolving IRPC requests by validating inputs,
+* executing the requested method, and formatting the response.
+*/
+var IRPCResolver = class {
+	/**
+	* Getter for the specification of the RPC method
+	*
+	* Retrieves the specification of the RPC method from the module based on the request
+	*/
+	get spec() {
+		return this.module.get(this.req);
+	}
+	/**
+	* Creates a new IRPCResolver instance
+	*
+	* @param req - The IRPC request object containing id, name and arguments
+	* @param module - The IRPC package module that contains the method to be executed
+	*/
+	constructor(req, module) {
+		this.req = req;
+		this.module = module;
+	}
+	/**
+	* Resolves an IRPC request
+	*
+	* This method validates the request, parses inputs according to the schema,
+	* and forwards the request to the appropriate handler.
+	*
+	* @returns A promise that resolves to an IRPC response with either the result or an error
+	*/
+	async resolve() {
+		const { id, name, args } = this.req;
+		if (!this.spec) return {
+			id,
+			name,
+			error: {
+				code: ERROR_CODE.NOT_FOUND,
+				message: `IRPC "${name}" does not exist.`
+			}
+		};
+		const { schema } = this.spec;
+		const inputs = parseInput(args, schema?.input);
+		if (!inputs.success) return {
+			id,
+			name,
+			error: {
+				code: ERROR_CODE.INVALID_INPUT,
+				message: inputs.error
+			}
+		};
+		return this.forward({
+			id,
+			name,
+			args: inputs.data
+		}, schema?.output);
+	}
+	/**
+	* Forwards a validated request to the module's resolver
+	*
+	* @param req - The validated IRPC request object
+	* @param schema - Optional output schema for result validation
+	* @returns A promise that resolves to an IRPC response with the result or an error
+	*/
+	async forward({ id, name, args }, schema) {
+		try {
+			const output = parseOutput(await this.module.resolve({
+				id,
+				name,
+				args
+			}), schema);
+			if (output.success) return {
+				id,
+				name,
+				result: output.data
+			};
+			else return {
+				id,
+				name,
+				error: {
+					code: ERROR_CODE.INVALID_OUTPUT,
+					message: output.error?.message
+				}
+			};
+		} catch (error) {
+			return {
+				id,
+				name,
+				error: {
+					code: ERROR_CODE.UNKNOWN,
+					message: error.message
+				}
+			};
+		}
+	}
+};
+/**
+* Parses and validates input arguments against their schemas
+*
+* @param args - Array of input arguments
+* @param schema - Optional schema for validating the arguments
+* @returns Parsed result with success status and any error messages
+*/
+function parseInput(args, schema) {
+	if (schema && args.length !== schema.length) return {
+		data: args,
+		success: false,
+		error: "Invalid arguments"
+	};
+	const parsed = args.map((arg, i) => {
+		const input = schema?.[i];
+		return input ? input.safeParse(arg) : {
+			success: true,
+			data: arg
+		};
+	});
+	return {
+		data: parsed.map((arg) => arg.data),
+		error: parsed.filter((arg) => !arg.success).map((arg) => arg.error?.message).join("\n"),
+		success: parsed.every((arg) => arg.success)
+	};
+}
+/**
+* Parses and validates output result against its schema
+*
+* @param result - The result to validate
+* @param schema - Optional schema for validating the result
+* @returns Parsed result with success status and any error messages
+*/
+function parseOutput(result, schema) {
+	return schema ? schema.safeParse(result) : {
+		success: true,
+		data: result
+	};
+}
+
+//#endregion
+export { IRPCResolver };

package/dist/transport.d.ts

@@ -0,0 +1,45 @@
+import { IRPCData, IRPCInputs, IRPCOutput, IRPCSpec, TransportConfig } from "./types.js";
+import { IRPCCall } from "./call.js";
+
+//#region src/transport.d.ts
+
+/**
+ * IRPCTransport is responsible for managing and dispatching RPC calls.
+ * It handles queuing, debouncing, and timeout management for RPC requests.
+ */
+declare class IRPCTransport {
+  config?: TransportConfig | undefined;
+  /**
+   * A set of pending RPC calls that are queued for execution.
+   */
+  queue: Set<IRPCCall>;
+  /**
+   * Creates a new IRPCTransport instance.
+   * @param config - Optional transport configuration including timeout and debounce settings.
+   */
+  constructor(config?: TransportConfig | undefined);
+  /**
+   * 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.
+   * @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>;
+  /**
+   * 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;
+  /**
+   * Dispatches a batch of RPC calls. This base implementation rejects all calls
+   * with a "not implemented" error. Subclasses should override this method to
+   * provide actual transport mechanism.
+   * @param calls - An array of RPC calls to dispatch.
+   * @returns A promise that resolves when all calls have been processed.
+   */
+  protected dispatch(calls: IRPCCall[]): Promise<void>;
+}
+//#endregion
+export { IRPCTransport };

package/dist/transport.js

@@ -0,0 +1,74 @@
+import { IRPCCall } from "./call.js";
+import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
+
+//#region src/transport.ts
+/**
+* IRPCTransport is responsible for managing and dispatching RPC calls.
+* It handles queuing, debouncing, and timeout management for RPC requests.
+*/
+var IRPCTransport = class {
+	/**
+	* A set of pending RPC calls that are queued for execution.
+	*/
+	queue = /* @__PURE__ */ new Set();
+	/**
+	* Creates a new IRPCTransport instance.
+	* @param config - Optional transport configuration including timeout and debounce settings.
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* 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.
+	* @returns A promise that resolves with the RPC response data or rejects with an error.
+	*/
+	call(spec, args, timeout = this.config?.timeout) {
+		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);
+		});
+	}
+	/**
+	* 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.
+	*/
+	schedule(call) {
+		if (!this.queue.size) setTimeout(() => {
+			this.dispatch(Array.from(this.queue));
+			this.queue.clear();
+		}, this.config?.debounce ?? 0);
+		this.queue.add(call);
+	}
+	/**
+	* Dispatches a batch of RPC calls. This base implementation rejects all calls
+	* with a "not implemented" error. Subclasses should override this method to
+	* provide actual transport mechanism.
+	* @param calls - An array of RPC calls to dispatch.
+	* @returns A promise that resolves when all calls have been processed.
+	*/
+	async dispatch(calls) {
+		calls.forEach((call) => {
+			call.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]));
+		});
+	}
+};
+
+//#endregion
+export { IRPCTransport };