signalium 0.2.8 → 0.3.1

package/src/__tests__/utils/instrumented-signals.ts

@@ -0,0 +1,281 @@
+import { expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  createStateSignal as _createStateSignal,
+  createComputedSignal as _createComputedSignal,
+  createAsyncComputedSignal as _createAsyncComputedSignal,
+  createSubscriptionSignal as _createSubscriptionSignal,
+  createWatcherSignal as _createWatcherSignal,
+  SignalOptions,
+  Signal,
+  WriteableSignal,
+  SignalSubscription,
+  Watcher,
+} from '../../index.js';
+
+class SignalCounts {
+  name: string;
+
+  get = 0;
+  set = 0;
+  compute = 0;
+
+  resolve = 0;
+
+  subscribe = 0;
+  update = 0;
+  unsubscribe = 0;
+  internalGet = 0;
+  internalSet = 0;
+
+  effect = 0;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+const countsKeys = Object.keys(new SignalCounts('')).filter(k => k !== 'name') as (keyof SignalCounts)[];
+
+let currentOrder: string[] | undefined = [];
+const COUNTS = new WeakMap<Signal<any> | Watcher<any>, SignalCounts>();
+
+interface CustomMatchers<R = unknown> {
+  toHaveSignalValue: (v: any) => R;
+  toHaveSignalCounts: (counts: Partial<SignalCounts>) => R;
+  toHaveSignalValueAndCounts: (v: any, counts: Partial<SignalCounts>) => R;
+  toHaveComputedOrder: (order: string[]) => R;
+}
+
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Assertion<T = any> extends CustomMatchers<T> {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface AsymmetricMatchersContaining extends CustomMatchers {}
+}
+
+function toHaveSignalValue(this: { equals(a: unknown, b: unknown): boolean }, signal: Signal<any>, value: any) {
+  const signalValue = signal.get();
+
+  return {
+    pass: this.equals(signalValue, value),
+    message: () => `Expected signal value to be ${JSON.stringify(value)}, but got ${JSON.stringify(signalValue)}`,
+  };
+}
+
+function toHaveSignalCounts(signal: Signal<any>, counts: SignalCounts) {
+  const signalCounts = COUNTS.get(signal);
+
+  if (!signalCounts) {
+    return {
+      pass: false,
+      message: () => 'Signal not found in counts map',
+    };
+  }
+
+  for (const key of countsKeys) {
+    const count = counts[key];
+
+    if (count !== undefined && signalCounts[key] !== count) {
+      return {
+        pass: false,
+        message: () => `Expected ${key} count to be ${count} but got ${signalCounts[key]}`,
+      };
+    }
+  }
+
+  return {
+    pass: true,
+    message: () => 'Counts match',
+  };
+}
+
+expect.extend({
+  toHaveSignalValue,
+  toHaveSignalCounts,
+
+  toHaveSignalValueAndCounts(signal, value, counts) {
+    const valueResult = toHaveSignalValue.call(this, signal, value);
+    const countsResult = toHaveSignalCounts.call(this, signal, counts);
+
+    return {
+      pass: valueResult.pass && countsResult.pass,
+      message: () => {
+        const messages = [
+          !valueResult.pass && valueResult.message(),
+          !countsResult.pass && countsResult.message(),
+        ].filter(m => m);
+
+        return messages.join('\n');
+      },
+    };
+  },
+
+  toHaveComputedOrder(fn: () => void, expectedOrder: string[]) {
+    const order = (currentOrder = []);
+
+    fn();
+
+    currentOrder = undefined;
+
+    return {
+      pass: this.equals(order, expectedOrder),
+      message: () => `Expected compute count to be ${expectedOrder.toString()} but got ${order.toString()}`,
+    };
+  },
+});
+
+export const createStateSignal = <T>(initialValue: T, opts?: SignalOptions<T>): WriteableSignal<T> => {
+  const desc = opts?.desc || 'unlabeled';
+  const s = _createStateSignal(initialValue, opts);
+
+  const counts = new SignalCounts(desc);
+
+  const wrapper = {
+    get() {
+      counts.get++;
+      return s.get();
+    },
+
+    set(value: T) {
+      counts.set++;
+      s.set(value);
+    },
+  };
+
+  COUNTS.set(wrapper, counts);
+
+  return wrapper;
+};
+
+export const createComputedSignal: typeof _createComputedSignal = (compute, opts) => {
+  const desc = opts?.desc || 'unlabeled';
+  const counts = new SignalCounts(desc);
+
+  const s = _createComputedSignal(v => {
+    counts.compute++;
+
+    if (desc) {
+      currentOrder?.push(desc);
+    }
+
+    return compute(v);
+  }, opts);
+
+  const wrapper = {
+    get() {
+      counts.get++;
+
+      // Get twice to ensure idempotency
+      s.get();
+
+      return s.get();
+    },
+  };
+
+  COUNTS.set(wrapper, counts);
+
+  return wrapper;
+};
+
+export const createAsyncComputedSignal: typeof _createAsyncComputedSignal = (compute, opts) => {
+  const desc = opts?.desc || 'unlabeled';
+  const counts = new SignalCounts(desc);
+
+  const s = _createAsyncComputedSignal(async v => {
+    counts.compute++;
+
+    if (desc) {
+      currentOrder?.push(desc);
+    }
+
+    const result = await compute(v);
+
+    counts.resolve++;
+
+    return result;
+  }, opts);
+
+  const wrapper = {
+    get() {
+      counts.get++;
+      return s.get();
+    },
+  };
+
+  COUNTS.set(wrapper, counts);
+
+  return wrapper;
+};
+
+export const createSubscriptionSignal: typeof _createSubscriptionSignal = (subscribe, opts) => {
+  const desc = opts?.desc || 'unlabeled';
+  const counts = new SignalCounts(desc);
+
+  const s = _createSubscriptionSignal((get, set) => {
+    counts.subscribe++;
+
+    if (desc) {
+      currentOrder?.push(desc);
+    }
+
+    const result = subscribe(
+      () => {
+        counts.internalGet++;
+        return get();
+      },
+      v => {
+        counts.internalSet++;
+        set(v);
+      },
+    );
+
+    const subscriptionWrapper: SignalSubscription = {
+      unsubscribe() {
+        counts.unsubscribe++;
+        result?.unsubscribe?.();
+      },
+
+      update() {
+        counts.update++;
+        result?.update?.();
+      },
+    };
+
+    return subscriptionWrapper;
+  }, opts);
+
+  const wrapper = {
+    get() {
+      counts.get++;
+      return s.get();
+    },
+  };
+
+  COUNTS.set(wrapper, counts);
+
+  return wrapper;
+};
+
+export function createWatcherSignal<T>(fn: () => T, opts?: SignalOptions<T>): Watcher<T> {
+  const desc = opts?.desc || 'unlabeled';
+  const counts = new SignalCounts(desc);
+
+  const w = _createWatcherSignal<T>(() => {
+    counts.compute++;
+    return fn();
+  }, opts);
+
+  const wrapper: Watcher<T> = {
+    addListener: (fn, opts) => {
+      counts.subscribe++;
+      return w.addListener(v => {
+        counts.effect++;
+        return fn(v);
+      }, opts);
+    },
+  };
+
+  COUNTS.set(wrapper, counts);
+
+  return wrapper;
+}

package/src/__tests__/utils/permute.ts

@@ -0,0 +1,74 @@
+import { describe } from 'vitest';
+import { asyncComputed, computed, subscription, wrapHook } from './instrumented-hooks.js';
+import { SignalOptionsWithInit } from '../../types.js';
+
+const createMethods = [
+  {
+    name: 'createComputed',
+    create: computed,
+  },
+  {
+    name: 'createAsyncComputed',
+    create: <T, Args extends unknown[]>(
+      fn: (...args: Args) => T | Promise<T>,
+      opts?: Partial<SignalOptionsWithInit<T, Args>>,
+    ) => {
+      const computed = asyncComputed(fn, opts);
+
+      return wrapHook(computed, (...args: Args) => {
+        return computed(...args).result;
+      });
+    },
+  },
+  {
+    name: 'createSubscription',
+    create: function _createSubscription<T, Args extends unknown[]>(
+      fn: (...args: Args) => T,
+      opts?: Partial<SignalOptionsWithInit<T, Args>>,
+    ): (...args: Args) => T {
+      return subscription(({ set }, ...args) => {
+        set(fn(...args));
+
+        return {
+          update: () => {
+            set(fn(...args));
+          },
+        };
+      }, opts);
+    },
+  },
+];
+
+function generatePermutations(n: number, m: number): number[][] {
+  const results: number[][] = [];
+
+  function generate(current: number[], remaining: number) {
+    if (remaining === 0) {
+      results.push([...current]);
+      return;
+    }
+
+    for (let i = 0; i < n; i++) {
+      current.push(i);
+      generate(current, remaining - 1);
+      current.pop();
+    }
+  }
+
+  generate([], m);
+  return results;
+}
+
+type CreateMethod = (typeof createMethods)[number]['create'];
+
+export function permute(m: number, fn: (...args: CreateMethod[]) => void) {
+  const testCases = generatePermutations(createMethods.length, m);
+
+  for (const testCase of testCases) {
+    const testMethods = [createMethods[testCase[0]], ...testCase.slice(1).map(i => createMethods[i])];
+
+    describe(`${testMethods.map(m => m.name).join(', ')}`, () => {
+      fn(...testMethods.map(m => m.create));
+    });
+  }
+}

package/src/config.ts

@@ -1,27 +1,42 @@
-let currentFlush: ReturnType<typeof setTimeout> | null = null;
+import { SignalScope } from './hooks.js';
+import { getCurrentConsumer } from './signals.js';
 
-export type FlushCallback = () => Promise<void>;
+export type FlushCallback = () => void;
 
-export type FlushFn = (fn: () => Promise<void>) => void;
-
-export let scheduleFlush: FlushFn = flushWatchers => {
-  if (currentFlush !== null) return;
+export type FlushFn = (fn: FlushCallback) => void;
+export type BatchFn = (fn: () => void) => void;
 
-  currentFlush = setTimeout(() => {
-    currentFlush = null;
+interface SignalHooksConfig {
+  scheduleFlush: FlushFn;
+  runBatch: BatchFn;
+  getFrameworkScope: () => SignalScope | undefined;
+  useSignalValue: <T>(key: string, fn: () => T) => T;
+}
 
+export let scheduleFlush: FlushFn = flushWatchers => {
+  setTimeout(() => {
     flushWatchers();
   }, 0);
 };
 
-export const setScheduleFlush = (flushFn: FlushFn) => {
-  scheduleFlush = flushFn;
-};
-
-export type BatchFn = (fn: () => void) => void;
-
 export let runBatch: BatchFn = fn => fn();
 
-export const setRunBatch = (batchFn: BatchFn) => {
-  runBatch = batchFn;
-};
+export let getFrameworkScope: () => SignalScope | undefined = () => undefined;
+
+let useFrameworkSignalValue: <T>(key: string, fn: () => T) => T = (key, fn) => fn();
+
+export function useSignalValue<T>(key: string, fn: () => T): T {
+  if (getCurrentConsumer()) {
+    return fn();
+  } else {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return useFrameworkSignalValue(key, fn);
+  }
+}
+
+export function setConfig(cfg: Partial<SignalHooksConfig>) {
+  scheduleFlush = cfg.scheduleFlush ?? scheduleFlush;
+  runBatch = cfg.runBatch ?? runBatch;
+  getFrameworkScope = cfg.getFrameworkScope ?? getFrameworkScope;
+  useFrameworkSignalValue = cfg.useSignalValue ?? useFrameworkSignalValue;
+}

package/src/debug.ts

@@ -0,0 +1,14 @@
+export {
+  setTracing,
+  createTracer,
+  createTracerFromId,
+  removeTracer,
+  VisualizerNode,
+  type VisualizerLink,
+  VisualizerNodeType,
+  TracerEventType,
+  Tracer,
+  TRACER,
+} from './trace.js';
+
+export { scheduleTracer } from './scheduling.js';