@uniweb/core 0.6.1 → 0.6.2

package/src/fetcher-dispatcher.js

@@ -0,0 +1,333 @@
+/**
+ * FetcherDispatcher
+ *
+ * Assembled by the Website from the primary foundation's named transports
+ * plus any extensions'. Resolves which fetcher handles a given request by
+ * name lookup — the site selects per-schema in `site.yml fetcher.transports`.
+ *
+ * The dispatcher owns cache-key derivation, checks the DataStore, dedups
+ * concurrent in-flight requests, and passes an AbortSignal through to the
+ * selected fetcher. A runtime `transport` override (editor preview bridge)
+ * bypasses all of that and handles every request directly.
+ *
+ * The dispatcher is the only layer that touches DataStore directly;
+ * EntityStore calls the dispatcher's `peek` / `dispatch` methods and
+ * never goes around it.
+ */
+import { deriveCacheKey } from './datastore.js'
+
+/**
+ * Extract the declaration object from a foundation — either an ESM module
+ * with a default export, or an already-plain declaration.
+ */
+function getFoundationDecl(mod) {
+  if (!mod) return null
+  if (mod.default && typeof mod.default === 'object') return mod.default
+  if (typeof mod === 'object') return mod
+  return null
+}
+
+function isValidTransport(t) {
+  return !!t && typeof t.resolve === 'function'
+}
+
+/**
+ * Collect transports from a foundation declaration, returning a Map
+ * `name → transport`. Throwing or malformed entries are dropped with a
+ * dev-mode warning so a single bad transport never tears down the
+ * registry. This mirrors the `Promise.allSettled` pattern the runtime
+ * uses when loading extensions — one bad extension doesn't block the site.
+ */
+function collectTransports(decl, { source, dev }) {
+  const out = new Map()
+  if (!decl) return out
+
+  let raw
+  try {
+    raw = decl.transports
+  } catch (err) {
+    if (dev) console.warn(`[FetcherDispatcher] ${source} transports getter threw:`, err)
+    return out
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out
+
+  for (const name of Object.keys(raw)) {
+    let t
+    try {
+      t = raw[name]
+    } catch (err) {
+      if (dev) {
+        console.warn(`[FetcherDispatcher] ${source} transport "${name}" getter threw:`, err)
+      }
+      continue
+    }
+    if (!isValidTransport(t)) {
+      if (dev) {
+        console.warn(
+          `[FetcherDispatcher] ${source} transport "${name}" missing resolve(); skipped.`,
+        )
+      }
+      continue
+    }
+    out.set(name, t)
+  }
+  return out
+}
+
+export default class FetcherDispatcher {
+  /**
+   * @param {Object} options
+   * @param {Object|null} options.foundation - Primary foundation module or declaration.
+   * @param {Array<Object>} [options.extensions] - Extension modules or declarations.
+   * @param {Object} options.dataStore - The Website's DataStore.
+   * @param {{ resolve: Function, cacheKey?: Function }} [options.defaultFetcher]
+   *   Framework default fetcher. Used when the site doesn't pick a named
+   *   transport for the request's schema.
+   * @param {{ resolve: Function, cacheKey?: Function }} [options.transport] -
+   *   Runtime-level transport override. When set, every Layer-1 request is
+   *   routed through this transport — no named-transport lookup, no fallback
+   *   to the framework default. Editor preview iframe only.
+   * @param {boolean} [options.dev] - Enable dev-mode validation warnings.
+   */
+  constructor({ foundation, extensions = [], dataStore, defaultFetcher = null, transport = null, dev = false }) {
+    if (!dataStore) throw new Error('FetcherDispatcher: dataStore is required')
+    this._dataStore = dataStore
+    this._defaultFetcher = defaultFetcher
+    this._transportOverride = isValidTransport(transport) ? transport : null
+    this._dev = !!dev
+
+    // Named transport registry. Primary foundation wins on name collisions
+    // with extensions (dev-mode warning); bad extension transports are
+    // skipped individually rather than tearing down the whole registry.
+    const registry = new Map()
+
+    const primaryTransports = collectTransports(getFoundationDecl(foundation), {
+      source: 'primary foundation',
+      dev: this._dev,
+    })
+    for (const [name, t] of primaryTransports) registry.set(name, t)
+
+    for (const ext of extensions) {
+      let extTransports
+      try {
+        extTransports = collectTransports(getFoundationDecl(ext), {
+          source: 'extension',
+          dev: this._dev,
+        })
+      } catch (err) {
+        if (this._dev) {
+          console.warn('[FetcherDispatcher] extension transports collection threw:', err)
+        }
+        continue
+      }
+      for (const [name, t] of extTransports) {
+        if (registry.has(name)) {
+          if (this._dev) {
+            console.warn(
+              `[FetcherDispatcher] extension transport "${name}" ignored — primary foundation already provides it.`,
+            )
+          }
+          continue
+        }
+        registry.set(name, t)
+      }
+    }
+
+    this._namedTransports = registry
+
+    Object.freeze(this)
+  }
+
+  /**
+   * Select the fetcher for a request.
+   *
+   *   1. Runtime `transport` override (editor preview) wins over everything.
+   *   2. Otherwise, look up the site's per-schema selection in
+   *      `ctx.website.config.fetcher.transports[schema]` → `.transports.default`.
+   *      A named match is resolved against the registry of foundation /
+   *      extension transports.
+   *   3. If the site didn't pick a name (or picked one that's not in the
+   *      registry), fall through to the framework default fetcher.
+   */
+  _selectFetcher(request, ctx) {
+    if (this._transportOverride) return this._transportOverride
+
+    const transportsConfig = ctx?.website?.config?.fetcher?.transports
+    if (transportsConfig && typeof transportsConfig === 'object') {
+      const schema = request?.schema
+      const name = (schema && transportsConfig[schema]) || transportsConfig.default
+      if (name) {
+        const t = this._namedTransports.get(name)
+        if (t) return t
+        if (this._dev) {
+          console.warn(
+            `[FetcherDispatcher] site selected transport "${name}" for schema "${schema ?? '(none)'}" ` +
+              'but no foundation or extension registered it; falling back to the framework default.',
+          )
+        }
+      }
+    }
+
+    return this._defaultFetcher
+  }
+
+  _cacheKey(fetcher, request) {
+    if (fetcher && typeof fetcher.cacheKey === 'function') {
+      try {
+        return String(fetcher.cacheKey(request))
+      } catch (err) {
+        console.warn('[FetcherDispatcher] fetcher.cacheKey threw:', err)
+      }
+    }
+    return deriveCacheKey(request)
+  }
+
+  /**
+   * Synchronous cache probe. Selects the fetcher (for key derivation), checks
+   * DataStore, returns the cached `{ data, meta }` entry or null. Never starts
+   * a fetch.
+   */
+  peek(request, ctx = {}) {
+    const fetcher = this._selectFetcher(request, ctx)
+    const key = this._cacheKey(fetcher, request)
+    return this._dataStore.get(key)
+  }
+
+  /**
+   * Full dispatch — selection, cache check, in-flight dedup, execution.
+   *
+   *   Cache hit        → returns a resolved promise with the cached entry.
+   *   In-flight match  → attaches the caller's signal, awaits the shared promise.
+   *   Miss             → runs fetcher, stores on success, returns the result.
+   *
+   * Signal semantics: the dispatcher owns a master `AbortController` per
+   * in-flight entry. The fetcher sees the master's signal in `ctx.signal`;
+   * each caller's own signal is attached for bookkeeping. The master aborts
+   * only when every attached signal has aborted — so cancelling one block
+   * doesn't kill a fetch another block still needs.
+   *
+   * Error isolation: thrown exceptions and malformed returns surface as
+   * `{ data: [], error }` and never poison the cache. Successful results
+   * containing an `error` field are passed through unchanged and not cached.
+   */
+  async dispatch(request, ctx = {}) {
+    const fetcher = this._selectFetcher(request, ctx)
+    if (!fetcher) {
+      return { data: [], error: 'FetcherDispatcher: no fetcher selected and no default configured' }
+    }
+
+    const key = this._cacheKey(fetcher, request)
+
+    const cached = this._dataStore.get(key)
+    if (cached) return { data: cached.data, meta: cached.meta }
+
+    const existing = this._dataStore.inflight.get(key)
+    if (existing) {
+      this._attachSignal(existing, ctx.signal)
+      return existing.promise
+    }
+
+    const master = typeof AbortController !== 'undefined' ? new AbortController() : null
+    const inflight = {
+      promise: null,
+      master,
+      signals: new Set(),
+      everAttached: false,
+    }
+
+    this._attachSignal(inflight, ctx.signal)
+    this._dataStore.inflight.set(key, inflight)
+
+    const innerCtx = master ? { ...ctx, signal: master.signal } : ctx
+    inflight.promise = this._runFetcher(fetcher, request, innerCtx, key, inflight)
+    return inflight.promise
+  }
+
+  /**
+   * Attach a caller's AbortSignal to an in-flight entry. Aborting a signal
+   * removes it from the entry's set; when every attached signal has aborted
+   * (and at least one was ever attached), the master controller fires so the
+   * underlying fetch can bail out.
+   */
+  _attachSignal(inflight, signal) {
+    if (!signal) return
+    if (!inflight.master) return
+
+    inflight.everAttached = true
+
+    if (signal.aborted) {
+      this._maybeAbortMaster(inflight)
+      return
+    }
+
+    inflight.signals.add(signal)
+    const onAbort = () => {
+      inflight.signals.delete(signal)
+      this._maybeAbortMaster(inflight)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  }
+
+  _maybeAbortMaster(inflight) {
+    if (!inflight.master) return
+    if (inflight.master.signal.aborted) return
+    if (!inflight.everAttached) return
+    if (inflight.signals.size > 0) return
+    inflight.master.abort()
+  }
+
+  async _runFetcher(fetcher, request, ctx, key, inflight) {
+    try {
+      const result = await fetcher.resolve(request, ctx)
+
+      if (this._dataStore.inflight.get(key) === inflight) {
+        this._dataStore.inflight.delete(key)
+      }
+
+      if (!result || typeof result !== 'object') {
+        if (this._dev) {
+          console.warn(
+            '[FetcherDispatcher] Fetcher returned a non-object; expected { data, error?, meta? }.',
+            { request, result },
+          )
+        }
+        return { data: [], error: 'Fetcher returned a non-object' }
+      }
+
+      const { data, error, meta } = result
+      if (this._dev) this._validateReturnShape(result, request)
+
+      if (error) return { data: data ?? [], error, meta }
+
+      if (data === undefined || data === null) {
+        // Nothing meaningful to cache; surface as-is.
+        return { data: data ?? [], meta }
+      }
+
+      const entry = meta !== undefined ? { data, meta } : { data }
+      this._dataStore.set(key, entry)
+      return { data, meta }
+    } catch (err) {
+      if (this._dataStore.inflight.get(key) === inflight) {
+        this._dataStore.inflight.delete(key)
+      }
+      return { data: [], error: String(err?.message || err) }
+    }
+  }
+
+  /**
+   * Dev-mode: warn when the fetcher's return object has unexpected top-level
+   * keys — catches typos like { items, error } instead of { data, error }.
+   */
+  _validateReturnShape(result, request) {
+    const allowed = new Set(['data', 'error', 'meta'])
+    const unexpected = Object.keys(result).filter((k) => !allowed.has(k))
+    if (unexpected.length > 0) {
+      console.warn(
+        `[FetcherDispatcher] Fetcher return has unexpected keys: ${unexpected.join(', ')}. ` +
+          'Expected { data, error?, meta? }.',
+        { request, result },
+      )
+    }
+  }
+}

package/src/index.js

@@ -13,6 +13,14 @@ export { default as Website } from './website.js'
 export { default as Page } from './page.js'
 export { default as Block } from './block.js'
 export { default as Theme } from './theme.js'
+export { default as DataStore, deriveCacheKey } from './datastore.js'
+export { default as EntityStore } from './entity-store.js'
+export { default as FetcherDispatcher } from './fetcher-dispatcher.js'
+export { default as ObservableState } from './observable-state.js'
+
+// Utilities
+export { default as singularize } from './singularize.js'
+export { substitutePlaceholders } from './substitute-placeholders.js'
 
 /**
  * The singleton Uniweb instance.
@@ -25,13 +33,19 @@ export function getUniweb() {
 
 /**
  * Create and register the Uniweb singleton.
- * Called by @uniweb/runtime during site initialization.
  *
- * @param {Object} configData - Website configuration (pages, theme, config)
- * @returns {Uniweb} The created instance
+ * @param {Object} content - Site content payload (pages, theme, config, layouts, ...).
+ * @param {Object} [foundation] - Loaded primary foundation module.
+ * @param {Array<Object>} [extensions] - Loaded extension modules.
+ * @param {Object} [options]
+ * @param {{ resolve: Function }} [options.defaultFetcher] - Framework default fetcher.
+ * @param {{ resolve: Function, cacheKey?: Function }} [options.transport] -
+ *   Runtime-level transport override — routes every Layer-1 request through
+ *   this transport. Used only by the editor's preview iframe.
+ * @returns {Uniweb} The created instance (also assigned to globalThis.uniweb).
  */
-export function createUniweb(configData) {
-  const instance = new Uniweb(configData)
+export function createUniweb(content, foundation = null, extensions = [], { defaultFetcher = null, transport = null, dev = false } = {}) {
+  const instance = new Uniweb({ content, foundation, extensions, defaultFetcher, transport, dev })
   globalThis.uniweb = instance
   return instance
 }

package/src/observable-state.js

@@ -0,0 +1,103 @@
+/**
+ * ObservableState
+ *
+ * Small typed observable value store used by `page.state` and `website.state`.
+ * Foundations write into it (current selected query, active filter, view-mode
+ * toggle). Kit hooks subscribe and re-render React components on change. The
+ * fetcher — which runs outside React — reads it directly from `ctx.page.state`
+ * / `ctx.website.state`.
+ *
+ * Plain typed API: no Proxies, no reactive derivations, no middleware. Strict
+ * shape reduces accidental reads, makes subscriptions explicit, and avoids
+ * enumerate/ownKey surprises that come with property-access proxies.
+ *
+ * Subscribers fire on change only — `set(key, sameValue)` is a no-op.
+ *
+ * @example
+ *   page.state.get('selectedQuery')           // → any | undefined
+ *   page.state.set('selectedQuery', 'X')      // fires listeners
+ *   page.state.delete('selectedQuery')        // fires listeners if the key existed
+ *
+ *   page.state.subscribe('selectedQuery', fn) // listener for this key only
+ */
+export default class ObservableState {
+  constructor() {
+    // key → value
+    this._values = new Map()
+    // key → Set<fn> — listeners for a specific key.
+    this._keyListeners = new Map()
+
+    Object.seal(this)
+  }
+
+  /**
+   * @param {string} key
+   * @returns {any|undefined}
+   */
+  get(key) {
+    return this._values.get(key)
+  }
+
+  /**
+   * @param {string} key
+   * @returns {boolean}
+   */
+  has(key) {
+    return this._values.has(key)
+  }
+
+  /**
+   * Set a key. No-op when the value is `===` the existing value.
+   * Listeners fire only on actual changes.
+   *
+   * @param {string} key
+   * @param {any} value
+   */
+  set(key, value) {
+    if (this._values.has(key) && this._values.get(key) === value) return
+    this._values.set(key, value)
+    this._notify(key)
+  }
+
+  /**
+   * Remove a key. No-op when the key was already absent.
+   *
+   * @param {string} key
+   * @returns {boolean} true if a key was deleted
+   */
+  delete(key) {
+    if (!this._values.has(key)) return false
+    this._values.delete(key)
+    this._notify(key)
+    return true
+  }
+
+  /**
+   * Subscribe to changes for a specific key. Returns an unsubscribe function.
+   *
+   * There is no all-keys subscription form — fan-out belongs in the caller
+   * when it's really needed. Subscribing per key keeps re-render blast
+   * radius predictable and avoids "every write wakes every listener" fan-in.
+   *
+   * @param {string} key
+   * @param {Function} fn
+   * @returns {Function} unsubscribe
+   */
+  subscribe(key, fn) {
+    let bucket = this._keyListeners.get(key)
+    if (!bucket) {
+      bucket = new Set()
+      this._keyListeners.set(key, bucket)
+    }
+    bucket.add(fn)
+    return () => {
+      bucket.delete(fn)
+      if (bucket.size === 0) this._keyListeners.delete(key)
+    }
+  }
+
+  _notify(key) {
+    const bucket = this._keyListeners.get(key)
+    if (bucket) for (const fn of bucket) fn()
+  }
+}

package/src/page.js

@@ -6,6 +6,7 @@
  */
 
 import Block from './block.js'
+import ObservableState from './observable-state.js'
 
 export default class Page {
   constructor(pageData, id, website) {
@@ -92,9 +93,26 @@ export default class Page {
     // Guard against concurrent loadContent() calls
     this._loadingContent = null
 
+    // Observable state — allocated on first access via the `state` getter.
+    // Pages that never use state pay nothing; the prop is read-only (no
+    // `page.state = X` reassignment) so components can only mutate slots
+    // via the intended `page.state.set(key, value)` API.
+    this._state = null
+
     Object.seal(this)
   }
 
+  /**
+   * Observable state scoped to this page. Foundations write scoped UI / query
+   * state here; kit's usePageState bridges it into React; fetchers read it
+   * via ctx.page.state. Lazily allocated on first read — pages that never
+   * touch state never build one.
+   */
+  get state() {
+    if (!this._state) this._state = new ObservableState()
+    return this._state
+  }
+
   /**
    * Lazy getter for body blocks
    * Blocks are built on first access, ensuring foundation is loaded

package/src/substitute-placeholders.js

@@ -0,0 +1,63 @@
+/**
+ * Substitute `{name}` placeholders in strings (or throughout an object tree)
+ * using a flat context map. Used in two places:
+ *
+ *   - URL templates for detail queries: `detail: '/articles/{slug}'` gets
+ *     `slug` resolved from the dynamic-route context. Encoding ON.
+ *
+ *   - POST `body:` objects where a field carries a route-param reference:
+ *     `body: { variables: { slug: "{slug}" } }`. Encoding OFF — values go
+ *     into JSON as-is.
+ *
+ * Behavior:
+ *   - Matches `{name}` where `name` is `[A-Za-z_][A-Za-z0-9_]*`. This keeps
+ *     the substitution *strict* so literal `{` / `}` elsewhere (notably
+ *     GraphQL selection sets like `{ field }`) don't accidentally match.
+ *     A whitespace inside the braces disqualifies the match.
+ *   - Only keys actually present in `context` substitute. Unknown keys
+ *     pass through unchanged, preserving the literal `{name}`.
+ *   - Encoding uses `encodeURIComponent` when `encode: true`.
+ *   - Object/array recursion is structural; primitives other than strings
+ *     pass through. Returns a new object tree; input is not mutated.
+ */
+
+const PLACEHOLDER_RE = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/**
+ * @param {*} value - The tree (string, object, array, primitive) to walk.
+ * @param {Record<string, string|number>} context - Name → value map. Missing
+ *   keys leave the placeholder literal in place.
+ * @param {Object} [options]
+ * @param {boolean} [options.encode=true] - When true, `encodeURIComponent` the
+ *   substituted value. Turn off for JSON-body substitution where the value
+ *   will be serialized by JSON.stringify.
+ * @returns {*} New tree with substitutions applied.
+ */
+export function substitutePlaceholders(value, context, options = {}) {
+  const { encode = true } = options
+
+  if (typeof value === 'string') {
+    return value.replace(PLACEHOLDER_RE, (literal, key) => {
+      if (!(key in (context || {}))) return literal
+      const raw = context[key]
+      if (raw === undefined || raw === null) return literal
+      return encode ? encodeURIComponent(String(raw)) : String(raw)
+    })
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => substitutePlaceholders(item, context, options))
+  }
+
+  if (value && typeof value === 'object') {
+    const result = {}
+    for (const key of Object.keys(value)) {
+      result[key] = substitutePlaceholders(value[key], context, options)
+    }
+    return result
+  }
+
+  return value
+}
+
+export default substitutePlaceholders