mikser-io-sdk-api 3.5.1 → 3.7.0

package/README.md

@@ -285,6 +285,21 @@ expand: ['sections.*.image']
 // → each section's $image becomes the resolved image entity
 ```
 
+**Resolve every reference with `$`** — when you don't want to enumerate a document's shape:
+
+```js
+// $ resolves every $-keyed ref reachable in the doc, one hop, at any depth.
+expand: ['$']
+// → author, hero, every section's image, every related entry — all hydrated,
+//   without naming where any of them sit.
+
+// $.$.$ walks the resolved graph deeper: refs, then refs of those, then refs
+// of those. A literal prefix scopes it — 'faq.$' resolves refs under faq only.
+expand: ['$.$.$', 'faq.$']
+```
+
+Where `*` iterates array indices, `$` iterates *references* — it descends objects and arrays structure-agnostically and expands what it finds. Useful when a consumer wants resolution but shouldn't have to know the document's internal shape (a framework SDK passing `expand: ['$']` for the current document, say). Still bounded by the same caps below — `maxResolved` is what keeps `$` honest.
+
 **Multiple paths in one call**:
 
 ```js
@@ -489,6 +504,55 @@ Equivalent to:
 
 `live()` keeps an internal `items` array, patches it on each event, and hands the whole array to `onChange` every time. That's the simplest contract for frameworks with state-replace semantics (the callback just overwrites state). If you need per-event deltas — animated reveals, audit logs, derived counters — use `watch()` directly.
 
+### `createCache(docs)` / `cacheKey(query)` — load-once memoized reads
+
+A local request cache: dedupe + memoize over an entities client's `list()`. For content you read repeatedly but that changes rarely — system docs, navigation, site settings — re-fetching on every component mount is wasted work. `createCache` is the lightweight tier next to `live()`: `live()` is an always-fresh SSE subscription; this is **load-once with explicit invalidation**.
+
+```js
+import { createCache } from 'mikser-io-sdk-api'
+
+const cache = createCache(client.entities('public'))
+
+// First call fetches; subsequent calls for the same query are served from memory.
+const { items } = await cache.get({ filter: { type: 'navigation' } })
+
+// Sync read — envelope if loaded, undefined otherwise.
+cache.peek({ filter: { type: 'navigation' } })   // { items, total, … } | undefined
+
+// Drop entries when you know the underlying content changed.
+cache.invalidate({ filter: { type: 'navigation' } })  // one entry
+cache.invalidate()                                     // everything
+```
+
+`createCache(client.entities('public'))` returns:
+
+| Method | What it does |
+|---|---|
+| `get(query, opts)` | Returns the same envelope as `list()` (`{ items, total, … }`). Memoizes the result; concurrent `get()`s for the same query share one in-flight request. A **failed** `get()` is not memoized — the next call retries. |
+| `peek(query)` | Sync read: the cached envelope, or `undefined` if not loaded. No fetch. |
+| `has(query)` | Sync `true`/`false` — is this query cached? |
+| `invalidate(query?)` | Drop one entry (`invalidate(query)`) or all of them (`invalidate()`). |
+| `subscribe(cb)` | Register a change listener; called on any `get` resolution or `invalidate`. Returns an unsubscribe fn. The framework SDKs build reactive reads on top of this. |
+| `key` | The `cacheKey` function (below), exposed for callers that want to key their own structures the same way. |
+
+**Keyed by the whole query.** The cache key covers `filter` / `sort` / `fields` / `expand` / `limit` / `skip` / `page` — so a with-expand and a without-expand read of the **same filter** are *distinct* entries. This is the same identity rule `cacheKeyFor()` and the api plugin's on-disk cache name already follow; a key that ignored `expand` would let a no-expand load shadow an expanded one. `cacheKey(query)` is the pure key function if you need it standalone:
+
+```js
+import { cacheKey } from 'mikser-io-sdk-api'
+
+cacheKey({ filter: { type: 'nav' } })
+cacheKey({ filter: { type: 'nav' }, expand: ['icon'] })   // ≠ the line above
+```
+
+#### Which caching tier?
+
+| Tier | Surface | Use when |
+|---|---|---|
+| One-shot | `list(query)` | A single read; you'll re-fetch yourself if you need it again. |
+| Stateful pages | `paginator(options)` | UI navigation through pages; current-page state lives in the paginator. |
+| Always-fresh feed | `live(filter, onChange)` | The view must stay in sync as content changes (SSE-driven). |
+| Load-once memoized | `createCache(docs)` | Read-repeatedly, changes-rarely content; load once, invalidate explicitly. |
+
 ### `update(payload)` / `delete(payload)` — writes
 
 Requires a token-gated endpoint with `operations: ['update', 'delete', ...]`.
@@ -523,6 +587,65 @@ Return shape follows the response `content-type`:
 - `text/*` → `string`
 - anything else (`application/pdf`, images, …) → `ArrayBuffer`
 
+## Assets
+
+Helpers for resolving served files and their transcoded derivatives. mikser's `assets()` plugin is a preset transcoder (video, image, pdf, audio), not an image pipeline — so these are format-neutral. Image-specific concerns (srcset, dimensions, `<img>` props) are a consumer concern; build them on top of `meta` where you actually know an asset is an image.
+
+### `deployedUrl(ref, { baseUrl })` — prefix a served path with the client base
+
+The catalog now carries the served path itself — `meta.url` for a file, `meta.presets.<name>` for a transcoded derivative; the engine stamps them per [ADR-0011](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/decisions/0011-asset-urls.md). So the SDK no longer *constructs* `/assets/<preset>/<source>` client-side; it just prefixes the base. One rule for every served reference, files and derivatives alike.
+
+```js
+import { deployedUrl } from 'mikser-io-sdk-api'
+
+deployedUrl(product.image.meta.url, { baseUrl: 'https://cms.example.com' })
+// → https://cms.example.com/img/products/x.jpg
+
+deployedUrl(product.video.meta.presets.poster, { baseUrl: 'https://cms.example.com' })
+// → https://cms.example.com/assets/poster/…x.jpg
+```
+
+- **Empty `baseUrl`** (the default) → returns the ref root-relative, for same-origin serving.
+- **Already-absolute ref** (`https://…` — e.g. a render baked the origin in) → passes through untouched.
+- **Falsy ref** → `''`.
+
+```js
+deployedUrl('/img/x.jpg')                                  // '/img/x.jpg'   (root-relative)
+deployedUrl('/img/x.jpg', { baseUrl: 'https://cms' })      // 'https://cms/img/x.jpg'
+deployedUrl('https://cdn.example.com/x.jpg')               // unchanged (absolute passthrough)
+```
+
+> `deployedUrl` **replaces** the old `assetUrl(source, preset, { ext })`, which constructed the derivative path client-side. That path now lives in the catalog (`meta.url` / `meta.presets.<name>`), so the SDK only prefixes the base — `assetUrl` is gone.
+
+### `watchAssetFallbacks({ doc, warn })` — dev-mode safety net
+
+A development aid (ADR-0011 Part E). It warns when an `<img>` or `<video>` fails to load — the signature of a served-file URL that hit the SPA's HTML fallback. When a served URL is missing its base prefix or points at an unexpanded reference, the app origin answers with `text/html`, which can't decode as media, so the element fires an `error` event. `watchAssetFallbacks` catches that and warns, pointing at the likely cause.
+
+```js
+import { watchAssetFallbacks } from 'mikser-io-sdk-api'
+
+if (import.meta.env.DEV) watchAssetFallbacks()
+```
+
+It installs a **capture-phase** `error` listener (media `error` events don't bubble) and returns a teardown function. Outside a browser it's a no-op that returns a no-op teardown, so it's safe to call unconditionally during SSR.
+
+| Option | Default | What it does |
+|---|---|---|
+| `doc` | `globalThis.document` | The document to listen on. Override for an iframe or a test DOM. |
+| `warn` | `console.warn` | Where the warning goes. Override to route into your own logger. |
+
+### `createAssetIndex(assets)` — id → `{ url, meta }` lookup
+
+Format-neutral lookup for managed asset entities that carry their own URL and metadata. `createAssetIndex(assets)` returns `{ asset, map }`; `asset(ref)` resolves an entity `id` to `{ url, meta } | null`, and `map` is the same data as a plain object. `meta` is the entity's raw meta block — opaque (mime, dimensions, duration, whatever the preset emitted), so a consumer that knows an asset is an image reads `meta.width` / `meta.srcset` itself.
+
+```js
+import { createAssetIndex } from 'mikser-io-sdk-api'
+
+const { asset } = createAssetIndex(items)
+asset('/images/launch-hero')   // { url: '/img/launch-hero.jpg', meta: { width: 1600, … } }
+asset('/images/missing')       // null
+```
+
 ## Recipes — composing real-time and search
 
 The methods above are the building blocks. The interesting work is gluing them together — `list()` for an initial snapshot, `watch()` to keep it fresh, and `findSimilar()` (from [`mikser-io-sdk-vector`](https://github.com/almero-digital-marketing/mikser-io-sdk-vector)) when the user is searching by meaning rather than fields.

package/index.d.ts

@@ -311,20 +311,19 @@ export interface AssetIndex {
     map: Record<string, AssetRecord>
 }
 
-export interface AssetUrlOptions {
-    /** Origin of the mikser server; omit for a root-relative URL. */
-    baseUrl?: string
-    /** Preset output format — replaces the source extension (.mp4 → .jpg). */
-    ext?: string
-}
+/**
+ * Join a base-relative served path to a base. An empty baseUrl yields a
+ * root-relative URL; an already-absolute ref passes through unchanged; an
+ * empty ref returns ''.
+ */
+export function deployedUrl(ref: string, options?: { baseUrl?: string }): string
 
 /**
- * URL of a transcoded derivative, by the assets() plugin convention:
- * `<baseUrl>/assets/<preset>/<source>`. Format-neutral (video, image,
- * pdf, audio, …) — mikser's assets() is a preset transcoder, not an
- * image pipeline.
+ * Dev-mode load-failure warner: attaches listeners that log a warning when
+ * an <img>/<video> fails to load. Returns a teardown function. No-op
+ * outside a browser.
  */
-export function assetUrl(source: string, preset: string, options?: AssetUrlOptions): string
+export function watchAssetFallbacks(options?: { doc?: Document; warn?: (message: string) => void }): () => void
 
 /**
  * Build a format-neutral lookup (id → { url, meta }) from a snapshot of
@@ -335,3 +334,32 @@ export function createAssetIndex(
     assets: Array<{ id: string; meta?: Record<string, unknown> }>,
 ): AssetIndex
 
+/**
+ * Memoizing cache over an entities client's list() — keyed by query.
+ * Frameworks wrap this in their own reactive shell; the engine layer
+ * just deduplicates and serves cached envelopes.
+ */
+export interface Cache {
+    /** Fetch (and cache) the envelope for a query; resolves from cache when present. */
+    get(query?: ListQuery, options?: object): Promise<ListEnvelope>
+    /** Synchronously read a cached envelope without fetching, or undefined when absent. */
+    peek(query?: ListQuery): ListEnvelope | undefined
+    /** Whether a cached envelope exists for the query. */
+    has(query?: ListQuery): boolean
+    /** Drop the cached envelope for the query and notify subscribers. */
+    invalidate(query?: ListQuery): void
+    /** Subscribe to cache changes; returns an unsubscribe function. */
+    subscribe(callback: () => void): () => void
+    /** The canonical cache key for a query — stable across equivalent queries. */
+    key(query?: ListQuery): string
+}
+
+/**
+ * Build a {@link Cache} over an object exposing `list(query, options)` —
+ * typically an EntitiesClient.
+ */
+export function createCache(docs: { list(query?: ListQuery, options?: object): Promise<ListEnvelope> }): Cache
+
+/** The canonical cache key for a query — stable across equivalent queries. */
+export function cacheKey(query?: ListQuery): string
+

package/index.js

@@ -29,7 +29,8 @@
 //   src/entities.js  — per-endpoint entities client (list / watch / live / ...)
 //   src/routes.js    — generateMikserRoutes (build-time route enumeration)
 //   src/href.js      — createHrefIndex (multilingual reference → URL lookup)
-//   src/asset.js     — createAssetIndex (asset metadata lookup)
+//   src/asset.js     — deployedUrl / watchAssetFallbacks / createAssetIndex
+//   src/cache.js     — createCache / cacheKey (load-once memoized list())
 import { MikserError } from './src/error.js'
 import { createEntitiesClient } from './src/entities.js'
 
@@ -65,4 +66,5 @@ export function createClient({
 export { MikserError }
 export { generateMikserRoutes } from './src/routes.js'
 export { createHrefIndex }      from './src/href.js'
-export { createAssetIndex, assetUrl } from './src/asset.js'
+export { createAssetIndex, deployedUrl, watchAssetFallbacks } from './src/asset.js'
+export { createCache, cacheKey } from './src/cache.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-sdk-api",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Client SDK for mikser-io's api plugin — query the document catalog from the browser or Node",
   "main": "index.js",
   "types": "index.d.ts",

package/src/asset.js

@@ -7,25 +7,55 @@
 import { joinUrl } from './url.js'
 
 /**
- * URL of a transcoded derivative, by the assets() plugin convention:
+ * Join a deployed, base-relative served path to the client base (ADR-0011).
  *
- *   <baseUrl>/assets/<preset>/<source>
+ * The catalog already carries the path — `meta.url` for a file, or
+ * `meta.presets.<name>` for a transcoded derivative (the assets() plugin
+ * stamps them). The SDK no longer *constructs* `/assets/<preset>/<source>`
+ * client-side; it only prefixes the base. One rule for every served
+ * reference, files and derivatives alike:
  *
- * `source` is the source ref, e.g. `/media/bg/clip.mp4`. `ext`, when
- * given, is the preset's output format and REPLACES the source extension
- * (a poster preset turns .mp4 → .jpg); omit it to keep the source ext.
- * `baseUrl` is optional — omit for a same-origin, root-relative URL.
+ *   url(product.image.meta.url)             // <base>/img/products/X.jpg
+ *   url(product.video.meta.presets.poster)  // <base>/assets/poster/…X.jpg
  *
- * @param {string} source
- * @param {string} preset
- * @param {{ baseUrl?: string, ext?: string }} [options]
+ * `baseUrl` empty → same-origin, root-relative. An already-absolute ref
+ * (a render baked the origin in) passes through untouched.
+ *
+ * @param {string} ref  A base-relative served path, e.g. `/img/x.jpg`.
+ * @param {{ baseUrl?: string }} [options]
  * @returns {string}
  */
-export function assetUrl(source, preset, { baseUrl = '', ext } = {}) {
-    if (!source || !preset) return ''
-    const file = ext ? source.replace(/\.[^./]+$/, `.${ext}`) : source
-    const path = `/assets/${preset}/${file.replace(/^\/+/, '')}`
-    return baseUrl ? joinUrl(baseUrl, path) : path
+export function deployedUrl(ref, { baseUrl = '' } = {}) {
+    if (!ref) return ''
+    if (/^https?:\/\//i.test(ref)) return ref
+    return baseUrl ? joinUrl(baseUrl, ref) : ref
+}
+
+/**
+ * Dev-mode safety net (ADR-0011 Part E). Warns when an `<img>` / `<video>`
+ * failed to load — the signature of a served-file URL that hit the app
+ * origin and got the SPA's HTML fallback (`text/html` can't decode as an
+ * image → an `error` event), i.e. a missing base prefix or an unexpanded
+ * served-entity reference. Capture phase, because media `error` events
+ * don't bubble. Returns a teardown function; no-op outside a browser.
+ *
+ *   if (import.meta.env.DEV) watchAssetFallbacks()
+ */
+export function watchAssetFallbacks({ doc = globalThis.document, warn = console.warn } = {}) {
+    if (!doc || typeof doc.addEventListener !== 'function') return () => {}
+    function onError(event) {
+        const el = event.target
+        if (!el || (el.tagName !== 'IMG' && el.tagName !== 'VIDEO')) return
+        const src = el.currentSrc || el.src || el.poster
+        if (!src) return
+        warn(
+            `[mikser] asset failed to load: ${src}\n` +
+            `  Did it resolve to the SPA fallback (text/html)? Likely a missing ` +
+            `base prefix (use url(ref)) or an unexpanded served-entity reference (ADR-0011).`,
+        )
+    }
+    doc.addEventListener('error', onError, true)
+    return () => doc.removeEventListener('error', onError, true)
 }
 
 /**

package/src/cache.js

@@ -0,0 +1,86 @@
+// Local request cache — dedupe + memoize over an entities client's list(),
+// for content read repeatedly that changes rarely (system docs, nav,
+// settings, prices). The lightweight tier next to live(): live() is an
+// always-fresh SSE subscription; this is load-once with explicit
+// invalidation. Pairs with the live href index too — meta()/useHref is
+// always-fresh; this is load-once, expand-capable, and readable from
+// non-component code (Pinia stores, plain modules), because it's a plain
+// factory, not a composable.
+//
+// Keyed by the WHOLE query — filter/sort/fields/expand/limit/skip/page — so
+// a with-expand and a without-expand read of the same filter are distinct
+// entries. Same identity rule cacheKeyFor (SDK) and cacheNameForQueryString
+// (api) already follow; a href-only key lets a no-expand load shadow an
+// expanded one (the gpoint bug that motivated this).
+//
+// Framework SDKs wrap this with their reactive primitive so a sync peek()
+// re-evaluates when an entry lands — see createReactiveCache in -vue/-react/
+// -svelte.
+
+// Deterministic JSON: object keys sorted recursively, so two equivalent
+// queries (key order aside) produce the same cache key.
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+    if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']'
+    const keys = Object.keys(value).sort()
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}'
+}
+
+export function cacheKey(query = {}) {
+    const { filter = null, sort = null, fields = null, expand = null, limit = null, skip = null, page = null } = query
+    return stableStringify({ filter, sort, fields, expand, limit, skip, page })
+}
+
+/**
+ * createCache(docs) — a memoized, deduped view over docs.list().
+ *
+ *   const cache = createCache(client.entities('public'))
+ *   await cache.get({ filter: {...}, expand: [...] })  // fetch + memoize
+ *   cache.peek(query)                                   // sync: envelope | undefined
+ *   cache.invalidate(query)  // drop one    cache.invalidate()  // drop all
+ *   const off = cache.subscribe(() => …)                // notified on any change
+ *
+ * `get` returns the same envelope shape as list() ({ items, total, … }).
+ * Concurrent get()s for the same query share one in-flight request. A
+ * failed get() is not memoized (the next call retries).
+ *
+ * @param {{ list: (query: object, opts?: object) => Promise<object> }} docs
+ */
+export function createCache(docs) {
+    if (!docs || typeof docs.list !== 'function') {
+        throw new Error('createCache: pass an entities client (got something without .list)')
+    }
+    const store = new Map()
+    const inflight = new Map()
+    const listeners = new Set()
+    const notify = () => { for (const cb of listeners) { try { cb() } catch { /* listener errors are not the cache's problem */ } } }
+
+    function get(query = {}, opts = {}) {
+        const k = cacheKey(query)
+        if (store.has(k)) return Promise.resolve(store.get(k))
+        if (inflight.has(k)) return inflight.get(k)
+        const p = Promise.resolve(docs.list(query, opts))
+            .then(env => {
+                store.set(k, env)
+                inflight.delete(k)
+                notify()
+                return env
+            })
+            .catch(err => { inflight.delete(k); throw err })
+        inflight.set(k, p)
+        return p
+    }
+
+    function peek(query = {}) { return store.get(cacheKey(query)) }
+    function has(query = {})  { return store.has(cacheKey(query)) }
+
+    function invalidate(query) {
+        if (query === undefined) { store.clear() }
+        else { store.delete(cacheKey(query)) }
+        notify()
+    }
+
+    function subscribe(cb) { listeners.add(cb); return () => { listeners.delete(cb) } }
+
+    return { get, peek, has, invalidate, subscribe, key: cacheKey }
+}