signalium 0.2.8 → 0.3.1

package/src/trace.ts

@@ -0,0 +1,449 @@
+import { scheduleTracer } from './scheduling.js';
+import { ComputedSignal } from './signals.js';
+import { Signal, Watcher } from './types.js';
+
+export let TRACER: TracerProxy | undefined;
+
+export enum VisualizerNodeType {
+  State,
+  Computed,
+  AsyncComputed,
+  Subscription,
+  Watcher,
+}
+
+export interface VisualizerLink {
+  connected: boolean;
+  version: number;
+  node: VisualizerNode;
+}
+
+export enum TracerEventType {
+  StartUpdate = 'StartUpdate',
+  EndUpdate = 'EndUpdate',
+  StartLoading = 'StartLoading',
+  EndLoading = 'EndLoading',
+
+  Connected = 'Connected',
+  Disconnected = 'Disconnected',
+
+  ConsumeState = 'ConsumeState',
+}
+
+type StartUpdateEvent = {
+  type: TracerEventType.StartUpdate;
+  id: string;
+};
+
+type EndUpdateEvent = {
+  type: TracerEventType.EndUpdate;
+  id: string;
+  value: unknown;
+  preserveChildren?: boolean;
+};
+
+type StartLoadingEvent = {
+  type: TracerEventType.StartLoading;
+  id: string;
+};
+
+type EndLoadingEvent = {
+  type: TracerEventType.EndLoading;
+  id: string;
+  value: unknown;
+};
+
+type ConnectedEvent = {
+  type: TracerEventType.Connected;
+  id: string;
+  childId: string;
+  nodeType: VisualizerNodeType;
+  name?: string;
+  params?: string;
+};
+
+type DisconnectedEvent = {
+  type: TracerEventType.Disconnected;
+  id: string;
+  childId: string;
+};
+
+type ConsumeStateEvent = {
+  type: TracerEventType.ConsumeState;
+  id: string;
+  childId: string;
+  value: unknown;
+  setValue: (value: unknown) => void;
+};
+
+type TracerEvent =
+  | StartUpdateEvent
+  | EndUpdateEvent
+  | StartLoadingEvent
+  | EndLoadingEvent
+  | ConnectedEvent
+  | DisconnectedEvent
+  | ConsumeStateEvent;
+
+export class VisualizerNode {
+  private subscribers: (() => void)[] = [];
+
+  private nextStateChildren: VisualizerNode[] = [];
+
+  public stateChildren: VisualizerNode[] = [];
+  public children: VisualizerLink[] = [];
+  public updating = true;
+  public loading = false;
+  public version = 0;
+
+  private updatingVersion = 0;
+  private didConnect = false;
+
+  constructor(
+    private tracer: Tracer,
+    public depth: number,
+    public type: VisualizerNodeType,
+    public id: string,
+    public value: unknown,
+    public name?: string,
+    public params?: string,
+    private _setValue?: (value: unknown) => void,
+  ) {
+    this.tracer.maxDepth = Math.max(this.tracer.maxDepth, this.depth);
+  }
+
+  get showParams() {
+    return this.tracer.showParams;
+  }
+
+  get showValue() {
+    return this.tracer.showValue;
+  }
+
+  get interactive() {
+    return this.tracer.interactive;
+  }
+
+  setValue(value: unknown) {
+    if (this.type !== VisualizerNodeType.State) {
+      throw new Error('setValue is only allowed on state nodes');
+    }
+
+    this._setValue?.(value);
+    this.notify();
+    scheduleTracer(this.tracer);
+  }
+
+  connectChild(child: VisualizerNode): boolean {
+    let childLink = this.children.find(
+      link => link.node.id === child.id || (link.node.name === child.name && link.version !== this.updatingVersion),
+    );
+
+    let shouldSkip = false;
+
+    if (childLink) {
+      if (!child.didConnect) {
+        child.value = childLink.node.value;
+        child.children = childLink.node.children.map(link => ({
+          ...link,
+          version: child.version,
+        }));
+      }
+
+      childLink.node = child;
+      childLink.connected = true;
+      childLink.version = this.updatingVersion;
+      shouldSkip = true;
+    } else {
+      this.children.push({
+        connected: true,
+        node: child,
+        version: this.updatingVersion,
+      });
+    }
+
+    child.didConnect = true;
+    this.notify();
+
+    return shouldSkip;
+  }
+
+  disconnectChild(childId: string) {
+    const childLink = this.children.find(link => link.node.id === childId);
+
+    if (!childLink) {
+      return;
+    }
+
+    childLink.connected = false;
+
+    this.notify();
+  }
+
+  startUpdate() {
+    this.updating = true;
+    this.updatingVersion++;
+
+    this.notify();
+  }
+
+  endUpdate(value: unknown, preserveChildren = false) {
+    this.updating = false;
+    this.value = value;
+    if (!preserveChildren) {
+      this.stateChildren = this.nextStateChildren;
+    }
+    this.nextStateChildren = [];
+    this.notify();
+  }
+
+  startLoading() {
+    this.loading = true;
+    this.notify();
+  }
+
+  endLoading(value: unknown) {
+    this.loading = false;
+    this.value = value;
+    this.notify();
+  }
+
+  consumeState(id: string, value: unknown, setValue: (value: unknown) => void) {
+    const existing = this.stateChildren.find(child => child.id === id);
+
+    if (existing) {
+      existing.value = value;
+      this.nextStateChildren.push(existing);
+      existing.notify();
+    } else {
+      const node = new VisualizerNode(
+        this.tracer,
+        this.depth + 1,
+        VisualizerNodeType.State,
+        id,
+        value,
+        undefined,
+        undefined,
+        setValue,
+      );
+      node.updating = false;
+      this.nextStateChildren.push(node);
+    }
+  }
+
+  notify() {
+    this.version++;
+    for (const subscriber of this.subscribers) {
+      subscriber();
+    }
+  }
+
+  subscribe(subscriber: () => void) {
+    this.subscribers.push(subscriber);
+
+    return () => {
+      this.subscribers = this.subscribers.filter(s => s !== subscriber);
+    };
+  }
+}
+
+let ID = 0;
+
+class TraceFlush {
+  private forceComplete = false;
+  public promise: Promise<void>;
+  public id = ID++;
+  constructor(tracer: Tracer, queue: TracerEvent[], previousFlush?: TraceFlush) {
+    this.promise = this.runFlush(tracer, queue, previousFlush);
+  }
+
+  complete() {
+    this.forceComplete = true;
+    return this.promise;
+  }
+
+  private async runFlush(tracer: Tracer, queue: TracerEvent[], previousFlush?: TraceFlush) {
+    if (previousFlush) {
+      await previousFlush.complete();
+    }
+
+    for (let i = 0; i < queue.length; i++) {
+      const event = queue[i];
+      const nextEvent = queue[i + 1];
+
+      const skipDelay = tracer.handleEvent(event, nextEvent);
+
+      if (!this.forceComplete && !skipDelay && tracer.delay > 0 && !document.hidden) {
+        await new Promise(resolve => setTimeout(resolve, tracer.delay));
+      }
+    }
+  }
+}
+
+export class Tracer {
+  private nodeMap = new Map<string, VisualizerNode>();
+
+  delay = 200;
+  maxDepth = 0;
+
+  private initialized = false;
+
+  constructor(
+    id: string,
+    immediate = false,
+    public showParams = true,
+    public showValue = true,
+    public interactive = true,
+  ) {
+    // If it's immediate, we should run the first flush immediately, skipping animations
+    this.initialized = !immediate;
+
+    const node = new VisualizerNode(this, 0, VisualizerNodeType.Watcher, id, '');
+
+    this.rootNode = node;
+    this.nodeMap.set(id, node);
+  }
+
+  public rootNode: VisualizerNode;
+
+  private eventQueue: TracerEvent[] = [];
+  private currentFlush: TraceFlush | undefined;
+
+  emit(event: TracerEvent) {
+    if (event.type === TracerEventType.Connected || event.type === TracerEventType.ConsumeState) {
+      const node = this.nodeMap.get(event.id);
+
+      if (!node) {
+        return;
+      }
+
+      if (!this.nodeMap.has(event.childId)) {
+        const name = event.type === TracerEventType.Connected ? event.name : undefined;
+        const params = event.type === TracerEventType.Connected ? event.params : undefined;
+        const nodeType = event.type === TracerEventType.Connected ? event.nodeType : VisualizerNodeType.State;
+
+        this.nodeMap.set(
+          event.childId,
+          new VisualizerNode(this, node.depth + 1, nodeType, event.childId, '', name, params),
+        );
+      }
+    }
+
+    if (this.initialized) {
+      this.eventQueue.push(event);
+    } else {
+      this.handleEvent(event);
+    }
+  }
+
+  handleEvent(event: TracerEvent, nextEvent?: TracerEvent) {
+    const node = this.nodeMap.get(event.id);
+
+    if (!node) {
+      return true;
+    }
+
+    let skipDelay = nextEvent?.type === TracerEventType.StartLoading;
+
+    if (event.type === TracerEventType.Connected) {
+      let child = this.nodeMap.get(event.childId);
+
+      if (!child) {
+        throw new Error(`Child node ${event.childId} not found`);
+      }
+
+      skipDelay = node.connectChild(child);
+    } else if (event.type === TracerEventType.Disconnected) {
+      node.disconnectChild(event.childId);
+    } else if (event.type === TracerEventType.StartUpdate) {
+      node.startUpdate();
+      if (
+        nextEvent &&
+        nextEvent.id === event.id &&
+        (nextEvent.type === TracerEventType.EndUpdate || nextEvent.type === TracerEventType.StartLoading)
+      ) {
+        skipDelay = true;
+      }
+    } else if (event.type === TracerEventType.EndUpdate) {
+      node.endUpdate(event.value, event.preserveChildren);
+    } else if (event.type === TracerEventType.StartLoading) {
+      node.startLoading();
+      skipDelay = true;
+    } else if (event.type === TracerEventType.EndLoading) {
+      node.endLoading(event.value);
+    } else if (event.type === TracerEventType.ConsumeState) {
+      node.consumeState(event.childId, event.value, event.setValue);
+    }
+
+    return skipDelay;
+  }
+
+  async flush() {
+    if (this.eventQueue.length === 0) {
+      return;
+    }
+
+    this.currentFlush = new TraceFlush(this, this.eventQueue, this.currentFlush);
+    this.eventQueue = [];
+  }
+
+  addListener(listener: () => void) {
+    this.initialized = true;
+    return this.rootNode.subscribe(listener);
+  }
+}
+
+class TracerProxy {
+  private tracers: Tracer[] = [];
+
+  constructor() {}
+
+  emit(event: TracerEvent) {
+    this.tracers.forEach(tracer => tracer.emit(event));
+  }
+
+  createTracer(id: string, immediate = false): Tracer {
+    const tracer = new Tracer(id, immediate);
+
+    this.tracers.push(tracer);
+
+    return tracer;
+  }
+
+  removeTracer(tracer: Tracer) {
+    this.tracers = this.tracers.filter(t => t !== tracer);
+  }
+
+  flush() {
+    this.tracers.forEach(tracer => tracer.flush());
+  }
+}
+
+export function setTracing(enabled: boolean) {
+  if (enabled) {
+    TRACER = new TracerProxy();
+  } else {
+    TRACER = undefined;
+  }
+}
+
+export function createTracer(_signal: Signal<unknown> | Watcher<unknown>, immediate = false) {
+  const signal = _signal as ComputedSignal<unknown>;
+  return createTracerFromId(signal._opts.id, immediate);
+}
+
+export function createTracerFromId(id: string, immediate = false) {
+  if (!TRACER) {
+    throw new Error('Tracing is not enabled');
+  }
+
+  return TRACER.createTracer(id, immediate);
+}
+
+export function removeTracer(tracer: Tracer) {
+  if (!TRACER) {
+    throw new Error('Tracing is not enabled');
+  }
+
+  TRACER.removeTracer(tracer);
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+import type { SignalScope } from './hooks.js';
+
+export interface Signal<T = unknown> {
+  get(): T;
+}
+
+export interface WriteableSignal<T> extends Signal<T> {
+  set(value: T): void;
+}
+
+export type AsyncSignal<T> = Signal<AsyncResult<T>>;
+
+export type SignalCompute<T> = (prev: T | undefined) => T;
+
+export type SignalAsyncCompute<T> = (prev: T | undefined) => T | Promise<T>;
+
+export type SignalEquals<T> = (prev: T, next: T) => boolean;
+
+export type SignalSubscription = {
+  update?(): void;
+  unsubscribe?(): void;
+};
+
+export type SignalSubscribe<T> = (
+  get: () => T | undefined,
+  set: (value: T) => void,
+) => SignalSubscription | undefined | void;
+
+export interface SignalOptions<T, Args extends unknown[]> {
+  equals?: SignalEquals<T> | false;
+  id?: string;
+  desc?: string;
+  params?: string;
+  scope?: SignalScope;
+  paramKey?: (...args: Args) => string;
+}
+
+export interface SignalOptionsWithInit<T, Args extends unknown[]> extends SignalOptions<T, Args> {
+  initValue: T;
+}
+
+export interface AsyncBaseResult<T> {
+  invalidate(): void;
+  await(): T;
+}
+
+export interface AsyncPending<T> extends AsyncBaseResult<T> {
+  result: undefined;
+  error: unknown;
+  isPending: boolean;
+  isReady: false;
+  isError: boolean;
+  isSuccess: boolean;
+  didResolve: boolean;
+}
+
+export interface AsyncReady<T> extends AsyncBaseResult<T> {
+  result: T;
+  error: unknown;
+  isPending: boolean;
+  isReady: true;
+  isError: boolean;
+  isSuccess: boolean;
+  didResolve: boolean;
+}
+
+export type AsyncResult<T> = AsyncPending<T> | AsyncReady<T>;
+
+export interface AsyncTask<T, Args extends unknown[] = unknown[]> {
+  result: T | undefined;
+  error: unknown;
+  isPending: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+  isReady: boolean;
+
+  run(...args: Args): Promise<T>;
+}
+
+export interface WatcherListenerOptions {
+  immediate?: boolean;
+}
+
+export interface Watcher<T> {
+  addListener(listener: (value: T) => void, opts?: WatcherListenerOptions): () => void;
+}

package/src/utils.ts

@@ -0,0 +1,83 @@
+import { createComputedSignal, createSubscriptionSignal } from './signals.js';
+
+const objectToIdMap = new WeakMap<object, string>();
+let nextId = 1;
+
+export function getObjectId(obj: object): string {
+  let id = objectToIdMap.get(obj);
+  if (id === undefined) {
+    id = `obj-${nextId++}`;
+    objectToIdMap.set(obj, id);
+  }
+  return id;
+}
+
+// Handle basic POJOs and arrays recursively
+function isPOJO(obj: object): boolean {
+  return Object.getPrototypeOf(obj) === Object.prototype;
+}
+
+function isPlainArray(arr: unknown): arr is unknown[] {
+  return Array.isArray(arr);
+}
+
+export function hashValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+
+  switch (typeof value) {
+    case 'number':
+    case 'boolean':
+    case 'string':
+      return String(value);
+    case 'bigint':
+      return value.toString();
+    case 'symbol':
+      return String(value);
+    case 'object': {
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+      if (isPlainArray(value)) {
+        return `[${value.map(hashValue).join(',')}]`;
+      }
+      if (isPOJO(value)) {
+        const entries = [
+          ...Object.entries(value),
+          ...Object.getOwnPropertySymbols(value).map(sym => [sym, value[sym as keyof typeof value]]),
+        ].sort(([a], [b]) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0));
+
+        return `{ ${entries.map(([k, v]) => `${String(k)}: ${hashValue(v)}`).join(', ')} }`;
+      }
+      return getObjectId(value);
+    }
+    case 'function':
+      return getObjectId(value);
+    default:
+      return getObjectId(value as object);
+  }
+}
+
+let UNKNOWN_SUBSCRIPTION_ID = 0;
+let UNKNOWN_COMPUTED_ID = 0;
+let UNKNOWN_ASYNC_COMPUTED_ID = 0;
+
+const UNKNOWN_SIGNAL_NAMES = new Map<object, string>();
+
+export function getUnknownSignalFnName(fn: object, makeSignal: unknown) {
+  let name = UNKNOWN_SIGNAL_NAMES.get(fn);
+
+  if (name === undefined) {
+    if (makeSignal === createSubscriptionSignal) {
+      name = `unknownSubscription${UNKNOWN_SUBSCRIPTION_ID++}`;
+    } else if (makeSignal === createComputedSignal) {
+      name = `unknownComputed${UNKNOWN_COMPUTED_ID++}`;
+    } else {
+      name = `unknownAsyncComputed${UNKNOWN_ASYNC_COMPUTED_ID++}`;
+    }
+
+    UNKNOWN_SIGNAL_NAMES.set(fn, name);
+  }
+
+  return name;
+}

package/tsconfig.json

@@ -5,7 +5,8 @@
     "rootDir": "src",
     "declaration": true,
     "declarationMap": true,
-    "sourceMap": true
+    "sourceMap": true,
+    "jsx": "react-jsx"
   },
   "include": ["src"],
   "exclude": ["**/__tests__"]

package/vitest.workspace.ts

@@ -0,0 +1,24 @@
+/// <reference types="@vitest/browser/providers/playwright" />
+
+import { defineWorkspace } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineWorkspace([
+  {
+    test: {
+      include: ['src/__tests__/**/*.test.ts'],
+      name: 'unit',
+      environment: 'node',
+    },
+  },
+  {
+    plugins: [react()],
+    test: {
+      browser: {
+        enabled: true,
+        provider: 'playwright',
+        instances: [{ browser: 'chromium' }],
+      },
+    },
+  },
+]);