@dxos/compute 0.8.4-main.fcfe5033a5 → 0.8.4-staging.60fe92afc8

package/src/OperationHandlerSet.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, Registry } from '@effect-atom/atom';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Operation from './Operation';
+import * as OperationHandlerSet from './OperationHandlerSet';
+
+const KEY_A = DXN.make('org.example.test.a');
+const KEY_B = DXN.make('org.example.test.b');
+
+const makeHandler = (key: DXN.DXN, output: string) =>
+  Operation.withHandler(Operation.make({ input: Schema.Void, output: Schema.String, meta: { key } }), () =>
+    Effect.succeed(output),
+  );
+
+describe('OperationHandlerSet.reactive', () => {
+  test('merges handlers from contributed sets', async ({ expect }) => {
+    const registry = Registry.make();
+    const setA = OperationHandlerSet.make(makeHandler(KEY_A, 'A'));
+    const setB = OperationHandlerSet.make(makeHandler(KEY_B, 'B'));
+    const atom = Atom.make<readonly OperationHandlerSet.OperationHandlerSet[]>([setA, setB]).pipe(Atom.keepAlive);
+    registry.mount(atom);
+
+    const reactive = OperationHandlerSet.reactive(registry, atom);
+    const handlers = await reactive.getHandlers();
+    expect(handlers.map((handler) => handler.meta.key).sort()).toEqual([KEY_A, KEY_B]);
+  });
+
+  test('caches the merged result across calls', async ({ expect }) => {
+    const registry = Registry.make();
+    let resolveCount = 0;
+    const trackingSet: OperationHandlerSet.OperationHandlerSet = {
+      [OperationHandlerSet.TypeId]: OperationHandlerSet.TypeId,
+      getHandlers: () => Promise.resolve([makeHandler(KEY_A, 'A')]),
+      handlers: Effect.sync(() => {
+        resolveCount++;
+        return [makeHandler(KEY_A, 'A')];
+      }),
+    };
+    const atom = Atom.make<readonly OperationHandlerSet.OperationHandlerSet[]>([trackingSet]).pipe(Atom.keepAlive);
+    registry.mount(atom);
+
+    const reactive = OperationHandlerSet.reactive(registry, atom);
+    await reactive.getHandlers();
+    await reactive.getHandlers();
+    await reactive.getHandlers();
+    expect(resolveCount).toBe(1);
+  });
+
+  test('retries after a rejection rather than caching the failure', async ({ expect }) => {
+    const registry = Registry.make();
+    let callCount = 0;
+    const flakySet: OperationHandlerSet.OperationHandlerSet = {
+      [OperationHandlerSet.TypeId]: OperationHandlerSet.TypeId,
+      getHandlers: () => Promise.resolve([]),
+      handlers: Effect.suspend(() => {
+        callCount++;
+        if (callCount === 1) {
+          return Effect.promise(() => Promise.reject(new Error('transient')));
+        }
+        return Effect.succeed([makeHandler(KEY_A, 'A')]);
+      }),
+    };
+    const atom = Atom.make<readonly OperationHandlerSet.OperationHandlerSet[]>([flakySet]).pipe(Atom.keepAlive);
+    registry.mount(atom);
+
+    const reactive = OperationHandlerSet.reactive(registry, atom);
+    await expect(reactive.getHandlers()).rejects.toThrow('transient');
+    const retried = await reactive.getHandlers();
+    expect(retried.map((handler) => handler.meta.key)).toEqual([KEY_A]);
+    expect(callCount).toBe(2);
+  });
+
+  test('invalidates and re-resolves when the atom changes', async ({ expect }) => {
+    const registry = Registry.make();
+    const setA = OperationHandlerSet.make(makeHandler(KEY_A, 'A'));
+    const setB = OperationHandlerSet.make(makeHandler(KEY_B, 'B'));
+    const atom = Atom.make<readonly OperationHandlerSet.OperationHandlerSet[]>([setA]).pipe(Atom.keepAlive);
+    registry.mount(atom);
+
+    const reactive = OperationHandlerSet.reactive(registry, atom);
+    expect((await reactive.getHandlers()).map((handler) => handler.meta.key)).toEqual([KEY_A]);
+
+    registry.set(atom, [setA, setB]);
+    expect((await reactive.getHandlers()).map((handler) => handler.meta.key).sort()).toEqual([KEY_A, KEY_B]);
+
+    registry.set(atom, []);
+    expect(await reactive.getHandlers()).toEqual([]);
+  });
+});

package/src/OperationHandlerSet.ts

@@ -0,0 +1,181 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom, type Registry } from '@effect-atom/atom';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
+
+import { EffectEx } from '@dxos/effect';
+import { assertArgument } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { NoHandlerError } from './errors';
+import type * as Operation from './Operation';
+
+export const TypeId = '~@dxos/operation/OperationHandlerSet' as const;
+export type TypeId = typeof TypeId;
+
+export interface OperationHandlerSet {
+  [TypeId]: TypeId;
+
+  readonly handlers: Effect.Effect<Operation.WithHandler<Operation.Definition.Any>[]>;
+
+  getHandlers(): Promise<Operation.WithHandler<Operation.Definition.Any>[]>;
+}
+
+export const isOperationHandlerSet = (value: unknown): value is OperationHandlerSet => {
+  return typeof value === 'object' && value !== null && TypeId in value;
+};
+
+export const empty: OperationHandlerSet = {
+  [TypeId]: TypeId,
+  handlers: Effect.succeed([]),
+  getHandlers: () => Promise.resolve([]),
+};
+
+/**
+ * Creates a new operation handler set from a list of handlers.
+ *
+ * @example
+ * ```ts
+ * const set = OperationHandlerSet.make(
+ *   Operation.withHandler(Operation.make({ input: Schema.Void, output: Schema.Void }), (input) => Effect.succeed({})),
+ *   Operation.withHandler(Operation.make({ input: Schema.Void, output: Schema.Void }), (input) => Effect.succeed({})),
+ * );
+ * ```
+ */
+export const make = (...handlers: Operation.WithHandler<Operation.Definition.Any>[]): OperationHandlerSet => {
+  return async(() => Promise.resolve(handlers));
+};
+
+export const async = (
+  getHandlers: () => Promise<Operation.WithHandler<Operation.Definition.Any>[]>,
+): OperationHandlerSet => {
+  // NOTE: Re-runing async module imports has a big performance penalty in Chrome.
+  let promise: Promise<Operation.WithHandler<Operation.Definition.Any>[]> | null = null;
+  const getHandlersCached = () => {
+    if (!promise) {
+      promise = getHandlers();
+    }
+    return promise;
+  };
+  return {
+    [TypeId]: TypeId,
+    getHandlers,
+    handlers: Effect.promise(getHandlersCached),
+  };
+};
+
+/**
+ * Builds a set backed by an atom of contributed sets. The merged result is
+ * cached and invalidated whenever the atom changes, so most accesses are
+ * cheap but newly registered handlers are picked up.
+ */
+export const reactive = (
+  registry: Registry.Registry,
+  atom: Atom.Atom<readonly OperationHandlerSet[]>,
+): OperationHandlerSet => {
+  let cached: Promise<Operation.WithHandler<Operation.Definition.Any>[]> | null = null;
+  registry.subscribe(atom, () => {
+    cached = null;
+  });
+  // `suspend` defers `registry.get(atom)` until each run, so re-evaluations
+  // after cache invalidation see the current contributed sets.
+  const compute = Effect.suspend(() =>
+    pipe(
+      registry.get(atom),
+      Effect.forEach((set) => set.handlers, { concurrency: 'unbounded' }),
+      Effect.map((groups) => groups.flat()),
+      // Reset cached on failure so a transient error doesn't permanently
+      // poison subsequent calls.
+      Effect.tapErrorCause(() =>
+        Effect.sync(() => {
+          cached = null;
+        }),
+      ),
+    ),
+  );
+  const getHandlers = () => (cached ??= EffectEx.runAndForwardErrors(compute));
+  return {
+    [TypeId]: TypeId,
+    getHandlers,
+    handlers: Effect.promise(getHandlers),
+  };
+};
+
+/**
+ * Merges multiple operation handler sets into a single set.
+ *
+ */
+export const merge = (...sets: OperationHandlerSet[]): OperationHandlerSet => {
+  assertArgument(sets.every(isOperationHandlerSet), 'sets', 'sets must be an array of OperationHandlerSet');
+  return async(() => Promise.all(sets.map((set) => set.getHandlers())).then((handlers) => handlers.flat()));
+};
+
+/**
+ * Creates a new operation handler set from a list of lazy-loaded modules.
+ *
+ * @example
+ * ```ts
+ * const set = OperationHandlerSet.lazy(
+ *   () => import('./my-handler'),
+ *   () => import('./my-other-handler'),
+ * );
+ * ```
+ */
+export const lazy = (
+  ...modules: (() => Promise<{ default: Operation.WithHandler<Operation.Definition.Any> }>)[]
+): OperationHandlerSet => {
+  return async(() => Promise.all(modules.map((module) => module().then(({ default: handler }) => handler))));
+};
+
+/**
+ * Gets a handler for an operation by definition.
+ */
+export const getHandler = <const Op extends Operation.Definition.Any>(
+  set: OperationHandlerSet,
+  definition: Op,
+): Effect.Effect<Operation.WithHandler<Op>, NoHandlerError> =>
+  Effect.gen(function* () {
+    const handlers = yield* set.handlers;
+    const handler = handlers.find((handler) => handler.meta.key === definition.meta.key);
+    if (!handler) {
+      return yield* Effect.fail(new NoHandlerError(definition.meta.key));
+    }
+    return handler as any;
+  });
+
+/**
+ * Gets a handler for an operation by key.
+ * Accepts either a plain NSID (`org.dxos.function.database.contextAdd`) or a
+ * full DXN string (`dxn:org.dxos.function.database.contextAdd`).
+ */
+export const getHandlerByKey = (
+  set: OperationHandlerSet,
+  key: string,
+): Effect.Effect<Operation.WithHandler<Operation.Definition.Any>, NoHandlerError> =>
+  Effect.gen(function* () {
+    const handlers = yield* set.handlers;
+    // Normalize both sides to plain NSID for comparison so callers can pass
+    // either a ToolId (plain NSID) or a full DXN string.
+    const normalizeKey = (k: string) => (DXN.isDXN(k) ? DXN.getName(k) : k);
+    const normalizedKey = normalizeKey(key);
+    const handler = handlers.find((handler) => normalizeKey(handler.meta.key) === normalizedKey);
+    if (!handler) {
+      return yield* Effect.fail(new NoHandlerError(key));
+    }
+    return handler as any;
+  });
+
+export class OperationHandlerProvider extends Context.Tag('@dxos/operation/OperationHandlerProvider')<
+  OperationHandlerProvider,
+  OperationHandlerSet
+>() {}
+
+export const provide = (handlers: OperationHandlerSet): Layer.Layer<OperationHandlerProvider, never, never> =>
+  Layer.succeed(OperationHandlerProvider, handlers);

package/src/OperationRegistry.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+
+import { Database, Filter, Query } from '@dxos/echo';
+
+import * as Operation from './Operation';
+import * as OperationHandlerSet from './OperationHandlerSet';
+
+export interface OperationRegistry {
+  /**
+   * Resolve an operation by key.
+   */
+  resolve(key: string): Effect.Effect<Option.Option<Operation.Definition.Any>>;
+}
+
+export class Service extends Context.Tag('@dxos/operation/OperationRegistry')<Service, OperationRegistry>() {}
+
+/**
+ * Resolve an operation by key.
+ */
+export const resolve: (key: string) => Effect.Effect<Option.Option<Operation.Definition.Any>, never, Service> =
+  Effect.serviceFunctionEffect(Service, (service) => service.resolve);
+
+export const layer: Layer.Layer<Service, never, Database.Service | OperationHandlerSet.OperationHandlerProvider> =
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const database = yield* Database.Service;
+      const handlerSet = yield* OperationHandlerSet.OperationHandlerProvider;
+      return {
+        resolve: (key: string) =>
+          Database.query(Query.select(Filter.and(Filter.type(Operation.PersistentOperation), Filter.key(key))))
+            .first.pipe(
+              Effect.flatten,
+              Effect.map(Operation.deserialize),
+              Effect.catchTag('NoSuchElementException', () => OperationHandlerSet.getHandlerByKey(handlerSet, key)),
+              Effect.option,
+            )
+            .pipe(Effect.provideService(Database.Service, database)),
+      };
+    }),
+  );