dawg-search 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnluckyNinja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# DAWG Search
+[![npm version][npm-version-src]][npm-href]
+[![npm downloads][npm-downloads-src]][npm-href]
+[![Unit Test][unit-test-src]][unit-test-href]
+[![License][license-src]][license-href]
+
+## Description
+- It aims at solving a string searching problem: how to find **many** words in **one** text.
+- It's designed to work with non-English languages like Chinese and Japanese.
+- It's based on two well-studied data strucutres: Trie Automaton and Suffix Automaton
+- If multiple words overlaps, words shown first or longer take precedence,
+
+## Install
+
+```bash
+npm i dawg-search
+```
+
+## Usage
+
+```js
+import { prepareSearch, refineMatches } from 'dawg-search'
+
+const text = '举头望明月，低头思故乡'
+const words = ['明月', '故乡', '月，低']
+
+const { findWords } = prepareSearch(words)
+const results = refineMatches(findWords(text))
+
+// [{start: 3, end: 5}, {start: 9, end: 11}]
+
+```
+
+## How it works
+1. Trie Automaton  
+First you need to prepare a dictionary of words.
+It will be processed into a trie, which merged not only the prefixes but also the suffixes.  
+Historically it's called *Deterministic Acyclic Finite State Automaton* (DAFSA).
+(A regular trie will work, but considering many words have common suffix, it could save a lot of memory).
+
+2. Suffix Automaton 
+When searching text, the text is processed into a suffix automaton. The trie automaton can be reused.
+
+3. Traversing Phase  
+Then, from root node of the suffix automaton, it will traverse every transition,
+which implicitly will traverse all substrings.  
+It runs in two pass,  
+`findWords` return results in unordered list,  
+`refineMatches` will sort and eliminate overlaps.
+
+## Limitations
+- This lib can only process concrete words, not regex.
+- For the two data structures, a long chain of single transitions could be compressed into one transition, achieving more compact forms. 
+
+## License
+[MIT](./LICENSE) License © 2026 [UnluckyNinja](https://github.com/UnluckyNinja)
+
+[npm-version-src]: https://img.shields.io/npm/v/dawg-search?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-src]: https://img.shields.io/npm/dm/dawg-search?style=flat&colorA=080f12&colorB=1fa669
+[npm-href]: https://npmjs.com/package/dawg-search
+[unit-test-src]: https://github.com/UnluckyNinja/dawg-search/actions/workflows/unit-test.yml/badge.svg
+[unit-test-href]: https://github.com/UnluckyNinja/dawg-search/actions/workflows/unit-test.yml
+[license-src]: https://img.shields.io/github/license/UnluckyNinja/dawg-search.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/UnluckyNinja/dawg-search/blob/main/LICENSE

package/dist/index.d.mts

@@ -0,0 +1,106 @@
+//#region src/utils.d.ts
+declare function binarySearch<T>(arr: T[], target: T, cmp: (a: T, b: T) => number, start?: number, end?: number): number;
+interface DGraphNode {
+  id: number;
+  out: [string, this][];
+}
+declare function nodeGetNext<T extends DGraphNode>(node: T, char: string): T | undefined;
+/**
+ * only works for single char link
+ * @param next if undefined, delete edge
+ */
+declare function nodeSetOutEdge<T extends DGraphNode>(node: T, char: string, next?: T): void;
+declare function compareNodeOut(a: [string, unknown], b: [string, unknown]): number;
+//#endregion
+//#region src/trie.d.ts
+interface TrieNode extends DGraphNode {
+  final: boolean;
+  inDegree: number;
+}
+declare class TrieAutomaton {
+  private _root;
+  get root(): TrieNode;
+  private _states;
+  get states(): TrieNode[];
+  private nodePool;
+  private register;
+  constructor(words?: string[]);
+  private init;
+  refill(words: string[]): void;
+  /**
+   * MARK: Internal funcs
+   */
+  private addNode;
+  private cloneNode;
+  private removeFromRegister;
+  /**
+   * Will register child
+   */
+  private replaceOrRegister;
+  /**
+   * @returns false if the parameter is not presented in states, true otherwise.
+   */
+  private deleteNode;
+  /**
+   * Giving a word, from root node follow transition of each character:
+   * - if there is a transition to a child node
+   *   - if child and all parent nodes have only one in-edge
+   *     - push it to an array and remove it from merge-able list, if it's in.
+   *       (to avoid a chain of transitions megring with itself,
+   *       where there might be a shorter word happening to be the prefix of it
+   *       and ends with the same char)
+   *   - if child node or any parent have more than one in-edge
+   *     - clone child node (excluding all in-edges), separate current transition from old one
+   *       and reroute to cloned node.
+   * - if there isn't one transtion of that character
+   *   - if it's removing, break and do nothing
+   *   - if adding, create new node
+   * After done:
+   * - if removing, and didn't early break, mark last node as NOT final
+   * - if adding, mark last node as final
+   * Then try merging (and retracting for removing)
+   */
+  private processWord;
+  /**
+   * MARK: API
+   */
+  addWord(word: string): void;
+  removeWord(word: string): void;
+}
+//#endregion
+//#region src/suffix.d.ts
+interface SuffixNode extends DGraphNode {
+  id: number;
+  len: number;
+  link: this | null;
+  out: [string, this][];
+}
+/**
+ * Reference: https://oi-wiki.org/string/sam/
+ */
+declare class SuffixAutomaton {
+  private _root;
+  get root(): SuffixNode;
+  private _last;
+  get last(): SuffixNode;
+  private _states;
+  get states(): SuffixNode[];
+  constructor(text: string);
+  private addNode;
+  private cloneNode;
+  extend(char: string): void;
+  getFinals(): Set<number>;
+}
+//#endregion
+//#region src/index.d.ts
+interface Result {
+  start: number;
+  end: number;
+}
+declare function prepareSearch(words: string[]): {
+  findWords: (text: string) => Result[];
+};
+declare function findWords(text: string, trie: TrieAutomaton): Result[];
+declare function refineMatches(result: Result[], inPlace?: boolean): Result[];
+//#endregion
+export { DGraphNode, SuffixAutomaton, SuffixNode, TrieAutomaton, TrieNode, binarySearch, compareNodeOut, findWords, nodeGetNext, nodeSetOutEdge, prepareSearch, refineMatches };

package/dist/index.mjs

@@ -0,0 +1,323 @@
+import SplayTree from "splaytree";
+function binarySearch(arr, target, cmp, start = 0, end = arr.length - 1) {
+	while (start <= end) {
+		let mid = Math.floor((start + end) / 2);
+		let result = cmp(arr[mid], target);
+		if (result === 0) return mid;
+		else if (result > 0) end = mid - 1;
+		else start = mid + 1;
+	}
+	return start;
+}
+function nodeGetNext(node, char) {
+	const idx = binarySearch(node.out, [char, void 0], compareNodeOut);
+	if (node.out[idx]?.[0] === char) return node.out[idx][1];
+	else return;
+}
+function nodeSetOutEdge(node, char, next) {
+	const idx = binarySearch(node.out, [char, void 0], compareNodeOut);
+	let replace = false;
+	if (node.out[idx]?.[0] === char) replace = true;
+	if (replace) if (!next) node.out.splice(idx, 1);
+	else node.out.splice(idx, 1, [char, next]);
+	else if (!next) return;
+	else node.out.splice(idx, 0, [char, next]);
+}
+function compareNodeOut(a, b) {
+	return a[0].localeCompare(b[0]);
+}
+var SuffixAutomaton = class {
+	_root;
+	get root() {
+		return this._root;
+	}
+	_last;
+	get last() {
+		return this._last;
+	}
+	_states = [];
+	get states() {
+		return this._states;
+	}
+	constructor(text) {
+		this._root = this.addNode();
+		this._last = this._root;
+		for (const char of text) this.extend(char);
+	}
+	addNode() {
+		const node = {
+			id: this.states.length,
+			len: 0,
+			link: null,
+			out: []
+		};
+		this.states.push(node);
+		return node;
+	}
+	cloneNode(node) {
+		const clone = this.addNode();
+		clone.len = node.len;
+		clone.link = node.link;
+		clone.out = [...node.out];
+		return clone;
+	}
+	extend(char) {
+		const cur = this.addNode();
+		cur.len = this._last.len + 1;
+		let p = this._last;
+		while (p && nodeGetNext(p, char) === void 0) {
+			nodeSetOutEdge(p, char, cur);
+			p = p.link;
+		}
+		if (!p) cur.link = this._root;
+		else {
+			let q = nodeGetNext(p, char);
+			if (q === void 0) throw new Error(`p:${p.id}->${char} is undefined}`);
+			if (p.len + 1 === q.len) cur.link = q;
+			else {
+				const clone = this.cloneNode(q);
+				clone.len = p.len + 1;
+				while (p && nodeGetNext(p, char) === q) {
+					nodeSetOutEdge(p, char, clone);
+					p = p.link;
+				}
+				q.link = cur.link = clone;
+			}
+		}
+		this._last = cur;
+	}
+	getFinals() {
+		const map = /* @__PURE__ */ new Set();
+		let node = this._last;
+		while (node.link) {
+			map.add(node.id);
+			node = node.link;
+		}
+		return map;
+	}
+};
+var TrieAutomaton = class {
+	_root;
+	get root() {
+		return this._root;
+	}
+	_states = [];
+	get states() {
+		return this._states;
+	}
+	nodePool = [];
+	register;
+	constructor(words) {
+		this.refill(words ?? []);
+	}
+	init() {
+		this._states.length = 0;
+		this.nodePool.length = 0;
+		this._root = this.addNode();
+		this.register = new SplayTree(compareNode);
+	}
+	refill(words) {
+		this.init();
+		for (let i = 0; i < words.length; ++i) this.addWord(words[i]);
+	}
+	addNode() {
+		let node;
+		if (this.nodePool.length > 0) {
+			node = this.nodePool.pop();
+			node.id = this._states.length;
+			node.final = false;
+			node.inDegree = 0;
+			node.out = [];
+			this._states.push(node);
+		} else {
+			node = {
+				id: this._states.length,
+				final: false,
+				inDegree: 0,
+				out: []
+			};
+			this._states.push(node);
+		}
+		return node;
+	}
+	cloneNode(node) {
+		const clone = this.addNode();
+		clone.final = node.final;
+		clone.inDegree = 0;
+		clone.out = node.out.map((it) => it.slice());
+		for (let i = 0; i < clone.out.length; ++i) ++clone.out[i][1].inDegree;
+		return clone;
+	}
+	removeFromRegister(node) {
+		this.register.remove(node);
+	}
+	replaceOrRegister(state, char) {
+		const child = nodeGetNext(state, char);
+		if (!child) throw new Error(`State doesn't have a transition of "${char}"`);
+		if (child.inDegree > 1) throw new Error(`There are more than one transition to the child by "${char}"`);
+		const node = this.register.find(child);
+		if (node) {
+			const found = node.key;
+			setTrieTransition(state, char, found);
+			this.deleteNode(child, false);
+			return found;
+		} else {
+			this.register.add(child);
+			return child;
+		}
+	}
+	deleteNode(node, alsoRegister) {
+		const id = node.id;
+		if (!this._states[id] || this._states[id] !== node) return false;
+		for (let i = 0; i < node.out.length; ++i) --node.out[i][1].inDegree;
+		if (alsoRegister) this.removeFromRegister(node);
+		this.nodePool.push(node);
+		const lastID = this.states.length - 1;
+		const swapnode = this._states[lastID];
+		this._states[id] = swapnode;
+		swapnode.id = id;
+		this._states.length = lastID;
+		return true;
+	}
+	processWord(word, remove) {
+		let lastNode = this._root;
+		const chain = [lastNode];
+		let i = 0;
+		let shouldClone = false;
+		for (; i < word.length; ++i) {
+			const char = word.charAt(i);
+			const child = nodeGetNext(lastNode, char);
+			if (child) {
+				if (child.inDegree > 1) shouldClone = true;
+				if (shouldClone) {
+					const cloned = this.cloneNode(child);
+					setTrieTransition(lastNode, char, cloned);
+					lastNode = cloned;
+				} else {
+					this.removeFromRegister(child);
+					lastNode = child;
+				}
+			} else if (remove) break;
+			else {
+				const newNode = this.addNode();
+				setTrieTransition(lastNode, char, newNode);
+				lastNode = newNode;
+			}
+			chain.push(lastNode);
+		}
+		if (remove) {
+			if (i === word.length) lastNode.final = false;
+		} else lastNode.final = true;
+		for (let i = chain.length - 2; i >= 0; --i) this.replaceOrRegister(chain[i], word.charAt(i));
+	}
+	addWord(word) {
+		this.processWord(word, false);
+	}
+	removeWord(word) {
+		this.processWord(word, true);
+	}
+};
+function compareNode(a, b) {
+	if (a === b) return 0;
+	let diff = (a.final ? 1 : 0) - (b.final ? 1 : 0);
+	if (diff !== 0) return diff;
+	diff = a.out.length - b.out.length;
+	if (diff !== 0) return diff;
+	for (let i = 0; i < a.out.length; ++i) {
+		const [charA, nodeA] = a.out[i];
+		const [charB, nodeB] = b.out[i];
+		diff = charA.localeCompare(charB);
+		if (diff !== 0) return diff;
+		return compareNode(nodeA, nodeB);
+	}
+	return 0;
+}
+function setTrieTransition(node, char, next) {
+	const idx = binarySearch(node.out, [char, void 0], compareNodeOut);
+	const found = node.out[idx]?.[0] === char;
+	const oldNext = found ? node.out[idx]?.[1] : void 0;
+	if (oldNext === next) return;
+	if (found) if (next) node.out.splice(idx, 1, [char, next]);
+	else node.out.splice(idx, 1);
+	else if (next) node.out.splice(idx, 0, [char, next]);
+	if (oldNext) --oldNext.inDegree;
+	if (next) ++next.inDegree;
+}
+function prepareSearch(words) {
+	const trie = new TrieAutomaton(words);
+	function _findWords(text) {
+		return findWords(text, trie);
+	}
+	return { findWords: _findWords };
+}
+function findWords(text, trie) {
+	const sam = new SuffixAutomaton(text);
+	const finals = sam.getFinals();
+	const result = [];
+	const queue = [{
+		matchedLength: 0,
+		matchingLength: 0,
+		final: false,
+		samNode: sam.root,
+		trieNode: trie.root
+	}];
+	function pushToQueue(oldState, options = {}) {
+		const { matched = false, matching = true, final = false, nextSAM = null, nextTrie = null } = options;
+		queue.push({
+			matchedLength: matched ? oldState.matchingLength + 1 : oldState.matchedLength,
+			matchingLength: matching ? oldState.matchingLength + 1 : oldState.matchingLength,
+			final,
+			samNode: nextSAM,
+			trieNode: nextTrie
+		});
+	}
+	outter: while (queue.length > 0) {
+		const state = queue.pop();
+		if (finals.has(state.samNode.id)) {
+			if (state.matchedLength > 0) result.push({
+				start: text.length - state.matchingLength,
+				end: text.length - state.matchingLength + state.matchedLength
+			});
+		}
+		if (!state.trieNode) {
+			for (const [_, nextSAM] of state.samNode.out) pushToQueue(state, { nextSAM });
+			continue outter;
+		}
+		for (const [char, nextSAM] of state.samNode.out) {
+			const nextTrie = nodeGetNext(state.trieNode, char);
+			if (!nextTrie) {
+				if (state.matchedLength === 0) continue;
+				pushToQueue(state, {
+					nextTrie: null,
+					nextSAM
+				});
+				continue;
+			}
+			if (nextTrie.final) pushToQueue(state, {
+				matched: true,
+				nextTrie,
+				nextSAM
+			});
+			else pushToQueue(state, {
+				nextTrie,
+				nextSAM
+			});
+		}
+	}
+	return result;
+}
+function refineMatches(result, inPlace = true) {
+	let outputArray = result;
+	if (!inPlace) outputArray = result.slice();
+	if (outputArray.length <= 1) return outputArray;
+	outputArray.sort((a, b) => {
+		if (a.start !== b.start) return b.start - a.start;
+		return a.end - b.end;
+	});
+	for (let i = outputArray.length - 1; i >= 1; --i) {
+		const cur = outputArray[i];
+		if (outputArray[i - 1].start < cur.end) outputArray.splice(i - 1, 1);
+	}
+	return outputArray.reverse();
+}
+export { SuffixAutomaton, TrieAutomaton, binarySearch, compareNodeOut, findWords, nodeGetNext, nodeSetOutEdge, prepareSearch, refineMatches };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dawg-search",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "search multiple word in text, by leveraging two types of automaton",
+  "author": "UnluckyNinja <unluckyninja4ever@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/UnluckyNinja/dawg-search#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UnluckyNinja/dawg-search.git"
+  },
+  "bugs": {
+    "url": "https://github.com/UnluckyNinja/dawg-search/issues"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./*"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --env.DEV=true",
+    "dev:playground": "pnpm -r --include-workspace-root --parallel run dev",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "bumpp": "^10.4.1",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "splaytree": "^3.2.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "npm:rolldown-vite@^7.3.1"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org"
+  }
+}