Orama

Orama is a TypeScript search engine and RAG pipeline that runs anywhere JavaScript runs — the browser, Node.js, Deno, Bun, or the edge — with zero runtime dependencies at under 2kb gzipped for its core. It indexes documents in memory using custom radix trees, AVL trees, and flat/vector indexes, giving you full-text search with typo tolerance and BM25 ranking, vector search over embeddings, and hybrid search that blends both, all through the same small API surface.

Beyond retrieval, Orama ships an AnswerSession API for building ChatGPT-style RAG chat experiences directly on top of your indexed data, plus an official plugin system (embeddings generation, secure OpenAI proxying, analytics, data persistence, and framework-specific docs-search integrations for Astro, Docusaurus, VitePress, and Nextra). It supports 30 languages via pluggable stemmers and tokenizers, geosearch, facets, result pinning for merchandising, and field boosting, making it a serious alternative to hosted search services for teams that want search logic to live in their own process instead of a third-party API.

What You Get

• A create/insert/search core API that indexes documents into radix trees (strings), AVL trees (numbers), flat indexes (booleans/enums), and dedicated vector indexes for embeddings
• Full-text search with typo tolerance, BM25 relevance scoring, field boosting, facets, and geosearch out of the box
• Vector and hybrid search modes for combining semantic embedding similarity with keyword relevance in a single query
• An AnswerSession API for building RAG-style chat/answer experiences directly over your indexed documents
• A first-party plugin ecosystem: embeddings generation, a secure OpenAI proxy, analytics, data persistence/serialization, and doc-site integrations for Astro, Docusaurus, VitePress, and Nextra
• Built-in stemming and tokenization for 30 languages, plus support for custom tokenizers and stemmers

Common Use Cases

• Adding instant, typo-tolerant full-text search to a docs site, blog, or e-commerce catalog without standing up Elasticsearch or Algolia
• Building a RAG-powered chat assistant that answers questions grounded in your own content using AnswerSession
• Combining keyword and vector search (hybrid mode) to improve relevance for semantic queries like product descriptions or support articles
• Running search entirely client-side in the browser or on edge functions where spinning up a separate search server isn’t practical
• Powering search for static-site generators and documentation frameworks via the official Astro/Docusaurus/VitePress/Nextra plugins

Under The Hood

Architecture: Orama’s create() (src/methods/create.ts) wires together a set of pluggable “components” — a DocumentsStore, an Index, a Sorter, a tokenizer, and pinning manager — each independently swappable via the components option, with sensible defaults supplied by validateComponents. Search dispatch (src/methods/search.ts) routes to search-fulltext.ts, search-vector.ts, or search-hybrid.ts depending on the requested mode, all operating over the shared Index abstraction (src/components/index.ts, ~1,070 lines) that internally delegates to specialized tree structures in src/trees/ — a radix tree (radix.ts) for string tokens, an AVL tree (avl.ts) for numeric range queries, a flat index (flat.ts) for booleans/enums, a BKD tree (bkd.ts) for geopoints, and a dedicated vector.ts index for embedding similarity. A hook system (components/hooks.ts) and plugin registry (components/plugins.ts) let plugins intercept lifecycle events like afterCreate, which is how the official embeddings/secure-proxy/analytics plugins attach behavior without forking core.

Tech Stack: Written entirely in TypeScript (97.8% of the codebase) with zero runtime dependencies for the core @orama/orama package. The monorepo is managed with pnpm workspaces and Turborepo, built via tshy to emit dual CJS/ESM output plus dedicated browser and deno export conditions, and uses @swc/core for fast dev-mode transpilation. Companion workspace packages (@orama/stemmers, @orama/stopwords, @orama/tokenizers) supply language data, keeping the core package’s own dependency footprint at zero.

Code Quality: The core package has 19 dedicated test files under packages/orama/tests/ (create, insert, remove, upsert, search, search-vector, search.geo, filters, sort, group, distinct, languages, diacritics, levenshtein, tree.zip, plugin-embeddings, and more) totaling roughly 445 test cases, run with tap and measured for coverage via c8 in both local and CI configurations. Errors are centralized in a single errors.ts module with ~40 named, parameterized error codes (e.g. INVALID_SEARCH_MODE, UNKNOWN_VECTOR_PROPERTY) rather than ad hoc thrown strings, which keeps failure messages consistent and greppable. Type coverage is exhaustive — types.ts alone is over 1,400 lines — and the project runs a separate test:types step using tsd to assert the public type surface against fixtures, catching type regressions that unit tests would miss.

API Design: The public API is intentionally minimal and functional rather than class-based — create, insert, search, remove, update, save/load — so getting from zero to a working search index takes only a schema object and a few function calls, as shown in the README’s first example. Search mode (fulltext | vector | hybrid) is a single parameter on the same search() call rather than a different API, which keeps the mental model small even as capabilities grow. The tradeoff is a fairly large types.ts surface (schemas are generic over document shape, index type, document-store type, sorter type, and pinning type), which gives strong compile-time guarantees but means TypeScript users occasionally need to read type errors carefully; plain JavaScript users are unaffected and get a much simpler experience.