mikser-io-sdk-api 2.3.0 → 2.4.0

package/README.md

@@ -8,6 +8,14 @@ For semantic search against the `vector` plugin, install [mikser-io-sdk-vector](
 
 Zero dependencies. Runs anywhere `fetch` is available (modern browsers, Node 18+, Deno, Bun, Workers).
 
+> **Using Vue, React, or Svelte?** You probably want one of the framework SDKs — they wrap this package in framework-idiomatic primitives (`useDocument` / `useDocuments`, multilingual `useHref`, live SSE-driven updates) so you don't write a watch loop or lifecycle plumbing yourself:
+>
+> - [`mikser-io-sdk-vue`](https://github.com/almero-digital-marketing/mikser-io-sdk-vue) — Vue 3 composables + vue-router integration
+> - [`mikser-io-sdk-react`](https://github.com/almero-digital-marketing/mikser-io-sdk-react) — React 18+ / 19+ hooks + React Router v6+
+> - [`mikser-io-sdk-svelte`](https://github.com/almero-digital-marketing/mikser-io-sdk-svelte) — Svelte 5 (runes) + SvelteKit
+>
+> Use **this** package directly when you're writing a custom adapter for another framework (Solid, Qwik, vanilla JS, server-side Node) or when you need the lower-level surface (`list`, `urlFor`, `watch`, `render`).
+
 ## Install
 
 ```bash
@@ -206,9 +214,9 @@ Equivalent to:
 // 4. abort on dispose
 ```
 
-…but with race-safe cleanup (no `mounted` flag needed in caller code), unified error routing via `onError`, and a single dispose path. This is the building block the framework adapters in [**Recipes**](#recipes--composing-real-time-and-search) use.
+…but with race-safe cleanup (no `mounted` flag needed in caller code), unified error routing via `onError`, and a single dispose path. This is the building block the [framework SDKs](#framework-integration) (Vue / React / Svelte) consume internally — and the surface to use directly if you're writing a custom adapter.
 
-`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 React-style frameworks (the callback can replace state). If you need per-event deltas — animated reveals, audit logs, derived counters — use `watch()` directly.
+`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.
 
 ### `update(payload)` / `delete(payload)` — writes
 
@@ -443,142 +451,32 @@ Two SDKs, one mental model, one server. The vector store gives you ranked semant
 
 ### Framework integration
 
-All the boilerplate (initial fetch, watch loop, race-safe cleanup) lives inside `docs.live()`. The framework adapters are ~5 lines each — they just give the SDK a callback and call dispose on unmount.
+All the boilerplate (initial fetch, watch loop, race-safe cleanup) lives inside `live()`. A framework adapter is ~5 lines — it gives the SDK a callback and calls dispose on unmount. For the three major frameworks, those adapters are already published:
 
-The shared module — used by every variant below — wires the client once:
+| Framework | Package | Primitive |
+|---|---|---|
+| Vue 3 | [`mikser-io-sdk-vue`](https://github.com/almero-digital-marketing/mikser-io-sdk-vue) | `useDocument(id)` / `useDocuments(query)` returning Vue refs; vue-router integration via `createMikserRouter` |
+| React 18+ / 19+ | [`mikser-io-sdk-react`](https://github.com/almero-digital-marketing/mikser-io-sdk-react) | `useDocument(id)` / `useDocuments(query)` hooks; React Router integration via `useMikserRoutes` → `useRoutes` |
+| Svelte 5 | [`mikser-io-sdk-svelte`](https://github.com/almero-digital-marketing/mikser-io-sdk-svelte) | `useDocument(() => id)` / `useDocuments(() => query)` runes-backed reactives; SvelteKit `entries()` integration via `generateMikserRoutes` |
 
-```js
-// mikser.js — single source of truth for the configured client
-import { createClient } from 'mikser-io-sdk-api'
-export const docs = createClient({ baseUrl: 'https://cms.example.com' })
-    .entities('public')
-```
+All three share the same conceptual surface — single-document subscription, list subscription, multilingual `useHref` / `useAlternates`, asset resolution via `useAsset` — wrapped in each framework's idiomatic shape. They all peer-depend on this package and consume `live()` internally; nothing about their behaviour is duplicated logic. If you have one of those three frameworks, prefer the matching SDK over hand-rolling against `live()`.
 
-#### React (hook)
+The shape adapts to **any** framework with a setup-and-cleanup lifecycle — Solid (`createSignal` + `onCleanup`), Qwik (`useTask$`), Lit, or vanilla JS. For those, the adapter pattern is the same five lines: instantiate state, call `live(filter, setState)`, store the returned `dispose`, call it on teardown.
 
 ```js
-// useLiveEntities.js
-import { useEffect, useState } from 'react'
-import { docs } from './mikser'
-
-export function useLiveEntities(filter, options) {
-    const [items, setItems] = useState([])
-    useEffect(
-        () => docs.live(filter, setItems, options),  // returns dispose
-        [JSON.stringify(filter)],
-    )
-    return items
-}
-```
+// vanilla adapter shape — works in any environment
+const documents = createClient({ baseUrl }).entities('public')
 
-```jsx
-// ArticleList.jsx
-import { useLiveEntities } from './useLiveEntities'
-
-export function ArticleList() {
-    const articles = useLiveEntities(
-        { type: 'document', 'meta.collection': 'articles', 'meta.published': true },
-        { sort: { 'meta.date': -1 }, limit: 20 },
-    )
-    return (
-        <ul>
-            {articles.map(a => <li key={a.id}>{a.meta.title}</li>)}
-        </ul>
-    )
-}
-```
-
-#### Vue 3 (composable, Composition API)
-
-```js
-// useLiveEntities.js
-import { ref, onMounted, onUnmounted } from 'vue'
-import { docs } from './mikser'
-
-export function useLiveEntities(filter, options) {
-    const items = ref([])
-    let dispose
-    onMounted (() => { dispose = docs.live(filter, v => items.value = v, options) })
-    onUnmounted(() => dispose?.())
-    return { items }
-}
-```
-
-```vue
-<!-- ArticleList.vue -->
-<script setup>
-import { useLiveEntities } from './useLiveEntities'
-
-const { items: articles } = useLiveEntities(
-    { type: 'document', 'meta.collection': 'articles', 'meta.published': true },
+const dispose = documents.live(
+    { 'meta.published': true },
+    (items) => render(items),               // your update callback
     { sort: { 'meta.date': -1 }, limit: 20 },
 )
-</script>
 
-<template>
-    <ul>
-        <li v-for="a in articles" :key="a.id">{{ a.meta.title }}</li>
-    </ul>
-</template>
-```
-
-#### Svelte (writable store — works in Svelte 3, 4, and 5)
-
-Svelte's `writable(initial, start)` pattern is a perfect fit: `start` runs when the store gains its first subscriber and the returned `stop` runs when the last one disappears. The store lifecycle and `live()`'s dispose function line up exactly.
-
-```js
-// liveEntities.js
-import { writable } from 'svelte/store'
-import { docs } from './mikser'
-
-export function liveEntities(filter, options) {
-    return writable([], (set) => docs.live(filter, set, options))
-}
-```
-
-```svelte
-<!-- ArticleList.svelte -->
-<script>
-    import { liveEntities } from './liveEntities'
-
-    const articles = liveEntities(
-        { type: 'document', 'meta.collection': 'articles', 'meta.published': true },
-        { sort: { 'meta.date': -1 }, limit: 20 },
-    )
-</script>
-
-<ul>
-    {#each $articles as a (a.id)}
-        <li>{a.meta.title}</li>
-    {/each}
-</ul>
-```
-
-If you're on Svelte 5 and prefer runes over stores:
-
-```svelte
-<!-- ArticleList.svelte (Svelte 5 runes) -->
-<script>
-    import { onMount } from 'svelte'
-    import { docs } from './mikser'
-
-    let articles = $state([])
-    const filter = { type: 'document', 'meta.collection': 'articles', 'meta.published': true }
-
-    onMount(() => docs.live(filter, v => articles = v, {
-        sort: { 'meta.date': -1 }, limit: 20,
-    }))
-</script>
-
-<ul>
-    {#each articles as a (a.id)}
-        <li>{a.meta.title}</li>
-    {/each}
-</ul>
+// later, on teardown
+dispose()
 ```
 
-The same shape adapts to Solid (`createSignal` + `onCleanup`), Qwik (`useTask$`), or vanilla JS — anywhere with a setup-and-cleanup lifecycle. The SDK doesn't care.
-
 ## Configure
 
 ```js

package/index.d.ts

@@ -115,6 +115,13 @@ export interface EntitiesClient {
     urlFor(query?: ListQuery): string
     /** Iterate result pages — yields each envelope until hasNext is false. */
     pages<T = unknown>(query?: ListQuery): AsyncGenerator<ListEnvelope<T>>
+    /**
+     * One-shot: fetch every matching entity into a flat array.
+     * Auto-paginates internally; `limit` controls per-page batch size
+     * (default 1000), not total cap. Right for SSG enumeration; wrong
+     * for catalogs too large to hold in memory.
+     */
+    listAll<T = unknown>(query?: ListQuery): Promise<T[]>
     /**
      * Open an SSE stream and yield events as matching entities change.
      * Compose with list() for initial state, then watch() for updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-sdk-api",
-  "version": "2.3.0",
+  "version": "2.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",
@@ -18,7 +18,13 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {},
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/almero-digital-marketing/mikser-io-sdk-api.git"

package/src/entities.js

@@ -64,6 +64,27 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             }
         }
 
+        /**
+         * One-shot: fetch every entity matching the filter into a flat
+         * array. Auto-paginates internally via pages() — `limit` in the
+         * query controls the per-page batch size (default 1000), not the
+         * total cap.
+         *
+         * Right when: SSG route enumeration, sitemap generation, build-
+         * time indexing — anything that needs the whole filtered set in
+         * memory at once.
+         *
+         * Wrong when: the catalog is large enough that loading all of it
+         * is wasteful. Use pages() directly and stream-process there.
+         */
+        async function listAll(query = {}) {
+            const items = []
+            for await (const env of pages({ limit: 1000, ...query })) {
+                items.push(...env.items)
+            }
+            return items
+        }
+
         /**
          * Subscribe to changes — opens an SSE stream and yields events
          * for each matching entity change (CREATE / UPDATE / DELETE).
@@ -264,6 +285,6 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             return res.arrayBuffer()
         }
 
-        return { list, urlFor, pages, watch, live, update, delete: remove, render }
+        return { list, listAll, urlFor, pages, watch, live, update, delete: remove, render }
     }
 }