decantr 0.9.0

package/src/state/middleware.js

@@ -0,0 +1,288 @@
+import { createSignal, createEffect, batch } from './index.js';
+
+/**
+ * Apply a middleware chain to a signal [getter, setter] tuple.
+ * Each middleware factory returns `{ onGet?, onSet? }`.
+ * - `onGet(value)` — intercept reads, return transformed value.
+ * - `onSet(newValue, prevValue)` — intercept writes, return value to set
+ *   or `undefined` to reject the write.
+ * Middlewares run in order: first middleware's onSet executes first (pipeline).
+ *
+ * @template T
+ * @param {[() => T, (v: T | ((prev: T) => T)) => void]} signal
+ * @param {Array<() => { onGet?: (v: T) => T, onSet?: (next: T, prev: T) => T | undefined }>} middlewares
+ * @param {{ name?: string }} [options]
+ * @returns {[() => T, (v: T | ((prev: T) => T)) => void]}
+ */
+export function withMiddleware(signal, middlewares, options) {
+  const [rawGet, rawSet] = signal;
+  const chain = middlewares.map(m => m());
+
+  // Wire _attach hooks (used by undoMiddleware to get a reference to rawSet)
+  for (let i = 0; i < chain.length; i++) {
+    if (typeof chain[i]._attach === 'function') chain[i]._attach(rawSet);
+  }
+
+  // Hydrate from persistMiddleware if present
+  for (let i = 0; i < chain.length; i++) {
+    if (chain[i]._hasHydrated) rawSet(chain[i]._hydrated);
+  }
+
+  function getter() {
+    let value = rawGet();
+    for (let i = 0; i < chain.length; i++) {
+      if (chain[i].onGet) value = chain[i].onGet(value);
+    }
+    return value;
+  }
+
+  function setter(next) {
+    const prev = rawGet();
+    let resolved = typeof next === 'function' ? next(prev) : next;
+    for (let i = 0; i < chain.length; i++) {
+      if (chain[i].onSet) {
+        resolved = chain[i].onSet(resolved, prev);
+        if (resolved === undefined) return;
+      }
+    }
+    rawSet(resolved);
+  }
+
+  // Preserve _subscribers for reactive tracking
+  getter._subscribers = rawGet._subscribers;
+
+  return [getter, setter];
+}
+
+/**
+ * Apply a middleware chain to a store proxy.
+ * Returns a new Proxy with middleware interception on property get/set.
+ *
+ * @template {object} T
+ * @param {T} store - Proxy-based store from createStore
+ * @param {Array<() => { onGet?: (v: any, prop: string|symbol) => any, onSet?: (next: any, prev: any, prop: string|symbol) => any }>} middlewares
+ * @returns {T}
+ */
+export function withStoreMiddleware(store, middlewares) {
+  const chain = middlewares.map(m => m());
+
+  return new Proxy(store, {
+    get(target, prop, receiver) {
+      let value = Reflect.get(target, prop, receiver);
+      for (let i = 0; i < chain.length; i++) {
+        if (chain[i].onGet) value = chain[i].onGet(value, prop);
+      }
+      return value;
+    },
+    set(target, prop, value, receiver) {
+      const prev = target[prop];
+      let resolved = value;
+      for (let i = 0; i < chain.length; i++) {
+        if (chain[i].onSet) {
+          resolved = chain[i].onSet(resolved, prev, prop);
+          if (resolved === undefined) return true;
+        }
+      }
+      return Reflect.set(target, prop, resolved, receiver);
+    }
+  });
+}
+
+/**
+ * Console logging middleware for signals and stores.
+ * Logs `[label] set: prev -> next` on every setter call.
+ *
+ * @param {{ label?: string, collapsed?: boolean }} [options]
+ * @returns {() => { onSet: (next: any, prev: any) => any }}
+ */
+export function loggerMiddleware(options) {
+  const label = (options && options.label) || 'signal';
+  const collapsed = (options && options.collapsed) || false;
+
+  return () => ({
+    onSet(next, prev) {
+      const group = collapsed ? console.groupCollapsed : console.group;
+      group.call(console, `[${label}] set`);
+      console.log('prev:', prev);
+      console.log('next:', next);
+      console.groupEnd();
+      return next;
+    }
+  });
+}
+
+/**
+ * Auto-persist middleware. Reads initial value from storage on creation
+ * and writes to storage on every set (debounced if configured).
+ *
+ * On init, if a stored value exists under `options.key`, it is hydrated
+ * into the signal via the `_hasHydrated` / `_hydrated` protocol.
+ *
+ * @param {{ key: string, storage?: 'local' | 'session', debounce?: number }} options
+ * @returns {() => { _hasHydrated: boolean, _hydrated: any, onSet: (next: any, prev: any) => any }}
+ */
+export function persistMiddleware(options) {
+  const key = options.key;
+  const storageType = options.storage || 'local';
+  const debounceMs = options.debounce || 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+
+  function getStorage() {
+    return storageType === 'session'
+      ? (typeof sessionStorage !== 'undefined' ? sessionStorage : null)
+      : (typeof localStorage !== 'undefined' ? localStorage : null);
+  }
+
+  function writeTo(store, value) {
+    if (!store) return;
+    try {
+      store.setItem(key, JSON.stringify(value));
+    } catch (_) { /* quota exceeded or private browsing */ }
+  }
+
+  return () => {
+    const store = getStorage();
+    let hydrated = false;
+    /** @type {any} */
+    let hydratedValue;
+
+    if (store) {
+      try {
+        const raw = store.getItem(key);
+        if (raw !== null) {
+          hydratedValue = JSON.parse(raw);
+          hydrated = true;
+        }
+      } catch (_) { /* corrupt data */ }
+    }
+
+    return {
+      _hasHydrated: hydrated,
+      _hydrated: hydrated ? hydratedValue : undefined,
+
+      onSet(next, _prev) {
+        const s = getStorage();
+        if (debounceMs > 0) {
+          if (timer !== null) clearTimeout(timer);
+          timer = setTimeout(() => writeTo(s, next), debounceMs);
+        } else {
+          writeTo(s, next);
+        }
+        return next;
+      }
+    };
+  };
+}
+
+/**
+ * Validation middleware. Rejects writes that fail the validator function.
+ * If validation fails, the set is silently rejected (returns `undefined`).
+ *
+ * @template T
+ * @param {(value: T) => true | string | Error} validator
+ *   Return `true` if valid, or an error string / Error object if invalid.
+ * @param {{ onError?: (error: string | Error, value: T) => void }} [options]
+ * @returns {() => { onSet: (next: T, prev: T) => T | undefined }}
+ */
+export function validationMiddleware(validator, options) {
+  const onError = options && options.onError;
+
+  return () => ({
+    onSet(next, _prev) {
+      const result = validator(next);
+      if (result === true) return next;
+      if (onError) onError(result, next);
+      return undefined;
+    }
+  });
+}
+
+/**
+ * Undo/redo middleware. Tracks every set call and exposes controls.
+ *
+ * Returns an object with:
+ * - `middleware` — factory to pass into withMiddleware's array
+ * - `undo()` / `redo()` — restore previous/next value
+ * - `canUndo` / `canRedo` — signal getters (boolean)
+ * - `history()` — returns shallow copy of the undo stack
+ *
+ * @param {{ maxLength?: number }} [options]
+ * @returns {{
+ *   middleware: () => { _attach: (setter: Function) => void, onSet: (next: any, prev: any) => any },
+ *   undo: () => void,
+ *   redo: () => void,
+ *   canUndo: () => boolean,
+ *   canRedo: () => boolean,
+ *   history: () => any[]
+ * }}
+ */
+export function undoMiddleware(options) {
+  const maxLength = (options && options.maxLength) || 100;
+
+  /** @type {any[]} */
+  const stack = [];
+  /** @type {any[]} */
+  const redoStack = [];
+
+  const [canUndo, setCanUndo] = createSignal(false);
+  const [canRedo, setCanRedo] = createSignal(false);
+
+  let skip = false;
+  /** @type {((v: any) => void) | null} */
+  let rawSetter = null;
+
+  function updateFlags() {
+    batch(() => {
+      setCanUndo(stack.length > 1);
+      setCanRedo(redoStack.length > 0);
+    });
+  }
+
+  return {
+    middleware() {
+      return {
+        /** @internal Called by withMiddleware to wire the raw setter. */
+        _attach(setter) { rawSetter = setter; },
+
+        onSet(next, prev) {
+          if (skip) return next;
+          // Capture initial value on first write
+          if (stack.length === 0) stack.push(prev);
+          stack.push(next);
+          if (stack.length > maxLength + 1) stack.shift();
+          redoStack.length = 0;
+          updateFlags();
+          return next;
+        }
+      };
+    },
+
+    undo() {
+      if (stack.length <= 1 || !rawSetter) return;
+      redoStack.push(stack.pop());
+      skip = true;
+      rawSetter(stack[stack.length - 1]);
+      skip = false;
+      updateFlags();
+    },
+
+    redo() {
+      if (redoStack.length === 0 || !rawSetter) return;
+      const value = redoStack.pop();
+      stack.push(value);
+      skip = true;
+      rawSetter(value);
+      skip = false;
+      updateFlags();
+    },
+
+    canUndo,
+    canRedo,
+
+    /** @returns {any[]} Shallow copy of the undo history stack. */
+    history() {
+      return stack.slice();
+    }
+  };
+}

package/src/state/scheduler.js

@@ -0,0 +1,206 @@
+/** @typedef {{ run: Function, level: number, sources?: Set, disposed?: boolean }} ReactiveNode */
+
+/** @type {Set<ReactiveNode>} */
+const pending = new Set();
+let flushing = false;
+let scheduled = false;
+
+/** @type {ReactiveNode|null} */
+export let currentEffect = null;
+
+/**
+ * @param {ReactiveNode|null} effect
+ */
+export function setCurrentEffect(effect) {
+  currentEffect = effect;
+}
+
+// ─── Ownership Tree ─────────────────────────────────────────
+
+/** @typedef {{ children: Set<Owner>, cleanups: Function[], onError?: Function, context?: Map }} Owner */
+
+/** @type {Owner|null} */
+let currentOwner = null;
+
+/**
+ * @returns {Owner|null}
+ */
+export function getOwner() {
+  return currentOwner;
+}
+
+/**
+ * @param {Owner|null} owner
+ * @param {Function} fn
+ * @returns {*}
+ */
+export function runWithOwner(owner, fn) {
+  const prev = currentOwner;
+  currentOwner = owner;
+  try {
+    return fn();
+  } finally {
+    currentOwner = prev;
+  }
+}
+
+/**
+ * Create an independent reactive scope.
+ * @param {Function} fn
+ * @returns {*}
+ */
+export function createRoot(fn) {
+  /** @type {Owner} */
+  const owner = { children: new Set(), cleanups: [] };
+  const prev = currentOwner;
+  currentOwner = owner;
+  let result;
+  try {
+    result = fn(() => disposeOwner(owner));
+  } finally {
+    currentOwner = prev;
+  }
+  return result;
+}
+
+/**
+ * Register current node with owner tree.
+ * @param {Function} cleanup
+ */
+export function registerCleanup(cleanup) {
+  if (currentOwner) {
+    currentOwner.cleanups.push(cleanup);
+  }
+}
+
+/**
+ * Create a child owner under the current owner.
+ * @returns {Owner}
+ */
+export function createChildOwner() {
+  /** @type {Owner} */
+  const child = { children: new Set(), cleanups: [] };
+  if (currentOwner) {
+    currentOwner.children.add(child);
+    child._parent = currentOwner;
+  }
+  return child;
+}
+
+/**
+ * Dispose an owner and all its descendants.
+ * @param {Owner} owner
+ */
+export function disposeOwner(owner) {
+  // Dispose children first (depth-first)
+  for (const child of owner.children) {
+    disposeOwner(child);
+  }
+  owner.children.clear();
+  // Run cleanups in reverse order
+  for (let i = owner.cleanups.length - 1; i >= 0; i--) {
+    try { owner.cleanups[i](); } catch (_) {}
+  }
+  owner.cleanups.length = 0;
+  // Remove from parent
+  if (owner._parent) {
+    owner._parent.children.delete(owner);
+    owner._parent = null;
+  }
+}
+
+// ─── Error Boundaries ───────────────────────────────────────
+
+/**
+ * Set error handler on current owner.
+ * @param {Function} handler — (error) => void
+ */
+export function onError(handler) {
+  if (currentOwner) {
+    currentOwner.onError = handler;
+  }
+}
+
+/**
+ * Walk up owner tree to find error handler.
+ * @param {Error} error
+ * @param {Owner|null} owner
+ */
+export function handleError(error, owner) {
+  let current = owner;
+  while (current) {
+    if (current.onError) {
+      try {
+        current.onError(error);
+        return;
+      } catch (e) {
+        // Handler itself threw — continue up
+        error = e instanceof Error ? e : new Error(String(e));
+      }
+    }
+    current = current._parent || null;
+  }
+  // No handler found — rethrow
+  throw error;
+}
+
+// ─── Scheduling & Flush ─────────────────────────────────────
+
+/**
+ * @param {ReactiveNode} effect
+ */
+export function scheduleEffect(effect) {
+  if (effect.disposed) return;
+  pending.add(effect);
+  if (!scheduled) {
+    scheduled = true;
+    queueMicrotask(flush);
+  }
+}
+
+/**
+ * Topological flush — sort pending effects by level (lowest first).
+ * Effects with lower levels (closer to signals) run first,
+ * preventing diamond-problem double-firing.
+ */
+export function flush() {
+  if (flushing) return;
+  flushing = true;
+  scheduled = false;
+
+  while (pending.size > 0) {
+    // Sort by level for topological ordering
+    const effects = [...pending].sort((a, b) => (a.level || 0) - (b.level || 0));
+    pending.clear();
+    for (let i = 0; i < effects.length; i++) {
+      const effect = effects[i];
+      if (!effect.disposed) {
+        effect.run();
+      }
+    }
+  }
+
+  flushing = false;
+}
+
+let batchDepth = 0;
+
+/**
+ * @param {Function} fn
+ */
+export function batch(fn) {
+  batchDepth++;
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}
+
+/**
+ * @returns {boolean}
+ */
+export function isBatching() {
+  return batchDepth > 0;
+}