@arraypress/search 0.0.0-stage → 0.2.0

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>;