@voltro/plugin-search 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { ColumnDefinition } from '@voltro/database';
+import { DataStore } from '@voltro/database';
+import { PluginChangeEvent } from '@voltro/protocol';
+import { TableIndex } from '@voltro/database';
+import { TableLike } from '@voltro/database';
+import { VoidIfEmpty } from 'effect/Types';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** Algolia. Native: filters (facetFilters + numericFilters), facets
+ *  (`facets`→`facets` response), highlighting (`_highlightResult`), typo
+ *  tolerance (`typoTolerance`), engine-param passthrough.
+ *  DEGRADED: like Meili, no numeric edit-distance knob — `fuzziness:0` maps to
+ *  `typoTolerance:false`; other values keep Algolia's built-in tolerance. */
+export declare const algoliaBackend: (cfg: VendorConfig) => SearchBackend;
+
+/** Apply one ChangeEvent to the backend (pure-ish; exported for tests). */
+export declare const applyChange: (backend: SearchBackend, spec: IndexSpec, event: PluginChangeEvent) => Promise<void>;
+
+/** Seed an index from existing rows (call from a `*.startup.tsx` or a CLI). */
+export declare const backfillIndex: (backend: SearchBackend, spec: IndexSpec, rows: ReadonlyArray<Record<string, unknown>>) => Promise<number>;
+
+/**
+ * DataStore-backed stats. Each replica owns one row per index (keyed by
+ * `replicaId`). A counter bump is a compare-and-set loop on THAT row (mirror of
+ * `plugin-billing`'s usage-store CAS): read `synced`/`removed`, conditionally
+ * `updateMany` gated on the read value, `insertIgnore` the first time. Reads
+ * aggregate every replica's row for the index.
+ */
+export declare const dataStoreStatsStore: (store: DataStore, replicaId?: string) => StatsStore;
+
+/** field → (value → count). Present only for the requested `facets`. */
+export declare type FacetCounts = Record<string, Record<string, number>>;
+
+/** Typo-tolerance knob: a max edit distance (0 = exact), or `'auto'` to let the
+ *  engine pick per-term length. Memory approximates `'auto'` as distance 1–2. */
+export declare type Fuzziness = number | 'auto';
+
+export declare interface HighlightSpec {
+    /** Fields to highlight. Omit / empty ⇒ every text field the engine indexes. */
+    readonly fields?: ReadonlyArray<string>;
+    /** Wrapping tags around a matched term. Default `<mark>`/`</mark>`. */
+    readonly preTag?: string;
+    readonly postTag?: string;
+}
+
+export declare interface IndexSpec {
+    /** Target index/collection name in the backend. */
+    readonly index: string;
+    /** Map a table row → a flat search doc (must include `id`). */
+    readonly map: (row: Record<string, unknown>) => SearchDoc;
+    /** Doc field carrying the tenant id — when set, `search.query` auto-filters
+     *  to the caller's tenant (no cross-tenant leakage). */
+    readonly tenantField?: string;
+}
+
+/** Aggregated, cross-replica stats for one index — the exact wire shape the
+ *  `/indexes` inspect endpoint + the dashboard panel already consume. */
+export declare interface IndexStats {
+    readonly synced: number;
+    readonly removed: number;
+    /** The MOST RECENT reindex across all replicas (max of each replica's). */
+    readonly lastReindexAt: string | null;
+    /** Docs seeded by that most-recent reindex. */
+    readonly lastReindexCount: number;
+}
+
+/** Meilisearch. Native: filters (range+negation), facets
+ *  (`facets`→`facetDistribution`), highlighting (`attributesToHighlight`), typo
+ *  tolerance (on by default; `fuzziness:0` disables), engine-param passthrough.
+ *  DEGRADED: Meilisearch has no numeric edit-distance knob — a `fuzziness`
+ *  number other than 0 falls back to its built-in typo tolerance (documented). */
+export declare const meilisearchBackend: (cfg: VendorConfig) => SearchBackend;
+
+/** In-process inverted-ish search: substring (or fuzzy) match over stringified
+ *  doc values + structured filters. Computes facets + highlights ITSELF (it's
+ *  the honest-degradation reference — every feature works, just not at scale).
+ *  Not for scale — but correct + dependency-free, and the right default for
+ *  dev/tests/single-process apps. */
+export declare const memoryBackend: () => SearchBackend;
+
+export declare const memoryStatsStore: () => StatsStore;
+
+/**
+ * Compute the backend filters for a query, FAIL-CLOSED on tenant scoping.
+ * Returns `null` when the caller must see NOTHING: a tenant-scoped index
+ * (`tenantField` set) queried by a caller with no tenant (`tenantId == null`).
+ * A tenant-scoped index gets an `eq(tenantField, tenantId)` clause ANDed into
+ * whatever filters the caller passed; anon on a tenant-scoped index gets an
+ * empty result (not an unfiltered all-tenant query — the cross-tenant leak).
+ */
+export declare const scopeSearchFilters: (tenantField: string | undefined, tenantId: string | null, filters: ReadonlyArray<SearchFilter> | undefined) => ReadonlyArray<SearchFilter> | null;
+
+export declare const SEARCH_STATS_TABLE = "_voltro_search_stats";
+
+export declare interface SearchBackend {
+    readonly upsert: (index: string, docs: ReadonlyArray<SearchDoc>) => Promise<void>;
+    readonly remove: (index: string, ids: ReadonlyArray<string>) => Promise<void>;
+    readonly query: (index: string, query: SearchQuery) => Promise<SearchResult>;
+}
+
+export declare type SearchBackendConfig = 'memory' | SearchBackend | ({
+    readonly engine: 'typesense' | 'meilisearch' | 'algolia';
+} & VendorConfig);
+
+/** Typed failure surfaced by a backend op. Tagged so a caller can discriminate
+ *  a backend outage / bad query from a generic rpc error. `transient` marks a
+ *  retry-worthy failure (network / engine unavailable) vs. a permanent one
+ *  (unsupported query shape). */
+export declare class SearchBackendError extends SearchBackendError_base<{
+    readonly engine: string;
+    readonly op: 'upsert' | 'remove' | 'query';
+    readonly message: string;
+    readonly transient: boolean;
+}> {
+}
+
+declare const SearchBackendError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "SearchBackendError";
+} & Readonly<A>;
+
+export declare interface SearchDoc {
+    readonly id: string;
+    readonly [field: string]: unknown;
+}
+
+export declare interface SearchFilter {
+    readonly field: string;
+    readonly op: SearchFilterOp;
+    /** Scalar for eq/neq/gt/gte/lt/lte; an array for in/nin. */
+    readonly value: SearchFilterValue | ReadonlyArray<SearchFilterValue>;
+}
+
+/** A single filter clause. `op` widens the old equality-only model to range
+ *  (`gt`/`gte`/`lt`/`lte`) and negation (`neq`/`nin`). `in`/`nin` take an
+ *  array value; the scalar ops take a string|number|boolean. */
+export declare type SearchFilterOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin';
+
+declare type SearchFilterValue = string | number | boolean;
+
+/** One hit — the doc plus, when `highlight` was requested and the engine
+ *  supports it, per-field snippet HTML. */
+export declare interface SearchHit {
+    readonly doc: SearchDoc;
+    /** field → snippet with matched terms wrapped. Absent when highlight wasn't
+     *  requested OR the engine doesn't support it (degraded — see per backend). */
+    readonly highlights?: Record<string, string>;
+}
+
+export declare const searchPlugin: (options: SearchPluginOptions) => VoltroPlugin;
+
+export declare interface SearchPluginOptions {
+    readonly backend?: SearchBackendConfig;
+    /** Map of source table → index spec. */
+    readonly indexes: Record<string, IndexSpec>;
+    readonly name?: string;
+}
+
+export declare interface SearchQuery {
+    readonly q: string;
+    readonly limit?: number;
+    /** Skip this many leading hits before returning `limit` — offset paging. */
+    readonly offset?: number;
+    /** Filter clauses ANDed together — equality, range (`gt`/`lte`/…) and
+     *  negation (`neq`/`nin`). Replaces the old equality-only `Record`. */
+    readonly filters?: ReadonlyArray<SearchFilter>;
+    /** Request facet counts for these fields (returned in `SearchResult.facets`). */
+    readonly facets?: ReadonlyArray<string>;
+    /** Request matched-term snippets (returned per-hit in `SearchResult.hits`). */
+    readonly highlight?: HighlightSpec;
+    /** Typo tolerance. Omit ⇒ the engine default (memory: exact substring). */
+    readonly fuzziness?: Fuzziness;
+    /** Escape hatch: forwarded VERBATIM into the engine's search-params object,
+     *  shallow-merged AFTER the mapped params (so it can override them). Ignored
+     *  by the memory backend (nothing to forward to). */
+    readonly engineParams?: Record<string, unknown>;
+}
+
+export declare interface SearchResult {
+    readonly hits: ReadonlyArray<SearchHit>;
+    /** Facet counts for the requested fields. `{}` when none requested or the
+     *  engine can't facet natively (degraded — memory computes them itself). */
+    readonly facets: FacetCounts;
+}
+
+/** `_voltro_search_stats` — one row per (indexName, replicaId). UNIQUE over the
+ *  pair so each replica's create-path `insertIgnore` is idempotent and the CAS
+ *  increment targets exactly its own row (no cross-replica contention). */
+export declare const searchStatsTable: StatsTable;
+
+/** All tables for `extendSchema.tables`. */
+export declare const searchTables: () => ReadonlyArray<StatsTable>;
+
+/** The stats store. All ops key on the index name; the durable impl fans out to
+ *  per-replica rows internally and aggregates on read. */
+export declare interface StatsStore {
+    /** +1 synced (an insert/update mirrored) or +1 removed (a delete). */
+    readonly bump: (index: string, kind: 'synced' | 'removed') => Promise<void>;
+    /** Record a reindex: +count synced AND set lastReindex{At,Count}. */
+    readonly recordReindex: (index: string, count: number, at: string) => Promise<void>;
+    /** Aggregated stats for one index (summed across replicas). */
+    readonly get: (index: string) => Promise<IndexStats>;
+}
+
+declare interface StatsTable extends TableLike {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+}
+
+/** Typesense (self-host / cloud). Native: filters (range+negation), facets,
+ *  highlighting, typo tolerance (`num_typos`), engine-param passthrough. */
+export declare const typesenseBackend: (cfg: VendorConfig) => SearchBackend;
+
+export declare interface VendorConfig {
+    readonly url?: string;
+    readonly host?: string;
+    readonly apiKey: string;
+    /** Algolia application id. */
+    readonly appId?: string;
+}
+
+export { }