@absolutejs/sync 0.4.0 → 0.5.0

package/dist/engine/search.d.ts

@@ -0,0 +1,61 @@
+import type { CollectionContext } from './collection';
+import type { RowKey } from './types';
+/**
+ * A scored search result: the matched row and its relevance score (higher is
+ * more relevant). A search collection sorts hits descending and tags each
+ * emitted row with its score (see {@link SEARCH_SCORE_FIELD}).
+ */
+export type SearchHit<T> = {
+    row: T;
+    score: number;
+};
+/**
+ * An incremental search index over a row set, queried by `Q` (a string for
+ * full-text, a vector for similarity). Maintained as rows are added/removed, so
+ * the collection that owns it stays live as the corpus changes.
+ * {@link createTextIndex} and {@link createVectorIndex} implement it.
+ */
+export type SearchIndex<T, Q> = {
+    /** Add or replace a row (upsert by key). */
+    add: (row: T) => void;
+    /** Remove a row by key. */
+    remove: (key: RowKey) => void;
+    /** Top-`limit` hits for `query`, sorted by descending score. */
+    search: (query: Q, limit: number) => SearchHit<T>[];
+    /** Number of indexed rows. */
+    size: () => number;
+    /** Drop every indexed row. */
+    clear: () => void;
+};
+/** The field a search collection adds to each emitted row carrying its score. */
+export declare const SEARCH_SCORE_FIELD = "_score";
+export type SearchCollectionDefinition<T, Query = string, Ctx = CollectionContext> = {
+    /** Collection name — its identity for subscribe. */
+    name: string;
+    kind: 'search';
+    /** Source table whose committed changes keep the index live. */
+    table: string;
+    /** Build the (empty) index — e.g. `() => createTextIndex({ ... })`. */
+    index: () => SearchIndex<T, Query>;
+    /** The full corpus to index on first subscribe (e.g. a DB read). */
+    source: () => Promise<Iterable<T>> | Iterable<T>;
+    /** Row identity. */
+    key: (row: T) => RowKey;
+    /** Max results returned. Defaults to 20. */
+    limit?: number;
+    /** Access control: return `false` (or throw) to deny the subscription. */
+    authorize?: (query: Query, ctx: Ctx) => boolean | Promise<boolean>;
+};
+/**
+ * Define a live search collection: an index (full-text via {@link createTextIndex}
+ * or vector via {@link createVectorIndex}) maintained from a source table's
+ * change feed. The subscription's `params` *are* the query — a string for
+ * full-text, a vector for similarity. Register it with
+ * {@link SyncEngine.registerSearch}; the client receives the ranked top-K as a
+ * normal collection, re-ranked live as rows change. Each emitted row carries its
+ * relevance under {@link SEARCH_SCORE_FIELD}, so the client can sort by it.
+ *
+ * The corpus is the whole table; a row-level read permission on the table (see
+ * {@link definePermissions}) still filters a caller's hits.
+ */
+export declare const defineSearchCollection: <T, Query = string, Ctx = CollectionContext>(definition: Omit<SearchCollectionDefinition<T, Query, Ctx>, "kind">) => SearchCollectionDefinition<T, Query, Ctx>;

package/dist/engine/syncEngine.d.ts

@@ -3,6 +3,7 @@ import type { GraphCollectionDefinition } from './graph';
 import type { MutationDefinition, TableWriter, TransactionRunner } from './mutation';
 import type { ReactiveQueryDefinition, TableReader } from './reactive';
 import type { PermissionsDefinition, TablePermissions } from './permissions';
+import type { SearchCollectionDefinition } from './search';
 import type { ClusterBus } from './cluster';
 import type { ChangeSource, RowChange, ViewDiff } from './types';
 /**
@@ -46,6 +47,12 @@ export type SyncEngine = {
     registerJoin: <L, R, Out, P = void, Ctx = CollectionContext>(collection: JoinCollectionDefinition<L, R, Out, P, Ctx>) => void;
     /** Register an operator-graph collection (see {@link defineGraphCollection}). */
     registerGraph: <Out, P = void, Ctx = CollectionContext>(collection: GraphCollectionDefinition<Out, P, Ctx>) => void;
+    /**
+     * Register a live search collection (see {@link defineSearchCollection}): a
+     * full-text or vector index maintained from a source table's change feed and
+     * queried by the subscription's params, returning the ranked top-K live.
+     */
+    registerSearch: <T, Query = string, Ctx = CollectionContext>(collection: SearchCollectionDefinition<T, Query, Ctx>) => void;
     /**
      * Open a live subscription: authorize, hydrate the initial set, and stream
      * diffs as changes arrive. Rejects with {@link UnauthorizedError} on deny.

package/dist/engine/textIndex.d.ts

@@ -0,0 +1,33 @@
+import type { RowKey } from './types';
+import type { SearchIndex } from './search';
+/**
+ * An incremental full-text index with BM25 ranking — the keyword-search half of
+ * the search surface (see {@link createVectorIndex} for semantic search). Pure
+ * and dependency-free: an in-memory inverted index maintained as rows are
+ * added/removed, so a {@link defineSearchCollection} stays live as the corpus
+ * changes. For a large corpus back it with your DB's FTS instead; this is the
+ * BYO, no-extension default.
+ */
+export type TextIndexOptions<T> = {
+    /** Row identity. */
+    key: (row: T) => RowKey;
+    /** Fields whose text is indexed. Their values are stringified and joined. */
+    fields: (keyof T)[];
+    /**
+     * Split text into terms. Defaults to lowercase alphanumeric runs. Provide your
+     * own for stemming, n-grams, or a different alphabet — used for both indexing
+     * and querying, so the two always agree.
+     */
+    tokenize?: (text: string) => string[];
+    /** Terms to drop (e.g. `the`, `a`). Applied after `tokenize`. */
+    stopwords?: Iterable<string>;
+    /** BM25 term-frequency saturation. Defaults to 1.5. */
+    k1?: number;
+    /** BM25 length normalization (0–1). Defaults to 0.75. */
+    b?: number;
+};
+/**
+ * Build an incremental BM25 full-text index over rows of `T`. Implements the
+ * {@link SearchIndex} interface, so it plugs straight into a search collection.
+ */
+export declare const createTextIndex: <T>(options: TextIndexOptions<T>) => SearchIndex<T, string>;

package/dist/engine/vectorIndex.d.ts

@@ -0,0 +1,27 @@
+import type { RowKey } from './types';
+import type { SearchIndex } from './search';
+/**
+ * An incremental vector index for semantic / similarity search — the embeddings
+ * half of the search surface (see {@link createTextIndex} for keyword search).
+ * Pure and dependency-free: an exact (brute-force) k-NN over in-memory vectors,
+ * maintained as rows are added/removed, so a {@link defineSearchCollection}
+ * stays live. Pairs naturally with `@absolutejs/ai` / `@absolutejs/rag` for RAG
+ * retrieval on your own data. Exact search is O(n·d) per query — fine for tens
+ * of thousands of vectors; for more, back it with pgvector and a real ANN index.
+ */
+/** Similarity metric. `cosine`/`dot` rank higher = closer; `euclidean` too (negated distance). */
+export type VectorMetric = 'cosine' | 'dot' | 'euclidean';
+export type VectorIndexOptions<T> = {
+    /** Row identity. */
+    key: (row: T) => RowKey;
+    /** Extract a row's embedding vector. */
+    embedding: (row: T) => number[];
+    /** Similarity metric. Defaults to `cosine`. */
+    metric?: VectorMetric;
+};
+/**
+ * Build an incremental vector index over rows of `T`. Implements the
+ * {@link SearchIndex} interface (queried by a query vector), so it plugs
+ * straight into a search collection.
+ */
+export declare const createVectorIndex: <T>(options: VectorIndexOptions<T>) => SearchIndex<T, number[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/sync",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
 	"repository": {
 		"type": "git",