voltjs-framework 1.0.0

package/src/ui/reactive.js

@@ -0,0 +1,503 @@
+/**
+ * VoltJS Reactive System
+ * 
+ * Fine-grained reactivity engine (inspired by Solid/Svelte signals).
+ * 
+ * @example
+ * const { Reactive } = require('voltjs');
+ * 
+ * const count = Reactive.signal(0);
+ * const doubled = Reactive.computed(() => count.value * 2);
+ * 
+ * Reactive.effect(() => {
+ *   console.log(`Count: ${count.value}, Doubled: ${doubled.value}`);
+ * });
+ * 
+ * count.value = 5; // Logs: "Count: 5, Doubled: 10"
+ */
+
+'use strict';
+
+let currentEffect = null;
+const effectQueue = [];
+let batchDepth = 0;
+let pendingEffects = new Set();
+
+class Signal {
+  constructor(value) {
+    this._value = value;
+    this._subscribers = new Set();
+  }
+
+  get value() {
+    // Track dependency
+    if (currentEffect) {
+      this._subscribers.add(currentEffect);
+      currentEffect._deps.add(this);
+    }
+    return this._value;
+  }
+
+  set value(newValue) {
+    if (Object.is(this._value, newValue)) return;
+    this._value = newValue;
+    this._notify();
+  }
+
+  /** Update value with function */
+  update(fn) {
+    this.value = fn(this._value);
+  }
+
+  /** Peek at value without tracking */
+  peek() {
+    return this._value;
+  }
+
+  _notify() {
+    for (const effect of this._subscribers) {
+      if (batchDepth > 0) {
+        pendingEffects.add(effect);
+      } else {
+        effect._run();
+      }
+    }
+  }
+
+  toString() { return String(this._value); }
+  toJSON() { return this._value; }
+}
+
+class Computed {
+  constructor(fn) {
+    this._fn = fn;
+    this._value = undefined;
+    this._dirty = true;
+    this._subscribers = new Set();
+    this._deps = new Set();
+    
+    // Set up effect to track dependencies
+    this._effect = new Effect(() => {
+      this._value = this._fn();
+      this._dirty = false;
+      // Notify our subscribers
+      for (const sub of this._subscribers) {
+        if (batchDepth > 0) {
+          pendingEffects.add(sub);
+        } else {
+          sub._run();
+        }
+      }
+    });
+    this._effect._run();
+  }
+
+  get value() {
+    if (currentEffect) {
+      this._subscribers.add(currentEffect);
+      currentEffect._deps.add(this);
+    }
+    return this._value;
+  }
+
+  peek() { return this._value; }
+  toString() { return String(this._value); }
+  toJSON() { return this._value; }
+}
+
+class Effect {
+  constructor(fn) {
+    this._fn = fn;
+    this._deps = new Set();
+    this._active = true;
+  }
+
+  _run() {
+    if (!this._active) return;
+    
+    // Cleanup old deps
+    for (const dep of this._deps) {
+      dep._subscribers.delete(this);
+    }
+    this._deps.clear();
+
+    // Run with tracking
+    const prevEffect = currentEffect;
+    currentEffect = this;
+    try {
+      this._fn();
+    } finally {
+      currentEffect = prevEffect;
+    }
+  }
+
+  dispose() {
+    this._active = false;
+    for (const dep of this._deps) {
+      dep._subscribers.delete(this);
+    }
+    this._deps.clear();
+  }
+}
+
+class Reactive {
+  /** Create a reactive signal */
+  static signal(initialValue) {
+    return new Signal(initialValue);
+  }
+
+  /** Create a computed value */
+  static computed(fn) {
+    return new Computed(fn);
+  }
+
+  /** Create a side effect that re-runs when dependencies change */
+  static effect(fn) {
+    const effect = new Effect(fn);
+    effect._run();
+    return () => effect.dispose(); // Return cleanup function
+  }
+
+  /** Batch multiple updates (single re-render) */
+  static batch(fn) {
+    batchDepth++;
+    try {
+      fn();
+    } finally {
+      batchDepth--;
+      if (batchDepth === 0) {
+        const effects = [...pendingEffects];
+        pendingEffects.clear();
+        for (const effect of effects) {
+          effect._run();
+        }
+      }
+    }
+  }
+
+  /** Create a reactive store (object with reactive properties) */
+  static store(initialState) {
+    const signals = {};
+    const store = {};
+
+    for (const [key, value] of Object.entries(initialState)) {
+      signals[key] = new Signal(value);
+      Object.defineProperty(store, key, {
+        get: () => signals[key].value,
+        set: (v) => { signals[key].value = v; },
+        enumerable: true,
+      });
+    }
+
+    store.$set = (key, value) => {
+      if (!signals[key]) {
+        signals[key] = new Signal(value);
+        Object.defineProperty(store, key, {
+          get: () => signals[key].value,
+          set: (v) => { signals[key].value = v; },
+          enumerable: true,
+          configurable: true,
+        });
+      } else {
+        signals[key].value = value;
+      }
+    };
+
+    store.$snapshot = () => {
+      const obj = {};
+      for (const [key, sig] of Object.entries(signals)) {
+        obj[key] = sig.peek();
+      }
+      return obj;
+    };
+
+    store.$watch = (key, fn) => {
+      return Reactive.effect(() => {
+        const val = signals[key]?.value;
+        fn(val);
+      });
+    };
+
+    store.$reset = (state) => {
+      for (const [key, value] of Object.entries(state)) {
+        if (signals[key]) signals[key].value = value;
+      }
+    };
+
+    return store;
+  }
+
+  /** Create a reactive list */
+  static list(initialItems = []) {
+    const items = Reactive.signal([...initialItems]);
+    
+    return {
+      get value() { return items.value; },
+      get length() { return items.value.length; },
+      add(item) { items.value = [...items.value, item]; },
+      remove(index) { items.value = items.value.filter((_, i) => i !== index); },
+      removeWhere(fn) { items.value = items.value.filter((item) => !fn(item)); },
+      update(index, item) {
+        const arr = [...items.value];
+        arr[index] = typeof item === 'function' ? item(arr[index]) : item;
+        items.value = arr;
+      },
+      clear() { items.value = []; },
+      find(fn) { return items.value.find(fn); },
+      filter(fn) { return items.value.filter(fn); },
+      map(fn) { return items.value.map(fn); },
+      sort(fn) { items.value = [...items.value].sort(fn); },
+      toArray() { return [...items.value]; },
+      [Symbol.iterator]() { return items.value[Symbol.iterator](); },
+    };
+  }
+
+  /** Untrack — read without creating dependency */
+  static untrack(fn) {
+    const prevEffect = currentEffect;
+    currentEffect = null;
+    try {
+      return fn();
+    } finally {
+      currentEffect = prevEffect;
+    }
+  }
+
+  /** Create a derived signal from multiple sources */
+  static derive(sources, fn) {
+    return Reactive.computed(() => {
+      const values = sources.map(s => s.value);
+      return fn(...values);
+    });
+  }
+
+  // ===== ADVANCED STATE MANAGEMENT =====
+
+  /**
+   * Create a store with actions & middleware (Redux-like)
+   * 
+   * @example
+   * const counter = Reactive.createStore({
+   *   state: { count: 0 },
+   *   actions: {
+   *     increment(state) { state.count++; },
+   *     add(state, amount) { state.count += amount; },
+   *   },
+   *   middleware: [loggerMiddleware],
+   * });
+   * 
+   * counter.dispatch('increment');
+   * counter.dispatch('add', 5);
+   * counter.select(s => s.count); // Computed selector
+   */
+  static createStore(config = {}) {
+    const { state: initialState = {}, actions = {}, middleware = [], persist = null } = config;
+
+    // Load persisted state if available
+    let loadedState = { ...initialState };
+    if (persist) {
+      try {
+        const fs = require('fs');
+        const key = persist.key || 'volt_store';
+        if (persist.storage === 'file' && persist.path) {
+          if (fs.existsSync(persist.path)) {
+            const saved = JSON.parse(fs.readFileSync(persist.path, 'utf-8'));
+            loadedState = { ...loadedState, ...saved };
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    // Create reactive signals for each state key
+    const signals = {};
+    const storeObj = {};
+
+    for (const [key, value] of Object.entries(loadedState)) {
+      signals[key] = new Signal(value);
+      Object.defineProperty(storeObj, key, {
+        get: () => signals[key].value,
+        set: (v) => { signals[key].value = v; },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+
+    // History for undo/redo
+    const history = [];
+    const future = [];
+    let historyEnabled = config.history !== false;
+    const maxHistory = config.maxHistory || 50;
+
+    const _snapshot = () => {
+      const obj = {};
+      for (const [k, sig] of Object.entries(signals)) obj[k] = sig.peek();
+      return JSON.parse(JSON.stringify(obj));
+    };
+
+    const _restore = (snapshot) => {
+      Reactive.batch(() => {
+        for (const [k, v] of Object.entries(snapshot)) {
+          if (signals[k]) signals[k].value = v;
+        }
+      });
+    };
+
+    const _persist = () => {
+      if (!persist) return;
+      try {
+        const fs = require('fs');
+        const data = JSON.stringify(_snapshot());
+        if (persist.storage === 'file' && persist.path) {
+          const path = require('path');
+          const dir = path.dirname(persist.path);
+          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(persist.path, data);
+        }
+      } catch { /* ignore */ }
+    };
+
+    /** Dispatch an action by name */
+    storeObj.dispatch = (actionName, ...args) => {
+      const action = actions[actionName];
+      if (!action) throw new Error(`Unknown action: ${actionName}`);
+
+      // Run middleware (before)
+      const ctx = { store: storeObj, action: actionName, args, state: _snapshot() };
+      for (const mw of middleware) {
+        if (mw.before) mw.before(ctx);
+      }
+
+      // Save to history
+      if (historyEnabled) {
+        history.push(_snapshot());
+        if (history.length > maxHistory) history.shift();
+        future.length = 0;
+      }
+
+      // Execute action — pass a mutable proxy
+      const proxy = {};
+      for (const [k, sig] of Object.entries(signals)) {
+        Object.defineProperty(proxy, k, {
+          get: () => sig.peek(),
+          set: (v) => { sig.value = v; },
+          enumerable: true,
+          configurable: true,
+        });
+      }
+
+      Reactive.batch(() => {
+        const result = action(proxy, ...args);
+        // Sync proxy writes back (already done via signal set)
+        return result;
+      });
+
+      // Run middleware (after)
+      const afterCtx = { ...ctx, newState: _snapshot() };
+      for (const mw of middleware) {
+        if (mw.after) mw.after(afterCtx);
+      }
+
+      _persist();
+      return storeObj;
+    };
+
+    /** Create a memoized selector */
+    storeObj.select = (selectorFn) => {
+      return Reactive.computed(() => selectorFn(storeObj));
+    };
+
+    /** Watch a specific key */
+    storeObj.$watch = (key, fn) => {
+      return Reactive.effect(() => {
+        const val = signals[key]?.value;
+        fn(val);
+      });
+    };
+
+    /** Watch multiple keys */
+    storeObj.$watchMany = (keys, fn) => {
+      return Reactive.effect(() => {
+        const vals = {};
+        for (const k of keys) vals[k] = signals[k]?.value;
+        fn(vals);
+      });
+    };
+
+    /** Get a snapshot of current state */
+    storeObj.$snapshot = _snapshot;
+
+    /** Reset state to initial values */
+    storeObj.$reset = () => {
+      _restore(initialState);
+      history.length = 0;
+      future.length = 0;
+      _persist();
+    };
+
+    /** Set a new key dynamically */
+    storeObj.$set = (key, value) => {
+      if (!signals[key]) {
+        signals[key] = new Signal(value);
+        Object.defineProperty(storeObj, key, {
+          get: () => signals[key].value,
+          set: (v) => { signals[key].value = v; },
+          enumerable: true,
+          configurable: true,
+        });
+      } else {
+        signals[key].value = value;
+      }
+    };
+
+    /** Undo last action */
+    storeObj.$undo = () => {
+      if (history.length === 0) return false;
+      future.push(_snapshot());
+      _restore(history.pop());
+      return true;
+    };
+
+    /** Redo last undone action */
+    storeObj.$redo = () => {
+      if (future.length === 0) return false;
+      history.push(_snapshot());
+      _restore(future.pop());
+      return true;
+    };
+
+    /** Check if undo/redo is available */
+    storeObj.$canUndo = () => history.length > 0;
+    storeObj.$canRedo = () => future.length > 0;
+
+    /** Subscribe to all state changes */
+    storeObj.$subscribe = (fn) => {
+      const disposers = [];
+      for (const key of Object.keys(signals)) {
+        disposers.push(Reactive.effect(() => {
+          const val = signals[key].value;
+          fn(key, val, _snapshot());
+        }));
+      }
+      return () => disposers.forEach(d => d());
+    };
+
+    return storeObj;
+  }
+
+  /**
+   * Built-in logger middleware for createStore
+   * 
+   * @example
+   * Reactive.createStore({ middleware: [Reactive.loggerMiddleware] })
+   */
+  static loggerMiddleware = {
+    before(ctx) {
+      console.log(`[Store] Action: ${ctx.action}`, ctx.args, 'State:', ctx.state);
+    },
+    after(ctx) {
+      console.log(`[Store] After ${ctx.action}`, 'New State:', ctx.newState);
+    },
+  };
+}
+
+module.exports = { Reactive, Signal, Computed, Effect };