@uniweb/core 0.6.0 → 0.6.2

package/src/entity-store.js

@@ -1,53 +1,71 @@
 /**
  * EntityStore
  *
- * Resolves entity data for components by walking the page hierarchy.
- * Leverages DataStore for caching and deduplication.
+ * Walks the block→page→parent→site cascade to find applicable fetch configs,
+ * asks the Website's FetcherDispatcher to execute them, and assembles the
+ * data payload passed to `prepare-props`.
  *
- * Two-method API:
- * - resolve(block, meta) — sync, reads cache only
- * - fetch(block, meta)   — async, fetches missing data via DataStore
+ * The cascade, localization, detail-query handling, and collection-first
+ * content-gate logic all live here — unchanged from the pre-refactor model.
+ * What changed: EntityStore no longer talks to DataStore directly. It calls
+ * `website.fetcher.peek(request, ctx)` for the sync path (resolve) and
+ * `website.fetcher.dispatch(request, ctx)` for the async path (fetch).
+ * The dispatcher owns fetcher selection, cache-key derivation, cache lookup,
+ * and in-flight dedup.
  */
 
 import singularize from './singularize.js'
+import { substitutePlaceholders } from './substitute-placeholders.js'
+
+/**
+ * Is `block.fetch` a per-instance refinement of the ancestor's fetch config
+ * rather than a new source? The canonical spelling is `refine: true`; the
+ * legacy spelling `inherit: true` is still honored for one release with a
+ * dev-mode warning.
+ */
+function isRefinement(bf) {
+  return bf?.refine === true || bf?.inherit === true
+}
+
+let inheritDeprecationWarned = false
+function warnInheritDeprecation(block) {
+  if (inheritDeprecationWarned) return
+  inheritDeprecationWarned = true
+  // Dev-only; production builds typically strip console.warn. We gate on
+  // the presence of the deprecated key and fire once per process.
+  console.warn(
+    "[uniweb] 'fetch: { inherit: true }' is deprecated; rename to 'fetch: { refine: true }'. " +
+    'Accepted for one release; will be removed in the next minor. ' +
+    `First seen on block ${block?.id ?? '(unknown)'} of page ${block?.page?.route ?? '(unknown)'}.`
+  )
+}
 
 export default class EntityStore {
   /**
    * @param {Object} options
-   * @param {import('./datastore.js').default} options.dataStore
+   * @param {import('./website.js').default} options.website
    */
-  constructor({ dataStore }) {
-    this.dataStore = dataStore
-
+  constructor({ website }) {
+    this.website = website
     Object.seal(this)
   }
 
-  /**
-   * Whether a component wants detail-URL resolution on dynamic pages.
-   * Default true. Set to false via `data: { inherit: true, detail: false }`
-   * to receive the full collection (minus the active item) instead.
-   *
-   * @param {Object} meta
-   * @returns {boolean}
-   */
   _shouldInheritDetail(meta, block) {
-    // Block-level fetch inherit override takes priority over meta
     const bf = block?.fetch
-    if (bf?.inherit === true && bf?.detail !== undefined) return bf.detail !== false
+    if (isRefinement(bf) && bf?.detail !== undefined) return bf.detail !== false
     if (!meta) return true
     return meta.inheritDetail !== false
   }
 
   _inheritLimit(meta, block) {
-    // Block-level fetch inherit override takes priority over meta
     const bf = block?.fetch
-    if (bf?.inherit === true && bf?.limit > 0) return bf.limit
+    if (isRefinement(bf) && bf?.limit > 0) return bf.limit
     return (meta?.inheritLimit > 0) ? meta.inheritLimit : null
   }
 
   _inheritOrder(block) {
     const bf = block?.fetch
-    if (bf?.inherit === true && bf?.order?.orderBy) return bf.order
+    if (isRefinement(bf) && bf?.order?.orderBy) return bf.order
     return null
   }
 
@@ -66,144 +84,125 @@ export default class EntityStore {
   }
 
   /**
-   * Determine which schemas a component requests.
+   * Which schemas does this component want delivered?
    *
-   * @param {Object} meta - Component runtime metadata
-   * @returns {string[]|null} Array of schema names, or null if none requested
+   * - meta missing → default-on: collect all available schemas.
+   * - meta.inheritData === false → opt out entirely.
+   * - Anything else → collect all (legacy inheritData arrays collapse here).
    */
   _getRequestedSchemas(meta) {
-    if (!meta) return null
-
-    const inheritData = meta.inheritData
-    if (!inheritData) return null
-
-    // inheritData: true → inherit all (resolved from fetch configs)
-    // inheritData: ['articles'] → specific schemas
-    if (Array.isArray(inheritData)) return inheritData.length > 0 ? inheritData : null
-    if (inheritData === true) return [] // empty = "all available"
-
-    return null
+    if (!meta) return []
+    if (meta.inheritData === false) return null
+    return []
   }
 
   /**
    * Return a localized copy of a fetch config for collection data.
-   * For non-default locales, prepends /{locale} to /data/ paths so the
-   * client fetches the translated JSON (e.g. /fr/data/articles.json).
-   *
-   * @param {Object} cfg - Fetch config
-   * @param {import('./website.js').default|null} website
-   * @returns {Object} Localized config (or original if no change needed)
+   * Non-default locales get /{locale} prefixed onto /data/ paths so the
+   * client fetches the translated JSON (/fr/data/articles.json).
    */
   _localizeConfig(cfg, website) {
     if (!cfg.path || !website) return cfg
-
-    const locale = website.getActiveLocale()
-    const defaultLocale = website.getDefaultLocale()
+    const locale = website.getActiveLocale?.()
+    const defaultLocale = website.getDefaultLocale?.()
     if (!locale || locale === defaultLocale) return cfg
-
     if (!cfg.path.startsWith('/data/')) return cfg
-
     return { ...cfg, path: `/${locale}${cfg.path}` }
   }
 
   /**
-   * Walk the hierarchy to find fetch configs for requested schemas.
-   * Order: block.fetch → page.fetch → parent.fetch → site config.fetch
-   * First match per schema wins. Only walks one parent level (auto-wiring).
-   *
-   * @param {import('./block.js').default} block
-   * @param {string[]} requested - Schema names (empty = collect all)
-   * @returns {Map<string, Object>} schema → fetch config
+   * Walk the four-level hierarchy and collect fetch configs for the
+   * requested schemas. First match per schema wins.
    */
   _findFetchConfigs(block, requested) {
     const configs = new Map()
     const collectAll = requested.length === 0
-
     const sources = []
 
-    // 1. Block-level fetch (skip inherit-merge configs — they have no URL, only override props)
-    if (block.fetch && !block.fetch.inherit) {
-      sources.push(block.fetch)
+    if (block.fetch?.inherit === true && block.fetch?.refine !== true) {
+      warnInheritDeprecation(block)
     }
-
-    // 2. Page-level fetch
+    if (block.fetch && !isRefinement(block.fetch)) sources.push(block.fetch)
     const page = block.page
-    if (page?.fetch) {
-      sources.push(page.fetch)
-    }
-
-    // 3. Parent page fetch (one level — auto-wiring for dynamic routes)
-    if (page?.parent?.fetch) {
-      sources.push(page.parent.fetch)
-    }
-
-    // 4. Site-level fetch
+    if (page?.fetch) sources.push(page.fetch)
+    if (page?.parent?.fetch) sources.push(page.parent.fetch)
     const siteFetch = block.website?.config?.fetch
-    if (siteFetch) {
-      sources.push(siteFetch)
-    }
+    if (siteFetch) sources.push(siteFetch)
 
     const website = block.website
 
     for (const source of sources) {
-      // Normalize: single config or array of configs
       const configList = Array.isArray(source) ? source : [source]
-
       for (const cfg of configList) {
         if (!cfg.schema) continue
-        if (configs.has(cfg.schema)) continue // first match wins
-
+        if (configs.has(cfg.schema)) continue
         if (collectAll || requested.includes(cfg.schema)) {
           configs.set(cfg.schema, this._localizeConfig(cfg, website))
         }
       }
     }
-
     return configs
   }
 
   /**
-   * Build a fetch config for a single entity using the detail convention.
+   * Build a detail-URL fetch config from a collection config + dynamic context.
    *
-   * @param {Object} collectionConfig - The collection's fetch config (must have `detail`)
-   * @param {Object} dynamicContext - { paramName, paramValue, schema }
-   * @returns {Object|null} A fetch config for the single entity, or null
+   * Three forms of `detail:`:
+   *   - `'rest'`                — append paramValue as a path segment.
+   *   - `'query'`               — append `?paramName=paramValue`.
+   *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders.
+   *   - `{ body, envelope }`    — object form. Reuses the collection's url /
+   *                               method / headers / auth; adds per-detail
+   *                               body (with placeholder substitution) and
+   *                               per-detail envelope.
    */
   _buildDetailConfig(collectionConfig, dynamicContext) {
     const { detail } = collectionConfig
     if (!detail) return null
-
     const { paramName, paramValue } = dynamicContext
     if (!paramName || paramValue === undefined) return null
 
     const baseUrl = collectionConfig.url || collectionConfig.path
     if (!baseUrl) return null
+    const isLocalPath = !!collectionConfig.path && !collectionConfig.url
 
-    let detailUrl
+    // Object form: `detail: { body, envelope }`. Reuses collection's URL +
+    // method + headers + auth. The body is placeholder-substituted against
+    // the dynamic context so `body: { variables: { slug: "{slug}" } }` works.
+    if (detail && typeof detail === 'object') {
+      const out = {
+        ...(isLocalPath ? { path: baseUrl } : { url: baseUrl }),
+        schema: singularize(collectionConfig.schema) || collectionConfig.schema,
+        transform: collectionConfig.transform,
+      }
+      if (collectionConfig.method) out.method = collectionConfig.method
+      if (detail.body !== undefined) {
+        out.body = substitutePlaceholders(detail.body, { [paramName]: paramValue }, { encode: false })
+      } else if (collectionConfig.body !== undefined) {
+        out.body = substitutePlaceholders(collectionConfig.body, { [paramName]: paramValue }, { encode: false })
+      }
+      if (detail.envelope) out.envelope = detail.envelope
+      return out
+    }
 
+    // String-form: URL-based conventions.
+    let detailUrl
     if (detail === 'rest') {
-      // REST convention: {baseUrl}/{paramValue}
-      // Preserve query string (auth params like token, profileLang) — only insert
-      // the param value before the '?', not after.
       const [basePath, queryString] = baseUrl.split('?')
       const cleanBase = basePath.replace(/\/$/, '')
       detailUrl = queryString
         ? `${cleanBase}/${encodeURIComponent(paramValue)}?${queryString}`
         : `${cleanBase}/${encodeURIComponent(paramValue)}`
     } else if (detail === 'query') {
-      // Query param convention: {baseUrl}?{paramName}={paramValue}
       const sep = baseUrl.includes('?') ? '&' : '?'
       detailUrl = `${baseUrl}${sep}${paramName}=${encodeURIComponent(paramValue)}`
     } else {
-      // Custom pattern: replace {paramName} placeholders
-      detailUrl = detail.replace(/\{(\w+)\}/g, (_, key) => {
-        if (key === paramName) return encodeURIComponent(paramValue)
-        return `{${key}}` // leave unknown placeholders
-      })
+      // Custom pattern like '/articles/{slug}' — substitute placeholders
+      // from the dynamic-route context. Only placeholders matching the
+      // active paramName resolve; others pass through as literal `{name}`.
+      detailUrl = substitutePlaceholders(detail, { [paramName]: paramValue })
     }
 
-    // Build a fetch config for the single item
-    const isLocalPath = !!collectionConfig.path && !collectionConfig.url
     return {
       ...(isLocalPath ? { path: detailUrl } : { url: detailUrl }),
       schema: singularize(collectionConfig.schema) || collectionConfig.schema,
@@ -212,19 +211,13 @@ export default class EntityStore {
   }
 
   /**
-   * Resolve singular item for dynamic routes.
-   * If block/page has dynamicContext, find the matching item in the collection.
-   *
-   * @param {Object} data - Resolved entity data { schema: items[] }
-   * @param {Object|null} dynamicContext
-   * @returns {Object} data with singular key added if applicable
+   * For dynamic routes: extract the matching item from a collection and
+   * expose it under the singular schema key (articles → article).
    */
   _resolveSingularItem(data, dynamicContext) {
     if (!dynamicContext) return data
-
     const { paramName, paramValue, schema: pluralSchema } = dynamicContext
     if (!pluralSchema || !paramName || paramValue === undefined) return data
-
     const items = data[pluralSchema]
     if (!Array.isArray(items)) return data
 
@@ -232,63 +225,66 @@ export default class EntityStore {
     const currentItem = items.find(
       (item) => String(item[paramName]) === String(paramValue)
     )
-
     if (currentItem && singularSchema) {
       return { ...data, [singularSchema]: currentItem }
     }
-
     return data
   }
 
   /**
-   * Sync resolution. Checks DataStore cache for fetch configs found in hierarchy.
+   * Build the `ctx` handed to the dispatcher for a given block.
+   * @private
+   */
+  _ctx(block, extra = {}) {
+    return {
+      website: this.website,
+      page: block?.page || null,
+      block: block || null,
+      signal: extra.signal,
+    }
+  }
+
+  /**
+   * Sync resolution — probes the cache via `fetcher.peek`. Returns
+   * `ready` only when every relevant entry is cached, otherwise `pending`
+   * (caller falls through to `fetch()` to populate and await).
    *
-   * @param {import('./block.js').default} block
-   * @param {Object} meta - Component runtime metadata
    * @returns {{ status: 'ready'|'pending'|'none', data: Object|null }}
    */
   resolve(block, meta) {
+    const dispatcher = this.website?.fetcher
     let requested = this._getRequestedSchemas(meta)
 
-    // If the component doesn't declare inheritData but the block itself
-    // has a fetch config (e.g. data_source_info converted to fetch),
-    // use the block's schema directly. Block-level fetch is an explicit
-    // data assignment, not inheritance.
+    // If the component hasn't declared data inheritance but the block itself
+    // has a fetch config, target the block's schema explicitly rather than
+    // collecting all cascade matches.
     if (requested === null && block.fetch) {
       const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
-      const schemas = blockFetchList
-        .filter((cfg) => cfg.schema)
-        .map((cfg) => cfg.schema)
-      if (schemas.length > 0) {
-        requested = schemas
-      }
+      const schemas = blockFetchList.filter((cfg) => cfg.schema).map((cfg) => cfg.schema)
+      if (schemas.length > 0) requested = schemas
     }
 
-    if (requested === null) {
-      return { status: 'none', data: null }
-    }
+    if (requested === null) return { status: 'none', data: null }
 
-    // Walk hierarchy for fetch configs
     const configs = this._findFetchConfigs(block, requested)
+    if (configs.size === 0) return { status: 'none', data: null }
 
-    if (configs.size === 0) {
-      return { status: 'none', data: null }
-    }
-
-    // Check DataStore cache for each config
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const inheritDetail = this._shouldInheritDetail(meta, block)
     const limit = this._inheritLimit(meta, block)
     const order = this._inheritOrder(block)
+    const ctx = this._ctx(block)
+
     const data = {}
     let allCached = true
 
     for (const [schema, cfg] of configs) {
       if (dynamicContext && cfg.detail && !inheritDetail) {
-        // detail: false — return collection minus the active item (sidebar/related use case)
-        if (this.dataStore.has(cfg)) {
+        // detail: false — return collection minus the active item.
+        const cached = dispatcher?.peek(cfg, ctx)
+        if (cached) {
           const { paramName, paramValue } = dynamicContext
-          const items = this.dataStore.get(cfg)
+          const items = cached.data
           let filtered = Array.isArray(items)
             ? items.filter((item) => String(item[paramName]) !== String(paramValue))
             : items
@@ -298,11 +294,10 @@ export default class EntityStore {
           allCached = false
         }
       } else if (dynamicContext && cfg.detail) {
-        // Collection-first detail resolution:
-        // The collection acts as the access gate — the item must exist in the
-        // cached collection before we'll serve (or fetch) its detail data.
-        if (this.dataStore.has(cfg)) {
-          const collectionItems = this.dataStore.get(cfg)
+        // Collection-first detail: the collection is the content gate.
+        const cachedCollection = dispatcher?.peek(cfg, ctx)
+        if (cachedCollection) {
+          const collectionItems = cachedCollection.data
           const { paramName, paramValue } = dynamicContext
           const singularKey = singularize(schema) || schema
           const match = Array.isArray(collectionItems)
@@ -310,27 +305,29 @@ export default class EntityStore {
             : null
 
           if (!match) {
-            // Item not in collection — definitive "not found" (content gate).
             data[singularKey] = null
           } else {
-            // Item is valid. Check if the detail result is already cached.
             const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
-            if (detailCfg && this.dataStore.has(detailCfg)) {
-              data[singularKey] = this.dataStore.get(detailCfg)
+            const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
+            if (detailCfg && detailCached) {
+              data[singularKey] = detailCached.data
             } else if (detailCfg) {
-              allCached = false // Collection cached, item valid, detail still needed
+              allCached = false
             } else {
-              data[singularKey] = match // No detail URL — use collection item directly
+              data[singularKey] = match
             }
           }
         } else {
-          allCached = false // Collection not yet cached — must fetch it first
+          allCached = false
         }
-      } else if (this.dataStore.has(cfg)) {
-        const items = this.dataStore.get(cfg)
-        data[schema] = order ? this._sortItems(items, order) : items
       } else {
-        allCached = false
+        const cached = dispatcher?.peek(cfg, ctx)
+        if (cached) {
+          const items = cached.data
+          data[schema] = order ? this._sortItems(items, order) : items
+        } else {
+          allCached = false
+        }
       }
     }
 
@@ -338,57 +335,48 @@ export default class EntityStore {
       const resolved = this._resolveSingularItem(data, dynamicContext)
       return { status: 'ready', data: resolved }
     }
-
     return { status: 'pending', data: null }
   }
 
   /**
-   * Async fetch. Walks hierarchy, fetches missing data via DataStore.
+   * Async fetch — dispatches missing configs through the FetcherDispatcher
+   * and assembles the result. Collection-first detail ordering preserved.
    *
-   * @param {import('./block.js').default} block
-   * @param {Object} meta - Component runtime metadata
+   * @param {Object} [options]
+   * @param {AbortSignal} [options.signal] - Forwarded to the dispatcher.
    * @returns {Promise<{ data: Object|null }>}
    */
-  async fetch(block, meta) {
-    let requested = this._getRequestedSchemas(meta)
+  async fetch(block, meta, { signal } = {}) {
+    const dispatcher = this.website?.fetcher
+    if (!dispatcher) return { data: null }
 
-    // Same block-level fetch fallback as resolve()
+    let requested = this._getRequestedSchemas(meta)
     if (requested === null && block.fetch) {
       const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
-      const schemas = blockFetchList
-        .filter((cfg) => cfg.schema)
-        .map((cfg) => cfg.schema)
-      if (schemas.length > 0) {
-        requested = schemas
-      }
-    }
-
-    if (requested === null) {
-      return { data: null }
+      const schemas = blockFetchList.filter((cfg) => cfg.schema).map((cfg) => cfg.schema)
+      if (schemas.length > 0) requested = schemas
     }
+    if (requested === null) return { data: null }
 
     const configs = this._findFetchConfigs(block, requested)
-    if (configs.size === 0) {
-      return { data: null }
-    }
+    if (configs.size === 0) return { data: null }
 
-    // Fetch all missing configs
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const inheritDetail = this._shouldInheritDetail(meta, block)
     const limit = this._inheritLimit(meta, block)
     const order = this._inheritOrder(block)
+    const ctx = this._ctx(block, { signal })
 
     const data = {}
     const parallelFetches = []
 
     for (const [schema, cfg] of configs) {
       if (dynamicContext && cfg.detail && !inheritDetail) {
-        // detail: false — fetch collection and return it minus the active item
-        // (sidebar / related-posts use case on a dynamic page)
-        let collectionItems = this.dataStore.has(cfg) ? this.dataStore.get(cfg) : null
+        // detail: false — collection-only, minus the active item.
+        let collectionItems = peekArray(dispatcher, cfg, ctx)
         if (collectionItems === null) {
-          const result = await this.dataStore.fetch(cfg)
-          collectionItems = Array.isArray(result.data) ? result.data : null
+          const result = await dispatcher.dispatch(cfg, ctx)
+          collectionItems = Array.isArray(result?.data) ? result.data : null
         }
         const { paramName, paramValue } = dynamicContext
         let filtered = Array.isArray(collectionItems)
@@ -397,48 +385,41 @@ export default class EntityStore {
         if (order) filtered = this._sortItems(filtered, order)
         data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
       } else if (dynamicContext && cfg.detail) {
-        // Collection-first detail resolution:
-        // 1. Ensure the collection is in DataStore (fetching if needed).
-        // 2. Validate that paramValue exists in the collection (content gate).
-        // 3. Only then fetch the detail URL for richer item data.
+        // Collection-first detail resolution.
         const { paramName, paramValue } = dynamicContext
         const singularKey = singularize(schema) || schema
 
-        // Step 1: ensure collection is cached (sequential — needed for validation)
-        let collectionItems = this.dataStore.has(cfg) ? this.dataStore.get(cfg) : null
+        let collectionItems = peekArray(dispatcher, cfg, ctx)
         if (collectionItems === null) {
-          const result = await this.dataStore.fetch(cfg)
-          collectionItems = Array.isArray(result.data) ? result.data : null
+          const result = await dispatcher.dispatch(cfg, ctx)
+          collectionItems = Array.isArray(result?.data) ? result.data : null
         }
 
-        // Step 2: validate paramValue is in the collection (content gate)
         const match = collectionItems?.find(
           (item) => String(item[paramName]) === String(paramValue)
         ) ?? null
 
         if (!match) {
-          data[singularKey] = null // Not in collection — content gate
+          data[singularKey] = null
           continue
         }
 
-        // Step 3: fetch detail URL for richer data; fall back to collection item
         const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
         if (detailCfg) {
           parallelFetches.push(
-            this.dataStore.fetch(detailCfg).then((result) => {
-              data[singularKey] = (result.data !== undefined && result.data !== null)
+            dispatcher.dispatch(detailCfg, ctx).then((result) => {
+              data[singularKey] = (result?.data !== undefined && result?.data !== null)
                 ? result.data
-                : match // fallback: collection item is still valid
+                : match
             })
           )
         } else {
-          data[singularKey] = match // No detail URL — collection item is enough
+          data[singularKey] = match
         }
       } else {
-        // Default: fetch the full collection
         parallelFetches.push(
-          this.dataStore.fetch(cfg).then((result) => {
-            if (result.data !== undefined && result.data !== null) {
+          dispatcher.dispatch(cfg, ctx).then((result) => {
+            if (result?.data !== undefined && result?.data !== null) {
               data[schema] = result.data
             }
           })
@@ -446,10 +427,17 @@ export default class EntityStore {
       }
     }
 
-    if (parallelFetches.length > 0) {
-      await Promise.all(parallelFetches)
-    }
+    if (parallelFetches.length > 0) await Promise.all(parallelFetches)
     const resolved = this._resolveSingularItem(data, dynamicContext)
     return { data: resolved }
   }
 }
+
+/**
+ * Sync-peek helper: return the cached array for a config, or null on miss.
+ */
+function peekArray(dispatcher, cfg, ctx) {
+  const cached = dispatcher.peek(cfg, ctx)
+  if (!cached) return null
+  return Array.isArray(cached.data) ? cached.data : null
+}