@mionjs/client 0.8.6 → 0.8.8

package/src/client.ts

@@ -0,0 +1,290 @@
+/* ########
+ * 2023 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {DEFAULT_PREFILL_OPTIONS} from './constants.ts';
+import {
+    ClientOptions,
+    MiddlewareSubRequest,
+    InitClientOptions,
+    RouteSubRequest,
+    SubRequest,
+    RequestErrors,
+    ClientRoutes,
+    ClientMiddleFns,
+    Result,
+    WorkflowResult,
+} from './types.ts';
+import type {RemoteApi} from '@mionjs/router';
+import {registerErrorDeserializers} from '@mionjs/core';
+import {getRouterItemId} from '@mionjs/core';
+import {MionClientRequest} from './request.ts';
+import type {RunTypeError} from '@mionjs/core';
+import {HandlersRegistry} from './lib/handlersRegistry.ts';
+import {MionSubRequest, findSubRequestError} from './subRequest.ts';
+
+export function initClient<RM extends RemoteApi>(
+    options: InitClientOptions
+): {client: MionClient; routes: ClientRoutes<RM>; middleFns: ClientMiddleFns<RM>} {
+    registerErrorDeserializers();
+    const clientOptions = {
+        ...DEFAULT_PREFILL_OPTIONS,
+        ...options,
+    };
+    const client = new MionClient(clientOptions);
+    const rootProxy = new MethodProxy([], client, clientOptions);
+    return {
+        client,
+        routes: rootProxy.proxy as ClientRoutes<RM>,
+        middleFns: rootProxy.proxy as ClientMiddleFns<RM>,
+    };
+}
+
+export class MionClient {
+    /** Shared registry for persistent middleFn error handlers */
+    readonly handlersRegistry = new HandlersRegistry();
+
+    /** In-memory cache for prefilled middleFn subrequests (keyed by baseURL:middleFnId) */
+    readonly prefilledMiddleFnsCache = new Map<string, SubRequest<any>>();
+
+    /** Tracks in-flight prefill operations to avoid race conditions */
+    private pendingPrefills: Promise<void>[] = [];
+
+    private globalAbortController = new AbortController();
+    private get globalSignal(): AbortSignal {
+        return this.globalAbortController.signal;
+    }
+
+    constructor(private clientOptions: ClientOptions) {}
+
+    /** Aborts all in-flight requests. New requests after this call work normally. */
+    abort(): void {
+        this.globalAbortController.abort();
+        this.globalAbortController = new AbortController();
+    }
+
+    /** Composes a single AbortSignal from global, per-request, and timeout signals */
+    private composeSignal(signal?: AbortSignal, timeout?: number): AbortSignal {
+        const signals: AbortSignal[] = [this.globalSignal];
+        if (signal) signals.push(signal);
+        const effectiveTimeout = timeout ?? this.clientOptions.timeout;
+        if (effectiveTimeout !== undefined) signals.push(AbortSignal.timeout(effectiveTimeout));
+        return AbortSignal.any(signals);
+    }
+
+    /** Executes a route call with optional workflow routes and middleFns */
+    execute(
+        routeSubRequest?: RouteSubRequest<any>,
+        workflowSubRequests?: RouteSubRequest<any>[],
+        middleFnsRecord?: Record<string, MiddlewareSubRequest<any>>,
+        signal?: AbortSignal,
+        timeout?: number
+    ): Promise<any> {
+        return this.executeRequest(routeSubRequest, workflowSubRequests, middleFnsRecord, signal, timeout);
+    }
+
+    private async executeRequest<Routes extends RouteSubRequest<any>[], H extends Record<string, MiddlewareSubRequest<any>>>(
+        routeSubRequest: RouteSubRequest<any> | undefined,
+        workflowSubRequests: Routes | undefined,
+        middleFnsRecord: H | undefined,
+        signal?: AbortSignal,
+        timeout?: number
+    ): Promise<any> {
+        // Capture the signal before any async work so abort() during prefill await is respected
+        const composedSignal = this.composeSignal(signal, timeout);
+
+        // Wait for any in-flight prefill operations to complete before executing the request
+        if (this.pendingPrefills.length > 0) await Promise.allSettled([...this.pendingPrefills]);
+
+        const middleFnSubRequests = middleFnsRecord ? Object.values(middleFnsRecord) : [];
+        const request = new MionClientRequest(
+            this.clientOptions,
+            this.prefilledMiddleFnsCache,
+            routeSubRequest,
+            middleFnSubRequests,
+            workflowSubRequests,
+            composedSignal
+        );
+
+        try {
+            await request.call();
+            const routeIds = this.getRouteIds(routeSubRequest, workflowSubRequests);
+            const allMiddleFns = this.getAllMiddleFnsFromRequest(request, routeIds);
+            this.processMiddleFnsResponses(allMiddleFns, undefined);
+            return this.buildResult(routeSubRequest, workflowSubRequests, middleFnsRecord || allMiddleFns, undefined);
+        } catch (errors: any) {
+            const routeIds = this.getRouteIds(routeSubRequest, workflowSubRequests);
+            const allMiddleFns = this.getAllMiddleFnsFromRequest(request, routeIds);
+            this.processMiddleFnsResponses(allMiddleFns, errors);
+            return this.buildResult(routeSubRequest, workflowSubRequests, middleFnsRecord || allMiddleFns, errors);
+        }
+    }
+
+    /** Get route IDs from single route or routesFlow routes */
+    private getRouteIds(
+        routeSubRequest: RouteSubRequest<any> | undefined,
+        workflowSubRequests: RouteSubRequest<any>[] | undefined
+    ): Set<string> {
+        const routeIds = new Set<string>();
+        if (routeSubRequest) routeIds.add(routeSubRequest.id);
+        if (workflowSubRequests) workflowSubRequests.forEach((sr) => routeIds.add(sr.id));
+        return routeIds;
+    }
+
+    /** Get all middleFns from the request's subRequestList, excluding the route(s) */
+    private getAllMiddleFnsFromRequest(
+        request: MionClientRequest<any, any>,
+        excludedIds: Set<string>
+    ): MiddlewareSubRequest<any>[] {
+        return Object.entries(request.subRequestList)
+            .filter(([id]) => !excludedIds.has(id))
+            .map(([, subRequest]) => subRequest as MiddlewareSubRequest<any>);
+    }
+
+    /** Process all middleFn responses - call success or error handlers for each middleFn individually */
+    private processMiddleFnsResponses(middleFnSubRequests: MiddlewareSubRequest<any>[], errors: RequestErrors | undefined): void {
+        for (const middleFn of middleFnSubRequests) {
+            const middleFnError = errors?.get(middleFn.id);
+            if (middleFnError) {
+                this.handlersRegistry.executeHandler(middleFn.id, middleFnError);
+            } else if (middleFn.resolvedValue !== undefined) {
+                this.handlersRegistry.executeSuccessHandler(middleFn.id, middleFn.resolvedValue);
+            }
+        }
+    }
+
+    /** Build the result 4-tuple from the request results. middleFns can be a named record or an array of subrequests */
+    private buildResult<Routes extends RouteSubRequest<any>[], H extends Record<string, MiddlewareSubRequest<any>>>(
+        routeSubRequest: RouteSubRequest<any> | undefined,
+        workflowSubRequests: Routes | undefined,
+        middleFns: H | MiddlewareSubRequest<any>[],
+        errors: RequestErrors | undefined
+    ): WorkflowResult<Routes, H> | Result<any, any> {
+        const middleFnsResults = {} as Record<string, any>;
+        const middleFnsErrors = {} as Record<string, any>;
+        const processedIds = new Set<string>();
+
+        let routeResultPart: any;
+        let routeErrorPart: any;
+
+        if (routeSubRequest) {
+            processedIds.add(routeSubRequest.id);
+            const routeError =
+                errors?.get(routeSubRequest.id) || (errors ? findSubRequestError(routeSubRequest, errors) : undefined);
+            routeResultPart = routeError ? undefined : routeSubRequest.resolvedValue;
+            routeErrorPart = routeError;
+        } else if (workflowSubRequests) {
+            const routeResults: (any | undefined)[] = [];
+            const routeErrors: (any | undefined)[] = [];
+            for (const routeSubRequest of workflowSubRequests) {
+                processedIds.add(routeSubRequest.id);
+                const routeError = errors?.get(routeSubRequest.id);
+                if (routeError) {
+                    routeResults.push(undefined);
+                    routeErrors.push(routeError);
+                } else {
+                    routeResults.push(routeSubRequest.resolvedValue);
+                    routeErrors.push(undefined);
+                }
+            }
+            const hasAnyResult = routeResults.some((r) => r !== undefined);
+            const hasAnyError = routeErrors.some((e) => e !== undefined);
+            routeResultPart = hasAnyResult ? routeResults : undefined;
+            routeErrorPart = hasAnyError ? routeErrors : undefined;
+        }
+
+        // middleFns can be a named record (from callWithMiddleFns/routesFlow) or an array (from executeCall)
+        if (Array.isArray(middleFns)) {
+            // Array of subrequests - use IDs as keys
+            for (const middleFn of middleFns) {
+                processedIds.add(middleFn.id);
+                const middleFnError = errors?.get(middleFn.id);
+                if (middleFnError) {
+                    middleFnsErrors[middleFn.id] = middleFnError;
+                } else if (middleFn.resolvedValue !== undefined) {
+                    middleFnsResults[middleFn.id] = middleFn.resolvedValue;
+                }
+            }
+        } else {
+            // Named record - use names as keys
+            for (const [name, middleFn] of Object.entries(middleFns)) {
+                processedIds.add(middleFn.id);
+                const middleFnError = errors?.get(middleFn.id);
+                if (middleFnError) {
+                    middleFnsErrors[name] = middleFnError;
+                } else if (middleFn.resolvedValue !== undefined) {
+                    middleFnsResults[name] = middleFn.resolvedValue;
+                }
+            }
+        }
+
+        if (errors) {
+            for (const [id, error] of errors) {
+                if (!processedIds.has(id)) {
+                    middleFnsErrors[id] = error;
+                }
+            }
+        }
+
+        return [routeResultPart, routeErrorPart, middleFnsResults, middleFnsErrors] as any;
+    }
+
+    typeErrors<List extends SubRequest<any>[]>(...subRequest: List): Promise<RunTypeError[]> {
+        const request = new MionClientRequest(this.clientOptions, this.prefilledMiddleFnsCache);
+        return request.validateParams(subRequest);
+    }
+
+    prefill<List extends MiddlewareSubRequest<any>[]>(...subRequest: List): Promise<void> {
+        const request = new MionClientRequest(this.clientOptions, this.prefilledMiddleFnsCache);
+        const promise = request.prefill(subRequest);
+        this.pendingPrefills.push(promise);
+        promise.finally(() => {
+            const index = this.pendingPrefills.indexOf(promise);
+            if (index >= 0) this.pendingPrefills.splice(index, 1);
+        });
+        return promise;
+    }
+
+    removePrefill<List extends MiddlewareSubRequest<any>[]>(...subRequest: List): Promise<void> {
+        const request = new MionClientRequest(this.clientOptions, this.prefilledMiddleFnsCache);
+        return request.removePrefill(subRequest);
+    }
+
+    /** Clear all error handlers from the registry and abort in-flight requests */
+    destroy(): void {
+        this.abort();
+        this.handlersRegistry.clearAll();
+    }
+}
+
+class MethodProxy {
+    propsProxies: Record<string, MethodProxy> = {};
+    handler = {
+        apply: (_target: any, _thisArg: any, argArray?: any): RouteSubRequest<any> & MiddlewareSubRequest<any> => {
+            const handlerId = getRouterItemId(this.parentProps);
+            return new MionSubRequest(this.parentProps, handlerId, argArray, this.client);
+        },
+
+        get: (_target: any, prop: string): typeof Proxy => {
+            const existing = this.propsProxies[prop];
+            if (existing) return existing.proxy;
+            const newMethodProxy = new MethodProxy([...this.parentProps, prop], this.client, this.clientOptions);
+            this.propsProxies[prop] = newMethodProxy;
+            return newMethodProxy.proxy;
+        },
+    };
+
+    proxy: typeof Proxy;
+
+    constructor(
+        public parentProps: string[],
+        private client: MionClient,
+        private clientOptions: ClientOptions
+    ) {
+        const target = () => null;
+        this.proxy = new Proxy(target, this.handler);
+    }
+}

package/src/constants.ts

@@ -0,0 +1,37 @@
+/* ########
+ * 2022 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {ClientOptions} from './types.ts';
+
+export const DEFAULT_PREFILL_OPTIONS: ClientOptions = {
+    baseURL: '',
+    fetchOptions: {
+        method: 'PUT',
+        headers: {'Content-Type': 'application/json'},
+    },
+    /** Prefix for all routes, i.e: api/v1 */
+    basePath: '',
+    /** Suffix for all routes, i.e: .json */
+    suffix: '',
+    /** Enables automatic parameter validation */
+    validateParams: true,
+    /** Set true to automatically generate and id for every error */
+    autoGenerateErrorId: false,
+    /** Default serializer mode - stringifyJson as default native serializer */
+    serializer: 'stringifyJson',
+};
+
+/** Maximum safe URL length for GET requests with ?data= query param */
+export const MAX_GET_URL_LENGTH = 4096;
+
+export const STORAGE_KEY = 'mion:client';
+
+/** RoutesFlow route key - matches router constant */
+export const ROUTES_FLOW_KEY = 'mion-routes-flow';
+
+/** RoutesFlow route path - matches router constant */
+export const ROUTES_FLOW_PATH = `/${ROUTES_FLOW_KEY}`;

package/src/lib/clientMethodsMetadata.ts

@@ -0,0 +1,187 @@
+/* ########
+ * 2023 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {isRpcError, addRoutesToCache} from '@mionjs/core';
+import {MION_ROUTES} from '@mionjs/core';
+import {ClientOptions, SubRequest} from '../types.ts';
+import type {
+    JitCompiledFnData,
+    MethodsCache,
+    MethodWithOptions,
+    PureFunctionData,
+    SerializableMethodsData,
+    PureFnsDataCache,
+} from '@mionjs/core';
+import {routesCache, addSerializedJitCaches} from '@mionjs/core';
+import {STORAGE_KEY} from '../constants.ts';
+import {getStorage} from './storage.ts';
+
+const METHOD_DATA_PREFIX = `${STORAGE_KEY}:method-data:`;
+const JIT_FN_PREFIX = `${STORAGE_KEY}:jit-fn:`;
+const PURE_FN_PREFIX = `${STORAGE_KEY}:pure-fn:`;
+
+type MetadataRouteKey = typeof MION_ROUTES.methodsMetadata | typeof MION_ROUTES.methodsMetadataById;
+
+/** Extracts raw metadata from a parsed response body, unwraps the JIT union discriminator, and processes it. */
+export function extractAndProcessMetadata(routeKey: MetadataRouteKey, parsedBody: any, options: ClientOptions): void {
+    if (typeof parsedBody !== 'object' || !(routeKey in parsedBody)) return;
+    const rawMetadata = parsedBody[routeKey];
+    delete parsedBody[routeKey];
+    if (!rawMetadata) return;
+    const metadataValue = Array.isArray(rawMetadata) ? rawMetadata[1] : rawMetadata;
+    if (metadataValue && !isRpcError(metadataValue) && metadataValue.methods) {
+        processMethodsMetadata(metadataValue as SerializableMethodsData, options);
+    }
+}
+
+/** Processes metadata from an optimistic response and caches it */
+function processMethodsMetadata(serializableMethodsData: SerializableMethodsData, options: ClientOptions): void {
+    storeDependencies(serializableMethodsData.deps, serializableMethodsData.purFnDeps, options);
+    storeMethodsMetadata(serializableMethodsData.methods, options);
+    addToCaches(serializableMethodsData);
+}
+
+function getSerializedMethodDataKey(methodId: string, options: ClientOptions) {
+    return `${METHOD_DATA_PREFIX}${methodId}:${options.baseURL}`;
+}
+
+function getJitCompiledFnKey(jitFnHash: string, options: ClientOptions) {
+    return `${JIT_FN_PREFIX}${jitFnHash}:${options.baseURL}`;
+}
+
+function getJitPureFnKey(namespace: string, pureFnHash: string, options: ClientOptions) {
+    return `${PURE_FN_PREFIX}${namespace}:${pureFnHash}:${options.baseURL}`;
+}
+
+/** Stores JIT compiled functions and pure functions globally in localStorage */
+export function storeDependencies(deps: Record<string, JitCompiledFnData>, pureFnDeps: PureFnsDataCache, options: ClientOptions) {
+    Object.entries(deps).forEach(([hash, jitFnData]: [string, JitCompiledFnData]) => {
+        const key = getJitCompiledFnKey(hash, options);
+        try {
+            getStorage().setItem(key, JSON.stringify(jitFnData));
+        } catch (error) {
+            console.warn(`Failed to store JIT function dependency ${hash}:`, error);
+        }
+    });
+
+    // Store namespaced pure functions
+    Object.entries(pureFnDeps).forEach(([namespace, nsPureFns]) => {
+        Object.entries(nsPureFns).forEach(([fnHash, pureFnData]: [string, PureFunctionData]) => {
+            const key = getJitPureFnKey(namespace, fnHash, options);
+            try {
+                getStorage().setItem(key, JSON.stringify(pureFnData));
+            } catch (error) {
+                console.warn(`Failed to store pure function dependency ${namespace}::${fnHash}:`, error);
+            }
+        });
+    });
+}
+
+/** Stores method metadata in localStorage using the new storage format */
+export function storeMethodsMetadata(methods: MethodsCache, options: ClientOptions) {
+    Object.entries(methods).forEach(([methodId, methodData]) => {
+        const key = getSerializedMethodDataKey(methodId, options);
+        try {
+            getStorage().setItem(key, JSON.stringify(methodData));
+        } catch (error) {
+            console.warn(`Failed to store method metadata ${methodId}:`, error);
+        }
+    });
+}
+
+/** Restores all JIT compiled functions and pure functions from localStorage and deserializes them */
+export function restoreAllDependencies(options: ClientOptions) {
+    const deps: Record<string, JitCompiledFnData> = {};
+    const pureFnDeps: PureFnsDataCache = {};
+    const baseURLSuffix = `:${options.baseURL}`;
+
+    for (let i = 0; i < getStorage().length; i++) {
+        const key = getStorage().key(i);
+        if (key?.startsWith(JIT_FN_PREFIX) && key.endsWith(baseURLSuffix)) {
+            try {
+                const data = getStorage().getItem(key);
+                if (data) {
+                    const parsedData = JSON.parse(data);
+                    deps[parsedData.jitFnHash] = parsedData;
+                }
+            } catch (error) {
+                console.warn(`Failed to restore JIT function from key ${key}:`, error);
+            }
+        }
+    }
+
+    for (let i = 0; i < getStorage().length; i++) {
+        const key = getStorage().key(i);
+        if (key?.startsWith(PURE_FN_PREFIX) && key.endsWith(baseURLSuffix)) {
+            try {
+                const data = getStorage().getItem(key);
+                if (data) {
+                    const parsedData = JSON.parse(data);
+                    // Extract namespace from key: "mion:pure-fn:namespace:fnHash:baseURL"
+                    const inner = key.slice(PURE_FN_PREFIX.length, key.length - baseURLSuffix.length);
+                    const namespace = inner.split(':')[0] || parsedData.namespace;
+                    if (!pureFnDeps[namespace]) pureFnDeps[namespace] = {};
+                    pureFnDeps[namespace][parsedData.fnName] = parsedData;
+                }
+            } catch (error) {
+                console.warn(`Failed to restore pure function from key ${key}:`, error);
+            }
+        }
+    }
+
+    if (Object.keys(deps).length > 0 || Object.keys(pureFnDeps).length > 0) {
+        addSerializedJitCaches(deps, pureFnDeps);
+    }
+}
+
+/** Creates a SubRequest for the metadata middleware to piggyback on an optimistic request */
+export function createMetadataSubRequest(methodIds: string[]): SubRequest<any> {
+    return {
+        pointer: [MION_ROUTES.methodsMetadata],
+        id: MION_ROUTES.methodsMetadata,
+        isResolved: false,
+        params: [methodIds],
+    };
+}
+
+/** Restores method metadata from localStorage using the new storage format */
+export function restoreFromLocalStorage(methodIds: string[], options: ClientOptions) {
+    restoreAllDependencies(options);
+
+    const methods: MethodsCache = {};
+    let anyMethodsRestored = false;
+
+    methodIds.forEach((id) => {
+        if (routesCache.hasMetadata(id)) return;
+        const methodKey = getSerializedMethodDataKey(id, options);
+        const methodMetaJson = getStorage().getItem(methodKey);
+        if (methodMetaJson) {
+            try {
+                const methodMeta: MethodWithOptions = JSON.parse(methodMetaJson);
+                methods[id] = methodMeta;
+                anyMethodsRestored = true;
+            } catch (error) {
+                console.warn(`Failed to restore method metadata for ${id}:`, error);
+                getStorage().removeItem(methodKey);
+            }
+        }
+    });
+
+    if (anyMethodsRestored) {
+        const serializableMethodsData: SerializableMethodsData = {
+            methods,
+            deps: {},
+            purFnDeps: {},
+        };
+        addToCaches(serializableMethodsData);
+    }
+}
+
+function addToCaches(serializableMethodsData: SerializableMethodsData) {
+    addSerializedJitCaches(serializableMethodsData.deps, serializableMethodsData.purFnDeps);
+    addRoutesToCache(serializableMethodsData.methods);
+}

package/src/lib/fetchRemoteMethodsMetadata.ts

@@ -0,0 +1,44 @@
+/* ########
+ * 2023 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {isRpcError, MION_ROUTES, getRoutePath, routesCache} from '@mionjs/core';
+import {ClientOptions, RequestBody} from '../types.ts';
+import {restoreFromLocalStorage} from './clientMethodsMetadata.ts';
+import {deserializeResponseBody} from './serializer.ts';
+
+/** Manually calls mionGetRemoteMethodsInfoById to get Remote Api Metadata */
+export async function fetchRemoteMethodsMetadata(
+    methodIds: string[],
+    options: ClientOptions,
+    signal?: AbortSignal
+): Promise<void> {
+    restoreFromLocalStorage(methodIds, options);
+    const missingAfterLocal = methodIds.filter((path) => !routesCache.hasMetadata(path));
+    if (!missingAfterLocal.length) return;
+    const body: RequestBody = {
+        [MION_ROUTES.methodsMetadataById]: [missingAfterLocal],
+    };
+    try {
+        const path = getRoutePath([MION_ROUTES.methodsMetadataById], options);
+        const url = new URL(path, options.baseURL);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify(body),
+            signal,
+        });
+        const deserialized = await deserializeResponseBody(response, options);
+        const platformError = deserialized[MION_ROUTES.platformError];
+        if (isRpcError(platformError)) throw platformError;
+        const stillMissing = missingAfterLocal.filter((id) => !routesCache.hasMetadata(id));
+        if (stillMissing.length) throw new Error(`Failed to fetch metadata for: ${stillMissing.join(', ')}`);
+    } catch (error: any) {
+        // Preserve abort/timeout DOMException so the caller's onError can classify it correctly
+        if (signal?.aborted) throw error;
+        throw new Error(`Error fetching validation and serialization metadata: ${error?.message}`);
+    }
+}

package/src/lib/handlersRegistry.ts

@@ -0,0 +1,101 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import type {RpcError} from '@mionjs/core';
+import type {ErrorHandler, SuccessHandler} from '../types.ts';
+
+/** Central registry for persistent middleFn handlers (both success and error) */
+export class HandlersRegistry {
+    private errorHandlers: Map<string, Map<string, ErrorHandler<any>>> = new Map();
+    private successHandlers: Map<string, SuccessHandler<any>> = new Map();
+
+    /** Register an error handler for a specific handler (middleFn) and error type */
+    register(handlerId: string, errorType: string, handler: ErrorHandler<any>): void {
+        let handlerMap = this.errorHandlers.get(handlerId);
+        if (!handlerMap) {
+            handlerMap = new Map();
+            this.errorHandlers.set(handlerId, handlerMap);
+        }
+        handlerMap.set(errorType, handler);
+    }
+
+    /** Unregister an error handler for a specific handler and error type */
+    unregister(handlerId: string, errorType: string): void {
+        const handlerMap = this.errorHandlers.get(handlerId);
+        if (handlerMap) {
+            handlerMap.delete(errorType);
+            if (handlerMap.size === 0) this.errorHandlers.delete(handlerId);
+        }
+    }
+
+    /** Check if an error handler exists for a specific handler ID and error type */
+    hasHandler(handlerId: string, errorType: string): boolean {
+        const handlerMap = this.errorHandlers.get(handlerId);
+        return handlerMap?.has(errorType) ?? false;
+    }
+
+    /** Get and execute the handler for an error, if it exists */
+    executeHandler(handlerId: string, error: RpcError<string>): boolean {
+        const handlerMap = this.errorHandlers.get(handlerId);
+        if (!handlerMap) return false;
+
+        const handler = handlerMap.get(error.type);
+        if (!handler) return false;
+
+        handler(error);
+        return true;
+    }
+
+    /** Register a success handler for a specific middleFn */
+    registerSuccess(handlerId: string, handler: SuccessHandler<any>): void {
+        this.successHandlers.set(handlerId, handler);
+    }
+
+    /** Unregister a success handler for a specific middleFn */
+    unregisterSuccess(handlerId: string): void {
+        this.successHandlers.delete(handlerId);
+    }
+
+    /** Check if a success handler exists for a specific handler ID */
+    hasSuccessHandler(handlerId: string): boolean {
+        return this.successHandlers.has(handlerId);
+    }
+
+    /** Get and execute the success handler for a middleFn result, if it exists */
+    executeSuccessHandler(handlerId: string, result: any): boolean {
+        const handler = this.successHandlers.get(handlerId);
+        if (!handler) return false;
+
+        handler(result);
+        return true;
+    }
+
+    /** Clear all handlers (both error and success) for a specific handler ID */
+    clearHandlers(handlerId: string): void {
+        this.errorHandlers.delete(handlerId);
+        this.successHandlers.delete(handlerId);
+    }
+
+    /** Clear all registered handlers (both error and success) */
+    clearAll(): void {
+        this.errorHandlers.clear();
+        this.successHandlers.clear();
+    }
+
+    /** Get all registered handler IDs */
+    getHandlerIds(): string[] {
+        const errorIds = Array.from(this.errorHandlers.keys());
+        const successIds = Array.from(this.successHandlers.keys());
+        return [...new Set([...errorIds, ...successIds])];
+    }
+
+    /** Get all error types registered for a handler ID */
+    getErrorTypes(handlerId: string): string[] {
+        const handlerMap = this.errorHandlers.get(handlerId);
+        return handlerMap ? Array.from(handlerMap.keys()) : [];
+    }
+}