@ozsarman/clarityjs 0.6.0

package/src/store.js

@@ -0,0 +1,276 @@
+/**
+ * Clarity.js — Global Store
+ *
+ * Signal-based cross-component state management.
+ * Inspired by Pinia (Vue) and Zustand (React), built natively on Clarity signals.
+ *
+ * Quick start:
+ *
+ *   // stores/counter.js
+ *   import { createStore } from '@ozsarman/clarityjs/store';
+ *
+ *   export const useCounterStore = createStore('counter', {
+ *     state: () => ({ count: 0, step: 1 }),
+ *
+ *     getters: {
+ *       doubled: (state) => state.count * 2,
+ *       label:   (state) => `Count is ${state.count}`,
+ *     },
+ *
+ *     actions: {
+ *       increment()          { this.count += this.step; },
+ *       decrement()          { this.count -= this.step; },
+ *       async loadFromAPI()  {
+ *         const data = await fetch('/api/count').then(r => r.json());
+ *         this.count = data.value;
+ *       },
+ *     },
+ *   });
+ *
+ *   // In any component:
+ *   const store = useCounterStore();
+ *   store.count          // reactive read (current signal value)
+ *   store.doubled        // reactive getter
+ *   store.increment()    // action
+ *   store.$patch({ count: 10, step: 2 })   // batch update
+ *   store.$reset()       // restore initial state
+ *   store.$subscribe(state => console.log(state))  // watch all changes
+ *
+ * Devtools integration:
+ *   Each store self-registers with __clarity_stores__ on globalThis so that
+ *   the Clarity DevTools panel can enumerate stores and inspect their state.
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal, computed, effect, batch } from './runtime.js';
+
+// ─── Global store registry (for devtools) ────────────────────────────────────
+
+if (typeof globalThis.__clarity_stores__ === 'undefined') {
+  globalThis.__clarity_stores__ = new Map();
+}
+
+// ─── createStore ─────────────────────────────────────────────────────────────
+
+/**
+ * Define a global reactive store.
+ *
+ * Returns a factory function (useXxxStore) that can be called anywhere to get
+ * the singleton store instance — all callers share the same reactive signals.
+ *
+ * @template {object} S
+ * @template {object} G
+ * @template {object} A
+ *
+ * @param {string} id        — Unique store identifier (used by DevTools)
+ * @param {object} definition
+ * @param {() => S}   definition.state    — Factory that returns initial state
+ * @param {G}         [definition.getters]  — Derived values (computed signals)
+ * @param {A}         [definition.actions]  — Methods that mutate state
+ *
+ * @returns {() => StoreInstance<S, G, A>}
+ */
+export function createStore(id, { state: stateFn, getters = {}, actions = {} }) {
+  if (typeof id !== 'string' || !id) {
+    throw new Error('[Clarity createStore] id must be a non-empty string');
+  }
+  if (typeof stateFn !== 'function') {
+    throw new Error('[Clarity createStore] state must be a function that returns an object');
+  }
+
+  // ── Singleton: created once, shared across all callers ─────────────────────
+  let _instance = null;
+
+  function _createInstance() {
+    const initialState = stateFn();
+    if (typeof initialState !== 'object' || initialState === null) {
+      throw new Error(`[Clarity createStore] "${id}" state() must return a plain object`);
+    }
+
+    // ── 1. Turn every state key into a signal ───────────────────────────────
+    const _signals = {};
+    for (const [key, val] of Object.entries(initialState)) {
+      _signals[key] = signal(val);
+    }
+
+    // ── 2. Subscribers list (for $subscribe) ────────────────────────────────
+    const _subscribers = new Set();
+
+    // ── 3. Build the public store proxy ─────────────────────────────────────
+    const _stateProxy = new Proxy({}, {
+      get(_, key) {
+        if (key in _signals) return _signals[key].get();
+        return undefined;
+      },
+      set(_, key, value) {
+        if (key in _signals) {
+          _signals[key].set(value);
+        } else {
+          // Dynamically add new state key
+          _signals[key] = signal(value);
+        }
+        return true;
+      },
+      has(_, key)     { return key in _signals; },
+      ownKeys()       { return Object.keys(_signals); },
+      getOwnPropertyDescriptor(_, key) {
+        if (key in _signals) return { enumerable: true, configurable: true, writable: true };
+        return undefined;
+      },
+    });
+
+    // ── 4. Build computed getters ────────────────────────────────────────────
+    const _computed = {};
+    for (const [key, fn] of Object.entries(getters)) {
+      _computed[key] = computed(() => fn(_stateProxy));
+    }
+
+    // ── 5. Build bound action methods ────────────────────────────────────────
+    // Actions run with `this` pointing at the proxy so they can do:
+    //   this.count += 1   or   await this.loadData()
+    const _actions = {};
+    for (const [key, fn] of Object.entries(actions)) {
+      _actions[key] = function (...args) {
+        return fn.apply(_stateProxy, args);
+      };
+    }
+
+    // ── 6. Effect to notify $subscribe listeners ─────────────────────────────
+    effect(() => {
+      // Read all signals to subscribe to all of them
+      const snapshot = {};
+      for (const [k, sig] of Object.entries(_signals)) {
+        snapshot[k] = sig.get();
+      }
+      // Notify subscribers (skip on first run before any listener is added)
+      if (_subscribers.size > 0) {
+        _subscribers.forEach(fn => {
+          try { fn(snapshot); } catch {}
+        });
+      }
+    });
+
+    // ── 7. Assemble public API ───────────────────────────────────────────────
+    const store = new Proxy({}, {
+      get(_, key) {
+        // State reads — reactive
+        if (key in _signals)   return _signals[key].get();
+        // Getter reads — computed
+        if (key in _computed)  return _computed[key].get();
+        // Actions
+        if (key in _actions)   return _actions[key];
+        // $ helpers
+        if (key === '$id')          return id;
+        if (key === '$state')       return _stateProxy;
+        if (key === '$signals')     return _signals;   // for devtools
+        if (key === '$patch')       return _patch;
+        if (key === '$reset')       return _reset;
+        if (key === '$subscribe')   return _subscribe;
+        if (key === '$dispose')     return _dispose;
+        return undefined;
+      },
+      set(_, key, value) {
+        if (key in _signals) {
+          _signals[key].set(value);
+          return true;
+        }
+        return false;
+      },
+      has(_, key) {
+        return (key in _signals) || (key in _computed) || (key in _actions) ||
+          ['$id','$state','$signals','$patch','$reset','$subscribe','$dispose'].includes(key);
+      },
+      ownKeys() {
+        return [
+          ...Object.keys(_signals),
+          ...Object.keys(_computed),
+          ...Object.keys(_actions),
+          '$id', '$patch', '$reset', '$subscribe', '$dispose',
+        ];
+      },
+    });
+
+    // ── $patch — batch update multiple state keys ────────────────────────────
+    function _patch(partial) {
+      if (typeof partial === 'function') {
+        // Patcher receives the proxy and mutates directly
+        batch(() => partial(_stateProxy));
+      } else {
+        batch(() => {
+          for (const [k, v] of Object.entries(partial)) {
+            if (k in _signals) _signals[k].set(v);
+          }
+        });
+      }
+    }
+
+    // ── $reset — restore initial state ───────────────────────────────────────
+    function _reset() {
+      const fresh = stateFn();
+      batch(() => {
+        for (const [k, v] of Object.entries(fresh)) {
+          if (k in _signals) _signals[k].set(v);
+        }
+      });
+    }
+
+    // ── $subscribe — watch all state changes ─────────────────────────────────
+    /**
+     * @param {(state: S) => void} fn   Called with a snapshot on any change
+     * @returns {() => void}            Unsubscribe function
+     */
+    function _subscribe(fn) {
+      _subscribers.add(fn);
+      return () => _subscribers.delete(fn);
+    }
+
+    // ── $dispose — remove from global registry (tests / SSR) ─────────────────
+    function _dispose() {
+      globalThis.__clarity_stores__.delete(id);
+      _instance = null;
+    }
+
+    // Register in global devtools registry
+    globalThis.__clarity_stores__.set(id, store);
+
+    return store;
+  }
+
+  // ── Returned hook — always returns the same singleton ────────────────────
+  return function useStore() {
+    if (!_instance) _instance = _createInstance();
+    return _instance;
+  };
+}
+
+// ─── Store utilities ─────────────────────────────────────────────────────────
+
+/**
+ * Get the registry of all active stores (for DevTools).
+ * @returns {Map<string, object>}
+ */
+export function getStoreRegistry() {
+  return globalThis.__clarity_stores__;
+}
+
+/**
+ * Reset all registered stores to their initial state.
+ * Useful in tests: call between each test case.
+ */
+export function resetAllStores() {
+  for (const store of globalThis.__clarity_stores__.values()) {
+    store.$reset?.();
+  }
+}
+
+/**
+ * Dispose (destroy) all registered stores.
+ * Used in SSR per-request isolation to avoid state leaking between requests.
+ */
+export function disposeAllStores() {
+  for (const store of globalThis.__clarity_stores__.values()) {
+    store.$dispose?.();
+  }
+  globalThis.__clarity_stores__.clear();
+}