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

package/src/plugin-operation/history/history-tracker.test.ts

@@ -0,0 +1,380 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as TestClock from 'effect/TestClock';
+import { describe, expect } from 'vitest';
+
+import { OperationInvoker, OperationResolver } from '@dxos/operation';
+
+import { UndoOperation } from '../../common';
+import {
+  Compute,
+  HalveCompute,
+  ToString,
+  computeHandler,
+  createEventCollector,
+  halveComputeHandler,
+  toStringHandler,
+  waitUntil,
+} from '../testing';
+
+import * as HistoryTracker from './history-tracker';
+import * as UndoMapping from './undo-mapping';
+import * as UndoRegistry from './undo-registry';
+
+describe('HistoryTracker', () => {
+  it.effect('tracks undoable operations', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Fork compute operation and advance clock.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      expect(tracker.canUndo()).toBe(true);
+    }),
+  );
+
+  it.effect('does not track operations without undo mapping', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([toStringHandler]));
+      const undoRegistry = UndoRegistry.make(() => []);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      yield* invoker.invoke(ToString, { value: 42 });
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Without an undo mapping, canUndo should remain false.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo invokes inverse operation', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      let halveWasCalled = false;
+      const trackingHalveHandler = OperationResolver.make({
+        operation: HalveCompute,
+        handler: (data) => {
+          halveWasCalled = true;
+          return Effect.succeed({ value: data.value / 2 });
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      // Fork compute operation: 2 * 2 = 4.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+      expect(tracker.canUndo()).toBe(true);
+
+      // Undo should invoke halve with { value: 4 }.
+      yield* tracker.undo();
+      expect(halveWasCalled).toBe(true);
+      expect(tracker.canUndo()).toBe(false);
+    }),
+  );
+
+  it.effect('undo uses _invokeCore to skip event emission', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute operation (should emit event).
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      yield* collector.waitForEvents(1);
+      expect(collector.events.length).toBe(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // Undo (should NOT emit event because it uses _invokeCore).
+      yield* tracker.undo();
+
+      // Verify no new events were emitted.
+      expect(collector.events.length).toBe(1);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('multiple undos work in LIFO order', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const halveInputs: number[] = [];
+      const trackingHalveHandler = OperationResolver.make({
+        operation: HalveCompute,
+        handler: (data) => {
+          halveInputs.push(data.value);
+          return Effect.succeed({ value: data.value / 2 });
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute with 2 → 4.
+      const fiber1 = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber1);
+
+      // Fork compute with 3 → 6.
+      const fiber2 = yield* Effect.fork(invoker.invoke(Compute, { value: 3 }));
+      yield* TestClock.adjust('30 millis');
+      yield* Fiber.join(fiber2);
+
+      // Wait for both events to be collected.
+      yield* collector.waitForEvents(2);
+
+      // First undo should halve 6 (the output of the second compute).
+      yield* tracker.undo();
+      expect(halveInputs[0]).toBe(6);
+
+      // Second undo should halve 4 (the output of the first compute).
+      yield* tracker.undo();
+      expect(halveInputs[1]).toBe(4);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo on empty history returns error', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([]));
+      const undoRegistry = UndoRegistry.make(() => []);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      const result = yield* tracker.undo().pipe(Effect.either);
+      expect(result._tag).toBe('Left');
+      if (result._tag === 'Left') {
+        expect(result.left.message).toContain('empty');
+      }
+    }),
+  );
+
+  it.effect('fires ShowUndo operation when undoable operation is tracked', () =>
+    Effect.gen(function* () {
+      const testMessage: [string, { ns: string }] = ['test undo message', { ns: 'test' }];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: testMessage,
+      });
+
+      let showUndoWasCalled = false;
+      let showUndoMessage: unknown = undefined;
+      const showUndoHandler = OperationResolver.make({
+        operation: UndoOperation.ShowUndo,
+        handler: (input) => {
+          showUndoWasCalled = true;
+          showUndoMessage = input.message;
+          return Effect.succeed(undefined);
+        },
+      });
+
+      const invoker = OperationInvoker.make(() =>
+        Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
+      );
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(showUndoWasCalled).toBe(false);
+
+      // Fork compute operation and advance clock.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // ShowUndo should have been called with the message from the undo mapping.
+      yield* waitUntil(() => showUndoWasCalled);
+      expect(showUndoWasCalled).toBe(true);
+      expect(showUndoMessage).toEqual(testMessage);
+    }),
+  );
+
+  it.effect('ShowUndo message can be derived from input and output', () =>
+    Effect.gen(function* () {
+      // Dynamic message that depends on input/output.
+      const dynamicMessage = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
+        `computed ${input.value} to ${output.value}`,
+        { ns: 'test' },
+      ];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: dynamicMessage,
+      });
+
+      let showUndoWasCalled = false;
+      let showUndoMessage: unknown = undefined;
+      const showUndoHandler = OperationResolver.make({
+        operation: UndoOperation.ShowUndo,
+        handler: (input) => {
+          showUndoWasCalled = true;
+          showUndoMessage = input.message;
+          return Effect.succeed(undefined);
+        },
+      });
+
+      const invoker = OperationInvoker.make(() =>
+        Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
+      );
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(showUndoWasCalled).toBe(false);
+
+      // Fork compute operation and advance clock (same as passing test).
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // ShowUndo should have been called with the derived message.
+      yield* waitUntil(() => showUndoWasCalled);
+      expect(showUndoWasCalled).toBe(true);
+      // Compute 2 * 2 = 4, so message should be 'computed 2 to 4'.
+      expect(showUndoMessage).toEqual(['computed 2 to 4', { ns: 'test' }]);
+    }),
+  );
+
+  it.effect('does not track operations when deriveContext returns undefined', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 2 * 2 = 4, which is < 10, so deriveContext returns undefined.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Even though there's an undo mapping, deriveContext returned undefined,
+      // so this operation should not be tracked as undoable.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('tracks operations when deriveContext returns a value', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]));
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 5 * 2 = 10, which is >= 10, so deriveContext returns a value.
+      // Handler sleeps for value * 10 = 50ms.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 5 }));
+      yield* TestClock.adjust('50 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // This operation should be tracked as undoable.
+      expect(tracker.canUndo()).toBe(true);
+
+      yield* collector.dispose;
+    }),
+  );
+});

package/src/plugin-operation/history/history-tracker.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { type OperationInvoker } from '@dxos/operation';
+
+import { UndoOperation } from '../../common';
+
+import { EmptyHistoryError } from './errors';
+import type { HistoryEntry } from './types';
+import { resolveMessage } from './undo-mapping';
+import type { UndoRegistry } from './undo-registry';
+
+const HISTORY_LIMIT = 100;
+
+//
+// Public Interface
+//
+
+/**
+ * HistoryTracker interface - tracks operation history and provides undo.
+ */
+export interface HistoryTracker {
+  undo: () => Effect.Effect<void, Error>;
+  undoPromise: () => Promise<{ error?: Error }>;
+  canUndo: () => boolean;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates a HistoryTracker that subscribes to invocation events and provides undo.
+ */
+export const make = (
+  invoker: OperationInvoker.OperationInvokerInternal,
+  undoRegistry: UndoRegistry,
+): HistoryTracker => {
+  const history: HistoryEntry[] = [];
+
+  // Subscribe to invocation stream.
+  const handleInvocation = (event: OperationInvoker.InvocationEvent) => {
+    const mapping = undoRegistry.lookup(event.operation);
+    if (!mapping) {
+      // Operation is not undoable, skip.
+      return;
+    }
+
+    const inverseInput = mapping.deriveContext(event.input, event.output);
+    if (inverseInput === undefined) {
+      // Operation is conditionally not undoable (deriveContext returned undefined).
+      log('operation not undoable', { key: event.operation.meta.key });
+      return;
+    }
+
+    const entry: HistoryEntry = {
+      operation: event.operation,
+      input: event.input,
+      output: event.output,
+      inverse: mapping.inverse,
+      inverseInput,
+      timestamp: event.timestamp,
+    };
+
+    history.push(entry);
+    log('history entry added', { key: event.operation.meta.key, historyLength: history.length });
+
+    // Trim history if it exceeds limit.
+    if (history.length > HISTORY_LIMIT) {
+      history.splice(0, history.length - HISTORY_LIMIT);
+    }
+
+    // Show undo toast (resolve message if it's a function).
+    const resolvedMessage = resolveMessage(mapping.message, event.input, event.output);
+    Effect.runFork(
+      invoker.invoke(UndoOperation.ShowUndo, {
+        message: resolvedMessage,
+      }),
+    );
+  };
+
+  // Fork a fiber to consume the invocation stream.
+  Effect.runFork(
+    Stream.fromPubSub(invoker.invocations).pipe(
+      Stream.runForEach((event) => Effect.sync(() => handleInvocation(event))),
+    ),
+  );
+
+  const undo = (): Effect.Effect<void, Error> => {
+    return Effect.gen(function* () {
+      const entry = history.pop();
+      if (!entry) {
+        return yield* Effect.fail(new EmptyHistoryError());
+      }
+
+      log('undoing operation', { key: entry.operation.meta.key, inverseKey: entry.inverse.meta.key });
+
+      // Use _invokeCore to skip event emission (avoid undo-of-undo loops).
+      yield* invoker._invokeCore(entry.inverse, entry.inverseInput);
+
+      log('undo completed', { key: entry.operation.meta.key });
+    });
+  };
+
+  const undoPromise = async (): Promise<{ error?: Error }> => {
+    return runAndForwardErrors(undo())
+      .then(() => ({}))
+      .catch((error) => {
+        log.catch(error);
+        return { error };
+      });
+  };
+
+  const canUndo = (): boolean => {
+    return history.length > 0;
+  };
+
+  return {
+    undo,
+    undoPromise,
+    canUndo,
+  };
+};

package/src/plugin-operation/history/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './errors';
+export * from './types';
+export * as UndoMapping from './undo-mapping';
+export * as UndoRegistry from './undo-registry';
+export * as HistoryTracker from './history-tracker';

package/src/plugin-operation/history/types.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/operation';
+
+/**
+ * History entry stored by HistoryTracker.
+ */
+export type HistoryEntry = {
+  operation: Operation.Definition<any, any>;
+  input: any;
+  output: any;
+  inverse: Operation.Definition<any, any>;
+  inverseInput: any;
+  timestamp: number;
+};

package/src/plugin-operation/history/undo-mapping.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/operation';
+
+/**
+ * Label type for translatable text (canonical definition in @dxos/app-toolkit).
+ */
+type Label = string | [string, { ns: string; count?: number; defaultValue?: string }];
+
+/**
+ * Extract the input type from an OperationDefinition.
+ */
+export type InputOf<T> = T extends Operation.Definition<infer I, any> ? I : never;
+
+/**
+ * Extract the output type from an OperationDefinition.
+ */
+export type OutputOf<T> = T extends Operation.Definition<any, infer O> ? O : never;
+
+/**
+ * Message provider for undo toast.
+ * Can be a static Label or a function that derives the message from input/output.
+ */
+export type MessageProvider<Op extends Operation.Definition<any, any>> =
+  | Label
+  | ((input: InputOf<Op>, output: OutputOf<Op>) => Label);
+
+/**
+ * Undo mapping that links a forward operation to its inverse.
+ * Type parameters ensure deriveContext has correctly typed arguments.
+ *
+ * @template Op - The forward operation definition type.
+ * @template Inv - The inverse operation definition type.
+ */
+export interface UndoMapping<
+  Op extends Operation.Definition<any, any> = Operation.Definition<any, any>,
+  Inv extends Operation.Definition<any, any> = Operation.Definition<any, any>,
+> {
+  /** The forward operation. */
+  readonly operation: Op;
+
+  /** The inverse operation to invoke for undo. */
+  readonly inverse: Inv;
+
+  /**
+   * Derives the input for the inverse operation from the forward operation's input and output.
+   * @param input - The input that was passed to the forward operation.
+   * @param output - The output that was returned by the forward operation.
+   * @returns The input to pass to the inverse operation, or undefined to indicate the operation is not undoable.
+   */
+  readonly deriveContext: (input: InputOf<Op>, output: OutputOf<Op>) => InputOf<Inv> | undefined;
+
+  /**
+   * Optional message to show in the undo toast.
+   * Can be a static Label or a function that derives the message from input/output.
+   */
+  readonly message?: MessageProvider<Op>;
+}
+
+/**
+ * Props for creating an UndoMapping.
+ */
+export interface UndoMappingProps<
+  Op extends Operation.Definition<any, any>,
+  Inv extends Operation.Definition<any, any>,
+> {
+  /** The forward operation. */
+  operation: Op;
+
+  /** The inverse operation to invoke for undo. */
+  inverse: Inv;
+
+  /**
+   * Derives the input for the inverse operation from the forward operation's input and output.
+   * Return undefined to indicate the operation is not undoable.
+   */
+  deriveContext: (input: InputOf<Op>, output: OutputOf<Op>) => InputOf<Inv> | undefined;
+
+  /**
+   * Optional message to show in the undo toast.
+   * Can be a static Label or a function that derives the message from input/output.
+   */
+  message?: MessageProvider<Op>;
+}
+
+/**
+ * Creates a type-safe undo mapping.
+ *
+ * @example
+ * ```ts
+ * // Static message
+ * const mapping = UndoMapping.make({
+ *   operation: DeleteThread,
+ *   inverse: RestoreThread,
+ *   deriveContext: (input, output) => ({
+ *     thread: output.thread,
+ *     anchor: output.anchor,
+ *   }),
+ *   message: ['thread deleted label', { ns: '@dxos/plugin-thread' }],
+ * });
+ *
+ * // Dynamic message based on input/output
+ * const mapping = UndoMapping.make({
+ *   operation: RemoveObjects,
+ *   inverse: RestoreObjects,
+ *   deriveContext: (_input, output) => output,
+ *   message: (input, _output) =>
+ *     input.objects.length === 1
+ *       ? ['object deleted label', { ns: getTypename(input.objects[0]) }]
+ *       : ['objects deleted label', { ns: '@dxos/plugin-space' }],
+ * });
+ * ```
+ */
+export const make = <Op extends Operation.Definition<any, any>, Inv extends Operation.Definition<any, any>>(
+  props: UndoMappingProps<Op, Inv>,
+): UndoMapping<Op, Inv> => props;
+
+/**
+ * Resolves a message provider to a Label.
+ */
+export const resolveMessage = <Op extends Operation.Definition<any, any>>(
+  message: MessageProvider<Op> | undefined,
+  input: InputOf<Op>,
+  output: OutputOf<Op>,
+): Label | undefined => {
+  if (message === undefined) {
+    return undefined;
+  }
+  if (typeof message === 'function') {
+    return message(input, output);
+  }
+  return message;
+};