@korajs/devtools 0.1.0

package/dist/index.js

@@ -0,0 +1,383 @@
+import {
+  PortRouter
+} from "./chunk-JH2X4T4Z.js";
+import {
+  buildPanelModel,
+  renderDevtoolsPanel
+} from "./chunk-4ZQ2RTZM.js";
+
+// src/bridge/message-bridge.ts
+var DEFAULT_CHANNEL = "kora-devtools";
+var MessageBridge = class {
+  channelName;
+  listeners = /* @__PURE__ */ new Set();
+  messageHandler;
+  destroyed = false;
+  constructor(channelName = DEFAULT_CHANNEL) {
+    this.channelName = channelName;
+    if (typeof window === "undefined") {
+      this.messageHandler = null;
+      return;
+    }
+    this.messageHandler = (event) => {
+      if (this.destroyed) return;
+      const data = event.data;
+      if (!data || data.source !== this.channelName) return;
+      for (const listener of this.listeners) {
+        listener(data.payload);
+      }
+    };
+    window.addEventListener("message", this.messageHandler);
+  }
+  /**
+   * Post a timestamped event through the bridge.
+   * No-op if window is not available or the bridge has been destroyed.
+   */
+  send(event) {
+    if (this.destroyed || typeof window === "undefined") return;
+    const message = {
+      source: this.channelName,
+      payload: event
+    };
+    window.postMessage(message, "*");
+  }
+  /**
+   * Register a callback for events received through the bridge.
+   * Returns an unsubscribe function.
+   */
+  onReceive(callback) {
+    if (this.destroyed) return () => {
+    };
+    this.listeners.add(callback);
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  /**
+   * Remove all listeners and detach from window.
+   * After calling destroy, all operations become no-ops.
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.listeners.clear();
+    if (this.messageHandler && typeof window !== "undefined") {
+      window.removeEventListener("message", this.messageHandler);
+    }
+  }
+};
+
+// src/buffer/event-buffer.ts
+var DEFAULT_CAPACITY = 1e4;
+var EventBuffer = class {
+  _capacity;
+  buffer;
+  /** Index where the next event will be written */
+  head = 0;
+  /** Total number of events ever pushed (used to compute readable range) */
+  _totalPushed = 0;
+  constructor(capacity = DEFAULT_CAPACITY) {
+    if (capacity < 1) {
+      throw new Error("EventBuffer capacity must be at least 1");
+    }
+    this._capacity = capacity;
+    this.buffer = new Array(capacity);
+  }
+  /** Maximum number of events the buffer can hold */
+  get capacity() {
+    return this._capacity;
+  }
+  /** Current number of events in the buffer */
+  get size() {
+    return Math.min(this._totalPushed, this._capacity);
+  }
+  /**
+   * Append an event to the buffer.
+   * If the buffer is at capacity, the oldest event is evicted.
+   */
+  push(event) {
+    this.buffer[this.head] = event;
+    this.head = (this.head + 1) % this._capacity;
+    this._totalPushed++;
+  }
+  /**
+   * Returns all events in insertion order (oldest first).
+   */
+  getAll() {
+    if (this._totalPushed === 0) return [];
+    const result = [];
+    if (this._totalPushed <= this._capacity) {
+      for (let i = 0; i < this.head; i++) {
+        const event = this.buffer[i];
+        if (event) result.push(event);
+      }
+    } else {
+      for (let i = 0; i < this._capacity; i++) {
+        const index = (this.head + i) % this._capacity;
+        const event = this.buffer[index];
+        if (event) result.push(event);
+      }
+    }
+    return result;
+  }
+  /**
+   * Returns events whose sequential IDs fall within [start, end] (inclusive).
+   */
+  getRange(start, end) {
+    return this.getAll().filter((e) => e.id >= start && e.id <= end);
+  }
+  /**
+   * Returns events matching a specific KoraEventType.
+   */
+  getByType(type) {
+    return this.getAll().filter((e) => e.event.type === type);
+  }
+  /** Remove all events from the buffer */
+  clear() {
+    this.buffer.fill(void 0);
+    this.head = 0;
+    this._totalPushed = 0;
+  }
+};
+
+// src/instrumenter/instrumenter.ts
+var DEFAULT_BUFFER_SIZE = 1e4;
+var DEFAULT_CHANNEL_NAME = "kora-devtools";
+var ALL_EVENT_TYPES = [
+  "operation:created",
+  "operation:applied",
+  "merge:started",
+  "merge:completed",
+  "merge:conflict",
+  "constraint:violated",
+  "sync:connected",
+  "sync:disconnected",
+  "sync:sent",
+  "sync:received",
+  "sync:acknowledged",
+  "query:subscribed",
+  "query:invalidated",
+  "query:executed",
+  "connection:quality"
+];
+var Instrumenter = class {
+  constructor(emitter, config) {
+    this.emitter = emitter;
+    const bufferSize = config?.bufferSize ?? DEFAULT_BUFFER_SIZE;
+    const bridgeEnabled = config?.bridgeEnabled ?? true;
+    const channelName = config?.channelName ?? DEFAULT_CHANNEL_NAME;
+    this.buffer = new EventBuffer(bufferSize);
+    this.bridge = bridgeEnabled ? new MessageBridge(channelName) : null;
+    this.attachListeners();
+  }
+  emitter;
+  buffer;
+  bridge;
+  unsubscribers = [];
+  nextId = 1;
+  paused = false;
+  destroyed = false;
+  /** Access the underlying event buffer */
+  getBuffer() {
+    return this.buffer;
+  }
+  /** Access the message bridge, or null if bridge is disabled */
+  getBridge() {
+    return this.bridge;
+  }
+  /** Temporarily stop recording events. Events emitted while paused are dropped. */
+  pause() {
+    this.paused = true;
+  }
+  /** Resume recording events after a pause. */
+  resume() {
+    this.paused = false;
+  }
+  /** Whether the instrumenter is currently paused */
+  isPaused() {
+    return this.paused;
+  }
+  /**
+   * Detach all listeners from the emitter and destroy the bridge.
+   * After calling destroy, the instrumenter is inert.
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    for (const unsub of this.unsubscribers) {
+      unsub();
+    }
+    this.unsubscribers.length = 0;
+    this.bridge?.destroy();
+  }
+  attachListeners() {
+    for (const eventType of ALL_EVENT_TYPES) {
+      const unsub = this.emitter.on(eventType, (event) => {
+        this.handleEvent(event);
+      });
+      this.unsubscribers.push(unsub);
+    }
+  }
+  handleEvent(event) {
+    if (this.paused || this.destroyed) return;
+    const timestamped = {
+      id: this.nextId++,
+      event,
+      receivedAt: Date.now()
+    };
+    this.buffer.push(timestamped);
+    this.bridge?.send(timestamped);
+  }
+};
+
+// src/types.ts
+var EVENT_TYPE_CATEGORIES = {
+  "operation:created": "operation",
+  "operation:applied": "operation",
+  "merge:started": "merge",
+  "merge:completed": "merge",
+  "merge:conflict": "merge",
+  "constraint:violated": "merge",
+  "sync:connected": "sync",
+  "sync:disconnected": "sync",
+  "sync:sent": "sync",
+  "sync:received": "sync",
+  "sync:acknowledged": "sync",
+  "query:subscribed": "query",
+  "query:invalidated": "query",
+  "query:executed": "query",
+  "connection:quality": "connection"
+};
+function eventTypeToCategory(type) {
+  return EVENT_TYPE_CATEGORIES[type];
+}
+
+// src/filter/event-filter.ts
+function getEventCategory(type) {
+  return eventTypeToCategory(type);
+}
+function extractCollection(event) {
+  const e = event.event;
+  switch (e.type) {
+    case "operation:created":
+    case "operation:applied":
+      return e.operation.collection;
+    case "merge:started":
+      return e.operationA.collection;
+    case "merge:completed":
+    case "merge:conflict":
+      return e.trace.operationA.collection;
+    case "constraint:violated":
+      return e.trace.operationA.collection;
+    case "query:subscribed":
+      return e.collection;
+    case "query:invalidated":
+      return e.trigger.collection;
+    case "sync:sent":
+      return e.operations[0]?.collection ?? null;
+    case "sync:received":
+      return e.operations[0]?.collection ?? null;
+    default:
+      return null;
+  }
+}
+function filterEvents(events, criteria) {
+  const { categories, types, timeRange, collection } = criteria;
+  if (!categories && !types && !timeRange && !collection) {
+    return events;
+  }
+  const categorySet = categories ? new Set(categories) : null;
+  const typeSet = types ? new Set(types) : null;
+  return events.filter((event) => {
+    if (categorySet) {
+      const cat = eventTypeToCategory(event.event.type);
+      if (!categorySet.has(cat)) return false;
+    }
+    if (typeSet) {
+      if (!typeSet.has(event.event.type)) return false;
+    }
+    if (timeRange) {
+      if (event.receivedAt < timeRange.start || event.receivedAt > timeRange.end) {
+        return false;
+      }
+    }
+    if (collection) {
+      const eventCollection = extractCollection(event);
+      if (eventCollection !== collection) return false;
+    }
+    return true;
+  });
+}
+
+// src/stats/event-stats.ts
+function computeStatistics(events) {
+  const eventsByCategory = {
+    operation: 0,
+    merge: 0,
+    sync: 0,
+    query: 0,
+    connection: 0
+  };
+  const eventsByType = {};
+  let mergeConflicts = 0;
+  let constraintViolations = 0;
+  let mergeDurationSum = 0;
+  let mergeDurationCount = 0;
+  let queryDurationSum = 0;
+  let queryDurationCount = 0;
+  let syncOperationsSent = 0;
+  let syncOperationsReceived = 0;
+  for (const timestamped of events) {
+    const e = timestamped.event;
+    const category = eventTypeToCategory(e.type);
+    eventsByCategory[category]++;
+    eventsByType[e.type] = (eventsByType[e.type] ?? 0) + 1;
+    switch (e.type) {
+      case "merge:completed":
+        mergeDurationSum += e.trace.duration;
+        mergeDurationCount++;
+        break;
+      case "merge:conflict":
+        mergeConflicts++;
+        mergeDurationSum += e.trace.duration;
+        mergeDurationCount++;
+        break;
+      case "constraint:violated":
+        constraintViolations++;
+        break;
+      case "query:executed":
+        queryDurationSum += e.duration;
+        queryDurationCount++;
+        break;
+      case "sync:sent":
+        syncOperationsSent += e.batchSize;
+        break;
+      case "sync:received":
+        syncOperationsReceived += e.batchSize;
+        break;
+    }
+  }
+  return {
+    totalEvents: events.length,
+    eventsByCategory,
+    eventsByType,
+    mergeConflicts,
+    constraintViolations,
+    avgMergeDuration: mergeDurationCount > 0 ? mergeDurationSum / mergeDurationCount : null,
+    avgQueryDuration: queryDurationCount > 0 ? queryDurationSum / queryDurationCount : null,
+    syncOperationsSent,
+    syncOperationsReceived
+  };
+}
+export {
+  EventBuffer,
+  Instrumenter,
+  MessageBridge,
+  PortRouter,
+  buildPanelModel,
+  computeStatistics,
+  filterEvents,
+  getEventCategory,
+  renderDevtoolsPanel
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge/message-bridge.ts","../src/buffer/event-buffer.ts","../src/instrumenter/instrumenter.ts","../src/types.ts","../src/filter/event-filter.ts","../src/stats/event-stats.ts"],"sourcesContent":["import type { TimestampedEvent } from '../types'\n\nconst DEFAULT_CHANNEL = 'kora-devtools'\n\n/** Shape of messages posted through the bridge */\ninterface BridgeMessage {\n\tsource: string\n\tpayload: TimestampedEvent\n}\n\n/**\n * Communicates between the page context and a DevTools panel via window.postMessage.\n * All messages are namespaced with a `source` field to avoid collisions with other\n * postMessage consumers on the page.\n *\n * Safe to instantiate in non-browser environments (SSR/Node) — all operations\n * become no-ops when `window` is not available.\n */\nexport class MessageBridge {\n\tprivate readonly channelName: string\n\tprivate readonly listeners: Set<(event: TimestampedEvent) => void> = new Set()\n\tprivate readonly messageHandler: ((event: MessageEvent) => void) | null\n\tprivate destroyed = false\n\n\tconstructor(channelName: string = DEFAULT_CHANNEL) {\n\t\tthis.channelName = channelName\n\n\t\tif (typeof window === 'undefined') {\n\t\t\tthis.messageHandler = null\n\t\t\treturn\n\t\t}\n\n\t\t// Single shared handler that dispatches to all registered callbacks\n\t\tthis.messageHandler = (event: MessageEvent) => {\n\t\t\tif (this.destroyed) return\n\t\t\tconst data = event.data as Partial<BridgeMessage> | undefined\n\t\t\tif (!data || data.source !== this.channelName) return\n\n\t\t\tfor (const listener of this.listeners) {\n\t\t\t\tlistener(data.payload as TimestampedEvent)\n\t\t\t}\n\t\t}\n\n\t\twindow.addEventListener('message', this.messageHandler)\n\t}\n\n\t/**\n\t * Post a timestamped event through the bridge.\n\t * No-op if window is not available or the bridge has been destroyed.\n\t */\n\tsend(event: TimestampedEvent): void {\n\t\tif (this.destroyed || typeof window === 'undefined') return\n\n\t\tconst message: BridgeMessage = {\n\t\t\tsource: this.channelName,\n\t\t\tpayload: event,\n\t\t}\n\t\twindow.postMessage(message, '*')\n\t}\n\n\t/**\n\t * Register a callback for events received through the bridge.\n\t * Returns an unsubscribe function.\n\t */\n\tonReceive(callback: (event: TimestampedEvent) => void): () => void {\n\t\tif (this.destroyed) return () => {}\n\n\t\tthis.listeners.add(callback)\n\t\treturn () => {\n\t\t\tthis.listeners.delete(callback)\n\t\t}\n\t}\n\n\t/**\n\t * Remove all listeners and detach from window.\n\t * After calling destroy, all operations become no-ops.\n\t */\n\tdestroy(): void {\n\t\tif (this.destroyed) return\n\t\tthis.destroyed = true\n\t\tthis.listeners.clear()\n\n\t\tif (this.messageHandler && typeof window !== 'undefined') {\n\t\t\twindow.removeEventListener('message', this.messageHandler)\n\t\t}\n\t}\n}\n","import type { KoraEventType } from '@korajs/core'\nimport type { TimestampedEvent } from '../types'\n\nconst DEFAULT_CAPACITY = 10_000\n\n/**\n * Fixed-capacity ring buffer for storing timestamped events.\n * When the buffer is full, the oldest events are evicted to make room for new ones.\n * This prevents unbounded memory growth when events accumulate fast.\n */\nexport class EventBuffer {\n\tprivate readonly _capacity: number\n\tprivate readonly buffer: Array<TimestampedEvent | undefined>\n\t/** Index where the next event will be written */\n\tprivate head = 0\n\t/** Total number of events ever pushed (used to compute readable range) */\n\tprivate _totalPushed = 0\n\n\tconstructor(capacity: number = DEFAULT_CAPACITY) {\n\t\tif (capacity < 1) {\n\t\t\tthrow new Error('EventBuffer capacity must be at least 1')\n\t\t}\n\t\tthis._capacity = capacity\n\t\tthis.buffer = new Array<TimestampedEvent | undefined>(capacity)\n\t}\n\n\t/** Maximum number of events the buffer can hold */\n\tget capacity(): number {\n\t\treturn this._capacity\n\t}\n\n\t/** Current number of events in the buffer */\n\tget size(): number {\n\t\treturn Math.min(this._totalPushed, this._capacity)\n\t}\n\n\t/**\n\t * Append an event to the buffer.\n\t * If the buffer is at capacity, the oldest event is evicted.\n\t */\n\tpush(event: TimestampedEvent): void {\n\t\tthis.buffer[this.head] = event\n\t\tthis.head = (this.head + 1) % this._capacity\n\t\tthis._totalPushed++\n\t}\n\n\t/**\n\t * Returns all events in insertion order (oldest first).\n\t */\n\tgetAll(): readonly TimestampedEvent[] {\n\t\tif (this._totalPushed === 0) return []\n\n\t\tconst result: TimestampedEvent[] = []\n\n\t\tif (this._totalPushed <= this._capacity) {\n\t\t\t// Buffer hasn't wrapped yet — events are 0..head-1\n\t\t\tfor (let i = 0; i < this.head; i++) {\n\t\t\t\tconst event = this.buffer[i]\n\t\t\t\tif (event) result.push(event)\n\t\t\t}\n\t\t} else {\n\t\t\t// Buffer has wrapped — oldest is at head, newest is at head-1\n\t\t\tfor (let i = 0; i < this._capacity; i++) {\n\t\t\t\tconst index = (this.head + i) % this._capacity\n\t\t\t\tconst event = this.buffer[index]\n\t\t\t\tif (event) result.push(event)\n\t\t\t}\n\t\t}\n\n\t\treturn result\n\t}\n\n\t/**\n\t * Returns events whose sequential IDs fall within [start, end] (inclusive).\n\t */\n\tgetRange(start: number, end: number): readonly TimestampedEvent[] {\n\t\treturn this.getAll().filter((e) => e.id >= start && e.id <= end)\n\t}\n\n\t/**\n\t * Returns events matching a specific KoraEventType.\n\t */\n\tgetByType(type: KoraEventType): readonly TimestampedEvent[] {\n\t\treturn this.getAll().filter((e) => e.event.type === type)\n\t}\n\n\t/** Remove all events from the buffer */\n\tclear(): void {\n\t\tthis.buffer.fill(undefined)\n\t\tthis.head = 0\n\t\tthis._totalPushed = 0\n\t}\n}\n","import type { KoraEvent, KoraEventEmitter, KoraEventType } from '@korajs/core'\nimport { MessageBridge } from '../bridge/message-bridge'\nimport { EventBuffer } from '../buffer/event-buffer'\nimport type { DevtoolsConfig, TimestampedEvent } from '../types'\n\nconst DEFAULT_BUFFER_SIZE = 10_000\nconst DEFAULT_CHANNEL_NAME = 'kora-devtools'\n\n/** All event types the instrumenter subscribes to */\nconst ALL_EVENT_TYPES: readonly KoraEventType[] = [\n\t'operation:created',\n\t'operation:applied',\n\t'merge:started',\n\t'merge:completed',\n\t'merge:conflict',\n\t'constraint:violated',\n\t'sync:connected',\n\t'sync:disconnected',\n\t'sync:sent',\n\t'sync:received',\n\t'sync:acknowledged',\n\t'query:subscribed',\n\t'query:invalidated',\n\t'query:executed',\n\t'connection:quality',\n] as const\n\n/**\n * Core orchestrator for Kora DevTools instrumentation.\n *\n * Attaches to a KoraEventEmitter, records all emitted events into a ring buffer\n * with sequential IDs and reception timestamps, and optionally forwards them\n * through a MessageBridge for consumption by a DevTools panel.\n *\n * @example\n * ```typescript\n * const instrumenter = new Instrumenter(app.emitter, { bufferSize: 5000 })\n * const buffer = instrumenter.getBuffer()\n * // ... later\n * instrumenter.destroy()\n * ```\n */\nexport class Instrumenter {\n\tprivate readonly buffer: EventBuffer\n\tprivate readonly bridge: MessageBridge | null\n\tprivate readonly unsubscribers: Array<() => void> = []\n\tprivate nextId = 1\n\tprivate paused = false\n\tprivate destroyed = false\n\n\tconstructor(\n\t\tprivate readonly emitter: KoraEventEmitter,\n\t\tconfig?: DevtoolsConfig,\n\t) {\n\t\tconst bufferSize = config?.bufferSize ?? DEFAULT_BUFFER_SIZE\n\t\tconst bridgeEnabled = config?.bridgeEnabled ?? true\n\t\tconst channelName = config?.channelName ?? DEFAULT_CHANNEL_NAME\n\n\t\tthis.buffer = new EventBuffer(bufferSize)\n\t\tthis.bridge = bridgeEnabled ? new MessageBridge(channelName) : null\n\n\t\tthis.attachListeners()\n\t}\n\n\t/** Access the underlying event buffer */\n\tgetBuffer(): EventBuffer {\n\t\treturn this.buffer\n\t}\n\n\t/** Access the message bridge, or null if bridge is disabled */\n\tgetBridge(): MessageBridge | null {\n\t\treturn this.bridge\n\t}\n\n\t/** Temporarily stop recording events. Events emitted while paused are dropped. */\n\tpause(): void {\n\t\tthis.paused = true\n\t}\n\n\t/** Resume recording events after a pause. */\n\tresume(): void {\n\t\tthis.paused = false\n\t}\n\n\t/** Whether the instrumenter is currently paused */\n\tisPaused(): boolean {\n\t\treturn this.paused\n\t}\n\n\t/**\n\t * Detach all listeners from the emitter and destroy the bridge.\n\t * After calling destroy, the instrumenter is inert.\n\t */\n\tdestroy(): void {\n\t\tif (this.destroyed) return\n\t\tthis.destroyed = true\n\n\t\tfor (const unsub of this.unsubscribers) {\n\t\t\tunsub()\n\t\t}\n\t\tthis.unsubscribers.length = 0\n\n\t\tthis.bridge?.destroy()\n\t}\n\n\tprivate attachListeners(): void {\n\t\tfor (const eventType of ALL_EVENT_TYPES) {\n\t\t\tconst unsub = this.emitter.on(eventType, (event: KoraEvent) => {\n\t\t\t\tthis.handleEvent(event)\n\t\t\t})\n\t\t\tthis.unsubscribers.push(unsub)\n\t\t}\n\t}\n\n\tprivate handleEvent(event: KoraEvent): void {\n\t\tif (this.paused || this.destroyed) return\n\n\t\tconst timestamped: TimestampedEvent = {\n\t\t\tid: this.nextId++,\n\t\t\tevent,\n\t\t\treceivedAt: Date.now(),\n\t\t}\n\n\t\tthis.buffer.push(timestamped)\n\t\tthis.bridge?.send(timestamped)\n\t}\n}\n","import type { KoraEvent, KoraEventType } from '@korajs/core'\n\n/** A KoraEvent wrapped with a reception timestamp and sequential ID */\nexport interface TimestampedEvent {\n\t/** Auto-incrementing sequential ID */\n\tid: number\n\t/** The original framework event */\n\tevent: KoraEvent\n\t/** Date.now() when the instrumenter captured the event */\n\treceivedAt: number\n}\n\n/** Event categories for filtering and grouping */\nexport type EventCategory = 'operation' | 'merge' | 'sync' | 'query' | 'connection'\n\n/** Maps each KoraEventType to its category */\nconst EVENT_TYPE_CATEGORIES: Record<KoraEventType, EventCategory> = {\n\t'operation:created': 'operation',\n\t'operation:applied': 'operation',\n\t'merge:started': 'merge',\n\t'merge:completed': 'merge',\n\t'merge:conflict': 'merge',\n\t'constraint:violated': 'merge',\n\t'sync:connected': 'sync',\n\t'sync:disconnected': 'sync',\n\t'sync:sent': 'sync',\n\t'sync:received': 'sync',\n\t'sync:acknowledged': 'sync',\n\t'query:subscribed': 'query',\n\t'query:invalidated': 'query',\n\t'query:executed': 'query',\n\t'connection:quality': 'connection',\n}\n\n/** Look up the category for a given event type */\nexport function eventTypeToCategory(type: KoraEventType): EventCategory {\n\treturn EVENT_TYPE_CATEGORIES[type]\n}\n\n/** All event categories */\nexport const EVENT_CATEGORIES = ['operation', 'merge', 'sync', 'query', 'connection'] as const\n\n/** Configuration for the Instrumenter */\nexport interface DevtoolsConfig {\n\t/** Max events in the ring buffer (default: 10000) */\n\tbufferSize?: number\n\t/** Enable message bridge for DevTools panel communication (default: true) */\n\tbridgeEnabled?: boolean\n\t/** Custom message channel name (default: 'kora-devtools') */\n\tchannelName?: string\n}\n\n/** Filter criteria for querying events */\nexport interface EventFilterCriteria {\n\t/** Filter by event categories */\n\tcategories?: EventCategory[]\n\t/** Filter by specific event types */\n\ttypes?: KoraEventType[]\n\t/** Filter by reception time range */\n\ttimeRange?: { start: number; end: number }\n\t/** Filter by collection name (extracted from operation events) */\n\tcollection?: string\n}\n\n/** Aggregated statistics computed from a set of events */\nexport interface EventStatistics {\n\ttotalEvents: number\n\teventsByCategory: Record<EventCategory, number>\n\teventsByType: Partial<Record<KoraEventType, number>>\n\tmergeConflicts: number\n\tconstraintViolations: number\n\tavgMergeDuration: number | null\n\tavgQueryDuration: number | null\n\tsyncOperationsSent: number\n\tsyncOperationsReceived: number\n}\n","import type { KoraEventType } from '@korajs/core'\nimport type { EventCategory, EventFilterCriteria, TimestampedEvent } from '../types'\nimport { eventTypeToCategory } from '../types'\n\n/**\n * Maps a KoraEventType to its EventCategory.\n * Re-exported from types for public API convenience.\n */\nexport function getEventCategory(type: KoraEventType): EventCategory {\n\treturn eventTypeToCategory(type)\n}\n\n/**\n * Extracts the collection name from an event, if present.\n * Only operation events and query:subscribed carry a collection field directly.\n * For other event types that embed operations, we inspect the nested operation.\n */\nfunction extractCollection(event: TimestampedEvent): string | null {\n\tconst e = event.event\n\tswitch (e.type) {\n\t\tcase 'operation:created':\n\t\tcase 'operation:applied':\n\t\t\treturn e.operation.collection\n\t\tcase 'merge:started':\n\t\t\treturn e.operationA.collection\n\t\tcase 'merge:completed':\n\t\tcase 'merge:conflict':\n\t\t\treturn e.trace.operationA.collection\n\t\tcase 'constraint:violated':\n\t\t\treturn e.trace.operationA.collection\n\t\tcase 'query:subscribed':\n\t\t\treturn e.collection\n\t\tcase 'query:invalidated':\n\t\t\treturn e.trigger.collection\n\t\tcase 'sync:sent':\n\t\t\treturn e.operations[0]?.collection ?? null\n\t\tcase 'sync:received':\n\t\t\treturn e.operations[0]?.collection ?? null\n\t\tdefault:\n\t\t\treturn null\n\t}\n}\n\n/**\n * Filters a list of timestamped events by the given criteria.\n * All criteria are combined with AND logic: an event must match all specified criteria.\n * Returns all events if no criteria are specified.\n */\nexport function filterEvents(\n\tevents: readonly TimestampedEvent[],\n\tcriteria: EventFilterCriteria,\n): readonly TimestampedEvent[] {\n\tconst { categories, types, timeRange, collection } = criteria\n\n\t// Fast path: no filters\n\tif (!categories && !types && !timeRange && !collection) {\n\t\treturn events\n\t}\n\n\t// Pre-compute the set of allowed types from categories for efficient lookup\n\tconst categorySet = categories ? new Set<EventCategory>(categories) : null\n\tconst typeSet = types ? new Set<KoraEventType>(types) : null\n\n\treturn events.filter((event) => {\n\t\t// Category filter\n\t\tif (categorySet) {\n\t\t\tconst cat = eventTypeToCategory(event.event.type)\n\t\t\tif (!categorySet.has(cat)) return false\n\t\t}\n\n\t\t// Specific type filter\n\t\tif (typeSet) {\n\t\t\tif (!typeSet.has(event.event.type)) return false\n\t\t}\n\n\t\t// Time range filter (on receivedAt)\n\t\tif (timeRange) {\n\t\t\tif (event.receivedAt < timeRange.start || event.receivedAt > timeRange.end) {\n\t\t\t\treturn false\n\t\t\t}\n\t\t}\n\n\t\t// Collection filter\n\t\tif (collection) {\n\t\t\tconst eventCollection = extractCollection(event)\n\t\t\tif (eventCollection !== collection) return false\n\t\t}\n\n\t\treturn true\n\t})\n}\n","import type { KoraEventType } from '@korajs/core'\nimport type { EventCategory, EventStatistics, TimestampedEvent } from '../types'\nimport { EVENT_CATEGORIES, eventTypeToCategory } from '../types'\n\n/**\n * Computes aggregate statistics from a collection of timestamped events.\n * Processes the event list in a single pass for efficiency.\n */\nexport function computeStatistics(events: readonly TimestampedEvent[]): EventStatistics {\n\tconst eventsByCategory: Record<EventCategory, number> = {\n\t\toperation: 0,\n\t\tmerge: 0,\n\t\tsync: 0,\n\t\tquery: 0,\n\t\tconnection: 0,\n\t}\n\tconst eventsByType: Partial<Record<KoraEventType, number>> = {}\n\n\tlet mergeConflicts = 0\n\tlet constraintViolations = 0\n\tlet mergeDurationSum = 0\n\tlet mergeDurationCount = 0\n\tlet queryDurationSum = 0\n\tlet queryDurationCount = 0\n\tlet syncOperationsSent = 0\n\tlet syncOperationsReceived = 0\n\n\tfor (const timestamped of events) {\n\t\tconst e = timestamped.event\n\n\t\t// Category count\n\t\tconst category = eventTypeToCategory(e.type)\n\t\teventsByCategory[category]++\n\n\t\t// Type count\n\t\teventsByType[e.type] = (eventsByType[e.type] ?? 0) + 1\n\n\t\t// Type-specific aggregations\n\t\tswitch (e.type) {\n\t\t\tcase 'merge:completed':\n\t\t\t\tmergeDurationSum += e.trace.duration\n\t\t\t\tmergeDurationCount++\n\t\t\t\tbreak\n\t\t\tcase 'merge:conflict':\n\t\t\t\tmergeConflicts++\n\t\t\t\tmergeDurationSum += e.trace.duration\n\t\t\t\tmergeDurationCount++\n\t\t\t\tbreak\n\t\t\tcase 'constraint:violated':\n\t\t\t\tconstraintViolations++\n\t\t\t\tbreak\n\t\t\tcase 'query:executed':\n\t\t\t\tqueryDurationSum += e.duration\n\t\t\t\tqueryDurationCount++\n\t\t\t\tbreak\n\t\t\tcase 'sync:sent':\n\t\t\t\tsyncOperationsSent += e.batchSize\n\t\t\t\tbreak\n\t\t\tcase 'sync:received':\n\t\t\t\tsyncOperationsReceived += e.batchSize\n\t\t\t\tbreak\n\t\t}\n\t}\n\n\treturn {\n\t\ttotalEvents: events.length,\n\t\teventsByCategory,\n\t\teventsByType,\n\t\tmergeConflicts,\n\t\tconstraintViolations,\n\t\tavgMergeDuration: mergeDurationCount > 0 ? mergeDurationSum / mergeDurationCount : null,\n\t\tavgQueryDuration: queryDurationCount > 0 ? queryDurationSum / queryDurationCount : null,\n\t\tsyncOperationsSent,\n\t\tsyncOperationsReceived,\n\t}\n}\n"],"mappings":";;;;;;;;;AAEA,IAAM,kBAAkB;AAgBjB,IAAM,gBAAN,MAAoB;AAAA,EACT;AAAA,EACA,YAAoD,oBAAI,IAAI;AAAA,EAC5D;AAAA,EACT,YAAY;AAAA,EAEpB,YAAY,cAAsB,iBAAiB;AAClD,SAAK,cAAc;AAEnB,QAAI,OAAO,WAAW,aAAa;AAClC,WAAK,iBAAiB;AACtB;AAAA,IACD;AAGA,SAAK,iBAAiB,CAAC,UAAwB;AAC9C,UAAI,KAAK,UAAW;AACpB,YAAM,OAAO,MAAM;AACnB,UAAI,CAAC,QAAQ,KAAK,WAAW,KAAK,YAAa;AAE/C,iBAAW,YAAY,KAAK,WAAW;AACtC,iBAAS,KAAK,OAA2B;AAAA,MAC1C;AAAA,IACD;AAEA,WAAO,iBAAiB,WAAW,KAAK,cAAc;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,OAA+B;AACnC,QAAI,KAAK,aAAa,OAAO,WAAW,YAAa;AAErD,UAAM,UAAyB;AAAA,MAC9B,QAAQ,KAAK;AAAA,MACb,SAAS;AAAA,IACV;AACA,WAAO,YAAY,SAAS,GAAG;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAU,UAAyD;AAClE,QAAI,KAAK,UAAW,QAAO,MAAM;AAAA,IAAC;AAElC,SAAK,UAAU,IAAI,QAAQ;AAC3B,WAAO,MAAM;AACZ,WAAK,UAAU,OAAO,QAAQ;AAAA,IAC/B;AAAA,EACD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAgB;AACf,QAAI,KAAK,UAAW;AACpB,SAAK,YAAY;AACjB,SAAK,UAAU,MAAM;AAErB,QAAI,KAAK,kBAAkB,OAAO,WAAW,aAAa;AACzD,aAAO,oBAAoB,WAAW,KAAK,cAAc;AAAA,IAC1D;AAAA,EACD;AACD;;;ACnFA,IAAM,mBAAmB;AAOlB,IAAM,cAAN,MAAkB;AAAA,EACP;AAAA,EACA;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,eAAe;AAAA,EAEvB,YAAY,WAAmB,kBAAkB;AAChD,QAAI,WAAW,GAAG;AACjB,YAAM,IAAI,MAAM,yCAAyC;AAAA,IAC1D;AACA,SAAK,YAAY;AACjB,SAAK,SAAS,IAAI,MAAoC,QAAQ;AAAA,EAC/D;AAAA;AAAA,EAGA,IAAI,WAAmB;AACtB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA,EAGA,IAAI,OAAe;AAClB,WAAO,KAAK,IAAI,KAAK,cAAc,KAAK,SAAS;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,OAA+B;AACnC,SAAK,OAAO,KAAK,IAAI,IAAI;AACzB,SAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;AACnC,SAAK;AAAA,EACN;AAAA;AAAA;AAAA;AAAA,EAKA,SAAsC;AACrC,QAAI,KAAK,iBAAiB,EAAG,QAAO,CAAC;AAErC,UAAM,SAA6B,CAAC;AAEpC,QAAI,KAAK,gBAAgB,KAAK,WAAW;AAExC,eAAS,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;AACnC,cAAM,QAAQ,KAAK,OAAO,CAAC;AAC3B,YAAI,MAAO,QAAO,KAAK,KAAK;AAAA,MAC7B;AAAA,IACD,OAAO;AAEN,eAAS,IAAI,GAAG,IAAI,KAAK,WAAW,KAAK;AACxC,cAAM,SAAS,KAAK,OAAO,KAAK,KAAK;AACrC,cAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,YAAI,MAAO,QAAO,KAAK,KAAK;AAAA,MAC7B;AAAA,IACD;AAEA,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA,EAKA,SAAS,OAAe,KAA0C;AACjE,WAAO,KAAK,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,SAAS,EAAE,MAAM,GAAG;AAAA,EAChE;AAAA;AAAA;AAAA;AAAA,EAKA,UAAU,MAAkD;AAC3D,WAAO,KAAK,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,SAAS,IAAI;AAAA,EACzD;AAAA;AAAA,EAGA,QAAc;AACb,SAAK,OAAO,KAAK,MAAS;AAC1B,SAAK,OAAO;AACZ,SAAK,eAAe;AAAA,EACrB;AACD;;;ACvFA,IAAM,sBAAsB;AAC5B,IAAM,uBAAuB;AAG7B,IAAM,kBAA4C;AAAA,EACjD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD;AAiBO,IAAM,eAAN,MAAmB;AAAA,EAQzB,YACkB,SACjB,QACC;AAFgB;AAGjB,UAAM,aAAa,QAAQ,cAAc;AACzC,UAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,UAAM,cAAc,QAAQ,eAAe;AAE3C,SAAK,SAAS,IAAI,YAAY,UAAU;AACxC,SAAK,SAAS,gBAAgB,IAAI,cAAc,WAAW,IAAI;AAE/D,SAAK,gBAAgB;AAAA,EACtB;AAAA,EAXkB;AAAA,EARD;AAAA,EACA;AAAA,EACA,gBAAmC,CAAC;AAAA,EAC7C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,YAAY;AAAA;AAAA,EAiBpB,YAAyB;AACxB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA,EAGA,YAAkC;AACjC,WAAO,KAAK;AAAA,EACb;AAAA;AAAA,EAGA,QAAc;AACb,SAAK,SAAS;AAAA,EACf;AAAA;AAAA,EAGA,SAAe;AACd,SAAK,SAAS;AAAA,EACf;AAAA;AAAA,EAGA,WAAoB;AACnB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAgB;AACf,QAAI,KAAK,UAAW;AACpB,SAAK,YAAY;AAEjB,eAAW,SAAS,KAAK,eAAe;AACvC,YAAM;AAAA,IACP;AACA,SAAK,cAAc,SAAS;AAE5B,SAAK,QAAQ,QAAQ;AAAA,EACtB;AAAA,EAEQ,kBAAwB;AAC/B,eAAW,aAAa,iBAAiB;AACxC,YAAM,QAAQ,KAAK,QAAQ,GAAG,WAAW,CAAC,UAAqB;AAC9D,aAAK,YAAY,KAAK;AAAA,MACvB,CAAC;AACD,WAAK,cAAc,KAAK,KAAK;AAAA,IAC9B;AAAA,EACD;AAAA,EAEQ,YAAY,OAAwB;AAC3C,QAAI,KAAK,UAAU,KAAK,UAAW;AAEnC,UAAM,cAAgC;AAAA,MACrC,IAAI,KAAK;AAAA,MACT;AAAA,MACA,YAAY,KAAK,IAAI;AAAA,IACtB;AAEA,SAAK,OAAO,KAAK,WAAW;AAC5B,SAAK,QAAQ,KAAK,WAAW;AAAA,EAC9B;AACD;;;AC9GA,IAAM,wBAA8D;AAAA,EACnE,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,uBAAuB;AAAA,EACvB,kBAAkB;AAAA,EAClB,qBAAqB;AAAA,EACrB,aAAa;AAAA,EACb,iBAAiB;AAAA,EACjB,qBAAqB;AAAA,EACrB,oBAAoB;AAAA,EACpB,qBAAqB;AAAA,EACrB,kBAAkB;AAAA,EAClB,sBAAsB;AACvB;AAGO,SAAS,oBAAoB,MAAoC;AACvE,SAAO,sBAAsB,IAAI;AAClC;;;AC7BO,SAAS,iBAAiB,MAAoC;AACpE,SAAO,oBAAoB,IAAI;AAChC;AAOA,SAAS,kBAAkB,OAAwC;AAClE,QAAM,IAAI,MAAM;AAChB,UAAQ,EAAE,MAAM;AAAA,IACf,KAAK;AAAA,IACL,KAAK;AACJ,aAAO,EAAE,UAAU;AAAA,IACpB,KAAK;AACJ,aAAO,EAAE,WAAW;AAAA,IACrB,KAAK;AAAA,IACL,KAAK;AACJ,aAAO,EAAE,MAAM,WAAW;AAAA,IAC3B,KAAK;AACJ,aAAO,EAAE,MAAM,WAAW;AAAA,IAC3B,KAAK;AACJ,aAAO,EAAE;AAAA,IACV,KAAK;AACJ,aAAO,EAAE,QAAQ;AAAA,IAClB,KAAK;AACJ,aAAO,EAAE,WAAW,CAAC,GAAG,cAAc;AAAA,IACvC,KAAK;AACJ,aAAO,EAAE,WAAW,CAAC,GAAG,cAAc;AAAA,IACvC;AACC,aAAO;AAAA,EACT;AACD;AAOO,SAAS,aACf,QACA,UAC8B;AAC9B,QAAM,EAAE,YAAY,OAAO,WAAW,WAAW,IAAI;AAGrD,MAAI,CAAC,cAAc,CAAC,SAAS,CAAC,aAAa,CAAC,YAAY;AACvD,WAAO;AAAA,EACR;AAGA,QAAM,cAAc,aAAa,IAAI,IAAmB,UAAU,IAAI;AACtE,QAAM,UAAU,QAAQ,IAAI,IAAmB,KAAK,IAAI;AAExD,SAAO,OAAO,OAAO,CAAC,UAAU;AAE/B,QAAI,aAAa;AAChB,YAAM,MAAM,oBAAoB,MAAM,MAAM,IAAI;AAChD,UAAI,CAAC,YAAY,IAAI,GAAG,EAAG,QAAO;AAAA,IACnC;AAGA,QAAI,SAAS;AACZ,UAAI,CAAC,QAAQ,IAAI,MAAM,MAAM,IAAI,EAAG,QAAO;AAAA,IAC5C;AAGA,QAAI,WAAW;AACd,UAAI,MAAM,aAAa,UAAU,SAAS,MAAM,aAAa,UAAU,KAAK;AAC3E,eAAO;AAAA,MACR;AAAA,IACD;AAGA,QAAI,YAAY;AACf,YAAM,kBAAkB,kBAAkB,KAAK;AAC/C,UAAI,oBAAoB,WAAY,QAAO;AAAA,IAC5C;AAEA,WAAO;AAAA,EACR,CAAC;AACF;;;AClFO,SAAS,kBAAkB,QAAsD;AACvF,QAAM,mBAAkD;AAAA,IACvD,WAAW;AAAA,IACX,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,YAAY;AAAA,EACb;AACA,QAAM,eAAuD,CAAC;AAE9D,MAAI,iBAAiB;AACrB,MAAI,uBAAuB;AAC3B,MAAI,mBAAmB;AACvB,MAAI,qBAAqB;AACzB,MAAI,mBAAmB;AACvB,MAAI,qBAAqB;AACzB,MAAI,qBAAqB;AACzB,MAAI,yBAAyB;AAE7B,aAAW,eAAe,QAAQ;AACjC,UAAM,IAAI,YAAY;AAGtB,UAAM,WAAW,oBAAoB,EAAE,IAAI;AAC3C,qBAAiB,QAAQ;AAGzB,iBAAa,EAAE,IAAI,KAAK,aAAa,EAAE,IAAI,KAAK,KAAK;AAGrD,YAAQ,EAAE,MAAM;AAAA,MACf,KAAK;AACJ,4BAAoB,EAAE,MAAM;AAC5B;AACA;AAAA,MACD,KAAK;AACJ;AACA,4BAAoB,EAAE,MAAM;AAC5B;AACA;AAAA,MACD,KAAK;AACJ;AACA;AAAA,MACD,KAAK;AACJ,4BAAoB,EAAE;AACtB;AACA;AAAA,MACD,KAAK;AACJ,8BAAsB,EAAE;AACxB;AAAA,MACD,KAAK;AACJ,kCAA0B,EAAE;AAC5B;AAAA,IACF;AAAA,EACD;AAEA,SAAO;AAAA,IACN,aAAa,OAAO;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,kBAAkB,qBAAqB,IAAI,mBAAmB,qBAAqB;AAAA,IACnF,kBAAkB,qBAAqB,IAAI,mBAAmB,qBAAqB;AAAA,IACnF;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@korajs/devtools",
+  "version": "0.1.0",
+  "description": "Kora.js devtools package",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@korajs/core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "tsup": "^8.3.6",
+    "vitest": "^3.0.4"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup && node ./scripts/build-extension-assets.mjs",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "clean": "rm -rf dist .turbo coverage"
+  }
+}