@antelopejs/interface-core 0.1.0 → 0.2.0

package/docs/2.proxies.md

@@ -4,9 +4,11 @@
 
 Proxies are the backbone of cross-module communication in AntelopeJS. They provide module-aware abstractions for function calls, event handling, and registration patterns. Each proxy type automatically tracks the module that attaches callbacks and detaches them when that module is unloaded, preventing memory leaks and dangling references.
 
+A proxy has a single provider and keeps its state on the proxy object itself. When a project has several providers of one interface, the core evaluates a separate instance of the interface package for each provider, so each instance's proxies reach exactly one provider; no call selects a provider at run time.
+
 ## `AsyncProxy`
 
-`AsyncProxy` wraps asynchronous function calls. It queues invocations when no callback is attached and flushes the queue once a callback becomes available.
+`AsyncProxy` wraps asynchronous function calls. It queues invocations when no callback is attached and flushes the queue once a callback becomes available. The queue holds at most 1,000 pending calls: once it is full, further calls reject with `ProviderQueueFullError` until a callback attaches.
 
 ### Create and use an `AsyncProxy`
 
@@ -29,9 +31,9 @@ const greeting = await proxy.call("Bob"); // "Hello, Bob!"
 
 ### `onCall(callback, manualDetach?)`
 
-Attaches a callback function to the proxy. The proxy automatically tracks the calling module and detaches the callback when that module is unloaded. Pass `manualDetach: true` to disable automatic cleanup.
+Attaches the provider's callback to the proxy, replacing any callback attached before, so a provider's new generation takes over from the old one. The proxy automatically tracks the calling module and detaches the callback when that module is unloaded; releasing an older generation never detaches a newer one. Pass `manualDetach: true` to disable automatic cleanup.
 
-When attachment occurs inside `RunWithModuleContext`, calls execute in the captured provider context rather than the consumer context. The captured module, owner generation, provider, and provider routes remain available across nested calls and `await`. Calls reject with `ModuleContextInvalidatedError` if the captured owner has been destroyed.
+When attachment occurs inside `RunWithModuleContext`, calls execute in the captured provider context rather than the consumer context. The captured module and owner generation remain available across nested calls and `await`. Calls reject with `ModuleContextInvalidatedError` if the captured owner has been destroyed.
 
 ```ts
 // Automatic cleanup (default) - detaches when the module unloads
@@ -88,7 +90,7 @@ onUserCreated.emit("u-1", "Alice");
 
 ### `register(func)`
 
-Registers a handler for the event. Duplicate handlers (same function reference) are ignored. The proxy tracks the calling module and removes the handler when that module is unloaded.
+Registers a handler for the event. Duplicate handlers (same function reference) are ignored. The proxy tracks the calling module and removes the handler when that module is unloaded. The handler runs in the context of the module that registered it, whichever module emits the event.
 
 ### `emit(...args)`
 
@@ -100,7 +102,7 @@ Removes a specific handler by function reference.
 
 ## `RegisteringProxy`
 
-`RegisteringProxy` manages a register/unregister pair. It tracks registered entries by a unique identifier and supports queuing registrations until the callbacks are attached.
+`RegisteringProxy` manages a register/unregister pair. It tracks registered entries by a unique identifier and keeps every entry so it can replay them when callbacks attach. This registry is not capped: registering entries without an attached provider never throws `ProviderQueueFullError`.
 
 ### Create and use a `RegisteringProxy`
 
@@ -152,6 +154,15 @@ Removes the entry with the given identifier and calls the unregister callback if
 
 Manually removes both the register and unregister callbacks. Registered entries remain stored.
 
+## Functions passed through a proxy
+
+A function a module hands to a proxy runs as that module's work, whoever invokes it later:
+
+- an event handler runs in the context of the module that registered it;
+- a function passed as an argument to `AsyncProxy.call` or `RegisteringProxy.register`, or held in a plain object or array passed that way, runs in the context of the module that made the call.
+
+Inside such a function, `GetModuleContext` and `GetResponsibleModule` report the module that passed it, and what it registers is owned by that module. Once that module's generation is destroyed, invoking the function throws `ModuleContextInvalidatedError`. Plain data, class instances and proxies cross unchanged; a function passed twice reaches the provider as the same value, and a function passed on by another module keeps its original context.
+
 ## `ImplementInterface`
 
 `ImplementInterface` connects an interface declaration to its implementation. It iterates over the declaration object and wires up each proxy to the corresponding implementation function.
@@ -228,17 +239,19 @@ const connections = GetInterfaceInstances("database");
 const primary = GetInterfaceInstance("database", "primary");
 ```
 
-Each `InterfaceConnection` includes the provider module ID and whether that provider is selected for unqualified calls:
+Each `InterfaceConnection` includes the path to `require()` for the interface instance bound to that connection, the provider module ID (absent for a connection to a self-hosted interface), and whether it is the connection a plain import reaches:
 
 ```ts
 interface InterfaceConnection {
   id?: string;
   path: string;
-  provider: string;
+  provider?: string;
   selected: boolean;
 }
 ```
 
+Requiring a connection's `path` (or a subpath of it) gives the interface bound to that connection's provider, and the objects built from it stay bound to that provider wherever they are used.
+
 ## `GetResponsibleModule`
 
 `GetResponsibleModule` inspects the call stack to determine which module is responsible for the current execution. The proxy classes use this internally for automatic cleanup tracking.

package/docs/5.modules.md

@@ -37,7 +37,7 @@ loaded -> constructed -> active -> constructed -> loaded
 
 ## Module execution context
 
-`RunWithModuleContext` propagates module ownership and provider routing through synchronous and asynchronous work:
+`RunWithModuleContext` propagates module ownership through synchronous and asynchronous work:
 
 ```ts
 import { RunWithModuleContext } from "@antelopejs/interface-core/modules";
@@ -46,8 +46,6 @@ await RunWithModuleContext(
   {
     module: "search-provider",
     owner: "search-provider#42",
-    provider: "search-provider",
-    providerRoutes: routes,
   },
   () => constructModule(),
 );

package/docs/7.configuration.md

@@ -154,13 +154,16 @@ Like the local source, `local-folder` also accepts an optional `reloadCommand` t
 
 Full module configuration within the project config.
 
-| Property          | Type                                         | Description                                           |
-| ----------------- | -------------------------------------------- | ----------------------------------------------------- |
-| `version`         | `string`                                     | Optional version constraint                           |
-| `source`          | `ModuleSource*`                              | Source definition (local, git, package, local-folder) |
-| `config`          | `unknown`                                    | Optional runtime configuration                        |
-| `importOverrides` | `ImportOverride[] \| Record<string, string>` | Optional import path redirections                     |
-| `disabledExports` | `string[]`                                   | Optional list of exports to disable                   |
+| Property          | Type                                         | Description                                                                                                        |
+| ----------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `version`         | `string`                                     | Optional version constraint                                                                                        |
+| `source`          | `ModuleSource*`                              | Source definition (local, git, package, local-folder)                                                              |
+| `config`          | `unknown`                                    | Optional runtime configuration                                                                                     |
+| `importOverrides` | `ImportOverride[] \| Record<string, string>` | Optional providers pinned for the interfaces the module uses, and named connections                                |
+| `disabledExports` | `string[]`                                   | Optional list of exports to disable                                                                                |
+| `exportPriority`  | `Record<string, number>`                     | Optional priority of this module as the default provider of each interface it implements (default 0; highest wins) |
+
+An `ImportOverride` is `{ interface, source?, id? }`. The first entry for an interface pins it to the `source` module; further entries are connections reached through `GetInterfaceInstance(interface, id)`. An entry for a standalone interface may omit `source`, declaring a connection to that self-hosted interface.
 
 ## `AntelopeLogging`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AntelopeJS core interface primitives - proxies, decorators, interface functions, and logging",
   "keywords": [
     "antelopejs",
@@ -90,7 +90,7 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@antelopejs/tooling-configs": "^0.0.4",
+    "@antelopejs/tooling-configs": "^0.0.6",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",

package/dist/tests/provider-routing.test.js

@@ -1,78 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const chai_1 = require("chai");
-const modules_1 = require("../modules");
-const __1 = require("..");
-describe("provider routing and leases", () => {
-    it("routes providers through async module execution context", async () => {
-        const proxy = new __1.AsyncProxy("test.provider-routing");
-        (0, modules_1.RunWithModuleContext)({ module: "owner-a", provider: "provider-a" }, () => {
-            proxy.onCall(() => "a");
-        });
-        (0, modules_1.RunWithModuleContext)({ module: "owner-b", provider: "provider-b" }, () => {
-            proxy.onCall(() => "b");
-        });
-        (0, chai_1.expect)(await (0, modules_1.RunWithModuleContext)({ module: "consumer", provider: "provider-a" }, () => proxy.call())).to.equal("a");
-        (0, chai_1.expect)(await (0, modules_1.RunWithModuleContext)({ module: "consumer", provider: "provider-b" }, () => proxy.call())).to.equal("b");
-        const error = await proxy.call().then(() => undefined, (reason) => reason);
-        (0, chai_1.expect)(error).to.be.instanceOf(__1.AmbiguousProviderError);
-    });
-    it("rejects an explicit route that has no attached provider", async () => {
-        const proxy = new __1.AsyncProxy("test.missing-route");
-        (0, modules_1.RunWithModuleContext)({ module: "owner", provider: "available" }, () => {
-            proxy.onCall(() => "ok");
-        });
-        const result = (0, modules_1.RunWithModuleContext)({ module: "consumer", provider: "missing" }, () => proxy.call());
-        const error = await result.then(() => undefined, (reason) => reason);
-        (0, chai_1.expect)(error).to.be.instanceOf(__1.MissingProviderError);
-    });
-    it("supports per-proxy provider bindings in one module context", async () => {
-        const first = new __1.AsyncProxy("test.route-map.first");
-        const second = new __1.AsyncProxy("test.route-map.second");
-        (0, modules_1.RunWithModuleContext)({ module: "owner-a", provider: "provider-a" }, () => {
-            first.onCall(() => "first-a");
-            second.onCall(() => "second-a");
-        });
-        (0, modules_1.RunWithModuleContext)({ module: "owner-b", provider: "provider-b" }, () => {
-            first.onCall(() => "first-b");
-            second.onCall(() => "second-b");
-        });
-        const firstIdentity = (0, __1.GetInterfaceProxyIdentity)(first);
-        const secondIdentity = (0, __1.GetInterfaceProxyIdentity)(second);
-        const values = await (0, modules_1.RunWithModuleContext)({
-            module: "consumer",
-            providerRoutes: {
-                [firstIdentity]: "provider-a",
-                [secondIdentity]: "provider-b",
-            },
-        }, () => Promise.all([first.call(), second.call()]));
-        (0, chai_1.expect)(values).to.deep.equal(["first-a", "second-b"]);
-    });
-    it("routes registrations and unregisters to the bound provider", () => {
-        const proxy = new __1.RegisteringProxy("test.registering-routes");
-        const calls = [];
-        (0, modules_1.RunWithModuleContext)({ module: "owner-a", provider: "provider-a" }, () => {
-            proxy.onHandlers((id) => calls.push(`register-a:${id}`), (id) => calls.push(`unregister-a:${id}`));
-        });
-        (0, modules_1.RunWithModuleContext)({ module: "owner-b", provider: "provider-b" }, () => {
-            proxy.onHandlers((id) => calls.push(`register-b:${id}`), (id) => calls.push(`unregister-b:${id}`));
-        });
-        (0, modules_1.RunWithModuleContext)({ module: "consumer", provider: "provider-b" }, () => {
-            proxy.register("item");
-            proxy.unregister("item");
-        });
-        (0, chai_1.expect)(calls).to.deep.equal(["register-b:item", "unregister-b:item"]);
-    });
-    it("does not let an old owner lease detach a newer provider generation", async () => {
-        const proxy = new __1.AsyncProxy("test.provider-lease");
-        (0, modules_1.RunWithModuleContext)({ module: "owner-a", provider: "shared" }, () => {
-            proxy.onCall(() => "old");
-        });
-        (0, modules_1.RunWithModuleContext)({ module: "owner-b", provider: "shared" }, () => {
-            proxy.onCall(() => "new");
-        });
-        modules_1.Events.ModuleDestroyed.emit("owner-a");
-        (0, chai_1.expect)(await (0, modules_1.RunWithModuleContext)({ module: "consumer", provider: "shared" }, () => proxy.call())).to.equal("new");
-    });
-});
-//# sourceMappingURL=provider-routing.test.js.map

package/dist/tests/provider-routing.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-routing.test.js","sourceRoot":"","sources":["../../src/tests/provider-routing.test.ts"],"names":[],"mappings":"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"}