@ai-matrx/kit 0.5.0

package/dist/search-scoring.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/search-scoring.ts
+var search_scoring_exports = {};
+__export(search_scoring_exports, {
+  computeSearchScore: () => computeSearchScore,
+  filterAndSortBySearch: () => filterAndSortBySearch,
+  idMatchesQuery: () => idMatchesQuery,
+  matchesSearch: () => matchesSearch
+});
+module.exports = __toCommonJS(search_scoring_exports);
+var WEIGHT_TABLE = {
+  title: { exact: 1e4, startsWith: 5e3, includes: 2e3 },
+  subtitle: { exact: 2e3, startsWith: 1e3, includes: 500 },
+  body: { exact: 1e3, startsWith: 600, includes: 400 },
+  tag: { exact: 500, startsWith: 400, includes: 300 },
+  meta: { exact: 200, startsWith: 150, includes: 100 },
+  id: { exact: 100, startsWith: 75, includes: 50 }
+};
+var MIN_AUTO_ID_QUERY_LEN = 3;
+function getStringId(item) {
+  if (item && typeof item === "object" && "id" in item) {
+    const id = item.id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return null;
+}
+function resolveTiers(field) {
+  if (field.weight === "custom" || field.exact != null) {
+    return {
+      exact: field.exact ?? 0,
+      startsWith: field.startsWith ?? 0,
+      includes: field.includes ?? 0
+    };
+  }
+  return WEIGHT_TABLE[field.weight ?? "body"];
+}
+function scoreValue(value, q, tiers) {
+  if (!value) return 0;
+  const v = value.toLowerCase();
+  if (v === q) return tiers.exact;
+  if (v.startsWith(q)) return tiers.startsWith;
+  if (v.includes(q)) return tiers.includes;
+  return 0;
+}
+function computeSearchScore(item, query, fields) {
+  const trimmed = query.trim();
+  if (!trimmed) return 0;
+  const q = trimmed.toLowerCase();
+  let total = 0;
+  fields.forEach((field, idx) => {
+    const raw = field.get(item);
+    if (raw == null) return;
+    const tiers = resolveTiers(field);
+    let best = 0;
+    if (Array.isArray(raw)) {
+      for (const v of raw) {
+        if (typeof v !== "string") continue;
+        const s = scoreValue(v, q, tiers);
+        if (s > best) best = s;
+      }
+    } else if (typeof raw === "string") {
+      best = scoreValue(raw, q, tiers);
+    }
+    if (best > 0) {
+      total += best + (fields.length - idx);
+    }
+  });
+  const hasExplicitId = fields.some((f) => f.weight === "id");
+  if (!hasExplicitId && q.length >= MIN_AUTO_ID_QUERY_LEN) {
+    const id = getStringId(item);
+    if (id) {
+      total += scoreValue(id, q, WEIGHT_TABLE.id);
+    }
+  }
+  return total;
+}
+function matchesSearch(item, query, fields) {
+  return computeSearchScore(item, query, fields) > 0;
+}
+function idMatchesQuery(item, query) {
+  const q = query.trim().toLowerCase();
+  if (q.length < MIN_AUTO_ID_QUERY_LEN) return false;
+  const id = getStringId(item);
+  return id != null && id.toLowerCase().includes(q);
+}
+function filterAndSortBySearch(items, query, fields) {
+  const trimmed = query.trim();
+  if (!trimmed) return items.slice();
+  const scored = [];
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const score = computeSearchScore(item, trimmed, fields);
+    if (score > 0) scored.push({ item, score, idx: i });
+  }
+  scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+  return scored.map((s) => s.item);
+}
+//# sourceMappingURL=search-scoring.cjs.map

package/dist/search-scoring.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/search-scoring.ts"],"sourcesContent":["/**\n * Relevance-weighted search scoring.\n *\n * Use instead of the naive `name.includes(q) || description.includes(q)` pattern\n * so that title/name matches rank above description matches, and exact/prefix\n * matches rank above partial ones.\n *\n * ── Quick start ────────────────────────────────────────────────────────────────\n *   const filtered = filterAndSortBySearch(items, query, [\n *     { get: (t) => t.name, weight: \"title\" },\n *     { get: (t) => t.description, weight: \"body\" },\n *     { get: (t) => t.tags, weight: \"tag\" },\n *   ]);\n *\n * ── Weight tiers (higher = more important field) ──────────────────────────────\n *   title    — the primary identifier (name, label, subject)\n *   subtitle — secondary identifier (vendor, author, category name)\n *   body     — long-form descriptive text (description, summary)\n *   tag      — tag/category labels\n *   meta     — weak metadata (modelId, type)\n *   id       — raw identifiers (uuid, slug) — only useful for pasted-id lookups\n *\n * Within each field, an EXACT match > STARTS-WITH match > INCLUDES match.\n * Fields declared first are a slight tiebreaker (via field-index bonus).\n *\n * ── Automatic id matching ─────────────────────────────────────────────────────\n * Every item with a string `id` is ALSO matched against the query at the `id`\n * weight tier, automatically — you do NOT need to declare an id field. This\n * means a user can paste a full or partial UUID into ANY search box wired to\n * this helper and find the record. It kicks in from {@link MIN_AUTO_ID_QUERY_LEN}\n * characters up (so short queries don't match random hex). Declare an explicit\n * `{ weight: \"id\" }` field only if you want id matching at any length / on a\n * non-`id` property; doing so opts that callsite out of the automatic pass.\n */\n\nexport type SearchFieldWeight =\n  | \"title\"\n  | \"subtitle\"\n  | \"body\"\n  | \"tag\"\n  | \"meta\"\n  | \"id\"\n  | \"custom\";\n\nexport interface SearchFieldConfig<T> {\n  /**\n   * Extracts the value(s) from the item. Return a string, an array of strings,\n   * or null/undefined. Arrays score based on the best-matching element.\n   */\n  get: (item: T) => string | string[] | null | undefined;\n  /** Field importance tier. Defaults to \"body\". */\n  weight?: SearchFieldWeight;\n  /** Optional override for custom tiers. Ignored when `weight` is preset. */\n  exact?: number;\n  startsWith?: number;\n  includes?: number;\n}\n\nconst WEIGHT_TABLE: Record<\n  Exclude<SearchFieldWeight, \"custom\">,\n  { exact: number; startsWith: number; includes: number }\n> = {\n  title: { exact: 10000, startsWith: 5000, includes: 2000 },\n  subtitle: { exact: 2000, startsWith: 1000, includes: 500 },\n  body: { exact: 1000, startsWith: 600, includes: 400 },\n  tag: { exact: 500, startsWith: 400, includes: 300 },\n  meta: { exact: 200, startsWith: 150, includes: 100 },\n  id: { exact: 100, startsWith: 75, includes: 50 },\n};\n\n/**\n * Below this query length we do NOT auto-match the row `id`. A 1–2 char query\n * is almost always a substring of *some* hex chars in *every* UUID, so matching\n * id at that length would flood results with the whole table. From 3 chars up a\n * partial-UUID paste is selective enough to be a real lookup.\n */\nconst MIN_AUTO_ID_QUERY_LEN = 3;\n\n/** Pull a non-empty string `id` off an item, or null if it has none. */\nfunction getStringId(item: unknown): string | null {\n  if (item && typeof item === \"object\" && \"id\" in item) {\n    const id = (item as { id?: unknown }).id;\n    if (typeof id === \"string\" && id.length > 0) return id;\n  }\n  return null;\n}\n\nfunction resolveTiers(field: SearchFieldConfig<unknown>) {\n  if (field.weight === \"custom\" || field.exact != null) {\n    return {\n      exact: field.exact ?? 0,\n      startsWith: field.startsWith ?? 0,\n      includes: field.includes ?? 0,\n    };\n  }\n  return WEIGHT_TABLE[field.weight ?? \"body\"];\n}\n\nfunction scoreValue(\n  value: string,\n  q: string,\n  tiers: { exact: number; startsWith: number; includes: number },\n): number {\n  if (!value) return 0;\n  const v = value.toLowerCase();\n  if (v === q) return tiers.exact;\n  if (v.startsWith(q)) return tiers.startsWith;\n  if (v.includes(q)) return tiers.includes;\n  return 0;\n}\n\n/**\n * Compute a weighted relevance score for `item` against `query`.\n * Returns 0 if there is no match — callers can treat `> 0` as a match predicate.\n *\n * Within each field, multiple values (e.g. tags) contribute the BEST match,\n * not the sum, so an item with many tags doesn't unfairly outrank one with a\n * single exact title match.\n */\nexport function computeSearchScore<T>(\n  item: T,\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): number {\n  const trimmed = query.trim();\n  if (!trimmed) return 0;\n  const q = trimmed.toLowerCase();\n\n  let total = 0;\n  fields.forEach((field, idx) => {\n    const raw = field.get(item);\n    if (raw == null) return;\n    const tiers = resolveTiers(field as SearchFieldConfig<unknown>);\n\n    let best = 0;\n    if (Array.isArray(raw)) {\n      for (const v of raw) {\n        if (typeof v !== \"string\") continue;\n        const s = scoreValue(v, q, tiers);\n        if (s > best) best = s;\n      }\n    } else if (typeof raw === \"string\") {\n      best = scoreValue(raw, q, tiers);\n    }\n\n    if (best > 0) {\n      // Tiny bias so that when two fields tie, the one declared first wins.\n      total += best + (fields.length - idx);\n    }\n  });\n\n  // Auto-match the row's UUID `id` against EVERY search box. A user can paste a\n  // full or partial id and find the record, without each callsite remembering\n  // to declare an id field. Skipped when the caller already declared an\n  // explicit `weight: \"id\"` field (so we don't double-score), and gated on a\n  // minimum query length so short queries don't match random hex substrings.\n  const hasExplicitId = fields.some((f) => f.weight === \"id\");\n  if (!hasExplicitId && q.length >= MIN_AUTO_ID_QUERY_LEN) {\n    const id = getStringId(item);\n    if (id) {\n      total += scoreValue(id, q, WEIGHT_TABLE.id);\n    }\n  }\n\n  return total;\n}\n\nexport function matchesSearch<T>(\n  item: T,\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): boolean {\n  return computeSearchScore(item, query, fields) > 0;\n}\n\n/**\n * Drop-in id-match for hand-rolled `.filter()` predicates that can't (yet) move\n * onto {@link filterAndSortBySearch}. Returns true when `query` is a substring\n * of the item's string `id`, applying the same {@link MIN_AUTO_ID_QUERY_LEN}\n * guard as the automatic pass so short queries don't match random hex.\n *\n *   list.filter((x) => x.name.toLowerCase().includes(q) || idMatchesQuery(x, q))\n *\n * Prefer migrating the callsite to `filterAndSortBySearch` (which does this for\n * free); reach for this only when an existing custom sort must be preserved.\n */\nexport function idMatchesQuery(item: unknown, query: string): boolean {\n  const q = query.trim().toLowerCase();\n  if (q.length < MIN_AUTO_ID_QUERY_LEN) return false;\n  const id = getStringId(item);\n  return id != null && id.toLowerCase().includes(q);\n}\n\n/**\n * Filter out non-matches and sort remaining items by descending relevance.\n * Stable with respect to the original order when two items tie.\n */\nexport function filterAndSortBySearch<T>(\n  items: readonly T[],\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): T[] {\n  const trimmed = query.trim();\n  if (!trimmed) return items.slice();\n\n  const scored: { item: T; score: number; idx: number }[] = [];\n  for (let i = 0; i < items.length; i++) {\n    const item = items[i] as T;\n    const score = computeSearchScore(item, trimmed, fields);\n    if (score > 0) scored.push({ item, score, idx: i });\n  }\n  scored.sort((a, b) => (b.score - a.score) || (a.idx - b.idx));\n  return scored.map((s) => s.item);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0DA,IAAM,eAGF;AAAA,EACF,OAAO,EAAE,OAAO,KAAO,YAAY,KAAM,UAAU,IAAK;AAAA,EACxD,UAAU,EAAE,OAAO,KAAM,YAAY,KAAM,UAAU,IAAI;AAAA,EACzD,MAAM,EAAE,OAAO,KAAM,YAAY,KAAK,UAAU,IAAI;AAAA,EACpD,KAAK,EAAE,OAAO,KAAK,YAAY,KAAK,UAAU,IAAI;AAAA,EAClD,MAAM,EAAE,OAAO,KAAK,YAAY,KAAK,UAAU,IAAI;AAAA,EACnD,IAAI,EAAE,OAAO,KAAK,YAAY,IAAI,UAAU,GAAG;AACjD;AAQA,IAAM,wBAAwB;AAG9B,SAAS,YAAY,MAA8B;AACjD,MAAI,QAAQ,OAAO,SAAS,YAAY,QAAQ,MAAM;AACpD,UAAM,KAAM,KAA0B;AACtC,QAAI,OAAO,OAAO,YAAY,GAAG,SAAS,EAAG,QAAO;AAAA,EACtD;AACA,SAAO;AACT;AAEA,SAAS,aAAa,OAAmC;AACvD,MAAI,MAAM,WAAW,YAAY,MAAM,SAAS,MAAM;AACpD,WAAO;AAAA,MACL,OAAO,MAAM,SAAS;AAAA,MACtB,YAAY,MAAM,cAAc;AAAA,MAChC,UAAU,MAAM,YAAY;AAAA,IAC9B;AAAA,EACF;AACA,SAAO,aAAa,MAAM,UAAU,MAAM;AAC5C;AAEA,SAAS,WACP,OACA,GACA,OACQ;AACR,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,IAAI,MAAM,YAAY;AAC5B,MAAI,MAAM,EAAG,QAAO,MAAM;AAC1B,MAAI,EAAE,WAAW,CAAC,EAAG,QAAO,MAAM;AAClC,MAAI,EAAE,SAAS,CAAC,EAAG,QAAO,MAAM;AAChC,SAAO;AACT;AAUO,SAAS,mBACd,MACA,OACA,QACQ;AACR,QAAM,UAAU,MAAM,KAAK;AAC3B,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,IAAI,QAAQ,YAAY;AAE9B,MAAI,QAAQ;AACZ,SAAO,QAAQ,CAAC,OAAO,QAAQ;AAC7B,UAAM,MAAM,MAAM,IAAI,IAAI;AAC1B,QAAI,OAAO,KAAM;AACjB,UAAM,QAAQ,aAAa,KAAmC;AAE9D,QAAI,OAAO;AACX,QAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,iBAAW,KAAK,KAAK;AACnB,YAAI,OAAO,MAAM,SAAU;AAC3B,cAAM,IAAI,WAAW,GAAG,GAAG,KAAK;AAChC,YAAI,IAAI,KAAM,QAAO;AAAA,MACvB;AAAA,IACF,WAAW,OAAO,QAAQ,UAAU;AAClC,aAAO,WAAW,KAAK,GAAG,KAAK;AAAA,IACjC;AAEA,QAAI,OAAO,GAAG;AAEZ,eAAS,QAAQ,OAAO,SAAS;AAAA,IACnC;AAAA,EACF,CAAC;AAOD,QAAM,gBAAgB,OAAO,KAAK,CAAC,MAAM,EAAE,WAAW,IAAI;AAC1D,MAAI,CAAC,iBAAiB,EAAE,UAAU,uBAAuB;AACvD,UAAM,KAAK,YAAY,IAAI;AAC3B,QAAI,IAAI;AACN,eAAS,WAAW,IAAI,GAAG,aAAa,EAAE;AAAA,IAC5C;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,cACd,MACA,OACA,QACS;AACT,SAAO,mBAAmB,MAAM,OAAO,MAAM,IAAI;AACnD;AAaO,SAAS,eAAe,MAAe,OAAwB;AACpE,QAAM,IAAI,MAAM,KAAK,EAAE,YAAY;AACnC,MAAI,EAAE,SAAS,sBAAuB,QAAO;AAC7C,QAAM,KAAK,YAAY,IAAI;AAC3B,SAAO,MAAM,QAAQ,GAAG,YAAY,EAAE,SAAS,CAAC;AAClD;AAMO,SAAS,sBACd,OACA,OACA,QACK;AACL,QAAM,UAAU,MAAM,KAAK;AAC3B,MAAI,CAAC,QAAS,QAAO,MAAM,MAAM;AAEjC,QAAM,SAAoD,CAAC;AAC3D,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,QAAQ,mBAAmB,MAAM,SAAS,MAAM;AACtD,QAAI,QAAQ,EAAG,QAAO,KAAK,EAAE,MAAM,OAAO,KAAK,EAAE,CAAC;AAAA,EACpD;AACA,SAAO,KAAK,CAAC,GAAG,MAAO,EAAE,QAAQ,EAAE,SAAW,EAAE,MAAM,EAAE,GAAI;AAC5D,SAAO,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI;AACjC;","names":[]}

package/dist/search-scoring.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Relevance-weighted search scoring.
+ *
+ * Use instead of the naive `name.includes(q) || description.includes(q)` pattern
+ * so that title/name matches rank above description matches, and exact/prefix
+ * matches rank above partial ones.
+ *
+ * ── Quick start ────────────────────────────────────────────────────────────────
+ *   const filtered = filterAndSortBySearch(items, query, [
+ *     { get: (t) => t.name, weight: "title" },
+ *     { get: (t) => t.description, weight: "body" },
+ *     { get: (t) => t.tags, weight: "tag" },
+ *   ]);
+ *
+ * ── Weight tiers (higher = more important field) ──────────────────────────────
+ *   title    — the primary identifier (name, label, subject)
+ *   subtitle — secondary identifier (vendor, author, category name)
+ *   body     — long-form descriptive text (description, summary)
+ *   tag      — tag/category labels
+ *   meta     — weak metadata (modelId, type)
+ *   id       — raw identifiers (uuid, slug) — only useful for pasted-id lookups
+ *
+ * Within each field, an EXACT match > STARTS-WITH match > INCLUDES match.
+ * Fields declared first are a slight tiebreaker (via field-index bonus).
+ *
+ * ── Automatic id matching ─────────────────────────────────────────────────────
+ * Every item with a string `id` is ALSO matched against the query at the `id`
+ * weight tier, automatically — you do NOT need to declare an id field. This
+ * means a user can paste a full or partial UUID into ANY search box wired to
+ * this helper and find the record. It kicks in from {@link MIN_AUTO_ID_QUERY_LEN}
+ * characters up (so short queries don't match random hex). Declare an explicit
+ * `{ weight: "id" }` field only if you want id matching at any length / on a
+ * non-`id` property; doing so opts that callsite out of the automatic pass.
+ */
+type SearchFieldWeight = "title" | "subtitle" | "body" | "tag" | "meta" | "id" | "custom";
+interface SearchFieldConfig<T> {
+    /**
+     * Extracts the value(s) from the item. Return a string, an array of strings,
+     * or null/undefined. Arrays score based on the best-matching element.
+     */
+    get: (item: T) => string | string[] | null | undefined;
+    /** Field importance tier. Defaults to "body". */
+    weight?: SearchFieldWeight;
+    /** Optional override for custom tiers. Ignored when `weight` is preset. */
+    exact?: number;
+    startsWith?: number;
+    includes?: number;
+}
+/**
+ * Compute a weighted relevance score for `item` against `query`.
+ * Returns 0 if there is no match — callers can treat `> 0` as a match predicate.
+ *
+ * Within each field, multiple values (e.g. tags) contribute the BEST match,
+ * not the sum, so an item with many tags doesn't unfairly outrank one with a
+ * single exact title match.
+ */
+declare function computeSearchScore<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): number;
+declare function matchesSearch<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): boolean;
+/**
+ * Drop-in id-match for hand-rolled `.filter()` predicates that can't (yet) move
+ * onto {@link filterAndSortBySearch}. Returns true when `query` is a substring
+ * of the item's string `id`, applying the same {@link MIN_AUTO_ID_QUERY_LEN}
+ * guard as the automatic pass so short queries don't match random hex.
+ *
+ *   list.filter((x) => x.name.toLowerCase().includes(q) || idMatchesQuery(x, q))
+ *
+ * Prefer migrating the callsite to `filterAndSortBySearch` (which does this for
+ * free); reach for this only when an existing custom sort must be preserved.
+ */
+declare function idMatchesQuery(item: unknown, query: string): boolean;
+/**
+ * Filter out non-matches and sort remaining items by descending relevance.
+ * Stable with respect to the original order when two items tie.
+ */
+declare function filterAndSortBySearch<T>(items: readonly T[], query: string, fields: SearchFieldConfig<T>[]): T[];
+
+export { type SearchFieldConfig, type SearchFieldWeight, computeSearchScore, filterAndSortBySearch, idMatchesQuery, matchesSearch };

package/dist/search-scoring.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Relevance-weighted search scoring.
+ *
+ * Use instead of the naive `name.includes(q) || description.includes(q)` pattern
+ * so that title/name matches rank above description matches, and exact/prefix
+ * matches rank above partial ones.
+ *
+ * ── Quick start ────────────────────────────────────────────────────────────────
+ *   const filtered = filterAndSortBySearch(items, query, [
+ *     { get: (t) => t.name, weight: "title" },
+ *     { get: (t) => t.description, weight: "body" },
+ *     { get: (t) => t.tags, weight: "tag" },
+ *   ]);
+ *
+ * ── Weight tiers (higher = more important field) ──────────────────────────────
+ *   title    — the primary identifier (name, label, subject)
+ *   subtitle — secondary identifier (vendor, author, category name)
+ *   body     — long-form descriptive text (description, summary)
+ *   tag      — tag/category labels
+ *   meta     — weak metadata (modelId, type)
+ *   id       — raw identifiers (uuid, slug) — only useful for pasted-id lookups
+ *
+ * Within each field, an EXACT match > STARTS-WITH match > INCLUDES match.
+ * Fields declared first are a slight tiebreaker (via field-index bonus).
+ *
+ * ── Automatic id matching ─────────────────────────────────────────────────────
+ * Every item with a string `id` is ALSO matched against the query at the `id`
+ * weight tier, automatically — you do NOT need to declare an id field. This
+ * means a user can paste a full or partial UUID into ANY search box wired to
+ * this helper and find the record. It kicks in from {@link MIN_AUTO_ID_QUERY_LEN}
+ * characters up (so short queries don't match random hex). Declare an explicit
+ * `{ weight: "id" }` field only if you want id matching at any length / on a
+ * non-`id` property; doing so opts that callsite out of the automatic pass.
+ */
+type SearchFieldWeight = "title" | "subtitle" | "body" | "tag" | "meta" | "id" | "custom";
+interface SearchFieldConfig<T> {
+    /**
+     * Extracts the value(s) from the item. Return a string, an array of strings,
+     * or null/undefined. Arrays score based on the best-matching element.
+     */
+    get: (item: T) => string | string[] | null | undefined;
+    /** Field importance tier. Defaults to "body". */
+    weight?: SearchFieldWeight;
+    /** Optional override for custom tiers. Ignored when `weight` is preset. */
+    exact?: number;
+    startsWith?: number;
+    includes?: number;
+}
+/**
+ * Compute a weighted relevance score for `item` against `query`.
+ * Returns 0 if there is no match — callers can treat `> 0` as a match predicate.
+ *
+ * Within each field, multiple values (e.g. tags) contribute the BEST match,
+ * not the sum, so an item with many tags doesn't unfairly outrank one with a
+ * single exact title match.
+ */
+declare function computeSearchScore<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): number;
+declare function matchesSearch<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): boolean;
+/**
+ * Drop-in id-match for hand-rolled `.filter()` predicates that can't (yet) move
+ * onto {@link filterAndSortBySearch}. Returns true when `query` is a substring
+ * of the item's string `id`, applying the same {@link MIN_AUTO_ID_QUERY_LEN}
+ * guard as the automatic pass so short queries don't match random hex.
+ *
+ *   list.filter((x) => x.name.toLowerCase().includes(q) || idMatchesQuery(x, q))
+ *
+ * Prefer migrating the callsite to `filterAndSortBySearch` (which does this for
+ * free); reach for this only when an existing custom sort must be preserved.
+ */
+declare function idMatchesQuery(item: unknown, query: string): boolean;
+/**
+ * Filter out non-matches and sort remaining items by descending relevance.
+ * Stable with respect to the original order when two items tie.
+ */
+declare function filterAndSortBySearch<T>(items: readonly T[], query: string, fields: SearchFieldConfig<T>[]): T[];
+
+export { type SearchFieldConfig, type SearchFieldWeight, computeSearchScore, filterAndSortBySearch, idMatchesQuery, matchesSearch };

package/dist/search-scoring.js

@@ -0,0 +1,95 @@
+// src/search-scoring.ts
+var WEIGHT_TABLE = {
+  title: { exact: 1e4, startsWith: 5e3, includes: 2e3 },
+  subtitle: { exact: 2e3, startsWith: 1e3, includes: 500 },
+  body: { exact: 1e3, startsWith: 600, includes: 400 },
+  tag: { exact: 500, startsWith: 400, includes: 300 },
+  meta: { exact: 200, startsWith: 150, includes: 100 },
+  id: { exact: 100, startsWith: 75, includes: 50 }
+};
+var MIN_AUTO_ID_QUERY_LEN = 3;
+function getStringId(item) {
+  if (item && typeof item === "object" && "id" in item) {
+    const id = item.id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return null;
+}
+function resolveTiers(field) {
+  if (field.weight === "custom" || field.exact != null) {
+    return {
+      exact: field.exact ?? 0,
+      startsWith: field.startsWith ?? 0,
+      includes: field.includes ?? 0
+    };
+  }
+  return WEIGHT_TABLE[field.weight ?? "body"];
+}
+function scoreValue(value, q, tiers) {
+  if (!value) return 0;
+  const v = value.toLowerCase();
+  if (v === q) return tiers.exact;
+  if (v.startsWith(q)) return tiers.startsWith;
+  if (v.includes(q)) return tiers.includes;
+  return 0;
+}
+function computeSearchScore(item, query, fields) {
+  const trimmed = query.trim();
+  if (!trimmed) return 0;
+  const q = trimmed.toLowerCase();
+  let total = 0;
+  fields.forEach((field, idx) => {
+    const raw = field.get(item);
+    if (raw == null) return;
+    const tiers = resolveTiers(field);
+    let best = 0;
+    if (Array.isArray(raw)) {
+      for (const v of raw) {
+        if (typeof v !== "string") continue;
+        const s = scoreValue(v, q, tiers);
+        if (s > best) best = s;
+      }
+    } else if (typeof raw === "string") {
+      best = scoreValue(raw, q, tiers);
+    }
+    if (best > 0) {
+      total += best + (fields.length - idx);
+    }
+  });
+  const hasExplicitId = fields.some((f) => f.weight === "id");
+  if (!hasExplicitId && q.length >= MIN_AUTO_ID_QUERY_LEN) {
+    const id = getStringId(item);
+    if (id) {
+      total += scoreValue(id, q, WEIGHT_TABLE.id);
+    }
+  }
+  return total;
+}
+function matchesSearch(item, query, fields) {
+  return computeSearchScore(item, query, fields) > 0;
+}
+function idMatchesQuery(item, query) {
+  const q = query.trim().toLowerCase();
+  if (q.length < MIN_AUTO_ID_QUERY_LEN) return false;
+  const id = getStringId(item);
+  return id != null && id.toLowerCase().includes(q);
+}
+function filterAndSortBySearch(items, query, fields) {
+  const trimmed = query.trim();
+  if (!trimmed) return items.slice();
+  const scored = [];
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const score = computeSearchScore(item, trimmed, fields);
+    if (score > 0) scored.push({ item, score, idx: i });
+  }
+  scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+  return scored.map((s) => s.item);
+}
+export {
+  computeSearchScore,
+  filterAndSortBySearch,
+  idMatchesQuery,
+  matchesSearch
+};
+//# sourceMappingURL=search-scoring.js.map

package/dist/search-scoring.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/search-scoring.ts"],"sourcesContent":["/**\n * Relevance-weighted search scoring.\n *\n * Use instead of the naive `name.includes(q) || description.includes(q)` pattern\n * so that title/name matches rank above description matches, and exact/prefix\n * matches rank above partial ones.\n *\n * ── Quick start ────────────────────────────────────────────────────────────────\n *   const filtered = filterAndSortBySearch(items, query, [\n *     { get: (t) => t.name, weight: \"title\" },\n *     { get: (t) => t.description, weight: \"body\" },\n *     { get: (t) => t.tags, weight: \"tag\" },\n *   ]);\n *\n * ── Weight tiers (higher = more important field) ──────────────────────────────\n *   title    — the primary identifier (name, label, subject)\n *   subtitle — secondary identifier (vendor, author, category name)\n *   body     — long-form descriptive text (description, summary)\n *   tag      — tag/category labels\n *   meta     — weak metadata (modelId, type)\n *   id       — raw identifiers (uuid, slug) — only useful for pasted-id lookups\n *\n * Within each field, an EXACT match > STARTS-WITH match > INCLUDES match.\n * Fields declared first are a slight tiebreaker (via field-index bonus).\n *\n * ── Automatic id matching ─────────────────────────────────────────────────────\n * Every item with a string `id` is ALSO matched against the query at the `id`\n * weight tier, automatically — you do NOT need to declare an id field. This\n * means a user can paste a full or partial UUID into ANY search box wired to\n * this helper and find the record. It kicks in from {@link MIN_AUTO_ID_QUERY_LEN}\n * characters up (so short queries don't match random hex). Declare an explicit\n * `{ weight: \"id\" }` field only if you want id matching at any length / on a\n * non-`id` property; doing so opts that callsite out of the automatic pass.\n */\n\nexport type SearchFieldWeight =\n  | \"title\"\n  | \"subtitle\"\n  | \"body\"\n  | \"tag\"\n  | \"meta\"\n  | \"id\"\n  | \"custom\";\n\nexport interface SearchFieldConfig<T> {\n  /**\n   * Extracts the value(s) from the item. Return a string, an array of strings,\n   * or null/undefined. Arrays score based on the best-matching element.\n   */\n  get: (item: T) => string | string[] | null | undefined;\n  /** Field importance tier. Defaults to \"body\". */\n  weight?: SearchFieldWeight;\n  /** Optional override for custom tiers. Ignored when `weight` is preset. */\n  exact?: number;\n  startsWith?: number;\n  includes?: number;\n}\n\nconst WEIGHT_TABLE: Record<\n  Exclude<SearchFieldWeight, \"custom\">,\n  { exact: number; startsWith: number; includes: number }\n> = {\n  title: { exact: 10000, startsWith: 5000, includes: 2000 },\n  subtitle: { exact: 2000, startsWith: 1000, includes: 500 },\n  body: { exact: 1000, startsWith: 600, includes: 400 },\n  tag: { exact: 500, startsWith: 400, includes: 300 },\n  meta: { exact: 200, startsWith: 150, includes: 100 },\n  id: { exact: 100, startsWith: 75, includes: 50 },\n};\n\n/**\n * Below this query length we do NOT auto-match the row `id`. A 1–2 char query\n * is almost always a substring of *some* hex chars in *every* UUID, so matching\n * id at that length would flood results with the whole table. From 3 chars up a\n * partial-UUID paste is selective enough to be a real lookup.\n */\nconst MIN_AUTO_ID_QUERY_LEN = 3;\n\n/** Pull a non-empty string `id` off an item, or null if it has none. */\nfunction getStringId(item: unknown): string | null {\n  if (item && typeof item === \"object\" && \"id\" in item) {\n    const id = (item as { id?: unknown }).id;\n    if (typeof id === \"string\" && id.length > 0) return id;\n  }\n  return null;\n}\n\nfunction resolveTiers(field: SearchFieldConfig<unknown>) {\n  if (field.weight === \"custom\" || field.exact != null) {\n    return {\n      exact: field.exact ?? 0,\n      startsWith: field.startsWith ?? 0,\n      includes: field.includes ?? 0,\n    };\n  }\n  return WEIGHT_TABLE[field.weight ?? \"body\"];\n}\n\nfunction scoreValue(\n  value: string,\n  q: string,\n  tiers: { exact: number; startsWith: number; includes: number },\n): number {\n  if (!value) return 0;\n  const v = value.toLowerCase();\n  if (v === q) return tiers.exact;\n  if (v.startsWith(q)) return tiers.startsWith;\n  if (v.includes(q)) return tiers.includes;\n  return 0;\n}\n\n/**\n * Compute a weighted relevance score for `item` against `query`.\n * Returns 0 if there is no match — callers can treat `> 0` as a match predicate.\n *\n * Within each field, multiple values (e.g. tags) contribute the BEST match,\n * not the sum, so an item with many tags doesn't unfairly outrank one with a\n * single exact title match.\n */\nexport function computeSearchScore<T>(\n  item: T,\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): number {\n  const trimmed = query.trim();\n  if (!trimmed) return 0;\n  const q = trimmed.toLowerCase();\n\n  let total = 0;\n  fields.forEach((field, idx) => {\n    const raw = field.get(item);\n    if (raw == null) return;\n    const tiers = resolveTiers(field as SearchFieldConfig<unknown>);\n\n    let best = 0;\n    if (Array.isArray(raw)) {\n      for (const v of raw) {\n        if (typeof v !== \"string\") continue;\n        const s = scoreValue(v, q, tiers);\n        if (s > best) best = s;\n      }\n    } else if (typeof raw === \"string\") {\n      best = scoreValue(raw, q, tiers);\n    }\n\n    if (best > 0) {\n      // Tiny bias so that when two fields tie, the one declared first wins.\n      total += best + (fields.length - idx);\n    }\n  });\n\n  // Auto-match the row's UUID `id` against EVERY search box. A user can paste a\n  // full or partial id and find the record, without each callsite remembering\n  // to declare an id field. Skipped when the caller already declared an\n  // explicit `weight: \"id\"` field (so we don't double-score), and gated on a\n  // minimum query length so short queries don't match random hex substrings.\n  const hasExplicitId = fields.some((f) => f.weight === \"id\");\n  if (!hasExplicitId && q.length >= MIN_AUTO_ID_QUERY_LEN) {\n    const id = getStringId(item);\n    if (id) {\n      total += scoreValue(id, q, WEIGHT_TABLE.id);\n    }\n  }\n\n  return total;\n}\n\nexport function matchesSearch<T>(\n  item: T,\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): boolean {\n  return computeSearchScore(item, query, fields) > 0;\n}\n\n/**\n * Drop-in id-match for hand-rolled `.filter()` predicates that can't (yet) move\n * onto {@link filterAndSortBySearch}. Returns true when `query` is a substring\n * of the item's string `id`, applying the same {@link MIN_AUTO_ID_QUERY_LEN}\n * guard as the automatic pass so short queries don't match random hex.\n *\n *   list.filter((x) => x.name.toLowerCase().includes(q) || idMatchesQuery(x, q))\n *\n * Prefer migrating the callsite to `filterAndSortBySearch` (which does this for\n * free); reach for this only when an existing custom sort must be preserved.\n */\nexport function idMatchesQuery(item: unknown, query: string): boolean {\n  const q = query.trim().toLowerCase();\n  if (q.length < MIN_AUTO_ID_QUERY_LEN) return false;\n  const id = getStringId(item);\n  return id != null && id.toLowerCase().includes(q);\n}\n\n/**\n * Filter out non-matches and sort remaining items by descending relevance.\n * Stable with respect to the original order when two items tie.\n */\nexport function filterAndSortBySearch<T>(\n  items: readonly T[],\n  query: string,\n  fields: SearchFieldConfig<T>[],\n): T[] {\n  const trimmed = query.trim();\n  if (!trimmed) return items.slice();\n\n  const scored: { item: T; score: number; idx: number }[] = [];\n  for (let i = 0; i < items.length; i++) {\n    const item = items[i] as T;\n    const score = computeSearchScore(item, trimmed, fields);\n    if (score > 0) scored.push({ item, score, idx: i });\n  }\n  scored.sort((a, b) => (b.score - a.score) || (a.idx - b.idx));\n  return scored.map((s) => s.item);\n}\n"],"mappings":"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","names":[]}