@absolutejs/sync 0.3.0 → 0.5.0

package/dist/engine/permissions.d.ts

@@ -0,0 +1,51 @@
+import type { CollectionContext } from './collection';
+/**
+ * Declarative, row-level access control keyed by table — the engine enforces it,
+ * so a rule lives in one place instead of being restated across a collection's
+ * `authorize` (gate), `hydrate` (DB filter), and `match` (incremental filter).
+ * This is the BYO-database analogue of Convex/Zero permissions: plain predicate
+ * functions over `(ctx, row)`, applied uniformly to reads and writes.
+ */
+/**
+ * A row-level read rule: may `ctx` see `row`? Return `true` to allow. The engine
+ * applies it to every row it would emit for the table — the initial snapshot, an
+ * incremental diff, a catch-up diff, and the one-shot hydrate — and to the reads
+ * a reactive query makes through `ctx.db`. So a row a caller can't see never
+ * reaches them, even if the collection's `hydrate`/`match` are too loose.
+ */
+export type ReadRule<Row = unknown, Ctx = CollectionContext> = (ctx: Ctx, row: Row) => boolean;
+/**
+ * A row-level write rule: may `ctx` perform this write? Return `true` to allow; a
+ * `false` rejects the mutation with `UnauthorizedError`, rolling back its
+ * transaction. For `insert` the rule sees the row being created. For
+ * `update`/`delete` it sees the *existing* row when the table has a reader with
+ * `get` (so the check can't be spoofed by the client payload), otherwise the row
+ * passed to the action.
+ */
+export type WriteRule<Row = unknown, Ctx = CollectionContext> = (ctx: Ctx, row: Row) => boolean;
+/** Declarative permissions for one table's rows. An omitted rule allows. */
+export type TablePermissions<Row = unknown, Ctx = CollectionContext> = {
+    /** Who may read a row — filters every row the engine emits for this table. */
+    read?: ReadRule<Row, Ctx>;
+    /** Who may insert a row. Falls back to {@link TablePermissions.write}. */
+    insert?: WriteRule<Row, Ctx>;
+    /** Who may update a row. Falls back to {@link TablePermissions.write}. */
+    update?: WriteRule<Row, Ctx>;
+    /** Who may delete a row. Falls back to {@link TablePermissions.write}. */
+    delete?: WriteRule<Row, Ctx>;
+    /** Default write rule for any of insert/update/delete without a specific one. */
+    write?: WriteRule<Row, Ctx>;
+};
+/** A `table` → {@link TablePermissions} map. */
+export type PermissionsDefinition<Ctx = CollectionContext> = Record<string, TablePermissions<any, Ctx>>;
+/**
+ * Define declarative, row-level permissions keyed by table. Identity at runtime —
+ * it exists for type inference. Pass to `createSyncEngine({ permissions })` or
+ * register incrementally with `engine.registerPermissions(table, rules)`.
+ *
+ * Scope: read rules are enforced for single-table `view` collections and for the
+ * reads a reactive query makes through `ctx.db`; join/graph collections scope via
+ * their own `hydrate`/`match`. Write rules are enforced in
+ * `actions.insert/update/delete` (not the low-level `actions.change`).
+ */
+export declare const definePermissions: <Ctx = CollectionContext>(permissions: PermissionsDefinition<Ctx>) => PermissionsDefinition<Ctx>;

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

@@ -2,6 +2,8 @@ import type { CollectionContext, CollectionDefinition, JoinCollectionDefinition
 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';
 /**
@@ -45,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.
@@ -96,6 +104,13 @@ export type SyncEngine = {
      * ORM). Required for every table a reactive query reads.
      */
     registerReader: <Ctx = CollectionContext>(table: string, reader: TableReader<Ctx>) => void;
+    /**
+     * Register declarative, row-level permissions for a `table` (see
+     * {@link definePermissions}). Read rules filter every row the engine emits for
+     * the table; write rules gate `actions.insert/update/delete`. Equivalent to a
+     * `permissions` entry on {@link createSyncEngine}.
+     */
+    registerPermissions: <Row = unknown, Ctx = CollectionContext>(table: string, rules: TablePermissions<Row, Ctx>) => void;
     /**
      * Run a registered mutation: authorize, invoke its handler (which writes and
      * emits changes via `applyChange`), and resolve with the handler's result.
@@ -118,6 +133,15 @@ export type SyncEngineOptions = {
      * mutations without a transaction (each writer call is its own DB op).
      */
     transaction?: TransactionRunner;
+    /**
+     * Declarative, row-level permissions keyed by table (see
+     * {@link definePermissions}). Read rules filter every row the engine emits;
+     * write rules gate `actions.insert/update/delete`. Add more later with
+     * {@link SyncEngine.registerPermissions}. Type the rules at the
+     * `definePermissions<YourCtx>(...)` call site; the engine accepts any context
+     * (it threads `ctx` untyped to your rules).
+     */
+    permissions?: PermissionsDefinition<any>;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

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.3.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",