mikser-io-sdk-api 3.3.0 → 3.5.0

package/README.md

@@ -305,9 +305,9 @@ const { items } = await docs.list({
 
 | Cap | Default | Configured at | What triggers it |
 |---|---|---|---|
-| `maxDepth` | 5 | `api.expand.maxDepth` | One path is longer than this (`a.b.c.d.e.f` at default) |
-| `maxPaths` | 20 | `api.expand.maxPaths` | The `expand` array has more entries than this |
-| `maxResolved` | 100 | `api.expand.maxResolved` | Total entity lookups for the request (across all paths) exceeded |
+| `maxDepth` | 5 | `catalog.expand.maxDepth` | One path is longer than this (`a.b.c.d.e.f` at default) |
+| `maxPaths` | 20 | `catalog.expand.maxPaths` | The `expand` array has more entries than this |
+| `maxResolved` | 100 | `catalog.expand.maxResolved` | Total entity lookups for the request (across all paths) exceeded |
 
 ```js
 try {

package/index.d.ts

@@ -302,31 +302,34 @@ export function createHrefIndex(
 
 export interface AssetRecord {
     url: string
-    width?: number
-    height?: number
-    srcset?: string
-    alt?: string
+    /** Raw entity meta block — opaque (mime, dimensions, duration, …). */
     meta?: Record<string, unknown>
 }
 
-export interface ImageProps {
-    src: string
-    width?: number
-    height?: number
-    srcset?: string
-    alt?: string
-}
-
 export interface AssetIndex {
     asset(ref: string): AssetRecord | null
-    image(ref: string): ImageProps | null
     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
+}
+
 /**
- * Build an asset metadata lookup from a snapshot of asset entities.
- * Pure data transformation — wrap in a framework-specific reactive
- * shell to drive `useAsset` composables.
+ * 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.
+ */
+export function assetUrl(source: string, preset: string, options?: AssetUrlOptions): string
+
+/**
+ * Build a format-neutral lookup (id → { url, meta }) from a snapshot of
+ * managed asset entities. Pure data transformation — wrap in a
+ * framework-specific reactive shell to drive `useAsset` composables.
  */
 export function createAssetIndex(
     assets: Array<{ id: string; meta?: Record<string, unknown> }>,

package/index.js

@@ -65,4 +65,4 @@ export function createClient({
 export { MikserError }
 export { generateMikserRoutes } from './src/routes.js'
 export { createHrefIndex }      from './src/href.js'
-export { createAssetIndex }     from './src/asset.js'
+export { createAssetIndex, assetUrl } from './src/asset.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-sdk-api",
-  "version": "3.3.0",
+  "version": "3.5.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

@@ -1,65 +1,53 @@
-// Asset metadata index — pure data version. Framework SDKs wrap this
-// in their own reactivity primitives and expose useAsset on top.
-//
-// When assets carry metadata the template needs (dimensions, srcset,
-// alt text), looking them up by reference is cleaner than re-fetching
-// per render. The convention is that asset entities have an `id`
-// (used as the reference key) plus a `meta` block with the metadata.
+// Asset URLs + metadata — format-neutral. mikser's assets() plugin is a
+// preset transcoder (video, image, pdf, audio, …), not an image pipeline,
+// so neither is this: it models a (source, preset) → derivative-URL
+// convention plus an opaque metadata lookup. 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.
+import { joinUrl } from './url.js'
 
 /**
- * @param {Array<{id: string, meta?: object}>} assets  Asset entities.
- * @returns {{
- *   asset: (ref: string) => AssetRecord|null,
- *   image: (ref: string) => ImageProps|null,
- *   map: Record<string, AssetRecord>,
- * }}
+ * URL of a transcoded derivative, by the assets() plugin convention:
  *
- * @typedef {Object} AssetRecord
- * @property {string} url
- * @property {number|undefined} width
- * @property {number|undefined} height
- * @property {string|undefined} srcset
- * @property {string|undefined} alt
- * @property {object|undefined} meta   The raw meta block, for downstream use.
+ *   <baseUrl>/assets/<preset>/<source>
  *
- * @typedef {Object} ImageProps
- * @property {string} src
- * @property {number|undefined} width
- * @property {number|undefined} height
- * @property {string|undefined} srcset
- * @property {string|undefined} alt
+ * `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.
+ *
+ * @param {string} source
+ * @param {string} preset
+ * @param {{ baseUrl?: string, ext?: 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
+}
+
+/**
+ * Format-neutral lookup for managed asset entities that carry their own
+ * URL/metadata. `asset(ref)` → `{ url, meta }` | null, keyed by entity
+ * `id`. `meta` is the entity's raw meta block, opaque — mime, dimensions,
+ * duration, whatever the preset emitted. No image semantics: a consumer
+ * that knows an asset is an image reads `meta.width`/`meta.srcset` itself.
+ *
+ * @param {Array<{id: string, meta?: object}>} assets
+ * @returns {{ asset: (ref: string) => ({url: string, meta?: object}|null), map: Record<string, {url: string, meta?: object}> }}
  */
 export function createAssetIndex(assets) {
     const map = {}
     if (Array.isArray(assets)) {
         for (const a of assets) {
             if (!a?.id) continue
-            map[a.id] = {
-                url:    a.meta?.destination ?? a.meta?.url ?? a.id,
-                width:  a.meta?.width,
-                height: a.meta?.height,
-                srcset: a.meta?.srcset,
-                alt:    a.meta?.alt,
-                meta:   a.meta,
-            }
+            map[a.id] = { url: a.meta?.destination ?? a.meta?.url ?? a.id, meta: a.meta }
         }
     }
-
-    function asset(ref) {
-        return map[ref] ?? null
+    return {
+        asset: (ref) => map[ref] ?? null,
+        map,
     }
-
-    function image(ref) {
-        const a = map[ref]
-        if (!a) return null
-        return {
-            src:    a.url,
-            width:  a.width,
-            height: a.height,
-            srcset: a.srcset,
-            alt:    a.alt,
-        }
-    }
-
-    return { asset, image, map }
 }

package/src/entities.js

@@ -51,7 +51,7 @@ const GET_MAX_URL = 1800
 // console). Server-side has a matching warning that fires for all
 // clients regardless of SDK use.
 const WIDE_RESPONSE_ITEMS = 50
-const _warnedShapes = new Set()
+const warnedShapes = new Set()
 
 function isProductionEnv() {
     try {
@@ -74,8 +74,8 @@ function maybeWarnWide({ endpoint, query, envelopeOrItems, quiet }) {
     const hasFields = Array.isArray(query?.fields) && query.fields.length > 0
     if (hasFields) return
     const shape = `${endpoint}|${JSON.stringify(query?.filter ?? null)}|${JSON.stringify(query?.sort ?? null)}`
-    if (_warnedShapes.has(shape)) return
-    _warnedShapes.add(shape)
+    if (warnedShapes.has(shape)) return
+    warnedShapes.add(shape)
     let sizeNote = ''
     try {
         const bytes = JSON.stringify(items).length
@@ -100,7 +100,7 @@ function maybeWarnWide({ endpoint, query, envelopeOrItems, quiet }) {
 // calls without noticing the snapshot is no longer involved. Deduped
 // per (endpoint, kind, what-was-set) so a page with 3 filtered calls
 // produces 3 warnings, not 30.
-const _bypassedShapes = new Set()
+const bypassedShapes = new Set()
 function maybeWarnSnapshotBypass({ endpoint, kind, filter, sort, skip, quiet }) {
     if (quiet || isProductionEnv() || isQuiet()) return
     const reasons = []
@@ -110,8 +110,8 @@ function maybeWarnSnapshotBypass({ endpoint, kind, filter, sort, skip, quiet })
     if (reasons.length === 0) return
     const reasonLabel = reasons.join('+')
     const shape = `${endpoint}|${kind}|${reasonLabel}`
-    if (_bypassedShapes.has(shape)) return
-    _bypassedShapes.add(shape)
+    if (bypassedShapes.has(shape)) return
+    bypassedShapes.add(shape)
     const fallback = kind === 'live' ? 'live list()' : 'paginated fetch'
     console.warn(
         `[mikser-sdk] data.catalog is set on "${endpoint}" but this ${kind}() call uses ${reasonLabel} — snapshot bypassed, falling back to ${fallback}.\n` +
@@ -776,7 +776,7 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             return api
         }
 
-        return { list, listAll, urlFor, cacheKeyFor, pages, paginator, watch, live, update, delete: remove, render }
+        return { list, listAll, urlFor, cacheKeyFor, pages, paginator, watch, live, update, delete: remove, render, baseUrl }
     }
 }
 

package/src/href.js

@@ -22,20 +22,31 @@
  * @returns {{
  *   href: (ref: string, lang?: string) => string,
  *   refFor: (url: string|null) => string|null,
+ *   docFor: (ref: string, lang?: string) => object|null,
+ *   metaFor: (ref: string, lang?: string) => object|null,
  *   alternates: (opts: { route: string|null, languages?: string[] }) => { current: {lang, url, ref}|null, alternates: Array<{lang, url}> },
  *   map: Record<string, Record<string, string>>,
  * }}
  */
 export function createHrefIndex(documents, { defaultLang = 'default' } = {}) {
     const map = {}
+    // ref → lang → document. The index already iterates every document
+    // with its full meta to build `map`; keeping the document here too
+    // turns the href index into a content index — `metaFor('/menu')`
+    // reads a known document by its logical reference, the companion to
+    // `href('/menu')` resolving the URL. Costs one extra object slot per
+    // document; the data was already in hand.
+    const docs = {}
     if (Array.isArray(documents)) {
         for (const document of documents) {
             const ref = document?.meta?.href
             if (!ref) continue
             const lang = document.meta?.lang ?? defaultLang
             const url  = document.meta?.route ?? document.meta?.destination ?? ref
-            if (!map[ref]) map[ref] = {}
-            map[ref][lang] = url
+            if (!map[ref])  map[ref]  = {}
+            if (!docs[ref]) docs[ref] = {}
+            map[ref][lang]  = url
+            docs[ref][lang] = document
         }
     }
 
@@ -56,6 +67,32 @@ export function createHrefIndex(documents, { defaultLang = 'default' } = {}) {
             ?? ref
     }
 
+    /**
+     * Resolve a logical reference to its document — the content
+     * companion to href(). Same lang-fallback chain (requested lang →
+     * 'default' → any available). Returns null when the ref isn't in
+     * the index (a missing document can't be faked the way a missing
+     * URL falls back to the ref string).
+     */
+    function docFor(ref, lang) {
+        const target = lang ?? defaultLang
+        const entry = docs[ref]
+        if (!entry) return null
+        return entry[target]
+            ?? entry['default']
+            ?? Object.values(entry)[0]
+            ?? null
+    }
+
+    /**
+     * The meta of the document a logical reference resolves to — the
+     * 90% case (read fields off known content by its ref). Shorthand
+     * for `docFor(ref, lang)?.meta`.
+     */
+    function metaFor(ref, lang) {
+        return docFor(ref, lang)?.meta ?? null
+    }
+
     /**
      * Reverse lookup — given a deployed URL, return the logical
      * reference it belongs to (or null if it's not in the index).
@@ -106,5 +143,5 @@ export function createHrefIndex(documents, { defaultLang = 'default' } = {}) {
         return { current, alternates: list }
     }
 
-    return { href, refFor, alternates, map }
+    return { href, refFor, docFor, metaFor, alternates, map }
 }