@absolutejs/sync 0.1.0 → 0.2.0

package/dist/client/presence.d.ts

@@ -0,0 +1,37 @@
+import type { PresenceMember } from '../engine/presence';
+export type { PresenceMember } from '../engine/presence';
+export type PresenceClientOptions<S> = {
+    /** WebSocket URL of the {@link syncSocket} endpoint (e.g. `ws://host/sync/ws`). */
+    url: string;
+    /** Presence room to join (e.g. a document id or channel). */
+    room: string;
+    /** This member's initial state (e.g. `{ name, typing: false }`). */
+    state: S;
+    /** Stable id for this member; defaults to a random one per client. */
+    memberId?: string;
+    /** WebSocket implementation; defaults to the global one. */
+    webSocketImpl?: typeof WebSocket;
+    /** Initial reconnect backoff (ms); doubles per attempt. Defaults to 500. */
+    reconnectMs?: number;
+    /** Max reconnect backoff (ms). Defaults to 10000. */
+    maxReconnectMs?: number;
+};
+export type PresenceClient<S> = {
+    /** This member's id. */
+    id: string;
+    /** Current members in the room (including this one). */
+    get: () => PresenceMember<S>[];
+    /** Subscribe to member changes; returns an unsubscribe. */
+    subscribe: (listener: (members: PresenceMember<S>[]) => void) => () => void;
+    /** Update this member's own state (e.g. set `typing: true`). */
+    set: (state: S) => void;
+    /** Leave the room and close the socket. */
+    close: () => void;
+};
+/**
+ * Browser client for {@link createPresenceHub} presence: join a room, see who's
+ * present (and their state — typing, cursor…), and publish your own. Opens its
+ * own small socket to the sync endpoint and re-joins on reconnect.
+ * Framework-agnostic (`get` + `subscribe`, ready for `useSyncExternalStore`).
+ */
+export declare const createPresence: <S>(options: PresenceClientOptions<S>) => PresenceClient<S>;

package/dist/client/syncClient.d.ts

@@ -0,0 +1,53 @@
+import type { RowKey } from '../engine/types';
+import type { MutateOptions, SyncCollectionState, SyncCollectionStatus } from './syncCollection';
+export type SyncClientOptions = {
+    /** WebSocket URL of the {@link syncSocket} endpoint (e.g. `ws://host/sync/ws`). */
+    url: string;
+    /** WebSocket implementation; defaults to the global one (pass for tests/SSR). */
+    webSocketImpl?: typeof WebSocket;
+    /** Initial reconnect backoff (ms); doubles per attempt. Defaults to 500. */
+    reconnectMs?: number;
+    /** Max reconnect backoff (ms). Defaults to 10000. */
+    maxReconnectMs?: number;
+    /** Called with the message of any server `error` frame. */
+    onError?: (message: unknown) => void;
+};
+export type SyncCollectionHandleOptions<T> = {
+    /** Registered collection name to subscribe to. */
+    collection: string;
+    /** Query params forwarded to the server collection. */
+    params?: unknown;
+    /** Row identity. Defaults to `row.id`. */
+    key?: (row: T) => RowKey;
+};
+export type SyncCollectionHandle<T> = {
+    /** Current state snapshot (stable until the next change). */
+    get: () => SyncCollectionState<T>;
+    /** Subscribe to state changes; returns an unsubscribe. */
+    subscribe: (listener: (state: SyncCollectionState<T>) => void) => () => void;
+    /** Run a server mutation, optionally applying it optimistically. */
+    mutate: <R = unknown>(options: MutateOptions<T>) => Promise<R>;
+    /** Unsubscribe this collection (the socket stays open for others). */
+    close: () => void;
+};
+export type SyncClient = {
+    /** Subscribe to a collection over the shared socket. */
+    collection: <T>(options: SyncCollectionHandleOptions<T>) => SyncCollectionHandle<T>;
+    /** Close the socket and every handle. */
+    close: () => void;
+};
+/**
+ * A multiplexed sync client: one WebSocket serving many live collections. Its
+ * reason to exist over per-collection {@link createSyncCollection} is the
+ * **consistent frame** — when one atomic mutation touches several collections,
+ * the server bundles the diffs into a single `frame` and this client applies
+ * them all (to every collection's confirmed state) before notifying any
+ * listener, so a view reading multiple collections never paints a torn
+ * intermediate where one moved and the other hasn't.
+ *
+ * Reads: subscribe, apply snapshot then diffs/frames, resume on reconnect.
+ * Writes: per-collection optimistic overlay, reconciled on ack/reject and
+ * replayed on reconnect (make server mutations idempotent).
+ */
+export declare const createSyncClient: (options: SyncClientOptions) => SyncClient;
+export type { SyncCollectionState, SyncCollectionStatus };

package/dist/engine/cluster.d.ts

@@ -0,0 +1,41 @@
+import type { RowChange } from './types';
+/**
+ * Horizontal scale — the seam for running the engine across many server
+ * instances. The in-process hub only reaches subscribers on the same instance;
+ * a {@link ClusterBus} fans every instance's committed changes out to the
+ * others, so a mutation on instance A reaches subscribers on instance B.
+ *
+ * Client-agnostic like the {@link ChangeSource} seam: you supply `publish` +
+ * `subscribe` over your bus of choice (Redis stream, Postgres `LISTEN/NOTIFY`,
+ * NATS…), and the engine handles fan-out and loop prevention (each message is
+ * tagged with the originating instance, and an instance ignores its own).
+ *
+ * Note: version cursors are per-instance, so a client that reconnects to a
+ * *different* instance falls back to a fresh snapshot (correct, just not a
+ * catch-up diff) — use sticky sessions if you want cross-instance resume.
+ */
+/** A committed change as it travels over the bus. */
+export type ClusterChange = {
+    table: string;
+    change: RowChange<unknown>;
+};
+export type ClusterMessage = {
+    /** The instance that produced these changes (so peers ignore their own). */
+    origin: string;
+    changes: ClusterChange[];
+};
+export type ClusterBus = {
+    /** Broadcast this instance's committed changes to the others. */
+    publish: (message: ClusterMessage) => void | Promise<void>;
+    /**
+     * Receive other instances' changes; return a function that stops listening.
+     * The engine filters out messages from its own `origin`.
+     */
+    subscribe: (onMessage: (message: ClusterMessage) => void) => (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
+};
+/**
+ * An in-process {@link ClusterBus} — for tests, local dev, or several engines in
+ * one process. **Not** cross-process: real horizontal scale needs a bus that
+ * spans machines (Redis stream, Postgres `LISTEN/NOTIFY`).
+ */
+export declare const createInMemoryClusterBus: () => ClusterBus;

package/dist/engine/connection.d.ts

@@ -1,3 +1,4 @@
+import type { PresenceHub, PresenceMember } from './presence';
 import type { SyncEngine } from './syncEngine';
 /**
  * Wire protocol for the sync-engine WebSocket. One connection multiplexes many
@@ -19,6 +20,25 @@ export type ClientFrame = {
     mutationId: number;
     name: string;
     args?: unknown;
+} | {
+    type: 'presence-join';
+    room: string;
+    memberId: string;
+    state: unknown;
+} | {
+    type: 'presence-set';
+    room: string;
+    state: unknown;
+} | {
+    type: 'presence-leave';
+    room: string;
+};
+/** One subscription's delta within a {@link ServerFrame} `frame`. */
+export type FrameDiff<T = unknown> = {
+    id: string;
+    added: T[];
+    removed: T[];
+    changed: T[];
 };
 /** Server → client. `version` is the change-feed watermark this frame brings. */
 export type ServerFrame<T = unknown> = {
@@ -33,6 +53,16 @@ export type ServerFrame<T = unknown> = {
     removed: T[];
     changed: T[];
     version?: number;
+} | {
+    type: 'frame';
+    version?: number;
+    diffs: FrameDiff<T>[];
+} | {
+    type: 'presence';
+    room: string;
+    joined: PresenceMember<T>[];
+    updated: PresenceMember<T>[];
+    left: string[];
 } | {
     type: 'error';
     id?: string;
@@ -52,6 +82,8 @@ export type SyncConnectionOptions = {
     ctx: unknown;
     /** Send a frame to the client (the transport serializes it). */
     send: (frame: ServerFrame) => void;
+    /** Optional presence hub; enables the `presence-*` frames (see createPresenceHub). */
+    presence?: PresenceHub;
 };
 export type SyncConnection = {
     /** Handle one client frame (a parsed object or a raw JSON string). */
@@ -68,4 +100,4 @@ export type SyncConnection = {
  * Pure (no WebSocket import) so it can be unit-tested with a fake `send`; the
  * Elysia `syncSocket` plugin is the thin adapter that feeds it socket events.
  */
-export declare const createSyncConnection: ({ engine, ctx, send }: SyncConnectionOptions) => SyncConnection;
+export declare const createSyncConnection: ({ engine, ctx, send, presence }: SyncConnectionOptions) => SyncConnection;

package/dist/engine/index.d.ts

@@ -20,15 +20,21 @@ export type { AggregateOpOptions, Change, JoinNode, JoinNodeOptions, Materialize
 export type { ChangeSource, EmitChange, ParsedChange, RowChange, RowKey, RowOp, ViewDiff } from './types';
 export { createPollingChangeSource, parseOutboxRow } from './pollingSource';
 export type { OutboxRow, PollingChangeSourceOptions } from './pollingSource';
+export { createInMemoryClusterBus } from './cluster';
+export type { ClusterBus, ClusterChange, ClusterMessage } from './cluster';
+export { createPresenceHub } from './presence';
+export type { PresenceDiff, PresenceHandle, PresenceHub, PresenceMember } from './presence';
 export { defineCollection, defineJoinCollection } from './collection';
 export type { CollectionContext, CollectionDefinition, JoinCollectionDefinition, JoinSide } from './collection';
+export { defineReactiveQuery } from './reactive';
+export type { ReactiveQueryContext, ReactiveQueryDefinition, ReadHandle, TableReader } from './reactive';
 export { defineGraphCollection, query } from './graph';
 export type { GraphCollectionDefinition, GraphInstance, GraphSource, GroupByOptions, JoinOptions, OrderByQueryOptions, Query } from './graph';
 export { defineMutation } from './mutation';
-export type { MutationActions, MutationDefinition, MutationHandler } from './mutation';
+export type { MutationActions, MutationDefinition, MutationHandler, TableWriter, TransactionRunner } from './mutation';
 export { createSyncEngine, UnauthorizedError } from './syncEngine';
 export type { SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
 export { hydrateRoute, mutateRoute } from './routes';
 export type { SyncRouteContext } from './routes';
 export { createSyncConnection } from './connection';
-export type { ClientFrame, ServerFrame, SyncConnection, SyncConnectionOptions } from './connection';
+export type { ClientFrame, FrameDiff, ServerFrame, SyncConnection, SyncConnectionOptions } from './connection';