mikser-io-sdk-api 3.4.0 → 3.5.1

package/README.md

@@ -453,6 +453,8 @@ For framework integration, prefer `live()` below — it handles the list+watch c
 
 The higher-level real-time primitive. Calls `onChange(items)` with the initial snapshot, then again with the patched array on every create/update/delete event. Returns a dispose function.
 
+The initial snapshot is the **complete** matching set — `live()` paginates to the end, it doesn't stop at the server's default page size. This keeps the snapshot consistent with the SSE stream that follows: `watch()` subscribes by filter with no limit, so a create/update/delete to *any* matching entity is delivered; if the snapshot were capped at page one, updates to entities past it would silently no-op (they aren't in `items`) and the view would drift. Pass `limit` (or `skip`) only when you want a bounded window — a "latest N" feed — and accept that updates outside that window won't be reflected.
+
 ```js
 const dispose = docs.live(
     { 'meta.published': true, type: 'document' },
@@ -476,7 +478,8 @@ dispose()
 Equivalent to:
 
 ```js
-// 1. await list({ filter, sort, fields, limit, skip })
+// 1. paginate list({ filter, sort, fields }) to the end  (or one bounded
+//    list() when limit/skip is set)
 // 2. onChange(items)
 // 3. for await (event of watch({ filter })) patch + onChange
 // 4. abort on dispose

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.4.0",
+  "version": "3.5.1",
   "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

@@ -556,19 +556,45 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
                     }
 
                     if (!usedFastPath) {
-                        // Pass { quiet } so list()'s wide-warning honors
-                        // the live() caller's quiet opt.
+                        // The initial snapshot must be the COMPLETE matching
+                        // set, not a single server page. watch() below
+                        // subscribes by filter with no limit, so create /
+                        // update / delete events arrive for ANY matching
+                        // entity. If the initial load stopped at the server's
+                        // default page size, an update to an entity past page 1
+                        // would silently no-op (it isn't in `items`) and a
+                        // create could append out of sort order — the live view
+                        // would drift out of sync with its own change stream.
+                        // So paginate to completion, unless the caller opted
+                        // into a bounded window via `limit` or `skip`.
                         //
-                        // `expand` flows through to the initial snapshot
-                        // call AND to watch() below, so the server's
-                        // graph-subscription path (runtime.refs) emits
-                        // already-expanded entities on every mutation
-                        // within the expansion graph. Update events
-                        // replace items in place with the new expanded
-                        // shape, keeping the consumer's view consistent.
-                        const env = await list({ filter, sort, fields, limit, skip, expand }, { quiet })
-                        if (disposed || ac.signal.aborted) return
-                        items = env.items
+                        // Pass { quiet } so list()'s wide-warning honors the
+                        // live() caller's quiet opt.
+                        //
+                        // `expand` flows through to the initial snapshot call
+                        // AND to watch() below, so the server's graph-
+                        // subscription path (runtime.refs) emits already-
+                        // expanded entities on every mutation within the
+                        // expansion graph. Update events replace items in place
+                        // with the new expanded shape, keeping the consumer's
+                        // view consistent.
+                        const bounded = limit != null || skip != null
+                        if (bounded) {
+                            const env = await list({ filter, sort, fields, limit, skip, expand }, { quiet })
+                            if (disposed || ac.signal.aborted) return
+                            items = env.items
+                        } else {
+                            const collected = []
+                            let page = 1
+                            while (true) {
+                                const env = await list({ filter, sort, fields, expand, limit: 1000, page }, { quiet })
+                                if (disposed || ac.signal.aborted) return
+                                collected.push(...env.items)
+                                if (!env.hasNext) break
+                                page = env.page + 1
+                            }
+                            items = collected
+                        }
                         onChange(items)
                     }
 
@@ -776,7 +802,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 }
     }
 }