@stll/text-search

@stll/text-search

Multi-engine text search orchestrator for Node.js and Bun. It classifies each pattern once, routes literals to Aho-Corasick, regex to RegexSet, fuzzy entries to FuzzySearch, and merges the results into one stable match stream.

Part of the @stll text search ecosystem: @stll/regex-set, @stll/aho-corasick, @stll/fuzzy-search.

Install

Node.js / Bun:

npm install @stll/text-search
# or
bun add @stll/text-search

@stll/text-search ships the engine packages as regular dependencies. You do not install them separately unless you want to use the lower-level engine APIs directly.

Browser / WebAssembly:

npm install @stll/text-search-wasm
# or
bun add @stll/text-search-wasm

Vite

@stll/text-search-wasm depends on the browser variants of the Stella engines. Import the bundled Vite plugin so those WASM loaders stay out of pre-bundling and keep their relative asset paths.

import stllTextSearchWasm from "@stll/text-search-wasm/vite";

export default {
  plugins: [stllTextSearchWasm()],
};

Usage

import { TextSearch } from "@stll/text-search";

const search = new TextSearch([
  "Confidential",
  "Attorney-Client Privilege",
  /\b\d{2}\.\d{2}\.\d{4}\b/,
  /\b[\w.+-]+@[\w-]+\.[\w]+\b/,
  { pattern: "Novák", distance: 1, name: "person" },
  { pattern: "s.r.o.", literal: true, name: "company-type" },
]);

const matches = search.findIter(
  "Ing. Jan Novak, s.r.o., born 15.03.1990.",
);

Routing model

Patterns are classified once at construction time.

Engine	Used for
Aho-Corasick	Pure literals and explicit literal: true entries
RegexSet	Standard regex patterns
FuzzySearch	Entries with a distance field

Large alternation-heavy regexes are isolated into their own RegexSet instance so they do not poison the shared DFA for simpler patterns.

Options

new TextSearch(patterns, {
  unicodeBoundaries: true,
  wholeWords: false,
  maxAlternations: 50,
  fuzzyMetric: "levenshtein",
  normalizeDiacritics: false,
  caseInsensitive: false,
  overlapStrategy: "longest",
  allLiteral: false,
});

API

Method	Returns	Description
findIter(text)	Match[]	Find matches in input text
isMatch(text)	boolean	Fast yes/no check
whichMatch(text)	number[]	Pattern indices that matched
replaceAll(text, replacements)	string	Replace matched ranges
length	number	Number of configured patterns

Pattern entry types

"literal"
/\bregex\b/i
{ pattern: "\\d+", name: "number" }
{ pattern: "Novák", distance: 1, name: "person" }
{ pattern: "s.r.o.", literal: true, wholeWords: true }

Match shape

type Match = {
  pattern: number;
  start: number;
  end: number;
  text: string;
  name?: string;
  distance?: number;
};

The Match shape is aligned with the other Stella text-search packages.

Development

bun install
bun test
bun run lint
bun run format
bun run build

Built on

• @stll/aho-corasick
• @stll/regex-set
• @stll/fuzzy-search

License

MIT