@navaramap/core 0.0.0

package/src/event/EventManager.ts

@@ -0,0 +1,387 @@
+import { type Events } from "@navaramap/engine";
+
+import { generate_id_from_entity, isEntityEvent } from "../id";
+
+import { TransactionManager } from "./TransactionManager";
+
+// The WASM `Events` class exposes each stack only through a move-out
+// `take_<key>()` method (reading a getter would deep-clone the array and every
+// element). Stack keys and value types are derived from those methods.
+export type JsEvents = {
+  [K in keyof Events as K extends `take_${infer P}`
+    ? P
+    : never]: Events[K] extends (...args: never[]) => infer R ? R : never;
+};
+export type JsEventsKey = keyof JsEvents;
+
+type EventsStacks = {
+  [K in JsEventsKey]-?: JsEvents[K] extends unknown[]
+    ? JsEvents[K]
+    : JsEvents[K][];
+};
+
+type GetJsEventValue<K extends JsEventsKey> = EventsStacks[K] extends unknown[]
+  ? EventsStacks[K][number]
+  : EventsStacks[K];
+
+type TransactionProcessOption<
+  AddKey extends JsEventsKey,
+  RemoveKey extends JsEventsKey,
+  ChangeKey extends JsEventsKey,
+> = {
+  add: {
+    key: AddKey;
+    max?: number;
+  };
+  remove: {
+    key: RemoveKey;
+    max?: number;
+  };
+  change?: {
+    key: ChangeKey;
+    max?: number;
+  };
+};
+
+type TransactionCallbackParams<
+  AddKey extends JsEventsKey,
+  RemoveKey extends JsEventsKey,
+  ChangeKey extends JsEventsKey,
+> =
+  | { type: "add"; event: GetJsEventValue<AddKey> }
+  | { type: "remove"; event: GetJsEventValue<RemoveKey> }
+  | { type: "change"; event: GetJsEventValue<ChangeKey> };
+
+const maybeFree = (ev: object | undefined) => {
+  if (ev && "free" in ev && ev.free instanceof Function) {
+    ev.free();
+  }
+};
+
+const defaultGenerateEventId = <
+  AddKey extends JsEventsKey,
+  RemoveKey extends JsEventsKey,
+  ChangeKey extends JsEventsKey,
+>(
+  ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>,
+) => {
+  const { event } = ev;
+
+  if (!isEntityEvent(event)) {
+    return;
+  }
+  const id = generate_id_from_entity(event);
+  return id;
+};
+
+export class EventManager {
+  stacks: EventsStacks = {
+    camera_transform_updated: [],
+    camera_frustum_updated: [],
+    data_requested: [],
+    data_requester_removed: [],
+    mesh_added: [],
+    mesh_updated: [],
+    mesh_removed: [],
+    object_transform_updated: [],
+    renderable_feature_added: [],
+    renderable_feature_changed: [],
+    renderable_feature_removed: [],
+    texture_fragment_removed: [],
+    texture_fragment_requested: [],
+    update_sample_terrain_height: [],
+    worker_task_delegated: [],
+    worker_task_removed: [],
+    hillshade_backfilled: [],
+    hillshade_canceled: [],
+  };
+  // In-flight "add" event ids per transaction key, used to abort adds whose
+  // matching remove arrives while they are still pending. Keyed by transaction
+  // so one transaction's remove phase cannot wipe another's tracking.
+  addedEventIds = new Map<string, Set<unknown>>();
+  private transactionManager = new TransactionManager();
+
+  needsUpdate() {
+    return Object.values(this.stacks).some((v) => !!v.length);
+  }
+
+  pushEvents(events: Events | undefined) {
+    if (!events) return;
+    for (const k of Object.keys(this.stacks) as JsEventsKey[]) {
+      // Move the stack out of WASM instead of reading a cloning getter.
+      const take = events[`take_${k}` as keyof Events] as unknown as (
+        this: Events,
+      ) => JsEvents[JsEventsKey];
+      const event = take.call(events);
+      if (!event) continue;
+      if (Array.isArray(event)) {
+        (this.stacks[k] as unknown[]).push(...event);
+      } else {
+        (this.stacks[k] as unknown[]).push(event);
+      }
+    }
+  }
+
+  forEachStack<Key extends JsEventsKey>(
+    key: Key,
+    cb: (value: GetJsEventValue<Key>) => void,
+    max = 100,
+  ) {
+    let idx = 0;
+    for (const value of this.stacks[key]) {
+      if (idx === max) {
+        break;
+      }
+
+      cb(value as GetJsEventValue<Key>);
+
+      maybeFree(value);
+
+      idx++;
+    }
+
+    // Remove processed events
+    this.stacks[key].splice(0, idx);
+  }
+
+  async forEachStackAsync<Key extends JsEventsKey>(
+    key: Key,
+    cb: (value: GetJsEventValue<Key>) => Promise<void>,
+    max = 100,
+    shouldProcess?: (value: GetJsEventValue<Key>) => boolean,
+  ) {
+    const promises = [];
+
+    let idx = 0;
+    const removedIndices = [];
+    for (const value of this.stacks[key]) {
+      if (idx === max) {
+        break;
+      }
+
+      const v = value as GetJsEventValue<Key>;
+
+      if (shouldProcess && !shouldProcess(v)) {
+        idx++;
+        continue;
+      }
+
+      promises.push(cb(v));
+
+      removedIndices.push(idx);
+
+      idx++;
+    }
+
+    const removedEvs = [];
+
+    let offset = 0;
+    for (const idx of removedIndices) {
+      // Remove processed events
+      const i = idx - offset;
+      removedEvs.push(this.stacks[key][i]);
+      this.stacks[key].splice(i, 1);
+      offset++;
+    }
+
+    // A single failing handler must not reject the whole batch: the other
+    // handlers' results still count and the processed events below must be
+    // freed exactly once regardless.
+    const settled = await Promise.allSettled(promises);
+    for (const s of settled) {
+      if (s.status === "rejected") {
+        console.error(`Event handler for "${key}" failed:`, s.reason);
+      }
+    }
+
+    for (const e of removedEvs) {
+      maybeFree(e);
+    }
+  }
+
+  // Remove duplicated events before it's proceeded.
+  // For example, if MeshAdd event and MeshRemove event are exist, it should be considered as duplicated.
+  removeDuplicatedTransactionEvents<
+    AddKey extends JsEventsKey,
+    RemoveKey extends JsEventsKey,
+    ChangeKey extends JsEventsKey,
+  >(options: TransactionProcessOption<AddKey, RemoveKey, ChangeKey>) {
+    const addedEventsMap = new Map<string, number>();
+    const changedEventsMap = options.change ? new Map<string, number>() : null;
+
+    this.stacks[options.add.key].forEach((added, index) => {
+      if (isEntityEvent(added)) {
+        const id = generate_id_from_entity(added);
+        addedEventsMap.set(id, index);
+      }
+    });
+
+    if (changedEventsMap && options.change) {
+      this.stacks[options.change.key].forEach((changed, index) => {
+        if (isEntityEvent(changed)) {
+          const id = generate_id_from_entity(changed);
+          changedEventsMap.set(id, index);
+        }
+      });
+    }
+
+    // Track indices to remove from each stack
+    const addedIndicesToRemove = new Set<number>();
+    const changedIndicesToRemove = new Set<number>();
+    const removedIndicesToSkip = new Set<number>();
+
+    this.stacks[options.remove.key].forEach((removed, removeIdx) => {
+      if (!isEntityEvent(removed)) return;
+
+      const removedId = generate_id_from_entity(removed);
+
+      const addedIdx = addedEventsMap.get(removedId);
+      let foundMatch = false;
+
+      if (addedIdx !== undefined) {
+        addedIndicesToRemove.add(addedIdx);
+        foundMatch = true;
+      }
+
+      if (changedEventsMap && options.change) {
+        const changedIdx = changedEventsMap.get(removedId);
+        if (changedIdx !== undefined) {
+          changedIndicesToRemove.add(changedIdx);
+        }
+      }
+
+      if (foundMatch) {
+        removedIndicesToSkip.add(removeIdx);
+      }
+    });
+
+    if (addedIndicesToRemove.size > 0) {
+      this.removeStacksByIndices(options.add.key, addedIndicesToRemove);
+    }
+
+    if (changedIndicesToRemove.size > 0 && options.change) {
+      this.removeStacksByIndices(options.change.key, changedIndicesToRemove);
+    }
+
+    if (removedIndicesToSkip.size > 0) {
+      this.removeStacksByIndices(options.remove.key, removedIndicesToSkip);
+    }
+  }
+
+  removeStacksByIndices(key: JsEventsKey, removedIndices: Set<number>) {
+    const sortedIndices = [...removedIndices].sort((a, b) => b - a);
+    for (const idx of sortedIndices) {
+      maybeFree(this.stacks[key][idx]);
+      this.stacks[key].splice(idx, 1);
+    }
+  }
+
+  processTransactionEvents<
+    AddKey extends JsEventsKey,
+    RemoveKey extends JsEventsKey,
+    ChangeKey extends JsEventsKey,
+  >(
+    transactionKey: string,
+    options: TransactionProcessOption<AddKey, RemoveKey, ChangeKey>,
+    cb: (
+      ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>,
+    ) => Promise<void>,
+    handlers?: {
+      shouldProcess?: (
+        ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>,
+      ) => boolean;
+      generateEventId?: (
+        ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>,
+      ) => string;
+      onAbort?: (ev: GetJsEventValue<RemoveKey>) => void | Promise<void>;
+    },
+  ) {
+    const {
+      shouldProcess,
+      generateEventId = defaultGenerateEventId,
+      onAbort,
+    } = handlers ?? {};
+
+    this.removeDuplicatedTransactionEvents(options);
+
+    const addedEventIds = this.addedEventIds.get(transactionKey) ?? new Set();
+    this.addedEventIds.set(transactionKey, addedEventIds);
+
+    const transaction = this.transactionManager
+      .getOrInsert(transactionKey)
+      .then(() =>
+        this.forEachStackAsync(
+          options.add.key,
+          (event) => {
+            if (onAbort) {
+              addedEventIds.add(generateEventId({ type: "add", event }));
+            }
+            return cb({ type: "add", event });
+          },
+          options.add.max,
+          shouldProcess
+            ? (event) => shouldProcess({ type: "add", event })
+            : undefined,
+        ),
+      )
+      .then(() => {
+        if (onAbort) {
+          addedEventIds.clear();
+        }
+        return this.forEachStackAsync(
+          options.remove.key,
+          (event) => cb({ type: "remove", event }),
+          options.remove.max,
+          shouldProcess
+            ? (event) => shouldProcess({ type: "remove", event })
+            : undefined,
+        );
+      });
+
+    // Handle an abort process to an add event.
+    if (onAbort && addedEventIds.size) {
+      for (const event of this.stacks[options.remove.key]) {
+        if (!event) continue;
+        const removeEv = event as GetJsEventValue<RemoveKey>;
+        const id = generateEventId({ type: "remove", event: removeEv });
+        if (id && addedEventIds.has(id)) {
+          // Contain both sync throws and async rejections: an abort handler
+          // failure must not escape into the caller (or become an unhandled
+          // rejection) and must not stop the remaining aborts.
+          try {
+            Promise.resolve(onAbort(removeEv)).catch((err) => {
+              console.error(
+                `onAbort handler for "${transactionKey}" failed:`,
+                err,
+              );
+            });
+          } catch (err) {
+            console.error(
+              `onAbort handler for "${transactionKey}" failed:`,
+              err,
+            );
+          }
+          addedEventIds.delete(id);
+        }
+      }
+    }
+
+    if (options.change) {
+      const change = options.change;
+      transaction
+        .then(() =>
+          this.forEachStackAsync(
+            change.key,
+            (event) => cb({ type: "change", event }),
+            change.max,
+            shouldProcess
+              ? (event) => shouldProcess({ type: "change", event })
+              : undefined,
+          ),
+        )
+        .end();
+    } else {
+      transaction.end();
+    }
+  }
+}

package/src/event/TransactionManager.test.ts

@@ -0,0 +1,126 @@
+import { expect, it, vi } from "vitest";
+
+import { TransactionManager } from "./TransactionManager";
+
+it("should manage transaction", async () => {
+  const transactionManager = new TransactionManager();
+  const transaction = transactionManager.getOrInsert("test");
+
+  const mockFn = vi.fn();
+  const mockFnDuplicated = vi.fn();
+  const mockFnNext = vi.fn();
+
+  // First frame
+  transaction
+    .then(async () => mockFn())
+    .then(async () => mockFnNext())
+    .end();
+
+  // Second frame
+  transaction.then(async () => mockFnDuplicated());
+  transaction.then(async () => mockFnDuplicated());
+
+  await vi.waitUntil(() => !transaction.continuable);
+  expect(mockFn).toBeCalledTimes(1);
+  expect(mockFnNext).toBeCalledTimes(0);
+
+  // Third frame
+  transaction
+    .then(async () => mockFn())
+    .then(async () => mockFnNext())
+    .end();
+  transaction
+    .then(async () => mockFnDuplicated())
+    .then(async () => mockFnDuplicated());
+
+  await vi.waitUntil(() => !transaction.next?.continuable);
+  expect(mockFn).toBeCalledTimes(1);
+  expect(mockFnNext).toBeCalledTimes(1);
+
+  expect(transaction.next?.next?.continuable).toBeTruthy();
+
+  // Forth frame
+  transaction
+    .then(async () => mockFn())
+    .then(async () => mockFnNext())
+    .end();
+
+  expect(mockFn).toBeCalledTimes(1);
+  expect(mockFnNext).toBeCalledTimes(1);
+  expect(mockFnDuplicated).not.toBeCalled();
+
+  expect(transaction.continuable).toBeTruthy();
+  expect(transaction.next?.continuable).toBeFalsy();
+  expect(transaction.next?.next?.continuable).toBeFalsy();
+});
+
+it("should continue the transaction chain after a rejected callback", async () => {
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  const transactionManager = new TransactionManager();
+  const transaction = transactionManager.getOrInsert("test");
+
+  const mockFnNext = vi.fn();
+  const mockFnRecovered = vi.fn();
+
+  // First frame: the first-phase callback fails. Before the fix this left
+  // `currentPending` set forever, wedging the whole transaction id.
+  transaction
+    .then(async () => {
+      throw new Error("boom");
+    })
+    .then(async () => mockFnNext())
+    .end();
+
+  // Later frames replay the same chain; both phases must eventually run.
+  await vi.waitUntil(() => {
+    transaction
+      .then(async () => mockFnRecovered())
+      .then(async () => mockFnNext())
+      .end();
+    return (
+      mockFnRecovered.mock.calls.length > 0 && mockFnNext.mock.calls.length > 0
+    );
+  });
+
+  expect(consoleError).toHaveBeenCalledWith(
+    expect.stringContaining('Transaction "test" callback failed:'),
+    expect.any(Error),
+  );
+  consoleError.mockRestore();
+});
+
+it("should continue the transaction chain after a synchronously throwing callback", async () => {
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  const transactionManager = new TransactionManager();
+  const transaction = transactionManager.getOrInsert("test");
+
+  const mockFnNext = vi.fn();
+  const mockFnRecovered = vi.fn();
+
+  // First frame: the callback throws before ever returning a promise. This
+  // must be contained just like a rejection, or the continuable flags stay
+  // down forever.
+  transaction
+    .then(() => {
+      throw new Error("boom");
+    })
+    .then(async () => mockFnNext())
+    .end();
+
+  // Later frames replay the same chain; both phases must eventually run.
+  await vi.waitUntil(() => {
+    transaction
+      .then(async () => mockFnRecovered())
+      .then(async () => mockFnNext())
+      .end();
+    return (
+      mockFnRecovered.mock.calls.length > 0 && mockFnNext.mock.calls.length > 0
+    );
+  });
+
+  expect(consoleError).toHaveBeenCalledWith(
+    expect.stringContaining('Transaction "test" callback failed:'),
+    expect.any(Error),
+  );
+  consoleError.mockRestore();
+});

package/src/event/TransactionManager.ts

@@ -0,0 +1,78 @@
+export class TransactionManager {
+  private record: Record<string, Transaction | undefined> = {};
+  getOrInsert(id: string) {
+    if (this.record[id]) {
+      return this.record[id];
+    }
+    this.record[id] = new Transaction(id);
+    return this.record[id];
+  }
+}
+
+export class Transaction {
+  id: string;
+  continuable: boolean;
+  currentPending?: Promise<void>;
+  next?: Transaction;
+  parent?: Transaction;
+
+  constructor(id: string, continuable = true) {
+    this.id = id;
+    this.continuable = continuable;
+  }
+
+  then(cb: () => Promise<void>) {
+    if (!this.next) {
+      this.next = new Transaction(this.id, false);
+      this.next.parent = this;
+    }
+    if (!this.currentPending && this.continuable) {
+      this.continuable = false;
+      this.next.continuable = false;
+      // A failed callback must be contained here: leaving the continuable
+      // flags down (and `currentPending` possibly set) would wedge this
+      // transaction id forever, silently stopping every event that flows
+      // through it.
+      const settle = () => {
+        this.currentPending = undefined;
+        if (this.next) {
+          this.next.continuable = true;
+        }
+      };
+      const fail = (err: unknown) => {
+        console.error(`Transaction "${this.id}" callback failed:`, err);
+        settle();
+      };
+      try {
+        this.currentPending = cb().then(settle, fail);
+      } catch (err) {
+        // `cb` threw synchronously, before returning a promise.
+        fail(err);
+      }
+    }
+    return this.next;
+  }
+
+  end() {
+    if (!this.continuable) {
+      return;
+    }
+
+    let parent: Transaction | undefined = this.parent;
+    if (!parent) {
+      // Root parent should be true.
+      this.continuable = true;
+      return;
+    }
+
+    this.continuable = false;
+
+    while (true) {
+      if (!parent.parent) {
+        break;
+      }
+      parent = parent.parent;
+    }
+    parent.continuable = true;
+  }
+}

package/src/event/index.ts

@@ -0,0 +1,2 @@
+export * from "./EventManager";
+export * from "./TransactionManager";

package/src/event/mock.ts

@@ -0,0 +1,36 @@
+import type {
+  EntityEvent,
+  Events,
+  RenderableFeatureAddedEvent,
+  RenderableFeatureChangedEvent,
+} from "@navaramap/engine";
+import { noop } from "lodash-es";
+
+import type { JsEvents, JsEventsKey } from "./EventManager";
+
+export const makeRenderableFeatures = <
+  Ev extends
+    | RenderableFeatureAddedEvent
+    | RenderableFeatureChangedEvent
+    | EntityEvent,
+>(
+  ind: number,
+  gen: number,
+) => {
+  return { ind, gen, free: noop } as Ev;
+};
+
+// The real `Events` exposes each stack only via a `take_<key>()` method
+// (see EventManager.pushEvents); mimic that shape for any key.
+export const makeEvent = (events: { [K in JsEventsKey]?: JsEvents[K] }) =>
+  new Proxy(
+    {},
+    {
+      get: (_target, prop) => {
+        if (typeof prop === "string" && prop.startsWith("take_")) {
+          return () => events[prop.slice("take_".length) as JsEventsKey];
+        }
+        return undefined;
+      },
+    },
+  ) as Events;

package/src/eventHandler.ts

@@ -0,0 +1,52 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BaseEventMap = Record<string, (...args: any[]) => unknown>;
+
+export class EventHandler<
+  T extends BaseEventMap = BaseEventMap,
+  K extends keyof T = keyof T,
+> {
+  events: { [E in K]?: Set<T[E]> } = {};
+  onceEvents: { [E in K]?: Set<T[E]> } = {};
+
+  on<E extends K>(k: E, f: T[E]) {
+    if (!this.events[k]) {
+      this.events[k] = new Set();
+    }
+    this.events[k].add(f);
+  }
+
+  off<E extends K>(k: E, f: T[E]) {
+    this.events[k]?.delete(f);
+    this.onceEvents[k]?.delete(f);
+  }
+
+  clear<E extends K>(k: E) {
+    this.events[k]?.clear();
+    this.onceEvents[k]?.clear();
+  }
+
+  size<E extends K>(k: E) {
+    return this.events[k]?.size || this.onceEvents[k]?.size;
+  }
+
+  /**
+   * Register a callback that will be executed only once and then removed
+   */
+  once<E extends K>(k: E, f: T[E]) {
+    if (!this.onceEvents[k]) {
+      this.onceEvents[k] = new Set();
+    }
+    this.onceEvents[k].add(f);
+  }
+
+  emit<E extends K>(k: E, ...args: Parameters<T[E]>) {
+    // Execute regular callbacks
+    this.events[k]?.forEach((c) => c(...args));
+
+    // Execute once callbacks and then remove them
+    if (this.onceEvents[k]?.size) {
+      this.onceEvents[k]?.forEach((c) => c(...args));
+      this.onceEvents[k]?.clear();
+    }
+  }
+}