@dxos/app-framework 0.7.4 → 0.7.5-main.937ce75

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

@@ -0,0 +1,285 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Effect, Ref } from 'effect';
+
+import { type MaybePromise, pick } from '@dxos/util';
+
+import {
+  createIntent,
+  IntentAction,
+  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.
+   */
+  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'>;
+
+/**
+ * Determines the priority of the effect when multiple intent resolvers are matched.
+ *
+ * - `static` - The effect is selected in the order it was resolved.
+ * - `hoist` - The effect is selected before `static` effects.
+ * - `fallback` - The effect is selected after `static` effects.
+ */
+export type IntentDisposition = 'static' | 'hoist' | 'fallback';
+
+/**
+ * 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> = {
+  action: Tag;
+  disposition?: IntentDisposition;
+  // 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<IntentDispatcherResult<Fields>>;
+
+/**
+ * Creates an effect for intents.
+ */
+export type IntentDispatcher = <Fields extends IntentParams>(
+  intent: IntentChain<any, any, any, Fields>,
+  depth?: number,
+) => Effect.Effect<IntentDispatcherResult<Fields>, Error>;
+
+type IntentResult<Tag extends string, Fields extends IntentParams> = IntentEffectResult<Fields> & {
+  _intent: Intent<Tag, Fields>;
+};
+
+type AnyIntentResult = IntentResult<any, any>;
+
+/**
+ * Invokes the most recent undoable intent with undo flags.
+ */
+export type PromiseIntentUndo = () => Promise<IntentDispatcherResult<any> | undefined>;
+
+/**
+ * Creates an effect which undoes the last intent.
+ */
+export type IntentUndo = () => Effect.Effect<IntentDispatcherResult<any> | undefined, 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;
+  registerResolver: (id: string, resolver: AnyIntentResolver) => () => void;
+};
+
+/**
+ * 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 = (
+  resolvers: Record<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 = Object.entries(resolvers)
+        .filter(([id, _]) => (intent.plugin ? id === intent.plugin : true))
+        .flatMap(([_, resolvers]) => resolvers)
+        .filter((r) => r.action === intent.action)
+        .filter((r) => !r.filter || r.filter(intent.data))
+        .toSorted(({ disposition: a = 'static' }, { disposition: b = 'static' }) => {
+          return a === b ? 0 : a === 'hoist' || b === 'fallback' ? -1 : b === 'hoist' || a === 'fallback' ? 1 : 0;
+        });
+      if (candidates.length === 0) {
+        return {
+          _intent: intent,
+          error: new Error(`No resolver found for action: ${intent.action}`),
+        } satisfies 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 } satisfies AnyIntentResult;
+    });
+  };
+
+  const dispatch: IntentDispatcher = (intentChain, depth = 0) => {
+    return Effect.gen(function* () {
+      if (depth > executionLimit) {
+        yield* Effect.fail(
+          new Error('Intent execution limit exceeded. This is likely due to an infinite loop within intent resolvers.'),
+        );
+      }
+
+      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.error) {
+          break;
+        }
+        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);
+          }
+        }
+      }
+
+      const results = yield* resultsRef.get;
+      const result = results[0];
+      if (result) {
+        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* dispatch(createIntent(IntentAction.ShowUndo, { message: result.undoable.message }));
+        }
+
+        return pick(result, ['data', 'error']);
+      } else {
+        return { data: {}, error: new Error('No results') };
+      }
+    });
+  };
+
+  const dispatchPromise: PromiseIntentDispatcher = (intentChain) => {
+    const program = dispatch(intentChain);
+    return Effect.runPromise(program);
+  };
+
+  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 = () => {
+    const program = undo();
+    return Effect.runPromise(program);
+  };
+
+  const registerResolver = (id: string, resolver: AnyIntentResolver) => {
+    resolvers[id] = [...(resolvers[id] ?? []), resolver];
+    return () => {
+      resolvers[id] = resolvers[id].filter((r) => r !== resolver);
+    };
+  };
+
+  return { dispatch, dispatchPromise, undo, undoPromise, registerResolver };
+};

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

@@ -2,100 +2,161 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { MaybePromise } from '@dxos/util';
+import { S } from '@dxos/echo-schema';
 
-import type { Plugin } from '../plugin-host';
+import { INTENT_PLUGIN } from './meta';
 
-/**
- * Type of data returned from an intent.
- */
-export type IntentData<T extends Record<string, any> = Record<string, any>> = T & {
-  /**
-   * The data from the result of the previous intent.
-   */
-  // TODO(burdon): Chainable types? (see Effect hooks).
-  result?: any;
+export type IntentParams = {
+  readonly input: S.Schema.All;
+  readonly output: S.Schema.All;
 };
 
+export type IntentData<Fields extends IntentParams> =
+  S.Schema.Type<S.Struct<Fields>> extends { readonly input: any } ? S.Schema.Type<S.Struct<Fields>>['input'] : any;
+
+export type IntentResultData<Fields extends IntentParams> =
+  S.Schema.Type<S.Struct<Fields>> extends { readonly output: any } ? S.Schema.Type<S.Struct<Fields>>['output'] : any;
+
+export type IntentSchema<Tag extends string, Fields extends IntentParams> = S.TaggedClass<any, Tag, Fields>;
+
 /**
  * An intent is an abstract description of an operation to be performed.
  * Intents allow actions to be performed across plugins.
  */
-export type Intent = {
-  /**
-   * Plugin ID.
-   * If specified, the intent will be sent explicitly to the plugin.
-   * Otherwise, the intent will be sent to all plugins, in order and the first to resolve a non-null value will be used.
-   */
-  plugin?: string;
+export type Intent<Tag extends string, Fields extends IntentParams> = {
+  _schema: IntentSchema<Tag, Fields>;
 
   /**
    * The action to perform.
    */
-  action: string;
-
-  /**
-   * Whether or not the intent is being undone.
-   */
-  undo?: boolean;
+  action: Tag;
 
   /**
    * Any data needed to perform the desired action.
    */
-  // TODO(burdon): Typed intents.
-  data?: IntentData;
-};
+  data: IntentData<Fields>;
 
-export type IntentResult = {
   /**
-   * 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.
+   * Plugin ID.
+   * If specified, the intent will be sent explicitly to the plugin.
+   * Otherwise, the intent will be sent to all plugins, in order and the first to resolve a non-null value will be used.
    */
-  data?: any;
+  plugin?: string;
 
   /**
-   * If provided, the action will be undoable.
+   * Whether or not the intent is being undone.
    */
-  undoable?: {
-    /**
-     * Message to display to the user when indicating that the action can be undone.
-     */
-    message: string;
-
-    /**
-     * Will be merged with the original intent data when firing the undo intent.
-     */
-    data?: IntentData;
-  };
+  undo?: boolean;
+};
 
-  /**
-   * 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.
-   */
-  error?: Error;
+export type AnyIntent = Intent<any, any>;
 
-  /**
-   * Other intent chains to be triggered.
-   */
-  intents?: Intent[][];
+/**
+ * Chain of intents to be executed together.
+ * The result of each intent is merged into the next intent's input data.
+ */
+export type IntentChain<
+  FirstTag extends string,
+  LastTag extends string,
+  FirstFields extends IntentParams,
+  LastFields extends IntentParams,
+> = {
+  first: Intent<FirstTag, FirstFields>;
+  last: Intent<LastTag, LastFields>;
+  all: AnyIntent[];
 };
 
+export type AnyIntentChain = IntentChain<any, any, any, any>;
+
 /**
- * Trigger one or more intents to be sent.
- * If multiple intents are specified, the result of each will be merged with the data to the next.
- *
- * @returns The result of the last intent.
+ * Creates a typed intent.
+ * @param schema Schema of the intent. Must be a tagged class with input and output schemas.
+ * @param data Data fulfilling the input schema of the intent.
+ * @param params.plugin Optional plugin ID to send the intent to.
+ * @param params.undo Optional flag to indicate that the intent is being undone. Generally not set manually.
  */
-// TODO(burdon): Generic/typed intents.
-export type IntentDispatcher = (intent: Intent | Intent[]) => Promise<IntentResult | void>;
+export const createIntent = <Tag extends string, Fields extends IntentParams>(
+  schema: IntentSchema<Tag, Fields>,
+  data: IntentData<Fields> = {},
+  params: Pick<AnyIntent, 'plugin' | 'undo'> = {},
+): IntentChain<Tag, Tag, Fields, Fields> => {
+  // The output of validateSync breaks proxy objects so this is just used for validation.
+  // TODO(wittjosiah): Is there a better way to make theses types align?
+  const _ = S.validateSync(schema.fields.input as S.Schema<any, any, unknown>)(data);
+  const intent = {
+    ...params,
+    _schema: schema,
+    action: schema._tag,
+    data,
+  } satisfies Intent<Tag, Fields>;
+
+  return {
+    first: intent,
+    last: intent,
+    all: [intent],
+  };
+};
+
+// TODO(wittjosiah): Add a function for mapping the output of one intent to the input of another.
 
 /**
- * Resolves an intent that was dispatched.
- * If the intent is not handled, nothing should be returned.
+ * Chain two intents together.
  *
- * @returns The result of the intent.
+ * NOTE: Chaining of intents depends on the data inputs and outputs being structs.
  */
-// TODO(burdon): All graph callback should use objects.
-export type IntentResolver = (intent: Intent, plugins: Plugin[]) => MaybePromise<IntentResult | void>;
+export const chain =
+  <
+    FirstTag extends string,
+    NextTag extends string,
+    FirstFields extends IntentParams,
+    LastFields extends IntentParams,
+    NextFields extends IntentParams,
+  >(
+    schema: IntentSchema<NextTag, NextFields>,
+    data: Omit<IntentData<NextFields>, keyof IntentResultData<LastFields>> = {},
+    params: Pick<AnyIntent, 'plugin' | 'undo'> = {},
+  ) =>
+  (
+    intent: IntentChain<FirstTag, any, FirstFields, LastFields>,
+  ): IntentChain<FirstTag, NextTag, FirstFields, NextFields> => {
+    const intents = 'all' in intent ? intent.all : [intent];
+    const first = intents[0];
+    const last = {
+      ...params,
+      _schema: schema,
+      action: schema._tag,
+      data,
+    } satisfies Intent<NextTag, NextFields>;
+
+    return {
+      first,
+      last,
+      all: [...intents, last],
+    };
+  };
+
+//
+// Intents
+//
+
+// NOTE: Should maintain compatibility with `i18next` (and @dxos/react-ui).
+// TODO(wittjosiah): Making this immutable breaks type compatibility.
+export const Label = S.Union(
+  S.String,
+  S.mutable(S.Tuple(S.String, S.mutable(S.Struct({ ns: S.String, count: S.optional(S.Number) })))),
+);
+export type Label = S.Schema.Type<typeof Label>;
+
+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/plugins/plugin-intent/meta.ts

@@ -2,8 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
+export const INTENT_PLUGIN = 'dxos.org/plugin/intent';
+
 const IntentMeta = {
-  id: 'dxos.org/plugin/intent',
+  id: INTENT_PLUGIN,
 };
 
 export default IntentMeta;

package/src/plugins/plugin-intent/provides.ts

@@ -2,13 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type IntentContext } from './IntentContext';
-import { type IntentResolver } from './intent';
-import { type Plugin } from '../plugin-host';
+import { type IntentContext, type AnyIntentResolver } from './intent-dispatcher';
+import { type HostContext, type Plugin } from '../plugin-host';
+
+type Context = HostContext & IntentContext;
+
+export type ResolverDefinitions = AnyIntentResolver | AnyIntentResolver[] | ResolverDefinitions[];
 
 export type IntentResolverProvides = {
   intent: {
-    resolver: IntentResolver;
+    resolvers: (context: Context) => ResolverDefinitions;
   };
 };
 
@@ -20,19 +23,4 @@ export const parseIntentPlugin = (plugin: Plugin) =>
   (plugin.provides as any).intent?.dispatch ? (plugin as Plugin<IntentPluginProvides>) : undefined;
 
 export const parseIntentResolverPlugin = (plugin: Plugin) =>
-  (plugin.provides as any).intent?.resolver ? (plugin as Plugin<IntentResolverProvides>) : undefined;
-
-//
-// Intents
-//
-
-const INTENT_PLUGIN = 'dxos.org/plugin/intent';
-
-const INTENT_ACTION = `${INTENT_PLUGIN}/action`;
-
-export enum IntentAction {
-  /**
-   * Fired after an intent is dispatched if the intent is undoable.
-   */
-  SHOW_UNDO = `${INTENT_ACTION}/show-undo`,
-}
+  (plugin.provides as any).intent?.resolvers ? (plugin as Plugin<IntentResolverProvides>) : undefined;

package/src/plugins/plugin-settings/provides.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+import { S } from '@dxos/echo-schema';
 import { type SettingsStoreFactory, type SettingsValue } from '@dxos/local-storage';
 
 import { type Plugin } from '../plugin-host';
@@ -20,10 +21,14 @@ export const parseSettingsPlugin = (plugin: Plugin) => {
     : undefined;
 };
 
-const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
+export const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
+export const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
 
-const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
-
-export enum SettingsAction {
-  OPEN = `${SETTINGS_ACTION}/open`,
+export namespace SettingsAction {
+  export class Open extends S.TaggedClass<Open>()(`${SETTINGS_ACTION}/open`, {
+    input: S.Struct({
+      plugin: S.optional(S.String),
+    }),
+    output: S.Void,
+  }) {}
 }