mikser-io-sdk-api 3.0.0 → 3.1.0

package/index.d.ts

@@ -187,3 +187,86 @@ export declare class MikserError extends Error {
     status: number
     body: { error?: string } | undefined
 }
+
+// ────────────────────────────────────────────────────────────────────
+// Pure utilities — framework SDKs wrap these in their own reactivity.
+// ────────────────────────────────────────────────────────────────────
+
+export interface GenerateRoutesOptions<TRoute = unknown> {
+    /** A mikser entities client (the result of createClient(...).entities(name)). */
+    client: { listAll(query: ListQuery): Promise<Array<{ id: string; meta?: Record<string, unknown> }>> }
+    /** Sift filter — defaults to "published documents that declare meta.route". */
+    filter?: Filter
+    /** Maps a catalog document to a route descriptor (or null to skip). */
+    mapRoute: (document: { id: string; meta?: Record<string, unknown> }) => TRoute | null
+}
+
+/**
+ * Build-time route enumeration. Auto-paginates via listAll() and
+ * applies `mapRoute` to every catalog entity that matches the filter.
+ * `null` returns from `mapRoute` are dropped.
+ */
+export function generateMikserRoutes<TRoute = unknown>(
+    options: GenerateRoutesOptions<TRoute>,
+): Promise<TRoute[]>
+
+export interface HrefIndexOptions {
+    /** Fallback language tag for documents that don't declare meta.lang. Default 'default'. */
+    defaultLang?: string
+}
+
+export interface HrefIndex {
+    /** Resolve a logical reference (`/about`) to a deployed URL for the given language. */
+    href(ref: string, lang?: string): string
+    /** Reverse — given a deployed URL, return the logical reference it belongs to. */
+    refFor(url: string | null): string | null
+    /** Alternates for a deployed URL — `current` plus the alternate-language URLs. */
+    alternates(options: { route: string | null; languages?: string[] }): {
+        current: { lang: string | null; url: string; ref: string } | null
+        alternates: Array<{ lang: string; url: string }>
+    }
+    /** Raw `ref → { lang → url }` map, for inspection / debugging. */
+    map: Record<string, Record<string, string>>
+}
+
+/**
+ * Build a multilingual href lookup from a snapshot of catalog documents.
+ * Pure data transformation — wrap in a framework-specific reactive
+ * shell to drive `useHref` / `useAlternates` composables.
+ */
+export function createHrefIndex(
+    documents: Array<{ meta?: Record<string, unknown> }>,
+    options?: HrefIndexOptions,
+): HrefIndex
+
+export interface AssetRecord {
+    url: string
+    width?: number
+    height?: number
+    srcset?: string
+    alt?: string
+    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>
+}
+
+/**
+ * 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.
+ */
+export function createAssetIndex(
+    assets: Array<{ id: string; meta?: Record<string, unknown> }>,
+): AssetIndex

package/index.js

@@ -27,6 +27,9 @@
 //   src/url.js       — URL building (joinUrl, sortToParam, filterToParams)
 //   src/sse.js       — SSE event parser
 //   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)
 import { MikserError } from './src/error.js'
 import { createEntitiesClient } from './src/entities.js'
 
@@ -60,3 +63,6 @@ export function createClient({
 }
 
 export { MikserError }
+export { generateMikserRoutes } from './src/routes.js'
+export { createHrefIndex }      from './src/href.js'
+export { createAssetIndex }     from './src/asset.js'

package/package.json

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

@@ -0,0 +1,65 @@
+// 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.
+
+/**
+ * @param {Array<{id: string, meta?: object}>} assets  Asset entities.
+ * @returns {{
+ *   asset: (ref: string) => AssetRecord|null,
+ *   image: (ref: string) => ImageProps|null,
+ *   map: Record<string, AssetRecord>,
+ * }}
+ *
+ * @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.
+ *
+ * @typedef {Object} ImageProps
+ * @property {string} src
+ * @property {number|undefined} width
+ * @property {number|undefined} height
+ * @property {string|undefined} srcset
+ * @property {string|undefined} alt
+ */
+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,
+            }
+        }
+    }
+
+    function asset(ref) {
+        return map[ref] ?? null
+    }
+
+    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/href.js

@@ -0,0 +1,110 @@
+// Multilingual href resolution — pure data version. Framework SDKs
+// (Vue/React/Svelte) wrap this in their own reactivity primitives and
+// expose useHref / useAlternates composables on top.
+//
+// The "logical reference → deployed URL" mapping lets the consumer
+// link to a content-shaped identifier (`/about`) and have it resolve
+// to whatever URL the current locale serves it at (`/en/about`,
+// `/fr/a-propos`, etc.). Convention is three meta fields:
+//
+//   meta.href:  '/about'              (logical reference)
+//   meta.lang:  'en'                  (language this doc represents)
+//   meta.route: '/en/about'           (deployed URL)
+//
+// Anything missing `meta.href` is excluded from the index.
+
+/**
+ * @param {Array<{meta?: object}>} documents  Catalog documents with meta.
+ * @param {Object} [options]
+ * @param {string} [options.defaultLang='default']  Fallback language tag
+ *        for documents that don't declare meta.lang. The literal string
+ *        `'default'` is treated as a fallback bucket in lookups.
+ * @returns {{
+ *   href: (ref: string, lang?: string) => string,
+ *   refFor: (url: string|null) => string|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 = {}
+    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
+        }
+    }
+
+    /**
+     * Resolve a logical reference to a deployed URL.
+     *
+     * Fallback chain: requested lang → `'default'` bucket → any
+     * available language → the input reference unchanged (so broken
+     * references stay visible rather than silently becoming undefined).
+     */
+    function href(ref, lang) {
+        const target = lang ?? defaultLang
+        const entry = map[ref]
+        if (!entry) return ref
+        return entry[target]
+            ?? entry['default']
+            ?? Object.values(entry)[0]
+            ?? ref
+    }
+
+    /**
+     * Reverse lookup — given a deployed URL, return the logical
+     * reference it belongs to (or null if it's not in the index).
+     */
+    function refFor(url) {
+        if (url == null) return null
+        for (const [ref, byLang] of Object.entries(map)) {
+            if (Object.values(byLang).includes(url)) return ref
+        }
+        return null
+    }
+
+    /**
+     * Alternates for a deployed URL — useful for hreflang tags and
+     * language switchers.
+     *
+     * `languages` controls the alternate set:
+     *   - omitted: only return languages that actually exist in the
+     *     catalog for this ref. Right shape for hreflang (don't
+     *     advertise translations that don't exist).
+     *   - provided as an array: return one entry per requested
+     *     language, using href()'s fallback chain when a translation
+     *     doesn't exist. Right shape for language switchers (show
+     *     every locale the app supports).
+     *
+     * The current page's own language is excluded from `alternates` —
+     * it's what `current` is for. Callers that want it included can
+     * prepend `current` themselves.
+     */
+    function alternates({ route, languages } = {}) {
+        if (route == null) return { current: null, alternates: [] }
+        const ref = refFor(route)
+        if (ref == null) return { current: null, alternates: [] }
+        const entry = map[ref] ?? {}
+        const currentLang = Object.entries(entry).find(([, url]) => url === route)?.[0] ?? null
+        const current = { lang: currentLang, url: route, ref }
+
+        let list
+        if (Array.isArray(languages)) {
+            list = languages
+                .filter(lang => lang !== currentLang)
+                .map(lang => ({ lang, url: href(ref, lang) }))
+        } else {
+            list = Object.entries(entry)
+                .filter(([lang]) => lang !== currentLang && lang !== 'default')
+                .map(([lang, url]) => ({ lang, url }))
+        }
+        return { current, alternates: list }
+    }
+
+    return { href, refFor, alternates, map }
+}

package/src/routes.js

@@ -0,0 +1,34 @@
+// Build-time route enumeration. Given a mikser entities client and a
+// mapRoute function, return the array of route descriptors produced by
+// applying `mapRoute` to every catalog entity that matches the filter.
+//
+// Auto-paginates via the client's listAll() under the hood — no manual
+// limit, no silent truncation on large catalogs.
+//
+// Framework-agnostic: the `mapRoute` return shape is whatever your build
+// pipeline expects (vite-ssg routes, Next pages, SvelteKit entries, etc.).
+// Framework SDKs re-export this with their own typed mapRoute signatures.
+
+const DEFAULT_FILTER = { 'meta.published': true, 'meta.route': { $exists: true } }
+
+/**
+ * @param {Object} options
+ * @param {Object} options.client    A mikser entities client (the result of
+ *                                   createClient(...).entities(name)).
+ * @param {Object} [options.filter]  Sift filter — defaults to "published
+ *                                   documents that declare meta.route".
+ * @param {Function} options.mapRoute  (document) => routeDescriptor | null.
+ *                                   Null returns are dropped.
+ * @returns {Promise<Array>} The mapped route descriptors.
+ */
+export async function generateMikserRoutes({
+    client,
+    filter = DEFAULT_FILTER,
+    mapRoute,
+} = {}) {
+    if (!client)   throw new Error('generateMikserRoutes: { client } is required')
+    if (!mapRoute) throw new Error('generateMikserRoutes: { mapRoute } is required')
+
+    const items = await client.listAll({ filter, fields: ['id', 'meta'] })
+    return items.map(mapRoute).filter(r => r != null)
+}