@ozsarman/clarityjs 0.6.0

package/src/async-state.js

@@ -0,0 +1,555 @@
+/**
+ * Clarity.js — Async State Management
+ *
+ * Reactive data fetching with cache, stale-while-revalidate, optimistic updates,
+ * and automatic deduplication. Inspired by TanStack Query / SWR but built
+ * natively on Clarity signals.
+ *
+ * Quick reference:
+ *
+ *   const users = createQuery(() => fetch('/api/users').then(r => r.json()))
+ *
+ *   // In a component render:
+ *   users.data.get()    // current data (or undefined while loading)
+ *   users.loading.get() // true while the first fetch is in-flight
+ *   users.error.get()   // Error | null
+ *   users.stale.get()   // true when showing cached data, refetch in progress
+ *
+ *   users.refetch()     // manual refetch
+ *   users.mutate(newData, { revalidate: true }) // optimistic update + sync
+ *   users.invalidate()  // mark cache stale and trigger background refetch
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal, effect, batch } from './runtime.js';
+
+// ─── Global query cache ───────────────────────────────────────────────────────
+// Key → { data, error, timestamp, subscribers, inFlight }
+
+const _cache = new Map();
+const _DEFAULT_STALE_TIME   = 30_000; // 30 s
+const _DEFAULT_CACHE_TIME   = 5 * 60_000; // 5 min
+const _DEFAULT_RETRY        = 3;
+const _DEFAULT_RETRY_DELAY  = (attempt) => Math.min(1000 * 2 ** attempt, 30_000);
+
+// ─── QueryState ───────────────────────────────────────────────────────────────
+
+class QueryState {
+  constructor(key, fetchFn, options) {
+    this._key     = key;
+    this._fetchFn = fetchFn;
+    this._opts    = options;
+
+    // Public signals (readable from components)
+    this.data    = signal(undefined);
+    this.error   = signal(null);
+    this.loading = signal(false);
+    this.stale   = signal(false);
+
+    // Internal
+    this._inFlight    = false;
+    this._retryCount  = 0;
+    this._lastFetched = 0;
+    this._gcTimer     = null;
+  }
+
+  // ── Core fetch logic ────────────────────────────────────────────────────────
+
+  async fetch({ force = false } = {}) {
+    const opts = this._opts;
+
+    // Deduplicate: if already in-flight, skip
+    if (this._inFlight && !force) return;
+
+    // Stale-while-revalidate: use cached data if fresh
+    const now     = Date.now();
+    const staleMs = opts.staleTime ?? _DEFAULT_STALE_TIME;
+    const isFresh = this._lastFetched > 0 && (now - this._lastFetched) < staleMs;
+
+    if (isFresh && !force) return; // still fresh, no need to refetch
+
+    // If we have data but it's stale, mark as stale (SWR)
+    if (this.data.peek() !== undefined) {
+      this.stale.set(true);
+    } else {
+      this.loading.set(true);
+    }
+
+    this._inFlight   = true;
+    this._retryCount = 0;
+
+    await this._fetchWithRetry();
+  }
+
+  async _fetchWithRetry() {
+    const opts     = this._opts;
+    const maxRetry = opts.retry ?? _DEFAULT_RETRY;
+    const delay    = opts.retryDelay ?? _DEFAULT_RETRY_DELAY;
+
+    while (this._retryCount <= maxRetry) {
+      try {
+        const result = await this._fetchFn(this._key);
+
+        // Success — update signals atomically
+        batch(() => {
+          this.data.set(result);
+          this.error.set(null);
+          this.loading.set(false);
+          this.stale.set(false);
+        });
+
+        this._lastFetched = Date.now();
+        this._inFlight    = false;
+        this._retryCount  = 0;
+
+        // Notify cache
+        _cache.set(this._key, {
+          data:      result,
+          timestamp: this._lastFetched,
+        });
+
+        // Schedule garbage collection
+        this._scheduleGC();
+        return;
+
+      } catch (err) {
+        this._retryCount++;
+
+        if (this._retryCount > maxRetry) {
+          // All retries exhausted
+          batch(() => {
+            this.error.set(err);
+            this.loading.set(false);
+            this.stale.set(false);
+          });
+          this._inFlight = false;
+
+          opts.onError?.(err, this._key);
+          return;
+        }
+
+        // Wait before retry
+        const waitMs = typeof delay === 'function'
+          ? delay(this._retryCount)
+          : delay;
+
+        await _sleep(waitMs);
+      }
+    }
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  /** Force a refetch regardless of cache freshness. */
+  refetch() {
+    return this.fetch({ force: true });
+  }
+
+  /**
+   * Optimistic update — set data immediately, optionally revalidate.
+   *
+   * @param {* | ((current: *) => *)} updater  - New value or updater function
+   * @param {{ revalidate?: boolean }}  options
+   */
+  mutate(updater, { revalidate = false } = {}) {
+    const current = this.data.peek();
+    const next    = typeof updater === 'function' ? updater(current) : updater;
+    this.data.set(next);
+
+    _cache.set(this._key, { data: next, timestamp: Date.now() });
+
+    if (revalidate) {
+      // Sync in background
+      this.fetch({ force: true }).catch(err => {
+        console.error('[Clarity createQuery] revalidate after mutate failed:', err);
+      });
+    }
+  }
+
+  /**
+   * Mark as stale — triggers a background refetch on next read or immediately.
+   */
+  invalidate() {
+    this._lastFetched = 0;
+    if (this._opts.invalidateImmediately !== false) {
+      this.fetch({ force: false });
+    }
+  }
+
+  /** Cancel any pending in-flight request (best-effort via AbortController). */
+  cancel() {
+    this._inFlight = false;
+  }
+
+  /** Clean up timers and listeners. */
+  dispose() {
+    if (this._gcTimer) clearTimeout(this._gcTimer);
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────────────
+
+  _scheduleGC() {
+    const cacheTime = this._opts.cacheTime ?? _DEFAULT_CACHE_TIME;
+    if (this._gcTimer) clearTimeout(this._gcTimer);
+    this._gcTimer = setTimeout(() => {
+      _cache.delete(this._key);
+    }, cacheTime);
+  }
+}
+
+// ─── createQuery ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a reactive, cached, auto-fetching data source.
+ *
+ * @param {string | (() => string)}        key       - Cache key (string or reactive function)
+ * @param {(key: string) => Promise<*>}    fetchFn   - Async data fetcher
+ * @param {CreateQueryOptions}             [options]
+ * @returns {QueryState}
+ *
+ * @typedef {object} CreateQueryOptions
+ * @property {boolean}            [enabled=true]          - Set false to disable auto-fetch
+ * @property {number}             [staleTime=30000]        - Ms until cached data is stale
+ * @property {number}             [cacheTime=300000]       - Ms to keep data in cache
+ * @property {number}             [retry=3]               - Retry count on failure
+ * @property {number|Function}    [retryDelay]            - Ms or fn(attempt)→ms
+ * @property {boolean}            [refetchOnWindowFocus=true] - Refetch on tab focus
+ * @property {number|false}       [refetchInterval=false] - Polling interval (ms)
+ * @property {Function}           [onSuccess]             - (data, key) → void
+ * @property {Function}           [onError]               - (err, key) → void
+ * @property {*}                  [initialData]           - Pre-seed data (skips first fetch)
+ * @property {boolean}            [invalidateImmediately=true] - Fetch on invalidate()
+ *
+ * @example
+ * const todos = createQuery(
+ *   'todos',
+ *   () => fetch('/api/todos').then(r => r.json()),
+ *   { staleTime: 60_000 }
+ * );
+ *
+ * // Dynamic key (re-fetches when userId changes)
+ * const post = createQuery(
+ *   () => `post/${userId.get()}`,
+ *   (key) => fetch(`/api/${key}`).then(r => r.json())
+ * );
+ */
+export function createQuery(key, fetchFn, options = {}) {
+  // Support key-less API: createQuery(fetchFn, options)
+  if (typeof key === 'function' && typeof fetchFn !== 'function') {
+    options  = fetchFn ?? {};
+    fetchFn  = key;
+    key      = null; // computed key
+  }
+
+  const isReactiveKey = typeof key === 'function';
+  const resolvedKey   = isReactiveKey ? key() : (key ?? crypto.randomUUID?.() ?? Math.random().toString(36));
+
+  const state = new QueryState(resolvedKey, fetchFn, options);
+
+  // Seed initial data if provided
+  if (options.initialData !== undefined) {
+    state.data.set(options.initialData);
+    state._lastFetched = Date.now();
+  } else {
+    // Restore from cache if available
+    const cached = _cache.get(resolvedKey);
+    if (cached) {
+      state.data.set(cached.data);
+      state._lastFetched = cached.timestamp;
+    }
+  }
+
+  // Auto-fetch if enabled
+  const enabled = options.enabled !== false;
+  if (enabled) {
+    // Defer to microtask so the component can finish rendering first
+    Promise.resolve().then(() => state.fetch());
+  }
+
+  // Re-fetch when reactive key changes
+  if (isReactiveKey) {
+    effect(() => {
+      const newKey = key();
+      if (newKey !== state._key) {
+        state._key = newKey;
+        state._lastFetched = 0;
+        state.fetch({ force: false });
+      }
+    });
+  }
+
+  // Polling support
+  if (options.refetchInterval && options.refetchInterval > 0) {
+    const intervalId = setInterval(() => {
+      state.fetch({ force: false });
+    }, options.refetchInterval);
+
+    // Return dispose function attached to state
+    const origDispose = state.dispose.bind(state);
+    state.dispose = () => {
+      clearInterval(intervalId);
+      origDispose();
+    };
+  }
+
+  // Window focus refetch
+  if (options.refetchOnWindowFocus !== false &&
+      typeof window !== 'undefined' &&
+      typeof window.addEventListener === 'function') {
+    const onFocus = () => state.fetch({ force: false });
+    window.addEventListener('focus', onFocus);
+    const origDispose = state.dispose.bind(state);
+    state.dispose = () => {
+      window.removeEventListener('focus', onFocus);
+      origDispose();
+    };
+  }
+
+  return state;
+}
+
+// ─── useFetch ─────────────────────────────────────────────────────────────────
+
+/**
+ * useFetch — Nuxt-style alias over createQuery().
+ *
+ * A familiar entry point for developers coming from Nuxt. It is a thin wrapper
+ * around createQuery() with one ergonomic addition: if the first argument is a
+ * string or URL, it is treated as a URL to fetch (JSON), so the common case
+ * needs no fetcher function at all.
+ *
+ * @example — URL shorthand (auto fetch + JSON parse)
+ *   const posts = useFetch('/api/posts');
+ *   //  posts.data() · posts.loading() · posts.error() · posts.refetch()
+ *
+ * @example — Reactive URL (re-fetches when the signal changes)
+ *   const post = useFetch(() => `/api/posts/${id.get()}`);
+ *
+ * @example — Custom fetcher / options (identical to createQuery)
+ *   const users = useFetch('users', () => api.getUsers(), { staleTime: 60_000 });
+ *
+ * @param {string | URL | Function} keyOrUrl — URL string, reactive URL fn, or query key
+ * @param {Function | object} [fetchFn]       — fetcher (defaults to fetch+JSON for URLs)
+ * @param {object} [options]                  — same options as createQuery()
+ * @returns {QueryState}
+ */
+export function useFetch(keyOrUrl, fetchFn, options = {}) {
+  // URL shorthand: useFetch('/api/x'[, options]) or useFetch(() => url[, options])
+  const looksLikeUrl =
+    typeof keyOrUrl === 'string' ||
+    keyOrUrl instanceof URL ||
+    (typeof keyOrUrl === 'function' && typeof fetchFn !== 'function');
+
+  if (looksLikeUrl && typeof fetchFn !== 'function') {
+    // Second arg (if any) is the options object.
+    options = fetchFn ?? {};
+    const urlOf = typeof keyOrUrl === 'function' ? keyOrUrl : () => String(keyOrUrl);
+    const key   = typeof keyOrUrl === 'function' ? keyOrUrl : String(keyOrUrl);
+    const fetcher = async () => {
+      const res = await fetch(urlOf());
+      if (!res.ok) throw new Error(`[Clarity useFetch] HTTP ${res.status} for ${urlOf()}`);
+      const ct = res.headers?.get?.('content-type') ?? '';
+      return ct.includes('application/json') ? res.json() : res.text();
+    };
+    return createQuery(key, fetcher, options);
+  }
+
+  // Full pass-through to createQuery (key, fetchFn, options).
+  return createQuery(keyOrUrl, fetchFn, options);
+}
+
+// ─── createMutation ───────────────────────────────────────────────────────────
+
+/**
+ * Create a reactive mutation — for POST, PUT, DELETE operations.
+ * Supports TanStack Query-style optimistic updates with automatic rollback.
+ *
+ * @param {(variables: *) => Promise<*>} mutateFn   — async operation
+ * @param {object}   [options]
+ * @param {Function} [options.onMutate]     — (variables) → Promise<context> | context
+ *                                            Called before mutation fires.
+ *                                            Return a context object for rollback.
+ * @param {Function} [options.optimistic]   — (variables, currentData) → newData
+ *                                            Instantly update data before server responds.
+ *                                            Rolled back automatically on error.
+ * @param {Function} [options.onSuccess]    — (data, variables, context) → void
+ * @param {Function} [options.onError]      — (err, variables, context) → void
+ *                                            Called with the rollback context.
+ * @param {Function} [options.onSettled]    — (data|null, err|null, variables, context) → void
+ * @param {string | string[]} [options.invalidates] — query keys to invalidate on success
+ * @returns {{ mutate, mutateAsync, loading, error, data, reset, variables }}
+ *
+ * @example — Basic
+ *   const addTodo = createMutation(
+ *     (title) => fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) }).then(r => r.json()),
+ *     { onSuccess: () => todos.invalidate() }
+ *   );
+ *   addTodo.mutate('Buy milk');
+ *
+ * @example — Optimistic update
+ *   const toggleTodo = createMutation(
+ *     ({ id, done }) => fetch(`/api/todos/${id}`, { method: 'PATCH', body: JSON.stringify({ done }) }).then(r => r.json()),
+ *     {
+ *       optimistic: ({ id, done }, currentTodos) =>
+ *         currentTodos.map(t => t.id === id ? { ...t, done } : t),
+ *       onError: (err, vars, ctx) => {
+ *         todos.mutate(ctx.previousData); // manual rollback if needed
+ *       },
+ *     }
+ *   );
+ *
+ * @example — onMutate context
+ *   const deleteTodo = createMutation(deleteApi, {
+ *     onMutate: async (id) => {
+ *       const prev = todos.data.peek();
+ *       todos.mutate(prev.filter(t => t.id !== id)); // optimistic remove
+ *       return { previousTodos: prev };              // rollback context
+ *     },
+ *     onError: (err, id, ctx) => {
+ *       todos.mutate(ctx.previousTodos);             // undo on failure
+ *     },
+ *   });
+ */
+export function createMutation(mutateFn, options = {}) {
+  const loading   = signal(false);
+  const error     = signal(null);
+  const data      = signal(undefined);
+  const variables = signal(undefined); // last invocation variables
+
+  // Track optimistic snapshot for rollback
+  let _prevData = undefined;
+
+  /**
+   * Async version — returns Promise, throws on failure.
+   */
+  async function mutateAsync(vars) {
+    variables.set(vars);
+
+    batch(() => {
+      loading.set(true);
+      error.set(null);
+    });
+
+    // ── onMutate (may return rollback context) ─────────────────────────────
+    let context;
+    try {
+      if (typeof options.onMutate === 'function') {
+        context = await options.onMutate(vars);
+      }
+    } catch (mutateErr) {
+      // onMutate failure aborts the mutation
+      batch(() => { error.set(mutateErr); loading.set(false); });
+      throw mutateErr;
+    }
+
+    // ── Optimistic update ──────────────────────────────────────────────────
+    if (typeof options.optimistic === 'function') {
+      _prevData = data.peek();
+      data.set(options.optimistic(vars, _prevData));
+    }
+
+    // ── Execute mutation ───────────────────────────────────────────────────
+    try {
+      const result = await mutateFn(vars);
+
+      batch(() => {
+        data.set(result);
+        loading.set(false);
+      });
+      _prevData = undefined;
+
+      // Callbacks
+      options.onSuccess?.(result, vars, context);
+      options.onSettled?.(result, null, vars, context);
+
+      // Invalidate related queries
+      if (options.invalidates) {
+        const keys = Array.isArray(options.invalidates) ? options.invalidates : [options.invalidates];
+        for (const k of keys) invalidateQuery(k);
+      }
+
+      return result;
+
+    } catch (err) {
+      // ── Rollback optimistic update ───────────────────────────────────────
+      if (typeof options.optimistic === 'function' && _prevData !== undefined) {
+        data.set(_prevData);
+        _prevData = undefined;
+      }
+
+      batch(() => {
+        error.set(err);
+        loading.set(false);
+      });
+
+      options.onError?.(err, vars, context);
+      options.onSettled?.(null, err, vars, context);
+
+      throw err;
+    }
+  }
+
+  /**
+   * Trigger the mutation. Returns the underlying promise so callers may
+   * `await` it to read the resolved value; it rejects on failure (the error is
+   * ALSO captured in the `error` signal, so awaiting is optional for UI code
+   * that just renders from the signals).
+   */
+  function mutate(vars) {
+    return mutateAsync(vars);
+  }
+
+  function reset() {
+    _prevData = undefined;
+    batch(() => {
+      loading.set(false);
+      error.set(null);
+      data.set(undefined);
+      variables.set(undefined);
+    });
+  }
+
+  return { mutate, mutateAsync, loading, error, data, variables, reset };
+}
+
+// ─── Cache utilities ──────────────────────────────────────────────────────────
+
+/**
+ * Manually invalidate a cached query by key.
+ * @param {string} key
+ */
+export function invalidateQuery(key) {
+  _cache.delete(key);
+}
+
+/**
+ * Pre-populate the cache with data (useful for SSR → client handoff).
+ * @param {string} key
+ * @param {*}      data
+ */
+export function prefetchQuery(key, data) {
+  _cache.set(key, { data, timestamp: Date.now() });
+}
+
+/**
+ * Clear the entire query cache.
+ */
+export function clearQueryCache() {
+  _cache.clear();
+}
+
+/**
+ * Read raw cache entry (useful for testing or SSR state transfer).
+ * @param {string} key
+ * @returns {{ data: *, timestamp: number } | undefined}
+ */
+export function getCacheEntry(key) {
+  return _cache.get(key);
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/bundle-runtime.js

@@ -0,0 +1,35 @@
+/**
+ * Bundles clarity-runtime.js into a browser-ready IIFE
+ * Output: dist/clarity-runtime.browser.js
+ * Usage: <script src="clarity-runtime.browser.js"></script>
+ *        window.ClarityRuntime.signal(0) etc.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+const runtimeSrc = readFileSync('./src/runtime.js', 'utf8');
+
+// Strip ES module exports — convert to IIFE
+const iife = `
+// Clarity.js Runtime v0.0.1 — Browser Build
+// AI-Native UI Framework by Claude (Anthropic)
+(function(global) {
+  'use strict';
+
+${runtimeSrc
+  .replace(/^export function /gm, 'function ')
+  .replace(/^export const /gm, 'const ')
+  .replace(/^export \{[^}]+\};?/gm, '')
+}
+
+  // Expose to global scope
+  global.ClarityRuntime = {
+    signal, effect, computed, batch, mount, h, appendChild, when, list, __dev__
+  };
+
+})(typeof window !== 'undefined' ? window : globalThis);
+`.trim();
+
+mkdirSync('./dist', { recursive: true });
+writeFileSync('./dist/clarity-runtime.browser.js', iife, 'utf8');
+console.log('✓ dist/clarity-runtime.browser.js written');