@zenithbuild/core 0.1.0

package/core/lifecycle/zen-mount.ts

@@ -0,0 +1,182 @@
+/**
+ * Zenith OnMount - Post-Mount Lifecycle Hook
+ * 
+ * Registers a callback to run after a component's DOM is inserted.
+ * This is an effect wrapper that defers execution until the mount phase.
+ * 
+ * Features:
+ * - Runs after DOM is available
+ * - Only runs once per mount
+ * - Supports cleanup function return
+ * - Works with component lifecycle system
+ * 
+ * @example
+ * ```ts
+ * zenOnMount(() => {
+ *   console.log('Component mounted!')
+ *   const el = document.querySelector('.my-element')
+ *   
+ *   // Optional cleanup - runs on unmount
+ *   return () => {
+ *     console.log('Component will unmount')
+ *   }
+ * })
+ * ```
+ * 
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system. If no mount scheduler is active,
+ * callbacks are queued for later execution.
+ */
+
+/**
+ * Mount callback type - can optionally return a cleanup function
+ */
+export type MountCallback = () => void | (() => void)
+
+/**
+ * Mount hook state
+ */
+interface MountHookState {
+  callback: MountCallback
+  cleanup: (() => void) | null
+  mounted: boolean
+}
+
+/**
+ * Queue of pending mount callbacks
+ * These are registered but not yet executed because mount hasn't occurred
+ */
+const pendingMountCallbacks: MountHookState[] = []
+
+/**
+ * Currently active mount hooks (for cleanup on unmount)
+ */
+const activeMountHooks: Set<MountHookState> = new Set()
+
+/**
+ * Flag indicating whether we're in a mounted state
+ * This is controlled by the component lifecycle system
+ */
+let isMounted = false
+
+/**
+ * Register a callback to run after component mount
+ * 
+ * @param callback - Function to run after mount (can return cleanup function)
+ * @returns Dispose function to cancel the mount callback
+ */
+export function zenOnMount(callback: MountCallback): () => void {
+  const state: MountHookState = {
+    callback,
+    cleanup: null,
+    mounted: false
+  }
+  
+  if (isMounted) {
+    // Already mounted - run immediately
+    executeMountCallback(state)
+  } else {
+    // Queue for later execution
+    pendingMountCallbacks.push(state)
+  }
+  
+  activeMountHooks.add(state)
+  
+  // Return dispose function
+  return () => {
+    // Remove from pending if not yet executed
+    const pendingIndex = pendingMountCallbacks.indexOf(state)
+    if (pendingIndex !== -1) {
+      pendingMountCallbacks.splice(pendingIndex, 1)
+    }
+    
+    // Run cleanup if already mounted
+    if (state.mounted && state.cleanup) {
+      state.cleanup()
+      state.cleanup = null
+    }
+    
+    activeMountHooks.delete(state)
+  }
+}
+
+/**
+ * Execute a mount callback
+ */
+function executeMountCallback(state: MountHookState): void {
+  if (state.mounted) return
+  
+  state.mounted = true
+  
+  try {
+    const result = state.callback()
+    
+    if (typeof result === 'function') {
+      state.cleanup = result
+    }
+  } catch (error) {
+    console.error('[Zenith] Error in onMount callback:', error)
+  }
+}
+
+/**
+ * Trigger mount phase - called by component lifecycle system
+ * Executes all pending mount callbacks
+ * 
+ * @internal
+ */
+export function triggerMount(): void {
+  isMounted = true
+  
+  // Execute all pending callbacks
+  const callbacks = [...pendingMountCallbacks]
+  pendingMountCallbacks.length = 0
+  
+  for (const state of callbacks) {
+    executeMountCallback(state)
+  }
+}
+
+/**
+ * Trigger unmount phase - called by component lifecycle system
+ * Runs cleanup functions for all active mount hooks
+ * 
+ * @internal
+ */
+export function triggerUnmount(): void {
+  isMounted = false
+  
+  // Run all cleanup functions
+  for (const state of activeMountHooks) {
+    if (state.cleanup) {
+      try {
+        state.cleanup()
+      } catch (error) {
+        console.error('[Zenith] Error in onMount cleanup:', error)
+      }
+      state.cleanup = null
+    }
+    state.mounted = false
+  }
+}
+
+/**
+ * Check if currently in mounted state
+ * 
+ * @internal
+ */
+export function getIsMounted(): boolean {
+  return isMounted
+}
+
+/**
+ * Reset mount state - for testing purposes
+ * 
+ * @internal
+ */
+export function resetMountState(): void {
+  isMounted = false
+  pendingMountCallbacks.length = 0
+  activeMountHooks.clear()
+}
+

package/core/lifecycle/zen-unmount.ts

@@ -0,0 +1,88 @@
+/**
+ * Zenith OnUnmount - Pre-Unmount Lifecycle Hook
+ * 
+ * Registers a cleanup callback to run before a component is disposed.
+ * Useful for cleaning up subscriptions, timers, event listeners, etc.
+ * 
+ * Features:
+ * - Runs before component is removed from DOM
+ * - Can register multiple callbacks
+ * - Callbacks run in registration order
+ * 
+ * @example
+ * ```ts
+ * zenOnUnmount(() => {
+ *   console.log('Cleaning up...')
+ *   subscription.unsubscribe()
+ *   clearInterval(timerId)
+ * })
+ * ```
+ * 
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system when the component is disposed.
+ */
+
+/**
+ * Unmount callback type
+ */
+export type UnmountCallback = () => void
+
+/**
+ * Queue of registered unmount callbacks
+ */
+const unmountCallbacks: Set<UnmountCallback> = new Set()
+
+/**
+ * Register a callback to run before component unmount
+ * 
+ * @param callback - Function to run before unmount
+ * @returns Dispose function to cancel the unmount callback
+ */
+export function zenOnUnmount(callback: UnmountCallback): () => void {
+  unmountCallbacks.add(callback)
+  
+  // Return dispose function
+  return () => {
+    unmountCallbacks.delete(callback)
+  }
+}
+
+/**
+ * Execute all unmount callbacks
+ * Called by the component lifecycle system before disposal
+ * 
+ * @internal
+ */
+export function executeUnmountCallbacks(): void {
+  // Execute in registration order
+  for (const callback of unmountCallbacks) {
+    try {
+      callback()
+    } catch (error) {
+      console.error('[Zenith] Error in onUnmount callback:', error)
+    }
+  }
+  
+  // Clear all callbacks after execution
+  unmountCallbacks.clear()
+}
+
+/**
+ * Get count of registered unmount callbacks
+ * Useful for testing
+ * 
+ * @internal
+ */
+export function getUnmountCallbackCount(): number {
+  return unmountCallbacks.size
+}
+
+/**
+ * Reset unmount state - for testing purposes
+ * 
+ * @internal
+ */
+export function resetUnmountState(): void {
+  unmountCallbacks.clear()
+}
+

package/core/reactivity/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Zenith Reactivity System
+ * 
+ * This module exports all reactive primitives for the Zenith framework.
+ * 
+ * Exports both explicit `zen*` names (internal) and clean aliases (public DX).
+ */
+
+// Core primitives - explicit names
+import { zenSignal as _zenSignal, type Signal } from './zen-signal'
+import { zenState as _zenState } from './zen-state'
+import { zenEffect as _zenEffect, type EffectFn, type DisposeFn } from './zen-effect'
+import { zenMemo as _zenMemo, type Memo } from './zen-memo'
+import { zenRef as _zenRef, type Ref } from './zen-ref'
+import { zenBatch as _zenBatch } from './zen-batch'
+import { zenUntrack as _zenUntrack } from './zen-untrack'
+
+// Re-export with explicit names
+export const zenSignal = _zenSignal
+export const zenState = _zenState
+export const zenEffect = _zenEffect
+export const zenMemo = _zenMemo
+export const zenRef = _zenRef
+export const zenBatch = _zenBatch
+export const zenUntrack = _zenUntrack
+
+// Re-export types
+export type { Signal, Memo, Ref, EffectFn, DisposeFn }
+
+// Internal tracking utilities (for advanced use)
+export {
+  type Subscriber,
+  type TrackingContext,
+  trackDependency,
+  notifySubscribers,
+  getCurrentContext,
+  pushContext,
+  popContext,
+  cleanupContext,
+  runUntracked,
+  startBatch,
+  endBatch,
+  isBatching
+} from './tracking'
+
+// Public DX aliases - clean names
+export const signal = _zenSignal
+export const state = _zenState
+export const effect = _zenEffect
+export const memo = _zenMemo
+export const ref = _zenRef
+export const batch = _zenBatch
+export const untrack = _zenUntrack
+

package/core/reactivity/tracking.ts

@@ -0,0 +1,167 @@
+/**
+ * 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

@@ -0,0 +1,57 @@
+/**
+ * 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

@@ -0,0 +1,139 @@
+/**
+ * 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)
+}
+