@geenius/search

Full-text search, autocomplete, filters, command-surface primitives, and provider-backed indexing helpers for Geenius products.

Installation

pnpm add @geenius/search

Framework bindings and provider stores are exposed through subpath exports. Install the framework you use:

pnpm add react react-dom
# or
pnpm add solid-js

Subpath Imports

import {
  buildExcerpt,
  buildSearchSeoMeta,
  configureSearch,
  defaultSearchConfig,
  deduplicate,
  getCompositeSearchScore,
  getHighlightSegments,
  getSearchConfig,
  getSearchCategoryLabel,
  getSearchEntityTypePriority,
  getSearchProvider,
  getSearchRecencyBoost,
  getSearchTagLabel,
  getSearchTypeLabel,
  highlightMatches,
  InternalSearchProvider,
  pluralizeSearch,
  parseSearchQuery,
  querySearchIndex,
  rankResults,
  scoreSearchIndexDocument,
  streamSearchResults,
  translateSearch,
  setSearchConfig,
  setSearchProvider,
} from '@geenius/search'

import { schema, search, getSuggestions } from '@geenius/search/convex'
import { createMemorySearchStore } from '@geenius/search/memory'
import { createCloudflareKVSearchStore } from '@geenius/search/cloudflareKV'
import { createNeonSearchStore, runSearchMigrations } from '@geenius/search/neon'

import {
  CommandPalettePage,
  SearchBar,
  SearchCommandMenu,
  SearchInputTrigger,
  SearchPage,
  SearchProvider,
  useSearch,
  useSearchMenu,
} from '@geenius/search/react'

import {
  SearchBar as SearchBarCss,
  SearchCommandMenu as SearchCommandMenuCss,
  SearchInputTrigger as SearchInputTriggerCss,
  SearchPage as SearchPageCss,
  SearchProvider as SearchProviderCss,
} from '@geenius/search/react-css'
import '@geenius/search/react-css/styles.css'

import {
  CommandPalette,
  SearchBar as SolidSearchBar,
  SearchCommandMenu as SolidSearchCommandMenu,
  SearchPage as SolidSearchPage,
  SearchProvider as SolidSearchProvider,
  createSearch,
  useSearchMenu as useSolidSearchMenu,
} from '@geenius/search/solidjs'

import {
  CommandPalette as SolidCssCommandPalette,
  SearchBar as SolidCssSearchBar,
  SearchCommandMenu as SolidCssSearchCommandMenu,
  SearchPage as SolidCssSearchPage,
  SearchProvider as SolidCssSearchProvider,
} from '@geenius/search/solidjs-css'
import '@geenius/search/solidjs-css/styles.css'

import type {
  HighlightSegment,
  SearchConfig,
  SearchFilters,
  SearchIndex,
  SearchQuery,
  SearchProviderAdapter,
  SearchRequest,
  SearchResponse,
  SearchResultStream,
  SearchStreamChunk,
  SearchResult,
} from '@geenius/search'

Shared framework-agnostic helpers, types, and errors are re-exported from the root @geenius/search. The package does not expose a /shared subpath; do not import from @geenius/search/shared (it is private workspace plumbing).

Usage

import { configureSearch } from '@geenius/search'
import { createMemorySearchStore } from '@geenius/search/memory'
import {
  SearchBar,
  SearchCommandMenu,
  SearchProvider,
  SearchResults,
} from '@geenius/search/react'

const provider = createMemorySearchStore()
const config = configureSearch({ provider: 'memory', maxResults: 20 })

export function DocsSearch(): React.JSX.Element {
  return (
    <SearchProvider provider={provider} config={config}>
      <div className="flex flex-col gap-4">
        <SearchBar
          query=""
          onChange={() => undefined}
          onClear={() => undefined}
          placeholder="Search docs, guides, and APIs..."
        />
        <SearchResults
          results={[]}
          query=""
          isLoading={false}
          onSelect={() => undefined}
        />
        <SearchCommandMenu />
      </div>
    </SearchProvider>
  )
}

Cmd/Ctrl+K command palette

The React/Solid variants ship a global command palette wired through SearchProvider. The default shortcut is Cmd/Ctrl+K; arrow keys, Enter, Esc, Tab, and @/#// prefixes are all keyboard-routed by the shared core.

import { configureSearch } from '@geenius/search'
import {
  CommandPalettePage,
  SearchInputTrigger,
  SearchProvider,
} from '@geenius/search/react'

const config = configureSearch({ provider: 'memory', shortcutKey: 'k' })

export function GlobalSearch() {
  return (
    <SearchProvider config={config}>
      <SearchInputTrigger />
      <CommandPalettePage />
    </SearchProvider>
  )
}

Backends (launch axis)

| Backend | Subpath | At-launch | Notes | | --- | --- | --- | --- | | convex | @geenius/search/convex | yes (current dist) | Reactive indexed search, history, suggestions, analytics | | neon | @geenius/search/neon | yes (current dist) | Postgres-compatible store with append-only migrations and write-through indexing hooks | | cloudflareKV | @geenius/search/cloudflareKV | yes (current dist) | Edge KV store with key-prefix isolation, TTL support, and key/value-only semantics | | memory | @geenius/search/memory | yes (current dist) | Deterministic in-process store for tests, Storybook fixtures, and offline demos |

Algolia, Typesense, Meilisearch, Supabase, and MongoDB are post-launch adapter integrations and are not included in V1.

Variants

• @geenius/search: shared contract, search utilities, config helpers, and errors.
• @geenius/search/convex: Convex schema, queries, and mutations for indexed search data.
• @geenius/search/neon: Neon/Postgres-compatible migrations and provider factory.
• @geenius/search/cloudflareKV: Cloudflare KV-compatible provider factory and memory KV test namespace.
• @geenius/search/memory: deterministic in-process provider with indexing, history, and analytics helpers.
• @geenius/search/react: Tailwind-oriented React UI bindings.
• @geenius/search/react-css: standalone React UI bindings with shipped vanilla CSS at @geenius/search/react-css/styles.css.
• @geenius/search/solidjs: Tailwind-oriented SolidJS UI bindings.
• @geenius/search/solidjs-css: standalone SolidJS UI bindings with shipped vanilla CSS at @geenius/search/solidjs-css/styles.css.

CSS variants ship static stylesheets and do not re-export the Tailwind implementations. The current in-scope UI variants use local accessible React/Solid primitives and Geenius token conventions. Library-backed @geenius/ui variants remain deferred with the broader UI library set. getHighlightSegments() returns start/end character offsets for every segment, and highlightMatches() carries those offsets on generated mark elements while preserving HTML escaping. Providers can expose incremental results through streamSearch(); streamSearchResults() gives UIs one async-iterable contract and falls back to a single final search() response when streaming is not available. Ranking helpers include bounded entity-priority and recency boosts through getCompositeSearchScore(), getSearchEntityTypePriority(), and getSearchRecencyBoost(). parseSearchQuery() returns normalized terms and filters plus token metadata and expanded entity/tag/action/type arrays for provider-side query planning. Provider packages share the canonical matcher through querySearchIndex() and scoreSearchIndexDocument(), which cover exact, prefix, fuzzy, acronym, entity-priority, and recency ranking consistently across launch providers.

Storybook

The package ships stock Storybook v10 review apps built on the @geenius/storybook preset. Run pnpm test:storybook:build to build available in-scope apps from variants.json, and pnpm test:storybook to run the Storybook test-runner against the built static output.

Storybook review app sources:

• React review app
• React CSS review app
• SolidJS review app
• SolidJS CSS review app

Testing

The package test matrix is driven by variants.json. Run the PR-blocking gauntlet with:

pnpm test:gauntlet

Useful focused commands:

• pnpm lint, pnpm lint:apps, pnpm lint:pub
• pnpm type-check
• pnpm test:conventions
• pnpm test:unit, pnpm test:exports, pnpm test:types, pnpm test:packed-smoke
• pnpm test:e2e, pnpm test:a11y, pnpm test:visual
• pnpm test:coverage, pnpm coverage:diff
• pnpm test:mutation, pnpm size, pnpm audit:supply-chain, pnpm test:license, pnpm sbom
• pnpm test:all for the full gauntlet, DB conformance, e2e, a11y, visual, perf, coverage, and Storybook stack

Update visual snapshots with:

pnpm test:visual -- --update-snapshots

Contributing Tests

Add new variants in one place first: variants.json. Out-of-scope variants stay marked with inScope: false and are not scaffolded in this run. After an in-scope package source exists under packages/<variant>/, root scripts and Playwright projects discover it from that file. Add or update the variant's Storybook app, public-subpath e2e harness coverage, unit tests, and bundle budget in the same change.

License

Free Software License for the free tier. See LICENSE.