@dxos/app-framework 0.8.3 → 0.8.4-main.1068cf700f

package/src/core/capability-manager.ts

@@ -0,0 +1,171 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+import type * as Capability from './capability';
+
+type CapabilityEntry<T> = {
+  moduleId: string;
+  implementation: T;
+};
+
+/**
+ * Options for creating a capability manager.
+ * @internal
+ */
+export type CapabilityManagerOptions = {
+  registry: Registry.Registry;
+};
+
+/**
+ * Interface for the Capability Manager.
+ * Provides methods for contributing, removing, and accessing capabilities.
+ */
+export interface CapabilityManager {
+  contribute<T>(args: { module: string; interface: Capability.InterfaceDef<T>; implementation: T }): void;
+
+  remove<T>(interfaceDef: Capability.InterfaceDef<T>, implementation: T): void;
+
+  /**
+   * Get the Atom reference to the available capabilities for a given interface.
+   * Primarily useful for deriving other Atom values based on the capabilities or
+   * for subscribing to changes in the capabilities.
+   * @returns An atom reference to the available capabilities.
+   */
+  atom<T>(interfaceDef: Capability.InterfaceDef<T>): Atom.Atom<T[]>;
+
+  /**
+   * Get capabilities from the capability manager.
+   * @returns An array of capabilities.
+   */
+  getAll<T>(interfaceDef: Capability.InterfaceDef<T>): T[];
+
+  /**
+   * Requests a single capability from the capability manager.
+   * @returns The capability.
+   * @throws If no capability is found.
+   */
+  get<T>(interfaceDef: Capability.InterfaceDef<T>): T;
+
+  /**
+   * Waits for a capability to be available.
+   * @returns The capability.
+   */
+  waitFor<T>(interfaceDef: Capability.InterfaceDef<T>): Effect.Effect<T, Error>;
+}
+
+/**
+ * Internal implementation of CapabilityManager.
+ */
+class CapabilityManagerImpl implements CapabilityManager {
+  private readonly _registry: Registry.Registry;
+
+  private readonly _capabilityEntries = Atom.family<string, Atom.Writable<CapabilityEntry<unknown>[]>>(() => {
+    return Atom.make<CapabilityEntry<unknown>[]>([]).pipe(Atom.keepAlive);
+  });
+
+  readonly _capabilities = Atom.family<string, Atom.Atom<unknown[]>>((id: string) => {
+    return Atom.make((get) => {
+      const current = get(this._capabilityEntries(id));
+      return current.map((c) => c.implementation);
+    });
+  });
+
+  readonly _capability = Atom.family<string, Atom.Atom<unknown>>((id: string) => {
+    return Atom.make((get) => {
+      const current = get(this._capabilities(id));
+      invariant(current.length > 0, `No capability found for ${id}`);
+      return current[0];
+    });
+  });
+
+  constructor({ registry }: CapabilityManagerOptions) {
+    this._registry = registry;
+  }
+
+  contribute<T>({
+    module: moduleId,
+    interface: interfaceDef,
+    implementation,
+  }: {
+    module: string;
+    interface: Capability.InterfaceDef<T>;
+    implementation: T;
+  }): void {
+    const current = this._registry.get(this._capabilityEntries(interfaceDef.identifier));
+    const isDuplicate = current.some((c) => c.moduleId === moduleId && c.implementation === implementation);
+    if (isDuplicate) {
+      log('capability already contributed, skipping', { id: interfaceDef.identifier, moduleId });
+      return;
+    }
+
+    const entry: CapabilityEntry<T> = { moduleId, implementation };
+    this._registry.set(this._capabilityEntries(interfaceDef.identifier), [...current, entry]);
+    log('capability contributed', {
+      id: interfaceDef.identifier,
+      moduleId,
+      count: current.length,
+    });
+  }
+
+  remove<T>(interfaceDef: Capability.InterfaceDef<T>, implementation: T): void {
+    const current = this._registry.get(this._capabilityEntries(interfaceDef.identifier));
+    if (current.length === 0) {
+      return;
+    }
+
+    const next = current.filter((c) => c.implementation !== implementation);
+    if (next.length !== current.length) {
+      this._registry.set(this._capabilityEntries(interfaceDef.identifier), next);
+      log('capability removed', { id: interfaceDef.identifier, count: current.length });
+    } else {
+      log.warn('capability not removed', { id: interfaceDef.identifier });
+    }
+  }
+
+  atom<T>(interfaceDef: Capability.InterfaceDef<T>): Atom.Atom<T[]> {
+    // NOTE: This the type-checking for capabilities is done at the time of contribution.
+    return this._capabilities(interfaceDef.identifier) as Atom.Atom<T[]>;
+  }
+
+  getAll<T>(interfaceDef: Capability.InterfaceDef<T>): T[] {
+    return this._registry.get(this.atom(interfaceDef));
+  }
+
+  get<T>(interfaceDef: Capability.InterfaceDef<T>): T {
+    const capabilities = this.getAll(interfaceDef);
+    invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
+    return capabilities[0];
+  }
+
+  waitFor<T>(interfaceDef: Capability.InterfaceDef<T>): Effect.Effect<T, Error> {
+    return Effect.gen(this, function* () {
+      const [capability] = this.getAll(interfaceDef);
+      if (capability) {
+        return capability;
+      }
+
+      const deferred = yield* Deferred.make<T, Error>();
+      const cancel = this._registry.subscribe(this.atom(interfaceDef), (capabilities) => {
+        if (capabilities.length > 0) {
+          Effect.runSync(Deferred.succeed(deferred, capabilities[0]));
+        }
+      });
+      const result = yield* Deferred.await(deferred);
+      cancel();
+      return result;
+    });
+  }
+}
+
+/**
+ * Creates a new Capability Manager instance.
+ */
+export const make = (options: CapabilityManagerOptions): CapabilityManager => new CapabilityManagerImpl(options);

package/src/core/capability.ts

@@ -0,0 +1,236 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+
+import type * as CapabilityManager from './capability-manager';
+import type * as Plugin from './plugin';
+
+//
+// Capability Service Layer
+//
+
+/**
+ * Effect Context.Tag for accessing CapabilityManager via the Effect layer system.
+ * This allows capability modules to access the capability manager without having it passed as an argument.
+ */
+export class Service extends Context.Tag('@dxos/app-framework/CapabilityManager')<
+  Service,
+  CapabilityManager.CapabilityManager
+>() {}
+
+/**
+ * Get a single capability from the capability manager.
+ * @param interfaceDef The interface definition of the capability.
+ * @returns The capability implementation.
+ * @throws If no capability is found.
+ */
+// TODO(wittjosiah): Add custom tagged errors (Data.TaggedError) for app-framework to enable
+//   type-safe error handling with Effect. Consider CapabilityNotFoundError, ModuleActivationError, etc.
+export const get = <T>(interfaceDef: InterfaceDef<T>): Effect.Effect<T, Error, Service> =>
+  Effect.flatMap(Service, (manager) =>
+    Effect.try({
+      try: () => manager.get(interfaceDef),
+      catch: (error) => (error instanceof Error ? error : new Error(String(error))),
+    }),
+  );
+
+/**
+ * Get all capabilities from the capability manager for a given interface.
+ * @param interfaceDef The interface definition of the capability.
+ * @returns An array of capability implementations.
+ */
+export const getAll = <T>(interfaceDef: InterfaceDef<T>): Effect.Effect<T[], never, Service> =>
+  Effect.map(Service, (manager) => manager.getAll(interfaceDef));
+
+/**
+ * Wait for a capability to be available.
+ * @param interfaceDef The interface definition of the capability.
+ * @returns The capability implementation once available.
+ */
+export const waitFor = <T>(interfaceDef: InterfaceDef<T>): Effect.Effect<T, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.waitFor(interfaceDef));
+
+/**
+ * Get the Atom reference to capabilities for reactive access.
+ * @param interfaceDef The interface definition of the capability.
+ * @returns An Atom containing the array of capability implementations.
+ */
+export const atom = <T>(interfaceDef: InterfaceDef<T>): Effect.Effect<Atom.Atom<T[]>, never, Service> =>
+  Effect.map(Service, (manager) => manager.atom(interfaceDef));
+
+const InterfaceDefTypeId: unique symbol = Symbol.for('InterfaceDefTypeId');
+
+/**
+ * Symbol used to tag lazy capability functions with their module ID.
+ */
+export const ModuleTag: unique symbol = Symbol.for('@dxos/app-framework/ModuleTag');
+
+/**
+ * The interface definition of a capability.
+ */
+export type InterfaceDef<T> = {
+  [InterfaceDefTypeId]: T;
+  identifier: string;
+};
+
+export namespace InterfaceDef {
+  export type Implementation<I extends InterfaceDef<any>> = I extends InterfaceDef<infer T> ? T : never;
+}
+
+/**
+ * Helper to define the interface of a capability.
+ */
+export const make = <T>(identifier: string) => {
+  return { identifier } as InterfaceDef<T>;
+};
+
+/**
+ * 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> = {
+  /**
+   * The interface definition of the capability.
+   */
+  readonly interface: InterfaceDef<T>;
+
+  /**
+   * The implementation of the capability.
+   */
+  readonly implementation: T;
+
+  /**
+   * Called when the capability is deactivated.
+   */
+  readonly deactivate?: () => Effect.Effect<void, Error>;
+};
+
+export type Any = Capability<any>;
+
+/**
+ * Union type representing all valid return types for a capability module.
+ * Supports single capabilities, arrays, and tuples of different capability types.
+ */
+export type ModuleReturn = void | Any | Any[] | readonly Any[] | [Any, ...Any[]] | readonly [Any, ...Any[]];
+
+/**
+ * Helper to define the implementation of a capability.
+ */
+export const contributes = <I extends InterfaceDef<any>>(
+  interfaceDef: I,
+  implementation: Capability<InterfaceDef.Implementation<I>>['implementation'],
+  deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
+): Capability<I> => {
+  return {
+    interface: interfaceDef,
+    implementation,
+    deactivate,
+  } satisfies Capability<I>;
+};
+
+type LoadCapability<Props, Capabilities extends ModuleReturn = ModuleReturn> = () => Promise<{
+  default: (props?: Props) => Effect.Effect<Capabilities, Error, Service | Plugin.Service | never>;
+}>;
+type LoadCapabilities<Props, Capabilities extends ModuleReturn = ModuleReturn> = () => Promise<{
+  default: (props?: Props) => Effect.Effect<Capabilities, Error, Service | Plugin.Service | never>;
+}>;
+
+type NormalizeReturn<R> = R extends readonly (infer A)[]
+  ? A[]
+  : R extends (infer A)[]
+    ? A[]
+    : R extends Any
+      ? [R]
+      : Any[];
+
+export type LazyCapability<Props = void, Capabilities extends ModuleReturn = ModuleReturn, E extends Error = Error> = (
+  props?: Props,
+) => Effect.Effect<NormalizeReturn<Capabilities>, E, Service | Plugin.Service | never>;
+
+/**
+ * Helper to define a lazily loaded implementation of a capability.
+ * Supports single capabilities, arrays, and tuples of different capability types.
+ * @param name The export name (e.g., 'AppGraphBuilder') - used to auto-compute module IDs.
+ * @param loader The lazy loader function.
+ * @returns A lazy capability function with ModuleTag symbol attached.
+ */
+export const lazy = <T = void, R extends ModuleReturn = ModuleReturn>(
+  name: string,
+  c: LoadCapability<T, R> | LoadCapabilities<T, R>,
+): LazyCapability<T, R> => {
+  const lazyFn: LazyCapability<T, R> = (props?: T) =>
+    Effect.gen(function* () {
+      const { default: getCapability } = yield* Effect.tryPromise(() => c());
+      const result = yield* getCapability(props);
+      const normalized = result == null ? [] : Array.isArray(result) ? Array.from(result) : [result];
+      return normalized as NormalizeReturn<R>;
+    });
+
+  return Object.assign(lazyFn, { [ModuleTag]: name });
+};
+
+/**
+ * Gets the module tag (export name) from a lazy capability function.
+ * @param capability The lazy capability function.
+ * @returns The module tag if present, undefined otherwise.
+ */
+// TODO(wittjosiah): Stricter type for capability.
+export const getModuleTag = (capability: unknown): string | undefined => {
+  return capability && typeof capability === 'function' && ModuleTag in capability
+    ? String(capability[ModuleTag])
+    : undefined;
+};
+
+/**
+ * Helper to define a capability module with explicit typing.
+ * Wraps the default export function to provide better type inference and make the pattern explicit.
+ *
+ * This helper provides explicit typing for the module activation function,
+ * making it clear that the function should:
+ * - Access CapabilityManager via the Effect layer system (Capability.get, Capability.getAll, etc.)
+ * - Return a capability, array of capabilities, or tuple of different capability types (sync or async)
+ *
+ * Supports returning multiple capabilities of different types as a tuple, which will be normalized
+ * to an array at runtime for compatibility with the plugin system.
+ *
+ * @example
+ * ```ts
+ * // Module without options - single capability
+ * export default Capability.makeModule(
+ *   Effect.fnUntraced(function* () {
+ *     const client = yield* Capability.get(ClientCapabilities.Client);
+ *     return contributes(Capabilities.SettingsStore, store);
+ *   })
+ * );
+ *
+ * // Module with multiple capabilities
+ * export default Capability.makeModule(
+ *   Effect.fnUntraced(function* () {
+ *     return [
+ *       contributes(Capabilities.SettingsStore, store),
+ *       contributes(Capabilities.Translations, translations),
+ *     ];
+ *   })
+ * );
+ *
+ * // Module with additional options (context accessed via layer)
+ * export default Capability.makeModule(
+ *   Effect.fnUntraced(function* ({ observability }: { observability?: boolean }) {
+ *     const invoker = yield* Capability.get(Capabilities.OperationInvoker);
+ *     return contributes(Capabilities.IntentResolver, ...);
+ *   })
+ * );
+ * ```
+ */
+export const makeModule = <
+  TProps = void,
+  TReturn extends ModuleReturn = ModuleReturn,
+  E extends Error = Error,
+  R extends Service | Plugin.Service | never = Service,
+>(
+  fn: (props?: TProps) => Effect.Effect<TReturn, E, R>,
+): ((props?: TProps) => Effect.Effect<TReturn, E, R>) => fn;

package/src/core/index.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './capabilities';
-export * from './events';
-export * from './manager';
-export * from './plugin';
+export * as ActivationEvent from './activation-event';
+export * as Capability from './capability';
+export * as CapabilityManager from './capability-manager';
+export * as Plugin from './plugin';
+export * as PluginManager from './plugin-manager';