@dxos/app-framework 0.8.2-staging.7ac8446 → 0.8.2

package/src/core/capabilities.test.ts

@@ -2,15 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Registry } from '@effect-rx/rx-react';
 import { Effect } from 'effect';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, onTestFinished } from 'vitest';
 
-import { updateCounter } from '@dxos/echo-schema/testing';
-import { registerSignalsRuntime } from '@dxos/echo-signals';
-
-import { defineCapability, PluginsContext } from './capabilities';
-
-registerSignalsRuntime();
+import { defineCapability, PluginContext } from './capabilities';
 
 const defaultOptions = {
   activate: () => Effect.succeed(false),
@@ -19,99 +15,122 @@ const defaultOptions = {
 
 describe('PluginsContext', () => {
   it('should return empty array if no capabilities are contributed', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+    expect(context.getCapabilities(interfaceDef)).toEqual([]);
   });
 
   it('should be able to contribute and request capabilities', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
     const implementation = { example: 'identifier' };
     context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+    expect(context.getCapabilities(interfaceDef)).toEqual([implementation]);
   });
 
   it('should be able to remove capabilities', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
     const implementation = { example: 'identifier' };
     context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+    expect(context.getCapabilities(interfaceDef)).toEqual([implementation]);
     context.removeCapability(interfaceDef, implementation);
-    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+    expect(context.getCapabilities(interfaceDef)).toEqual([]);
   });
 
   it('should be able to contribute and request multiple implementations', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
     const implementation1 = { example: 'first' };
     const implementation2 = { example: 'second' };
     context.contributeCapability({ interface: interfaceDef, implementation: implementation1, module: 'test' });
     context.contributeCapability({ interface: interfaceDef, implementation: implementation2, module: 'test' });
-    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
+    expect(context.getCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
   });
 
   it('should be able to request multiple capabilities', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef1 = defineCapability<{ one: number }>('@dxos/app-framework/test/one');
     const interfaceDef2 = defineCapability<{ two: number }>('@dxos/app-framework/test/two');
     const implementation1 = { one: 1 };
     const implementation2 = { two: 2 };
     context.contributeCapability({ interface: interfaceDef1, implementation: implementation1, module: 'test' });
     context.contributeCapability({ interface: interfaceDef2, implementation: implementation2, module: 'test' });
-    expect(context.requestCapabilities(interfaceDef1)).toEqual([implementation1]);
-    expect(context.requestCapabilities(interfaceDef2)).toEqual([implementation2]);
+    expect(context.getCapabilities(interfaceDef1)).toEqual([implementation1]);
+    expect(context.getCapabilities(interfaceDef2)).toEqual([implementation2]);
   });
 
   it('should be reactive', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
 
-    using updates = updateCounter(() => {
-      context.requestCapabilities(interfaceDef);
+    let count = 0;
+    const cancel = registry.subscribe(context.capabilities(interfaceDef), () => {
+      count++;
     });
+    onTestFinished(() => cancel());
+    expect(count).toEqual(0);
 
-    expect(updates.count).toEqual(0);
+    registry.get(context.capabilities(interfaceDef));
+    expect(count).toEqual(1);
 
     const implementation = { example: 'identifier' };
     context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(updates.count).toEqual(1);
+    expect(count).toEqual(2);
 
     context.removeCapability(interfaceDef, implementation);
-    expect(updates.count).toEqual(2);
+    expect(count).toEqual(3);
   });
 
   it('should not be reactive to changes within the implementation', () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
 
-    using updates = updateCounter(() => {
-      context.requestCapabilities(interfaceDef);
+    let count = 0;
+    const cancel = registry.subscribe(context.capabilities(interfaceDef), () => {
+      count++;
     });
+    onTestFinished(() => cancel());
+    expect(count).toEqual(0);
 
-    expect(updates.count).toEqual(0);
+    registry.get(context.capabilities(interfaceDef));
+    expect(count).toEqual(1);
 
     const implementation = { example: 'identifier' };
     context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(updates.count).toEqual(1);
+    expect(count).toEqual(2);
 
     implementation.example = 'updated';
-    expect(updates.count).toEqual(1);
+    expect(count).toEqual(2);
 
-    const capabilities = context.requestCapabilities(interfaceDef);
+    const capabilities = context.getCapabilities(interfaceDef);
     expect(capabilities).toEqual([implementation]);
     expect(capabilities[0].example).toEqual('updated');
-    expect(updates.count).toEqual(1);
+    expect(count).toEqual(2);
   });
 
   it('should be able to wait for a capability', async () => {
-    const context = new PluginsContext(defaultOptions);
+    const registry = Registry.make();
+    const context = new PluginContext({ registry, ...defaultOptions });
     const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    let capability: { example: string } | undefined;
+    const cancel = registry.subscribe(context.capabilities(interfaceDef), (capabilities) => {
+      capability = capabilities[0];
+    });
+    onTestFinished(() => cancel());
+    registry.get(context.capabilities(interfaceDef));
+    expect(capability).toBeUndefined();
+
     const implementation = { example: 'identifier' };
-    const promise = context.waitForCapability(interfaceDef);
     context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    const capability = await promise;
     expect(capability).toEqual(implementation);
   });
 });

package/src/core/capabilities.ts

@@ -1,16 +1,12 @@
-/**
- * Interface definition for a capability.
- */
 //
 // Copyright 2025 DXOS.org
 //
 
-import { effect, untracked } from '@preact/signals-core';
+import { type Registry, Rx } from '@effect-rx/rx-react';
 import { Effect } from 'effect';
 
 import { Trigger } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
-import { create } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
@@ -34,7 +30,8 @@ export const defineCapability = <T>(identifier: string) => {
 };
 
 /**
- * Functionality contributed to the application by a plugin module.
+ * A unique string identifier with a Typescript type associated with it.
+ * When a capability is contributed to the application an implementation of the interface is provided.
  */
 export type Capability<T> = {
   /**
@@ -56,6 +53,7 @@ export type Capability<T> = {
 export type AnyCapability = Capability<any>;
 
 type PluginsContextOptions = {
+  registry: Registry.Registry;
   activate: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
   reset: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
 };
@@ -95,10 +93,31 @@ export const lazy =
   };
 
 /**
- * Context which is passed to plugins, allowing them to interact with each other.
+ * Facilitates the dependency injection between [plugin modules](#pluginmodule) by allowing them contribute and request capabilities from each other.
+ * It tracks the capabilities that are contributed in an in-memory live object.
+ * This allows the application to subscribe to this state and incorporate plugins which are added dynamically.
  */
-export class PluginsContext {
-  private readonly _definedCapabilities = new Map<string, CapabilityImpl<unknown>[]>();
+export class PluginContext {
+  private readonly _registry: Registry.Registry;
+
+  private readonly _capabilityImpls = Rx.family<string, Rx.Writable<CapabilityImpl<unknown>[]>>(() => {
+    return Rx.make<CapabilityImpl<unknown>[]>([]).pipe(Rx.keepAlive);
+  });
+
+  readonly _capabilities = Rx.family<string, Rx.Rx<unknown[]>>((id: string) => {
+    return Rx.make((get) => {
+      const current = get(this._capabilityImpls(id));
+      return current.map((c) => c.implementation);
+    });
+  });
+
+  readonly _capability = Rx.family<string, Rx.Rx<unknown>>((id: string) => {
+    return Rx.make((get) => {
+      const current = get(this._capabilities(id));
+      invariant(current.length > 0, `No capability found for ${id}`);
+      return current[0];
+    });
+  });
 
   /**
    * Activates plugins based on the activation event.
@@ -114,7 +133,8 @@ export class PluginsContext {
    */
   readonly reset: PluginsContextOptions['reset'];
 
-  constructor({ activate, reset }: PluginsContextOptions) {
+  constructor({ registry, activate, reset }: PluginsContextOptions) {
+    this._registry = registry;
     this.activate = activate;
     this.reset = reset;
   }
@@ -130,94 +150,98 @@ export class PluginsContext {
     module: string;
     interface: InterfaceDef<T>;
     implementation: T;
-  }) {
-    let current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
-      const object = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
-      current = untracked(() => object.value);
-      this._definedCapabilities.set(interfaceDef.identifier, current);
+  }): void {
+    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
+    const capability = new CapabilityImpl(moduleId, implementation);
+    if (current.includes(capability)) {
+      return;
     }
 
-    current.push(new CapabilityImpl(moduleId, implementation));
+    this._registry.set(this._capabilityImpls(interfaceDef.identifier), [...current, capability]);
     log('capability contributed', {
       id: interfaceDef.identifier,
       moduleId,
-      count: untracked(() => current.length),
+      count: current.length,
     });
   }
 
   /**
    * @internal
    */
-  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T) {
-    const current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
+  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T): void {
+    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
+    if (current.length === 0) {
       return;
     }
 
-    const index = current.findIndex((i) => i.implementation === implementation);
-    if (index !== -1) {
-      current.splice(index, 1);
-      log('capability removed', { id: interfaceDef.identifier, count: untracked(() => current.length) });
+    const next = current.filter((c) => c.implementation !== implementation);
+    if (next.length !== current.length) {
+      this._registry.set(this._capabilityImpls(interfaceDef.identifier), next);
+      log('capability removed', { id: interfaceDef.identifier, count: current.length });
     } else {
       log.warn('capability not removed', { id: interfaceDef.identifier });
     }
   }
 
   /**
-   * Requests capabilities from the plugin context.
-   * @returns An array of capabilities.
-   * @reactive
+   * Get the Rx reference to the available capabilities for a given interface.
+   * Primarily useful for deriving other Rx values based on the capabilities or
+   * for subscribing to changes in the capabilities.
+   * @returns An Rx reference to the available capabilities.
    */
-  requestCapabilities<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T, moduleId: string) => capability is U,
-  ): U[] {
-    let current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
-      const object = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
-      current = untracked(() => object.value);
-      this._definedCapabilities.set(interfaceDef.identifier, current);
-    }
+  capabilities<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T[]> {
+    // NOTE: This the type-checking for capabilities is done at the time of contribution.
+    return this._capabilities(interfaceDef.identifier) as Rx.Rx<T[]>;
+  }
 
+  /**
+   * Get the Rx reference to the available capabilities for a given interface.
+   * Primarily useful for deriving other Rx values based on the capability or
+   * for subscribing to changes in the capability.
+   * @returns An Rx reference to the available capability.
+   * @throws If no capability is found.
+   */
+  capability<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T> {
     // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    const capabilities = filter ? current.filter((c) => filter(c.implementation as T, c.moduleId)) : current;
-    return capabilities.map((c) => c.implementation) as U[];
+    return this._capability(interfaceDef.identifier) as Rx.Rx<T>;
+  }
+
+  /**
+   * Get capabilities from the plugin context.
+   * @returns An array of capabilities.
+   */
+  getCapabilities<T>(interfaceDef: InterfaceDef<T>): T[] {
+    return this._registry.get(this.capabilities(interfaceDef));
   }
 
   /**
    * Requests a single capability from the plugin context.
    * @returns The capability.
    * @throws If no capability is found.
-   * @reactive
    */
-  requestCapability<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T, moduleId: string) => capability is U,
-  ): U {
-    const capability = this.requestCapabilities(interfaceDef, filter)[0];
-    invariant(capability, `No capability found for ${interfaceDef.identifier}`);
-    return capability;
+  getCapability<T>(interfaceDef: InterfaceDef<T>): T {
+    return this._registry.get(this.capability(interfaceDef));
   }
 
   /**
-   * Waits for a capability to be contributed.
+   * Waits for a capability to be available.
    * @returns The capability.
    */
-  async waitForCapability<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T) => capability is U,
-  ): Promise<U> {
-    const trigger = new Trigger<U>();
-    const unsubscribe = effect(() => {
-      const capabilities = this.requestCapabilities(interfaceDef, filter);
-      if (capabilities[0]) {
+  async waitForCapability<T>(interfaceDef: InterfaceDef<T>): Promise<T> {
+    const [capability] = this.getCapabilities(interfaceDef);
+    if (capability) {
+      return capability;
+    }
+
+    const trigger = new Trigger<T>();
+    const cancel = this._registry.subscribe(this.capabilities(interfaceDef), (capabilities) => {
+      if (capabilities.length > 0) {
         trigger.wake(capabilities[0]);
       }
     });
-    const capability = await trigger.wait();
-    unsubscribe();
-    return capability;
+    const result = await trigger.wait();
+    cancel();
+    return result;
   }
 
   async activatePromise(event: ActivationEvent): Promise<boolean> {

package/src/core/events.ts

@@ -3,7 +3,10 @@
 //
 
 /**
- * An event which activates a plugin module.
+ * A unique string identifier representing an event.
+ * This is expected to be a URI, where initial parts are often the id of the plugin whose package defines the event.
+ *
+ * @example dxos.org/plugin/example/event/ready
  */
 export type ActivationEvent = {
   id: string;

package/src/core/manager.test.ts

@@ -11,9 +11,9 @@ import { raise } from '@dxos/debug';
 import { updateCounter } from '@dxos/echo-schema/testing';
 import { registerSignalsRuntime } from '@dxos/echo-signals';
 import { invariant } from '@dxos/invariant';
-import { create } from '@dxos/live-object';
+import { live } from '@dxos/live-object';
 
-import { contributes, defineCapability, type PluginsContext } from './capabilities';
+import { contributes, defineCapability, type PluginContext } from './capabilities';
 import { allOf, defineEvent, oneOf } from './events';
 import { PluginManager } from './manager';
 import { definePlugin, defineModule, type Plugin } from './plugin';
@@ -205,22 +205,22 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(0);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(0);
 
     await manager.add(Plugin1.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(1);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(1);
 
     await manager.add(Plugin2.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id, Plugin2.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(2);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(2);
 
     await manager.add(Plugin3.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id, Plugin2.meta.id, Plugin3.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(3);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(3);
   });
 
   it('should only activate modules after all activatation events have been fired', async () => {
@@ -235,16 +235,16 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
 
     await manager.add(testMeta.id);
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
 
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
   });
 
   it('should only activate modules once when multiple activatation events have been fired', async () => {
@@ -261,25 +261,25 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
     expect(count).toEqual(0);
 
     await manager.add(testMeta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
     expect(count).toEqual(1);
 
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
     expect(count).toEqual(1);
   });
 
   it('should be able to disable and re-enable an active plugin', async () => {
     const state = { total: 0 };
-    const computeTotal = (context: PluginsContext) => {
-      const numbers = context.requestCapabilities(Number);
+    const computeTotal = (context: PluginContext) => {
+      const numbers = context.getCapabilities(Number);
       state.total = numbers.reduce((acc, n) => acc + n.number, 0);
     };
 
@@ -322,7 +322,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([...Test.modules.map((m) => m.id), Count.meta.id]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       expect(totals[0].total).toEqual(6);
     }
@@ -332,7 +332,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([Count.meta.id]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       // Total doesn't change because it is not reactive.
       expect(totals[0].total).toEqual(6);
@@ -343,7 +343,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([Count.meta.id, ...Test.modules.map((m) => m.id)]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       expect(totals[0].total).toEqual(6);
     }
@@ -358,14 +358,14 @@ describe('PluginManager', () => {
         id,
         activatesOn: Events.Startup,
         activatesAfter: [stateEvent],
-        activate: () => contributes(Number, create({ number: 1 })),
+        activate: () => contributes(Number, live({ number: 1 })),
       }),
       defineModule({
         id: 'dxos.org/test/doubler',
         activatesOn: stateEvent,
         activate: (context) => {
-          const counter = context.requestCapability(Number);
-          const state = create({ total: counter.number * 2 });
+          const counter = context.getCapability(Number);
+          const state = live({ total: counter.number * 2 });
           const unsubscribe = effect(() => {
             state.total = counter.number * 2;
           });
@@ -380,8 +380,8 @@ describe('PluginManager', () => {
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual(Test.modules.map((m) => m.id));
 
-    const counter = manager.context.requestCapability(Number);
-    const doubler = manager.context.requestCapability(Total);
+    const counter = manager.context.getCapability(Number);
+    const doubler = manager.context.getCapability(Total);
     expect(counter.number).toEqual(1);
     expect(doubler.total).toEqual(2);