@antelopejs/interface-core 0.0.8 → 0.0.10

package/dist/modules.js

@@ -1,8 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReloadModule = exports.DestroyModule = exports.StopModule = exports.StartModule = exports.LoadModule = exports.GetModuleInfo = exports.ListModules = exports.Events = void 0;
+exports.RunWithModuleContext = RunWithModuleContext;
+exports.GetModuleContext = GetModuleContext;
 const _1 = require(".");
 const internal_1 = require("./internal");
+/** Runs work with module ownership and an optional provider route across awaits. */
+function RunWithModuleContext(context, callback) {
+    return (0, internal_1.runWithModuleContext)(context, callback);
+}
+/** Returns the active module execution context, if one exists. */
+function GetModuleContext() {
+    return (0, internal_1.getModuleContext)();
+}
 /**
  * Contains events related to module lifecycle management.
  *
@@ -19,7 +29,7 @@ var Events;
      *
      * @param module Module ID
      */
-    Events.ModuleConstructed = new _1.EventProxy();
+    Events.ModuleConstructed = new _1.EventProxy("modules.ModuleConstructed");
     /**
      * Event triggers when a module is started.
      *
@@ -28,7 +38,7 @@ var Events;
      *
      * @param module Module ID
      */
-    Events.ModuleStarted = new _1.EventProxy();
+    Events.ModuleStarted = new _1.EventProxy("modules.ModuleStarted");
     /**
      * Event triggers when a module is stopped.
      *
@@ -37,7 +47,7 @@ var Events;
      *
      * @param module Module ID
      */
-    Events.ModuleStopped = new _1.EventProxy();
+    Events.ModuleStopped = new _1.EventProxy("modules.ModuleStopped");
     /**
      * Event triggers when a module is destroyed.
      *
@@ -46,29 +56,52 @@ var Events;
      *
      * @param module Module ID
      */
-    Events.ModuleDestroyed = new _1.EventProxy();
+    Events.ModuleDestroyed = new _1.EventProxy("modules.ModuleDestroyed");
 })(Events || (exports.Events = Events = {}));
-// Using the Events namespace from modules.ts instead of the lowercase events
-Events.ModuleDestroyed.register((module) => {
-    if (internal_1.internal.knownAsync.has(module)) {
-        for (const proxy of internal_1.internal.knownAsync.get(module) ?? []) {
-            proxy.detach();
+function runCleanup(cleanup, module, operation) {
+    try {
+        if ("cleanup" in cleanup) {
+            cleanup.cleanup();
         }
-        internal_1.internal.knownAsync.delete(module);
-    }
-    if (internal_1.internal.knownRegisters.has(module)) {
-        for (const proxy of internal_1.internal.knownRegisters.get(module) ?? []) {
-            proxy.detach();
+        else {
+            cleanup.detach();
         }
-        internal_1.internal.knownRegisters.delete(module);
     }
-    for (const [, proxies] of internal_1.internal.knownRegisters) {
-        for (const proxy of proxies) {
+    catch (error) {
+        internal_1.internal.runtimeErrorReporter?.(error, { operation, module });
+    }
+}
+Events.ModuleDestroyed.register((module) => {
+    (0, internal_1.invalidateModuleContext)(module);
+    for (const cleanup of internal_1.internal.knownAsync.get(module) ?? []) {
+        runCleanup(cleanup, module, "detach-async-provider");
+    }
+    internal_1.internal.knownAsync.delete(module);
+    for (const cleanup of internal_1.internal.knownRegisters.get(module) ?? []) {
+        runCleanup(cleanup, module, "detach-registering-provider");
+    }
+    internal_1.internal.knownRegisters.delete(module);
+    for (const proxy of internal_1.internal.registeringProxies) {
+        try {
             proxy.unregisterModule(module);
         }
+        catch (error) {
+            internal_1.internal.runtimeErrorReporter?.(error, {
+                operation: "unregister-module",
+                module,
+            });
+        }
     }
     for (const proxy of internal_1.internal.knownEvents) {
-        proxy.unregisterModule(module);
+        try {
+            proxy.unregisterModule(module);
+        }
+        catch (error) {
+            internal_1.internal.runtimeErrorReporter?.(error, {
+                operation: "unregister-event-module",
+                module,
+            });
+        }
     }
 });
 /**
@@ -79,7 +112,7 @@ Events.ModuleDestroyed.register((module) => {
  *
  * @returns Array of module IDs
  */
-exports.ListModules = (0, _1.InterfaceFunction)();
+exports.ListModules = (0, _1.InterfaceFunction)("modules.ListModules");
 /**
  * Retrieve the configuration and status information of a loaded module.
  *
@@ -89,7 +122,7 @@ exports.ListModules = (0, _1.InterfaceFunction)();
  * @param module The module ID to get information for
  * @returns Complete module information object
  */
-exports.GetModuleInfo = (0, _1.InterfaceFunction)();
+exports.GetModuleInfo = (0, _1.InterfaceFunction)("modules.GetModuleInfo");
 /**
  * Load a new module with the given ID and configuration.
  *
@@ -100,7 +133,7 @@ exports.GetModuleInfo = (0, _1.InterfaceFunction)();
  * @param configuration Module configuration including source information
  * @param autostart Whether to automatically start the module after loading (default: false)
  */
-exports.LoadModule = (0, _1.InterfaceFunction)();
+exports.LoadModule = (0, _1.InterfaceFunction)("modules.LoadModule");
 /**
  * Start a loaded but inactive module.
  *
@@ -110,7 +143,7 @@ exports.LoadModule = (0, _1.InterfaceFunction)();
  * @param module The module ID to start
  * @throws Error if the module is not loaded or cannot be started
  */
-exports.StartModule = (0, _1.InterfaceFunction)();
+exports.StartModule = (0, _1.InterfaceFunction)("modules.StartModule");
 /**
  * Stop an active module.
  *
@@ -120,7 +153,7 @@ exports.StartModule = (0, _1.InterfaceFunction)();
  * @param module The module ID to stop
  * @throws Error if the module is not loaded or cannot be stopped
  */
-exports.StopModule = (0, _1.InterfaceFunction)();
+exports.StopModule = (0, _1.InterfaceFunction)("modules.StopModule");
 /**
  * Destroy a stopped module.
  *
@@ -130,7 +163,7 @@ exports.StopModule = (0, _1.InterfaceFunction)();
  * @param module The module ID to destroy
  * @throws Error if the module is active or not loaded
  */
-exports.DestroyModule = (0, _1.InterfaceFunction)();
+exports.DestroyModule = (0, _1.InterfaceFunction)("modules.DestroyModule");
 /**
  * Unload a module and retrigger its source mechanism.
  *
@@ -141,5 +174,5 @@ exports.DestroyModule = (0, _1.InterfaceFunction)();
  * @param module The module ID to reload
  * @throws Error if the module cannot be reloaded
  */
-exports.ReloadModule = (0, _1.InterfaceFunction)();
+exports.ReloadModule = (0, _1.InterfaceFunction)("modules.ReloadModule");
 //# sourceMappingURL=modules.js.map

package/dist/modules.js.map

@@ -1 +1 @@
-{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":";;;AAAA,wBAAkD;AAClD,yCAAsC;AAEtC;;;;;GAKG;AACH,IAAiB,MAAM,CAwCtB;AAxCD,WAAiB,MAAM;IACrB;;;;;;;OAOG;IACU,wBAAiB,GAAG,IAAI,aAAU,EAA4B,CAAC;IAE5E;;;;;;;OAOG;IACU,oBAAa,GAAG,IAAI,aAAU,EAA4B,CAAC;IAExE;;;;;;;OAOG;IACU,oBAAa,GAAG,IAAI,aAAU,EAA4B,CAAC;IAExE;;;;;;;OAOG;IACU,sBAAe,GAAG,IAAI,aAAU,EAA4B,CAAC;AAC5E,CAAC,EAxCgB,MAAM,sBAAN,MAAM,QAwCtB;AAED,6EAA6E;AAC7E,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;IACzC,IAAI,mBAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,mBAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1D,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;QACD,mBAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,mBAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,KAAK,MAAM,KAAK,IAAI,mBAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAC9D,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;QACD,mBAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,mBAAQ,CAAC,cAAc,EAAE,CAAC;QAClD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,mBAAQ,CAAC,WAAW,EAAE,CAAC;QACzC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;AACH,CAAC,CAAC,CAAC;AAuDH;;;;;;;GAOG;AACU,QAAA,WAAW,GAAG,IAAA,oBAAiB,GAAkB,CAAC;AAE/D;;;;;;;;GAQG;AACU,QAAA,aAAa,GACxB,IAAA,oBAAiB,GAAkC,CAAC;AAEtD;;;;;;;;;GASG;AACU,QAAA,UAAU,GACrB,IAAA,oBAAiB,GAMd,CAAC;AAEN;;;;;;;;GAQG;AACU,QAAA,WAAW,GAAG,IAAA,oBAAiB,GAA4B,CAAC;AAEzE;;;;;;;;GAQG;AACU,QAAA,UAAU,GAAG,IAAA,oBAAiB,GAA4B,CAAC;AAExE;;;;;;;;GAQG;AACU,QAAA,aAAa,GAAG,IAAA,oBAAiB,GAA4B,CAAC;AAE3E;;;;;;;;;GASG;AACU,QAAA,YAAY,GAAG,IAAA,oBAAiB,GAA4B,CAAC"}
+{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":";;;AAWA,oDAKC;AAGD,4CAEC;AArBD,wBAAkD;AAClD,yCAOoB;AAEpB,oFAAoF;AACpF,SAAgB,oBAAoB,CAClC,OAA+B,EAC/B,QAAiB;IAEjB,OAAO,IAAA,+BAAoB,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED,kEAAkE;AAClE,SAAgB,gBAAgB;IAC9B,OAAO,IAAA,2BAAgB,GAAE,CAAC;AAC5B,CAAC;AAID;;;;;GAKG;AACH,IAAiB,MAAM,CAgDtB;AAhDD,WAAiB,MAAM;IACrB;;;;;;;OAOG;IACU,wBAAiB,GAAG,IAAI,aAAU,CAC7C,2BAA2B,CAC5B,CAAC;IAEF;;;;;;;OAOG;IACU,oBAAa,GAAG,IAAI,aAAU,CACzC,uBAAuB,CACxB,CAAC;IAEF;;;;;;;OAOG;IACU,oBAAa,GAAG,IAAI,aAAU,CACzC,uBAAuB,CACxB,CAAC;IAEF;;;;;;;OAOG;IACU,sBAAe,GAAG,IAAI,aAAU,CAC3C,yBAAyB,CAC1B,CAAC;AACJ,CAAC,EAhDgB,MAAM,sBAAN,MAAM,QAgDtB;AAED,SAAS,UAAU,CACjB,OAA4C,EAC5C,MAAc,EACd,SAAiB;IAEjB,IAAI,CAAC;QACH,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mBAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;IACzC,IAAA,kCAAuB,EAAC,MAAM,CAAC,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,mBAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5D,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACvD,CAAC;IACD,mBAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnC,KAAK,MAAM,OAAO,IAAI,mBAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAChE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,6BAA6B,CAAC,CAAC;IAC7D,CAAC;IACD,mBAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,mBAAQ,CAAC,kBAAkB,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mBAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE;gBACrC,SAAS,EAAE,mBAAmB;gBAC9B,MAAM;aACP,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,mBAAQ,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mBAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE;gBACrC,SAAS,EAAE,yBAAyB;gBACpC,MAAM;aACP,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC;AAuDH;;;;;;;GAOG;AACU,QAAA,WAAW,GAAG,IAAA,oBAAiB,EAC1C,qBAAqB,CACtB,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,aAAa,GAAG,IAAA,oBAAiB,EAC5C,uBAAuB,CACxB,CAAC;AAEF;;;;;;;;;GASG;AACU,QAAA,UAAU,GACrB,IAAA,oBAAiB,EAMf,oBAAoB,CAAC,CAAC;AAE1B;;;;;;;;GAQG;AACU,QAAA,WAAW,GAAG,IAAA,oBAAiB,EAC1C,qBAAqB,CACtB,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,UAAU,GACrB,IAAA,oBAAiB,EAA2B,oBAAoB,CAAC,CAAC;AAEpE;;;;;;;;GAQG;AACU,QAAA,aAAa,GAAG,IAAA,oBAAiB,EAC5C,uBAAuB,CACxB,CAAC;AAEF;;;;;;;;;GASG;AACU,QAAA,YAAY,GAAG,IAAA,oBAAiB,EAC3C,sBAAsB,CACvB,CAAC"}

package/dist/proxies.d.ts

@@ -1,135 +1,74 @@
+import { type ProxyBrand } from "./internal";
 type Func<A extends any[] = any[], R = any> = (...args: A) => R;
-/**
- * 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.
- */
-export declare class AsyncProxy<T extends Func = Func, R = Awaited<ReturnType<T>>> {
-    private callback?;
-    private 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
-     */
-    onCall(callback: T, manualDetach?: boolean): void;
-    /**
-     * Manually detach the callback on this proxy.
-     */
-    detach(): void;
-    /**
-     * Call the function attached to this proxy.
-     *
-     * If a callback has not been attached yet, the call is queued up for later.
-     */
-    call(...args: Parameters<T>): Promise<R>;
-}
 type RegisterFunction = (id: any, ...args: any[]) => void;
 type RID<T> = T extends (id: infer P, ...args: any[]) => void ? P : never;
 type RArgs<T> = T extends (id: any, ...args: infer P) => void ? P : never;
-/**
- * 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.
- */
+type ProxyKind = ProxyBrand["kind"];
+declare const PROXY_BRAND: unique symbol;
+export interface AttachmentLease {
+    generation: number;
+    owner: string;
+    provider: string;
+}
+/** Returns whether a value implements this runtime's stable proxy protocol. */
+export declare function IsInterfaceProxy(value: unknown, kind?: ProxyKind): boolean;
+/** Returns the stable identity used to bind a proxy to a provider route. */
+export declare function GetInterfaceProxyIdentity(value: unknown): string | undefined;
+/** @internal */
+export declare function InvalidateResponsibleModule(module: string): void;
+/** Runs work with explicit module ownership across asynchronous boundaries. */
+export declare function RunWithResponsibleModule<T>(module: string, callback: () => T): T;
+/** Proxy for an asynchronous interface function. */
+export declare class AsyncProxy<T extends Func = Func, R = Awaited<ReturnType<T>>> {
+    readonly [PROXY_BRAND]: ProxyBrand;
+    private readonly state;
+    constructor(identity?: string);
+    /** Attaches a provider callback and replays compatible queued calls. */
+    onCall(callback: T, manualDetach?: boolean): AttachmentLease;
+    /** Detaches one leased provider, or every provider when called without a lease. */
+    detach(lease?: AttachmentLease): void;
+    /** Calls the provider selected by the current module execution context. */
+    call(...args: Parameters<T>): Promise<R>;
+    private invoke;
+    private replayQueue;
+}
+/** Proxy for provider-aware register and unregister handlers. */
 export declare class RegisteringProxy<T extends RegisterFunction = RegisterFunction> {
-    private registerCallback?;
-    private unregisterCallback?;
-    private registered;
-    /**
-     * 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
-     */
-    onRegister(callback: T, manualDetach?: boolean): void;
-    /**
-     * 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: (id: RID<T>) => void): void;
-    /**
-     * Manually detach the callbacks on this proxy.
-     */
-    detach(): void;
-    /**
-     * 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
-     */
+    readonly [PROXY_BRAND]: ProxyBrand;
+    private readonly state;
+    constructor(identity?: string);
+    /** Attaches a register callback. */
+    onRegister(callback: T, manualDetach?: boolean): AttachmentLease;
+    /** Attaches an unregister callback to the current provider route. */
+    onUnregister(callback: (id: RID<T>) => void): AttachmentLease;
+    /** Atomically attaches both registration handlers. */
+    onHandlers(register: T, unregister: (id: RID<T>) => void, manualDetach?: boolean): AttachmentLease;
+    /** Detaches one leased provider, or every provider when called without a lease. */
+    detach(lease?: AttachmentLease): void;
+    /** Registers an entry with the selected provider or queues it for bootstrap. */
     register(id: RID<T>, ...args: RArgs<T>): void;
-    /**
-     * 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: RID<T>): void;
-    /**
-     * Unregister all entries created by the given module
-     * @internal
-     *
-     * @param mod Module ID
-     */
-    unregisterModule(mod: string): void;
+    /** Unregisters every entry owned by a destroyed module. */
+    unregisterModule(module: string): void;
+    private attachHandlers;
+    private replayRegistrations;
 }
 type EventFunction = (...args: any[]) => void;
-/**
- * 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. */
 export declare class EventProxy<T extends EventFunction = EventFunction> {
-    private registered;
-    constructor();
-    /**
-     * Call all the event handlers with the specified arguments.
-     *
-     * @param args Arguments
-     */
+    readonly [PROXY_BRAND]: ProxyBrand;
+    private readonly state;
+    constructor(identity?: string);
+    /** Emits to every handler, reporting failures without aborting later handlers. */
     emit(...args: Parameters<T>): void;
-    /**
-     * Register a new handler for this event.
-     *
-     * @param func Handler
-     */
+    /** Registers a handler once. */
     register(func: T): void;
-    /**
-     * Unregister a handler on this event.
-     *
-     * @param fn The handler that was passed to {@link register}
-     */
+    /** Unregisters a handler. */
     unregister(fn: T): void;
-    /**
-     * Unregister all handlers created by the given module.
-     * @internal
-     *
-     * @param mod Module ID
-     */
-    unregisterModule(mod: string): void;
+    /** Unregisters handlers owned by a destroyed module. */
+    unregisterModule(module: string): void;
 }
-/**
- * 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. */
 export declare function GetResponsibleModule(startFrame?: number): string | undefined;
 export {};