@uniweb/core 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -30,8 +30,8 @@
     "jest": "^29.7.0"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "1.1.9",
-    "@uniweb/theming": "0.1.3"
+    "@uniweb/theming": "0.1.3",
+    "@uniweb/semantic-parser": "1.1.9"
   },
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"

package/src/datastore.js

@@ -1,152 +1,153 @@
 /**
  * DataStore
  *
- * Runtime data cache that persists across SPA navigation.
- * Deduplicates in-flight fetches so concurrent callers share a single request.
+ * Pure keyed cache with in-flight deduplication. Persists across SPA navigation.
  *
- * Core can't import runtime, so the fetcher function is registered at startup
- * via registerFetcher().
+ * Owned by the Website; accessed only by the FetcherDispatcher (which computes
+ * cache keys and runs fetchers) and by build-time / startup preload paths
+ * (which write entries keyed by the default cache key so runtime cache probes
+ * find them).
+ *
+ * No knowledge of fetchers, transports, or cascades. Keys are opaque strings.
  */
 
 /**
- * Build a stable cache key from a fetch config.
- * Only includes fields that affect the response.
+ * Default cache-key derivation for a request or fetch config.
+ *
+ * The framework's default URL fetcher and the build-time preload path both
+ * use this key shape. Fetchers with state-dependent requests (e.g., a query
+ * slug read from `page.state`) must declare their own `cacheKey(request)`
+ * on the fetcher so reactive changes miss the cache and re-fetch.
+ *
+ * Fields that contribute to the key:
+ *   - path, url       — what resource is being fetched
+ *   - schema          — which entity type the response will be stored under
+ *   - transform       — any per-fetch response unwrap; different transforms
+ *                       of the same endpoint produce different cached data
+ *   - method (POST)   — POST requests may share a URL with GET; don't collide
+ *   - body (POST)     — two POSTs to the same URL with different bodies are
+ *                       different queries; must cache distinctly
  *
- * @param {Object} config
- * @returns {string}
+ * Post-processing fields like `limit`, `sort`, `filter` are applied after
+ * fetch and must not split the cache.
+ *
+ * @param {Object} request - Normalized request (or fetch config)
+ * @returns {string} A stable JSON string usable as a cache-Map key
  */
-function cacheKey(config) {
-  const { path, url, schema, transform } = config
-  return JSON.stringify({ path, url, schema, transform })
+export function deriveCacheKey(request) {
+  const { path, url, schema, transform } = request || {}
+  const method = request?.method && request.method.toUpperCase() !== 'GET'
+    ? request.method.toUpperCase()
+    : undefined
+  const body = method === 'POST' ? request?.body : undefined
+  return JSON.stringify({ path, url, schema, transform, method, body })
 }
 
 export default class DataStore {
   constructor() {
+    // key → { data, meta? }
     this._cache = new Map()
+    // key → { promise, signals: Set<AbortSignal> }
     this._inflight = new Map()
-    this._fetcher = null
-    this._transforms = new Map()
+    // Notified on every successful `set()`.
     this._listeners = new Set()
+    // Key-scoped listeners: key → Set<Function>
+    this._keyedListeners = new Map()
 
     Object.seal(this)
   }
 
   /**
-   * Subscribe to data updates. Returns an unsubscribe function.
-   * Called by PageRenderer to re-render when dynamic page data arrives.
-   * @param {Function} fn - Called whenever new data is stored
+   * Subscribe to cache updates.
+   *
+   * Two forms:
+   *   - `subscribe(fn)`      — fires after every successful `set()` (all keys).
+   *   - `subscribe(key, fn)` — fires only when `set(key, ...)` is called.
+   *
+   * The global form is useful for debugging / blanket observers. The keyed
+   * form is what Layer-3 kit hooks (`useFetched`, `useCacheEntry`) use so
+   * a cache write for one request doesn't wake up every subscriber.
+   *
+   * @param {string|Function} keyOrFn
+   * @param {Function} [maybeFn]
    * @returns {Function} unsubscribe
    */
-  onUpdate(fn) {
-    this._listeners.add(fn)
-    return () => this._listeners.delete(fn)
-  }
-
-  /**
-   * Register the fetcher function (called by runtime at startup).
-   * @param {Function} fn - (config) => Promise<{ data, error? }>
-   */
-  registerFetcher(fn) {
-    this._fetcher = fn
-  }
-
-  /**
-   * Register a named transform function.
-   * Named transforms are applied after the fetcher returns, before caching.
-   * @param {string} name - Transform name (e.g. 'profiles')
-   * @param {Function} fn - (data, config) => transformedData
-   */
-  registerTransform(name, fn) {
-    this._transforms.set(name, fn)
+  subscribe(keyOrFn, maybeFn) {
+    if (typeof keyOrFn === 'string' && typeof maybeFn === 'function') {
+      const key = keyOrFn
+      let set = this._keyedListeners.get(key)
+      if (!set) {
+        set = new Set()
+        this._keyedListeners.set(key, set)
+      }
+      set.add(maybeFn)
+      return () => {
+        const s = this._keyedListeners.get(key)
+        if (!s) return
+        s.delete(maybeFn)
+        if (s.size === 0) this._keyedListeners.delete(key)
+      }
+    }
+    if (typeof keyOrFn === 'function') {
+      this._listeners.add(keyOrFn)
+      return () => this._listeners.delete(keyOrFn)
+    }
+    throw new TypeError('DataStore.subscribe: expected (fn) or (key, fn)')
   }
 
   /**
-   * Check whether data for this config is cached.
-   * @param {Object} config - Fetch config
+   * Cache presence check.
+   *
+   * @param {string} key
    * @returns {boolean}
    */
-  has(config) {
-    return this._cache.has(cacheKey(config))
+  has(key) {
+    return this._cache.has(key)
   }
 
   /**
-   * Return cached data, or null on miss.
-   * @param {Object} config - Fetch config
-   * @returns {any|null}
+   * Cache lookup.
+   *
+   * @param {string} key
+   * @returns {{ data: any, meta?: Object } | null}
    */
-  get(config) {
-    const key = cacheKey(config)
+  get(key) {
     return this._cache.has(key) ? this._cache.get(key) : null
   }
 
   /**
-   * Store data in the cache.
-   * @param {Object} config - Fetch config
-   * @param {any} data
+   * Cache store. Fires listeners: first the global ones (all-writes), then
+   * any subscribers registered for this specific key.
+   *
+   * @param {string} key
+   * @param {{ data: any, meta?: Object }} entry
    */
-  set(config, data) {
-    this._cache.set(cacheKey(config), data)
-    this._listeners.forEach((fn) => fn())
+  set(key, entry) {
+    this._cache.set(key, entry)
+    for (const fn of this._listeners) fn()
+    const keyed = this._keyedListeners.get(key)
+    if (keyed) {
+      for (const fn of keyed) fn()
+    }
   }
 
   /**
-   * Fetch data with caching and in-flight deduplication.
-   *
-   * - Cache hit: returns immediately.
-   * - In-flight: returns existing promise (no duplicate request).
-   * - Miss: calls the registered fetcher, caches the result.
+   * In-flight fetch registry — used by the dispatcher to dedup concurrent
+   * requests and collect abort signals so the underlying fetch is cancelled
+   * only when every attached block aborts.
    *
-   * @param {Object} config - Fetch config
-   * @returns {Promise<{ data: any, error?: string }>}
+   * @returns {Map<string, { promise: Promise, signals: Set<AbortSignal> }>}
    */
-  async fetch(config) {
-    if (!this._fetcher) {
-      throw new Error('DataStore: no fetcher registered. Call registerFetcher() first.')
-    }
-
-    const key = cacheKey(config)
-
-    // Cache hit
-    if (this._cache.has(key)) {
-      return { data: this._cache.get(key) }
-    }
-
-    // In-flight dedup
-    if (this._inflight.has(key)) {
-      return this._inflight.get(key)
-    }
-
-    // Miss — execute fetch
-    const promise = this._fetcher(config).then((result) => {
-      this._inflight.delete(key)
-      let data = result.data
-      // Apply named transform if registered (dot-path transforms
-      // are handled by the fetcher itself via getNestedValue)
-      if (
-        data !== undefined &&
-        data !== null &&
-        config.transform &&
-        this._transforms.has(config.transform)
-      ) {
-        data = this._transforms.get(config.transform)(data, config)
-      }
-      if (data !== undefined && data !== null) {
-        this._cache.set(key, data)
-        this._listeners.forEach((fn) => fn())
-      }
-      return { ...result, data }
-    })
-
-    this._inflight.set(key, promise)
-    return promise
+  get inflight() {
+    return this._inflight
   }
 
   /**
-   * Flush cache and in-flight map.
+   * Flush cache and in-flight map. Listeners are preserved so subscribers
+   * that outlive the cache (kit hooks waiting on a key) aren't orphaned.
    */
   clear() {
     this._cache.clear()
     this._inflight.clear()
-    this._transforms.clear()
   }
 }