@antelopejs/interface-core 0.0.9 → 0.0.11

package/dist/proxies.js

@@ -1,265 +1,426 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventProxy = exports.RegisteringProxy = exports.AsyncProxy = void 0;
+exports.IsInterfaceProxy = IsInterfaceProxy;
+exports.GetInterfaceProxyIdentity = GetInterfaceProxyIdentity;
 exports.InvalidateResponsibleModule = InvalidateResponsibleModule;
 exports.RunWithResponsibleModule = RunWithResponsibleModule;
 exports.GetResponsibleModule = GetResponsibleModule;
-const node_async_hooks_1 = require("node:async_hooks");
 const errors_1 = require("./errors");
 const internal_1 = require("./internal");
 const responsible_module_1 = require("./responsible-module");
-const responsibleModuleContext = new node_async_hooks_1.AsyncLocalStorage();
-const activeResponsibleModuleTokens = new Map();
-function getResponsibleModuleToken(module) {
-    const activeToken = activeResponsibleModuleTokens.get(module);
-    if (activeToken) {
-        return activeToken;
-    }
-    const token = Symbol(module);
-    activeResponsibleModuleTokens.set(module, token);
-    return token;
+const PROXY_BRAND = Symbol.for("@antelopejs/interface-core/proxy");
+const DEFAULT_PROVIDER = "@antelopejs/interface-core/default-provider";
+function createIdentity(kind, identity) {
+    if (identity) {
+        return `${kind}:${identity}`;
+    }
+    const nextIdentity = internal_1.internal.nextProxyIdentity++;
+    return `${kind}:anonymous:${nextIdentity}`;
+}
+function getProxyState(brand, create) {
+    const existing = internal_1.internal.proxyStates.get(brand.identity);
+    if (existing && existing.kind !== brand.kind) {
+        throw new Error(`Proxy identity ${brand.identity} has conflicting kinds.`);
+    }
+    if (existing) {
+        return existing.value;
+    }
+    const value = create();
+    internal_1.internal.proxyStates.set(brand.identity, { kind: brand.kind, value });
+    return value;
+}
+function createBrand(kind, identity) {
+    return Object.freeze({
+        protocol: internal_1.RUNTIME_PROTOCOL_VERSION,
+        kind,
+        identity: createIdentity(kind, identity),
+    });
 }
-function assertActiveContext(context) {
-    if (activeResponsibleModuleTokens.get(context.module) !== context.token) {
-        throw new errors_1.ModuleContextInvalidatedError(context.module);
+function readBrand(value) {
+    if ((typeof value !== "object" && typeof value !== "function") || !value) {
+        return;
+    }
+    const brand = value[PROXY_BRAND];
+    if (!brand || brand.protocol !== internal_1.RUNTIME_PROTOCOL_VERSION) {
+        return;
     }
+    return brand;
+}
+/** Returns whether a value implements this runtime's stable proxy protocol. */
+function IsInterfaceProxy(value, kind) {
+    const brand = readBrand(value);
+    return Boolean(brand && (!kind || brand.kind === kind));
+}
+/** Returns the stable identity used to bind a proxy to a provider route. */
+function GetInterfaceProxyIdentity(value) {
+    return readBrand(value)?.identity;
+}
+function getAttachmentRoute(manualDetach) {
+    const context = (0, internal_1.getModuleContext)();
+    const responsible = manualDetach || context?.module ? undefined : GetResponsibleModule();
+    const owner = context?.owner ?? context?.module ?? responsible ?? DEFAULT_PROVIDER;
+    return { owner, provider: context?.provider ?? owner };
+}
+function getRequestedProvider(proxyIdentity) {
+    const context = (0, internal_1.getModuleContext)();
+    return context?.providerRoutes?.[proxyIdentity] ?? context?.provider;
+}
+function bindProviderCallback(callback) {
+    const context = (0, internal_1.captureModuleContext)();
+    if (!context) {
+        return callback;
+    }
+    return ((...args) => (0, internal_1.runWithCapturedModuleContext)(context, () => callback(...args)));
+}
+function getExecutionOwnership() {
+    const context = (0, internal_1.getModuleContext)();
+    if (context) {
+        return { module: context.module, owner: context.owner ?? context.module };
+    }
+    const module = GetResponsibleModule();
+    return { module, owner: module };
+}
+function selectProvider(callbacks, proxyIdentity, requested) {
+    if (requested) {
+        const callback = callbacks.get(requested);
+        if (!callback && callbacks.size > 0) {
+            throw new errors_1.MissingProviderError(`Interface proxy ${proxyIdentity} has no provider for route ${requested}.`);
+        }
+        return callback;
+    }
+    if (callbacks.size <= 1) {
+        return callbacks.values().next().value;
+    }
+    throw new errors_1.AmbiguousProviderError(proxyIdentity, [...callbacks.keys()]);
+}
+function reportRuntimeError(error, operation, proxyIdentity, module, registrationId) {
+    internal_1.internal.runtimeErrorReporter?.(error, {
+        operation,
+        module,
+        proxyIdentity,
+        registrationId,
+    });
+}
+function matchesLease(attachment, lease) {
+    return (attachment?.generation === lease.generation &&
+        attachment.owner === lease.owner);
 }
 /** @internal */
 function InvalidateResponsibleModule(module) {
-    activeResponsibleModuleTokens.delete(module);
+    (0, internal_1.invalidateModuleContext)(module);
 }
-/**
- * Runs work with an explicit responsible module.
- *
- * The module remains available to nested synchronous and asynchronous work.
- * Calls outside this context continue to use stack-based module resolution.
- *
- * @param module Module ID responsible for the work
- * @param callback Work to run in the module context
- * @returns The callback result
- */
+/** Runs work with explicit module ownership across asynchronous boundaries. */
 function RunWithResponsibleModule(module, callback) {
-    const inheritedContext = responsibleModuleContext.getStore();
-    if (inheritedContext) {
-        assertActiveContext(inheritedContext);
-    }
-    const context = { module, token: getResponsibleModuleToken(module) };
-    return responsibleModuleContext.run(context, callback);
+    return (0, internal_1.runWithModuleContext)({ module }, callback);
 }
-/**
- * Proxy for an asynchronous function.
- *
- * Queues up calls while unattached, automatically unattaches when the source module is unloaded.
- * Provides a mechanism for delayed execution and module-aware function binding.
- */
+/** Proxy for an asynchronous interface function. */
 class AsyncProxy {
-    callback;
-    queue = [];
-    /**
-     * Attaches a callback to the proxy
-     *
-     * Automatically detached if the module calling this function gets unloaded and manualDetach is not set to true.
-     * When attached, any queued calls will be executed immediately.
-     *
-     * @param callback Function to attach
-     * @param manualDetach Don't detach automatically when module is unloaded
-     */
+    [PROXY_BRAND];
+    state;
+    constructor(identity) {
+        this[PROXY_BRAND] = createBrand("async", identity);
+        this.state = getProxyState(this[PROXY_BRAND], () => ({
+            callbacks: new Map(),
+            queue: [],
+        }));
+    }
+    /** Attaches a provider callback and replays compatible queued calls. */
     onCall(callback, manualDetach) {
-        const caller = manualDetach ? undefined : GetResponsibleModule();
-        this.callback = callback;
-        if (caller) {
-            internal_1.internal.addAsyncProxy(caller, this);
-        }
-        if (this.queue.length > 0) {
-            this.queue.forEach(({ args, resolve, reject }) => {
-                try {
-                    resolve(callback(...args));
-                }
-                catch (err) {
-                    reject(err);
-                }
+        const route = getAttachmentRoute(manualDetach);
+        const lease = { ...route, generation: internal_1.internal.nextLeaseGeneration++ };
+        const providerCallback = bindProviderCallback(callback);
+        this.state.callbacks.set(route.provider, {
+            callback: providerCallback,
+            ...lease,
+        });
+        if (!manualDetach) {
+            internal_1.internal.addAsyncProxy(route.owner, {
+                cleanup: () => this.detach(lease),
             });
-            this.queue.splice(0, this.queue.length);
+        }
+        this.replayQueue(route.provider, providerCallback);
+        return lease;
+    }
+    /** Detaches one leased provider, or every provider when called without a lease. */
+    detach(lease) {
+        if (!lease) {
+            this.state.callbacks.clear();
+            return;
+        }
+        const current = this.state.callbacks.get(lease.provider);
+        if (current?.generation === lease.generation &&
+            current.owner === lease.owner) {
+            this.state.callbacks.delete(lease.provider);
         }
     }
-    /**
-     * Manually detach the callback on this proxy.
-     */
-    detach() {
-        this.callback = undefined;
-    }
-    /**
-     * Call the function attached to this proxy.
-     *
-     * If a callback has not been attached yet, the call is queued up for later.
-     */
+    /** Calls the provider selected by the current module execution context. */
     call(...args) {
-        if (this.callback) {
-            try {
-                return Promise.resolve(this.callback(...args));
-            }
-            catch (err) {
-                return Promise.reject(err);
-            }
+        let requested;
+        let attachment;
+        try {
+            requested = getRequestedProvider(this[PROXY_BRAND].identity);
+            attachment = selectProvider(this.state.callbacks, this[PROXY_BRAND].identity, requested);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (attachment) {
+            return this.invoke(attachment.callback, args);
         }
         if (internal_1.internal.testStubMode) {
             return Promise.reject(new errors_1.MissingProviderError());
         }
-        return new Promise((resolve, reject) => this.queue.push({ args, resolve, reject }));
+        if (this.state.queue.length >= internal_1.internal.maxPendingOperations) {
+            return Promise.reject(new errors_1.ProviderQueueFullError(this[PROXY_BRAND].identity, internal_1.internal.maxPendingOperations));
+        }
+        return new Promise((resolve, reject) => {
+            this.state.queue.push({ args, provider: requested, resolve, reject });
+        });
+    }
+    invoke(callback, args) {
+        try {
+            return Promise.resolve(callback(...args));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    replayQueue(provider, callback) {
+        const remaining = [];
+        for (const pending of this.state.queue) {
+            if (pending.provider && pending.provider !== provider) {
+                remaining.push(pending);
+                continue;
+            }
+            this.invoke(callback, pending.args).then(pending.resolve, pending.reject);
+        }
+        this.state.queue = remaining;
     }
 }
 exports.AsyncProxy = AsyncProxy;
-/**
- * Proxy for a pair of register/unregister functions.
- *
- * Manages registration of handlers and ensures proper cleanup when modules are unloaded.
- * This allows for module-aware event registration with automatic cleanup.
- */
+/** Proxy for provider-aware register and unregister handlers. */
 class RegisteringProxy {
-    registerCallback;
-    unregisterCallback;
-    registered = new Map();
-    /**
-     * Attaches a register callback to the proxy
-     *
-     * Automatically detached if the module calling this function gets unloaded and manualDetach is not set to true.
-     *
-     * @param callback Function to attach as the register callback
-     * @param manualDetach Don't detach automatically
-     */
+    [PROXY_BRAND];
+    state;
+    constructor(identity) {
+        this[PROXY_BRAND] = createBrand("registering", identity);
+        this.state = getProxyState(this[PROXY_BRAND], () => ({
+            callbacks: new Map(),
+            registered: new Map(),
+        }));
+        internal_1.internal.registeringProxies.add(this);
+    }
+    /** Attaches a register callback. */
     onRegister(callback, manualDetach) {
-        const caller = manualDetach ? undefined : GetResponsibleModule();
-        this.registerCallback = callback;
-        if (caller) {
-            internal_1.internal.addRegisteringProxy(caller, this);
-        }
-        for (const [id, { args }] of this.registered) {
-            try {
-                callback(id, ...args);
-            }
-            catch (err) {
-                // Best-effort replay: one throwing consumer must not strand the others.
-                if (internal_1.internal.replayErrorReporter) {
-                    internal_1.internal.replayErrorReporter(id, err);
-                }
+        const route = getAttachmentRoute(manualDetach);
+        return this.attachRegister(bindProviderCallback(callback), route, Boolean(manualDetach));
+    }
+    /** Attaches an unregister callback to the current provider route. */
+    onUnregister(callback) {
+        const context = (0, internal_1.getModuleContext)();
+        const requested = context?.provider ?? context?.module;
+        const current = selectProvider(this.state.callbacks, this[PROXY_BRAND].identity, requested);
+        const contextOwner = context?.owner ?? context?.module;
+        const attachments = [current?.unregister, current?.register];
+        const sibling = contextOwner
+            ? attachments.find((attachment) => attachment?.owner === contextOwner)
+            : attachments.find((attachment) => Boolean(attachment));
+        const canExtendCurrent = current && sibling;
+        const options = canExtendCurrent
+            ? {
+                route: { owner: sibling.owner, provider: current.provider },
+                manualDetach: sibling.manualDetach,
             }
+            : { route: getAttachmentRoute(), manualDetach: false };
+        return this.attachUnregister(bindProviderCallback(callback), options);
+    }
+    /** Atomically attaches both registration handlers. */
+    onHandlers(register, unregister, manualDetach) {
+        const route = getAttachmentRoute(manualDetach);
+        const lease = this.createLease(route);
+        const boundRegister = bindProviderCallback(register);
+        const boundUnregister = bindProviderCallback(unregister);
+        this.state.callbacks.set(route.provider, {
+            provider: route.provider,
+            register: this.createAttachment(boundRegister, lease, manualDetach),
+            unregister: this.createAttachment(boundUnregister, lease, manualDetach),
+        });
+        this.trackAttachment(lease, Boolean(manualDetach));
+        this.replayRegistrations(route.provider, boundRegister);
+        return lease;
+    }
+    /** Detaches one leased provider, or every provider when called without a lease. */
+    detach(lease) {
+        if (!lease) {
+            this.state.callbacks.clear();
+            return;
+        }
+        const current = this.state.callbacks.get(lease.provider);
+        if (!current) {
+            return;
+        }
+        if (matchesLease(current.register, lease)) {
+            current.register = undefined;
+        }
+        if (matchesLease(current.unregister, lease)) {
+            current.unregister = undefined;
+        }
+        if (!current.register && !current.unregister) {
+            this.state.callbacks.delete(lease.provider);
         }
     }
-    /**
-     * Attaches an unregister callback to the proxy
-     *
-     * Detached at the same time as the register callback.
-     *
-     * @param callback Function to attach as the unregister callback
-     */
-    onUnregister(callback) {
-        this.unregisterCallback = callback;
-    }
-    /**
-     * Manually detach the callbacks on this proxy.
-     */
-    detach() {
-        this.registerCallback = undefined;
-        this.unregisterCallback = undefined;
-    }
-    /**
-     * Call the register callback attached to this proxy.
-     *
-     * If a callback has not been attached yet, the call is queued up for later.
-     *
-     * @param id Unique identifier used to unregister
-     * @param args Extra arguments
-     */
+    /** Registers an entry with the selected provider or queues it for bootstrap. */
     register(id, ...args) {
-        if (!this.registerCallback && internal_1.internal.testStubMode) {
+        const requested = getRequestedProvider(this[PROXY_BRAND].identity);
+        const callback = selectProvider(this.state.callbacks, this[PROXY_BRAND].identity, requested);
+        if (!callback && internal_1.internal.testStubMode) {
             throw new errors_1.MissingProviderError();
         }
-        const module = GetResponsibleModule();
-        this.registered.set(id, { module, args });
-        if (this.registerCallback) {
-            this.registerCallback(id, ...args);
+        if (!callback &&
+            !this.state.registered.has(id) &&
+            this.state.registered.size >= internal_1.internal.maxPendingOperations) {
+            throw new errors_1.ProviderQueueFullError(this[PROXY_BRAND].identity, internal_1.internal.maxPendingOperations);
         }
+        const ownership = getExecutionOwnership();
+        this.state.registered.set(id, {
+            ...ownership,
+            provider: requested ?? callback?.provider,
+            args,
+        });
+        callback?.register?.callback(id, ...args);
     }
-    /**
-     * Call the unregister callback attached to this proxy.
-     *
-     * @param id Unique identifier to unregister
-     */
+    /** Unregisters an entry from the provider that accepted it. */
     unregister(id) {
-        if (this.registered.has(id)) {
-            if (this.unregisterCallback) {
-                this.unregisterCallback(id);
+        const entry = this.state.registered.get(id);
+        if (!entry) {
+            return;
+        }
+        const callback = selectProvider(this.state.callbacks, this[PROXY_BRAND].identity, entry.provider);
+        try {
+            callback?.unregister?.callback(id);
+        }
+        finally {
+            this.state.registered.delete(id);
+        }
+    }
+    /** Unregisters every entry owned by a destroyed module. */
+    unregisterModule(module) {
+        this.unregisterMatching((entry) => entry.module === module, module);
+    }
+    /** Unregisters every entry owned by a destroyed module generation. */
+    unregisterOwner(owner) {
+        this.unregisterMatching((entry) => entry.owner === owner, owner);
+    }
+    unregisterMatching(matches, owner) {
+        for (const [id, entry] of this.state.registered) {
+            if (!matches(entry)) {
+                continue;
             }
-            this.registered.delete(id);
+            try {
+                this.unregister(id);
+            }
+            catch (error) {
+                reportRuntimeError(error, "unregister", this[PROXY_BRAND].identity, owner, id);
+            }
+            finally {
+                this.state.registered.delete(id);
+            }
+        }
+    }
+    attachRegister(callback, route, manualDetach) {
+        const lease = this.createLease(route);
+        const current = this.state.callbacks.get(route.provider);
+        this.state.callbacks.set(route.provider, {
+            provider: route.provider,
+            register: this.createAttachment(callback, lease, manualDetach),
+            unregister: current?.unregister,
+        });
+        this.trackAttachment(lease, manualDetach);
+        this.replayRegistrations(route.provider, callback);
+        return lease;
+    }
+    attachUnregister(callback, options) {
+        const { route, manualDetach } = options;
+        const lease = this.createLease(route);
+        const current = this.state.callbacks.get(route.provider);
+        this.state.callbacks.set(route.provider, {
+            provider: route.provider,
+            register: current?.register,
+            unregister: this.createAttachment(callback, lease, manualDetach),
+        });
+        this.trackAttachment(lease, manualDetach);
+        return lease;
+    }
+    trackAttachment(lease, manualDetach) {
+        if (!manualDetach) {
+            internal_1.internal.addRegisteringProxy(lease.owner, {
+                cleanup: () => this.detach(lease),
+                unregisterModule: (module) => this.unregisterModule(module),
+            });
         }
     }
-    /**
-     * Unregister all entries created by the given module
-     * @internal
-     *
-     * @param mod Module ID
-     */
-    unregisterModule(mod) {
-        for (const [id, { module }] of this.registered) {
-            if (module === mod) {
-                if (this.unregisterCallback) {
-                    this.unregisterCallback(id);
-                }
-                this.registered.delete(id);
+    createLease(route) {
+        return { ...route, generation: internal_1.internal.nextLeaseGeneration++ };
+    }
+    createAttachment(callback, lease, manualDetach) {
+        return { callback, ...lease, manualDetach: Boolean(manualDetach) };
+    }
+    replayRegistrations(provider, callback) {
+        for (const [id, entry] of this.state.registered) {
+            if (entry.provider && entry.provider !== provider) {
+                continue;
+            }
+            try {
+                callback(id, ...entry.args);
+                entry.provider = provider;
+            }
+            catch (error) {
+                internal_1.internal.replayErrorReporter?.(id, error);
+                reportRuntimeError(error, "register-replay", this[PROXY_BRAND].identity, entry.module, id);
             }
         }
     }
 }
 exports.RegisteringProxy = RegisteringProxy;
-/**
- * Event handler list that automatically removes handlers from unloaded modules.
- *
- * Provides a module-aware event system that cleans up event handlers when modules are unloaded,
- * preventing memory leaks and ensuring proper modularity.
- */
+/** Module-aware event handler collection. */
 class EventProxy {
-    registered = [];
-    constructor() {
-        internal_1.internal.knownEvents.push(this);
-    }
-    /**
-     * Call all the event handlers with the specified arguments.
-     *
-     * @param args Arguments
-     */
+    [PROXY_BRAND];
+    state;
+    constructor(identity) {
+        this[PROXY_BRAND] = createBrand("event", identity);
+        this.state = getProxyState(this[PROXY_BRAND], () => ({ registered: [] }));
+        internal_1.internal.knownEvents.add(this);
+    }
+    /** Emits to every handler, reporting failures without aborting later handlers. */
     emit(...args) {
-        for (const { func } of this.registered) {
-            func(...args);
+        for (const { func, module } of this.state.registered) {
+            try {
+                func(...args);
+            }
+            catch (error) {
+                reportRuntimeError(error, "event-emit", this[PROXY_BRAND].identity, module);
+            }
         }
     }
-    /**
-     * Register a new handler for this event.
-     *
-     * @param func Handler
-     */
+    /** Registers a handler once. */
     register(func) {
-        if (this.registered.some((existing) => existing.func === func)) {
+        if (this.state.registered.some((existing) => existing.func === func)) {
             return;
         }
-        const module = GetResponsibleModule();
-        this.registered.push({ module, func });
-    }
-    /**
-     * Unregister a handler on this event.
-     *
-     * @param fn The handler that was passed to {@link register}
-     */
+        this.state.registered.push({ ...getExecutionOwnership(), func });
+    }
+    /** Unregisters a handler. */
     unregister(fn) {
-        this.registered = this.registered.filter(({ func }) => func !== fn);
+        this.state.registered = this.state.registered.filter(({ func }) => func !== fn);
+    }
+    /** Unregisters handlers owned by a destroyed module. */
+    unregisterModule(module) {
+        this.state.registered = this.state.registered.filter((entry) => entry.module !== module);
     }
-    /**
-     * Unregister all handlers created by the given module.
-     * @internal
-     *
-     * @param mod Module ID
-     */
-    unregisterModule(mod) {
-        this.registered = this.registered.filter(({ module }) => module !== mod);
+    /** Unregisters handlers owned by a destroyed module generation. */
+    unregisterOwner(owner) {
+        this.state.registered = this.state.registered.filter((entry) => entry.owner !== owner);
     }
 }
 exports.EventProxy = EventProxy;
@@ -268,27 +429,18 @@ function captureCallStack(startFrame = 0) {
     const oldLimit = Error.stackTraceLimit;
     Error.stackTraceLimit = Infinity;
     Error.prepareStackTrace = (_, trace) => trace;
-    const errObj = {};
-    Error.captureStackTrace(errObj, GetResponsibleModule);
-    const trace = errObj.stack;
+    const error = {};
+    Error.captureStackTrace(error, GetResponsibleModule);
+    const trace = error.stack;
     Error.prepareStackTrace = oldHandler;
     Error.stackTraceLimit = oldLimit;
     return trace.slice(startFrame);
 }
-/**
- * Gets the responsible module for the current execution context.
- *
- * Determines which module is responsible for the current code execution by analyzing the call stack.
- * This is used for automatic proxy detachment and event handler cleanup.
- *
- * @param startFrame The starting frame in the stack trace to analyze
- * @returns The module ID or undefined if no module is found
- */
+/** Gets the responsible module from explicit async context or the call stack. */
 function GetResponsibleModule(startFrame = 0) {
-    const explicitContext = responsibleModuleContext.getStore();
-    if (explicitContext) {
-        assertActiveContext(explicitContext);
-        return explicitContext.module;
+    const contextModule = (0, internal_1.getModuleContext)()?.module;
+    if (contextModule) {
+        return contextModule;
     }
     const trace = captureCallStack(startFrame);
     const responsible = (0, responsible_module_1.findResponsibleFile)(trace);