feat(packages/excalidraw): state tracking, api hook, and others (#10870)

packages/common/src/appEventBus.test.ts

@@ -0,0 +1,74 @@
+import { AppEventBus } from "./appEventBus";
+
+type TestEvents = {
+  initialize: [api: number];
+  pointerUp: [pointerId: string];
+  viewState: [zoom: number];
+};
+
+const behavior = {
+  initialize: { cardinality: "once", replay: "last" },
+  pointerUp: { cardinality: "many", replay: "none" },
+  viewState: { cardinality: "many", replay: "last" },
+} as const;
+
+const flushMicrotasks = async () => Promise.resolve();
+
+describe("AppEventBus", () => {
+  it("replays once events to late callback and Promise subscribers", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("initialize", 42);
+
+    const calls: number[] = [];
+    bus.on("initialize", (value) => {
+      calls.push(value);
+    });
+
+    expect(calls).toEqual([]);
+    await flushMicrotasks();
+    expect(calls).toEqual([42]);
+
+    await expect(bus.on("initialize")).resolves.toBe(42);
+  });
+
+  it("does not replay stream events to late subscribers", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("pointerUp", "first");
+
+    const calls: string[] = [];
+    bus.on("pointerUp", (pointerId) => {
+      calls.push(pointerId);
+    });
+
+    await flushMicrotasks();
+    expect(calls).toEqual([]);
+
+    bus.emit("pointerUp", "second");
+    expect(calls).toEqual(["second"]);
+  });
+
+  it("replays replay-last stream events and stays subscribed", async () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("viewState", 1);
+
+    const calls: number[] = [];
+    bus.on("viewState", (zoom) => {
+      calls.push(zoom);
+    });
+
+    await flushMicrotasks();
+    expect(calls).toEqual([1]);
+
+    bus.emit("viewState", 2);
+    expect(calls).toEqual([1, 2]);
+  });
+
+  it("throws when emitting a once event twice", () => {
+    const bus = new AppEventBus<TestEvents, typeof behavior>(behavior);
+    bus.emit("initialize", 1);
+
+    expect(() => {
+      bus.emit("initialize", 2);
+    }).toThrow('Event "initialize" can only be emitted once');
+  });
+});

packages/common/src/appEventBus.ts

@@ -0,0 +1,136 @@
+import type { UnsubscribeCallback } from "@excalidraw/excalidraw/types";
+
+import { Emitter } from "./emitter";
+import { isProdEnv } from "./utils";
+
+export type AppEventPayloadMap = Record<string, unknown[]>;
+
+export type AppEventBehavior = {
+  cardinality: "once" | "many";
+  replay: "none" | "last";
+};
+
+export type AppEventBehaviorMap<Events extends AppEventPayloadMap> = {
+  [K in keyof Events]: AppEventBehavior;
+};
+
+type AwaitableAppEventKeys<
+  Events extends AppEventPayloadMap,
+  Behavior extends AppEventBehaviorMap<Events>,
+> = {
+  [K in keyof Events]: Behavior[K]["cardinality"] extends "once"
+    ? Behavior[K]["replay"] extends "last"
+      ? K
+      : never
+    : never;
+}[keyof Events];
+
+type AppEventPromiseValue<Args extends any[]> = Args extends [infer Only]
+  ? Only
+  : Args;
+
+export class AppEventBus<
+  Events extends AppEventPayloadMap,
+  Behavior extends AppEventBehaviorMap<Events>,
+> {
+  private readonly emitters = new Map<keyof Events, Emitter<any>>();
+  private readonly lastPayload = new Map<keyof Events, any[]>();
+  private readonly emittedOnce = new Set<keyof Events>();
+
+  constructor(private readonly behavior: Behavior) {}
+
+  private getEmitter<K extends keyof Events>(name: K): Emitter<Events[K]> {
+    let emitter = this.emitters.get(name);
+    if (!emitter) {
+      emitter = new Emitter<any>();
+      this.emitters.set(name, emitter);
+    }
+    return emitter as Emitter<Events[K]>;
+  }
+
+  private toPromiseValue<Args extends any[]>(
+    args: Args,
+  ): AppEventPromiseValue<Args> {
+    return (args.length === 1 ? args[0] : args) as AppEventPromiseValue<Args>;
+  }
+
+  public on<K extends keyof Events>(
+    name: K,
+    callback: (...args: Events[K]) => void,
+  ): UnsubscribeCallback;
+  public on<K extends AwaitableAppEventKeys<Events, Behavior>>(
+    name: K,
+  ): Promise<AppEventPromiseValue<Events[K]>>;
+  public on<K extends keyof Events>(
+    name: K,
+    callback?: (...args: Events[K]) => void,
+  ): UnsubscribeCallback | Promise<AppEventPromiseValue<Events[K]>> {
+    const eventBehavior = this.behavior[name];
+    const cachedPayload = this.lastPayload.get(name) as Events[K] | undefined;
+
+    if (callback) {
+      if (eventBehavior.replay === "last" && cachedPayload) {
+        queueMicrotask(() => callback(...cachedPayload));
+
+        if (eventBehavior.cardinality === "once") {
+          return () => {};
+        }
+      }
+
+      return this.getEmitter(name).on(callback);
+    }
+
+    if (
+      eventBehavior.cardinality !== "once" ||
+      eventBehavior.replay !== "last"
+    ) {
+      throw new Error(`Event "${String(name)}" requires a callback`);
+    }
+
+    if (cachedPayload) {
+      return Promise.resolve(this.toPromiseValue(cachedPayload));
+    }
+
+    return new Promise<AppEventPromiseValue<Events[K]>>((resolve) => {
+      this.getEmitter(name).once((...args: Events[K]) => {
+        resolve(this.toPromiseValue(args));
+      });
+    });
+  }
+
+  public emit<K extends keyof Events>(name: K, ...args: Events[K]) {
+    const eventBehavior = this.behavior[name];
+
+    if (!isProdEnv()) {
+      if (eventBehavior.cardinality === "once") {
+        if (this.emittedOnce.has(name)) {
+          throw new Error(`Event "${String(name)}" can only be emitted once`);
+        }
+        this.emittedOnce.add(name);
+      }
+    }
+
+    if (eventBehavior.replay === "last") {
+      this.lastPayload.set(name, args);
+    }
+
+    try {
+      this.getEmitter(name).trigger(...args);
+    } finally {
+      if (eventBehavior.cardinality === "once") {
+        this.getEmitter(name).clear();
+      }
+    }
+  }
+
+  public clear() {
+    this.lastPayload.clear();
+    this.emittedOnce.clear();
+
+    for (const emitter of this.emitters.values()) {
+      emitter.clear();
+    }
+
+    this.emitters.clear();
+  }
+}

packages/common/src/index.ts

@@ -11,5 +11,7 @@ export * from "./random";
 export * from "./url";
 export * from "./utils";
 export * from "./emitter";
+export * from "./appEventBus";
 export * from "./editorInterface";
+export * from "./versionedSnapshotStore";
 export { Debug } from "../debug";

packages/common/src/versionedSnapshotStore.ts

@@ -0,0 +1,70 @@
+export type VersionedSnapshot<T> = Readonly<{
+  version: number;
+  value: T;
+}>;
+
+export class VersionedSnapshotStore<T> {
+  private version = 0;
+  private value: T;
+  private readonly waiters = new Set<
+    (snapshot: VersionedSnapshot<T>) => void
+  >();
+  private readonly subscribers = new Set<
+    (snapshot: VersionedSnapshot<T>) => void
+  >();
+
+  constructor(
+    initialValue: T,
+    private readonly isEqual: (prev: T, next: T) => boolean = Object.is,
+  ) {
+    this.value = initialValue;
+  }
+
+  public getSnapshot(): VersionedSnapshot<T> {
+    return { version: this.version, value: this.value };
+  }
+
+  public set(nextValue: T): boolean {
+    if (this.isEqual(this.value, nextValue)) {
+      return false;
+    }
+
+    this.value = nextValue;
+    this.version += 1;
+
+    const snapshot = this.getSnapshot();
+
+    for (const subscriber of this.subscribers) {
+      subscriber(snapshot);
+    }
+    for (const waiter of this.waiters) {
+      waiter(snapshot);
+    }
+    this.waiters.clear();
+
+    return true;
+  }
+
+  public update(updater: (prev: T) => T): boolean {
+    return this.set(updater(this.value));
+  }
+
+  public subscribe(
+    subscriber: (snapshot: VersionedSnapshot<T>) => void,
+  ): () => void {
+    this.subscribers.add(subscriber);
+    return () => {
+      this.subscribers.delete(subscriber);
+    };
+  }
+
+  public pull(sinceVersion = -1): Promise<VersionedSnapshot<T>> {
+    if (this.version !== sinceVersion) {
+      return Promise.resolve(this.getSnapshot());
+    }
+
+    return new Promise((resolve) => {
+      this.waiters.add(resolve);
+    });
+  }
+}