@dxos/app-framework 0.7.4 → 0.7.5-labs.071a3e2

package/src/plugin-intent/errors.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Reconcile with @dxos/protocols. Factor out errors.
+
+/**
+ * NOTE: Messages should be sentences (Start with a capital letter and end with a period).
+ * Errors can optionally include a JSON context object.
+ */
+export class BaseError extends Error {
+  constructor(
+    readonly code: string,
+    message?: string,
+    readonly context?: Record<string, any>,
+  ) {
+    // TODO(dmaretskyi): Error.cause.
+    super(message ?? code, { cause: context });
+    this.name = code;
+    // NOTE: Restores prototype chain (https://stackoverflow.com/a/48342359).
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class NoResolversError extends BaseError {
+  constructor(action: string) {
+    super('NO_RESOLVERS', 'No resolvers were found for the action', { action });
+  }
+}
+
+export class CycleDetectedError extends BaseError {
+  constructor(context?: Record<string, any>) {
+    super(
+      'CYCLE_DETECTED',
+      'Intent execution limit exceeded. This is likely due to an infinite loop within intent resolvers.',
+      context,
+    );
+  }
+}

package/src/plugin-intent/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './actions';
+export * from './intent';
+export * from './intent-dispatcher';
+export * from './IntentPlugin';

package/src/plugin-intent/intent-dispatcher.test.ts

@@ -0,0 +1,299 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+import { Effect, Fiber, pipe } from 'effect';
+import { describe, expect, test } from 'vitest';
+
+import { chain, createIntent } from './intent';
+import { type AnyIntentResolver, createDispatcher, createResolver } from './intent-dispatcher';
+
+describe('Intent dispatcher', () => {
+  test('throws error if no resolver found', async () => {
+    const { dispatchPromise } = createDispatcher(() => []);
+    const { data, error } = await dispatchPromise(createIntent(ToString, { value: 1 }));
+
+    expect(data).toBe(undefined);
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  test('matches intent to resolver and executes', async () => {
+    const { dispatchPromise } = createDispatcher(() => [toStringResolver]);
+    const { data, error } = await dispatchPromise(createIntent(ToString, { value: 1 }));
+
+    expect(error).toBe(undefined);
+    expect(data?.string).toBe('1');
+  });
+
+  test('update resolvers', async () => {
+    const resolvers: AnyIntentResolver[] = [];
+    const { dispatchPromise } = createDispatcher(() => resolvers);
+    const { error } = await dispatchPromise(createIntent(ToString, { value: 1 }));
+
+    expect(error).toBeInstanceOf(Error);
+
+    resolvers.push(toStringResolver);
+
+    const { data } = await dispatchPromise(createIntent(ToString, { value: 1 }));
+
+    expect(data?.string).toBe('1');
+
+    resolvers.splice(resolvers.indexOf(toStringResolver), 1);
+
+    {
+      const { data, error } = await dispatchPromise(createIntent(ToString, { value: 1 }));
+
+      expect(data).toBe(undefined);
+      expect(error).toBeInstanceOf(Error);
+    }
+  });
+
+  test('compose intent effects', async () => {
+    const { dispatch } = createDispatcher(() => [computeResolver]);
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 1 }));
+      const b = yield* dispatch(createIntent(Compute, { value: 2 }));
+      return b.value - a.value;
+    });
+
+    expect(await Effect.runPromise(program)).toBe(2);
+  });
+
+  test('concurrent intent effects', async () => {
+    const { dispatch } = createDispatcher(() => [computeResolver]);
+    const program = Effect.gen(function* () {
+      const fiberA = yield* Effect.fork(dispatch(createIntent(Compute, { value: 5 })));
+      const fiberB = yield* Effect.fork(dispatch(createIntent(Compute, { value: 2 })));
+      const [a, b] = yield* Fiber.join(Fiber.zip(fiberA, fiberB));
+      return b.value - a.value;
+    });
+
+    expect(await Effect.runPromise(program)).toBe(-6);
+  });
+
+  test('mix & match intent effects with promises', async () => {
+    const { dispatch, dispatchPromise } = createDispatcher(() => [toStringResolver, computeResolver]);
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 2 }));
+      const b = yield* dispatch(createIntent(ToString, { value: a.value }));
+      return b.string;
+    });
+
+    expect(await Effect.runPromise(program)).toBe('4');
+
+    const a = await dispatchPromise(createIntent(Compute, { value: 2 }));
+    const b = await dispatchPromise(createIntent(ToString, { value: a.data!.value }));
+
+    expect(b.data?.string).toBe('4');
+  });
+
+  test('undo intent', async () => {
+    const { dispatch, undo } = createDispatcher(() => [computeResolver]);
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 2 }));
+
+      expect(a.value).toBe(4);
+
+      const b = yield* undo();
+
+      expect(b.value).toBe(2);
+    });
+
+    await Effect.runPromise(program);
+  });
+
+  test('chain intents', async () => {
+    const { dispatch } = createDispatcher(() => [computeResolver, toStringResolver, concatResolver]);
+    const intent = pipe(createIntent(Compute, { value: 1 }), chain(ToString, {}), chain(Concat, { plus: '!' }));
+
+    expect(intent.first.id).toBe(Compute._tag);
+    expect(intent.last.id).toBe(Concat._tag);
+    expect(intent.all.length).toBe(3);
+
+    const program = Effect.gen(function* () {
+      const data = yield* dispatch(intent);
+      return data.string;
+    });
+
+    expect(await Effect.runPromise(program)).toBe('2!');
+  });
+
+  test('undo chained intent', async () => {
+    const { dispatch, undo } = createDispatcher(() => [computeResolver, toStringResolver, concatResolver]);
+    const intent = pipe(createIntent(Compute, { value: 1 }), chain(Compute, {}), chain(Compute, {}));
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(intent);
+
+      expect(a.value).toBe(8);
+
+      const b = yield* undo();
+
+      expect(b.value).toBe(1);
+    });
+
+    await Effect.runPromise(program);
+  });
+
+  test('filter resolvers by plugin', async () => {
+    const otherComputeResolver = createResolver({
+      intent: Compute,
+      resolve: async (data) => ({ data: { value: data?.value * 3 } }),
+    });
+    const { dispatch } = createDispatcher((module) => (module === 'test' ? [computeResolver] : [otherComputeResolver]));
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 1 }));
+
+      expect(a.value).toBe(3);
+
+      const b = yield* dispatch(createIntent(Compute, { value: 1 }, { module: 'test' }));
+
+      expect(b.value).toBe(2);
+    });
+
+    await Effect.runPromise(program);
+  });
+
+  test('filter resolvers by predicate', async () => {
+    const conditionalComputeResolver = createResolver({
+      intent: Compute,
+      filter: (data): data is { value: number } => data?.value > 1,
+      resolve: async (data) => ({ data: { value: data?.value * 3 } }),
+    });
+    const { dispatch } = createDispatcher(() => [conditionalComputeResolver, computeResolver]);
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 1 }));
+
+      expect(a.value).toBe(2);
+
+      const b = yield* dispatch(createIntent(Compute, { value: 2 }));
+
+      expect(b.value).toBe(6);
+    });
+
+    await Effect.runPromise(program);
+  });
+
+  test('hoist resolvers', async () => {
+    const hoistedComputeResolver = createResolver({
+      intent: Compute,
+      position: 'hoist',
+      resolve: async (data) => ({ data: { value: data?.value * 3 } }),
+    });
+    const { dispatchPromise } = createDispatcher(() => [computeResolver, hoistedComputeResolver]);
+    const { data } = await dispatchPromise(createIntent(Compute, { value: 1 }));
+    expect(data?.value).toBe(3);
+  });
+
+  test('fallback resolvers', async () => {
+    const conditionalComputeResolver = createResolver({
+      intent: Compute,
+      filter: (data): data is { value: number } => data?.value === 1,
+      resolve: async (data) => ({ data: { value: data?.value * 2 } }),
+    });
+    const fallbackComputeResolver = createResolver({
+      intent: Compute,
+      position: 'fallback',
+      resolve: async (data) => ({ data: { value: data?.value * 3 } }),
+    });
+    const { dispatch } = createDispatcher(() => [conditionalComputeResolver, fallbackComputeResolver]);
+    const program = Effect.gen(function* () {
+      const a = yield* dispatch(createIntent(Compute, { value: 1 }));
+
+      expect(a.value).toBe(2);
+
+      const b = yield* dispatch(createIntent(Compute, { value: 2 }));
+
+      expect(b.value).toBe(6);
+    });
+
+    await Effect.runPromise(program);
+  });
+
+  test('non-struct inputs & outputs', async () => {
+    const { dispatchPromise } = createDispatcher(() => [addResolver]);
+    const { data } = await dispatchPromise(createIntent(Add, [1, 1]));
+    expect(data).toBe(2);
+  });
+
+  test('empty inputs & outputs', async () => {
+    const { dispatchPromise } = createDispatcher(() => [sideEffectResolver]);
+    const { data } = await dispatchPromise(createIntent(SideEffect));
+    expect(data).toBe(undefined);
+  });
+
+  test.todo('follow up intents');
+});
+
+class ToString extends S.TaggedClass<ToString>()('ToString', {
+  input: S.Struct({
+    value: S.Number,
+  }),
+  output: S.Struct({
+    string: S.String,
+  }),
+}) {}
+
+const toStringResolver = createResolver({
+  intent: ToString,
+  resolve: async (data) => ({ data: { string: data.value.toString() } }),
+});
+
+class Compute extends S.TaggedClass<Compute>()('Compute', {
+  input: S.Struct({
+    value: S.Number,
+  }),
+  output: S.Struct({
+    value: S.Number,
+  }),
+}) {}
+
+const computeResolver = createResolver({
+  intent: Compute,
+  resolve: (data, undo) => {
+    return Effect.gen(function* () {
+      if (undo) {
+        return { data: { value: data.value / 2 } };
+      }
+
+      yield* Effect.sleep(data.value * 10);
+      const value = data.value * 2;
+      return { data: { value }, undoable: { message: 'test', data: { value } } };
+    });
+  },
+});
+
+class Concat extends S.TaggedClass<Concat>()('Concat', {
+  input: S.Struct({
+    string: S.String,
+    plus: S.String,
+  }),
+  output: S.Struct({
+    string: S.String,
+  }),
+}) {}
+
+const concatResolver = createResolver({
+  intent: Concat,
+  resolve: async (data) => ({ data: { string: data.string + data.plus } }),
+});
+
+class Add extends S.TaggedClass<Add>()('Add', {
+  input: S.Tuple(S.Number, S.Number),
+  output: S.Number,
+}) {}
+
+const addResolver = createResolver({
+  intent: Add,
+  resolve: async (data) => ({ data: data[0] + data[1] }),
+});
+
+class SideEffect extends S.TaggedClass<SideEffect>()('SideEffect', {
+  input: S.Void,
+  output: S.Void,
+}) {}
+
+const sideEffectResolver = createResolver({
+  intent: SideEffect,
+  resolve: async () => {},
+});

package/src/plugin-intent/intent-dispatcher.ts

@@ -0,0 +1,304 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Effect, Option, pipe, Ref } from 'effect';
+import { type Simplify } from 'effect/Types';
+
+import { create } from '@dxos/live-object';
+import { byPosition, type MaybePromise, type Position, type GuardedType } from '@dxos/util';
+
+import { IntentAction } from './actions';
+import { CycleDetectedError, NoResolversError } from './errors';
+import {
+  createIntent,
+  type AnyIntent,
+  type AnyIntentChain,
+  type Intent,
+  type IntentChain,
+  type IntentData,
+  type IntentParams,
+  type IntentResultData,
+  type IntentSchema,
+  type Label,
+} from './intent';
+import { Events, Capabilities } from '../common';
+import { contributes, type PluginsContext } from '../core';
+
+const EXECUTION_LIMIT = 100;
+const HISTORY_LIMIT = 100;
+
+/**
+ * The return value of an intent effect.
+ */
+export type IntentEffectResult<Input, Output> = {
+  /**
+   * The output of the action that was performed.
+   *
+   * If the intent is apart of a chain of intents, the data will be passed to the next intent.
+   */
+  data?: Output;
+
+  /**
+   * If provided, the action will be undoable.
+   */
+  undoable?: {
+    /**
+     * Message to display to the user when indicating that the action can be undone.
+     */
+    message: Label;
+
+    /**
+     * Will be merged with the original intent data when firing the undo intent.
+     */
+    data?: Partial<Input>;
+  };
+
+  /**
+   * An error that occurred while performing the action.
+   *
+   * If the intent is apart of a chain of intents and an error occurs, the chain will be aborted.
+   *
+   * Return caught error instead of throwing to trigger other intent to be triggered prior to returning the error.
+   */
+  error?: Error;
+
+  /**
+   * Other intent chains to be triggered.
+   */
+  intents?: AnyIntentChain[];
+};
+
+export type AnyIntentEffectResult = IntentEffectResult<any, any>;
+
+/**
+ * The result of an intent dispatcher.
+ */
+export type IntentDispatcherResult<Input, Output> = Pick<IntentEffectResult<Input, Output>, 'data' | 'error'>;
+
+/**
+ * The implementation of an intent effect.
+ */
+export type IntentEffectDefinition<Input, Output> = (
+  data: Input,
+  undo: boolean,
+) => MaybePromise<IntentEffectResult<Input, Output> | void> | Effect.Effect<IntentEffectResult<Input, Output> | void>;
+
+/**
+ * Intent resolver to match intents to their effects.
+ */
+export type IntentResolver<Tag extends string, Fields extends IntentParams, Data = IntentData<Fields>> = Readonly<{
+  intent: IntentSchema<Tag, Fields>;
+  position?: Position;
+  filter?: (data: IntentData<Fields>) => data is Data;
+  resolve: IntentEffectDefinition<GuardedType<IntentResolver<Tag, Fields, Data>['filter']>, IntentResultData<Fields>>;
+}>;
+
+export type AnyIntentResolver = IntentResolver<any, any, any>;
+
+/**
+ * Creates an intent resolver to match intents to their effects.
+ * @param schema Schema of the intent. Must be a tagged class with input and output schemas.
+ * @param effect Effect to be performed when the intent is resolved.
+ * @param params.disposition Determines the priority of the resolver when multiple are resolved.
+ * @param params.filter Optional filter to determine if the resolver should be used.
+ */
+export const createResolver = <Tag extends string, Fields extends IntentParams, Data = IntentData<Fields>>(
+  resolver: IntentResolver<Tag, Fields, Data>,
+) => resolver;
+
+/**
+ * Invokes intents and returns the result.
+ */
+export type PromiseIntentDispatcher = <Fields extends IntentParams>(
+  intent: IntentChain<any, any, any, Fields>,
+) => Promise<Simplify<IntentDispatcherResult<IntentData<Fields>, IntentResultData<Fields>>>>;
+
+/**
+ * Creates an effect for intents.
+ */
+export type IntentDispatcher = <Fields extends IntentParams>(
+  intent: IntentChain<any, any, any, Fields>,
+  depth?: number,
+) => Effect.Effect<
+  Simplify<Required<IntentDispatcherResult<IntentData<Fields>, IntentResultData<Fields>>>['data']>,
+  Error
+>;
+
+type IntentResult<Tag extends string, Fields extends IntentParams> = IntentEffectResult<
+  IntentData<Fields>,
+  IntentResultData<Fields>
+> & {
+  _intent: Intent<Tag, Fields>;
+};
+
+export type AnyIntentResult = IntentResult<any, any>;
+
+/**
+ * Invokes the most recent undoable intent with undo flags.
+ */
+export type PromiseIntentUndo = () => Promise<IntentDispatcherResult<any, any>>;
+
+/**
+ * Creates an effect which undoes the last intent.
+ */
+export type IntentUndo = () => Effect.Effect<any, Error>;
+
+/**
+ * Check if a chain of results is undoable.
+ */
+const isUndoable = (historyEntry: AnyIntentResult[]): boolean =>
+  historyEntry.length > 0 && historyEntry.every(({ undoable }) => !!undoable);
+
+export type IntentContext = {
+  dispatch: IntentDispatcher;
+  dispatchPromise: PromiseIntentDispatcher;
+  undo: IntentUndo;
+  undoPromise: PromiseIntentUndo;
+};
+
+/**
+ * Sets of an intent dispatcher.
+ *
+ * @param getResolvers A function that returns an array of available intent resolvers.
+ * @param params.historyLimit The maximum number of intent results to keep in history.
+ * @param params.executionLimit The maximum recursion depth of intent chains.
+ */
+export const createDispatcher = (
+  getResolvers: (module?: string) => AnyIntentResolver[],
+  { executionLimit = EXECUTION_LIMIT, historyLimit = HISTORY_LIMIT } = {},
+): IntentContext => {
+  const historyRef = Effect.runSync(Ref.make<AnyIntentResult[][]>([]));
+
+  const handleIntent = (intent: AnyIntent) =>
+    Effect.gen(function* () {
+      const candidates = getResolvers(intent.module)
+        .filter((r) => r.intent._tag === intent.id)
+        .filter((r) => !r.filter || r.filter(intent.data))
+        .toSorted(byPosition);
+      if (candidates.length === 0) {
+        yield* Effect.fail(new NoResolversError(intent.id));
+      }
+
+      const effect = candidates[0].resolve(intent.data, intent.undo ?? false);
+      const result = Effect.isEffect(effect) ? yield* effect : yield* Effect.promise(async () => effect);
+      return { _intent: intent, ...result } as AnyIntentResult;
+    });
+
+  const dispatch: IntentDispatcher = (intentChain, depth = 0) => {
+    return Effect.gen(function* () {
+      if (depth > executionLimit) {
+        yield* Effect.fail(new CycleDetectedError());
+      }
+
+      const resultsRef = yield* Ref.make<AnyIntentResult[]>([]);
+      for (const intent of intentChain.all) {
+        const { data: prev } = (yield* resultsRef.get)[0] ?? {};
+        const result = yield* handleIntent({ ...intent, data: { ...intent.data, ...prev } });
+        yield* Ref.update(resultsRef, (results) => [result, ...results]);
+        if (result.intents) {
+          for (const intent of result.intents) {
+            // Returned intents are dispatched but not yielded into results,
+            // as such they cannot be undone.
+            // TODO(wittjosiah): Use higher execution concurrency?
+            yield* dispatch(intent, depth + 1);
+          }
+        }
+        if (result.error) {
+          yield* Effect.fail(result.error);
+        }
+      }
+
+      const results = yield* resultsRef.get;
+      const result = results[0];
+      yield* Ref.update(historyRef, (history) => {
+        const next = [...history, results];
+        if (next.length > historyLimit) {
+          next.splice(0, next.length - historyLimit);
+        }
+        return next;
+      });
+
+      if (result.undoable && isUndoable(results)) {
+        // TODO(wittjosiah): Is there a better way to handle showing undo for chains?
+        yield* pipe(
+          dispatch(createIntent(IntentAction.ShowUndo, { message: result.undoable.message })),
+          Effect.catchSome((err) =>
+            err instanceof NoResolversError ? Option.some(Effect.succeed(undefined)) : Option.none(),
+          ),
+        );
+      }
+
+      return result.data;
+    });
+  };
+
+  const dispatchPromise: PromiseIntentDispatcher = (intentChain) => {
+    return Effect.runPromise(dispatch(intentChain))
+      .then((data) => ({ data }))
+      .catch((error) => ({ error }));
+  };
+
+  const undo: IntentUndo = () => {
+    return Effect.gen(function* () {
+      const history = yield* historyRef.get;
+      const last = history.findLastIndex(isUndoable);
+      const result = last !== -1 ? history[last] : undefined;
+      if (result) {
+        const all = result.map(({ _intent, undoable }): AnyIntent => {
+          const data = _intent.data;
+          const undoData = undoable?.data ?? {};
+          return { ..._intent, data: { ...data, ...undoData }, undo: true } satisfies AnyIntent;
+        });
+        const intent = { first: all[0], last: all.at(-1)!, all } satisfies AnyIntentChain;
+        yield* Ref.update(historyRef, (h) => h.filter((_, index) => index !== last));
+        return yield* dispatch(intent);
+      }
+    });
+  };
+
+  const undoPromise: PromiseIntentUndo = () => {
+    return Effect.runPromise(undo())
+      .then((data) => ({ data }))
+      .catch((error) => ({ error }));
+  };
+
+  return { dispatch, dispatchPromise, undo, undoPromise };
+};
+
+const defaultEffect = () => Effect.fail(new Error('Intent runtime not ready'));
+const defaultPromise = () => Effect.runPromise(defaultEffect());
+
+export default (context: PluginsContext) => {
+  const state = create<IntentContext>({
+    dispatch: defaultEffect,
+    dispatchPromise: defaultPromise,
+    undo: defaultEffect,
+    undoPromise: defaultPromise,
+  });
+
+  // TODO(wittjosiah): Make getResolver callback async and allow resolvers to be requested on demand.
+  const { dispatch, dispatchPromise, undo, undoPromise } = createDispatcher((module) =>
+    context
+      .requestCapabilities(Capabilities.IntentResolver, (c, moduleId): c is AnyIntentResolver => {
+        return module ? moduleId === module : true;
+      })
+      .flat(),
+  );
+
+  const manager = context.requestCapability(Capabilities.PluginManager);
+  state.dispatch = (intentChain, depth) => {
+    return Effect.gen(function* () {
+      yield* manager._activate(Events.SetupIntents);
+      return yield* dispatch(intentChain, depth);
+    });
+  };
+  state.dispatchPromise = async (intentChain) => {
+    await manager.activate(Events.SetupIntents);
+    return await dispatchPromise(intentChain);
+  };
+  state.undo = undo;
+  state.undoPromise = undoPromise;
+
+  return contributes(Capabilities.IntentDispatcher, state);
+};