@absolutejs/sync 0.0.1 → 0.2.0

package/dist/engine/presence.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Presence — ephemeral, room-scoped state shared over the live socket (who's
+ * online, who's typing, cursor positions). Unlike collections it is **not**
+ * persisted: it lives only while a member is joined, and a member's state is
+ * removed (and peers notified) the moment it leaves or its connection drops.
+ *
+ * A `room` is any string (a document id, a channel). Each `member` is one
+ * participant (typically one connection) with a `state` it owns and updates;
+ * everyone in the room sees the member set and its changes.
+ */
+export type PresenceMember<S = unknown> = {
+    id: string;
+    state: S;
+};
+/** What changed in a room: members that joined, updated state, or left. */
+export type PresenceDiff<S = unknown> = {
+    joined: PresenceMember<S>[];
+    updated: PresenceMember<S>[];
+    left: string[];
+};
+export type PresenceHandle<S> = {
+    /** The room's members at join time (including this one). */
+    members: PresenceMember<S>[];
+    /** Replace this member's state and notify the rest of the room. */
+    set: (state: S) => void;
+    /** Leave the room (remove this member; notify peers). */
+    leave: () => void;
+};
+export type PresenceHub = {
+    /**
+     * Join `room` as `memberId` with `state`; `onDiff` receives every later change
+     * to the room (not this member's own join). Returns the current members and
+     * handles to update/leave.
+     */
+    join: <S>(room: string, memberId: string, state: S, onDiff: (diff: PresenceDiff<S>) => void) => PresenceHandle<S>;
+    /** Snapshot a room's members without joining. */
+    members: <S = unknown>(room: string) => PresenceMember<S>[];
+    /** Number of members in a room (0 if none). */
+    count: (room: string) => number;
+};
+/**
+ * Create an in-process presence hub. Transport-agnostic (no socket import): the
+ * sync connection wires client `presence-*` frames to it and tears down a
+ * connection's memberships on close.
+ */
+export declare const createPresenceHub: () => PresenceHub;

package/dist/engine/reactive.d.ts

@@ -0,0 +1,67 @@
+import type { CollectionContext } from './collection';
+import type { RowKey } from './types';
+/**
+ * Read-set tracking — the reactor. You write a plain query function that reads
+ * through an instrumented `ctx.db`; the engine records which tables it touched
+ * and re-runs it (diffing old vs new) whenever any of those tables change. No
+ * hand-written `match`, no operator graph, no manual change emission for reads:
+ * write a query, it stays live. This is the BYO-database analogue of Convex's
+ * automatic read-set tracking — it works on your own DB because your reads go
+ * through the registered {@link TableReader}s.
+ *
+ * Granularity is table-level for now (a query that read a table re-runs on any
+ * change to it) — the full developer experience, and always correct; key/range
+ * precision is a later optimization.
+ */
+/** How to read a table for reactive queries — register with `registerReader`. */
+export type TableReader<Ctx = unknown> = {
+    /** All rows of the table (the common case; filter in JS in your query). */
+    all: (ctx: Ctx) => Promise<Iterable<unknown>> | Iterable<unknown>;
+    /** Optional point lookup by key. */
+    get?: (key: RowKey, ctx: Ctx) => Promise<unknown> | unknown;
+    /**
+     * Row identity. Provide it to unlock **key-level** read tracking: a query that
+     * only `db.get`s specific rows re-runs solely when one of *those* rows changes
+     * (matched via this `key`), not on every change to the table. Omit and `get`
+     * falls back to a table-level dependency (coarser, still correct).
+     */
+    key?: (row: unknown) => RowKey;
+};
+/** The instrumented data handle passed to a reactive query — reads are tracked. */
+export type ReadHandle = {
+    /** Read all rows of `table` (records a full-table dependency). */
+    all: <T = unknown>(table: string) => Promise<T[]>;
+    /** Read one row of `table` by key (records a row-key dependency). */
+    get: <T = unknown>(table: string, key: RowKey) => Promise<T | undefined>;
+    /**
+     * Read the rows of `table` matching `predicate` (records a **range**
+     * dependency): the query re-runs only when a change matches the predicate now
+     * or was in the matched set before — not on every change to the table. Needs
+     * the table's reader to declare a `key`; without one it falls back to a
+     * full-table dependency. Prefer this over `all().filter(...)` for precision.
+     */
+    where: <T = unknown>(table: string, predicate: (row: T) => boolean) => Promise<T[]>;
+};
+export type ReactiveQueryContext<P, Ctx> = {
+    /** Tracked reads — anything you read here becomes a live dependency. */
+    db: ReadHandle;
+    params: P;
+    ctx: Ctx;
+};
+export type ReactiveQueryDefinition<T, P = void, Ctx = CollectionContext> = {
+    name: string;
+    kind: 'reactive';
+    /** Compute the result set by reading through `ctx.db`; re-run on change. */
+    run: (context: ReactiveQueryContext<P, Ctx>) => Promise<T[]> | T[];
+    /** Result-row identity (used to diff re-runs). */
+    key: (row: T) => RowKey;
+    /** Access control; return false (or throw) to deny the subscription. */
+    authorize?: (params: P, ctx: Ctx) => boolean | Promise<boolean>;
+};
+/**
+ * Define a reactive query: a function that reads through `ctx.db` and is kept
+ * live automatically by read-set tracking. Register it with
+ * {@link SyncEngine.registerReactive} (and the tables it reads with
+ * `registerReader`).
+ */
+export declare const defineReactiveQuery: <T, P = void, Ctx = CollectionContext>(definition: Omit<ReactiveQueryDefinition<T, P, Ctx>, "kind">) => ReactiveQueryDefinition<T, P, Ctx>;

package/dist/engine/routes.d.ts

@@ -0,0 +1,40 @@
+import type { CollectionDefinition } from './collection';
+import type { MutationDefinition } from './mutation';
+import type { SyncEngine } from './syncEngine';
+/**
+ * Eden-native HTTP route helpers (Tier 3). These turn a typed collection /
+ * mutation definition into a plain Elysia route handler — so hydrate and mutate
+ * are ordinary Elysia routes that Eden types end to end, with TypeBox validating
+ * the params/body. The live diff stream stays on the WebSocket (`syncSocket`).
+ *
+ * They import no Elysia: each returns `(context) => Promise<...>`, which you pass
+ * to `.get` / `.post` with a TypeBox `query` / `body` schema. The handler's
+ * return type carries the row / result type, so `treaty<typeof app>()` infers it.
+ */
+/** The slice of an Elysia route context these helpers read. */
+export type SyncRouteContext = {
+    query: unknown;
+    body: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Build a GET handler that hydrates `collection` — authorize, then return its
+ * current rows. The handler returns `Promise<Row[]>`, so Eden infers the row
+ * type from the collection definition; the route's TypeBox `query` schema
+ * validates and types the params.
+ *
+ * @example
+ * .get('/sync/orders', hydrateRoute(engine, ordersCollection, (c) => ({ userId: c.userId })),
+ *      { query: t.Object({ userId: t.Numeric() }) })
+ */
+export declare const hydrateRoute: <Row, Params, Ctx>(engine: SyncEngine, collection: CollectionDefinition<Row, Params, Ctx>, resolveContext?: (context: SyncRouteContext) => Ctx) => (context: SyncRouteContext) => Promise<Row[]>;
+/**
+ * Build a POST handler that runs `mutation`. The handler returns
+ * `Promise<Result>`, so Eden infers the result type; the route's TypeBox `body`
+ * schema validates and types the args.
+ *
+ * @example
+ * .post('/sync/createOrder', mutateRoute(engine, createOrder, (c) => ({ userId: c.userId })),
+ *       { body: t.Object({ total: t.Number() }) })
+ */
+export declare const mutateRoute: <Args, Ctx, Result>(engine: SyncEngine, mutation: MutationDefinition<Args, Ctx, Result>, resolveContext?: (context: SyncRouteContext) => Ctx) => (context: SyncRouteContext) => Promise<Result>;

package/dist/engine/socket.d.ts

@@ -0,0 +1,67 @@
+import { Elysia } from 'elysia';
+import type { PresenceHub } from './presence';
+import type { SyncEngine } from './syncEngine';
+export type SyncSocketOptions = {
+    /** The sync engine whose collections this socket serves. */
+    engine: SyncEngine;
+    /** WebSocket route. Defaults to `/sync/ws`. */
+    path?: string;
+    /** Optional presence hub; enables `presence-*` frames on this socket. */
+    presence?: PresenceHub;
+    /**
+     * Build the per-connection auth context from the upgrade request data
+     * (`ws.data`: query, headers, cookies, and anything you `derive`d/`resolve`d
+     * earlier in the chain). Whatever you return is the `ctx` passed to every
+     * collection's `authorize`/`hydrate`/`match`. Defaults to an empty object.
+     */
+    resolveContext?: (data: Record<string, unknown>) => unknown | Promise<unknown>;
+};
+/**
+ * Elysia WebSocket plugin for the Tier 3 sync engine. One socket multiplexes any
+ * number of collection subscriptions: the client sends `subscribe`/`unsubscribe`
+ * frames and receives `snapshot`/`diff`/`error` frames (see
+ * {@link createSyncConnection}). Mount it once and drive `engine.applyChange`
+ * from your mutations.
+ *
+ * Uses Elysia's first-class `.ws()` rather than a hand-rolled stream — the
+ * bidirectional channel carries both subscriptions and (later) mutations, and
+ * `ws.send` serializes frames for us.
+ */
+export declare const syncSocket: ({ engine, path, resolveContext, presence }: SyncSocketOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        subscribe: {
+            body: {};
+            params: {};
+            query: {};
+            headers: {};
+            response: {};
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/engine/syncEngine.d.ts

@@ -0,0 +1,132 @@
+import type { CollectionContext, CollectionDefinition, JoinCollectionDefinition } from './collection';
+import type { GraphCollectionDefinition } from './graph';
+import type { MutationDefinition, TableWriter, TransactionRunner } from './mutation';
+import type { ReactiveQueryDefinition, TableReader } from './reactive';
+import type { ClusterBus } from './cluster';
+import type { ChangeSource, RowChange, ViewDiff } from './types';
+/**
+ * Thrown when `authorize` denies a subscribe or a mutation. The message names
+ * the denied action; the message always starts with "Not authorized".
+ */
+export declare class UnauthorizedError extends Error {
+    constructor(subject: string);
+}
+export type SubscribeArgs<T, P, Ctx> = {
+    /** Registered collection name. */
+    collection: string;
+    /** Query params (e.g. a filter value); passed to hydrate/match/authorize. */
+    params: P;
+    /** Caller context (e.g. session); passed to hydrate/match/authorize. */
+    ctx: Ctx;
+    /** Receives every non-empty diff (with its version) after the initial reply. */
+    onDiff: (diff: ViewDiff<T>, version: number) => void;
+    /**
+     * Resume from a version the client already applied. When the change log still
+     * covers `(since, now]` for a single-table collection, the engine replies with
+     * a catch-up diff instead of a full snapshot; otherwise it falls back to a
+     * snapshot.
+     */
+    since?: number;
+};
+export type Subscription<T> = {
+    /** The result set at subscribe time — a snapshot (empty when resuming). */
+    initial: T[];
+    /** Catch-up diff when resuming via `since` (instead of `initial`). */
+    catchup?: ViewDiff<T>;
+    /** The engine version this reply brings the client up to. */
+    version: number;
+    /** Stop receiving diffs and release the view. */
+    unsubscribe: () => void;
+};
+export type SyncEngine = {
+    /** Register a collection definition (see {@link defineCollection}). */
+    register: <T, P = void, Ctx = CollectionContext>(collection: CollectionDefinition<T, P, Ctx>) => void;
+    /** Register an incremental join collection (see {@link defineJoinCollection}). */
+    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;
+    /**
+     * Open a live subscription: authorize, hydrate the initial set, and stream
+     * diffs as changes arrive. Rejects with {@link UnauthorizedError} on deny.
+     */
+    subscribe: <T, P = void, Ctx = CollectionContext>(args: SubscribeArgs<T, P, Ctx>) => Promise<Subscription<T>>;
+    /**
+     * One-shot read: authorize and return a collection's current rows without
+     * subscribing. Powers an Eden-typed HTTP hydrate route (and SSR). Rejects
+     * with {@link UnauthorizedError} on deny.
+     */
+    hydrate: (collection: string, params: unknown, ctx: unknown) => Promise<unknown[]>;
+    /**
+     * Feed a committed change to `table` into the engine, fanning the resulting
+     * diff to every live subscription of every collection that reads that table.
+     * Call after a mutation, or wire a {@link ChangeSource} via `connectSource`.
+     * Single-table subscriptions diff the row; multi-table / refetch ones
+     * re-hydrate.
+     */
+    applyChange: <T>(table: string, change: RowChange<T>) => Promise<void>;
+    /**
+     * Connect a change source (e.g. a CDC adapter): its emitted changes flow into
+     * `applyChange`. Resolves to a disconnect function that stops the source.
+     */
+    connectSource: (source: ChangeSource) => Promise<() => Promise<void>>;
+    /**
+     * Join a cluster (see {@link ClusterBus}): broadcast this instance's committed
+     * changes to peers and apply theirs locally, so subscribers on every instance
+     * stay live. Resolves to a disconnect function. Run once per instance.
+     */
+    connectCluster: (bus: ClusterBus) => Promise<() => Promise<void>>;
+    /** Active subscription count, optionally for one collection. */
+    subscriptionCount: (collection?: string) => number;
+    /** Register a mutation definition (see {@link defineMutation}). */
+    registerMutation: <Args, Ctx = CollectionContext, Result = unknown>(mutation: MutationDefinition<Args, Ctx, Result>) => void;
+    /**
+     * Register how to persist a `table` (any ORM), so a mutation's
+     * `actions.insert/update/delete` write to your store and emit the live change
+     * in one step — you can't write without going live. See {@link TableWriter}.
+     */
+    registerWriter: <Row = unknown, Ctx = CollectionContext, Tx = unknown>(table: string, writer: TableWriter<Row, Ctx, Tx>) => void;
+    /**
+     * Register a read-set-tracked reactive query (see {@link defineReactiveQuery}):
+     * it re-runs and re-pushes whenever any table it read changes — no `match`, no
+     * operator graph, no manual change emission.
+     */
+    registerReactive: <T, P = void, Ctx = CollectionContext>(query: ReactiveQueryDefinition<T, P, Ctx>) => void;
+    /**
+     * Teach the engine how to read a table for reactive queries' `ctx.db` (any
+     * ORM). Required for every table a reactive query reads.
+     */
+    registerReader: <Ctx = CollectionContext>(table: string, reader: TableReader<Ctx>) => void;
+    /**
+     * Run a registered mutation: authorize, invoke its handler (which writes and
+     * emits changes via `applyChange`), and resolve with the handler's result.
+     * Rejects with {@link UnauthorizedError} on deny, or an error for an unknown
+     * mutation / a handler throw. Drive this from the transport's mutate frame.
+     */
+    runMutation: (name: string, args: unknown, ctx: unknown) => Promise<unknown>;
+};
+export type SyncEngineOptions = {
+    /**
+     * How many recent changes to retain for resumable reconnects. A client that
+     * reconnects within this window gets a catch-up diff; beyond it, a fresh
+     * snapshot. Defaults to 1024.
+     */
+    changeLogSize?: number;
+    /**
+     * Run every mutation inside your database's transaction (see
+     * {@link TransactionRunner}): the handler's writes commit all-or-nothing, and
+     * the engine emits the resulting diff only after the commit. Omit to run
+     * mutations without a transaction (each writer call is its own DB op).
+     */
+    transaction?: TransactionRunner;
+};
+/**
+ * The Tier 3 sync engine: a registry of collections plus the view syncer. It is
+ * transport-agnostic — `subscribe` returns the initial snapshot and an
+ * `onDiff` stream, which an Elysia/SSE layer wires to a connection, and
+ * `applyChange` is the change feed you drive from your mutations.
+ *
+ * Access control is first-class: every subscribe runs the collection's
+ * `authorize`, and a collection's `match`/`hydrate` scope rows to the caller, so
+ * a change to a row the caller can't see never reaches them.
+ */
+export declare const createSyncEngine: (options?: SyncEngineOptions) => SyncEngine;

package/dist/engine/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Core types shared across the Tier 3 sync engine (server-side). Deliberately
+ * ORM-agnostic: the engine operates on plain row objects, a key function, and a
+ * predicate — the Drizzle/Prisma adapters and the transport layer build on top.
+ */
+/** A scalar that identifies a row within a collection. */
+export type RowKey = string | number | bigint;
+/** The kind of row-level change flowing through the engine's change feed. */
+export type RowOp = 'insert' | 'update' | 'delete';
+/** One row-level change: a row that was inserted, updated, or deleted. */
+export type RowChange<T> = {
+    op: RowOp;
+    /**
+     * The affected row. For `insert`/`update` it is the new row value; for
+     * `delete` only the key field(s) need be present.
+     */
+    row: T;
+};
+/**
+ * The delta a change makes to a query's result set: rows that entered (`added`),
+ * left (`removed`), or stayed in the set but changed value (`changed`). The
+ * `removed` rows are the values the view last held for those keys.
+ */
+export type ViewDiff<T> = {
+    added: T[];
+    removed: T[];
+    changed: T[];
+};
+/** Report a committed row change on `table` into the engine. */
+export type EmitChange = (table: string, change: RowChange<unknown>) => void | Promise<void>;
+/** A committed change parsed from a CDC source, ready to feed the engine. */
+export type ParsedChange = {
+    table: string;
+    change: RowChange<unknown>;
+};
+/**
+ * A pluggable source of committed row changes — the seam for catching writes the
+ * mutation API didn't make (CDC: Postgres LISTEN/NOTIFY or logical replication,
+ * MySQL binlog, SQLite update hooks). `start` begins emitting via the supplied
+ * callback; `stop` tears it down. Wire one with {@link SyncEngine.connectSource}.
+ */
+export type ChangeSource = {
+    start: (emit: EmitChange) => void | Promise<void>;
+    stop: () => void | Promise<void>;
+};

package/dist/index.d.ts

@@ -4,3 +4,7 @@ export { createReactiveHub } from './reactiveHub';
 export type { ReactiveEvent, ReactiveHub, ReactiveListener } from './reactiveHub';
 export { sync } from './plugin';
 export type { SyncPluginOptions, SyncRequestContext } from './plugin';
+export { syncSocket } from './engine/socket';
+export type { SyncSocketOptions } from './engine/socket';
+export { createPresenceHub } from './engine/presence';
+export type { PresenceDiff, PresenceHandle, PresenceHub, PresenceMember } from './engine/presence';