@praxisjs/devtools 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/devtools",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,11 +12,11 @@
   },
   "dependencies": {
     "@unocss/reset": "^66.6.2",
-    "@praxisjs/core": "0.4.0",
-    "@praxisjs/decorators": "0.4.1",
-    "@praxisjs/jsx": "0.3.1",
-    "@praxisjs/runtime": "0.2.2",
-    "@praxisjs/shared": "0.2.0"
+    "@praxisjs/core": "0.4.2",
+    "@praxisjs/decorators": "0.4.3",
+    "@praxisjs/jsx": "0.3.3",
+    "@praxisjs/shared": "0.2.0",
+    "@praxisjs/runtime": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",

package/src/__tests__/debug.test.ts

@@ -0,0 +1,262 @@
+import { beforeEach, describe, it, expect, vi } from "vitest";
+
+import { computed, signal } from "@praxisjs/core/internal";
+
+import { Registry } from "../core/registry";
+import { Debug } from "../decorators/debug";
+
+beforeEach(() => {
+  (Registry as unknown as { _instance: Registry | null })._instance = null;
+});
+
+// ── Method decorator ──────────────────────────────────────────────────────────
+
+describe("Debug — method decorator", () => {
+  it("records a method:call timeline entry", () => {
+    const ctx = { kind: "method" as const, name: "doWork" } as ClassMethodDecoratorContext;
+    const original = vi.fn((_x: unknown) => "result");
+
+    const wrapped = Debug()(original as never, ctx) as (...args: unknown[]) => unknown;
+
+    class Comp { constructor() {} }
+    const instance = new Comp();
+    const registry = Registry.instance;
+    registry.registerComponent(instance, "Comp");
+
+    wrapped.call(instance, 42);
+
+    const entry = registry.getTimeline().find((t) => t.type === "method:call");
+    expect(entry).toBeDefined();
+    expect(entry?.label).toContain("doWork");
+    expect(entry?.data.args).toEqual([42]);
+    expect(entry?.data.result).toBe("result");
+  });
+
+  it("records throw result when method throws", () => {
+    const ctx = { kind: "method" as const, name: "boom" } as ClassMethodDecoratorContext;
+    const original = () => { throw new Error("fail"); };
+
+    const wrapped = Debug()(original as never, ctx) as () => void;
+
+    class Comp {}
+    const instance = new Comp();
+    Registry.instance.registerComponent(instance, "Comp");
+
+    expect(() => wrapped.call(instance)).toThrow("fail");
+
+    const entry = Registry.instance.getTimeline().find((t) => t.type === "method:call");
+    expect(entry?.data.result).toContain("throw");
+  });
+
+  it("uses custom label from options", () => {
+    const ctx = { kind: "method" as const, name: "internal" } as ClassMethodDecoratorContext;
+    const original = vi.fn(() => undefined);
+
+    const wrapped = Debug({ label: "myLabel" })(original as never, ctx) as () => void;
+
+    class Comp {}
+    const instance = new Comp();
+    Registry.instance.registerComponent(instance, "Comp");
+    wrapped.call(instance);
+
+    const entry = Registry.instance.getTimeline().find((t) => t.type === "method:call");
+    expect(entry?.label).toContain("myLabel");
+  });
+});
+
+// ── Field decorator (wrapping @State getter/setter) ───────────────────────────
+
+describe("Debug — field decorator wrapping @State", () => {
+  it("registers signal and tracks updates", () => {
+    const registry = Registry.instance;
+    const instance = { count: 0 } as Record<string, unknown>;
+
+    // Simulate what @State() does: install a getter/setter on the instance
+    const s = signal(0);
+    Object.defineProperty(instance, "count", {
+      get() { return s(); },
+      set(v: number) { s.set(v); },
+      enumerable: true,
+      configurable: true,
+    });
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "count",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    const signals = registry.getSignals();
+    expect(signals.length).toBeGreaterThan(0);
+    expect(signals[0].label).toBe("count");
+    expect(signals[0].value).toBe(0);
+
+    // Read the property through the getter (covers the get() function body)
+    const readValue = (instance as Record<string, unknown>).count;
+    expect(readValue).toBe(0);
+
+    // Trigger update through the wrapped setter
+    (instance as Record<string, unknown>).count = 10;
+
+    // The set through the defined property calls updateSignal
+    expect(registry.getSignals()[0].value).toBe(10);
+  });
+});
+
+// ── Field decorator (computed field) ─────────────────────────────────────────
+
+describe("Debug — field decorator with computed value", () => {
+  it("registers computed signal and tracks updates", () => {
+    const registry = Registry.instance;
+    const src = signal(1);
+    const c = computed(() => src() * 2);
+
+    const instance = { doubled: c } as Record<string, unknown>;
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "doubled",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    const signals = registry.getSignals();
+    expect(signals.length).toBeGreaterThan(0);
+    expect(signals[0].label).toBe("doubled");
+    expect(signals[0].value).toBe(2);
+
+    src.set(5);
+    expect(registry.getSignals()[0].value).toBe(10);
+  });
+
+  it("warns when field value is not a computed and not undefined", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const instance = { myField: "not-computed" } as Record<string, unknown>;
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "myField",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[PraxisJS DevTools]"));
+    warn.mockRestore();
+  });
+
+  it("warns when computed field is replaced with non-computed value via setter", () => {
+    const registry = Registry.instance;
+    const src = signal(1);
+    const c = computed(() => src() * 2);
+
+    const instance = { doubled: c } as Record<string, unknown>;
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "doubled",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // Set a non-computed value through the property setter
+    (instance as Record<string, unknown>).doubled = "not-a-computed";
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[PraxisJS DevTools]"));
+    warn.mockRestore();
+
+    void registry;
+  });
+
+  it("updates slot when computed field is replaced with a new computed", () => {
+    const registry = Registry.instance;
+    const src = signal(1);
+    const c1 = computed(() => src() * 2);
+    const c2 = computed(() => src() * 10);
+
+    const instance = { doubled: c1 } as Record<string, unknown>;
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "doubled",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    // Replace with new computed
+    (instance as Record<string, unknown>).doubled = c2;
+
+    // The getter should now return c2
+    const newComputed = (instance as Record<string, unknown>).doubled;
+    expect(typeof newComputed).toBe("function");
+
+    void registry;
+  });
+
+  it("does not warn when field value is undefined", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const instance = { myUndef: undefined } as Record<string, unknown>;
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "field" as const,
+      name: "myUndef",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext;
+
+    Debug()(undefined, ctx);
+    initializers.forEach((fn) => fn.call(instance));
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+// ── Getter decorator ──────────────────────────────────────────────────────────
+
+describe("Debug — getter decorator", () => {
+  it("returns undefined (void) for getter kind", async () => {
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      kind: "getter" as const,
+      name: "myGetter",
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassGetterDecoratorContext;
+
+    const src = signal(3);
+    const result = Debug()(() => src() * 2 as unknown as never, ctx);
+    expect(result).toBeUndefined();
+
+    // Run the initializer on a fake instance
+    const instance = { myGetter: computed(() => src() * 2) };
+    initializers.forEach((fn) => fn.call(instance));
+
+    // Wait for queueMicrotask
+    await new Promise<void>((r) => setTimeout(r, 0));
+
+    const signals = Registry.instance.getSignals();
+    expect(signals.length).toBeGreaterThan(0);
+
+    // Update src to trigger the subscribe callback (covers the updateSignal path)
+    const signalsBefore = Registry.instance.getSignals()[0]?.value;
+    src.set(10);
+    // The computed updates: src() * 2 = 20
+    await new Promise<void>((r) => setTimeout(r, 0));
+    expect(signalsBefore).toBe(6); // 3 * 2 = 6
+  });
+});

package/src/__tests__/event-bus.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { EventBus } from "../core/event-bus";
+
+describe("EventBus", () => {
+  it("calls registered handler when event is emitted", () => {
+    const bus = new EventBus();
+    const handler = vi.fn();
+    bus.on("test", handler);
+    bus.emit("test", "payload");
+    expect(handler).toHaveBeenCalledWith("payload");
+  });
+
+  it("calls multiple handlers for the same event", () => {
+    const bus = new EventBus();
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+    bus.on("event", h1);
+    bus.on("event", h2);
+    bus.emit("event", 42);
+    expect(h1).toHaveBeenCalledWith(42);
+    expect(h2).toHaveBeenCalledWith(42);
+  });
+
+  it("does not call handlers for different events", () => {
+    const bus = new EventBus();
+    const handler = vi.fn();
+    bus.on("a", handler);
+    bus.emit("b", "data");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("does not throw when emitting to an event with no handlers", () => {
+    const bus = new EventBus();
+    expect(() => bus.emit("no-listeners", null)).not.toThrow();
+  });
+
+  it("unsubscribe function removes the handler", () => {
+    const bus = new EventBus();
+    const handler = vi.fn();
+    const unsub = bus.on("event", handler);
+    unsub();
+    bus.emit("event", "data");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("unsubscribing one handler does not affect others", () => {
+    const bus = new EventBus();
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+    const unsub = bus.on("event", h1);
+    bus.on("event", h2);
+    unsub();
+    bus.emit("event", "data");
+    expect(h1).not.toHaveBeenCalled();
+    expect(h2).toHaveBeenCalledWith("data");
+  });
+
+  it("passes payload correctly to handler", () => {
+    const bus = new EventBus();
+    const handler = vi.fn();
+    const payload = { key: "value", nested: { n: 1 } };
+    bus.on("event", handler);
+    bus.emit("event", payload);
+    expect(handler).toHaveBeenCalledWith(payload);
+  });
+
+  it("each EventBus instance is independent", () => {
+    const bus1 = new EventBus();
+    const bus2 = new EventBus();
+    const handler = vi.fn();
+    bus1.on("event", handler);
+    bus2.emit("event", "data");
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/format-time.test.ts

@@ -0,0 +1,52 @@
+import { beforeEach, afterEach, describe, it, expect, vi } from "vitest";
+
+import { time } from "../utils/format-time";
+
+describe("time", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("formats diff < 1000ms as milliseconds", () => {
+    // Date.now() = 1000, ts = 1000 - diff
+    vi.setSystemTime(1000);
+    expect(time(1000 - 500)).toBe("500ms");   // diff = 500
+    expect(time(1000 - 999)).toBe("999ms");   // diff = 999
+    expect(time(1000)).toBe("0ms");           // diff = 0
+  });
+
+  it("formats diff >= 1000ms and < 60000ms as seconds", () => {
+    vi.setSystemTime(10_000);
+    expect(time(0)).toBe("10.0s");            // diff = 10_000ms
+
+    vi.setSystemTime(5_500);
+    expect(time(0)).toBe("5.5s");             // diff = 5_500ms
+  });
+
+  it("formats diff >= 60000ms as minutes", () => {
+    vi.setSystemTime(120_000);
+    expect(time(0)).toBe("2m");               // diff = 120_000ms
+
+    vi.setSystemTime(90_000);
+    expect(time(0)).toBe("1m");               // diff = 90_000ms (1.5m → floor = 1)
+  });
+
+  it("appends prefix when provided", () => {
+    vi.setSystemTime(500);
+    expect(time(0, "ago")).toBe("500ms ago");
+  });
+
+  it("has no prefix when not provided", () => {
+    vi.setSystemTime(500);
+    expect(time(0)).toBe("500ms");
+  });
+
+  it("diff = 0ms renders as '0ms'", () => {
+    vi.setSystemTime(100);
+    expect(time(100)).toBe("0ms");
+  });
+});

package/src/__tests__/format-value.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+
+import { formatValue } from "../utils/format-value";
+
+describe("formatValue", () => {
+  it("formats null", () => {
+    expect(formatValue(null)).toBe("null");
+  });
+
+  it("formats undefined", () => {
+    expect(formatValue(undefined)).toBe("undefined");
+  });
+
+  it("wraps strings in double quotes", () => {
+    expect(formatValue("hello")).toBe('"hello"');
+    expect(formatValue("")).toBe('""');
+  });
+
+  it("formats numbers via String()", () => {
+    expect(formatValue(42)).toBe("42");
+    expect(formatValue(3.14)).toBe("3.14");
+    expect(formatValue(0)).toBe("0");
+    expect(formatValue(-1)).toBe("-1");
+  });
+
+  it("formats booleans via String()", () => {
+    expect(formatValue(true)).toBe("true");
+    expect(formatValue(false)).toBe("false");
+  });
+
+  it("JSON-stringifies plain objects", () => {
+    expect(formatValue({ a: 1 })).toBe('{"a":1}');
+    expect(formatValue({})).toBe("{}");
+  });
+
+  it("JSON-stringifies arrays", () => {
+    expect(formatValue([1, 2, 3])).toBe("[1,2,3]");
+    expect(formatValue([])).toBe("[]");
+  });
+
+  it("returns '[object]' for circular references", () => {
+    const obj: Record<string, unknown> = {};
+    obj.self = obj;
+    expect(formatValue(obj)).toBe("[object]");
+  });
+});