@arraypress/search 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@arraypress/search` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-11-05
+
+### Added
+
+- **`createSearch`**: ranked in-memory search. It has field weights, list fields of search phrases with an exact-match score, and synonym groups, with a phrase of up to three words read as one. It folds English plurals and drops stop words. What is typed matches at the start of a word, and synonyms match as whole words. It has exact filters (values, list contains, all of several, or a function), facets, and stable tie-breaks (fields with a value first, or a comparison, then record order).
+- **`pack` / `unpack`**: a compact JSON index, built once and loaded in the browser. Records go in as columns, with repeated strings in tables.
+- **`@arraypress/search/rules`**: `scoreRule` (word patterns, points per value, vetoes) and `assign`. `assign` handles caps per record and per group, hand picks, and a review of drops, adds and keeps.
+- A golden corpus of 1,118 Logomarks queries, each returning the same ordered results as the site's own search before it moved here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArrayPress Limited
+
+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

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @arraypress/search
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ranked in-memory search with synonyms and facets. Field weights, synonym phrases (up to three words read as one), plural folding, word-start matching for what is typed and whole-word matching for synonyms, exact filters, stable tie-breaks, and a compact prebuilt index you build once and load in the browser. Plus rule-based tagging: weighted word rules with caps, hand picks and a review.
+
+No dependencies. Runs in the browser and in Node. About 2.2 KB minified and gzipped; the rules are 1.1 KB more.
+
+## Install
+
+```bash
+npm install @arraypress/search
+```
+
+## Quick start
+
+```js
+import { createSearch } from '@arraypress/search';
+
+const marks = [
+  { slug: 'scales', name: 'Pixel Scales', keywords: ['law', 'justice'], description: 'Balance scales.' },
+  { slug: 'house', name: 'House Line', keywords: ['estate agent', 'home'], description: 'A gabled house.' },
+];
+
+const board = createSearch(marks, {
+  fields: { name: 4, keywords: { weight: 2.5, exact: 4, list: true }, description: 1 },
+  synonyms: [['lawyer', 'solicitor', 'attorney', 'law'], ['realtor', 'estate agent', 'real estate']],
+  tie: ['keywords'],
+});
+
+board.search('solicitor').hits;      // [{ item: { slug: 'scales', … }, index: 0, score: 4 }]
+board.search('estate agents').hits;  // one phrase, plural folded: the house
+board.search('ho').hits;             // what was typed matches at the start of a word
+```
+
+Build the index once, at build time, and load it anywhere:
+
+```js
+import { pack, unpack } from '@arraypress/search';
+
+const json = JSON.stringify(pack(marks, options));   // records as columns, repeated strings in tables
+const board = unpack(JSON.parse(json));                // the same search, in the browser
+```
+
+Tag records by rules (`@arraypress/search/rules`):
+
+```js
+import { assign, scoreRule } from '@arraypress/search/rules';
+
+const rules = {
+  law: { words: [[/\b(scales|gavel)\b/, 3], [/\bbalance\b/, 2]] },
+  property: { words: [[/\b(house|key)\b/, 3]], not: /\bmouse\b/ },
+};
+const { byRecord } = assign(marks, Object.keys(rules), {
+  key: (m) => m.slug,
+  score: (m, group) => scoreRule(rules[group], `${m.name} ${m.description}`.toLowerCase(), m),
+  min: 3, perRecord: 4, perGroup: 60,
+});
+// { house: ['property'], scales: ['law'] }
+```
+
+## Docs
+
+- [How search reads, matches and ranks](https://github.com/arraypress/search/blob/main/docs/matching.md)
+- [API](https://github.com/arraypress/search/blob/main/docs/api.md): every export and option
+- [The packed index](https://github.com/arraypress/search/blob/main/docs/packed-index.md)
+- [Rules](https://github.com/arraypress/search/blob/main/docs/rules.md): scoring and assigning records to groups
+- [Changelog](https://github.com/arraypress/search/blob/main/CHANGELOG.md)
+
+## Licence
+
+MIT © ArrayPress Limited; author David Sherlock.

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@arraypress/search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Ranked in-memory search with synonyms and facets: field weights, synonym phrases, plural folding, word-start and whole-word matching, exact filters, stable tie-breaks and a compact prebuilt JSON index. Plus rule-based tagging (weighted word rules, caps, picks and a review). No dependencies; browser and Node.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./rules": {
+      "types": "./src/rules/index.d.ts",
+      "import": "./src/rules/index.js",
+      "default": "./src/rules/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "search",
+    "search-engine",
+    "synonyms",
+    "ranking",
+    "faceted-search",
+    "filter",
+    "facets",
+    "plural",
+    "tagging",
+    "rules"
+  ],
+  "author": "David Sherlock",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arraypress/search.git"
+  },
+  "homepage": "https://www.npmjs.com/package/@arraypress/search",
+  "bugs": "https://github.com/arraypress/search/issues",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^6.0.3"
+  }
+}

package/src/filter/facets.d.ts

@@ -0,0 +1,2 @@
+/** Each field's values across the records with how many have each, most first, then alphabetically. */
+export function facets<K extends string>(records: Iterable<Partial<Record<K, unknown>>>, fields: readonly K[]): Record<K, Record<string, number>>;

package/src/filter/facets.js

@@ -0,0 +1,28 @@
+/**
+ * @module @arraypress/search/filter/facets
+ *
+ * Facets: the values fields take across records, with how many records have
+ * each, most first.
+ */
+
+/**
+ * Counts each field's values across the records (each item of a list field).
+ * Empty and absent values aren't counted. Each field's values come most first,
+ * then alphabetically.
+ *
+ * @param {Iterable<Record<string, unknown>>} records The records.
+ * @param {readonly string[]} fields The fields to count.
+ * @returns {Record<string, Record<string, number>>} Per field, each value and its count.
+ */
+export function facets(records, fields) {
+	/** @type {Map<string, number>[]} */
+	const counts = fields.map(() => new Map());
+	for (const r of records)
+		fields.forEach((k, i) => {
+			for (const v of Array.isArray(r[k]) ? r[k] : [r[k]])
+				if (v != null && v !== '') counts[i].set(String(v), (counts[i].get(String(v)) ?? 0) + 1);
+		});
+	return Object.fromEntries(
+		fields.map((k, i) => [k, Object.fromEntries([...counts[i]].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])))]),
+	);
+}

package/src/filter/filter.d.ts

@@ -0,0 +1,8 @@
+/** A value a field must have; a list means every one of them. */
+export type FilterValue = string | number | boolean | readonly (string | number | boolean)[] | undefined;
+
+/** Field values a record must have (a list field: contain), or a test of its own. Empty or undefined values are ignored. */
+export type Filter<T> = { readonly [field: string]: FilterValue } | ((record: T, index: number) => boolean);
+
+/** A filter as a test. */
+export function filterOf<T>(filter?: Filter<T>): (record: T, index: number) => boolean;

package/src/filter/filter.js

@@ -0,0 +1,33 @@
+/**
+ * @module @arraypress/search/filter/filter
+ *
+ * Exact filters: a record passes when each named field has the value asked
+ * for (a list field: contains it). Several values for one field must all be
+ * there. A function filter is used as it is.
+ */
+
+/**
+ * Whether a record's field has a value: it equals it, or is a list holding it.
+ *
+ * @param {unknown} have The field's value.
+ * @param {unknown} want The value asked for.
+ * @returns {boolean} Whether it has it.
+ */
+const has = (have, want) => have === want || (Array.isArray(have) && have.includes(want));
+
+/**
+ * A filter as a test.
+ *
+ * @template T
+ * @param {import('./filter.js').Filter<T>} [filter] Field values to require, or a test of its own.
+ * @returns {(record: T, index: number) => boolean} The test.
+ */
+export function filterOf(filter) {
+	if (typeof filter === 'function') return filter;
+	const wants = Object.entries(filter ?? {}).filter(([, v]) => v !== undefined && v !== '');
+	return (record) =>
+		wants.every(([k, v]) => {
+			const have = /** @type {Record<string, unknown>} */ (record)[k];
+			return Array.isArray(v) ? v.every((w) => has(have, w)) : has(have, v);
+		});
+}

package/src/filter/tie.d.ts

@@ -0,0 +1,5 @@
+/** How ties are broken: fields whose records with a value go first (in order), or a comparison. Record order comes last. */
+export type Tie<T> = readonly string[] | ((a: T, b: T) => number);
+
+/** The tie option as a comparison (0 when there is nothing to break ties by). */
+export function tieOf<T>(tie?: Tie<T>): (a: T, b: T) => number;

package/src/filter/tie.js

@@ -0,0 +1,29 @@
+/**
+ * @module @arraypress/search/filter/tie
+ *
+ * Tie-breakers between records with the same score. Records keep their own
+ * order last, so a search's order never changes from one run to the next.
+ */
+
+import { filled } from '../util/values.js';
+
+/**
+ * The tie option as a comparison: a list of fields puts records that have a
+ * value in the first of them before those that don't, then the next field; a
+ * function is used as it is.
+ *
+ * @template T
+ * @param {import('./tie.js').Tie<T>} [tie] The fields, or a comparison.
+ * @returns {(a: T, b: T) => number} The comparison (0 when there is nothing to break ties by).
+ */
+export function tieOf(tie) {
+	if (typeof tie === 'function') return tie;
+	const fields = tie ?? [];
+	return (a, b) => {
+		for (const k of fields) {
+			const d = Number(filled(/** @type {Record<string, unknown>} */ (b)[k])) - Number(filled(/** @type {Record<string, unknown>} */ (a)[k]));
+			if (d) return d;
+		}
+		return 0;
+	};
+}

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export type { Field, Fields, SearchOptions, SearchQuery, Hit, Result, Search } from './search.js';
+export { createSearch } from './search.js';
+export type { Packed } from './pack/index.js';
+export { pack, unpack, PACK_VERSION } from './pack/index.js';
+export { facets } from './filter/facets.js';
+export type { Filter, FilterValue } from './filter/filter.js';
+export { filterOf } from './filter/filter.js';
+export type { Tie } from './filter/tie.js';
+export type { Term, TermOptions } from './query/terms.js';
+export { termsOf, synonymMap } from './query/terms.js';
+export { singular } from './query/plural.js';

package/src/index.js

@@ -0,0 +1,15 @@
+/**
+ * @module @arraypress/search
+ *
+ * Ranked in-memory search with synonyms and facets: field weights, synonym
+ * phrases, plural folding, word-start and whole-word matching, exact filters,
+ * stable ties, and a compact prebuilt index. No dependencies; runs in the
+ * browser and in Node. Rule-based tagging is `@arraypress/search/rules`.
+ */
+
+export { createSearch } from './search.js';
+export { pack, unpack, PACK_VERSION } from './pack/index.js';
+export { facets } from './filter/facets.js';
+export { filterOf } from './filter/filter.js';
+export { termsOf, synonymMap } from './query/terms.js';
+export { singular } from './query/plural.js';

package/src/match/fields.d.ts

@@ -0,0 +1,15 @@
+import type { Fields } from '../search.js';
+
+/** One field, ready to match against. */
+export interface FieldPlan {
+	key: string;
+	/** A phrase found in it as a whole word. */
+	weight: number;
+	/** A phrase that is one of a list field's items exactly (0: no bonus). */
+	exact: number;
+	/** Its items are separate phrases, each matched on its own. */
+	list: boolean;
+}
+
+/** The fields option as a plan, in order. */
+export function planOf(fields: Fields): FieldPlan[];

package/src/match/fields.js

@@ -0,0 +1,20 @@
+/**
+ * @module @arraypress/search/match/fields
+ *
+ * The fields option read into a plan: which record fields make a record's
+ * text, in order, and what a match in each is worth.
+ */
+
+/**
+ * The fields option as a plan. A number is a field's weight; an object can
+ * also make it a list of phrases (`list`) with a score for a phrase that is
+ * one of them exactly (`exact`).
+ *
+ * @param {import('../search.js').Fields} fields The fields option.
+ * @returns {import('./fields.js').FieldPlan[]} One entry per field, in order.
+ */
+export const planOf = (fields) =>
+	Object.entries(fields).map(([key, f]) => {
+		const { weight = 0, exact = 0, list = false } = typeof f === 'number' ? { weight: f } : f;
+		return { key, weight, exact, list };
+	});

package/src/match/record.d.ts

@@ -0,0 +1,12 @@
+import type { FieldPlan } from './fields.js';
+
+/** A record prepared for matching. */
+export interface Prepared {
+	/** Every field, in order, joined and lower case: what a term must be found in. */
+	text: string;
+	/** Each field's text, lower case: a list field as its phrases. */
+	texts: Record<string, string | string[]>;
+}
+
+/** A record prepared for matching: its whole text and each field's text. */
+export function prepare(record: Record<string, unknown>, plan: readonly FieldPlan[]): Prepared;

package/src/match/record.js

@@ -0,0 +1,44 @@
+/**
+ * @module @arraypress/search/match/record
+ *
+ * A record prepared for matching: its whole text (every field, in order, lower
+ * case) and each ranked field's text.
+ */
+
+import { listOf } from '../util/values.js';
+
+/**
+ * A value as text: a string as it is, a number written out, anything else ''.
+ *
+ * @param {unknown} v The value.
+ * @returns {string} The text.
+ */
+const textOf = (v) => (typeof v === 'string' ? v : typeof v === 'number' ? String(v) : '');
+
+/**
+ * A record prepared for matching. Its text joins every field with spaces: a
+ * string as it is, a list's items one by one, and a list field's phrases
+ * joined with commas (so one phrase never runs into the next).
+ *
+ * @param {Record<string, unknown>} record The record.
+ * @param {readonly import('./fields.js').FieldPlan[]} plan The fields.
+ * @returns {import('./record.js').Prepared} The prepared record.
+ */
+export function prepare(record, plan) {
+	/** @type {unknown[]} */
+	const parts = [];
+	/** @type {Record<string, string | string[]>} */
+	const texts = {};
+	for (const f of plan) {
+		const items = listOf(record[f.key]);
+		if (f.list) {
+			const phrases = items.map((v) => textOf(v).toLowerCase()).filter(Boolean);
+			parts.push(phrases.join(','));
+			texts[f.key] = phrases;
+		} else {
+			parts.push(...items);
+			texts[f.key] = items.map(textOf).join(' ').toLowerCase();
+		}
+	}
+	return { text: parts.map(textOf).join(' ').toLowerCase(), texts };
+}

package/src/match/score.d.ts

@@ -0,0 +1,16 @@
+import type { Prepared } from './record.js';
+import type { FieldPlan } from './fields.js';
+import type { Term } from '../query/terms.js';
+
+/** What scoring needs: the fields worth more than `anywhere`, those worth more than `prefix`, and the two scores. */
+export interface Scoring {
+	ranked: readonly FieldPlan[];
+	prefixed: readonly FieldPlan[];
+	prefix: number;
+	anywhere: number;
+}
+
+/** Whether a record has every term: what was typed at the start of a word, or one of its phrases as a whole word. */
+export function matches(doc: Prepared, terms: readonly Term[]): boolean;
+/** How well a record answers the terms: per term, the best of its phrases over the fields, added up. */
+export function score(doc: Prepared, terms: readonly Term[], scoring: Scoring): number;

package/src/match/score.js

@@ -0,0 +1,56 @@
+/**
+ * @module @arraypress/search/match/score
+ *
+ * Whether a prepared record answers a query's terms, and how well.
+ */
+
+/**
+ * Whether a record has every term: what was typed at the start of a word (it
+ * may still be being typed), or one of its phrases as a whole word ("dance"
+ * isn't found in "guidance", nor a synonym "cab" in "cabin").
+ *
+ * @param {import('./record.js').Prepared} doc The record.
+ * @param {readonly import('../query/terms.js').Term[]} terms The terms.
+ * @returns {boolean} Whether it matches.
+ */
+export const matches = (doc, terms) => terms.every((t) => t.start.test(doc.text) || t.whole.some((r) => r.test(doc.text)));
+
+/**
+ * Whether a pattern is found in a field's text (in any one phrase of a list field).
+ *
+ * @param {RegExp} r The pattern.
+ * @param {string | string[]} text The field's text.
+ * @returns {boolean} Whether it is found.
+ */
+const foundIn = (r, text) => (Array.isArray(text) ? text.some((w) => r.test(w)) : r.test(text));
+
+/**
+ * How well a record answers the terms: per term, the best any of its phrases
+ * scores, added up. A phrase scores a field's weight when it is a whole word
+ * of it (a list field's `exact` when it is one of its phrases outright), and
+ * `anywhere` when it is a whole word anywhere in the record. When that comes
+ * to less than `prefix`, what was typed at the start of a word of a field
+ * weighted above `prefix` scores `prefix`.
+ *
+ * @param {import('./record.js').Prepared} doc The record.
+ * @param {readonly import('../query/terms.js').Term[]} terms The terms.
+ * @param {import('./score.js').Scoring} scoring The fields and scores.
+ * @returns {number} The score.
+ */
+export function score(doc, terms, { ranked, prefixed, prefix, anywhere }) {
+	let total = 0;
+	for (const t of terms) {
+		let best = 0;
+		t.whole.forEach((r, k) => {
+			for (const f of ranked) {
+				const text = doc.texts[f.key];
+				if (f.exact > best && Array.isArray(text) && text.includes(t.phrases[k])) best = f.exact;
+				if (f.weight > best && foundIn(r, text)) best = f.weight;
+			}
+			if (anywhere > best && r.test(doc.text)) best = anywhere;
+		});
+		if (best < prefix && prefixed.some((f) => foundIn(t.start, doc.texts[f.key]))) best = prefix;
+		total += best;
+	}
+	return total;
+}

package/src/pack/columns.d.ts

@@ -0,0 +1,4 @@
+/** Records as columns (an absent value as null), with a string table for each column that is smaller as one. */
+export function toColumns(records: readonly Record<string, unknown>[]): { columns: Record<string, unknown[]>; tables: Record<string, string[]> };
+/** Columns back as records (a null value is left out). */
+export function fromColumns(n: number, columns: Readonly<Record<string, readonly unknown[]>>, tables?: Readonly<Record<string, readonly string[]>>): Record<string, unknown>[];

package/src/pack/columns.js

@@ -0,0 +1,78 @@
+/**
+ * @module @arraypress/search/pack/columns
+ *
+ * Records as columns, one per field, for a compact JSON index. A column of
+ * strings (or lists of strings) whose values repeat is stored as numbers into
+ * a table of its strings, most used first, when that comes out smaller.
+ */
+
+/**
+ * Whether every value of a column is a string, a list of strings or absent (null).
+ *
+ * @param {readonly unknown[]} values The column.
+ * @returns {boolean} Whether its strings can go in a table.
+ */
+const stringy = (values) =>
+	values.every((v) => v === null || typeof v === 'string' || (Array.isArray(v) && v.every((s) => typeof s === 'string')));
+
+/**
+ * A column of strings as a table of its strings (most used first) and each value as numbers into it.
+ *
+ * @param {readonly (string | string[] | null)[]} values The column.
+ * @returns {{ table: string[], values: (number | number[] | null)[] }} The table and the column.
+ */
+function tabled(values) {
+	/** @type {Map<string, number>} */
+	const uses = new Map();
+	for (const v of values) for (const s of v === null ? [] : [v].flat()) uses.set(s, (uses.get(s) ?? 0) + 1);
+	const table = [...uses.keys()].sort((a, b) => /** @type {number} */ (uses.get(b)) - /** @type {number} */ (uses.get(a)));
+	const at = new Map(table.map((s, i) => [s, i]));
+	const num = (/** @type {string} */ s) => /** @type {number} */ (at.get(s));
+	return { table, values: values.map((v) => (v === null ? null : Array.isArray(v) ? v.map(num) : num(v))) };
+}
+
+/**
+ * Records as columns: one per field (in the order fields first appear), an
+ * absent value as null, and a table for each column that is smaller as one.
+ *
+ * @param {readonly Record<string, unknown>[]} records The records.
+ * @returns {{ columns: Record<string, unknown[]>, tables: Record<string, string[]> }} The columns and their tables.
+ */
+export function toColumns(records) {
+	/** @type {Record<string, unknown[]>} */
+	const columns = {};
+	/** @type {Record<string, string[]>} */
+	const tables = {};
+	for (const k of new Set(records.flatMap((r) => Object.keys(r)))) {
+		const values = records.map((r) => r[k] ?? null);
+		const t = stringy(values) ? tabled(/** @type {(string | string[] | null)[]} */ (values)) : null;
+		if (t && JSON.stringify(t).length < JSON.stringify(values).length) {
+			columns[k] = t.values;
+			tables[k] = t.table;
+		} else columns[k] = values;
+	}
+	return { columns, tables };
+}
+
+/**
+ * Columns back as records: a null value is left out.
+ *
+ * @param {number} n How many records.
+ * @param {Readonly<Record<string, readonly unknown[]>>} columns The columns.
+ * @param {Readonly<Record<string, readonly string[]>>} [tables] Their tables.
+ * @returns {Record<string, unknown>[]} The records.
+ */
+export function fromColumns(n, columns, tables = {}) {
+	const entries = Object.entries(columns);
+	return Array.from({ length: n }, (_, i) => {
+		/** @type {Record<string, unknown>} */
+		const r = {};
+		for (const [k, values] of entries) {
+			const v = values[i];
+			if (v === null || v === undefined) continue;
+			const table = tables[k];
+			r[k] = !table ? v : Array.isArray(v) ? v.map((j) => table[j]) : table[/** @type {number} */ (v)];
+		}
+		return r;
+	});
+}

package/src/pack/index.d.ts

@@ -0,0 +1,22 @@
+import type { Search, SearchOptions } from '../search.js';
+
+/** A prebuilt index: records as columns, and how they are searched. Plain JSON. */
+export interface Packed<T = Record<string, unknown>> {
+	/** The format's version: 1. */
+	v: 1;
+	/** How many records. */
+	n: number;
+	/** The search options, less any functions. */
+	options: SearchOptions<T>;
+	/** One column per field: each record's value, null when absent (numbers into `tables[field]` when it has one). */
+	columns: Record<string, unknown[]>;
+	/** The string tables of the columns stored as numbers. */
+	tables: Record<string, string[]>;
+}
+
+/** The format's version: 1. */
+export const PACK_VERSION: 1;
+/** Records and their search options as a JSON-ready index (function options aren't packed: pass them to `unpack`). */
+export function pack<T extends object>(records: readonly T[], options: SearchOptions<T>): Packed<T>;
+/** A packed index back as a ready search; throws when it is from another version of the format. */
+export function unpack<T extends object>(packed: Packed<T>, options?: Partial<SearchOptions<T>>): Search<T>;

package/src/pack/index.js

@@ -0,0 +1,49 @@
+/**
+ * @module @arraypress/search/pack
+ *
+ * A prebuilt index: records and search options as compact JSON, built once
+ * (at build time, in Node) and loaded anywhere (the browser).
+ */
+
+import { createSearch } from '../search.js';
+import { toColumns, fromColumns } from './columns.js';
+
+/** The format's version. */
+export const PACK_VERSION = 1;
+
+/**
+ * Records and their search options as a JSON-ready index. Options that are
+ * functions (a `plural` or `tie` of your own) aren't packed: pass them to
+ * `unpack` again.
+ *
+ * @template {object} T
+ * @param {readonly T[]} records The records (strings, numbers, lists: anything JSON holds).
+ * @param {import('../search.js').SearchOptions<T>} options How they are searched.
+ * @returns {import('./index.js').Packed<T>} The index.
+ */
+export function pack(records, options) {
+	const { plural, tie, ...rest } = options;
+	const { columns, tables } = toColumns(/** @type {Record<string, unknown>[]} */ (/** @type {unknown} */ (records)));
+	return {
+		v: PACK_VERSION,
+		n: records.length,
+		options: { ...rest, ...(typeof plural === 'boolean' && { plural }), ...(Array.isArray(tie) && { tie }) },
+		columns,
+		tables,
+	};
+}
+
+/**
+ * A packed index back as a ready search.
+ *
+ * @template {object} T
+ * @param {import('./index.js').Packed<T>} packed The index (parsed JSON).
+ * @param {Partial<import('../search.js').SearchOptions<T>>} [options] Options to add or change (a `plural` or `tie` function, stop words).
+ * @returns {import('../search.js').Search<T>} The search.
+ * @throws {Error} When the index is from another version of the format.
+ */
+export function unpack(packed, options = {}) {
+	if (packed?.v !== PACK_VERSION) throw new Error(`@arraypress/search: index version ${packed?.v}, expected ${PACK_VERSION}`);
+	const records = /** @type {T[]} */ (/** @type {unknown} */ (fromColumns(packed.n, packed.columns, packed.tables)));
+	return createSearch(records, { ...packed.options, ...options });
+}

package/src/query/plural.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The singular of a plain English plural ("plumbers" → "plumber", "bakeries" → "bakery"); '' when it isn't one.
+ * Words of three letters or fewer, and words ending in "ss", are left alone.
+ */
+export function singular(word: string): string;

package/src/query/plural.js

@@ -0,0 +1,17 @@
+/**
+ * @module @arraypress/search/query/plural
+ *
+ * Plural folding for English: a plain plural's singular, so "plumbers" also
+ * finds "plumber" and "bakeries" finds "bakery".
+ */
+
+/**
+ * The singular of a plain English plural: "plumbers" → "plumber",
+ * "bakeries" → "bakery". Words of three letters or fewer, and words ending in
+ * "ss", are left alone.
+ *
+ * @param {string} word The word (or phrase: its last word is folded), lower case.
+ * @returns {string} Its singular, or '' when it isn't a plain plural.
+ */
+export const singular = (word) =>
+	word.length > 3 && /[^s]s$/.test(word) ? (word.endsWith('ies') ? `${word.slice(0, -3)}y` : word.slice(0, -1)) : '';

package/src/query/terms.d.ts

@@ -0,0 +1,28 @@
+/** One term of a query: a word, or a synonym phrase read as one. */
+export interface Term {
+	/** What was typed, lower case ("estate agents"). */
+	typed: string;
+	/** The phrases that count for it: what was typed, its synonym group, its singular. */
+	phrases: string[];
+	/** What was typed, at the start of a word. */
+	start: RegExp;
+	/** Each phrase as a whole word, in the order of `phrases`. */
+	whole: RegExp[];
+}
+
+/** How a query is read. */
+export interface TermOptions {
+	/** Synonym lookup (`synonymMap`). */
+	synonyms: ReadonlyMap<string, readonly string[]>;
+	/** A word's singular, or '' (plural folding off: always ''). */
+	singular: (word: string) => string;
+	/** The most words a synonym phrase can have. Default 3. */
+	phrase?: number;
+	/** Single words left out of a query ("a", "the", "logo"). */
+	stopWords?: ReadonlySet<string>;
+}
+
+/** Synonym groups as a lookup: each phrase → every phrase of its group (a later group wins a shared phrase). */
+export function synonymMap(groups?: readonly (readonly string[])[]): Map<string, readonly string[]>;
+/** Reads a query as terms: lower case, synonym phrases of up to `phrase` words read as one, stop words left out. */
+export function termsOf(query: string, options: TermOptions): Term[];

package/src/query/terms.js

@@ -0,0 +1,49 @@
+/**
+ * @module @arraypress/search/query/terms
+ *
+ * A query read as terms. Each term is a word, or a synonym phrase of up to
+ * three words read as one ("estate agents"), with the phrases that count for
+ * it too: its synonym group and its singular.
+ */
+
+import { atStart, asWord } from '../util/regex.js';
+
+/**
+ * Synonym groups as a lookup: each phrase → every phrase of its group. A
+ * phrase in two groups belongs to the later one.
+ *
+ * @param {readonly (readonly string[])[]} [groups] The groups, lower case.
+ * @returns {Map<string, readonly string[]>} The lookup.
+ */
+export function synonymMap(groups = []) {
+	/** @type {Map<string, readonly string[]>} */
+	const map = new Map();
+	for (const group of groups) for (const p of group) map.set(p, group);
+	return map;
+}
+
+/**
+ * Reads a query as terms. Words are split on white space and lower-cased; up
+ * to `phrase` words in a row are read as one term when they make a synonym
+ * phrase (or its plural). Single-word stop words are left out.
+ *
+ * @param {string} query What was typed.
+ * @param {import('./terms.js').TermOptions} options The synonyms, plural folding, phrase length and stop words.
+ * @returns {import('./terms.js').Term[]} The terms, in order.
+ */
+export function termsOf(query, { synonyms, singular, phrase = 3, stopWords }) {
+	const groupOf = (/** @type {string} */ p) => synonyms.get(p) ?? synonyms.get(singular(p));
+	const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+	/** @type {import('./terms.js').Term[]} */
+	const out = [];
+	for (let i = 0; i < words.length; ) {
+		let n = Math.min(phrase, words.length - i);
+		while (n > 1 && !groupOf(words.slice(i, i + n).join(' '))) n--;
+		const typed = words.slice(i, i + n).join(' ');
+		i += n;
+		if (n === 1 && stopWords?.has(typed)) continue;
+		const phrases = [...new Set([typed, ...(groupOf(typed) ?? []), singular(typed)].filter(Boolean))];
+		out.push({ typed, phrases, start: atStart(typed), whole: phrases.map(asWord) });
+	}
+	return out;
+}

package/src/rules/assign.d.ts

@@ -0,0 +1,48 @@
+/** Record keys as a list, or space-separated. */
+export type Keys = string | readonly string[];
+
+/** What looking at a group's records changed. */
+export interface ReviewEdit {
+	/** Records the rules found that don't belong. */
+	drop?: Keys;
+	/** Records no rule found that do: they go in at the pick score. */
+	add?: Keys;
+	/** Rules fits to hold past the `perGroup` cap. */
+	keep?: Keys;
+}
+
+/** The review, per group. */
+export type Review = Readonly<Record<string, ReviewEdit>>;
+
+/** How records are assigned. */
+export interface AssignOptions<T> {
+	/** A record's key (its slug or id). */
+	key: (record: T) => string;
+	/** A record's score for a group (0 when it doesn't fit): `scoreRule` over your own rules, or your own scoring. */
+	score: (record: T, group: string) => number;
+	/** The lowest score that counts as a fit. Default 1. */
+	min?: number;
+	/** The most groups a record keeps. Default no cap. */
+	perRecord?: number;
+	/** The most rules fits a group keeps (its review keeps and adds come on top). Default no cap. */
+	perGroup?: number;
+	/** Hand picks: a record's groups, best first. These records skip the rules; each pick scores `pick`, a little more the earlier it is listed. */
+	picks?: Readonly<Record<string, Keys>>;
+	/** An add's score: above any rule's, so caps keep it. Default 1000. */
+	pick?: number;
+	/** Per group: drops, adds and keeps. */
+	review?: Review;
+}
+
+/** What `assign` decided. */
+export interface Assigned {
+	/** Each group's records and scores, best first. */
+	byGroup: Record<string, [key: string, score: number][]>;
+	/** Each record that fits anything: its groups, best first, at most `perRecord`. Keys in alphabetical order. */
+	byRecord: Record<string, string[]>;
+	/** Review and pick keys that aren't records (they were skipped). */
+	missing: { group: string; key: string }[];
+}
+
+/** Assigns records to groups: rule scores with caps, then the review's drops and adds, then each record's best groups. */
+export function assign<T>(records: readonly T[], groups: readonly string[], options: AssignOptions<T>): Assigned;

package/src/rules/assign.js

@@ -0,0 +1,112 @@
+/**
+ * @module @arraypress/search/rules/assign
+ *
+ * Assigning records to groups (marks to industries, products to categories)
+ * by rule scores, with caps, hand picks and a review.
+ *
+ * 1. Rules. Every record is scored against every group; it keeps its best
+ *    `perRecord` groups scoring `min` or more (ties: group order). Each group
+ *    keeps its best `perGroup` records, plus any the review says to `keep`.
+ *    Picked records skip this pass.
+ * 2. Review. Per group, `drop` removes records, and `add` puts records in at
+ *    the pick score (`pick`), above any rule's. Each record's `picks` are adds
+ *    on those groups, scored a little higher the earlier they are listed.
+ * 3. Each record's groups, best first, at most `perRecord`.
+ */
+
+/**
+ * Space-separated keys, or a list, as a list.
+ *
+ * @param {string | readonly string[] | undefined} v The keys.
+ * @returns {string[]} The list.
+ */
+const keysOf = (v) => (typeof v === 'string' ? v.split(/\s+/).filter(Boolean) : [...(v ?? [])]);
+
+/**
+ * The review with every pick added to its groups' `add`s (after the review's own).
+ *
+ * @param {import('./assign.js').Review} review The review.
+ * @param {Readonly<Record<string, readonly string[]>>} picks The picks.
+ * @returns {Record<string, { drop: string[], add: string[], keep: string[] }>} The review, as lists.
+ */
+function withPicks(review, picks) {
+	/** @type {Record<string, { drop: string[], add: string[], keep: string[] }>} */
+	const out = {};
+	for (const [g, e] of Object.entries(review)) out[g] = { drop: keysOf(e.drop), add: keysOf(e.add), keep: keysOf(e.keep) };
+	for (const [key, groups] of Object.entries(picks)) for (const g of groups) (out[g] ??= { drop: [], add: [], keep: [] }).add.push(key);
+	return out;
+}
+
+/**
+ * Assigns records to groups by rule score, caps, picks and review.
+ *
+ * @template T
+ * @param {readonly T[]} records The records.
+ * @param {readonly string[]} groups The groups, in order (the tie-break).
+ * @param {import('./assign.js').AssignOptions<T>} options How records score, the caps, picks and review.
+ * @returns {import('./assign.js').Assigned} Each group's records and each record's groups, best first.
+ * @throws {Error} When the review names a group that isn't one.
+ */
+export function assign(records, groups, options) {
+	const { key, score, min = 1, perRecord = Infinity, perGroup = Infinity, pick = 1000, review = {} } = options;
+	/** @type {Record<string, string[]>} */
+	const picks = Object.fromEntries(Object.entries(options.picks ?? {}).map(([k, v]) => [k, keysOf(v)]));
+	const edits = withPicks(review, picks);
+	// a pick scores `pick`, plus a tenth for each place it is ahead of the record's last possible group
+	const pickScore = (/** @type {string} */ k, /** @type {string} */ g) => {
+		const at = picks[k]?.indexOf(g) ?? -1;
+		return at < 0 ? pick : pick + ((Number.isFinite(perRecord) ? perRecord : picks[k].length) - at) / 10;
+	};
+
+	// 1. rules: each record its best perRecord groups, each group its best perGroup records (and its keeps)
+	/** @type {Record<string, [string, number][]>} */
+	const byGroup = Object.fromEntries(groups.map((g) => [g, []]));
+	for (const r of records) {
+		const k = key(r);
+		if (picks[k]) continue;
+		const fits = groups
+			.map((g, order) => ({ g, s: score(r, g), order }))
+			.filter((f) => f.s >= min)
+			.sort((a, b) => b.s - a.s || a.order - b.order)
+			.slice(0, perRecord);
+		for (const f of fits) byGroup[f.g].push([k, f.s]);
+	}
+	for (const g of groups) {
+		const all = byGroup[g].sort((a, b) => b[1] - a[1]);
+		const keep = new Set(edits[g]?.keep);
+		byGroup[g] = [...all.slice(0, perGroup), ...all.slice(perGroup).filter(([k]) => keep.has(k))];
+	}
+
+	// 2. review: drops, then adds at the pick score
+	const known = new Set(records.map(key));
+	/** @type {{ group: string, key: string }[]} */
+	const missing = [];
+	for (const [g, { drop, add, keep }] of Object.entries(edits)) {
+		if (!byGroup[g]) throw new Error(`review: no group "${g}"`);
+		for (const k of [...drop, ...add, ...keep]) if (!known.has(k)) missing.push({ group: g, key: k });
+		const out = new Set(drop);
+		const picked = new Set(add);
+		const list = byGroup[g].filter(([k]) => !out.has(k)).map(([k, s]) => /** @type {[string, number]} */ ([k, picked.has(k) ? pickScore(k, g) : s]));
+		const have = new Set(list.map(([k]) => k));
+		for (const k of add) if (known.has(k) && !have.has(k)) list.push([k, pickScore(k, g)]);
+		byGroup[g] = list.sort((a, b) => b[1] - a[1]);
+	}
+
+	// 3. each record's groups, best first (ties: group order)
+	const order = new Map(groups.map((g, i) => [g, i]));
+	/** @type {Map<string, [string, number][]>} */
+	const fits = new Map();
+	for (const [g, list] of Object.entries(byGroup)) for (const [k, s] of list) fits.set(k, [...(fits.get(k) ?? []), [g, s]]);
+	const byRecord = Object.fromEntries(
+		[...fits]
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([k, list]) => [
+				k,
+				list
+					.sort((a, b) => b[1] - a[1] || /** @type {number} */ (order.get(a[0])) - /** @type {number} */ (order.get(b[0])))
+					.slice(0, perRecord)
+					.map(([g]) => g),
+			]),
+	);
+	return { byGroup, byRecord, missing };
+}

package/src/rules/index.d.ts

@@ -0,0 +1,4 @@
+export type { Words, Rule } from './score.js';
+export { found, wordScore, pointsFor, scoreRule } from './score.js';
+export type { Keys, ReviewEdit, Review, AssignOptions, Assigned } from './assign.js';
+export { assign } from './assign.js';

package/src/rules/index.js

@@ -0,0 +1,9 @@
+/**
+ * @module @arraypress/search/rules
+ *
+ * Rule-based tagging: score records against weighted word rules, then assign
+ * them to groups with caps, hand picks and a review.
+ */
+
+export { found, wordScore, pointsFor, scoreRule } from './score.js';
+export { assign } from './assign.js';

package/src/rules/score.d.ts

@@ -0,0 +1,21 @@
+/** Word patterns and what each is worth, strongest first: the first one found counts. */
+export type Words = readonly (readonly [pattern: RegExp | string, score: number])[];
+
+/** A rule: what makes a record fit one group. */
+export interface Rule {
+	/** Words that veto the rule outright. */
+	not?: RegExp | string;
+	/** Word patterns and what each is worth, strongest first. */
+	words?: Words;
+	/** Points per value, per field: `{ style: { iso: 1 }, mood: { calm: 2 } }`. A list field adds each of its values. */
+	points?: Readonly<Record<string, Readonly<Record<string, number>>>>;
+}
+
+/** Whether a pattern is found in a text (no pattern: never; a string is read as a regular expression). */
+export function found(pattern: RegExp | string | undefined, text: string): boolean;
+/** The score of the first word pattern found in a text, or 0. */
+export function wordScore(words: Words | undefined, text: string): number;
+/** Points for values: each value adds what the table gives it. */
+export function pointsFor(table: Readonly<Record<string, number>> | undefined, values: unknown): number;
+/** One record's score against one rule: 0 on a veto word, else the first word pattern found plus each field's points. */
+export function scoreRule(rule: Rule, text: string, record?: Readonly<Record<string, unknown>>): number;

package/src/rules/score.js

@@ -0,0 +1,49 @@
+/**
+ * @module @arraypress/search/rules/score
+ *
+ * Scoring one record against one rule: weighted word patterns over its text,
+ * plus points for the values it has, and words that veto the rule outright.
+ */
+
+/**
+ * Whether a pattern is found in a text (no pattern: never).
+ *
+ * @param {RegExp | string | undefined} pattern The pattern (a string is read as a regular expression).
+ * @param {string} text The text.
+ * @returns {boolean} Whether it is found.
+ */
+export const found = (pattern, text) => (pattern === undefined ? false : (typeof pattern === 'string' ? new RegExp(pattern) : pattern).test(text));
+
+/**
+ * The score of the first word pattern found in a text, strongest listed first.
+ *
+ * @param {import('./score.js').Words | undefined} words The patterns and what each is worth.
+ * @param {string} text The text.
+ * @returns {number} The first found pattern's score, or 0.
+ */
+export const wordScore = (words, text) => words?.find(([pattern]) => found(pattern, text))?.[1] ?? 0;
+
+/**
+ * Points for values: each value the record has adds what the table gives it.
+ *
+ * @param {Readonly<Record<string, number>> | undefined} table Points per value.
+ * @param {unknown} values The record's value, or list of values.
+ * @returns {number} The points, added up.
+ */
+export const pointsFor = (table, values) =>
+	(Array.isArray(values) ? values : [values]).reduce((s, v) => s + (table?.[String(v)] ?? 0), 0);
+
+/**
+ * One record's score against one rule: 0 when the text has a veto word (`not`);
+ * otherwise the first word pattern found (`words`), plus the points (`points`)
+ * of each field's values.
+ *
+ * @param {import('./score.js').Rule} rule The rule.
+ * @param {string} text The record's text, as the patterns read it (lower case).
+ * @param {Readonly<Record<string, unknown>>} [record] The record, for `points`.
+ * @returns {number} The score.
+ */
+export function scoreRule(rule, text, record = {}) {
+	if (found(rule.not, text)) return 0;
+	return Object.entries(rule.points ?? {}).reduce((s, [k, table]) => s + pointsFor(table, record[k]), wordScore(rule.words, text));
+}

package/src/search.d.ts

@@ -0,0 +1,79 @@
+import type { Term } from './query/terms.js';
+import type { Filter } from './filter/filter.js';
+import type { Tie } from './filter/tie.js';
+
+/** A field's scoring: a number is its weight. */
+export type Field =
+	| number
+	| {
+			/** A phrase found in it as a whole word. Default 0. */
+			weight?: number;
+			/** A list field: a phrase that is one of its items outright. Default 0. */
+			exact?: number;
+			/** Its items are separate phrases (search words: "nail salon", "cafe"), each matched on its own. */
+			list?: boolean;
+	  };
+
+/** The fields that make a record's text, in order, with their scoring. */
+export type Fields = { readonly [field: string]: Field };
+
+/** How a search reads, matches and ranks. */
+export interface SearchOptions<T> {
+	/** The fields searched, in order: `{ name: 4, keywords: { weight: 2.5, exact: 4, list: true }, description: 1 }`. */
+	fields: Fields;
+	/** Synonym groups, lower case: a phrase from one searches for every phrase of its group. */
+	synonyms?: readonly (readonly string[])[];
+	/** What was typed, at the start of a word of a field weighted above this, scores this. Default 2. */
+	prefix?: number;
+	/** A phrase found as a whole word anywhere in the record. Default 1. */
+	anywhere?: number;
+	/** Plural folding: English (`true`, the default), none (`false`), or a word's singular ('' for none). */
+	plural?: boolean | ((word: string) => string);
+	/** The most words a synonym phrase can have. Default 3. */
+	phrase?: number;
+	/** Single words left out of a query ("a", "the", "logo"). */
+	stopWords?: readonly string[];
+	/** Tie-breaks at an equal score: fields whose records with a value go first, or a comparison. Record order comes last. */
+	tie?: Tie<T>;
+}
+
+/** What one search narrows to and returns. */
+export interface SearchQuery<T> {
+	/** Field values a record must have (a list field: contain), or a test. */
+	filter?: Filter<T>;
+	/** The most hits to return (all of them by default). */
+	limit?: number;
+}
+
+/** One record found. */
+export interface Hit<T> {
+	item: T;
+	/** Its place in the records. */
+	index: number;
+	/** How well it answers the query (0 with no words). */
+	score: number;
+}
+
+/** A search's answer. */
+export interface Result<T> {
+	/** How many records matched (more than `hits` when the limit cut it). */
+	total: number;
+	/** Best first; in record order when the query has no words. */
+	hits: Hit<T>[];
+	/** The query as read. */
+	terms: Term[];
+}
+
+/** A built search. */
+export interface Search<T> {
+	readonly records: readonly T[];
+	/** Every record that passes the filter and has every term of the query, best first. */
+	search(query?: string, options?: SearchQuery<T>): Result<T>;
+	/** How a query is read: its terms, their synonyms and singulars. */
+	terms(query: string): Term[];
+	/** Each field's values among the records a query and filter find, with counts, most first. */
+	facets<K extends string>(fields: readonly K[], options?: { query?: string; filter?: Filter<T> }): Record<K, Record<string, number>>;
+}
+
+/** Builds a search over records: each is prepared once, then searched by words, filtered and ranked. */
+export function createSearch<T extends object>(records: readonly T[], options: SearchOptions<T>): Search<T>;

package/src/search.js

@@ -0,0 +1,68 @@
+/**
+ * @module @arraypress/search/search
+ *
+ * Ranked in-memory search over records: field weights, synonym groups (a
+ * phrase of up to three words read as one), plural folding, word-start and
+ * whole-word matching, exact filters and stable tie-breaks.
+ */
+
+import { synonymMap, termsOf } from './query/terms.js';
+import { singular } from './query/plural.js';
+import { planOf } from './match/fields.js';
+import { prepare } from './match/record.js';
+import { matches, score } from './match/score.js';
+import { filterOf } from './filter/filter.js';
+import { tieOf } from './filter/tie.js';
+import { facets } from './filter/facets.js';
+
+/**
+ * The plural option as a function: English (`true`), none (`false`), or your own.
+ *
+ * @param {import('./search.js').SearchOptions<unknown>['plural']} plural The option.
+ * @returns {(word: string) => string} A word's singular, or ''.
+ */
+const singularOf = (plural = true) => (typeof plural === 'function' ? plural : plural ? singular : () => '');
+
+/**
+ * Builds a search over records. Each record is prepared once (its text, lower
+ * case); every search then reads the query, keeps the records that pass the
+ * filter and have every term, and ranks them.
+ *
+ * @template {object} T
+ * @param {readonly T[]} records The records, in their own order (the last tie-break).
+ * @param {import('./search.js').SearchOptions<T>} options Fields, synonyms and scoring.
+ * @returns {import('./search.js').Search<T>} The search.
+ */
+export function createSearch(records, options) {
+	const { fields, synonyms, prefix = 2, anywhere = 1, plural, phrase, stopWords, tie } = options;
+	const plan = planOf(fields);
+	const top = (/** @type {import('./match/fields.js').FieldPlan} */ f) => Math.max(f.weight, f.exact);
+	const scoring = { ranked: plan.filter((f) => top(f) > anywhere), prefixed: plan.filter((f) => top(f) > prefix), prefix, anywhere };
+	const docs = records.map((r) => prepare(/** @type {Record<string, unknown>} */ (r), plan));
+	const reading = { synonyms: synonymMap(synonyms), singular: singularOf(plural), phrase, stopWords: stopWords && new Set(stopWords) };
+	const breakTie = tieOf(tie);
+
+	/** @type {import('./search.js').Search<T>['terms']} */
+	const terms = (query) => termsOf(query, reading);
+
+	/** @type {import('./search.js').Search<T>['search']} */
+	function search(query = '', { filter, limit = Infinity } = {}) {
+		const t = terms(query);
+		const passes = filterOf(filter);
+		/** @type {import('./search.js').Hit<T>[]} */
+		const hits = [];
+		records.forEach((item, index) => {
+			if (passes(item, index) && matches(docs[index], t)) hits.push({ item, index, score: t.length ? score(docs[index], t, scoring) : 0 });
+		});
+		if (t.length) hits.sort((a, b) => b.score - a.score || breakTie(a.item, b.item) || a.index - b.index);
+		return { total: hits.length, hits: hits.slice(0, limit), terms: t };
+	}
+
+	return {
+		records,
+		search,
+		terms,
+		facets: (keys, { query, filter } = {}) =>
+			facets(search(query, { filter }).hits.map((h) => /** @type {Record<string, unknown>} */ (h.item)), keys),
+	};
+}

package/src/util/regex.d.ts

@@ -0,0 +1,6 @@
+/** Text made safe to use literally inside a regular expression. */
+export function escape(s: string): string;
+/** A phrase at the start of a word ("spa" is found in "space"). */
+export function atStart(phrase: string): RegExp;
+/** A phrase as a whole word ("spa" is found in "spa stones", not "space"). */
+export function asWord(phrase: string): RegExp;

package/src/util/regex.js

@@ -0,0 +1,31 @@
+/**
+ * @module @arraypress/search/util/regex
+ *
+ * The two ways a phrase is looked for in lower-case text: at the start of a
+ * word (what is typed may still be being typed), and as a whole word. A word
+ * is a run of `a-z` and `0-9`; anything else is a boundary.
+ */
+
+/**
+ * Text made safe to use literally inside a regular expression.
+ *
+ * @param {string} s The text.
+ * @returns {string} It, with every special character escaped.
+ */
+export const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * A phrase at the start of a word: "spa" is found in "space".
+ *
+ * @param {string} phrase The phrase, lower case.
+ * @returns {RegExp} The pattern.
+ */
+export const atStart = (phrase) => new RegExp(`(?:^|[^a-z0-9])${escape(phrase)}`);
+
+/**
+ * A phrase as a whole word: "spa" is found in "spa stones", not "space".
+ *
+ * @param {string} phrase The phrase, lower case.
+ * @returns {RegExp} The pattern.
+ */
+export const asWord = (phrase) => new RegExp(`(?:^|[^a-z0-9])${escape(phrase)}(?![a-z0-9])`);

package/src/util/values.d.ts

@@ -0,0 +1,4 @@
+/** A value as a list: a list as it is, anything else as one item ('' when absent). */
+export function listOf(v: unknown): unknown[];
+/** Whether a value says something: a non-empty string or list, or any other value that isn't null or undefined. */
+export function filled(v: unknown): boolean;

package/src/util/values.js

@@ -0,0 +1,23 @@
+/**
+ * @module @arraypress/search/util/values
+ *
+ * Small helpers for record values, which are a string, a list of strings, or
+ * absent.
+ */
+
+/**
+ * A value as a list: a list as it is, anything else as one item ('' when absent).
+ *
+ * @param {unknown} v The value.
+ * @returns {unknown[]} The list.
+ */
+export const listOf = (v) => (Array.isArray(v) ? v : [v ?? '']);
+
+/**
+ * Whether a value says something: a non-empty string or list, or any other
+ * value that isn't null or undefined.
+ *
+ * @param {unknown} v The value.
+ * @returns {boolean} Whether it has content.
+ */
+export const filled = (v) => (Array.isArray(v) || typeof v === 'string' ? v.length > 0 : v != null);