@dxos/app-framework 0.7.4 → 0.7.5-labs.5f04cf6

package/src/plugin-intent/actions.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+
+import { Label } from './intent';
+
+export const INTENT_PLUGIN = 'dxos.org/plugin/intent';
+export const INTENT_ACTION = `${INTENT_PLUGIN}/action`;
+
+export namespace IntentAction {
+  /**
+   * Fired after an intent is dispatched if the intent is undoable.
+   */
+  export class ShowUndo extends S.TaggedClass<ShowUndo>()(`${INTENT_ACTION}/show-undo`, {
+    input: S.Struct({
+      message: Label,
+    }),
+    output: S.Void,
+  }) {}
+}

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);
+    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,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './actions';
+export * from './intent';
+export * from './intent-dispatcher';
+export * from './IntentContext';
+export * from './IntentPlugin';

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

@@ -0,0 +1,280 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Effect, Fiber, pipe } from 'effect';
+import { describe, expect, test } from 'vitest';
+
+import { S } from '@dxos/echo-schema';
+
+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.action).toBe(Compute._tag);
+    expect(intent.last.action).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(Compute, 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(Compute, async (data) => ({ data: { value: data?.value * 3 } }), {
+      filter: (data): data is { value: number } => data?.value > 1,
+    });
+    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(Compute, async (data) => ({ data: { value: data?.value * 3 } }), {
+      disposition: 'hoist',
+    });
+    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(Compute, async (data) => ({ data: { value: data?.value * 2 } }), {
+      filter: (data): data is { value: number } => data?.value === 1,
+    });
+    const fallbackComputeResolver = createResolver(Compute, async (data) => ({ data: { value: data?.value * 3 } }), {
+      disposition: 'fallback',
+    });
+    const { dispatch } = createDispatcher(() => [fallbackComputeResolver, conditionalComputeResolver]);
+    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(ToString, async (data) => {
+  return { 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(Compute, (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(Concat, async (data) => {
+  return { 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(Add, async (data) => {
+  return { data: data[0] + data[1] };
+});
+
+class SideEffect extends S.TaggedClass<SideEffect>()('SideEffect', {
+  input: S.Void,
+  output: S.Void,
+}) {}
+
+const sideEffectResolver = createResolver(SideEffect, async () => {});

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

@@ -0,0 +1,269 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Effect, Option, pipe, Ref } from 'effect';
+import { type Simplify } from 'effect/Types';
+
+import { type MaybePromise, byDisposition, type Disposition } 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';
+
+const EXECUTION_LIMIT = 100;
+const HISTORY_LIMIT = 100;
+
+/**
+ * The return value of an intent effect.
+ */
+export type IntentEffectResult<Fields extends IntentParams> = {
+  /**
+   * 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?: IntentResultData<Fields>;
+
+  /**
+   * 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<IntentData<Fields>>;
+  };
+
+  /**
+   * 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>;
+
+/**
+ * The result of an intent dispatcher.
+ */
+export type IntentDispatcherResult<Fields extends IntentParams> = Pick<IntentEffectResult<Fields>, 'data' | 'error'>;
+
+/**
+ * The implementation of an intent effect.
+ */
+export type IntentEffectDefinition<Fields extends IntentParams> = (
+  data: IntentData<Fields>,
+  undo: boolean,
+) => MaybePromise<IntentEffectResult<Fields> | void> | Effect.Effect<IntentEffectResult<Fields> | void>;
+
+/**
+ * Intent resolver to match intents to their effects.
+ */
+export type IntentResolver<Tag extends string, Fields extends IntentParams> = Readonly<{
+  action: Tag;
+  disposition?: Disposition;
+  // TODO(wittjosiah): Would be nice to make this a guard for intents with optional data.
+  filter?: (data: IntentData<Fields>) => boolean;
+  effect: IntentEffectDefinition<Fields>;
+}>;
+
+export type AnyIntentResolver = IntentResolver<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>(
+  schema: IntentSchema<Tag, Fields>,
+  effect: IntentEffectDefinition<Fields>,
+  params: Pick<IntentResolver<Tag, Fields>, 'disposition' | 'filter'> = {},
+): IntentResolver<Tag, Fields> => ({
+  action: schema._tag,
+  effect,
+  ...params,
+});
+
+/**
+ * Invokes intents and returns the result.
+ */
+export type PromiseIntentDispatcher = <Fields extends IntentParams>(
+  intent: IntentChain<any, any, any, Fields>,
+) => Promise<Simplify<IntentDispatcherResult<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<Fields>>['data']>, Error>;
+
+type IntentResult<Tag extends string, Fields extends IntentParams> = IntentEffectResult<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>>;
+
+/**
+ * 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 resolvers 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) => {
+    return Effect.gen(function* () {
+      const candidates = getResolvers(intent.module)
+        .filter((r) => r.action === intent.action)
+        .filter((r) => !r.filter || r.filter(intent.data))
+        .toSorted(byDisposition);
+      if (candidates.length === 0) {
+        return {
+          _intent: intent,
+          error: new NoResolversError(intent.action),
+        } as AnyIntentResult;
+      }
+
+      const effect = candidates[0].effect(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 };
+};