@zenithbuild/core 0.6.2 → 0.6.4

package/core/reactivity/tracking.ts

@@ -1,167 +0,0 @@
-/**
- * Zenith Reactivity Tracking System
- * 
- * This module provides the core dependency tracking mechanism used by
- * signals, effects, and memos. It uses a stack-based approach to track
- * which reactive values are accessed during effect/memo execution.
- * 
- * Key concepts:
- * - Subscriber: A function that should be called when a dependency changes
- * - Tracking context: The currently executing effect/memo that should collect dependencies
- * - Dependency: A reactive value that an effect/memo depends on
- */
-
-/**
- * A subscriber is a function that gets called when a reactive value changes
- */
-export type Subscriber = () => void
-
-/**
- * Tracking context - represents an effect or memo that is collecting dependencies
- */
-export interface TrackingContext {
-  /** The function to call when dependencies change */
-  execute: Subscriber
-  /** Set of dependency subscriber sets this context is registered with */
-  dependencies: Set<Set<Subscriber>>
-}
-
-/**
- * Stack of currently executing tracking contexts
- * When an effect runs, it pushes itself onto this stack.
- * When a signal is read, it registers the top of the stack as a subscriber.
- */
-const trackingStack: TrackingContext[] = []
-
-/**
- * Flag to disable tracking (used by zenUntrack)
- */
-let trackingDisabled = false
-
-/**
- * Batch depth counter - when > 0, effect execution is deferred
- */
-let batchDepth = 0
-
-/**
- * Queue of effects to run after batch completes
- */
-const pendingEffects: Set<Subscriber> = new Set()
-
-/**
- * Get the current tracking context (if any)
- */
-export function getCurrentContext(): TrackingContext | undefined {
-  if (trackingDisabled) return undefined
-  return trackingStack[trackingStack.length - 1]
-}
-
-/**
- * Push a new tracking context onto the stack
- */
-export function pushContext(context: TrackingContext): void {
-  trackingStack.push(context)
-}
-
-/**
- * Pop the current tracking context from the stack
- */
-export function popContext(): TrackingContext | undefined {
-  return trackingStack.pop()
-}
-
-/**
- * Track a dependency - called when a reactive value is read
- * 
- * @param subscribers - The subscriber set of the reactive value being read
- */
-export function trackDependency(subscribers: Set<Subscriber>): void {
-  const context = getCurrentContext()
-  
-  if (context) {
-    // Register this effect as a subscriber to the signal
-    subscribers.add(context.execute)
-    // Track that this effect depends on this signal
-    context.dependencies.add(subscribers)
-  }
-}
-
-/**
- * Notify subscribers that a reactive value has changed
- * 
- * @param subscribers - The subscriber set to notify
- */
-export function notifySubscribers(subscribers: Set<Subscriber>): void {
-  // Copy subscribers to avoid issues if the set is modified during iteration
-  const toNotify = [...subscribers]
-  
-  for (const subscriber of toNotify) {
-    if (batchDepth > 0) {
-      // Batching - defer effect execution
-      pendingEffects.add(subscriber)
-    } else {
-      // Execute immediately
-      subscriber()
-    }
-  }
-}
-
-/**
- * Clean up a tracking context - remove it from all dependency sets
- * 
- * @param context - The context to clean up
- */
-export function cleanupContext(context: TrackingContext): void {
-  for (const deps of context.dependencies) {
-    deps.delete(context.execute)
-  }
-  context.dependencies.clear()
-}
-
-/**
- * Run a function without tracking dependencies
- * 
- * @param fn - The function to run
- * @returns The return value of the function
- */
-export function runUntracked<T>(fn: () => T): T {
-  const wasDisabled = trackingDisabled
-  trackingDisabled = true
-  try {
-    return fn()
-  } finally {
-    trackingDisabled = wasDisabled
-  }
-}
-
-/**
- * Start a batch - defer effect execution until batch ends
- */
-export function startBatch(): void {
-  batchDepth++
-}
-
-/**
- * End a batch - run all pending effects
- */
-export function endBatch(): void {
-  batchDepth--
-  
-  if (batchDepth === 0 && pendingEffects.size > 0) {
-    // Run all pending effects
-    const effects = [...pendingEffects]
-    pendingEffects.clear()
-    
-    for (const effect of effects) {
-      effect()
-    }
-  }
-}
-
-/**
- * Check if currently inside a batch
- */
-export function isBatching(): boolean {
-  return batchDepth > 0
-}
-

package/core/reactivity/zen-batch.ts

@@ -1,57 +0,0 @@
-/**
- * Zenith Batch - Deferred Effect Execution
- * 
- * Batching allows you to make multiple reactive updates without
- * triggering effects until all updates are complete. This improves
- * performance by preventing redundant effect executions.
- * 
- * Features:
- * - Groups multiple mutations
- * - Defers effect execution until batch completes
- * - Supports nested batches
- * - Automatically flushes on completion
- * 
- * @example
- * ```ts
- * const firstName = zenSignal('John')
- * const lastName = zenSignal('Doe')
- * 
- * zenEffect(() => {
- *   console.log(`${firstName()} ${lastName()}`)
- * })
- * // Logs: "John Doe"
- * 
- * // Without batch - effect runs twice
- * firstName('Jane')  // Logs: "Jane Doe"
- * lastName('Smith')  // Logs: "Jane Smith"
- * 
- * // With batch - effect runs once
- * zenBatch(() => {
- *   firstName('Bob')
- *   lastName('Brown')
- * })
- * // Logs: "Bob Brown" (only once)
- * ```
- */
-
-import { startBatch, endBatch } from './tracking'
-
-/**
- * Execute a function with batched updates
- * 
- * All reactive updates inside the batch will be collected,
- * and effects will only run once after the batch completes.
- * 
- * @param fn - The function to execute
- * @returns The return value of the function
- */
-export function zenBatch<T>(fn: () => T): T {
-  startBatch()
-  
-  try {
-    return fn()
-  } finally {
-    endBatch()
-  }
-}
-

package/core/reactivity/zen-effect.ts

@@ -1,139 +0,0 @@
-/**
- * Zenith Effect - Auto-Tracked Side Effect
- * 
- * Effects are functions that automatically track their reactive dependencies
- * and re-run when those dependencies change. They are the bridge between
- * reactive state and side effects (DOM updates, logging, API calls, etc.)
- * 
- * Features:
- * - Automatic dependency tracking (no dependency arrays)
- * - Runs immediately on creation
- * - Re-runs when dependencies change
- * - Supports cleanup functions
- * - Can be manually disposed
- * 
- * @example
- * ```ts
- * const count = zenSignal(0)
- * 
- * // Effect runs immediately, then re-runs when count changes
- * const dispose = zenEffect(() => {
- *   console.log('Count:', count())
- *   
- *   // Optional cleanup - runs before next execution or on dispose
- *   return () => {
- *     console.log('Cleanup')
- *   }
- * })
- * 
- * count(1) // Logs: "Cleanup", then "Count: 1"
- * 
- * dispose() // Cleanup and stop watching
- * ```
- */
-
-import {
-  pushContext,
-  popContext,
-  cleanupContext,
-  type TrackingContext
-} from './tracking'
-
-/**
- * Effect function type - can optionally return a cleanup function
- */
-export type EffectFn = () => void | (() => void)
-
-/**
- * Dispose function - call to stop the effect
- */
-export type DisposeFn = () => void
-
-/**
- * Effect state
- */
-interface EffectState {
-  /** The effect function */
-  fn: EffectFn
-  /** Current cleanup function (if any) */
-  cleanup: (() => void) | null
-  /** Tracking context for dependency collection */
-  context: TrackingContext
-  /** Whether the effect has been disposed */
-  disposed: boolean
-}
-
-/**
- * Create an auto-tracked side effect
- * 
- * @param fn - The effect function to run
- * @returns A dispose function to stop the effect
- */
-export function zenEffect(fn: EffectFn): DisposeFn {
-  const state: EffectState = {
-    fn,
-    cleanup: null,
-    context: {
-      execute: () => runEffect(state),
-      dependencies: new Set()
-    },
-    disposed: false
-  }
-  
-  // Run the effect immediately
-  runEffect(state)
-  
-  // Return dispose function
-  return () => disposeEffect(state)
-}
-
-/**
- * Run an effect, tracking dependencies
- */
-function runEffect(state: EffectState): void {
-  if (state.disposed) return
-  
-  // Run cleanup from previous execution
-  if (state.cleanup) {
-    state.cleanup()
-    state.cleanup = null
-  }
-  
-  // Clean up old dependencies
-  cleanupContext(state.context)
-  
-  // Push this effect onto the tracking stack
-  pushContext(state.context)
-  
-  try {
-    // Run the effect function
-    const result = state.fn()
-    
-    // Store cleanup if returned
-    if (typeof result === 'function') {
-      state.cleanup = result
-    }
-  } finally {
-    // Pop from tracking stack
-    popContext()
-  }
-}
-
-/**
- * Dispose an effect - run cleanup and stop watching
- */
-function disposeEffect(state: EffectState): void {
-  if (state.disposed) return
-  
-  state.disposed = true
-  
-  // Run cleanup
-  if (state.cleanup) {
-    state.cleanup()
-    state.cleanup = null
-  }
-  
-  // Remove from all dependency sets
-  cleanupContext(state.context)
-}
-

package/core/reactivity/zen-memo.ts

@@ -1,146 +0,0 @@
-/**
- * Zenith Memo - Computed/Derived Value
- * 
- * A memo is a lazily-evaluated, cached computation that automatically
- * tracks its dependencies and only recomputes when those dependencies change.
- * 
- * Features:
- * - Lazy evaluation (only computes when read)
- * - Automatic dependency tracking
- * - Cached value until dependencies change
- * - Read-only (no setter)
- * 
- * @example
- * ```ts
- * const firstName = zenSignal('John')
- * const lastName = zenSignal('Doe')
- * 
- * // Memo computes full name, tracks firstName and lastName
- * const fullName = zenMemo(() => `${firstName()} ${lastName()}`)
- * 
- * console.log(fullName()) // "John Doe"
- * 
- * firstName('Jane')
- * console.log(fullName()) // "Jane Doe" (recomputed)
- * console.log(fullName()) // "Jane Doe" (cached, no recomputation)
- * ```
- */
-
-import {
-  pushContext,
-  popContext,
-  cleanupContext,
-  trackDependency,
-  type TrackingContext,
-  type Subscriber
-} from './tracking'
-
-/**
- * Memo interface - callable getter
- */
-export interface Memo<T> {
-  /** Get the current computed value */
-  (): T
-  /** Peek at cached value without tracking (may be stale) */
-  peek(): T
-}
-
-/**
- * Memo state
- */
-interface MemoState<T> {
-  /** The computation function */
-  fn: () => T
-  /** Cached value */
-  value: T | undefined
-  /** Whether the cached value is valid */
-  dirty: boolean
-  /** Tracking context for dependency collection */
-  context: TrackingContext
-  /** Subscribers to this memo */
-  subscribers: Set<Subscriber>
-  /** Whether this is the first computation */
-  initialized: boolean
-}
-
-/**
- * Create a memoized computed value
- * 
- * @param fn - The computation function
- * @returns A memo that can be read to get the computed value
- */
-export function zenMemo<T>(fn: () => T): Memo<T> {
-  const state: MemoState<T> = {
-    fn,
-    value: undefined,
-    dirty: true,
-    context: {
-      execute: () => markDirty(state),
-      dependencies: new Set()
-    },
-    subscribers: new Set(),
-    initialized: false
-  }
-  
-  function memo(): T {
-    // Track that something is reading this memo
-    trackDependency(state.subscribers)
-    
-    // Recompute if dirty
-    if (state.dirty) {
-      computeMemo(state)
-    }
-    
-    return state.value as T
-  }
-  
-  // Add peek method
-  ;(memo as Memo<T>).peek = function(): T {
-    // Return cached value without tracking or recomputing
-    if (state.dirty && !state.initialized) {
-      computeMemo(state)
-    }
-    return state.value as T
-  }
-  
-  return memo as Memo<T>
-}
-
-/**
- * Compute the memo value, tracking dependencies
- */
-function computeMemo<T>(state: MemoState<T>): void {
-  // Clean up old dependencies
-  cleanupContext(state.context)
-  
-  // Push this memo onto the tracking stack
-  pushContext(state.context)
-  
-  try {
-    // Compute new value
-    state.value = state.fn()
-    state.dirty = false
-    state.initialized = true
-  } finally {
-    // Pop from tracking stack
-    popContext()
-  }
-}
-
-/**
- * Mark the memo as dirty (needs recomputation)
- * Called when a dependency changes
- */
-function markDirty<T>(state: MemoState<T>): void {
-  if (!state.dirty) {
-    state.dirty = true
-    
-    // Notify any effects/memos that depend on this memo
-    // Copy to avoid issues during iteration
-    const subscribers = [...state.subscribers]
-    for (const subscriber of subscribers) {
-      subscriber()
-    }
-  }
-}
-

package/core/reactivity/zen-ref.ts

@@ -1,52 +0,0 @@
-/**
- * Zenith Ref - Mutable Reference Container
- * 
- * A ref is a mutable container that does NOT trigger reactivity.
- * It's useful for:
- * - Storing DOM element references
- * - Imperative escape hatches
- * - Values that change but shouldn't trigger re-renders
- * 
- * Features:
- * - Mutable `.current` property
- * - Does NOT track dependencies
- * - Does NOT trigger effects
- * - Persists across effect re-runs
- * 
- * @example
- * ```ts
- * // DOM reference
- * const inputRef = zenRef<HTMLInputElement>()
- * 
- * // Later, after mount
- * inputRef.current = document.querySelector('input')
- * inputRef.current?.focus()
- * 
- * // Mutable value that doesn't trigger reactivity
- * const previousValue = zenRef(0)
- * previousValue.current = count() // No effect triggered
- * ```
- */
-
-/**
- * Ref interface - mutable container with .current
- */
-export interface Ref<T> {
-  /** The current value */
-  current: T
-}
-
-/**
- * Create a mutable reference container
- * 
- * @param initialValue - The initial value (optional, defaults to undefined)
- * @returns A ref object with a mutable .current property
- */
-export function zenRef<T>(): Ref<T | undefined>
-export function zenRef<T>(initialValue: T): Ref<T>
-export function zenRef<T>(initialValue?: T): Ref<T | undefined> {
-  return {
-    current: initialValue
-  }
-}
-

package/core/reactivity/zen-signal.ts

@@ -1,121 +0,0 @@
-/**
- * Zenith Signal - Atomic Reactive Value
- * 
- * A signal is the most basic reactive primitive. It holds a single value
- * and notifies subscribers when the value changes.
- * 
- * Features:
- * - Getter/setter model
- * - Automatic dependency tracking
- * - Fine-grained reactivity (no component re-rendering)
- * 
- * @example
- * ```ts
- * const count = zenSignal(0)
- * 
- * // Read value
- * console.log(count()) // 0
- * 
- * // Write value
- * count(1)
- * 
- * // Or use .value
- * count.value = 2
- * console.log(count.value) // 2
- * ```
- */
-
-import { trackDependency, notifySubscribers, type Subscriber } from './tracking'
-
-/**
- * Signal interface - callable getter/setter with .value accessor
- */
-export interface Signal<T> {
-  /** Get the current value (also tracks dependency) */
-  (): T
-  /** Set a new value */
-  (value: T): void
-  /** Get/set value via property */
-  value: T
-  /** Peek at value without tracking */
-  peek(): T
-  /** Subscribe to changes */
-  subscribe(fn: (value: T) => void): () => void
-}
-
-/**
- * Internal signal state
- */
-interface SignalState<T> {
-  value: T
-  subscribers: Set<Subscriber>
-}
-
-/**
- * Create a reactive signal
- * 
- * @param initialValue - The initial value of the signal
- * @returns A signal that can be read and written
- */
-export function zenSignal<T>(initialValue: T): Signal<T> {
-  const state: SignalState<T> = {
-    value: initialValue,
-    subscribers: new Set()
-  }
-
-  // The signal function - acts as both getter and setter
-  function signal(newValue?: T): T {
-    if (arguments.length === 0) {
-      // Getter - track dependency and return value
-      trackDependency(state.subscribers)
-      return state.value
-    } else {
-      // Setter - update value and notify
-      const oldValue = state.value
-      state.value = newValue as T
-      
-      if (!Object.is(oldValue, newValue)) {
-        notifySubscribers(state.subscribers)
-      }
-      
-      return state.value
-    }
-  }
-
-  // Add .value accessor
-  Object.defineProperty(signal, 'value', {
-    get() {
-      trackDependency(state.subscribers)
-      return state.value
-    },
-    set(newValue: T) {
-      const oldValue = state.value
-      state.value = newValue
-      
-      if (!Object.is(oldValue, newValue)) {
-        notifySubscribers(state.subscribers)
-      }
-    },
-    enumerable: true,
-    configurable: false
-  })
-
-  // Add .peek() - read without tracking
-  ;(signal as Signal<T>).peek = function(): T {
-    return state.value
-  }
-
-  // Add .subscribe() - manual subscription
-  ;(signal as Signal<T>).subscribe = function(fn: (value: T) => void): () => void {
-    const subscriber: Subscriber = () => fn(state.value)
-    state.subscribers.add(subscriber)
-    
-    // Return unsubscribe function
-    return () => {
-      state.subscribers.delete(subscriber)
-    }
-  }
-
-  return signal as Signal<T>
-}
-