mikser-io-sdk-api 3.3.0 → 3.4.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/package.json

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

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 }
 }