@arraypress/search 0.0.0-stage → 0.2.0

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