@uniweb/core 0.12.1 → 0.13.1

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniweb/core",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./base-path": "./src/base-path.js",
+    "./collection-address": "./src/collection-address.js",
     "./data-paths": "./src/data-paths.js",
     "./detail-url": "./src/detail-url.js",
     "./fetch-config": "./src/fetch-config.js",

package/src/collection-address.js

@@ -0,0 +1,143 @@
+/**
+ * Resolve a collection request to an address the fetcher can call.
+ *
+ * ## The one idea
+ *
+ * A site names a collection; it never names where the collection lives. Where
+ * it lives is a **deployment** fact, and the two possible answers have different
+ * owners:
+ *
+ *   1. **A host that serves records live** declares a pair of URL *patterns*
+ *      at `config.records`. It owns every segment of them.
+ *   2. **Nobody** — and the answer is the artifact the build itself emitted,
+ *      `/data/<name>.json`, which is not an address at all but a path in the
+ *      site's own URL space.
+ *
+ * Absence of (1) is therefore not an error and not a decline: it falls THROUGH
+ * to (2). That is what makes a site with no backend the default rather than a
+ * special case, and it is why this does not go through `resolveService` — a
+ * service's absence means the site has no such feature and the caller draws
+ * nothing, which is right for `submit` and wrong here, where the fallback is a
+ * file the build knows it wrote.
+ *
+ * ## ⛔ Patterns, not a base — and the reason is a deleted function
+ *
+ * A base assumes the layout is "root plus one segment". A pattern assumes
+ * nothing, so a host can carry a site id, a locale segment, a different root
+ * for records than for the collection, or none of those, and move any of it
+ * without a framework release.
+ *
+ * This is the `config.assets.url` rule applied to records. That pattern exists
+ * because the CLI once composed `{assetBase}dist/{id}/base.{ext}` — a backend's
+ * path layout, inside a published CLI, on a release cadence the backend could
+ * not move. It was deleted rather than parameterized. Composing a segment of
+ * our own here would rebuild exactly that coupling, on a lane where the wrong
+ * answer is *stale or missing content* rather than a visible 404.
+ *
+ * ⇒ Substituting `{path}` and `{param}` is the WHOLE of what this does.
+ *
+ * Zero-dependency beyond two sibling leaves, so the SSR pipeline and a Worker
+ * isolate can both import it.
+ */
+
+import { substitutePlaceholders } from './substitute-placeholders.js'
+
+/**
+ * The placeholder a list pattern must carry.
+ *
+ * ⛔ IT IS `{path}`, NOT `{collection}`, AND THAT IS NOT COSMETIC. A *collection* is
+ * framework's own build concept — a named set our build compiles to one file. A host
+ * serving records has no such thing: it has content organised somewhere, and what we
+ * substitute is a **path** to it. Naming the slot for our file vocabulary put that
+ * vocabulary into a string a HOST writes, which makes them reason in our shape.
+ * See `kb/framework/architecture/backend-boundary.md` §2.
+ */
+const PATH_SLOT = '{path}'
+/** The placeholder a record pattern must carry to address a specific record. */
+const PARAM_SLOT = '{param}'
+
+const warnedPatterns = new Set()
+
+function warnOnce(key, message) {
+  if (warnedPatterns.has(key)) return
+  warnedPatterns.add(key)
+  console.warn(`[collection-address] ${message}`)
+}
+
+/** Test seam — reset the once-per-pattern memo so suites do not leak. */
+export function _resetCollectionAddressWarnings() {
+  warnedPatterns.clear()
+}
+
+/**
+ * Is this a usable lane declaration?
+ *
+ * A declaration present with no pattern is a host saying "not for this site" —
+ * indistinguishable, for a caller, from no declaration at all. Both fall
+ * through to the artifact.
+ */
+function readPattern(lane, key) {
+  if (!lane || typeof lane !== 'object' || Array.isArray(lane)) return null
+  const pattern = lane[key]
+  return typeof pattern === 'string' && pattern.length > 0 ? pattern : null
+}
+
+/**
+ * The address for a whole collection, or `null` to fall through to the artifact.
+ *
+ * ⚠️ A pattern that does not carry `{path}` is REFUSED rather than used.
+ * Substituting nothing would yield one identical URL for every collection on the
+ * site — every schema reading the same records, with a 200 on each request. That
+ * is the failure this check exists for; an unusable pattern must degrade to the
+ * artifact, which is at least correct.
+ *
+ * @param {string} collection - the collection's authored name (the wiring key).
+ * @param {Object|null} lane - `config.records`.
+ * @returns {string|null} the address, or null when nothing usable is declared.
+ */
+export function resolveCollectionAddress(collection, lane) {
+  if (typeof collection !== 'string' || collection.length === 0) return null
+  const pattern = readPattern(lane, 'list')
+  if (!pattern) return null
+  if (!pattern.includes(PATH_SLOT)) {
+    warnOnce(
+      `list:${pattern}`,
+      `config.records.list carries no ${PATH_SLOT} placeholder, so every ` +
+        `collection would resolve to the same address. Ignoring it and reading the ` +
+        `compiled collection file instead.`
+    )
+    return null
+  }
+  return substitutePlaceholders(pattern, { path: collection })
+}
+
+/**
+ * The address pattern for ONE record of a collection, with `{param}` left in
+ * place for the dynamic-route substitution that happens later.
+ *
+ * Returning a pattern rather than a finished URL is deliberate: the route param
+ * is not known here, and the framework already has one place that resolves it
+ * (`buildDetailConfig` / `substitutePlaceholders` at fetch time). Resolving it
+ * twice, in two places, is how the two copies drift.
+ *
+ * @param {string} collection
+ * @param {Object|null} lane - `config.records`.
+ * @returns {string|null} a pattern still containing `{param}`, or null.
+ */
+export function resolveRecordAddressPattern(collection, lane) {
+  if (typeof collection !== 'string' || collection.length === 0) return null
+  const pattern = readPattern(lane, 'record')
+  if (!pattern) return null
+  if (!pattern.includes(PARAM_SLOT)) {
+    warnOnce(
+      `record:${pattern}`,
+      `config.records.record carries no ${PARAM_SLOT} placeholder, so every record ` +
+        `would resolve to the same address. Ignoring it and reading the per-record ` +
+        `file instead.`
+    )
+    return null
+  }
+  // Only `{path}` is substituted here — `{param}` survives for the
+  // dynamic-route resolution that owns it.
+  return substitutePlaceholders(pattern, { path: collection })
+}

package/src/datastore.js

@@ -35,12 +35,12 @@
  * @returns {string} A stable JSON string usable as a cache-Map key
  */
 export function deriveCacheKey(request) {
-  const { path, url, schema, transform } = request || {}
+  const { path, url, endpoint, 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 })
+  return JSON.stringify({ path, url, endpoint, schema, transform, method, body })
 }
 
 export default class DataStore {

package/src/detail-url.js

@@ -24,13 +24,36 @@
 
 import { substitutePlaceholders } from './substitute-placeholders.js'
 
+/**
+ * The substitution context for a detail pattern: the route's own param name,
+ * plus a generic `param` alias bound to the same value.
+ *
+ * ⭐ Why the alias exists. An AUTHOR writing a detail pattern knows their route
+ * and writes `{slug}` or `{id}` — that convention is unchanged and must stay,
+ * because it is what every existing site and the auto-injected per-record
+ * pattern use. A HOST declaring a record address cannot know it: `param_name`
+ * is the site's routing choice, and the host is publishing one pattern for
+ * every site it serves. So the host writes `{param}`.
+ *
+ * Binding both names to one value is what lets the two conventions coexist
+ * without a translation step between them — and a translation step is exactly
+ * where the framework has twice grown a second copy of a rule that then drifted
+ * (`route-match`, `data-paths`). `substitutePlaceholders` only resolves keys
+ * present in the context, so an unrelated `{name}` still passes through
+ * literally, as it always has.
+ */
+function paramContext(paramName, paramValue) {
+  return { [paramName]: paramValue, param: paramValue }
+}
+
 /**
  * Build a detail-URL fetch config from a collection config + dynamic context.
  *
  * Four forms of `detail:`:
  *   - `'rest'`                — append paramValue as a path segment.
  *   - `'query'`               — append `?paramName=paramValue`.
- *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders.
+ *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders,
+ *                               or the generic `{param}` alias (see below).
  *   - `{ body, envelope }`    — object form. Reuses the collection's url /
  *                               method / headers / auth; adds per-detail
  *                               body (with placeholder substitution) and
@@ -53,30 +76,56 @@ export function buildDetailConfig(collectionConfig, dynamicContext) {
   const { paramName, paramValue } = dynamicContext
   if (!paramName || paramValue === undefined) return null
 
-  const baseUrl = collectionConfig.url || collectionConfig.path
+  // Three address kinds now, and the detail request must come back as the SAME
+  // kind: an `endpoint` carries remote semantics the fetcher decides on, so
+  // returning a detail as `path` would silently drop operator pushdown and the
+  // site's static headers for exactly the request that is one record.
+  const baseUrl = collectionConfig.endpoint || collectionConfig.url || collectionConfig.path
   if (!baseUrl) return null
-  const isLocalPath = !!collectionConfig.path && !collectionConfig.url
+  const addressKey = collectionConfig.endpoint
+    ? 'endpoint'
+    : collectionConfig.url
+      ? 'url'
+      : 'path'
 
   // 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 }),
+      [addressKey]: baseUrl,
       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 })
+      out.body = substitutePlaceholders(detail.body, paramContext(paramName, paramValue), { encode: false })
     } else if (collectionConfig.body !== undefined) {
-      out.body = substitutePlaceholders(collectionConfig.body, { [paramName]: paramValue }, { encode: false })
+      out.body = substitutePlaceholders(collectionConfig.body, paramContext(paramName, paramValue), { encode: false })
     }
     if (detail.envelope) out.envelope = detail.envelope
     return out
   }
 
   // String-form: URL-based conventions.
+  //
+  // ⭐ `rest` and `query` BUILD FROM THE LIST URL, so its query string survives onto
+  // the detail request. That is deliberate and it is the safe default: the params
+  // that matter most to a single-record read are exactly the ones a list carries —
+  // `?lang=`, an API key, a tenancy id. Dropping them would 401 the detail request
+  // or return the wrong language, on every detail page.
+  //
+  // ⚠️ The cost is real and lands on ONE category: a PROJECTION param (`?fields=`,
+  // `?select=`) asks the API for a summary, and carrying it truncates the very
+  // record the detail fetch exists to get in full. The request still succeeds and
+  // only some fields are missing, so it reads as a component or API fault rather
+  // than a URL one.
+  //
+  // ⛔ Framework cannot tell the categories apart — they are the host's vocabulary,
+  // not ours. So the default keeps everything and the CUSTOM PATTERN form is the
+  // way out: it is used verbatim, so nothing carries over unless the author writes
+  // it. Documented for authors in `docs/reference/dynamic-routes.md` § *The list's
+  // query string carries over*.
   let detailUrl
   if (detail === 'rest') {
     const [basePath, queryString] = baseUrl.split('?')
@@ -91,11 +140,11 @@ export function buildDetailConfig(collectionConfig, dynamicContext) {
     // 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 })
+    detailUrl = substitutePlaceholders(detail, paramContext(paramName, paramValue))
   }
 
   return {
-    ...(isLocalPath ? { path: detailUrl } : { url: detailUrl }),
+    [addressKey]: detailUrl,
     schema: collectionConfig.schema,
     transform: collectionConfig.transform,
   }

package/src/entity-store.js

@@ -128,6 +128,10 @@ export default class EntityStore {
         locale: website?.getActiveLocale?.() ?? null,
         defaultLocale: website?.getDefaultLocale?.() ?? null,
         collections: website?.config?.collections ?? null,
+        // A host's live-collection lane. Absent on every static site and on
+        // local dev, which is why `resolveCollectionSource` treats absence as
+        // the ordinary case and reads the compiled artifact without comment.
+        records: website?.config?.records ?? null,
       },
     )
   }

package/src/fetch-config.js

@@ -27,7 +27,8 @@
  * `resolveFetchConfigs`. That difference is real and stays with the caller.
  */
 
-import { isDataUrl, recordDataUrl } from './data-paths.js'
+import { collectionDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
+import { resolveCollectionAddress, resolveRecordAddressPattern } from './collection-address.js'
 
 /**
  * Is this fetch declaration a per-instance *refinement* of an ancestor's
@@ -95,8 +96,23 @@ function localizeConfig(cfg, locale, defaultLocale) {
  * @param {Object|null} collections - the site's `config.collections` map
  * @returns {Object} the original config, or a copy carrying `detail`
  */
-function applyDeferredDetail(cfg, collections) {
+function applyDeferredDetail(cfg, collections, records) {
   if (cfg.detail !== undefined) return cfg
+
+  // ⭐ A lane's record address is injected whenever the lane declares one —
+  // NOT only for a `deferred:` collection, and the difference is load-bearing.
+  //
+  // A live lane answers a list request at brief depth and a record request in
+  // full, so a detail page that filtered the list would render the brief and
+  // silently miss the body. And it cannot fall back to the rule below: the
+  // `deferred:` declaration lives in `config.collections`, which a host's
+  // projection is not obliged to carry — so on such a host that rule can never
+  // fire, and this is the only way a detail page reaches a whole record.
+  if (cfg.endpoint) {
+    const recordPattern = resolveRecordAddressPattern(cfg.collection ?? cfg.schema, records)
+    if (recordPattern) return { ...cfg, detail: recordPattern }
+  }
+
   const schema = cfg.schema
   if (!schema || !collections) return cfg
   const collConfig = collections[schema]
@@ -109,6 +125,40 @@ function applyDeferredDetail(cfg, collections) {
   return { ...cfg, detail: pattern }
 }
 
+/**
+ * Resolve a `collection:` reference to something the fetcher can call.
+ *
+ * The author names a collection; this decides where that collection lives, and
+ * there are exactly two answers:
+ *
+ *   - a host declared a live lane (`config.records`) → an `endpoint`, final on
+ *     arrival, which the fetcher calls without composing anything further;
+ *   - nobody did → the `path` of the artifact the build emitted.
+ *
+ * ⭐ The second is not a fallback in the apologetic sense. It is the answer for
+ * every site with no backend, which is the framework's default rather than a
+ * degraded mode — so an absent lane is silent, not warned.
+ *
+ * ⭐ `collection` OUTRANKS a `path` sitting beside it, which matters because the
+ * sync producer emits both during the transition — `collection` for a consumer
+ * that resolves it, `path` for one that has not been taught to yet. Resolving
+ * whenever `collection` is present is also what the build-time parser has always
+ * done (`parseFetchConfig` returns early on `collection`, ignoring any `path`),
+ * so the two agree rather than disagreeing on a shape nobody hand-writes.
+ */
+function resolveCollectionSource(cfg, records) {
+  if (typeof cfg.collection !== 'string' || cfg.collection.length === 0) return cfg
+
+  const endpoint = resolveCollectionAddress(cfg.collection, records)
+  if (endpoint) {
+    // Drop the transitional `path`: two addresses on one request is an
+    // ambiguity the fetcher would have to break by accident of field order.
+    const { path, url, ...rest } = cfg
+    return { ...rest, endpoint }
+  }
+  return { ...cfg, path: collectionDataUrl(cfg.collection) }
+}
+
 /**
  * Resolve the applicable fetch configs from an ordered list of sources.
  *
@@ -130,6 +180,9 @@ function applyDeferredDetail(cfg, collections) {
  * @param {string|null} [options.locale] - the locale being rendered
  * @param {string|null} [options.defaultLocale] - the site's default locale
  * @param {Object|null} [options.collections] - the site's `config.collections`
+ * @param {Object|null} [options.records] - the site's `config.records`, a host's
+ *   live-collection lane. Absent means the compiled artifact answers, which is
+ *   the whole of what a site with no backend needs.
  * @returns {Map<string, Object>} schema name → resolved config
  */
 export function resolveFetchConfigs(sources, options = {}) {
@@ -138,6 +191,7 @@ export function resolveFetchConfigs(sources, options = {}) {
     locale = null,
     defaultLocale = null,
     collections = null,
+    records = null,
   } = options
 
   const configs = new Map()
@@ -150,8 +204,11 @@ export function resolveFetchConfigs(sources, options = {}) {
       if (!cfg?.schema) continue
       if (configs.has(cfg.schema)) continue
       if (!collectAll && !schemas.includes(cfg.schema)) continue
-      const localized = localizeConfig(cfg, locale, defaultLocale)
-      configs.set(cfg.schema, applyDeferredDetail(localized, collections))
+      // Address first: localization and deferred-detail both key on `path`,
+      // which a `collection:` ref does not have until this runs.
+      const sourced = resolveCollectionSource(cfg, records)
+      const localized = localizeConfig(sourced, locale, defaultLocale)
+      configs.set(cfg.schema, applyDeferredDetail(localized, collections, records))
     }
   }
 

package/src/index.js

@@ -20,6 +20,12 @@ export { default as ObservableState } from './observable-state.js'
 
 // Utilities
 export { substitutePlaceholders } from './substitute-placeholders.js'
+export {
+  resolveCollectionAddress,
+  resolveRecordAddressPattern,
+} from './collection-address.js'
+export { resolveFetchConfigs } from './fetch-config.js'
+export { buildDetailConfig } from './detail-url.js'
 export {
   normalizeLanguageList,
   isWildcardLanguages,

package/src/request-styles/strapi.js

@@ -33,9 +33,26 @@
  * via `envelope:` at the site or per-fetch level.
  *
  * Operators mapped (where-object → Strapi `$op`):
- *   eq, ne, gt, gte, lt, lte, in, nin → notIn, like → containsi,
+ *   eq, ne, gt, gte, lt, lte, in, nin → notIn,
  *   exists → notNull, and → $and, or → $or, not → $not.
  *
+ * ⛔ `like` is deliberately NOT mapped, and the mapping it used to have was a
+ * correctness bug rather than an approximation. Our `like` is an ANCHORED glob
+ * (`^…$`, `*` = any run, `?` = one char); `$containsi` is an UNANCHORED
+ * substring test with no wildcard syntax. The two disagree in both directions
+ * and the pattern was forwarded verbatim, asterisks included:
+ *
+ *   like: 'Dr. *'  → filters[name][$containsi]=Dr. *   asks for the LITERAL
+ *                                                      text "Dr. *"
+ *   like: 'abc'    → matches 'xabcx' at the source, which our own evaluator
+ *                    would reject — anchored means exactly 'abc'
+ *
+ * Either way the request succeeds and the caller gets a WRONG set with a 200,
+ * which is the failure this style's fail-closed default exists to prevent.
+ * Unmapped, a predicate containing `like` is unencodable, nothing is pushed,
+ * and the default fetcher applies the whole predicate as a runtime fallback —
+ * correct records, at the cost of fetching more of them.
+ *
  * For operators the where-object supports but Strapi doesn't have a
  * clean equivalent for, the style leaves them untouched (the default
  * fetcher applies them as a runtime fallback).
@@ -95,7 +112,6 @@ const OPERATOR_MAP = {
   lte: '[$lte]',
   in: '[$in]',
   nin: '[$notIn]',
-  like: '[$containsi]',    // case-insensitive substring — closest Strapi analog
   exists: '[$notNull]',    // overridden below for exists:false → [$null]
 }
 

package/src/where.js

@@ -36,6 +36,7 @@
  *   nin     Value is not in the listed array.
  *   like    Glob match (`*` any run, `?` one char). String fields only.
  *   exists  Field is truthy (boolean toggle).
+ *   under   Path containment at SEGMENT boundaries. String fields only.
  *
  * Composition keys:
  *
@@ -43,6 +44,23 @@
  *   or      Array of sub-predicates; at least one must match.
  *   not     Single sub-predicate; must not match.
  *
+ * `under` is for fields holding a slash-separated location — a record's
+ * position inside its collection, a category path, a docs section. It matches
+ * the value itself and anything below it, and it respects segment boundaries so
+ * a sibling with a shared prefix does not match:
+ *
+ *   { path: { under: '2024' } }   matches '2024' and '2024/spring'
+ *                                 does NOT match '2024b'
+ *   { path: { under: '' } }       matches everything (the root contains all)
+ *   { path: '2024' }              plain equality — that level only
+ *
+ * ⭐ Why this is an operator and not a separate `recursive:` flag on a fetch
+ * declaration: the architecture holds that a query says WHICH records the
+ * author wants, and who evaluates it is a capability question. Recursion is
+ * then the difference between `eq` and `under` — no new vocabulary above the
+ * predicate, and a source free to satisfy `under` by walking one branch instead
+ * of scanning is doing query planning, which is its business.
+ *
  * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }`.
  *
  * Type safety: type mismatches return `false` rather than throwing
@@ -53,7 +71,7 @@
 
 const COMPOSITION_KEYS = new Set(['and', 'or', 'not'])
 const OPERATORS = new Set([
-  'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'exists',
+  'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'exists', 'under',
 ])
 
 /**
@@ -120,6 +138,30 @@ function evaluateClause(key, value, record) {
   return matchEqual(fieldValue, value)
 }
 
+/**
+ * Path containment at segment boundaries.
+ *
+ * Both sides are compared with leading and trailing `/` trimmed, so an author
+ * who writes `'/2024'` or `'2024/'` gets what they meant. An empty ancestor is
+ * the root and contains everything — which is what makes "the whole collection"
+ * expressible as a predicate rather than as the absence of one.
+ *
+ * ⛔ The `+ '/'` is the whole point: a plain `startsWith` would match `2024b`
+ * against `2024`, which is the classic prefix bug and silently returns records
+ * from a sibling the author never named.
+ */
+function matchUnder(fieldValue, ancestor) {
+  if (typeof fieldValue !== 'string' || typeof ancestor !== 'string') return false
+  const a = trimSlashes(ancestor)
+  if (a === '') return true
+  const f = trimSlashes(fieldValue)
+  return f === a || f.startsWith(a + '/')
+}
+
+function trimSlashes(s) {
+  return s.replace(/^\/+/, '').replace(/\/+$/, '')
+}
+
 function isOperatorObject(value) {
   if (value == null || typeof value !== 'object' || Array.isArray(value)) return false
   // An operator-object's keys are all in OPERATORS. If even one key isn't
@@ -164,6 +206,8 @@ function evaluateOperator(op, opValue, fieldValue) {
       return globMatch(opValue, fieldValue)
     case 'exists':
       return Boolean(fieldValue) === Boolean(opValue)
+    case 'under':
+      return matchUnder(fieldValue, opValue)
     default:
       // Unknown operator → fail closed.
       return false