@irpclib/irpc 1.0.0-beta.24 → 1.0.0

package/dist/adapter.d.ts

@@ -0,0 +1,76 @@
+import { IRPCCrudMeta, IRPCData, IRPCDriver, IRPCStub } from "./types.js";
+import { IRPCPackage } from "./module.js";
+
+//#region src/adapter.d.ts
+declare class NextDriver extends Error {
+  constructor();
+}
+/** Extracts operational method names from an adapter, excluding its own API. */
+type AttachableMethod<T> = string & keyof Omit<T, 'attach' | 'use' | 'dispatch'>;
+type AnyStub = IRPCStub<any, any[], any>;
+/**
+ * Attaches handlers to IRPC stubs and bridges them to drivers.
+ * Dispatches calls through the registered driver chain.
+ */
+declare class IRPCAdapter {
+  private module;
+  private drivers;
+  constructor(module: IRPCPackage);
+  /**
+   * Runs a get operation through the driver chain
+   * @param meta - Resolved entity metadata
+   * @param id - The entity identifier
+   */
+  get(meta: IRPCCrudMeta, id: IRPCData): Promise<IRPCData> | IRPCData;
+  /**
+   * Runs a create operation through the driver chain
+   * @param meta - Resolved entity metadata
+   * @param data - The entity data to create
+   */
+  create(meta: IRPCCrudMeta, data: IRPCData): Promise<IRPCData> | IRPCData;
+  /**
+   * Runs an update operation through the driver chain
+   * @param meta - Resolved entity metadata
+   * @param id - The entity identifier
+   * @param data - The entity data to update
+   */
+  update(meta: IRPCCrudMeta, id: IRPCData, data: IRPCData): Promise<IRPCData> | IRPCData;
+  /**
+   * Runs a delete operation through the driver chain
+   * @param meta - Resolved entity metadata
+   * @param id - The entity identifier
+   */
+  delete(meta: IRPCCrudMeta, id: IRPCData): Promise<IRPCData> | IRPCData;
+  /**
+   * Dispatches a method call through each registered driver in order
+   * @param method - The method name to dispatch
+   * @param meta - Resolved entity metadata
+   * @param args - Arguments forwarded to the driver method
+   * @throws CrudError.notImplemented if no driver handles the method
+   */
+  protected dispatch(method: string, meta: IRPCCrudMeta, ...args: IRPCData[]): Promise<IRPCData> | IRPCData;
+  /**
+   * Attaches a single stub to a specific method on this adapter
+   * @param stub - The stub function to attach
+   * @param method - The method name matching an adapter operation
+   * @throws CrudError.notFound if the stub is not registered in the package
+   */
+  attach(stub: AnyStub, method: AttachableMethod<this>): this;
+  /**
+   * Attaches stubs to this adapter by matching object keys to adapter methods
+   * @param stubs - Object mapping method names to stub functions
+   * @throws CrudError.notFound if a stub is not registered in the package
+   */
+  attach(stubs: Partial<Record<AttachableMethod<this>, AnyStub>>): this;
+  /**
+   * Registers a driver to handle dispatched operations
+   * @param driver - The driver implementation
+   */
+  use(driver: IRPCDriver): this;
+  /**
+   * Signals the current driver to pass execution to the next driver in the chain
+   */
+  static next(): NextDriver;
+}
+//#endregion
+export { IRPCAdapter };

package/dist/adapter.js

@@ -0,0 +1,109 @@
+import { CrudError } from "./error.js";
+
+//#region src/adapter.ts
+var NextDriver = class extends Error {
+	constructor() {
+		super("Next driver");
+	}
+};
+/**
+* Attaches handlers to IRPC stubs and bridges them to drivers.
+* Dispatches calls through the registered driver chain.
+*/
+var IRPCAdapter = class {
+	drivers = /* @__PURE__ */ new Set();
+	constructor(module) {
+		this.module = module;
+	}
+	/**
+	* Runs a get operation through the driver chain
+	* @param meta - Resolved entity metadata
+	* @param id - The entity identifier
+	*/
+	get(meta, id) {
+		return this.dispatch("get", meta, id);
+	}
+	/**
+	* Runs a create operation through the driver chain
+	* @param meta - Resolved entity metadata
+	* @param data - The entity data to create
+	*/
+	create(meta, data) {
+		return this.dispatch("create", meta, data);
+	}
+	/**
+	* Runs an update operation through the driver chain
+	* @param meta - Resolved entity metadata
+	* @param id - The entity identifier
+	* @param data - The entity data to update
+	*/
+	update(meta, id, data) {
+		return this.dispatch("update", meta, id, data);
+	}
+	/**
+	* Runs a delete operation through the driver chain
+	* @param meta - Resolved entity metadata
+	* @param id - The entity identifier
+	*/
+	delete(meta, id) {
+		return this.dispatch("delete", meta, id);
+	}
+	/**
+	* Dispatches a method call through each registered driver in order
+	* @param method - The method name to dispatch
+	* @param meta - Resolved entity metadata
+	* @param args - Arguments forwarded to the driver method
+	* @throws CrudError.notImplemented if no driver handles the method
+	*/
+	dispatch(method, meta, ...args) {
+		for (const driver of this.drivers) {
+			const fn = driver[method];
+			if (!fn) continue;
+			try {
+				return fn(meta, ...args);
+			} catch (err) {
+				if (err instanceof NextDriver) continue;
+				throw err;
+			}
+		}
+		throw CrudError.notImplemented(method);
+	}
+	attach(stubOrStubs, m) {
+		const stubs = m ? { [m]: stubOrStubs } : stubOrStubs;
+		const key = this.module.config.key ?? "id";
+		for (const [method, stub] of Object.entries(stubs)) {
+			if (!stub) continue;
+			const spec = this.module["stubs"].get(stub);
+			if (!spec) throw CrudError.notFound();
+			const meta = {
+				name: spec.name.replace(`.${method}`, ""),
+				key,
+				description: spec.description,
+				schema: spec.schema,
+				maxAge: spec.maxAge,
+				coalesce: spec.coalesce
+			};
+			this.module.construct(stub, ((...args) => {
+				return this[method](meta, ...args);
+			}));
+		}
+		return this;
+	}
+	/**
+	* Registers a driver to handle dispatched operations
+	* @param driver - The driver implementation
+	*/
+	use(driver) {
+		this.drivers.add(driver);
+		return this;
+	}
+	/**
+	* Signals the current driver to pass execution to the next driver in the chain
+	*/
+	static next() {
+		return new NextDriver();
+	}
+};
+
+//#endregion
+export { IRPCAdapter };

package/dist/call.d.ts

@@ -12,7 +12,9 @@ declare const DEFAULT_RETRY_DELAY = 1000;
 declare class IRPCCall {
   transport: IRPCTransport;
   payload: IRPCPayload;
-  options: IRPCCallConfig;
+  options: IRPCCallConfig & {
+    seed?: () => IRPCData;
+  };
   /**
    * Unique identifier for this RPC call, generated using shortId().
    */
@@ -51,7 +53,9 @@ declare class IRPCCall {
    * @param payload - The RPC payload containing method and parameters
    * @param options - Options for the call, such as timeout, maxRetries, etc.
    */
-  constructor(transport: IRPCTransport, payload: IRPCPayload, options: IRPCCallConfig, reader?: IRPCReader<IRPCData>);
+  constructor(transport: IRPCTransport, payload: IRPCPayload, options: IRPCCallConfig & {
+    seed?: () => IRPCData;
+  }, reader?: IRPCReader<IRPCData>);
   enqueue(packet: IRPCPacketStream<IRPCData>): void;
   /**
    * Resolves the RPC call with the provided value.

package/dist/call.js

@@ -1,5 +1,5 @@
+import { CallError } from "./error.js";
 import { IRPC_PACKET_TYPE, IRPC_STATUS } from "./enum.js";
-import { ERROR_CODE, ERROR_MESSAGE } from "./error.js";
 import { IRPCReader } from "./reader.js";
 import { IRPC_STORE } from "./store.js";
 import { uuid } from "@anchorlib/core";
@@ -60,16 +60,13 @@ var IRPCCall = class {
 				name: this.payload.name,
 				type: IRPC_PACKET_TYPE.CLOSE,
 				status: IRPC_STATUS.ERROR,
-				error: {
-					code: ERROR_CODE.TIMEOUT,
-					message: ERROR_MESSAGE[ERROR_CODE.TIMEOUT]
-				},
+				error: CallError.timeout().json(),
 				createdAt: Date.now()
 			});
 			clearTimeout(this.retryId);
-			this.reject(new Error(ERROR_MESSAGE[ERROR_CODE.TIMEOUT]), false);
+			this.reject(CallError.timeout(), false);
 		}, options.timeout);
-		this.reader = reader ?? new IRPCReader(uuid(), options?.init?.());
+		this.reader = reader ?? new IRPCReader(uuid(), options?.seed?.());
 		this.reader.onClose = () => this.close();
 		this.id = this.reader.id;
 	}
@@ -105,7 +102,7 @@ var IRPCCall = class {
 		if (maxRetries && retriable) {
 			if (reason) this.retryReasons.add(reason);
 			if (this.retries >= maxRetries) {
-				IRPC_STORE.error(/* @__PURE__ */ new Error(`${ERROR_MESSAGE[ERROR_CODE.CALL_MAX_RETRIES_REACHED]}: ${Array.from(this.retryReasons).map((r) => r.message).join(", ")}`), [{
+				IRPC_STORE.error(CallError.maxRetries(this.retryReasons), [{
 					id: this.id,
 					name: this.payload.name
 				}]);

package/dist/enum.d.ts

@@ -4,15 +4,6 @@ declare const IRPC_PACKET_TYPE: {
   readonly EVENT: "event";
   readonly CLOSE: "close";
   readonly ANSWER: "answer";
-  readonly REQUEST: "request";
-  readonly RESPONSE: "response";
-};
-declare const IRPC_DATA_TYPE: {
-  readonly ARRAY: "array";
-  readonly OBJECT: "object";
-  readonly READABLE: "readable";
-  readonly WRITABLE: "writable";
-  readonly PRIMITIVE: "primitive";
 };
 declare const IRPC_STATUS: {
   readonly IDLE: "idle";
@@ -40,4 +31,4 @@ declare const IRPC_FILE_STATUS: {
   readonly ERROR: "error";
 };
 //#endregion
-export { IRPC_BASE_CONTEXT, IRPC_DATA_TYPE, IRPC_FILE_STATUS, IRPC_PACKET_TYPE, IRPC_STATUS, IRPC_STORE_EVENT };
+export { IRPC_BASE_CONTEXT, IRPC_FILE_STATUS, IRPC_PACKET_TYPE, IRPC_STATUS, IRPC_STORE_EVENT };

package/dist/enum.js

@@ -3,16 +3,7 @@ const IRPC_PACKET_TYPE = {
 	CALL: "call",
 	EVENT: "event",
 	CLOSE: "close",
-	ANSWER: "answer",
-	REQUEST: "request",
-	RESPONSE: "response"
-};
-const IRPC_DATA_TYPE = {
-	ARRAY: "array",
-	OBJECT: "object",
-	READABLE: "readable",
-	WRITABLE: "writable",
-	PRIMITIVE: "primitive"
+	ANSWER: "answer"
 };
 const IRPC_STATUS = {
 	IDLE: "idle",
@@ -41,4 +32,4 @@ const IRPC_FILE_STATUS = {
 };
 
 //#endregion
-export { IRPC_BASE_CONTEXT, IRPC_DATA_TYPE, IRPC_FILE_STATUS, IRPC_PACKET_TYPE, IRPC_STATUS, IRPC_STORE_EVENT };
+export { IRPC_BASE_CONTEXT, IRPC_FILE_STATUS, IRPC_PACKET_TYPE, IRPC_STATUS, IRPC_STORE_EVENT };

package/dist/error.d.ts

@@ -1,61 +1,127 @@
+import { IRPCPacketError } from "./types.js";
+
 //#region src/error.d.ts
-declare const ERROR_CODE: {
-  UNKNOWN: string;
-  TIMEOUT: string;
-  NOT_FOUND: string;
-  NOT_SUPPORTED: string;
-  INVALID_TYPE: string;
-  INVALID_STATE: string;
-  INVALID_VALUE: string;
-  INVALID_INPUT: string;
-  INVALID_OUTPUT: string;
-  NOT_IMPLEMENTED: string;
-  INVALID_HANDLER: string;
-  INVALID_OPERATION: string;
-  INVALID_HOOK: string;
-  TRANSPORT_MISSING: string;
-  TRANSPORT_INVALID: string;
-  TRANSPORT_NOT_IMPLEMENTED: string;
-  STUB_MISSING: string;
-  STUB_INVALID: string;
-  STUB_NOT_IMPLEMENTED: string;
-  RESOLVER_MISSING: string;
-  RESOLVER_NOT_IMPLEMENTED: string;
-  RESOLVER_NOT_FOUND: string;
-  RESOLVER_NOT_SUPPORTED: string;
-  STREAM_ERROR: string;
-  HANDLER_ERROR: string;
-  RESOLVE_ERROR: string;
-  CALL_MAX_RETRIES_REACHED: string;
-};
-type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
-declare const ERROR_MESSAGE: {
-  [ERROR_CODE.UNKNOWN]: string;
-  [ERROR_CODE.TIMEOUT]: string;
-  [ERROR_CODE.NOT_FOUND]: string;
-  [ERROR_CODE.NOT_SUPPORTED]: string;
-  [ERROR_CODE.INVALID_TYPE]: string;
-  [ERROR_CODE.INVALID_STATE]: string;
-  [ERROR_CODE.INVALID_VALUE]: string;
-  [ERROR_CODE.INVALID_INPUT]: string;
-  [ERROR_CODE.INVALID_OUTPUT]: string;
-  [ERROR_CODE.NOT_IMPLEMENTED]: string;
-  [ERROR_CODE.INVALID_HANDLER]: string;
-  [ERROR_CODE.INVALID_OPERATION]: string;
-  [ERROR_CODE.INVALID_HOOK]: string;
-  [ERROR_CODE.TRANSPORT_MISSING]: string;
-  [ERROR_CODE.TRANSPORT_INVALID]: string;
-  [ERROR_CODE.TRANSPORT_NOT_IMPLEMENTED]: string;
-  [ERROR_CODE.STUB_INVALID]: string;
-  [ERROR_CODE.STREAM_ERROR]: string;
-  [ERROR_CODE.HANDLER_ERROR]: string;
-  [ERROR_CODE.RESOLVE_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;
+declare const IRPC_ERROR_TYPE: {
+  readonly STUB: "stub";
+  readonly HOOK: "hook";
+  readonly CALL: "call";
+  readonly CRUD: "crud";
+  readonly HANDLER: "handler";
+  readonly RESOLVE: "resolve";
+  readonly TRANSPORT: "transport";
 };
+type IRPCErrorType = (typeof IRPC_ERROR_TYPE)[keyof typeof IRPC_ERROR_TYPE];
+declare const STUB_ERROR: {
+  readonly DUPLICATE: "duplicate";
+  readonly INVALID: "invalid";
+  readonly NOT_FOUND: "not_found";
+  readonly INVALID_NAME: "invalid_name";
+  readonly INVALID_VERSION: "invalid_version";
+};
+declare const HANDLER_ERROR: {
+  readonly INVALID: "invalid";
+  readonly MISSING: "missing";
+  readonly ERROR: "error";
+};
+declare const TRANSPORT_ERROR: {
+  readonly INVALID: "invalid";
+  readonly MISSING: "missing";
+  readonly NOT_IMPLEMENTED: "not_implemented";
+  readonly NOT_CONNECTED: "not_connected";
+  readonly CLOSED: "closed";
+  readonly INVALID_BODY: "invalid_body";
+  readonly STREAM_TERMINATED: "stream_terminated";
+  readonly ERROR: "error";
+};
+declare const RESOLVE_ERROR: {
+  readonly NOT_FOUND: "not_found";
+  readonly INVALID_INPUT: "invalid_input";
+  readonly INVALID_OUTPUT: "invalid_output";
+  readonly ERROR: "error";
+};
+declare const HOOK_ERROR: {
+  readonly INVALID: "invalid";
+  readonly ERROR: "error";
+};
+declare const CALL_ERROR: {
+  readonly TIMEOUT: "timeout";
+  readonly MAX_RETRIES: "max_retries";
+  readonly STREAM_ERROR: "stream_error";
+};
+declare const CRUD_ERROR: {
+  readonly NOT_FOUND: "not_found";
+  readonly NOT_IMPLEMENTED: "not_implemented";
+};
+/**
+ * Base error class for all IRPC errors.
+ *
+ * @property type - The domain category of the error (stub, handler, transport, etc.)
+ * @property code - A stable, machine-readable code for translation or programmatic matching.
+ */
+declare class IRPCError extends Error {
+  type: IRPCErrorType;
+  code: string;
+  cause?: Error | undefined;
+  constructor(type: IRPCErrorType, code: string, message: string, cause?: Error | undefined);
+  /** Serialize to the wire format used in IRPC packets. */
+  json(): IRPCPacketError;
+  /** Reconstruct an IRPCError from a wire packet error. */
+  static from(obj: IRPCPacketError): IRPCError;
+}
+/** Errors related to stub declaration, registration, and lookup. */
+declare class StubError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static duplicate(name: string): StubError;
+  static invalid(): StubError;
+  static notFound(): StubError;
+  static invalidName(name: string): StubError;
+  static invalidVersion(version: string): StubError;
+}
+/** Errors related to handler registration and execution. */
+declare class HandlerError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static invalid(): HandlerError;
+  static missing(name: string): HandlerError;
+  static failed(input: Error | string): HandlerError;
+}
+/** Errors related to the transport layer. */
+declare class TransportError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static missing(): TransportError;
+  static invalid(): TransportError;
+  static notImplemented(): TransportError;
+  static notConnected(name: string): TransportError;
+  static closed(name: string): TransportError;
+  static invalidBody(): TransportError;
+  static streamTerminated(): TransportError;
+  static failed(input: Error | string): TransportError;
+}
+/** Errors related to server-side request resolution. */
+declare class ResolveError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static notFound(name: string): ResolveError;
+  static invalidInput(input: Error | string): ResolveError;
+  static invalidOutput(input?: Error | string): ResolveError;
+  static failed(input: Error | string): ResolveError;
+}
+/** Errors related to hook registration and execution. */
+declare class HookError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static invalid(): HookError;
+  static failed(input: Error | string): HookError;
+}
+/** Errors related to call execution lifecycle. */
+declare class CallError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static timeout(): CallError;
+  static maxRetries(reasons: Set<Error>): CallError;
+  static streamError(input: Error | string): CallError;
+}
+/** Errors related to CRUD adapter operations. */
+declare class CrudError extends IRPCError {
+  constructor(code: string, message: string, cause?: Error);
+  static notFound(): CrudError;
+  static notImplemented(method: string): CrudError;
+}
 //#endregion
-export { ERROR_CODE, ERROR_MESSAGE, ErrorCode };
+export { CALL_ERROR, CRUD_ERROR, CallError, CrudError, HANDLER_ERROR, HOOK_ERROR, HandlerError, HookError, IRPCError, IRPCErrorType, IRPC_ERROR_TYPE, RESOLVE_ERROR, ResolveError, STUB_ERROR, StubError, TRANSPORT_ERROR, TransportError };