@nixxie-cms/search 1.0.1

package/src/InMemorySearch.ts

@@ -0,0 +1,101 @@
+import type {
+  NixxieSearchDocument,
+  NixxieSearchQuery,
+  NixxieSearchResults,
+  NixxieSearchService,
+} from '@nixxie-cms/core'
+
+/**
+ * Zero-dependency in-memory search. Tokenises stringified document values and ranks by the
+ * number of query terms matched. Intended for development, tests and small datasets — swap in a
+ * real engine (Meilisearch/Typesense/Algolia/Elasticsearch) for production.
+ */
+export class InMemorySearch implements NixxieSearchService {
+  private indexes = new Map<string, Map<string, NixxieSearchDocument>>()
+
+  private indexFor(name: string): Map<string, NixxieSearchDocument> {
+    let idx = this.indexes.get(name)
+    if (!idx) {
+      idx = new Map()
+      this.indexes.set(name, idx)
+    }
+    return idx
+  }
+
+  async index(
+    indexName: string,
+    documents: NixxieSearchDocument | NixxieSearchDocument[]
+  ): Promise<void> {
+    const idx = this.indexFor(indexName)
+    for (const doc of Array.isArray(documents) ? documents : [documents]) {
+      if (!doc.id) throw new Error('Search documents must have an `id`')
+      idx.set(doc.id, doc)
+    }
+  }
+
+  async remove(indexName: string, id: string): Promise<void> {
+    this.indexes.get(indexName)?.delete(id)
+  }
+
+  async search<T = NixxieSearchDocument>(
+    indexName: string,
+    query: NixxieSearchQuery
+  ): Promise<NixxieSearchResults<T>> {
+    const start = Date.now()
+    const idx = this.indexes.get(indexName)
+    const terms = query.q.toLowerCase().split(/\s+/).filter(Boolean)
+    const matched: { document: NixxieSearchDocument; score: number }[] = []
+
+    for (const doc of idx?.values() ?? []) {
+      if (query.filter && !this.matchesFilter(doc, query.filter)) continue
+      const haystack = JSON.stringify(doc).toLowerCase()
+      const score = terms.length === 0 ? 1 : terms.filter(t => haystack.includes(t)).length
+      if (terms.length === 0 || score > 0) matched.push({ document: doc, score })
+    }
+
+    matched.sort((a, b) => b.score - a.score)
+    if (query.sort?.length) this.applySort(matched, query.sort)
+
+    const offset = query.offset ?? 0
+    const limit = query.limit ?? 20
+    const page = matched.slice(offset, offset + limit)
+
+    return {
+      hits: page.map(m => ({ document: m.document as T, score: m.score })),
+      total: matched.length,
+      tookMs: Date.now() - start,
+    }
+  }
+
+  async clear(indexName: string): Promise<void> {
+    this.indexes.get(indexName)?.clear()
+  }
+
+  async close(): Promise<void> {
+    this.indexes.clear()
+  }
+
+  private matchesFilter(
+    doc: NixxieSearchDocument,
+    filter: Record<string, string | number | boolean>
+  ): boolean {
+    return Object.entries(filter).every(([k, v]) => (doc as any)[k] === v)
+  }
+
+  private applySort(
+    items: { document: NixxieSearchDocument; score: number }[],
+    sort: string[]
+  ): void {
+    items.sort((a, b) => {
+      for (const spec of sort) {
+        const [attr, dir = 'asc'] = spec.split(':')
+        const av = (a.document as any)[attr]
+        const bv = (b.document as any)[attr]
+        if (av === bv) continue
+        const cmp = av > bv ? 1 : -1
+        return dir === 'desc' ? -cmp : cmp
+      }
+      return 0
+    })
+  }
+}

package/src/MeilisearchSearch.ts

@@ -0,0 +1,72 @@
+import type {
+  NixxieSearchDocument,
+  NixxieSearchQuery,
+  NixxieSearchResults,
+  NixxieSearchService,
+} from '@nixxie-cms/core'
+import type { MeilisearchConfig } from './types'
+
+/** Meilisearch backend over the REST API (no SDK dependency). */
+export class MeilisearchSearch implements NixxieSearchService {
+  private base: string
+  private apiKey?: string
+
+  constructor(config: MeilisearchConfig) {
+    this.base = config.url.replace(/\/$/, '')
+    this.apiKey = config.apiKey
+  }
+
+  private async request(path: string, method: string, body?: unknown): Promise<any> {
+    const res = await fetch(`${this.base}${path}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    if (!res.ok && res.status !== 404) {
+      throw new Error(`Meilisearch request failed (${res.status}): ${await res.text()}`)
+    }
+    return res.status === 404 ? undefined : res.json()
+  }
+
+  async index(
+    indexName: string,
+    documents: NixxieSearchDocument | NixxieSearchDocument[]
+  ): Promise<void> {
+    const docs = Array.isArray(documents) ? documents : [documents]
+    await this.request(`/indexes/${indexName}/documents`, 'POST', docs)
+  }
+
+  async remove(indexName: string, id: string): Promise<void> {
+    await this.request(`/indexes/${indexName}/documents/${encodeURIComponent(id)}`, 'DELETE')
+  }
+
+  async search<T = NixxieSearchDocument>(
+    indexName: string,
+    query: NixxieSearchQuery
+  ): Promise<NixxieSearchResults<T>> {
+    const filter = query.filter
+      ? Object.entries(query.filter).map(([k, v]) => `${k} = ${JSON.stringify(v)}`)
+      : undefined
+    const res = await this.request(`/indexes/${indexName}/search`, 'POST', {
+      q: query.q,
+      limit: query.limit ?? 20,
+      offset: query.offset ?? 0,
+      filter,
+      sort: query.sort,
+    })
+    return {
+      hits: (res?.hits ?? []).map((document: T) => ({ document })),
+      total: res?.estimatedTotalHits ?? res?.hits?.length ?? 0,
+      tookMs: res?.processingTimeMs,
+    }
+  }
+
+  async clear(indexName: string): Promise<void> {
+    await this.request(`/indexes/${indexName}/documents`, 'DELETE')
+  }
+
+  async close(): Promise<void> {}
+}

package/src/TypesenseSearch.ts

@@ -0,0 +1,98 @@
+import type {
+  NixxieSearchDocument,
+  NixxieSearchQuery,
+  NixxieSearchResults,
+  NixxieSearchService,
+} from '@nixxie-cms/core'
+import type { TypesenseConfig } from './types'
+
+/**
+ * Typesense backend over the REST API (no SDK dependency).
+ * Collections must already exist; documents are upserted. Typesense has no wildcard `query_by`,
+ * so configure `queryBy` to match your collection's searchable fields.
+ * Note: `clear()` drops the entire collection (Typesense has no schema-preserving truncate),
+ * so recreate the collection before re-indexing.
+ */
+export class TypesenseSearch implements NixxieSearchService {
+  private base: string
+  private apiKey: string
+  private queryBy: string
+
+  constructor(config: TypesenseConfig) {
+    const protocol = config.protocol ?? 'http'
+    const port = config.port ?? 8108
+    this.base = `${protocol}://${config.host}:${port}`
+    this.apiKey = config.apiKey
+    this.queryBy = config.queryBy ?? 'title,name,body,content'
+  }
+
+  private headers(): Record<string, string> {
+    return { 'Content-Type': 'application/json', 'X-TYPESENSE-API-KEY': this.apiKey }
+  }
+
+  async index(
+    indexName: string,
+    documents: NixxieSearchDocument | NixxieSearchDocument[]
+  ): Promise<void> {
+    const docs = Array.isArray(documents) ? documents : [documents]
+    const body = docs.map(d => JSON.stringify(d)).join('\n')
+    const res = await fetch(
+      `${this.base}/collections/${indexName}/documents/import?action=upsert`,
+      { method: 'POST', headers: this.headers(), body }
+    )
+    if (!res.ok) throw new Error(`Typesense import failed (${res.status}): ${await res.text()}`)
+  }
+
+  async remove(indexName: string, id: string): Promise<void> {
+    await fetch(`${this.base}/collections/${indexName}/documents/${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+      headers: this.headers(),
+    })
+  }
+
+  async search<T = NixxieSearchDocument>(
+    indexName: string,
+    query: NixxieSearchQuery
+  ): Promise<NixxieSearchResults<T>> {
+    // Use Typesense's `offset`/`limit` params (supported since v0.23) rather than `page`/`per_page`,
+    // so arbitrary, non-page-aligned offsets return the correct window.
+    const params = new URLSearchParams({
+      q: query.q,
+      query_by: this.queryBy,
+      limit: String(query.limit ?? 20),
+      offset: String(query.offset ?? 0),
+    })
+    if (query.filter) {
+      params.set(
+        'filter_by',
+        Object.entries(query.filter)
+          .map(([k, v]) => `${k}:=${JSON.stringify(v)}`)
+          .join(' && ')
+      )
+    }
+    if (query.sort?.length) params.set('sort_by', query.sort.join(','))
+    const res = await fetch(`${this.base}/collections/${indexName}/documents/search?${params}`, {
+      headers: this.headers(),
+    })
+    if (!res.ok) throw new Error(`Typesense search failed (${res.status}): ${await res.text()}`)
+    const data = await res.json()
+    return {
+      hits: (data.hits ?? []).map((h: any) => ({ document: h.document as T, score: h.text_match })),
+      total: data.found ?? 0,
+      tookMs: data.search_time_ms,
+    }
+  }
+
+  async clear(indexName: string): Promise<void> {
+    const res = await fetch(`${this.base}/collections/${indexName}`, {
+      method: 'DELETE',
+      headers: this.headers(),
+    })
+    // A missing collection (404) is already "cleared"; anything else is a real failure.
+    if (!res.ok && res.status !== 404) {
+      throw new Error(`Typesense clear failed (${res.status}): ${await res.text()}`)
+    }
+  }
+
+  async close(): Promise<void> {}
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+import type { SearchConfig } from './types'
+import { AlgoliaSearch } from './AlgoliaSearch'
+import { ElasticsearchSearch } from './ElasticsearchSearch'
+import { InMemorySearch } from './InMemorySearch'
+import { MeilisearchSearch } from './MeilisearchSearch'
+import { TypesenseSearch } from './TypesenseSearch'
+
+export function createSearch(
+  config: SearchConfig
+): InMemorySearch | MeilisearchSearch | TypesenseSearch | AlgoliaSearch | ElasticsearchSearch {
+  switch (config.driver) {
+    case 'memory':
+      return new InMemorySearch()
+    case 'meilisearch':
+      return new MeilisearchSearch(config)
+    case 'typesense':
+      return new TypesenseSearch(config)
+    case 'algolia':
+      return new AlgoliaSearch(config)
+    case 'elasticsearch':
+      return new ElasticsearchSearch(config)
+    default: {
+      const exhaustive: never = config
+      throw new Error(`Unknown search driver: ${(exhaustive as any).driver}`)
+    }
+  }
+}
+
+export { InMemorySearch, MeilisearchSearch, TypesenseSearch, AlgoliaSearch, ElasticsearchSearch }
+export type {
+  SearchConfig,
+  InMemorySearchConfig,
+  MeilisearchConfig,
+  TypesenseConfig,
+  AlgoliaConfig,
+  ElasticsearchConfig,
+} from './types'
+export type {
+  NixxieSearchService,
+  NixxieSearchDocument,
+  NixxieSearchQuery,
+  NixxieSearchHit,
+  NixxieSearchResults,
+} from '@nixxie-cms/core'

package/src/types.ts

@@ -0,0 +1,71 @@
+import type {
+  NixxieSearchDocument,
+  NixxieSearchHit,
+  NixxieSearchQuery,
+  NixxieSearchResults,
+  NixxieSearchService,
+} from '@nixxie-cms/core'
+
+export type {
+  NixxieSearchDocument,
+  NixxieSearchHit,
+  NixxieSearchQuery,
+  NixxieSearchResults,
+  NixxieSearchService,
+}
+
+export type InMemorySearchConfig = {
+  driver: 'memory'
+}
+
+export type MeilisearchConfig = {
+  driver: 'meilisearch'
+  /** Meilisearch host URL, e.g. http://localhost:7700 */
+  url: string
+  /** API key (master or scoped). */
+  apiKey?: string
+}
+
+export type TypesenseConfig = {
+  driver: 'typesense'
+  /** Host (without protocol), e.g. localhost */
+  host: string
+  /** Port. Default: 8108 */
+  port?: number
+  /** 'http' or 'https'. Default: 'http' */
+  protocol?: 'http' | 'https'
+  /** API key. */
+  apiKey: string
+  /**
+   * Comma-separated fields Typesense should search against (it has no wildcard query_by).
+   * Default: 'title,name,body,content'
+   */
+  queryBy?: string
+}
+
+export type AlgoliaConfig = {
+  driver: 'algolia'
+  /** Algolia application id. */
+  appId: string
+  /** Admin API key (write access). */
+  apiKey: string
+}
+
+export type ElasticsearchConfig = {
+  driver: 'elasticsearch'
+  /** Node URL, e.g. http://localhost:9200 */
+  node: string
+  /** Optional API key for auth. */
+  apiKey?: string
+  /** Optional basic-auth username. */
+  username?: string
+  /** Optional basic-auth password. */
+  password?: string
+}
+
+export type SearchConfig =
+  | InMemorySearchConfig
+  | MeilisearchConfig
+  | TypesenseConfig
+  | AlgoliaConfig
+  | ElasticsearchConfig