@uniweb/core 0.18.0 → 0.20.0

package/src/request-styles/flat-query.js

@@ -1,146 +0,0 @@
-/**
- * flat-query — plain URL query-string style.
- *
- * GET-only. Operators become bare query params:
- *
- *   ?limit=10
- *   ?sort=-date                  (single-key, "-" prefix for desc)
- *   ?sort=-date,title            (multi-key, comma-separated)
- *   ?dept=biology&tenured=true   (where, flat AND of equalities only)
- *
- * The `where:` operator is pushed **only** when the predicate is a flat
- * AND of equalities on top-level fields. Nested operator objects
- * (`{ age: { gte: 18 } }`), composition (`and` / `or` / `not`), and
- * dotted field paths disqualify pushdown — the wire format can't
- * express them. In those cases flat-query silently skips `where`, and
- * the default fetcher applies it as a runtime fallback after the
- * response arrives. This is the documented trade-off for the style's
- * simplicity: flat-query fits simple REST APIs; richer queries either
- * evaluate client-side or pick a different style.
- *
- * POST requests encode nothing — flat-query is a URL-params shape and
- * has no meaningful POST representation.
- *
- * Use case: public REST APIs like `?dept=biology&limit=10&sort=-date`.
- * For GraphQL or body-shaped backends, use json-body. For Strapi v4,
- * use the strapi style.
- */
-
-export const flatQuery = {
-  name: 'flat-query',
-  canPush: new Set(['where', 'limit', 'sort']),
-  defaultEnvelope: null,
-
-  encode(request, { method, pushCandidates, rename }) {
-    const pushed = new Set()
-    const queryParams = []
-
-    if (method !== 'GET') {
-      // POST has no flat-query representation; silent no-op.
-      return { queryParams, bodyMerge: null, pushed }
-    }
-
-    // where — only flat AND of equalities.
-    if (pushCandidates.has('where') && request.where !== undefined) {
-      const pairs = encodeFlatEqualities(request.where)
-      if (pairs !== null) {
-        for (const [k, v] of pairs) queryParams.push([applyRename(k, rename), v])
-        pushed.add('where')
-      }
-    }
-
-    if (pushCandidates.has('limit') && request.limit !== undefined) {
-      queryParams.push([wireName('limit', 'limit', rename), String(request.limit)])
-      pushed.add('limit')
-    }
-
-    if (pushCandidates.has('sort') && request.sort !== undefined) {
-      const encoded = encodeSort(request.sort)
-      if (encoded !== null) {
-        queryParams.push([wireName('sort', 'sort', rename), encoded])
-        pushed.add('sort')
-      }
-    }
-
-    return { queryParams, bodyMerge: null, pushed }
-  },
-}
-
-/**
- * Encode a where-object as flat [field, value] pairs. Returns null when
- * the predicate doesn't fit the flat-AND-equalities shape — caller
- * falls back to runtime evaluation.
- */
-function encodeFlatEqualities(where) {
-  if (!where || typeof where !== 'object' || Array.isArray(where)) return null
-  const out = []
-  for (const [key, raw] of Object.entries(where)) {
-    // Composition and operator shorthand disqualify the whole predicate.
-    if (key === 'and' || key === 'or' || key === 'not') return null
-    if (key.includes('.')) return null // dotted path — flat-query can't express nesting
-
-    // Bare primitive → implicit equality.
-    if (isPrimitive(raw)) {
-      out.push([key, stringifyPrimitive(raw)])
-      continue
-    }
-
-    // { eq: primitive } → equality. Anything else disqualifies.
-    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
-      const opKeys = Object.keys(raw)
-      if (opKeys.length === 1 && opKeys[0] === 'eq' && isPrimitive(raw.eq)) {
-        out.push([key, stringifyPrimitive(raw.eq)])
-        continue
-      }
-    }
-
-    return null
-  }
-  return out
-}
-
-/**
- * Encode `sort: 'date desc'` → `-date`; `sort: 'date desc, title asc'` →
- * `-date,title`. Returns null on malformed input (caller falls back).
- */
-function encodeSort(sortExpr) {
-  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
-  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
-  if (parts.length === 0) return null
-  const encoded = []
-  for (const part of parts) {
-    const [field, dirRaw] = part.split(/\s+/)
-    if (!field) return null
-    const desc = (dirRaw || 'asc').toLowerCase() === 'desc'
-    encoded.push(desc ? `-${field}` : field)
-  }
-  return encoded.join(',')
-}
-
-function isPrimitive(value) {
-  if (value === null) return true
-  const t = typeof value
-  return t === 'string' || t === 'number' || t === 'boolean'
-}
-
-function stringifyPrimitive(value) {
-  if (value === null) return ''
-  return String(value)
-}
-
-function wireName(operator, defaultWire, rename) {
-  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
-    return rename[operator]
-  }
-  return defaultWire
-}
-
-// `rename` on flat-query's where pushdown doesn't apply to individual
-// field names — authors who need `dept → department` should write
-// their where-objects with the backend's field name directly. rename
-// remains available for `limit` and `sort` wire names.
-function applyRename(fieldName, _rename) {
-  return fieldName
-}
-
-export default flatQuery

package/src/request-styles/index.js

@@ -1,61 +0,0 @@
-/**
- * Request-style registry.
- *
- * A "style" describes how the default fetcher reshapes a normalized
- * request into wire format — which operators become URL params, which
- * go into a body, what envelope the response carries. Sites pick a
- * style on `site.yml fetcher.request.style`; when unset, the ambient
- * default is `json-body`.
- *
- * Styles are shipped by the framework. There is no `registerStyle()`
- * API for foundations or sites — custom wire shapes are expressed via
- * foundation-level named transports. Styles are specifically for
- * reshapings of the framework's own fetcher behavior.
- *
- * Internal to @uniweb/core. Consumed by @uniweb/runtime's default-fetcher.
- */
-
-import { jsonBody } from './json-body.js'
-import { flatQuery } from './flat-query.js'
-import { strapi } from './strapi.js'
-
-const STYLES = new Map([
-  [jsonBody.name, jsonBody],
-  [flatQuery.name, flatQuery],
-  [strapi.name, strapi],
-])
-
-/**
- * Resolve a style by name. Returns the requested style if registered,
- * otherwise the ambient default (`json-body`). Unknown names trigger a
- * one-time dev warning; production silently falls back.
- *
- * @param {string|undefined|null} name
- * @param {{ dev?: boolean }} [options]
- * @returns {Object} A style module.
- */
-export function resolveStyle(name, { dev = false } = {}) {
-  if (!name) return jsonBody
-  const style = STYLES.get(name)
-  if (style) return style
-  if (dev && !warnedUnknownStyles.has(name)) {
-    warnedUnknownStyles.add(name)
-    console.warn(
-      `[default-fetcher] unknown request style "${name}"; falling back to "json-body". ` +
-        `Known styles: ${[...STYLES.keys()].join(', ')}.`,
-    )
-  }
-  return jsonBody
-}
-
-const warnedUnknownStyles = new Set()
-
-/**
- * Sentinel list of names registered at the registry level. Used by tests
- * and by dev-mode diagnostics; not part of the site-facing contract.
- */
-export function listStyleNames() {
-  return [...STYLES.keys()]
-}
-
-export { jsonBody, flatQuery, strapi }

package/src/request-styles/json-body.js

@@ -1,117 +0,0 @@
-/**
- * json-body — the framework's general-purpose request style.
- *
- * Ambient default when the site doesn't pick a style. Speaks the
- * framework's own conventions:
- *
- *   GET   — operators travel as URL params prefixed with underscore:
- *             ?_where=<JSON.stringify(predicate)>
- *             ?_limit=N
- *             ?_sort=field:dir       (comma-separated for multi-key)
- *           The leading underscore avoids collision with backend-
- *           specific query params the author may have included in `url:`.
- *
- *   POST  — operators merge as top-level keys into an object body,
- *           alongside any author-supplied body. Content-Type defaults
- *           to `application/json` unless the site set a different one.
- *           String POST bodies (rare; typically GraphQL-only) don't
- *           receive operator merge — the string is sent as-is.
- *
- * Operator name renames are applied from the `rename:` map passed in
- * context. Shallow substitutions only — `rename: { limit: pageSize }`
- * swaps the wire name `_limit` → `pageSize` on GET, or the body key
- * `limit` → `pageSize` on POST. The operator identity (what `limit`
- * means in the query) does not change.
- *
- * Internal module. Accessed by `default-fetcher.js` via the registry;
- * never imported directly from outside `@uniweb/runtime`.
- */
-
-export const jsonBody = {
-  name: 'json-body',
-
-  // Which operators this style knows how to push. The effective push set
-  // is the intersection of this and the site's `supports:` list.
-  canPush: new Set(['where', 'limit', 'sort']),
-
-  // Default response envelope. null = no wrapper (a plain JSON payload).
-  defaultEnvelope: null,
-
-  /**
-   * Encode a request against the json-body conventions.
-   *
-   * @param {Object} request - The normalized fetch request.
-   * @param {Object} ctx
-   * @param {'GET'|'POST'} ctx.method - The method the fetcher chose.
-   * @param {Set<string>} ctx.pushCandidates - Operators present on the
-   *   request AND listed in the site's `supports:`. Style may choose to
-   *   push all, some, or none of these based on what it knows how to
-   *   express on the wire.
-   * @param {Object|null} ctx.rename - Optional { operator → wireName } map.
-   * @returns {{
-   *   queryParams: Array<[string, string]>,
-   *   bodyMerge: Object|null,
-   *   pushed: Set<string>,
-   * }}
-   *   queryParams — pairs appended to the URL's query string.
-   *   bodyMerge   — object merged into the POST body, or null.
-   *   pushed      — the operators that actually rode on the wire.
-   *                 Feeds the fetcher's cache-key derivation and
-   *                 runtime-fallback skip.
-   */
-  encode(request, { method, pushCandidates, rename }) {
-    const pushed = new Set()
-    const queryParams = []
-    let bodyMerge = null
-
-    if (method === 'GET') {
-      if (pushCandidates.has('where') && request.where !== undefined) {
-        queryParams.push([
-          wireName('where', '_where', rename),
-          JSON.stringify(request.where),
-        ])
-        pushed.add('where')
-      }
-      if (pushCandidates.has('limit') && request.limit !== undefined) {
-        queryParams.push([
-          wireName('limit', '_limit', rename),
-          String(request.limit),
-        ])
-        pushed.add('limit')
-      }
-      if (pushCandidates.has('sort') && request.sort !== undefined) {
-        queryParams.push([
-          wireName('sort', '_sort', rename),
-          String(request.sort),
-        ])
-        pushed.add('sort')
-      }
-    } else if (method === 'POST') {
-      const merged = {}
-      if (pushCandidates.has('where') && request.where !== undefined) {
-        merged[wireName('where', 'where', rename)] = request.where
-        pushed.add('where')
-      }
-      if (pushCandidates.has('limit') && request.limit !== undefined) {
-        merged[wireName('limit', 'limit', rename)] = request.limit
-        pushed.add('limit')
-      }
-      if (pushCandidates.has('sort') && request.sort !== undefined) {
-        merged[wireName('sort', 'sort', rename)] = request.sort
-        pushed.add('sort')
-      }
-      if (Object.keys(merged).length > 0) bodyMerge = merged
-    }
-
-    return { queryParams, bodyMerge, pushed }
-  },
-}
-
-function wireName(operator, defaultWire, rename) {
-  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
-    return rename[operator]
-  }
-  return defaultWire
-}
-
-export default jsonBody

package/src/request-styles/strapi.js

@@ -1,248 +0,0 @@
-/**
- * strapi — Strapi v4 REST API query style.
- *
- * GET-only. Encodes a full where-object into Strapi's bracket-notation
- * filters:
- *
- *   where: { dept: 'biology' }
- *     → filters[dept][$eq]=biology
- *
- *   where: { age: { gte: 18 } }
- *     → filters[age][$gte]=18
- *
- *   where: { 'tenure.start': { gte: 2015 } }
- *     → filters[tenure][start][$gte]=2015
- *
- *   where: { or: [{ a: 1 }, { b: 2 }] }
- *     → filters[$or][0][a][$eq]=1 & filters[$or][1][b][$eq]=2
- *
- *   where: { not: { dept: 'emeritus' } }
- *     → filters[$not][dept][$eq]=emeritus
- *
- *   limit: 10
- *     → pagination[limit]=10
- *
- *   sort: 'date desc'
- *     → sort=date:desc
- *
- *   sort: 'date desc, title asc'
- *     → sort[0]=date:desc & sort[1]=title:asc
- *
- * Response envelope defaults to `{ list: 'data', item: 'data' }` —
- * Strapi v4 wraps every response in `{ data, meta }`. Sites can override
- * via `envelope:` at the site or per-fetch level.
- *
- * Operators mapped (where-object → Strapi `$op`):
- *   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).
- */
-
-export const strapi = {
-  name: 'strapi',
-  canPush: new Set(['where', 'limit', 'sort']),
-  defaultEnvelope: { list: 'data', item: 'data' },
-
-  encode(request, { method, pushCandidates, rename }) {
-    const pushed = new Set()
-    const queryParams = []
-
-    if (method !== 'GET') {
-      // Strapi v4 REST is GET-only for reads.
-      return { queryParams, bodyMerge: null, pushed }
-    }
-
-    if (pushCandidates.has('where') && request.where !== undefined) {
-      const filterKey = wireName('where', 'filters', rename)
-      const pairs = encodeStrapiFilters(request.where, filterKey)
-      if (pairs !== null) {
-        for (const pair of pairs) queryParams.push(pair)
-        pushed.add('where')
-      }
-    }
-
-    if (pushCandidates.has('limit') && request.limit !== undefined) {
-      const limitKey = wireName('limit', 'pagination[limit]', rename)
-      queryParams.push([limitKey, String(request.limit)])
-      pushed.add('limit')
-    }
-
-    if (pushCandidates.has('sort') && request.sort !== undefined) {
-      const sortPairs = encodeStrapiSort(request.sort, wireName('sort', 'sort', rename))
-      if (sortPairs !== null) {
-        for (const pair of sortPairs) queryParams.push(pair)
-        pushed.add('sort')
-      }
-    }
-
-    return { queryParams, bodyMerge: null, pushed }
-  },
-}
-
-// ─── where encoding ────────────────────────────────────────────────────────
-
-// Values are the Strapi operator *with* bracket delimiters, so they
-// concatenate cleanly into a bracketed path like `filters[field][$eq]`.
-const OPERATOR_MAP = {
-  eq: '[$eq]',
-  ne: '[$ne]',
-  gt: '[$gt]',
-  gte: '[$gte]',
-  lt: '[$lt]',
-  lte: '[$lte]',
-  in: '[$in]',
-  nin: '[$notIn]',
-  exists: '[$notNull]',    // overridden below for exists:false → [$null]
-}
-
-/**
- * Walk a where-object and emit [paramName, paramValue] pairs encoding
- * Strapi's bracket syntax. Returns null if any branch is unencodable
- * (caller falls back to runtime evaluation for the whole predicate).
- */
-function encodeStrapiFilters(where, rootKey) {
-  const out = []
-  try {
-    walkPredicate(where, [rootKey], out)
-  } catch (err) {
-    if (err && err.unencodable) return null
-    throw err
-  }
-  return out.length > 0 ? out : null
-}
-
-function walkPredicate(node, path, out) {
-  if (!node || typeof node !== 'object' || Array.isArray(node)) {
-    throwUnencodable()
-  }
-
-  // Top-level each key is either composition ($and/$or/$not) or a field.
-  for (const [key, value] of Object.entries(node)) {
-    if (key === 'and' || key === 'or') {
-      if (!Array.isArray(value)) throwUnencodable()
-      value.forEach((sub, i) => {
-        walkPredicate(sub, [...path, `[$${key}]`, `[${i}]`], out)
-      })
-    } else if (key === 'not') {
-      walkPredicate(value, [...path, '[$not]'], out)
-    } else {
-      emitFieldPredicate(key, value, path, out)
-    }
-  }
-}
-
-function emitFieldPredicate(field, value, path, out) {
-  // Dotted paths become nested bracket segments: `tenure.start` →
-  // `[tenure][start]`.
-  const fieldSegments = field.split('.').map((seg) => `[${seg}]`)
-  const fieldPath = [...path, ...fieldSegments]
-
-  // Bare primitive → implicit eq.
-  if (isPrimitive(value)) {
-    out.push([joinPath(fieldPath) + '[$eq]', stringifyPrimitive(value)])
-    return
-  }
-
-  if (value && typeof value === 'object' && !Array.isArray(value)) {
-    for (const [opName, opValue] of Object.entries(value)) {
-      const strapiOp = OPERATOR_MAP[opName]
-      if (!strapiOp) throwUnencodable()
-
-      if (opName === 'in' || opName === 'nin') {
-        if (!Array.isArray(opValue)) throwUnencodable()
-        opValue.forEach((item, i) => {
-          if (!isPrimitive(item)) throwUnencodable()
-          out.push([joinPath(fieldPath) + strapiOp + `[${i}]`, stringifyPrimitive(item)])
-        })
-        continue
-      }
-
-      if (opName === 'exists') {
-        // { exists: true }  → field IS NOT NULL  → [field][$notNull]=true
-        // { exists: false } → field IS NULL      → [field][$null]=true
-        const wantsPresent = !!opValue
-        out.push([joinPath(fieldPath) + (wantsPresent ? '[$notNull]' : '[$null]'), 'true'])
-        continue
-      }
-
-      if (!isPrimitive(opValue)) throwUnencodable()
-      out.push([joinPath(fieldPath) + strapiOp, stringifyPrimitive(opValue)])
-    }
-    return
-  }
-
-  throwUnencodable()
-}
-
-function joinPath(segments) {
-  return segments.join('')
-}
-
-function throwUnencodable() {
-  const err = new Error('unencodable predicate')
-  err.unencodable = true
-  throw err
-}
-
-// ─── sort encoding ─────────────────────────────────────────────────────────
-
-function encodeStrapiSort(sortExpr, baseKey) {
-  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
-  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
-  if (parts.length === 0) return null
-
-  const encoded = []
-  for (const part of parts) {
-    const [field, dirRaw] = part.split(/\s+/)
-    if (!field) return null
-    const dir = (dirRaw || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'
-    encoded.push(`${field}:${dir}`)
-  }
-
-  if (encoded.length === 1) {
-    return [[baseKey, encoded[0]]]
-  }
-  return encoded.map((v, i) => [`${baseKey}[${i}]`, v])
-}
-
-// ─── helpers ───────────────────────────────────────────────────────────────
-
-function isPrimitive(value) {
-  if (value === null) return true
-  const t = typeof value
-  return t === 'string' || t === 'number' || t === 'boolean'
-}
-
-function stringifyPrimitive(value) {
-  if (value === null) return ''
-  return String(value)
-}
-
-function wireName(operator, defaultWire, rename) {
-  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
-    return rename[operator]
-  }
-  return defaultWire
-}
-
-export default strapi