@everystate/perf 1.0.2 → 1.0.3

package/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @everystate/perf
+ *
+ * Non-invasive performance monitoring for EveryState stores.
+ */
+
+import type { EveryStateStore } from '@everystate/core';
+
+export interface PerfMonitorOptions {
+  /** Maximum timeline events to keep (default: 10000) */
+  maxEvents?: number;
+  /** Track values in timeline events (default: false) */
+  trackValues?: boolean;
+  /** Track get() calls (default: false) */
+  trackGets?: boolean;
+}
+
+export interface PathStat {
+  path: string;
+  sets: number;
+  gets: number;
+  fires: number;
+  avgSetMs: number;
+  peakSetMs: number;
+  subscriberCount: number;
+}
+
+export interface HotListener {
+  path: string;
+  fires: number;
+  firesPerSec: number;
+}
+
+export interface ActiveSub {
+  id: string;
+  path: string;
+  ts: number;
+}
+
+export interface TimelineEvent {
+  type: 'set' | 'get' | 'fire' | 'subscribe' | 'unsubscribe' | 'batch' | 'setMany';
+  path?: string;
+  paths?: string[];
+  dur?: number;
+  ts: number;
+  subId?: string;
+  _seq: number;
+}
+
+export interface PerfReport {
+  sessionId: string;
+  elapsedMs: number;
+  totalEvents: number;
+  dropped: number;
+  summary: {
+    totalSets: number;
+    totalGets: number;
+    totalFires: number;
+    uniquePaths: number;
+    totalSubscribes: number;
+    totalUnsubscribes: number;
+    activeSubscribers: number;
+    setsPerSec: number;
+  };
+  batches: {
+    count: number;
+    totalPaths: number;
+    totalCoalesced: number;
+  };
+  hotPaths: PathStat[];
+  hotListeners: HotListener[];
+  activeSubs: ActiveSub[];
+  timeline: TimelineEvent[];
+}
+
+export interface PerfMonitor {
+  /** Generate a performance report snapshot */
+  report(): PerfReport;
+  /** Download the report as a JSON file */
+  download(filename?: string): PerfReport;
+  /** Reset all collected stats */
+  reset(): void;
+  /** Unwrap the store (restore original methods) */
+  destroy(): void;
+  /** Raw timeline array */
+  readonly timeline: TimelineEvent[];
+  /** Raw per-path stats map */
+  readonly pathStats: Map<string, any>;
+  /** Session identifier */
+  readonly sessionId: string;
+  /** Reference to the wrapped store (used by State Tree tab) */
+  readonly store: EveryStateStore;
+}
+
+/**
+ * Create a performance monitor that wraps an EveryState store.
+ * Must be called BEFORE any subscriptions for full visibility.
+ */
+export function createPerfMonitor(store: EveryStateStore, options?: PerfMonitorOptions): PerfMonitor;
+
+/**
+ * Mount a floating overlay in the browser that displays live perf stats.
+ * Uses Shadow DOM for style encapsulation.
+ * @returns Unmount function
+ */
+export function mountOverlay(monitor: PerfMonitor, container: HTMLElement): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystate/perf",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "EveryState Performance Monitor: Non-invasive performance monitoring with method wrapping, path heatmaps, timeline recording, browser overlay",
   "type": "module",
   "main": "index.js",
@@ -31,9 +31,8 @@
     "test": "node self-test.js"
   },
   "files": [
-    "index.js",
-    "perfMonitor.js",
-    "overlay.js",
-    "README.md"
+    "*.js",
+    "*.d.ts",
+    "*.md"
   ]
 }

package/self-test.js

@@ -0,0 +1,307 @@
+/**
+ * @everystate/perf: self-test.js
+ *
+ * Zero-dependency self-test. Runs on postinstall.
+ * Tests the perfMonitor in Node (no DOM, no overlay).
+ */
+
+import { createPerfMonitor } from './perfMonitor.js';
+
+// Minimal EveryState mock (matches the API surface we wrap)
+function createMockStore() {
+  const state = {};
+  const listeners = new Map();
+
+  const store = {
+    get(path) {
+      const parts = path.split('.');
+      let cur = state;
+      for (const p of parts) {
+        if (cur == null) return undefined;
+        cur = cur[p];
+      }
+      return cur;
+    },
+    set(path, value) {
+      const parts = path.split('.');
+      const key = parts.pop();
+      let cur = state;
+      for (const p of parts) {
+        if (!cur[p]) cur[p] = {};
+        cur = cur[p];
+      }
+      cur[key] = value;
+
+      // Notify exact listeners
+      const exact = listeners.get(path);
+      if (exact) exact.forEach(cb => cb(value, { path, value }));
+
+      // Notify wildcard *
+      const global = listeners.get('*');
+      if (global) global.forEach(cb => cb({ path, value }));
+
+      return value;
+    },
+    subscribe(path, handler) {
+      if (!listeners.has(path)) listeners.set(path, new Set());
+      listeners.get(path).add(handler);
+      return () => {
+        const set = listeners.get(path);
+        if (set) {
+          set.delete(handler);
+          if (set.size === 0) listeners.delete(path);
+        }
+      };
+    },
+    batch(fn) {
+      fn();
+    },
+    setMany(entries) {
+      if (entries && typeof entries === 'object' && !Array.isArray(entries) && !(entries instanceof Map)) {
+        for (const [p, v] of Object.entries(entries)) {
+          store.set(p, v);
+        }
+      }
+    },
+  };
+  return store;
+}
+
+let passed = 0;
+let failed = 0;
+
+function assert(label, condition) {
+  if (condition) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+}
+
+// == Tests ================================================================
+
+console.log('\n1. createPerfMonitor wraps store methods');
+{
+  const store = createMockStore();
+  const origSet = store.set;
+  const origSubscribe = store.subscribe;
+  const origBatch = store.batch;
+  const origSetMany = store.setMany;
+
+  const perf = createPerfMonitor(store);
+
+  assert('set is wrapped', store.set !== origSet);
+  assert('subscribe is wrapped', store.subscribe !== origSubscribe);
+  assert('batch is wrapped', store.batch !== origBatch);
+  assert('setMany is wrapped', store.setMany !== origSetMany);
+
+  perf.destroy();
+  assert('set is restored after destroy', store.set === origSet);
+  assert('subscribe is restored after destroy', store.subscribe === origSubscribe);
+}
+
+console.log('\n2. tracks set events');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.set('count', 1);
+  store.set('count', 2);
+  store.set('name', 'Alice');
+
+  const r = perf.report();
+  assert('totalSets = 3', r.summary.totalSets === 3);
+  assert('uniquePaths = 2', r.summary.uniquePaths === 2);
+  assert('hotPaths[0] is count (2 sets)', r.hotPaths[0].path === 'count' && r.hotPaths[0].sets === 2);
+  assert('hotPaths[1] is name (1 set)', r.hotPaths[1].path === 'name' && r.hotPaths[1].sets === 1);
+
+  perf.destroy();
+}
+
+console.log('\n3. tracks subscribe and fire events');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  let fires = 0;
+  const unsub = store.subscribe('count', () => { fires++; });
+
+  store.set('count', 1);
+  store.set('count', 2);
+
+  const r = perf.report();
+  assert('totalSubscribes = 1', r.summary.totalSubscribes === 1);
+  assert('activeSubscribers = 1', r.summary.activeSubscribers === 1);
+  assert('totalFires = 2', r.summary.totalFires === 2);
+  assert('handler actually fired', fires === 2);
+
+  unsub();
+  const r2 = perf.report();
+  assert('totalUnsubscribes = 1 after unsub', r2.summary.totalUnsubscribes === 1);
+  assert('activeSubscribers = 0 after unsub', r2.summary.activeSubscribers === 0);
+
+  perf.destroy();
+}
+
+console.log('\n4. tracks batch events');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.batch(() => {
+    store.set('a', 1);
+    store.set('b', 2);
+    store.set('a', 3); // duplicate path
+  });
+
+  const r = perf.report();
+  assert('batch count = 1', r.batches.count === 1);
+  assert('batch totalPaths = 3', r.batches.totalPaths === 3);
+  assert('batch coalesced = 1 (duplicate a)', r.batches.totalCoalesced === 1);
+
+  perf.destroy();
+}
+
+console.log('\n5. tracks setMany events');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.setMany({ x: 1, y: 2, z: 3 });
+
+  const r = perf.report();
+  const setManyEvents = r.timeline.filter(e => e.type === 'setMany');
+  assert('setMany event recorded', setManyEvents.length === 1);
+  assert('setMany pathCount = 3', setManyEvents[0].pathCount === 3);
+
+  perf.destroy();
+}
+
+console.log('\n6. report structure');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.set('x', 1);
+
+  const r = perf.report();
+  assert('has sessionId', typeof r.sessionId === 'string' && r.sessionId.length > 0);
+  assert('has elapsedMs', typeof r.elapsedMs === 'number');
+  assert('has summary', typeof r.summary === 'object');
+  assert('has batches', typeof r.batches === 'object');
+  assert('has hotPaths', Array.isArray(r.hotPaths));
+  assert('has hotListeners', Array.isArray(r.hotListeners));
+  assert('has activeSubs', Array.isArray(r.activeSubs));
+  assert('has timeline', Array.isArray(r.timeline));
+
+  perf.destroy();
+}
+
+console.log('\n7. reset clears all data');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.set('x', 1);
+  store.set('x', 2);
+
+  perf.reset();
+  const r = perf.report();
+  assert('totalEvents = 0 after reset', r.totalEvents === 0);
+  assert('totalSets = 0 after reset', r.summary.totalSets === 0);
+  assert('uniquePaths = 0 after reset', r.summary.uniquePaths === 0);
+  assert('timeline empty after reset', r.timeline.length === 0);
+
+  perf.destroy();
+}
+
+console.log('\n8. ring buffer drops old events');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store, { maxEvents: 5 });
+
+  for (let i = 0; i < 10; i++) {
+    store.set('x', i);
+  }
+
+  const r = perf.report();
+  assert('totalEvents = 10', r.totalEvents === 10);
+  assert('timeline length capped at 5', perf.timeline.length === 5);
+  assert('dropped = 5', r.dropped === 5);
+  assert('oldest event is seq 5', perf.timeline[0]._seq === 5);
+
+  perf.destroy();
+}
+
+console.log('\n9. trackValues option');
+{
+  const store = createMockStore();
+  const perfNoVals = createPerfMonitor(store);
+  store.set('x', 42);
+  const evtNoVal = perfNoVals.timeline.find(e => e.type === 'set');
+  assert('value not tracked by default', evtNoVal.value === undefined);
+  perfNoVals.destroy();
+
+  const store2 = createMockStore();
+  const perfWithVals = createPerfMonitor(store2, { trackValues: true });
+  store2.set('x', 42);
+  const evtWithVal = perfWithVals.timeline.find(e => e.type === 'set');
+  assert('value tracked when enabled', evtWithVal.value === 42);
+  perfWithVals.destroy();
+}
+
+console.log('\n10. trackGets option');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store, { trackGets: true });
+  store.set('x', 1);
+  store.get('x');
+  store.get('x');
+
+  const r = perf.report();
+  const xStats = r.hotPaths.find(p => p.path === 'x');
+  assert('gets tracked when enabled', xStats.gets === 2);
+
+  perf.destroy();
+}
+
+console.log('\n11. per-path timing');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+
+  store.set('a', 1);
+  store.set('a', 2);
+  store.set('a', 3);
+
+  const r = perf.report();
+  const aStats = r.hotPaths.find(p => p.path === 'a');
+  assert('avgSetMs is a number', typeof aStats.avgSetMs === 'number');
+  assert('peakSetMs >= avgSetMs', aStats.peakSetMs >= aStats.avgSetMs);
+
+  perf.destroy();
+}
+
+console.log('\n12. download returns report object');
+{
+  const store = createMockStore();
+  const perf = createPerfMonitor(store);
+  store.set('x', 1);
+
+  // In Node there's no document, so download just returns data
+  const data = perf.download('test.json');
+  assert('download returns data', data !== undefined);
+  assert('download data has sessionId', typeof data.sessionId === 'string');
+  assert('download data has full timeline', Array.isArray(data.timeline));
+
+  perf.destroy();
+}
+
+// == Summary ==============================================================
+
+console.log(`\n@everystate/perf v1.0.0 self-test`);
+console.log(`✓ ${passed} assertions passed${failed ? `, ✗ ${failed} failed` : ''}\n`);
+
+if (failed > 0) process.exit(1);