@meeovi/layer-search 1.0.6 → 1.0.7

package/README.md

@@ -1,7 +1,7 @@
 <!-- packages/search/README.md -->
 # @meeovi/search
 
-A modular, provider-agnostic search module for the Alternate Framework. It provides a unified, typed search API with pluggable adapters (Meilisearch, OpenSearch, mock adapters), a small CLI for indexing/warmup, and event hooks.
+A modular, provider-agnostic search layer for the Alternate Framework. It provides a unified, typed search API with pluggable adapters (Meilisearch, OpenSearch, mock adapters), lightweight bridges for UI integrations (InstantSearch / Searchkit), a small CLI for indexing/warmup, and event hooks.
 
 ## Features
 
@@ -51,9 +51,12 @@ const app = createAlternateApp({
 
 await app.start()
 
-const search = app.context.getAdapter('search')
-const results = await search.search({ term: 'shoes' })
-console.log(results.items)
+// After app startup you can access the registered `search` adapter via the runtime
+const searchAdapter = app.context.getAdapter('search')
+if (searchAdapter) {
+  const results = await searchAdapter.search({ term: 'shoes', page: 1, pageSize: 10 })
+  console.log(results.items)
+}
 ```
 
 ## Adapters
@@ -92,7 +95,7 @@ const mock = createMockSearchAdapter([
   { id: '2', title: 'Blue Shirt' }
 ])
 
-const results = await mock.search({ term: 'red' })
+const results = await mock.search({ term: 'red', page: 1, pageSize: 10 })
 ```
 
 ## Configuration
@@ -115,6 +118,37 @@ Example `search` config in your app:
 
 The module validates that `defaultProvider` and the referenced provider configuration exist, and that required fields for each adapter are present.
 
+## UI Integrations (InstantSearch / Searchkit)
+
+This layer includes bridges that let UI code use Algolia InstantSearch or Searchkit clients without coupling the UI to a particular backend provider. Use `createInstantSearchBridge` / `createSearchkitBridge` on the client, and `createSearchkitGraphQLHandler` on the server when exposing a GraphQL endpoint for Searchkit-server.
+
+Example (client):
+
+```ts
+import { createInstantSearchBridge } from '@meeovi/search'
+// `manager` is the `SearchManager` instance available on the app context
+const bridge = createInstantSearchBridge(manager)
+
+const instantsearchClient = {
+  search(requests) {
+    return bridge.searchFunction({ state: requests[0].params, setResults: () => {} })
+  }
+}
+```
+
+Example (server - Express):
+
+```ts
+import express from 'express'
+import { createSearchkitGraphQLHandler } from '@meeovi/search'
+
+const app = express()
+app.use(express.json())
+app.post('/graphql', createSearchkitGraphQLHandler(manager))
+```
+
+These bridges map InstantSearch/Searchkit request shapes into the layer's `SearchManager` and underlying adapters so UI code doesn't need to change when you swap search providers.
+
 ## Events
 
 This module emits bus events that you can listen to:

package/app/composables/bridges/searchkit-server.ts

@@ -0,0 +1,51 @@
+import { graphql, buildSchema } from 'graphql'
+import type { SearchManager } from '../core/SearchManager'
+
+const schema = buildSchema(`
+  type Hit { id: ID, title: String, description: String, price: Float }
+  type SearchResult {
+    items: [Hit]
+    total: Int
+    page: Int
+    pageSize: Int
+  }
+  type Query {
+    search(term: String, page: Int, pageSize: Int, filters: String): SearchResult
+  }
+`)
+
+function parseFilters(filters?: string) {
+  if (!filters) return {}
+  const entries = String(filters).split(' AND ').map((s) => s.split(':'))
+  return Object.fromEntries(entries.map(([k, v]) => [k, v?.replace(/^"|"$/g, '')]))
+}
+
+export function createSearchkitGraphQLHandler(manager: SearchManager) {
+  const root: any = {
+    search: async ({ term, page, pageSize, filters }: any) => {
+      manager.context.setQuery(term || '')
+      manager.context.setPage(page || 1)
+      manager.context.setPageSize(pageSize || manager.context.state.pageSize)
+      if (filters) {
+        manager.context.state.filters = parseFilters(filters) as any
+      }
+
+      const res = await manager.search()
+
+      return {
+        items: res.items,
+        total: res.total,
+        page: res.page,
+        pageSize: res.pageSize
+      }
+    }
+  }
+
+  return async function handler(req: any, res: any) {
+    const { query, variables } = req.body || {}
+    const result = await graphql({ schema, source: query, rootValue: root, variableValues: variables })
+    res.json(result)
+  }
+}
+
+export default createSearchkitGraphQLHandler

package/app/composables/bridges/searchkit.ts

@@ -0,0 +1,88 @@
+import type { SearchManager } from '../core/SearchManager'
+import type { BuiltSearchQuery } from '../core/QueryBuilder'
+
+type InstantSearchRequest = {
+  indexName: string
+  params: Record<string, any>
+}
+
+type InstantSearchResult = {
+  results: {
+    hits: any[]
+    nbHits: number
+    page: number
+    hitsPerPage: number
+  }
+}
+
+function mapRequestToQuery(params: Record<string, any>, existing?: Partial<BuiltSearchQuery>) {
+  const q: Partial<BuiltSearchQuery> = existing ?? {}
+
+  if (typeof params.query === 'string') q.term = params.query
+  if (typeof params.page === 'number') q.page = params.page + 1 // instantsearch pages are 0-based
+  if (typeof params.hitsPerPage === 'number') q.pageSize = params.hitsPerPage
+
+  // Map simple filters from InstantSearch `facets` or `filters` param
+  if (params.filters && typeof params.filters === 'string') {
+    // basic parsing: "field:value AND other:value"
+    const entries = params.filters.split(' AND ').map((s: string) => s.split(':'))
+    q.filters = Object.fromEntries(entries.map(([k, v]) => [k, v.replace(/^"|"$/g, '')]))
+  }
+
+  return q as BuiltSearchQuery
+}
+
+export function createSearchkitBridge(manager: SearchManager) {
+  return {
+    // InstantSearch client "search" method
+    async search(requests: InstantSearchRequest[]): Promise<InstantSearchResult[]> {
+      // Support single-index or multi-index by mapping each request to a search call
+      const results: InstantSearchResult[] = []
+
+      for (const req of requests) {
+        const params = req.params || {}
+
+        const built = mapRequestToQuery(params)
+
+        // apply to manager context
+        manager.context.setQuery(built.term || '')
+        manager.context.setPage(built.page || 1)
+        manager.context.setPageSize(built.pageSize || manager.context.state.pageSize)
+        if (built.filters) {
+          // clear and set simple filters
+          manager.context.state.filters = built.filters as any
+        }
+
+        const res = await manager.search()
+
+        results.push({
+          results: {
+            hits: res.items,
+            nbHits: res.total,
+            page: (res.page || 1) - 1,
+            hitsPerPage: res.pageSize || manager.context.state.pageSize
+          }
+        })
+      }
+
+      return results
+    },
+
+    // Minimal support for Searchkit/InstantSearch facet search
+    async searchForFacetValues(indexName: string, params: any) {
+      // Map to a query with term for facet matching
+      const built = mapRequestToQuery({ query: params.facetQuery })
+
+      manager.context.setQuery(built.term || '')
+      manager.context.setPage(1)
+      const res = await manager.search()
+
+      return {
+        facetHits: (res.items || []).map((item: any) => ({ value: item[params.attribute], count: 0 })),
+        exhaustiveFacetsCount: true
+      }
+    }
+  }
+}
+
+export default createSearchkitBridge

package/app/composables/index.ts

@@ -6,4 +6,7 @@ export * from './core/Filters'
 export * from './core/Facets'
 export * from './bridges/instantsearch'
 export * from './bridges/vue'
-export * from './bridges/react'
+export * from './bridges/react'
+export * from './bridges/searchkit'
+export * from './bridges/searchkit-server'
+export * from './utils/health'

package/app/composables/module.ts

@@ -65,8 +65,49 @@ export default defineAlternateModule({
       ctx.searchManager = new SearchManager<MeeoviSearchItem>(adapter)
     }
 
+    // Ensure search manager exists now if adapter already registered
+    if (!ctx.searchManager && ctx.getAdapter('search')) {
+      const runtimeAdapter = ctx.getAdapter('search') as
+        | SearchAdapter<MeeoviSearchItem>
+        | undefined
+      if (runtimeAdapter) {
+        ctx.searchManager = new SearchManager<MeeoviSearchItem>(runtimeAdapter)
+      }
+    }
+
+    // Listen for app readiness and for runtime adapter registrations so
+    // new adapters (registered by other modules) will auto-create the
+    // search manager when they become available.
     bus.on('app:ready', () => {
+      if (!ctx.searchManager) {
+        const runtimeAdapter = ctx.getAdapter('search') as
+          | SearchAdapter<MeeoviSearchItem>
+          | undefined
+        if (runtimeAdapter) {
+          ctx.searchManager = new SearchManager<MeeoviSearchItem>(runtimeAdapter)
+        }
+      }
       console.info('[@meeovi/search] Search module initialized')
     })
+
+    // Optional runtime event: if other modules emit `adapter:registered`
+    // with a `{ key }` payload, respond and initialize when the `search`
+    // adapter becomes available.
+    // This is defensive — the core registry does not emit this by default,
+    // but some runtimes may choose to.
+    bus.on('adapter:registered' as any, (payload: any) => {
+      try {
+        if (payload?.key === 'search' && !ctx.searchManager) {
+          const runtimeAdapter = ctx.getAdapter('search') as
+            | SearchAdapter<MeeoviSearchItem>
+            | undefined
+          if (runtimeAdapter) {
+            ctx.searchManager = new SearchManager<MeeoviSearchItem>(runtimeAdapter)
+          }
+        }
+      } catch (e) {
+        /* noop */
+      }
+    })
   }
 })

package/app/composables/utils/health.ts

@@ -0,0 +1,13 @@
+import type { SearchAdapter } from '@meeovi/core'
+
+export async function checkAdapterHealth(adapter: SearchAdapter<any>) {
+  try {
+    // perform a minimal search to verify connectivity
+    const res = await adapter.search({ term: '', page: 1, pageSize: 1, filters: {} } as any)
+    return { ok: true, total: res?.total ?? null }
+  } catch (e: any) {
+    return { ok: false, error: e?.message || String(e) }
+  }
+}
+
+export default checkAdapterHealth

package/app/plugins/search.js

@@ -1,5 +1,5 @@
 import { defineNuxtPlugin } from '#imports'
-import { getSearchClient, getIndexName } from 'searchkit'
+import { getSearchClient, getIndexName } from '../utils/search/client'
 
 export default defineNuxtPlugin((nuxtApp) => {
   let searchClient

package/app/utils/search/client.ts

@@ -0,0 +1,40 @@
+// Lightweight helper to obtain a search client and index name for InstantSearch
+// This is intentionally minimal — it throws when no configuration is present
+// so the caller can fall back gracefully.
+import type { SearchClient } from 'instantsearch.js'
+
+export function getIndexName(): string {
+  return (
+    process.env.NUXT_PUBLIC_SEARCH_INDEX ||
+    process.env.SEARCH_INDEX ||
+    'default'
+  )
+}
+
+export function getSearchClient(): SearchClient {
+  const host = process.env.NUXT_PUBLIC_SEARCHKIT_HOST || process.env.SEARCHKIT_HOST
+  if (!host) {
+    throw new Error('Searchkit host not configured via SEARCHKIT_HOST or NUXT_PUBLIC_SEARCHKIT_HOST')
+  }
+
+  // Defer importing heavy searchkit/instantsearch client until runtime.
+  // Consumers can replace this implementation with a provider-specific client.
+  // Here we attempt to use @searchkit/instantsearch-client if available.
+  // If not present, let the import fail so the plugin can fallback.
+  // The actual creation API differs between versions; adjust as needed.
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const createClient = require('@searchkit/instantsearch-client')
+  if (!createClient) {
+    throw new Error('@searchkit/instantsearch-client is not installed')
+  }
+
+  // Create a minimal client. The factory API may vary; this is a best-effort
+  // placeholder that should be adapted to your Searchkit configuration.
+  // If your Searchkit installation exposes a helper, prefer using that.
+  try {
+    return createClient({ host })
+  } catch (e: any) {
+    // rethrow with context
+    throw new Error('Failed to create Searchkit client: ' + (e?.message || e))
+  }
+}

package/dist/app/composables/adapter/meilisearch.d.ts

@@ -0,0 +1,8 @@
+import { type SearchAdapterConfig } from '@meeovi/core';
+interface MeiliConfig extends SearchAdapterConfig {
+    host: string;
+    apiKey?: string;
+    index: string;
+}
+export declare function createMeilisearchAdapter(config: MeiliConfig): import("@meeovi/core").AlternateAdapter<SearchAdapterConfig>;
+export {};

package/dist/app/composables/adapter/meilisearch.js

@@ -0,0 +1,36 @@
+import { defineAlternateAdapter } from '@meeovi/core';
+export function createMeilisearchAdapter(config) {
+    const headers = {
+        'Content-Type': 'application/json'
+    };
+    if (config.apiKey) {
+        headers['Authorization'] = `Bearer ${config.apiKey}`;
+    }
+    const adapter = {
+        id: 'search:meilisearch',
+        type: 'search',
+        config,
+        async search(query) {
+            const params = new URLSearchParams({
+                q: query.term,
+                offset: String((query.page - 1) * query.pageSize),
+                limit: String(query.pageSize)
+            });
+            const res = await fetch(`${config.host}/indexes/${config.index}/search?${params}`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    filter: Object.entries(query.filters).map(([field, value]) => `${field} = ${value}`)
+                })
+            });
+            const json = await res.json();
+            return {
+                items: json.hits,
+                total: json.estimatedTotalHits ?? json.hits.length,
+                page: query.page,
+                pageSize: query.pageSize
+            };
+        }
+    };
+    return defineAlternateAdapter(adapter);
+}

package/dist/app/composables/adapter/mock.d.ts

@@ -0,0 +1,3 @@
+import { type SearchAdapterConfig } from '@meeovi/core';
+import type { MeeoviSearchItem } from './types';
+export declare function createMockSearchAdapter(items?: MeeoviSearchItem[]): import("@meeovi/core").AlternateAdapter<SearchAdapterConfig>;

package/dist/app/composables/adapter/mock.js

@@ -0,0 +1,19 @@
+import { defineAlternateAdapter } from '@meeovi/core';
+export function createMockSearchAdapter(items = []) {
+    const cfg = { provider: 'mock' };
+    const adapter = {
+        id: 'search:mock',
+        type: 'search',
+        config: cfg,
+        async search(query) {
+            const filtered = items.filter((item) => item.title.toLowerCase().includes(query.term.toLowerCase()));
+            return {
+                items: filtered,
+                total: filtered.length,
+                page: 1,
+                pageSize: filtered.length
+            };
+        }
+    };
+    return defineAlternateAdapter(adapter);
+}

package/dist/app/composables/adapter/opensearch.d.ts

@@ -0,0 +1,8 @@
+import { type SearchAdapterConfig } from '@meeovi/core';
+interface OpenSearchConfig extends SearchAdapterConfig {
+    endpoint: string;
+    index: string;
+    apiKey?: string;
+}
+export declare function createOpenSearchAdapter(config: OpenSearchConfig): import("@meeovi/core").AlternateAdapter<SearchAdapterConfig>;
+export {};

package/dist/app/composables/adapter/opensearch.js

@@ -0,0 +1,46 @@
+import { defineAlternateAdapter } from '@meeovi/core';
+import { normalizeOpenSearchHit } from '../utils/normalizers';
+export function createOpenSearchAdapter(config) {
+    const adapter = {
+        id: 'search:opensearch',
+        type: 'search',
+        config,
+        async search(query) {
+            const body = {
+                query: {
+                    bool: {
+                        must: [
+                            {
+                                multi_match: {
+                                    query: query.term,
+                                    fields: ['title^3', 'description', 'tags']
+                                }
+                            }
+                        ],
+                        filter: Object.entries(query.filters).map(([field, value]) => ({
+                            term: { [field]: value }
+                        }))
+                    }
+                },
+                from: (query.page - 1) * query.pageSize,
+                size: query.pageSize
+            };
+            const res = await fetch(`${config.endpoint}/${config.index}/_search`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {})
+                },
+                body: JSON.stringify(body)
+            });
+            const json = await res.json();
+            return {
+                items: json.hits.hits.map(normalizeOpenSearchHit),
+                total: json.hits.total.value,
+                page: query.page,
+                pageSize: query.pageSize
+            };
+        }
+    };
+    return defineAlternateAdapter(adapter);
+}

package/dist/app/composables/adapter/types.d.ts

@@ -0,0 +1,12 @@
+import type { SearchAdapter, SearchResult } from '@meeovi/core';
+import type { BuiltSearchQuery } from '../core/QueryBuilder';
+export interface MeeoviSearchItem {
+    id: string;
+    title: string;
+    description?: string;
+    price?: number;
+    [key: string]: unknown;
+}
+export type MeeoviSearchAdapter = SearchAdapter<MeeoviSearchItem> & {
+    search(query: BuiltSearchQuery): Promise<SearchResult<MeeoviSearchItem>>;
+};

package/dist/app/composables/adapter/types.js

@@ -0,0 +1 @@
+export {};

package/dist/app/composables/bridges/instantsearch.d.ts

@@ -0,0 +1,4 @@
+import type { SearchManager } from '../core/SearchManager';
+export declare function createInstantSearchBridge(manager: SearchManager): {
+    searchFunction(helper: any): Promise<void>;
+};

package/dist/app/composables/bridges/instantsearch.js

@@ -0,0 +1,17 @@
+export function createInstantSearchBridge(manager) {
+    return {
+        searchFunction(helper) {
+            manager.context.setQuery(helper.state.query || '');
+            manager.context.setPage(helper.state.page || 1);
+            // map filters if needed from helper.state
+            return manager.search().then((result) => {
+                helper.setResults({
+                    hits: result.items,
+                    nbHits: result.total,
+                    page: result.page - 1,
+                    hitsPerPage: result.pageSize
+                });
+            });
+        }
+    };
+}

package/dist/app/composables/bridges/react.d.ts

@@ -0,0 +1,12 @@
+export declare function useReactSearch(): {
+    query: string;
+    setQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    page: number;
+    setPage: import("react").Dispatch<import("react").SetStateAction<number>>;
+    pageSize: number;
+    setPageSize: import("react").Dispatch<import("react").SetStateAction<number>>;
+    results: any[];
+    total: number;
+    loading: boolean;
+    search: () => Promise<void>;
+};

package/dist/app/composables/bridges/react.js

@@ -0,0 +1,34 @@
+import { useState, useCallback } from 'react';
+import { useAlternateContext } from '@meeovi/core';
+export function useReactSearch() {
+    const ctx = useAlternateContext();
+    const manager = ctx.searchManager;
+    const [query, setQuery] = useState(manager.context.state.query);
+    const [page, setPage] = useState(manager.context.state.page);
+    const [pageSize, setPageSize] = useState(manager.context.state.pageSize);
+    const [results, setResults] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [loading, setLoading] = useState(false);
+    const search = useCallback(async () => {
+        setLoading(true);
+        manager.context.setQuery(query);
+        manager.context.setPage(page);
+        manager.context.setPageSize(pageSize);
+        const res = await manager.search();
+        setResults(res.items);
+        setTotal(res.total);
+        setLoading(false);
+    }, [query, page, pageSize, manager]);
+    return {
+        query,
+        setQuery,
+        page,
+        setPage,
+        pageSize,
+        setPageSize,
+        results,
+        total,
+        loading,
+        search
+    };
+}

package/dist/app/composables/bridges/vue.d.ts

@@ -0,0 +1,9 @@
+export declare function useSearch(): {
+    query: import("vue").Ref<string, string>;
+    page: import("vue").Ref<number, number>;
+    pageSize: import("vue").Ref<number, number>;
+    results: import("vue").ComputedRef<any[]>;
+    total: import("vue").ComputedRef<number>;
+    loading: import("vue").ComputedRef<boolean>;
+    search: () => Promise<void>;
+};

package/dist/app/composables/bridges/vue.js

@@ -0,0 +1,31 @@
+import { ref, computed } from 'vue';
+import { useAlternateContext } from '@meeovi/core';
+export function useSearch() {
+    const ctx = useAlternateContext();
+    const manager = ctx.searchManager;
+    const query = ref(manager.context.state.query);
+    const page = ref(manager.context.state.page);
+    const pageSize = ref(manager.context.state.pageSize);
+    const results = ref([]);
+    const total = ref(0);
+    const loading = ref(false);
+    async function run() {
+        loading.value = true;
+        manager.context.setQuery(query.value);
+        manager.context.setPage(page.value);
+        manager.context.setPageSize(pageSize.value);
+        const res = await manager.search();
+        results.value = res.items;
+        total.value = res.total;
+        loading.value = false;
+    }
+    return {
+        query,
+        page,
+        pageSize,
+        results: computed(() => results.value),
+        total: computed(() => total.value),
+        loading: computed(() => loading.value),
+        search: run
+    };
+}

package/dist/app/composables/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/app/composables/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAlternateApp } from '@meeovi/core';
+import searchModule from './module';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function run() {
+    const [, , command, arg] = process.argv;
+    const defaultProvider = process.env.SEARCH_PROVIDER === 'meilisearch' ? 'meilisearch' : 'opensearch';
+    const app = createAlternateApp({
+        config: {
+            env: 'production',
+            search: {
+                defaultProvider,
+                providers: {
+                    opensearch: {
+                        endpoint: process.env.OPENSEARCH_ENDPOINT,
+                        index: process.env.OPENSEARCH_INDEX
+                    },
+                    meilisearch: {
+                        host: process.env.MEILI_HOST,
+                        index: process.env.MEILI_INDEX,
+                        apiKey: process.env.MEILI_KEY
+                    }
+                }
+            }
+        },
+        modules: [searchModule]
+    });
+    const ctx = await app.start();
+    const search = ctx.getAdapter('search');
+    if (!search) {
+        console.error('No search adapter registered');
+        process.exit(1);
+    }
+    if (command === 'warmup') {
+        console.log('Warming up search provider...');
+        await search.search({ term: 'warmup' });
+        console.log('Warmup complete');
+        return;
+    }
+    if (command === 'index') {
+        if (!arg) {
+            console.error('Missing file path: meeovi-search index <file.json>');
+            process.exit(1);
+        }
+        const filePath = path.resolve(process.cwd(), arg);
+        const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        console.log(`Indexing ${data.length} items...`);
+        if (search.id === 'search:opensearch') {
+            // TODO: implement bulk indexing
+        }
+        if (search.id === 'search:meilisearch') {
+            await fetch(`${process.env.MEILI_HOST}/indexes/${process.env.MEILI_INDEX}/documents`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${process.env.MEILI_KEY}`
+                },
+                body: JSON.stringify(data)
+            });
+        }
+        console.log('Indexing complete');
+        return;
+    }
+    console.log(`Unknown command: ${command}`);
+}
+run();