@epoch32/visage 0.0.0-stage → 1.0.0

package/src/signals/computed.ts

@@ -0,0 +1,217 @@
+/**
+ * Visage Lazy, Glitch-Free Computed State Engine
+ */
+import type { Scope } from "./scope";
+import { currentScope, currentSubscriber, setCurrentScope, setCurrentSubscriber } from "./system";
+import {
+  COMPUTED_BRAND,
+  type ComputedOptions,
+  type IDependency,
+  type ISubscriber,
+  type ReadonlySignal,
+  SubscriberState
+} from "./types";
+
+export type { ComputedOptions };
+
+/**
+ * Computed / Derived reactive state (Lazy, Glitch-Free, Memoized)
+ */
+export class Computed<T> implements ISubscriber, IDependency {
+  [COMPUTED_BRAND] = true as const;
+  private _fn: () => T;
+  private _value!: T;
+  private _subscribers: Set<ISubscriber> = new Set();
+  sources: Set<IDependency> = new Set();
+  sourceVersions: Map<IDependency, number> = new Map();
+  state: SubscriberState = SubscriberState.DIRTY;
+  scope: Scope | null;
+  version = 0;
+
+  constructor(fn: () => T) {
+    this._fn = fn;
+    this.scope = currentScope;
+    if (currentScope) {
+      currentScope.addSubscriber(this);
+    }
+  }
+
+  get(): T {
+    if (this.state === SubscriberState.DISPOSED) {
+      return this._fn();
+    }
+
+    if (currentSubscriber !== null && currentSubscriber.state !== SubscriberState.DISPOSED) {
+      this._subscribers.add(currentSubscriber);
+      currentSubscriber.sources.add(this);
+      currentSubscriber.sourceVersions.set(this, this.version);
+    }
+
+    if (this.state === SubscriberState.DIRTY || this.state === SubscriberState.CHECK_DIRTY) {
+      this.updateIfNecessary();
+    }
+
+    return this._value;
+  }
+
+  get value(): T {
+    return this.get();
+  }
+
+  removeSubscriber(sub: ISubscriber): void {
+    this._subscribers.delete(sub);
+  }
+
+  markDirty(targetState: SubscriberState = SubscriberState.CHECK_DIRTY): void {
+    if (this.state >= targetState || this.state === SubscriberState.DISPOSED) {
+      return;
+    }
+    this.state = targetState;
+
+    for (const sub of this._subscribers) {
+      sub.markDirty(SubscriberState.CHECK_DIRTY);
+    }
+  }
+
+  updateIfNecessary(): boolean {
+    if (this.state === SubscriberState.DIRTY) {
+      const prev = this._value;
+      this.recompute();
+      return !Object.is(prev, this._value);
+    }
+
+    if (this.state === SubscriberState.CHECK_DIRTY) {
+      let anyChanged = false;
+      for (const source of this.sources) {
+        if (source instanceof Computed) {
+          source.updateIfNecessary();
+        }
+        const lastVersion = this.sourceVersions.get(source);
+        if (lastVersion !== undefined && lastVersion !== source.version) {
+          anyChanged = true;
+        }
+      }
+
+      if (anyChanged) {
+        const prev = this._value;
+        this.recompute();
+        return !Object.is(prev, this._value);
+      }
+
+      this.state = SubscriberState.CLEAN;
+      return false;
+    }
+
+    return false;
+  }
+
+  private recompute(): void {
+    this.cleanupSources();
+
+    const prevSubscriber = currentSubscriber;
+    setCurrentSubscriber(this);
+    const prevScope = currentScope;
+    setCurrentScope(this.scope);
+
+    try {
+      const next = this._fn();
+      if (!Object.is(this._value, next)) {
+        this._value = next;
+        this.version++;
+      }
+      this.state = SubscriberState.CLEAN;
+    } finally {
+      setCurrentSubscriber(prevSubscriber);
+      setCurrentScope(prevScope);
+    }
+  }
+
+  private cleanupSources(): void {
+    for (const source of this.sources) {
+      source.removeSubscriber(this);
+    }
+    this.sources.clear();
+    this.sourceVersions.clear();
+  }
+
+  dispose(): void {
+    if (this.state === SubscriberState.DISPOSED) return;
+    this.state = SubscriberState.DISPOSED;
+    this.cleanupSources();
+    this._subscribers.clear();
+  }
+}
+
+/**
+ * Factory for creating lazy, memoized, glitch-free computed signals.
+ *
+ * Computed values are only recalculated when one of their recorded reactive
+ * dependencies changes and the value is actually accessed.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(2);
+ * const double = computed(() => count() * 2);
+ *
+ * console.log(double()); // 4
+ *
+ * // In JSX, passes directly or as a function
+ * <div>Doubled value: {double}</div>
+ * ```
+ *
+ * @param fn - The pure reactive computation function
+ * @param options - Optional debug metadata and internal flags
+ * @returns A readonly reactive signal function accessor
+ */
+export function computed<T>(fn: () => T, options?: ComputedOptions): ReadonlySignal<T> {
+  const isInternal = options?.internal ?? false;
+  const customName = options?.name;
+
+  const c = new Computed(fn);
+
+  const accessor = ((): T => c.get()) as ReadonlySignal<T>;
+
+  Object.defineProperties(accessor, {
+    [COMPUTED_BRAND]: { value: true },
+    get: { value: () => c.get() },
+    value: { get: () => c.get() }
+  });
+
+  if (!isInternal && typeof window !== "undefined" && (window as any).__VISAGE_DEVTOOLS__) {
+    const devtools = (window as any).__VISAGE_DEVTOOLS__;
+    const sigId = devtools.registerSignal({
+      name: customName,
+      type: "computed",
+      getValue: () => c.get(),
+      version: () => c.version,
+      subscribersCount: () => (c as any)._subscribers?.size ?? 0,
+      dependencies: () =>
+        Array.from(c.sources ?? [])
+          .map((src: any) => (src as any)._devId)
+          .filter(Boolean),
+      dependents: () =>
+        Array.from((c as any)._subscribers ?? [])
+          .map((sub: any) => sub._devId)
+          .filter(Boolean)
+    });
+    (c as any)._devId = sigId;
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        devtools.unregisterSignal(sigId);
+      });
+    }
+  }
+
+  return accessor;
+}
+
+/**
+ * Solid-compatible alias for `computed()`.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(5);
+ * const squared = createMemo(() => count() ** 2);
+ * ```
+ */
+export const createMemo = computed;

package/src/signals/context.ts

@@ -0,0 +1,89 @@
+import { type Child, insertChild } from "../dom/render";
+import { getActiveScope, runInScope, Scope } from "./scope";
+import { untrack } from "./system";
+
+export interface Context<T> {
+  id: symbol;
+  defaultValue: T;
+  Provider: (props: { value: T; children: Child }) => any;
+}
+
+/**
+ * Create a reactive Context for dependency injection across the component tree.
+ *
+ * Context allows passing state and utilities down the component tree without
+ * manually drilling props through every intermediate component.
+ *
+ * @example
+ * ```tsx
+ * const ThemeContext = createContext<"light" | "dark">("light");
+ *
+ * // Provide value in parent
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <Header />
+ *     </ThemeContext.Provider>
+ *   );
+ * }
+ *
+ * // Consume value in descendant
+ * function Header() {
+ *   const theme = useContext(ThemeContext);
+ *   return <div>Current theme: {theme}</div>;
+ * }
+ * ```
+ */
+export function createContext<T>(defaultValue: T): Context<T>;
+export function createContext<T>(): Context<T | undefined>;
+export function createContext<T>(defaultValue?: T): Context<T | undefined> {
+  const id = Symbol("visage.context");
+
+  const context: Context<T | undefined> = {
+    id,
+    defaultValue,
+    Provider: (props: { value: T | undefined; children: Child }): any => {
+      const parentScope = getActiveScope();
+      const scope = new Scope(parentScope);
+
+      if (!scope.context) {
+        scope.context = new Map(parentScope?.context);
+      }
+      scope.context.set(id, props.value);
+
+      return runInScope(scope, () => {
+        const content =
+          typeof props.children === "function"
+            ? untrack(() => (props.children as (...args: any[]) => any)())
+            : props.children;
+        if (typeof document !== "undefined") {
+          const frag = document.createDocumentFragment();
+          insertChild(frag, content);
+          return frag;
+        }
+        return content;
+      });
+    }
+  };
+
+  return context;
+}
+
+/**
+ * Consume a Context value from the nearest ancestor Provider, falling back to defaultValue.
+ *
+ * @param context - The Context object returned from `createContext`
+ * @returns The current context value
+ */
+export function useContext<T>(context: Context<T>): T {
+  let scope = getActiveScope();
+
+  while (scope) {
+    if (scope.context?.has(context.id)) {
+      return scope.context.get(context.id);
+    }
+    scope = scope.parent;
+  }
+
+  return context.defaultValue;
+}

package/src/signals/effect.ts

@@ -0,0 +1,161 @@
+/**
+ * Visage Reactive Side-Effect Runner
+ */
+import { Computed } from "./computed";
+import type { Scope } from "./scope";
+import {
+  addPendingEffect,
+  batchDepth,
+  currentScope,
+  currentSubscriber,
+  flushEffects,
+  removePendingEffect,
+  setCurrentScope,
+  setCurrentSubscriber
+} from "./system";
+import { type CleanupFn, type IDependency, type ISubscriber, SubscriberState } from "./types";
+
+/**
+ * Side-effect runner with automatic dependency tracking and disposal
+ */
+export class Effect implements ISubscriber {
+  private _fn: () => void | CleanupFn;
+  sources: Set<IDependency> = new Set();
+  sourceVersions: Map<IDependency, number> = new Map();
+  cleanups: CleanupFn[] = [];
+  state: SubscriberState = SubscriberState.DIRTY;
+  scope: Scope | null;
+
+  constructor(fn: () => void | CleanupFn) {
+    this._fn = fn;
+    this.scope = currentScope;
+    if (currentScope) {
+      currentScope.addSubscriber(this);
+    }
+    this.run();
+  }
+
+  addCleanup(fn: CleanupFn): void {
+    this.cleanups.push(fn);
+  }
+
+  private runCleanups(): void {
+    for (let i = this.cleanups.length - 1; i >= 0; i--) {
+      try {
+        this.cleanups[i]!();
+      } catch (e) {
+        console.error("Error in effect cleanup:", e);
+      }
+    }
+    this.cleanups = [];
+  }
+
+  markDirty(targetState: SubscriberState = SubscriberState.DIRTY): void {
+    if (this.state >= targetState || this.state === SubscriberState.DISPOSED) {
+      return;
+    }
+    this.state = targetState;
+    addPendingEffect(this);
+
+    if (batchDepth === 0) {
+      flushEffects();
+    }
+  }
+
+  run(): void {
+    if (this.state === SubscriberState.DISPOSED) return;
+
+    if (this.state === SubscriberState.CHECK_DIRTY) {
+      let isDirty = false;
+      for (const source of this.sources) {
+        if (source instanceof Computed) {
+          source.updateIfNecessary();
+        }
+        const lastVersion = this.sourceVersions.get(source);
+        if (lastVersion !== undefined && lastVersion !== source.version) {
+          isDirty = true;
+        }
+      }
+      if (!isDirty) {
+        this.state = SubscriberState.CLEAN;
+        return;
+      }
+    }
+
+    this.runCleanups();
+    this.cleanupSources();
+
+    const prevSubscriber = currentSubscriber;
+    setCurrentSubscriber(this);
+    const prevScope = currentScope;
+    setCurrentScope(this.scope);
+
+    try {
+      this.state = SubscriberState.CLEAN;
+      const res = this._fn();
+      if (typeof res === "function") {
+        this.cleanups.push(res);
+      }
+    } finally {
+      setCurrentSubscriber(prevSubscriber);
+      setCurrentScope(prevScope);
+    }
+  }
+
+  private cleanupSources(): void {
+    for (const source of this.sources) {
+      source.removeSubscriber(this);
+    }
+    this.sources.clear();
+    this.sourceVersions.clear();
+  }
+
+  dispose(): void {
+    if (this.state === SubscriberState.DISPOSED) return;
+    this.state = SubscriberState.DISPOSED;
+    this.runCleanups();
+    this.cleanupSources();
+    removePendingEffect(this);
+  }
+}
+
+/**
+ * Execute side-effects reactively when dependencies change.
+ *
+ * Runs immediately upon creation and tracks any signals read within `fn`.
+ * When dependencies change, re-execution is scheduled automatically.
+ *
+ * An optional cleanup function can be returned from `fn`, which runs
+ * before the next re-execution and when the enclosing scope is disposed.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(0);
+ *
+ * effect(() => {
+ *   console.log("Count changed to:", count());
+ *
+ *   const timer = setInterval(() => console.log("tick"), 1000);
+ *   return () => clearInterval(timer);
+ * });
+ * ```
+ *
+ * @param fn - The side-effect function, optionally returning a cleanup function
+ * @returns A manual disposal cleanup function
+ */
+export function effect(fn: () => void | CleanupFn): CleanupFn {
+  const eff = new Effect(fn);
+  return () => eff.dispose();
+}
+
+/**
+ * Solid / React-compatible alias for `effect()`.
+ *
+ * @example
+ * ```tsx
+ * createEffect(() => {
+ *   document.title = `Total: ${count()}`;
+ * });
+ * ```
+ */
+export const createEffect = effect;

package/src/signals/index.ts

@@ -0,0 +1,57 @@
+export {
+  Computed,
+  type ComputedOptions,
+  computed,
+  createMemo
+} from "./computed";
+
+export {
+  type Context,
+  createContext,
+  useContext
+} from "./context";
+
+export {
+  createEffect,
+  Effect,
+  effect
+} from "./effect";
+
+export {
+  createRoot,
+  getActiveScope,
+  onCleanup,
+  runInScope,
+  Scope
+} from "./scope";
+
+export {
+  createSignal,
+  Signal,
+  type SignalOptions,
+  signal
+} from "./signal";
+
+export {
+  createStore,
+  mutateStore,
+  type Store,
+  unwrapStore
+} from "./store";
+
+export {
+  batch,
+  untrack
+} from "./system";
+
+export {
+  type CleanupFn,
+  COMPUTED_BRAND,
+  type Dependency,
+  isSignal,
+  type ReadonlySignal,
+  SIGNAL_BRAND,
+  type Subscriber,
+  SubscriberState,
+  type WritableSignal
+} from "./types";

package/src/signals/scope.ts

@@ -0,0 +1,132 @@
+/**
+ * Visage Reactive Scope & Lifecycle Management
+ */
+import { currentScope, currentSubscriber, getCurrentScope, setCurrentScope } from "./system";
+import type { CleanupFn, ISubscriber } from "./types";
+
+/**
+ * Reactive Scope for lifecycle and automatic memory management
+ */
+export class Scope {
+  subscribers = new Set<ISubscriber>();
+  cleanups: CleanupFn[] = [];
+  parent: Scope | null = null;
+  isDisposed = false;
+  context?: Map<symbol, any>;
+
+  constructor(parent: Scope | null = currentScope) {
+    this.parent = parent;
+    if (parent && !parent.isDisposed) {
+      parent.cleanups.push(() => this.dispose());
+      if (parent.context) {
+        this.context = new Map(parent.context);
+      }
+    }
+  }
+
+  addSubscriber(sub: ISubscriber): void {
+    if (this.isDisposed) return;
+    this.subscribers.add(sub);
+  }
+
+  addCleanup(fn: CleanupFn): void {
+    if (this.isDisposed) {
+      fn();
+      return;
+    }
+    this.cleanups.push(fn);
+  }
+
+  dispose(): void {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    for (const sub of this.subscribers) {
+      sub.dispose();
+    }
+    this.subscribers.clear();
+
+    for (let i = this.cleanups.length - 1; i >= 0; i--) {
+      try {
+        this.cleanups[i]!();
+      } catch (err) {
+        console.error("Error during cleanup:", err);
+      }
+    }
+    this.cleanups = [];
+  }
+}
+
+/**
+ * Register a cleanup callback for the current running effect or active scope.
+ *
+ * Runs automatically when the enclosing component/scope unmounts or before
+ * the effect re-executes.
+ *
+ * @example
+ * ```tsx
+ * function TimerComponent() {
+ *   const id = setInterval(() => console.log("tick"), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return <div>Timer running</div>;
+ * }
+ * ```
+ */
+export function onCleanup(fn: CleanupFn): void {
+  if (currentSubscriber && "addCleanup" in currentSubscriber) {
+    (currentSubscriber as any).addCleanup(fn);
+  } else if (currentScope) {
+    currentScope.addCleanup(fn);
+  }
+}
+
+/**
+ * Create an isolated reactive root scope that outlives the current execution context.
+ *
+ * Computations and signals created inside `fn` will not be tied to any parent scope
+ * and will persist until the provided `dispose` callback is invoked.
+ *
+ * @example
+ * ```tsx
+ * const dispose = createRoot((dispose) => {
+ *   const count = signal(0);
+ *   effect(() => console.log(count()));
+ *   return dispose;
+ * });
+ *
+ * // Later, dispose of all memory & subscribers
+ * dispose();
+ * ```
+ *
+ * @param fn - A factory function receiving the `dispose` callback
+ * @returns The return value of `fn`
+ */
+export function createRoot<T>(fn: (dispose: () => void) => T): T {
+  const prevScope = currentScope;
+  const scope = new Scope(null);
+  setCurrentScope(scope);
+  try {
+    return fn(() => scope.dispose());
+  } finally {
+    setCurrentScope(prevScope);
+  }
+}
+
+/**
+ * Run a function with a specified reactive scope active.
+ */
+export function runInScope<T>(scope: Scope | null, fn: () => T): T {
+  const prevScope = currentScope;
+  setCurrentScope(scope);
+  try {
+    return fn();
+  } finally {
+    setCurrentScope(prevScope);
+  }
+}
+
+/**
+ * Get the currently active reactive scope.
+ */
+export function getActiveScope(): Scope | null {
+  return getCurrentScope();
+}