@korajs/devtools 0.1.0

package/dist/index.cjs

@@ -0,0 +1,662 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  EventBuffer: () => EventBuffer,
+  Instrumenter: () => Instrumenter,
+  MessageBridge: () => MessageBridge,
+  PortRouter: () => PortRouter,
+  buildPanelModel: () => buildPanelModel,
+  computeStatistics: () => computeStatistics,
+  filterEvents: () => filterEvents,
+  getEventCategory: () => getEventCategory,
+  renderDevtoolsPanel: () => renderDevtoolsPanel
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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
+  };
+}
+
+// src/ui/panel-state.ts
+function buildPanelModel(events) {
+  const timeline = events.map((entry) => ({
+    id: entry.id,
+    type: entry.event.type,
+    label: timelineLabel(entry.event),
+    color: timelineColor(entry.event.type),
+    receivedAt: entry.receivedAt,
+    dependsOn: extractCausalDependencies(entry.event)
+  }));
+  const conflicts = events.flatMap((entry) => {
+    if (entry.event.type !== "merge:completed" && entry.event.type !== "merge:conflict") {
+      return [];
+    }
+    const trace = entry.event.trace;
+    return [
+      {
+        id: entry.id,
+        timestamp: entry.receivedAt,
+        collection: trace.operationA.collection,
+        field: trace.field,
+        strategy: trace.strategy,
+        tier: trace.tier,
+        inputA: trace.inputA,
+        inputB: trace.inputB,
+        output: trace.output,
+        constraintViolated: trace.constraintViolated
+      }
+    ];
+  });
+  const operations = events.map((entry) => {
+    const operation = extractOperation(entry.event);
+    if (!operation) return null;
+    return {
+      id: entry.id,
+      timestamp: entry.receivedAt,
+      operationId: operation.id,
+      collection: operation.collection,
+      recordId: operation.recordId,
+      opType: operation.type,
+      data: operation.data,
+      causalDeps: operation.causalDeps,
+      nodeId: operation.nodeId,
+      sequenceNumber: operation.sequenceNumber
+    };
+  }).filter((item) => item !== null);
+  const network = buildNetworkStatus(events, operations);
+  return {
+    timeline,
+    conflicts,
+    operations,
+    network
+  };
+}
+function buildNetworkStatus(events, operations) {
+  let connected = false;
+  let quality = null;
+  let pendingAcks = 0;
+  let lastSyncAt = null;
+  let sentOps = 0;
+  let receivedOps = 0;
+  for (const entry of events) {
+    switch (entry.event.type) {
+      case "sync:connected":
+        connected = true;
+        lastSyncAt = entry.receivedAt;
+        break;
+      case "sync:disconnected":
+        connected = false;
+        break;
+      case "connection:quality":
+        quality = entry.event.quality;
+        break;
+      case "sync:sent":
+        sentOps += entry.event.operations.length;
+        pendingAcks += entry.event.operations.length;
+        lastSyncAt = entry.receivedAt;
+        break;
+      case "sync:received":
+        receivedOps += entry.event.operations.length;
+        lastSyncAt = entry.receivedAt;
+        break;
+      case "sync:acknowledged":
+        pendingAcks = Math.max(0, pendingAcks - 1);
+        lastSyncAt = entry.receivedAt;
+        break;
+    }
+  }
+  const vector = /* @__PURE__ */ new Map();
+  for (const operation of operations) {
+    const current = vector.get(operation.nodeId) ?? 0;
+    if (operation.sequenceNumber > current) {
+      vector.set(operation.nodeId, operation.sequenceNumber);
+    }
+  }
+  return {
+    connected,
+    quality,
+    pendingAcks,
+    lastSyncAt,
+    sentOps,
+    receivedOps,
+    versionVector: [...vector.entries()].map(([nodeId, sequenceNumber]) => ({ nodeId, sequenceNumber })).sort((left, right) => left.nodeId.localeCompare(right.nodeId))
+  };
+}
+function timelineLabel(event) {
+  switch (event.type) {
+    case "operation:created":
+    case "operation:applied":
+      return `${event.operation.type} ${event.operation.collection}/${event.operation.recordId}`;
+    case "merge:started":
+      return `merge start ${event.operationA.collection}`;
+    case "merge:completed":
+      return `merge complete ${event.trace.field}`;
+    case "merge:conflict":
+      return `merge conflict ${event.trace.field}`;
+    case "constraint:violated":
+      return `constraint ${event.constraint}`;
+    case "sync:connected":
+      return `sync connected ${event.nodeId}`;
+    case "sync:disconnected":
+      return `sync disconnected`;
+    case "sync:sent":
+      return `sync sent ${event.batchSize}`;
+    case "sync:received":
+      return `sync received ${event.batchSize}`;
+    case "sync:acknowledged":
+      return `sync ack ${event.sequenceNumber}`;
+    case "query:subscribed":
+      return `query subscribed ${event.collection}`;
+    case "query:invalidated":
+      return `query invalidated ${event.queryId}`;
+    case "query:executed":
+      return `query executed ${event.queryId}`;
+    case "connection:quality":
+      return `connection ${event.quality}`;
+  }
+}
+function timelineColor(type) {
+  if (type.startsWith("operation:")) return "#22c55e";
+  if (type.startsWith("sync:")) return "#a855f7";
+  if (type.startsWith("merge:") || type.startsWith("constraint:")) return "#f59e0b";
+  if (type.startsWith("query:")) return "#0ea5e9";
+  return "#64748b";
+}
+function extractCausalDependencies(event) {
+  const operation = extractOperation(event);
+  return operation?.causalDeps ?? [];
+}
+function extractOperation(event) {
+  switch (event.type) {
+    case "operation:created":
+    case "operation:applied":
+      return event.operation;
+    case "query:invalidated":
+      return event.trigger;
+    default:
+      return null;
+  }
+}
+
+// src/ui/panel.ts
+function renderDevtoolsPanel(target, events) {
+  const model = buildPanelModel(events);
+  target.innerHTML = [
+    '<section data-panel="timeline"><h2>Sync Timeline</h2>',
+    `<p>Total events: ${model.timeline.length}</p>`,
+    "<ul>",
+    ...model.timeline.slice(-20).map(
+      (item) => `<li><span style="color:${item.color}">${item.type}</span> \xB7 ${escapeHtml(item.label)}</li>`
+    ),
+    "</ul></section>",
+    '<section data-panel="conflicts"><h2>Conflict Inspector</h2>',
+    `<p>Conflicts: ${model.conflicts.length}</p>`,
+    "<ul>",
+    ...model.conflicts.slice(-20).map(
+      (item) => `<li>${escapeHtml(item.collection)}.${escapeHtml(item.field)} \xB7 ${escapeHtml(item.strategy)} \xB7 tier ${item.tier}</li>`
+    ),
+    "</ul></section>",
+    '<section data-panel="operations"><h2>Operation Log</h2>',
+    `<p>Operations: ${model.operations.length}</p>`,
+    "<ul>",
+    ...model.operations.slice(-20).map(
+      (item) => `<li>${escapeHtml(item.opType)} ${escapeHtml(item.collection)}/${escapeHtml(item.recordId)} (${escapeHtml(item.operationId)})</li>`
+    ),
+    "</ul></section>",
+    '<section data-panel="network"><h2>Network Status</h2>',
+    `<p>Connected: ${model.network.connected ? "yes" : "no"}</p>`,
+    `<p>Pending ACKs: ${model.network.pendingAcks}</p>`,
+    `<p>Sent ops: ${model.network.sentOps}</p>`,
+    `<p>Received ops: ${model.network.receivedOps}</p>`,
+    "</section>"
+  ].join("");
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+// src/extension/port-router.ts
+var PortRouter = class {
+  panelClients = /* @__PURE__ */ new Map();
+  contentClients = /* @__PURE__ */ new Map();
+  handleConnection(port) {
+    if (port.name === "kora-panel") {
+      this.attachPanel(port);
+      return;
+    }
+    if (port.name === "kora-content") {
+      this.attachContent(port);
+    }
+  }
+  attachPanel(port) {
+    port.onMessage.addListener((message) => {
+      if (!isPanelInitMessage(message)) return;
+      this.panelClients.set(message.tabId, { tabId: message.tabId, port });
+    });
+    port.onDisconnect.addListener(() => {
+      for (const [tabId, client] of this.panelClients) {
+        if (client.port === port) {
+          this.panelClients.delete(tabId);
+        }
+      }
+    });
+  }
+  attachContent(port) {
+    const tabId = port.sender?.tab?.id;
+    if (typeof tabId !== "number") {
+      return;
+    }
+    this.contentClients.set(tabId, port);
+    port.onMessage.addListener((message) => {
+      if (!isContentEventMessage(message)) return;
+      const panel = this.panelClients.get(tabId);
+      if (!panel) return;
+      panel.port.postMessage({ type: "kora-event", payload: message.payload });
+    });
+    port.onDisconnect.addListener(() => {
+      this.contentClients.delete(tabId);
+    });
+  }
+};
+function isPanelInitMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.type === "panel-init" && typeof record.tabId === "number";
+}
+function isContentEventMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.type === "kora-event" && "payload" in record;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EventBuffer,
+  Instrumenter,
+  MessageBridge,
+  PortRouter,
+  buildPanelModel,
+  computeStatistics,
+  filterEvents,
+  getEventCategory,
+  renderDevtoolsPanel
+});
+//# sourceMappingURL=index.cjs.map