@arraypress/search 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 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.2.0] — 2026-11-15
+
+### Added
+
+- **A filter panel's logic:** `facetTable` (each record's values per facet, worked out once), `narrow` (any picked value within a facet, every facet with a pick), `facetCounts` (each value's live count against the other facets' picks, so it is what ticking it would show), `toggle`, `pickCount`, `picks`, `sameSelection`, and `readSelection` / `writeSelection` for the selection in a page's address. From the Logomarks filter panel. `facets()` is unchanged: it counts values without a selection.
+
+## [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, a filter panel's facet logic (live counts, the selection in the address), 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.2.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/address.d.ts

@@ -0,0 +1,6 @@
+import type { Selection } from './selection.js';
+
+/** Writes the selection into a query (one comma-joined parameter per picked facet), keeping other parameters. */
+export function writeSelection<F extends string>(params: URLSearchParams, ids: readonly F[], sel: Selection<F>, keys?: Partial<Record<F, string>>): URLSearchParams;
+/** The selection a query asks for; unknown values and repeats dropped. */
+export function readSelection<F extends string>(params: URLSearchParams, ids: readonly F[], known?: Partial<Record<F, ReadonlySet<string>>>, keys?: Partial<Record<F, string>>): Selection<F>;

package/src/filter/address.js

@@ -0,0 +1,48 @@
+/**
+ * @module @arraypress/search/filter/address
+ *
+ * A selection in a page's address: one query parameter per facet with a pick,
+ * its values joined by commas (`?style=iso,track&mood=calm`), and back.
+ */
+
+/**
+ * Writes the selection into a query: one parameter per facet with a pick (its key from `keys`, else its id), the
+ * values joined by commas, in facet order. Other parameters are kept; a facet without a pick is removed.
+ *
+ * @param {URLSearchParams} params The query, changed in place.
+ * @param {readonly string[]} ids The facets, in order.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @param {Record<string, string>} [keys] A parameter name per facet, where it isn't the facet's id.
+ * @returns {URLSearchParams} The same query.
+ */
+export function writeSelection(params, ids, sel, keys = {}) {
+	for (const f of ids) {
+		const key = keys[f] ?? f;
+		const vals = sel[f];
+		if (vals?.length) params.set(key, vals.join(','));
+		else params.delete(key);
+	}
+	return params;
+}
+
+/**
+ * The selection a query asks for. Values a facet doesn't take (when `known` is given) are dropped, and repeats.
+ *
+ * @param {URLSearchParams} params The query.
+ * @param {readonly string[]} ids The facets.
+ * @param {Record<string, ReadonlySet<string>>} [known] The values each facet takes (a table's `known`).
+ * @param {Record<string, string>} [keys] A parameter name per facet, where it isn't the facet's id.
+ * @returns {import('./selection.js').Selection} The selection.
+ */
+export function readSelection(params, ids, known, keys = {}) {
+	/** @type {Record<string, string[]>} */
+	const sel = {};
+	for (const f of ids) {
+		const raw = params.get(keys[f] ?? f);
+		if (!raw) continue;
+		const ok = known?.[f];
+		const vals = [...new Set(raw.split(',').map((v) => v.trim()))].filter((v) => v && (!ok || ok.has(v)));
+		if (vals.length) sel[f] = vals;
+	}
+	return sel;
+}

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/selection.d.ts

@@ -0,0 +1,28 @@
+/** The values picked in each facet; an absent or empty list means any. */
+export type Selection<F extends string = string> = Partial<Record<F, readonly string[]>>;
+
+/** Each record's values per facet: `values[k][i]` are record i's values in facet `ids[k]`. */
+export interface FacetTable<F extends string = string> {
+	ids: readonly F[];
+	values: (readonly string[])[][];
+	/** Every value each facet takes, for checking a selection read from an address. */
+	known: Record<F, ReadonlySet<string>>;
+}
+
+/** Live counts: per facet, each value's count among the records that pass every other facet. */
+export type FacetCounts<F extends string = string> = Record<F, Map<string, number>>;
+
+/** Each record's values in each facet, as a table. */
+export function facetTable<T, F extends string>(records: readonly T[], valuesOf: Record<F, (record: T) => readonly string[]>): FacetTable<F>;
+/** The records (indices, in the order given) that pass every facet with a pick. */
+export function narrow<F extends string>(table: FacetTable<F>, candidates: Iterable<number>, sel: Selection<F>): number[];
+/** Each facet's value counts among the candidates, each counted against the other facets' picks. */
+export function facetCounts<F extends string>(table: FacetTable<F>, candidates: Iterable<number>, sel: Selection<F>): FacetCounts<F>;
+/** The selection with one value ticked, unticked or (with `on`) forced. */
+export function toggle<F extends string>(sel: Selection<F>, facet: F, value: string, on?: boolean): Selection<F>;
+/** How many values are picked across every facet. */
+export function pickCount(sel: Selection): number;
+/** Every pick as [facet, value], in facet order then pick order. */
+export function picks<F extends string>(ids: readonly F[], sel: Selection<F>): (readonly [F, string])[];
+/** Whether two selections pick the same values, in any order. */
+export function sameSelection(a: Selection, b: Selection): boolean;

package/src/filter/selection.js

@@ -0,0 +1,135 @@
+/**
+ * @module @arraypress/search/filter/selection
+ *
+ * A filter panel's logic over facets: each record's values per facet worked
+ * out once (a table), the records that pass a selection (any picked value
+ * within a facet, every facet with a pick), each value's live count (counted
+ * against the other facets' picks, so it is what ticking it would show), and
+ * small helpers for changing and comparing selections. Generic over facet ids.
+ */
+
+/**
+ * Each record's values in each facet, as a table.
+ *
+ * @template T, F
+ * @param {readonly T[]} records The records.
+ * @param {Record<F & string, (record: T) => readonly string[]>} valuesOf Per facet, a record's values in it (none for none).
+ * @returns {import('./selection.js').FacetTable<F & string>} The table.
+ */
+export function facetTable(records, valuesOf) {
+	const ids = /** @type {(F & string)[]} */ (Object.keys(valuesOf));
+	const values = ids.map((f) => records.map((r) => valuesOf[f](r)));
+	const known = /** @type {Record<F & string, ReadonlySet<string>>} */ (Object.fromEntries(ids.map((f, k) => [f, new Set(values[k].flat())])));
+	return { ids, values, known };
+}
+
+/**
+ * The facets with a pick, as [table column, picked values].
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {(readonly [number, Set<string>])[]} The picks.
+ */
+const picked = (table, sel) => table.ids.flatMap((f, k) => (sel[f]?.length ? [/** @type {const} */ ([k, new Set(sel[f])])] : []));
+
+/**
+ * Whether a record has any of the picked values.
+ *
+ * @param {readonly string[]} have The record's values.
+ * @param {ReadonlySet<string>} want The picked values.
+ * @returns {boolean} True when one matches.
+ */
+const hasAny = (have, want) => have.some((v) => want.has(v));
+
+/**
+ * The records (indices, in the order given) that pass every facet with a pick: any of its picked values.
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {Iterable<number>} candidates The records to consider (a search's hits, or all).
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {number[]} The indices that pass.
+ */
+export function narrow(table, candidates, sel) {
+	const picks = picked(table, sel);
+	/** @type {number[]} */
+	const out = [];
+	for (const i of candidates) if (picks.every(([k, want]) => hasAny(table.values[k][i], want))) out.push(i);
+	return out;
+}
+
+/**
+ * Each facet's value counts among the candidates: a value's count is how many candidates have it and pass every
+ * OTHER facet, so it is how many records ticking it would add (or, in a facet with no pick, show).
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {Iterable<number>} candidates The records to count (a search's hits, or all).
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {Record<string, Map<string, number>>} Per facet, each value's count.
+ */
+export function facetCounts(table, candidates, sel) {
+	const picks = picked(table, sel);
+	const counts = table.ids.map(() => /** @type {Map<string, number>} */ (new Map()));
+	/** Counts record i's values in facet column k. */
+	const add = (/** @type {number} */ k, /** @type {number} */ i) => {
+		for (const v of table.values[k][i]) counts[k].set(v, (counts[k].get(v) ?? 0) + 1);
+	};
+	for (const i of candidates) {
+		// the facets it fails: none, it counts everywhere; one, it counts only there (ticking more of that facet adds it)
+		let failed = -1;
+		let fails = 0;
+		for (const [k, want] of picks)
+			if (!hasAny(table.values[k][i], want)) {
+				failed = k;
+				if (++fails > 1) break;
+			}
+		if (fails === 0) table.ids.forEach((_, k) => add(k, i));
+		else if (fails === 1) add(failed, i);
+	}
+	return Object.fromEntries(table.ids.map((f, k) => [f, counts[k]]));
+}
+
+/**
+ * The selection with one value ticked or unticked.
+ *
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @param {string} facet The facet.
+ * @param {string} value The value.
+ * @param {boolean} [on] Force it on or off; toggles when absent.
+ * @returns {import('./selection.js').Selection} A new selection.
+ */
+export function toggle(sel, facet, value, on) {
+	const have = sel[facet] ?? [];
+	const now = on ?? !have.includes(value);
+	const next = now ? (have.includes(value) ? have : [...have, value]) : have.filter((v) => v !== value);
+	return { ...sel, [facet]: next };
+}
+
+/**
+ * How many values are picked across every facet.
+ *
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {number} The count.
+ */
+export const pickCount = (sel) => Object.values(sel).reduce((n, v) => n + (v?.length ?? 0), 0);
+
+/**
+ * Every pick as [facet, value], in facet order then pick order (a row of chips).
+ *
+ * @param {readonly string[]} ids The facets, in order.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {(readonly [string, string])[]} The picks.
+ */
+export const picks = (ids, sel) => ids.flatMap((f) => (sel[f] ?? []).map((v) => /** @type {const} */ ([f, v])));
+
+/**
+ * Whether two selections pick the same values, in any order (an empty list is no pick).
+ *
+ * @param {import('./selection.js').Selection} a One selection.
+ * @param {import('./selection.js').Selection} b The other.
+ * @returns {boolean} True when they match.
+ */
+export function sameSelection(a, b) {
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const k of keys) if ([...(a[k] ?? [])].sort().join(',') !== [...(b[k] ?? [])].sort().join(',')) return false;
+	return true;
+}

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,14 @@
+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 { facetTable, narrow, facetCounts, toggle, pickCount, picks, sameSelection } from './filter/selection.js';
+export type { Selection, FacetTable, FacetCounts } from './filter/selection.js';
+export { readSelection, writeSelection } from './filter/address.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,17 @@
+/**
+ * @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 { facetTable, narrow, facetCounts, toggle, pickCount, picks, sameSelection } from './filter/selection.js';
+export { readSelection, writeSelection } from './filter/address.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 };
+}