@voltro/plugin-search 0.85.0 → 0.87.0

package/dist/memoryGuard.js

@@ -0,0 +1,38 @@
+//#region src/memoryGuard.ts
+var e = (e) => e === void 0 || e === "memory" ? "memory" : typeof e.query == "function" ? e.engineKind === "memory" ? "memory" : "custom" : "vendor", t = class extends Error {
+	_tag = "SearchBackendNotDurable";
+	constructor(e) {
+		super(e), this.name = "SearchBackendNotDurable";
+	}
+}, n = [
+	"plugin-search refuses to boot in production on the in-memory backend.",
+	"",
+	"The memory index lives in THIS process's heap. Two consequences, both silent:",
+	"  • every replica holds a different index, so a result depends on which replica served you;",
+	"  • the index starts EMPTY after every restart/deploy, and nothing re-seeds it automatically.",
+	"",
+	"Configure a durable engine in app.config.ts:",
+	"  searchPlugin({ backend: { engine: 'typesense',    url: …, apiKey: … }, indexes })",
+	"  searchPlugin({ backend: { engine: 'meilisearch',  url: …, apiKey: … }, indexes })",
+	"  searchPlugin({ backend: { engine: 'algolia',      appId: …, apiKey: … }, indexes })",
+	"or pass your own `SearchBackend` implementation.",
+	"",
+	"If this deployment really is ONE process that re-seeds its index at startup",
+	"(a `*.startup.tsx` calling `backfillIndex`), say so explicitly:",
+	"  searchPlugin({ singleProcessMemoryIndex: true, indexes })",
+	"That is a claim about your topology, not a mute switch: if a second replica",
+	"ever announces itself, the plugin logs that the claim was contradicted."
+].join("\n"), r = [
+	"plugin-search is running the in-memory backend in production under",
+	"`singleProcessMemoryIndex: true`. Holding you to the two conditions that makes true:",
+	"exactly ONE process serves search, and it re-seeds every index at startup",
+	"(`backfillIndex`) — the index is empty after each restart until it does."
+].join(" "), i = (e) => e.backendKind !== "memory" || !e.production ? { level: "quiet" } : e.singleProcessDeclared ? {
+	level: "note",
+	message: r
+} : {
+	level: "refuse",
+	message: n
+}, a = (e, t) => t ? `search: replica "${e}" joined, but this app declared \`singleProcessMemoryIndex: true\`. That declaration is now false: each replica has its own in-memory index, so search results depend on which one serves the request. Configure a durable backend (typesense / meilisearch / algolia) or run one process.` : `search: replica "${e}" joined while search is served from an in-memory index. Each replica indexes only its OWN writes, so results depend on which replica answers. Configure a durable backend (typesense / meilisearch / algolia) before relying on these results.`;
+//#endregion
+export { t as SearchBackendNotDurable, i as auditMemoryBackend, e as backendKindOf, a as peerObservedWarning };

package/dist/rpc.js

@@ -1,2 +1,57 @@
-import { i as e, n as t, r as n, t as r } from "./rpc-CggQ77CG.js";
-export { r as BASE_NAME, t as SearchFilterSchema, n as queryDescriptor, e as searchRpcClientImports };
+import { SearchFieldRejected as e, SearchIndexNotFound as t } from "./errors.js";
+import { Schema as n } from "effect";
+import { defineAction as r } from "@voltro/protocol";
+//#region src/rpc.ts
+var i = "@voltro/plugin-search", a = n.Union([
+	n.String,
+	n.Number,
+	n.Boolean
+]), o = n.Struct({
+	field: n.String,
+	op: n.Literals([
+		"eq",
+		"neq",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"nin"
+	]),
+	value: n.Union([a, n.Array(a)])
+}), s = n.Struct({
+	fields: n.optional(n.Array(n.String)),
+	preTag: n.optional(n.String),
+	postTag: n.optional(n.String)
+}), c = n.Struct({
+	doc: n.Record(n.String, n.Unknown),
+	highlights: n.optional(n.Record(n.String, n.String))
+}), l = r({
+	name: "search.query",
+	openAccess: "tenant scoping, index registration and field validation are enforced server-side per call; a non-tenant index exposes only what the app's map(row) deliberately indexed",
+	input: n.Struct({
+		index: n.String,
+		q: n.String,
+		limit: n.optional(n.Number),
+		offset: n.optional(n.Number),
+		filters: n.optional(n.Array(o)),
+		facets: n.optional(n.Array(n.String)),
+		highlight: n.optional(s),
+		fuzziness: n.optional(n.Union([n.Number, n.Literal("auto")])),
+		engineParams: n.optional(n.Record(n.String, n.Unknown))
+	}),
+	output: n.Struct({
+		hits: n.Array(c),
+		facets: n.Record(n.String, n.Record(n.String, n.Number))
+	}),
+	error: n.Union([t, e])
+}), u = [{
+	tag: "search.query",
+	kind: "action",
+	import: {
+		module: "@voltro/plugin-search/rpc",
+		name: "queryDescriptor"
+	}
+}];
+//#endregion
+export { i as BASE_NAME, o as SearchFilterSchema, l as queryDescriptor, u as searchRpcClientImports };

package/dist/sanitize.js

@@ -0,0 +1,122 @@
+//#region src/sanitize.ts
+var e = /^[A-Za-z_][A-Za-z0-9_.]*$/, t = (t) => e.test(t), n = (e, n) => {
+	let r = n ? new Set(n) : void 0;
+	for (let [n, i] of e) {
+		if (!t(i)) return {
+			field: i,
+			where: n,
+			reason: "not-an-identifier"
+		};
+		if (r && !r.has(i)) return {
+			field: i,
+			where: n,
+			reason: "not-queryable"
+		};
+	}
+}, r = {
+	typesense: [
+		"per_page",
+		"page",
+		"offset",
+		"limit",
+		"sort_by",
+		"num_typos",
+		"typo_tokens_threshold",
+		"drop_tokens_threshold",
+		"prefix",
+		"prioritize_exact_match",
+		"highlight_start_tag",
+		"highlight_end_tag",
+		"highlight_affix_num_tokens",
+		"snippet_threshold",
+		"max_facet_values"
+	],
+	meilisearch: [
+		"limit",
+		"offset",
+		"page",
+		"hitsPerPage",
+		"sort",
+		"matchingStrategy",
+		"showRankingScore",
+		"rankingScoreThreshold",
+		"distinct",
+		"attributesToHighlight",
+		"highlightPreTag",
+		"highlightPostTag",
+		"attributesToCrop",
+		"cropLength",
+		"cropMarker",
+		"showMatchesPosition"
+	],
+	algolia: [
+		"hitsPerPage",
+		"page",
+		"offset",
+		"length",
+		"typoTolerance",
+		"minWordSizefor1Typo",
+		"minWordSizefor2Typos",
+		"ignorePlurals",
+		"removeStopWords",
+		"queryType",
+		"distinct",
+		"attributesToHighlight",
+		"attributesToSnippet",
+		"snippetEllipsisText",
+		"highlightPreTag",
+		"highlightPostTag"
+	]
+}, i = {
+	typesense: [
+		"filter_by",
+		"q",
+		"preset",
+		"pinned_hits",
+		"hidden_hits",
+		"enable_overrides",
+		"override_tags",
+		"include_fields",
+		"exclude_fields",
+		"vector_query"
+	],
+	meilisearch: [
+		"filter",
+		"q",
+		"attributesToSearchOn",
+		"attributesToRetrieve",
+		"hybrid",
+		"vector",
+		"federation"
+	],
+	algolia: [
+		"filters",
+		"facetFilters",
+		"numericFilters",
+		"tagFilters",
+		"optionalFilters",
+		"query",
+		"restrictSearchableAttributes",
+		"attributesToRetrieve",
+		"enableRules",
+		"ruleContexts",
+		"similarQuery",
+		"aroundLatLng",
+		"insideBoundingBox"
+	]
+}, a = (e, t, n) => {
+	if (!t) return {
+		params: {},
+		appAllowed: {},
+		dropped: []
+	};
+	let a = new Set(i[e]), o = new Set(r[e]), s = new Set(n ?? []), c = {}, l = {}, u = [];
+	for (let [e, n] of Object.entries(t)) a.has(e) ? u.push(e) : o.has(e) ? c[e] = n : s.has(e) ? l[e] = n : u.push(e);
+	return {
+		params: c,
+		appAllowed: l,
+		dropped: u
+	};
+}, o = (e) => r[e];
+//#endregion
+export { e as FIELD_NAME_PATTERN, o as allowedEngineParams, n as firstRejectedField, t as isSafeFieldName, a as sanitizeEngineParams };

package/dist/statsBuffer.js

@@ -0,0 +1,36 @@
+//#region src/statsBuffer.ts
+var e = (e) => {
+	let t = /* @__PURE__ */ new Map(), n = 0, r = !1, i = async () => {
+		if (t.size === 0) return;
+		let r = t;
+		t = /* @__PURE__ */ new Map(), n = 0;
+		for (let [t, n] of r) try {
+			await e.flush(t, {
+				synced: n.synced,
+				removed: n.removed,
+				dropped: n.dropped
+			}, n.scope);
+		} catch {}
+	}, a = setInterval(() => {
+		i();
+	}, Math.max(1, e.intervalMs));
+	return a.unref?.(), {
+		bump: (a, o, s) => {
+			if (r) return;
+			let c = t.get(a);
+			c === void 0 ? t.set(a, {
+				synced: +(o === "synced"),
+				removed: +(o === "removed"),
+				dropped: +(o === "dropped"),
+				scope: s
+			}) : (o === "synced" ? c.synced += 1 : o === "removed" ? c.removed += 1 : c.dropped += 1, c.scope = s), n += 1, n >= e.maxBuffered && i();
+		},
+		flushNow: i,
+		shutdown: async () => {
+			r || (r = !0, clearInterval(a), await i());
+		},
+		pending: () => n
+	};
+}, t = (e) => (t, n, r) => e().add(t, n, r);
+//#endregion
+export { e as makeSearchStatsBuffer, t as statsStoreFlush };

package/dist/statsStore.js

@@ -0,0 +1,163 @@
+import { SearchBackendError as e } from "./backend.js";
+import { and as t, eq as n, id as r, integer as i, table as a, text as o, timestamp as s } from "@voltro/database";
+import { replicaId as c } from "@voltro/protocol/identity";
+//#region src/statsStore.ts
+var l = "_voltro_search_stats", u = () => ({
+	synced: 0,
+	removed: 0,
+	dropped: 0,
+	lastReindexAt: null,
+	lastReindexCount: 0
+}), d = a(l, {
+	id: r({ prefix: "sstat" }),
+	indexName: o().maxLength(191),
+	replicaId: o().maxLength(191),
+	synced: i().default(0),
+	removed: i().default(0),
+	dropped: i().default(0),
+	scope: o().maxLength(8).default("local"),
+	lastReindexAt: s().nullable(),
+	lastReindexCount: i().default(0),
+	updatedAt: s()
+}).unique("bySearchStatsIndexReplica", ["indexName", "replicaId"]).index("bySearchStatsIndex", ["indexName"]), f = () => [d], p = () => {
+	let e = /* @__PURE__ */ new Map(), t = (t) => e.get(t) ?? u();
+	return {
+		bump: async (n, r) => {
+			let i = t(n);
+			e.set(n, r === "synced" ? {
+				...i,
+				synced: i.synced + 1
+			} : r === "removed" ? {
+				...i,
+				removed: i.removed + 1
+			} : {
+				...i,
+				dropped: i.dropped + 1
+			});
+		},
+		add: async (n, r) => {
+			let i = t(n);
+			e.set(n, {
+				...i,
+				synced: i.synced + r.synced,
+				removed: i.removed + r.removed,
+				dropped: i.dropped + r.dropped
+			});
+		},
+		recordReindex: async (n, r, i) => {
+			let a = t(n);
+			e.set(n, {
+				...a,
+				synced: a.synced + r,
+				lastReindexAt: i,
+				lastReindexCount: r
+			});
+		},
+		get: async (e) => t(e)
+	};
+}, m = (e) => ({
+	table: l,
+	predicate: e,
+	order: [],
+	take: void 0,
+	skip: void 0,
+	projection: void 0
+}), h = () => `sstat_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`, g = () => c(), _ = 32, v = (r, i = g()) => {
+	let a = async (e) => (await r.query(m(t(n("indexName", e), n("replicaId", i)))))[0] ?? null, o = async (t) => {
+		try {
+			return await t();
+		} catch (t) {
+			throw t instanceof e ? t : new e({
+				engine: "stats",
+				op: "upsert",
+				message: String(t?.message ?? t),
+				transient: !0
+			});
+		}
+	}, s = (s, c, u, d) => o(async () => {
+		for (let e = 0; e < _; e++) {
+			e > 0 && await new Promise((t) => setTimeout(t, e));
+			let o = await a(s);
+			if (o) {
+				let e = Number(o.synced ?? 0), i = Number(o.removed ?? 0), a = Number(o.dropped ?? 0), s = {
+					synced: e,
+					removed: i,
+					dropped: a,
+					lastReindexAt: o.lastReindexAt ? new Date(o.lastReindexAt).toISOString() : null,
+					lastReindexCount: Number(o.lastReindexCount ?? 0)
+				};
+				if (await r.updateMany("_voltro_search_stats", {
+					...u(s),
+					...c ? { scope: c } : {},
+					updatedAt: /* @__PURE__ */ new Date()
+				}, { where: t(n("id", String(o.id)), n("synced", e), n("removed", i), n("dropped", a)) }) === 1) return;
+			} else {
+				let e = h(), t = await r.insertIgnore(l, {
+					id: e,
+					indexName: s,
+					replicaId: i,
+					synced: 0,
+					removed: 0,
+					dropped: 0,
+					scope: c ?? "local",
+					lastReindexAt: null,
+					lastReindexCount: 0,
+					updatedAt: /* @__PURE__ */ new Date(),
+					...d
+				}, { conflictColumns: ["indexName", "replicaId"] });
+				if (String(t.id) === e) return;
+			}
+		}
+		throw new e({
+			engine: "stats",
+			op: "upsert",
+			message: `search stats: contention on (${s}, ${i}) exceeded ${_} attempts`,
+			transient: !0
+		});
+	});
+	return {
+		bump: (e, t, n) => s(e, n, (e) => t === "synced" ? { synced: e.synced + 1 } : t === "removed" ? { removed: e.removed + 1 } : { dropped: e.dropped + 1 }, t === "synced" ? { synced: 1 } : t === "removed" ? { removed: 1 } : { dropped: 1 }),
+		add: (e, t, n) => s(e, n, (e) => ({
+			synced: e.synced + t.synced,
+			removed: e.removed + t.removed,
+			dropped: e.dropped + t.dropped
+		}), {
+			synced: t.synced,
+			removed: t.removed,
+			dropped: t.dropped
+		}),
+		recordReindex: (e, t, n) => s(e, void 0, (e) => ({
+			synced: e.synced + t,
+			lastReindexAt: new Date(n),
+			lastReindexCount: t
+		}), {
+			synced: t,
+			lastReindexAt: new Date(n),
+			lastReindexCount: t
+		}),
+		get: (e) => o(async () => {
+			let t = await r.query(m(n("indexName", e))), i = t.some((e) => e.scope === "fleet"), a = (e) => {
+				let n = 0;
+				for (let r of t) {
+					let t = Number(r[e] ?? 0);
+					n = i ? Math.max(n, t) : n + t;
+				}
+				return n;
+			}, o = null, s = 0;
+			for (let e of t) {
+				let t = e.lastReindexAt ? new Date(e.lastReindexAt).toISOString() : null;
+				t && (o === null || t > o) && (o = t, s = Number(e.lastReindexCount ?? 0));
+			}
+			return {
+				...u(),
+				synced: a("synced"),
+				removed: a("removed"),
+				dropped: a("dropped"),
+				lastReindexAt: o,
+				lastReindexCount: s
+			};
+		})
+	};
+};
+//#endregion
+export { l as SEARCH_STATS_TABLE, v as dataStoreStatsStore, p as memoryStatsStore, d as searchStatsTable, f as searchTables, u as zeroStats };

package/dist/web.js

@@ -1,4 +1,4 @@
-import { t as e } from "./rpc-CggQ77CG.js";
+import { BASE_NAME as e } from "./rpc.js";
 import { pluginTag as t } from "@voltro/protocol";
 import { useAction as n } from "@voltro/client";
 //#region src/web.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-search",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "Keep an external search index (Typesense / Meilisearch / Algolia) in sync with framework tables via the post-commit ChangeEvent tap, then query it — tenant-scoped, with a backfill path and a useSearch() hook.",
   "keywords": [
     "voltro",
@@ -43,9 +43,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.85.0",
-    "@voltro/database": "0.85.0",
-    "@voltro/protocol": "0.85.0"
+    "@voltro/client": "0.87.0",
+    "@voltro/database": "0.87.0",
+    "@voltro/protocol": "0.87.0"
   },
   "optionalDependencies": {
     "algoliasearch": "^5.59.0",

package/dist/rpc-CggQ77CG.js

@@ -1,64 +0,0 @@
-import { Schema as e } from "effect";
-import { defineAction as t } from "@voltro/protocol";
-//#region src/errors.ts
-var n = class extends e.TaggedError()("SearchIndexNotFound", { index: e.String }) {}, r = class extends e.TaggedError()("SearchFieldRejected", {
-	field: e.String,
-	where: e.Literals([
-		"filter",
-		"facet",
-		"highlight"
-	]),
-	reason: e.Literals(["not-an-identifier", "not-queryable"])
-}) {}, i = "@voltro/plugin-search", a = e.Union([
-	e.String,
-	e.Number,
-	e.Boolean
-]), o = e.Struct({
-	field: e.String,
-	op: e.Literals([
-		"eq",
-		"neq",
-		"gt",
-		"gte",
-		"lt",
-		"lte",
-		"in",
-		"nin"
-	]),
-	value: e.Union([a, e.Array(a)])
-}), s = e.Struct({
-	fields: e.optional(e.Array(e.String)),
-	preTag: e.optional(e.String),
-	postTag: e.optional(e.String)
-}), c = e.Struct({
-	doc: e.Record(e.String, e.Unknown),
-	highlights: e.optional(e.Record(e.String, e.String))
-}), l = t({
-	name: "search.query",
-	openAccess: "tenant scoping, index registration and field validation are enforced server-side per call; a non-tenant index exposes only what the app's map(row) deliberately indexed",
-	input: e.Struct({
-		index: e.String,
-		q: e.String,
-		limit: e.optional(e.Number),
-		offset: e.optional(e.Number),
-		filters: e.optional(e.Array(o)),
-		facets: e.optional(e.Array(e.String)),
-		highlight: e.optional(s),
-		fuzziness: e.optional(e.Union([e.Number, e.Literal("auto")])),
-		engineParams: e.optional(e.Record(e.String, e.Unknown))
-	}),
-	output: e.Struct({
-		hits: e.Array(c),
-		facets: e.Record(e.String, e.Record(e.String, e.Number))
-	}),
-	error: e.Union([n, r])
-}), u = [{
-	tag: "search.query",
-	kind: "action",
-	import: {
-		module: "@voltro/plugin-search/rpc",
-		name: "queryDescriptor"
-	}
-}];
-//#endregion
-export { r as a, u as i, o as n, n as o, l as r, i as t };