What Querylight TS Covers

Querylight TS is a pure TypeScript search toolkit for browsers and Node.js. It is positioned as the most feature-rich local search library for static sites and browser apps. It combines text retrieval, structured boolean queries, multi-field search, phrase search, prefix expansion, aggregations, dense vector search, sparse vector search, geo search, and portable index state under one API. For a direct comparison with narrower browser-first libraries, see Comparing Querylight TS to Other Browser Search Libraries.

In practical terms, that means you can use one local library to power very different kinds of search experiences:

• a docs search box with highlighting and BM25 ranking
• a dense vector search mode for semantic retrieval and related-content features
• a sparse vector search mode for learned token-weight retrieval
• faceted or filtered discovery over structured metadata
• “Ask the Docs” style semantic search over chunked content
• related-article or recommendation features using vector similarity
• geo-aware retrieval for map or region-based content

That breadth matters when you want one local index model for search, filters, facets, vectors, and geo features instead of stitching those behaviors together from separate tools.

If you are new to search tooling, the easiest mental model is:

• A DocumentIndex stores your documents.
• Each TextFieldIndex indexes one field such as title, body, or tags.
• A JSON request describes what you want to match.
• searchJsonDsl(...) returns an OpenSearch-style response with hits, highlight, and aggregations.

Why it is broader than a fuzzy-only library

• It indexes structured fields instead of only flat strings.
• It supports both TF-IDF and BM25 ranking.
• It exposes BoolQuery with should, must, filter, mustNot, and minimumShouldMatch.
• It includes dedicated PrefixQuery, TermsQuery, ExistsQuery, and MultiMatchQuery building blocks.
• It supports terms aggregations and significant terms for discovery.
• It includes VectorFieldIndex, SparseVectorFieldIndex, and GeoFieldIndex for non-lexical retrieval.

Common problems it can solve

If you are evaluating fit, use this matrix instead of guessing from the API names.

Minimal setup

import { DocumentIndex, searchJsonDsl, TextFieldIndex } from "@tryformation/querylight-ts";

const index = new DocumentIndex({
  title: new TextFieldIndex(),
  body: new TextFieldIndex()
});

index.index({
  id: "intro",
  fields: {
    title: ["Querylight TS"],
    body: ["Portable search for browser and Node.js"]
  }
});

const response = await searchJsonDsl({
  index,
  request: {
    query: { match_all: {} },
    size: 10
  }
});

Expected result:

response.hits.hits[0];
// {
//   _id: "intro",
//   _score: 1,
//   _source: {
//     title: ["Querylight TS"],
//     body: ["Portable search for browser and Node.js"]
//   }
// }

That score is mainly useful for ordering. The important part is that each hit already carries the document id and source payload in an OpenSearch-style envelope.

What the result ids are for

Search returns ids first, not your full source objects. That keeps the index compact and lets you decide how to store and render your actual documents.

Typical pattern:

const sourceDocuments = new Map([
  ["intro", { title: "Querylight TS", url: "/docs/intro" }]
]);

const results = response.hits.hits.map((hit) => ({
  ...sourceDocuments.get(hit._id),
  score: hit._score
}));

Expected result:

[
  {
    title: "Querylight TS",
    url: "/docs/intro",
    score: 1
  }
]

Common next steps

• Add more fields such as summary, tags, or api.
• Replace match_all with match, match_phrase, bool, or vector clauses.
• Use aggregations to build facets from the current result set.
• Add dense vectors for semantic search or related-content features.
• Add sparse vectors when your model emits learned token weights.
• Serialize the index at build time and load it in the browser.

More guides

• Choosing a Schema for Search
• OpenSearch-Style Search Requests
• Analyzer and Tokenization Deep Dive
• How To Build Autocomplete
• How To Build Faceted Navigation
• Relevance Tuning with BM25, TF-IDF, and RRF
• Document Chunking Strategies
• Serialization, Hydration, and Shipping Indexes
• Performance and Memory Tuning
• Testing Search Behavior
• Real-World Recipes
• Other Work Related to Querylight TS
• Comparing Querylight TS to Other Browser Search Libraries

Learn more

• Information retrieval on Wikipedia
• Okapi BM25 on Wikipedia