feat(debug): add trace and customFormatter

crimx · crimx · commit af67bf517128 · 2025-08-13T15:14:57.000+08:00
diff --git a/.export-size-svg.mjs b/.export-size-svg.mjs
@@ -26,6 +26,7 @@ export default defineConfig({
     {
       title: "*",
       code: "export * from './src/index.ts'",
+      externals: ["./dev"],
     },
     {
       title: "{ readable, writable } (core)",
diff --git a/mangle-cache.json b/mangle-cache.json
@@ -1,17 +1,18 @@
 {
-  "addDep_": "d",
-  "batching_": "c",
-  "data_": "a",
-  "delete_": "l",
-  "dependents_": "n",
-  "deps_": "p",
-  "equal_": "e",
-  "multi_": "m",
-  "notify_": "y",
-  "onDisposeValue_": "v",
-  "onReaction_": "o",
-  "single_": "s",
-  "task_": "k",
-  "tasks_": "t",
-  "upsert_": "u"
+  "addDep_": "_d",
+  "batching_": "_c",
+  "data_": "_a",
+  "delete_": "_l",
+  "dependents_": "_n",
+  "deps_": "_p",
+  "equal_": "_e",
+  "multi_": "_m",
+  "notify_": "_y",
+  "onDisposeValue_": "_v",
+  "onReaction_": "_o",
+  "single_": "_s",
+  "task_": "_k",
+  "tasks_": "_t",
+  "upsert_": "_u",
+  "watchDebug_": "_w"
 }
diff --git a/src/compute.ts b/src/compute.ts
@@ -2,7 +2,7 @@ import { ReadableImpl } from "./readable";
 import { type Config, type Get, type OwnedReadable, type Readable } from "./typings";
 import { isReadable } from "./utils";
 
-export interface ComputeFn<TValue> {
+export interface ComputeFn<TValue = any> {
   (get: Get): TValue;
 }
 
diff --git a/src/dev/customFormatter.ts b/src/dev/customFormatter.ts
@@ -1,6 +1,12 @@
 import { isReadable, isWritable } from "../utils";
 
-export function initCustomFormatter(): void {
+/**
+ * Enables custom formatting for Readable and Writable objects in Chrome DevTools.
+ * It is enabled in development by default.
+ *
+ * @see {@link https://www.mattzeunert.com/2016/02/19/custom-chrome-devtools-object-formatters.html}
+ */
+export function customFormatter(): void {
   if (typeof window === "undefined") {
     return;
   }
diff --git a/src/dev/index.ts b/src/dev/index.ts
@@ -0,0 +1,2 @@
+export * from "./customFormatter";
+export * from "./trace";
diff --git a/src/dev/trace.ts b/src/dev/trace.ts
@@ -0,0 +1,205 @@
+import { type ComputeFn } from "../compute";
+import { type Get, type Readable } from "../typings";
+import { isReadable, isWritable } from "../utils";
+import { type WatchEffect } from "../watch";
+
+export interface TraceConfig {
+  name?: string;
+  /** @default true */
+  printStack?: boolean;
+  /** @default true */
+  defaultExpand?: boolean;
+}
+
+export interface Trace {
+  <T extends Readable>($: T, config?: TraceConfig): T;
+  (effect: WatchEffect, config?: TraceConfig): WatchEffect;
+  (fn: ComputeFn, config?: TraceConfig): ComputeFn;
+}
+
+/**
+ * Console logs trace information about the provided Readable or WatchEffect.
+ * @example
+ * ```ts
+ * import { trace, writable, watch } from "@embra";
+ * const count$ = writable(0);
+ *
+ * trace(count$);
+ *
+ * watch(() => count$.value++);
+ *
+ * count$.set(1);
+ * ```
+ */
+export const trace: Trace = (x: unknown, config?: TraceConfig): any => {
+  if (isReadable(x)) {
+    return traceReadable(x, config);
+  }
+  if (typeof x === "function") {
+    return traceWatch(x as ComputeFn | WatchEffect, config);
+  }
+  throw new TypeError("trace expects a Readable, WatchEffect, or ComputeFn as the first argument");
+};
+
+interface Info {
+  value: any;
+  version: number;
+}
+
+class Deps {
+  public oldDeps = new Map<Readable, Info>();
+  public newDeps = new Map<Readable, Info>();
+
+  private readonly added: [Readable, Info][] = [];
+  private readonly updated: [Readable, Info][] = [];
+  private readonly unchanged: [Readable, Info][] = [];
+  private readonly removed: [Readable, Info][] = [];
+
+  public print(): void {
+    for (const [dep, info] of this.newDeps) {
+      const oldInfo = this.oldDeps.get(dep);
+      if (oldInfo) {
+        if (oldInfo.version !== info.version) {
+          this.updated.push([dep, info]);
+        } else {
+          this.unchanged.push([dep, info]);
+        }
+      } else {
+        this.added.push([dep, info]);
+      }
+    }
+
+    for (const [dep, info] of this.oldDeps) {
+      if (!this.newDeps.has(dep)) {
+        this.removed.push([dep, info]);
+      }
+    }
+
+    for (const [dep, info] of this.added) {
+      console.log(`\x1b[32m(+)\x1b[0m ${this.getDepName(dep)} ->`, info.value);
+    }
+    for (const [dep, info] of this.updated) {
+      console.log(
+        `\x1b[33m(*)\x1b[0m ${this.getDepName(dep)} ->`,
+        info.value,
+        `<- previous:`,
+        this.oldDeps.get(dep)?.value,
+      );
+    }
+    for (const [dep, info] of this.unchanged) {
+      console.log(`\x1b[37m(=) ${this.getDepName(dep)}\x1b[0m ->`, info.value);
+    }
+    for (const [dep, info] of this.removed) {
+      console.log(`\x1b[31m(-)\x1b[0m \x1b[9m${this.getDepName(dep)}\x1b[0m ->`, info.value);
+    }
+
+    this.added.length = this.updated.length = this.unchanged.length = this.removed.length = 0;
+  }
+
+  private depNameIndex = 1;
+  private readonly depNames = new WeakMap<Readable, string>();
+  private getDepName(dep: Readable): string {
+    if (this.depNames.has(dep)) {
+      return this.depNames.get(dep)!;
+    }
+    const depType = isWritable(dep) ? "Writable" : isReadable(dep) ? "Readable" : "Unknown";
+    let name =
+      dep.name ||
+      (this.depNameIndex <= 20 ? String.fromCodePoint(9311 + this.depNameIndex++) : `${this.depNameIndex++}`);
+    name = `${depType}(${name})`;
+    this.depNames.set(dep, name);
+    return name;
+  }
+}
+
+const traceReadable = <T extends Readable>($: T, config?: TraceConfig): T => {
+  const deps = new Deps();
+  const $type = isWritable($) ? "Writable" : isReadable($) ? "Readable" : "Unknown";
+  const traceLocation = new Error("LocationDebugError");
+  let lastValue: any = traceLocation;
+
+  $.subscribe(() => {
+    ((config?.defaultExpand ?? true) ? console.group : console.groupCollapsed)(
+      `\x1b[36m[embra]\x1b[0m trace ${$type}${$.name ? `(\x1b[33m${$.name}\x1b[0m)` : ""}${config?.name ? `: ${config.name}` : ""}`,
+    );
+
+    if (config?.printStack ?? true) {
+      console.groupCollapsed("trace location");
+      console.log(traceLocation);
+      console.groupEnd();
+
+      console.groupCollapsed(`effect location`);
+      console.trace();
+      console.groupEnd();
+    }
+
+    if (lastValue === traceLocation) {
+      console.log($.value);
+    } else {
+      console.log($.value, "<- previous:", lastValue);
+      lastValue = $.value;
+    }
+
+    if ($.deps_) {
+      for (const dep of $.deps_.keys()) {
+        deps.newDeps.set(dep, { value: dep.value, version: dep.$version });
+      }
+
+      deps.print();
+
+      [deps.oldDeps, deps.newDeps] = [deps.newDeps, deps.oldDeps];
+      deps.newDeps.clear();
+    } else {
+      deps.oldDeps.clear();
+      deps.newDeps.clear();
+    }
+
+    console.groupEnd();
+  });
+
+  return $;
+};
+
+const traceWatch = <T extends WatchEffect | ComputeFn>(effect: T, config?: TraceConfig): T => {
+  const deps = new Deps();
+  const traceLocation = new Error("TraceLocationDebugError");
+
+  return ((get: Get, ...args: [any]): any => {
+    const myGet: Get = $ => {
+      if (isReadable($)) {
+        deps.newDeps.set($, { value: $.value, version: $.$version });
+      }
+      return get($);
+    };
+
+    const type = typeof args[0] === "function" ? "watch" : "compute";
+    const start = performance.now();
+    const effectResult = effect(myGet, ...args);
+    const time = (performance.now() - start).toFixed(2);
+
+    ((config?.defaultExpand ?? true) ? console.group : console.groupCollapsed)(
+      `\x1b[36m[embra]\x1b[0m trace ${type}${effect.name ? `(\x1b[33m${effect.name}\x1b[0m)` : ""}${config?.name ? `: ${config.name}` : ""}`,
+    );
+
+    if (config?.printStack ?? true) {
+      console.groupCollapsed("trace location");
+      console.log(traceLocation);
+      console.groupEnd();
+
+      console.groupCollapsed(`effect executed in ${time} ms`);
+      console.trace();
+      console.groupEnd();
+    } else {
+      console.log(`effect executed in ${time} ms`);
+    }
+
+    deps.print();
+
+    console.groupEnd();
+
+    [deps.oldDeps, deps.newDeps] = [deps.newDeps, deps.oldDeps];
+    deps.newDeps.clear();
+
+    return effectResult;
+  }) as T;
+};
diff --git a/src/index.ts b/src/index.ts
@@ -1,4 +1,4 @@
-import { initCustomFormatter } from "./dev/customFormatter";
+import { customFormatter } from "./dev";
 
 export type {
   Get,
@@ -26,7 +26,15 @@ export { combine, type Combine, type MapReadablesToValues } from "./combine";
 export { readable, type CreateReadable, writable, type CreateWritable, toWritable, type ToWritable } from "./readable";
 export { watch, type WatchEffect } from "./watch";
 
-export { isReadable, type IsReadable, unsubscribe, strictEqual, arrayShallowEqual } from "./utils";
+export {
+  isReadable,
+  type IsReadable,
+  isWritable,
+  type IsWritable,
+  unsubscribe,
+  strictEqual,
+  arrayShallowEqual,
+} from "./utils";
 
 export { type OnDisposeValue } from "./collections/utils";
 
@@ -53,6 +61,8 @@ export {
   type ReadonlyReactiveArray,
 } from "./collections/reactiveArray";
 
+export { customFormatter, trace, type Trace, type TraceConfig } from "./dev";
+
 if (process.env.NODE_ENV !== "production") {
-  /* @__PURE__ */ initCustomFormatter();
+  /* @__PURE__ */ customFormatter();
 }
diff --git a/src/typings.ts b/src/typings.ts
@@ -30,6 +30,7 @@ export interface Get {
  * A Readable is a reactive value that can be read and subscribed to.
  */
 export interface Readable<TValue = any> {
+  readonly name?: string;
   /**
    * A version representation of the value.
    * If two versions of a $ is not equal(`Object.is`), it means the `value` has changed (event if the `value` is equal).
@@ -39,6 +40,10 @@ export interface Readable<TValue = any> {
    * @internal
    */
   readonly [BRAND]: BRAND;
+  /**
+   * @internal
+   */
+  deps_?: Map<Readable, Version>;
   /**
    * Current value of the $.
    */
diff --git a/src/utils.ts b/src/utils.ts
@@ -87,7 +87,12 @@ export interface IsWritable {
  */
 export const isWritable: IsWritable = ($: unknown): $ is Writable => isReadable($) && !!($ as Writable).set;
 
-export const invokeEach = <T>(iterable: Iterable<(value: T) => any>, value: T) => {
+interface InvokeEach {
+  (iterable: Iterable<() => any>): void;
+  <T>(iterable: Iterable<(value: T) => any>, value: T): void;
+}
+
+export const invokeEach: InvokeEach = <T>(iterable: Iterable<(value?: T) => any>, value?: T) => {
   let error: unknown = UNIQUE_VALUE;
   for (const fn of iterable) {
     try {
diff --git a/test/utils.test.ts b/test/utils.test.ts
@@ -1,6 +1,15 @@
 import { describe, expect, it, vi } from "vitest";
 
-import { arrayShallowEqual, compute, isReadable, readable, strictEqual, unsubscribe, writable } from "../src";
+import {
+  arrayShallowEqual,
+  compute,
+  isReadable,
+  isWritable,
+  readable,
+  strictEqual,
+  unsubscribe,
+  writable,
+} from "../src";
 
 describe("utils", () => {
   describe("unsubscribe", () => {
@@ -122,4 +131,22 @@ describe("utils", () => {
       expect(isReadable(notReadable)).toBe(false);
     });
   });
+
+  describe("isWritable", () => {
+    it("should return true for Writable instances", () => {
+      const a = writable("a");
+      expect(isWritable(a)).toBe(true);
+    });
+
+    it("should return false for Readable instances", () => {
+      const [b] = readable("b");
+      expect(isWritable(b)).toBe(false);
+    });
+
+    it("should return false for non-Readable/Writable instances", () => {
+      const notReadable = { value: "not readable" };
+      expect(isWritable(notReadable)).toBe(false);
+      expect(isWritable(undefined)).toBe(false);
+    });
+  });
 });
diff --git a/vitest.config.mts b/vitest.config.mts
@@ -4,6 +4,7 @@ export default defineConfig({
   test: {
     coverage: {
       include: ["src/**"],
+      exclude: ["src/dev/**"],
       reporter: ["html", "text", "lcov"],
     },
     poolOptions: {

Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,7 @@ export default defineConfig({`
`26`	`26`	`{`
`27`	`27`	`title: "*",`
`28`	`28`	`code: "export * from './src/index.ts'",`
	`29`	`+ externals: ["./dev"],`
`29`	`30`	`},`
`30`	`31`	`{`
`31`	`32`	`title: "{ readable, writable } (core)",`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@ import { ReadableImpl } from "./readable";`
`2`	`2`	`import { type Config, type Get, type OwnedReadable, type Readable } from "./typings";`
`3`	`3`	`import { isReadable } from "./utils";`
`4`	`4`
`5`		`-export interface ComputeFn<TValue> {`
	`5`	`+export interface ComputeFn<TValue = any> {`
`6`	`6`	`(get: Get): TValue;`
`7`	`7`	`}`
`8`	`8`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export * from "./customFormatter";`
	`2`	`+export * from "./trace";`