decantr 0.9.0

package/src/state/store.js

@@ -0,0 +1,300 @@
+/**
+ * Deep reactive store with per-property subscriptions,
+ * Immer-like produce(), and structural-sharing reconcile().
+ * @module state/store
+ */
+import { batch } from './index.js';
+import { currentEffect, isBatching, scheduleEffect } from './scheduler.js';
+
+/** @type {WeakMap<object, object>} raw target -> proxy */
+const proxyCache = new WeakMap();
+/** @type {WeakMap<object, Map<string|symbol, Set>>} target -> prop -> subscribers */
+const subMaps = new WeakMap();
+/** @type {WeakMap<object, object>} proxy -> raw target */
+const proxyToRaw = new WeakMap();
+
+const MUTATORS = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'fill', 'copyWithin'];
+
+function getSubs(prop, target) {
+  let map = subMaps.get(target);
+  if (!map) { map = new Map(); subMaps.set(target, map); }
+  let s = map.get(prop);
+  if (!s) { s = new Set(); map.set(prop, s); }
+  return s;
+}
+
+function track(subs) {
+  if (!currentEffect) return;
+  subs.add(currentEffect);
+  if (currentEffect.sources) currentEffect.sources.add(subs);
+}
+
+function notify(subs) {
+  if (!subs || subs.size === 0) return;
+  if (isBatching()) {
+    for (const sub of subs) scheduleEffect(sub);
+  } else {
+    const arr = [...subs];
+    for (let i = 0; i < arr.length; i++) {
+      if (!arr[i].disposed) arr[i].run();
+    }
+  }
+}
+
+function notifyAll(target) {
+  const map = subMaps.get(target);
+  if (!map) return;
+  for (const subs of map.values()) notify(subs);
+}
+
+/** @param {*} v */
+function isProxyable(v) {
+  return v !== null && typeof v === 'object' && !Object.isFrozen(v);
+}
+
+/** Unwrap proxy to raw target (identity if not proxied). */
+function toRaw(v) {
+  return (v && proxyToRaw.get(v)) || v;
+}
+
+/** Wrap a value in a deep reactive proxy (cached per identity). */
+function wrap(target) {
+  if (proxyCache.has(target)) return proxyCache.get(target);
+  const isArr = Array.isArray(target);
+
+  const proxy = new Proxy(target, {
+    get(target, prop, receiver) {
+      if (prop === '__raw') return target;
+      if (typeof prop === 'symbol') return Reflect.get(target, prop, receiver);
+
+      if (isArr && MUTATORS.includes(/** @type {string} */ (prop))) {
+        return (...args) => {
+          batch(() => {
+            Array.prototype[prop].apply(target, args.map(a => toRaw(a)));
+            notify(getSubs('length', target));
+            notifyAll(target);
+          });
+          return target.length;
+        };
+      }
+
+      track(getSubs(prop, target));
+      const value = Reflect.get(target, prop, receiver);
+      return isProxyable(value) ? wrap(value) : value;
+    },
+
+    set(target, prop, value) {
+      const raw = toRaw(value);
+      const prev = target[prop];
+      if (Object.is(prev, raw)) return true;
+      target[prop] = raw;
+      notify(getSubs(prop, target));
+      if (isArr && prop !== 'length') notify(getSubs('length', target));
+      return true;
+    },
+
+    deleteProperty(target, prop) {
+      const had = prop in target;
+      const result = Reflect.deleteProperty(target, prop);
+      if (had) notify(getSubs(prop, target));
+      return result;
+    },
+
+    has(target, prop) {
+      track(getSubs(prop, target));
+      return Reflect.has(target, prop);
+    },
+
+    ownKeys(target) {
+      track(getSubs('@@keys', target));
+      return Reflect.ownKeys(target);
+    }
+  });
+
+  proxyCache.set(target, proxy);
+  proxyToRaw.set(proxy, target);
+  return proxy;
+}
+
+// ─── createDeepStore ─────────────────────────────────────────
+
+/**
+ * Create a deeply reactive store. Nested objects/arrays are lazily
+ * wrapped in reactive proxies with per-property subscription tracking.
+ * @template T
+ * @param {T} init - Plain object or array
+ * @returns {T} Deep reactive proxy
+ */
+export function createDeepStore(init) {
+  if (!isProxyable(init)) {
+    throw new Error('createDeepStore requires a plain object or array');
+  }
+  return /** @type {T} */ (wrap(init));
+}
+
+// ─── produce ─────────────────────────────────────────────────
+
+/**
+ * Immer-like mutation. Executes recipe against a draft proxy that records
+ * mutations, then fires notifications in a single batch.
+ * @template T
+ * @param {T} store - Deep reactive store
+ * @param {(draft: T) => void} recipe - Mutation function
+ */
+export function produce(store, recipe) {
+  /** @type {Array<{target: object, prop: string|symbol, value: *, type: string}>} */
+  const patches = [];
+  const drafts = new WeakMap();
+
+  function createDraft(target) {
+    const raw = toRaw(target);
+    if (drafts.has(raw)) return drafts.get(raw);
+
+    const draft = new Proxy(raw, {
+      get(t, prop) {
+        if (prop === '__raw') return raw;
+        if (typeof prop === 'symbol') return Reflect.get(t, prop);
+        if (Array.isArray(t) && MUTATORS.includes(/** @type {string} */ (prop))) {
+          return (...args) => {
+            const unwrapped = args.map(a => toRaw(a));
+            patches.push({ target: t, prop, value: unwrapped, type: 'array' });
+            Array.prototype[prop].apply(t, unwrapped);
+            return t.length;
+          };
+        }
+        const value = Reflect.get(t, prop);
+        return isProxyable(value) ? createDraft(value) : value;
+      },
+      set(t, prop, value) {
+        const v = toRaw(value);
+        patches.push({ target: t, prop, value: v, type: 'set' });
+        t[prop] = v;
+        return true;
+      },
+      deleteProperty(t, prop) {
+        patches.push({ target: t, prop, value: undefined, type: 'delete' });
+        delete t[prop];
+        return true;
+      }
+    });
+
+    drafts.set(raw, draft);
+    return draft;
+  }
+
+  recipe(createDraft(store));
+
+  // Notify in a single batch — mutations already applied to raw targets
+  batch(() => {
+    const seen = new Set();
+    for (const { target, prop, type } of patches) {
+      if (type === 'array') {
+        const key = target.toString() + '::arr';
+        if (!seen.has(key)) {
+          seen.add(key);
+          notify(getSubs('length', target));
+          notifyAll(target);
+        }
+      } else if (type === 'delete') {
+        notify(getSubs(prop, target));
+        notify(getSubs('@@keys', target));
+      } else {
+        notify(getSubs(prop, target));
+      }
+    }
+  });
+}
+
+// ─── reconcile ───────────────────────────────────────────────
+
+/**
+ * Efficient bulk update with structural sharing. Parallel-walks old and
+ * new data, only notifying properties that actually changed.
+ * @template T
+ * @param {T} store - Deep reactive store
+ * @param {T} data - New plain data to reconcile against
+ */
+export function reconcile(store, data) {
+  const raw = toRaw(store);
+  if (!isProxyable(raw) || !isProxyable(data)) return;
+  batch(() => { _reconcile(raw, data); });
+}
+
+function _reconcile(target, next) {
+  const isArr = Array.isArray(target);
+  if (isArr !== Array.isArray(next)) return; // type mismatch
+  if (isArr) return _reconcileArray(target, next);
+
+  const oldKeys = Object.keys(target);
+  const newKeys = Object.keys(next);
+  let keysChanged = false;
+
+  for (let i = 0; i < newKeys.length; i++) {
+    const key = newKeys[i];
+    const oldVal = target[key];
+    const newVal = next[key];
+
+    if (!(key in target)) {
+      target[key] = newVal;
+      notify(getSubs(key, target));
+      keysChanged = true;
+      continue;
+    }
+    if (Object.is(oldVal, newVal)) continue;
+
+    if (isProxyable(oldVal) && isProxyable(newVal)
+        && Array.isArray(oldVal) === Array.isArray(newVal)) {
+      _reconcile(oldVal, newVal);
+    } else {
+      target[key] = newVal;
+      notify(getSubs(key, target));
+    }
+  }
+
+  for (let i = 0; i < oldKeys.length; i++) {
+    const key = oldKeys[i];
+    if (!(key in next)) {
+      delete target[key];
+      notify(getSubs(key, target));
+      keysChanged = true;
+    }
+  }
+  if (keysChanged) notify(getSubs('@@keys', target));
+}
+
+function _reconcileArray(target, next) {
+  const oldLen = target.length;
+  const newLen = next.length;
+  let changed = false;
+
+  for (let i = 0; i < Math.min(oldLen, newLen); i++) {
+    const oldVal = target[i];
+    const newVal = next[i];
+    if (Object.is(oldVal, newVal)) continue;
+    if (isProxyable(oldVal) && isProxyable(newVal)
+        && Array.isArray(oldVal) === Array.isArray(newVal)) {
+      _reconcile(oldVal, newVal);
+    } else {
+      target[i] = newVal;
+      notify(getSubs(String(i), target));
+      changed = true;
+    }
+  }
+
+  for (let i = oldLen; i < newLen; i++) {
+    target[i] = next[i];
+    notify(getSubs(String(i), target));
+    changed = true;
+  }
+
+  if (newLen < oldLen) {
+    for (let i = newLen; i < oldLen; i++) notify(getSubs(String(i), target));
+    target.length = newLen;
+    changed = true;
+  }
+
+  if (changed) {
+    notify(getSubs('length', target));
+    notify(getSubs('@@keys', target));
+  }
+}

package/src/tags/index.js

@@ -0,0 +1,19 @@
+import { h } from '../core/index.js';
+
+/**
+ * Proxy-based tag functions. Destructure what you need:
+ * @example const { div, p, h2, button } = tags;
+ * div({ class: 'card' }, h2('Title'), p('Content'))
+ * @type {Record<string, Function>}
+ */
+export const tags = new Proxy({}, {
+  get(_, tag) {
+    return (first, ...rest) => {
+      if (first && typeof first === 'object' && !first.nodeType
+          && !Array.isArray(first) && typeof first !== 'function') {
+        return h(tag, first, ...rest);
+      }
+      return h(tag, null, ...(first != null ? [first, ...rest] : rest));
+    };
+  }
+});

package/src/tannins/auth.js

@@ -0,0 +1,396 @@
+/**
+ * Decantr Auth Reference Tannin
+ *
+ * Provides token-based authentication with reactive signals,
+ * persistent cross-tab token storage, auto-refresh on 401,
+ * and a route guard helper.
+ *
+ * @module decantr/tannins/auth
+ */
+
+import { createSignal, createMemo, createEffect, batch } from '../state/index.js';
+import { createPersisted } from '../data/persist.js';
+
+/**
+ * Create an auth instance with reactive signals, token persistence,
+ * login/logout/refresh flows, and fetch middleware.
+ *
+ * @param {{
+ *   loginEndpoint?: string,
+ *   refreshEndpoint?: string,
+ *   logoutEndpoint?: string,
+ *   tokenKey?: string,
+ *   storage?: 'localStorage' | 'sessionStorage',
+ *   onAuthChange?: (isAuthenticated: boolean) => void
+ * }} [config]
+ * @returns {{
+ *   user: () => any,
+ *   token: () => string | null,
+ *   isAuthenticated: () => boolean,
+ *   isLoading: () => boolean,
+ *   error: () => any,
+ *   login: (credentials: Record<string, any>) => Promise<any>,
+ *   logout: () => Promise<void>,
+ *   refresh: () => Promise<void>,
+ *   setUser: (user: any) => void,
+ *   setToken: (token: string | null) => void,
+ *   destroy: () => void
+ * }}
+ */
+export function createAuth(config = {}) {
+  const {
+    loginEndpoint = '/api/auth/login',
+    refreshEndpoint = '/api/auth/refresh',
+    logoutEndpoint = '/api/auth/logout',
+    tokenKey = 'decantr_auth_token',
+    storage = 'localStorage',
+    onAuthChange = null
+  } = config;
+
+  // Persisted token signal — cross-tab sync via storage events
+  const persistedStorage = storage === 'sessionStorage' ? 'session' : 'local';
+  const [token, setTokenRaw] = createPersisted(tokenKey, null, { storage: persistedStorage });
+
+  // User object signal (not persisted — re-fetched on refresh)
+  const [user, setUser] = createSignal(null);
+
+  // Loading state
+  const [isLoading, setIsLoading] = createSignal(false);
+
+  // Error state
+  const [error, setError] = createSignal(null);
+
+  // Derived: is authenticated when token exists
+  const isAuthenticated = createMemo(() => token() !== null);
+
+  // Track previous auth state for onAuthChange callback
+  let prevAuth = isAuthenticated();
+  let authChangeDispose = null;
+  if (typeof onAuthChange === 'function') {
+    authChangeDispose = createEffect(() => {
+      const current = isAuthenticated();
+      if (current !== prevAuth) {
+        prevAuth = current;
+        onAuthChange(current);
+      }
+    });
+  }
+
+  // Track whether a refresh is in progress (to avoid concurrent refreshes)
+  let refreshPromise = null;
+
+  // Store the original fetch so we can restore it on destroy
+  const originalFetch = typeof globalThis !== 'undefined' ? globalThis.fetch : null;
+  let middlewareInstalled = false;
+
+  /**
+   * Install fetch middleware that injects Bearer token and handles 401 auto-refresh.
+   */
+  function installMiddleware() {
+    if (middlewareInstalled) return;
+    if (typeof globalThis === 'undefined' || typeof globalThis.fetch !== 'function') return;
+
+    const baseFetch = globalThis.fetch;
+    middlewareInstalled = true;
+
+    globalThis.fetch = async function authFetch(input, init) {
+      const currentToken = token();
+      const opts = { ...init };
+
+      // Inject Bearer token if available
+      if (currentToken) {
+        opts.headers = new Headers(opts.headers || {});
+        if (!opts.headers.has('Authorization')) {
+          opts.headers.set('Authorization', `Bearer ${currentToken}`);
+        }
+      }
+
+      let response;
+      try {
+        response = await baseFetch(input, opts);
+      } catch (err) {
+        throw err;
+      }
+
+      // On 401, attempt token refresh and retry once
+      if (response.status === 401 && currentToken && refreshEndpoint) {
+        try {
+          await doRefresh(baseFetch);
+          // Retry with new token
+          const retryToken = token();
+          if (retryToken) {
+            const retryOpts = { ...init };
+            retryOpts.headers = new Headers(retryOpts.headers || {});
+            retryOpts.headers.set('Authorization', `Bearer ${retryToken}`);
+            return baseFetch(input, retryOpts);
+          }
+        } catch (_) {
+          // Refresh failed — return original 401 response
+        }
+      }
+
+      return response;
+    };
+  }
+
+  /**
+   * Remove fetch middleware, restoring the original fetch.
+   */
+  function removeMiddleware() {
+    if (!middlewareInstalled) return;
+    if (typeof globalThis !== 'undefined' && originalFetch) {
+      globalThis.fetch = originalFetch;
+    }
+    middlewareInstalled = false;
+  }
+
+  // Install middleware immediately
+  installMiddleware();
+
+  /**
+   * Internal refresh using a specific fetch function (to avoid recursion through middleware).
+   * @param {Function} fetchFn
+   */
+  async function doRefresh(fetchFn) {
+    // Deduplicate concurrent refresh calls
+    if (refreshPromise) return refreshPromise;
+
+    refreshPromise = (async () => {
+      const currentToken = token();
+      try {
+        const res = await fetchFn(refreshEndpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(currentToken ? { 'Authorization': `Bearer ${currentToken}` } : {})
+          }
+        });
+        if (!res.ok) {
+          // Refresh failed — clear auth state
+          batch(() => {
+            setTokenRaw(null);
+            setUser(null);
+          });
+          throw new Error(`Refresh failed: ${res.status}`);
+        }
+        const data = await res.json();
+        batch(() => {
+          if (data.token !== undefined) setTokenRaw(data.token);
+          if (data.user !== undefined) setUser(data.user);
+        });
+      } finally {
+        refreshPromise = null;
+      }
+    })();
+
+    return refreshPromise;
+  }
+
+  /**
+   * Log in with credentials. POSTs to loginEndpoint.
+   * Expects response JSON: { token: string, user?: any }
+   * @param {Record<string, any>} credentials
+   * @returns {Promise<any>} The response data
+   */
+  async function login(credentials) {
+    setIsLoading(true);
+    setError(null);
+    try {
+      // Use originalFetch (or the base fetch before middleware) to avoid injecting a stale token
+      const fetchFn = originalFetch || globalThis.fetch;
+      const res = await fetchFn(loginEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(credentials)
+      });
+      if (!res.ok) {
+        const errText = await res.text().catch(() => `Login failed: ${res.status}`);
+        let errData;
+        try { errData = JSON.parse(errText); } catch (_) { errData = { message: errText }; }
+        const loginError = new Error(errData.message || `Login failed: ${res.status}`);
+        loginError.status = res.status;
+        loginError.data = errData;
+        setError(loginError);
+        throw loginError;
+      }
+      const data = await res.json();
+      batch(() => {
+        if (data.token !== undefined) setTokenRaw(data.token);
+        if (data.user !== undefined) setUser(data.user);
+        setError(null);
+      });
+      return data;
+    } catch (err) {
+      if (!error()) setError(err);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  /**
+   * Log out. Optionally POSTs to logoutEndpoint, then clears local state.
+   * @returns {Promise<void>}
+   */
+  async function logout() {
+    setIsLoading(true);
+    setError(null);
+    try {
+      if (logoutEndpoint) {
+        const currentToken = token();
+        const fetchFn = originalFetch || globalThis.fetch;
+        try {
+          await fetchFn(logoutEndpoint, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              ...(currentToken ? { 'Authorization': `Bearer ${currentToken}` } : {})
+            }
+          });
+        } catch (_) {
+          // Best-effort — always clear local state even if server call fails
+        }
+      }
+    } finally {
+      batch(() => {
+        setTokenRaw(null);
+        setUser(null);
+        setError(null);
+      });
+      setIsLoading(false);
+    }
+  }
+
+  /**
+   * Refresh the auth token. POSTs to refreshEndpoint.
+   * Expects response JSON: { token: string, user?: any }
+   * @returns {Promise<void>}
+   */
+  async function refresh() {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const fetchFn = originalFetch || globalThis.fetch;
+      await doRefresh(fetchFn);
+    } catch (err) {
+      setError(err);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  /**
+   * Manually set the token (e.g., from an external auth provider).
+   * @param {string | null} newToken
+   */
+  function setToken(newToken) {
+    setTokenRaw(newToken);
+  }
+
+  /**
+   * Clean up effects and remove fetch middleware.
+   */
+  function destroy() {
+    removeMiddleware();
+    if (typeof authChangeDispose === 'function') {
+      authChangeDispose();
+      authChangeDispose = null;
+    }
+  }
+
+  return {
+    user,
+    token,
+    isAuthenticated,
+    isLoading,
+    error,
+    login,
+    logout,
+    refresh,
+    setUser,
+    setToken,
+    destroy
+  };
+}
+
+/**
+ * Install a beforeEach route guard that redirects unauthenticated users.
+ *
+ * @param {Object} router — A Decantr router instance (from createRouter)
+ * @param {{
+ *   loginPath?: string,
+ *   redirectParam?: string,
+ *   isAuthenticated?: () => boolean
+ * }} [options]
+ */
+export function requireAuth(router, options = {}) {
+  const {
+    loginPath = '/login',
+    redirectParam = 'redirect',
+    isAuthenticated = null
+  } = options;
+
+  if (!router || typeof router.onNavigate !== 'function') {
+    throw new Error('requireAuth expects a Decantr router instance');
+  }
+
+  // We use onNavigate + navigate pattern since the router's beforeEach
+  // is set at construction time. This guard intercepts navigations by
+  // hooking into the router's existing lifecycle.
+  // However, if the router exposes a _beforeEach slot, we can use it.
+  // Since createRouter accepts beforeEach in config, and we want to add
+  // a guard post-construction, we store a reference and use onNavigate
+  // to redirect after the fact.
+
+  // The most reliable approach: override the navigate function to add a check
+  const originalNavigate = router.navigate;
+  const routerCurrent = router.current;
+
+  router.navigate = function guardedNavigate(to, opts) {
+    // Resolve the target path
+    let targetPath;
+    if (typeof to === 'object' && to.name) {
+      // Named route — let the original resolve it; we need the path
+      // For named routes, we can't easily pre-check, so navigate and check via onNavigate
+      return originalNavigate(to, opts);
+    }
+    targetPath = typeof to === 'string' ? to : '/';
+
+    // Skip guard for the login page itself
+    if (targetPath === loginPath || targetPath.startsWith(loginPath + '?') || targetPath.startsWith(loginPath + '/')) {
+      return originalNavigate(to, opts);
+    }
+
+    // Check authentication
+    const authCheck = typeof isAuthenticated === 'function' ? isAuthenticated : null;
+    if (authCheck && !authCheck()) {
+      const redirectTo = loginPath + (redirectParam ? `?${redirectParam}=${encodeURIComponent(targetPath)}` : '');
+      return originalNavigate(redirectTo, { replace: true });
+    }
+
+    return originalNavigate(to, opts);
+  };
+
+  // Also handle initial navigation and popstate-driven navigation via onNavigate
+  const unsubscribe = router.onNavigate((to) => {
+    const authCheck = typeof isAuthenticated === 'function' ? isAuthenticated : null;
+    if (!authCheck) return;
+
+    // Skip if already on login page
+    if (to.path === loginPath || to.path.startsWith(loginPath + '/')) return;
+
+    // If not authenticated, redirect to login
+    if (!authCheck()) {
+      const redirectTo = loginPath + (redirectParam ? `?${redirectParam}=${encodeURIComponent(to.path)}` : '');
+      // Use setTimeout to avoid navigating during a navigation callback
+      setTimeout(() => originalNavigate(redirectTo, { replace: true }), 0);
+    }
+  });
+
+  // Return a cleanup function
+  return function removeGuard() {
+    router.navigate = originalNavigate;
+    unsubscribe();
+  };
+}