@absolutejs/sync 0.0.1 → 0.1.0

package/dist/engine/dataflow.d.ts

@@ -0,0 +1,109 @@
+import type { AggregateGroup } from './aggregate';
+import type { RowChange, RowKey, ViewDiff } from './types';
+/**
+ * Composable incremental dataflow (the general operator graph, in progress).
+ *
+ * Every edge in the graph is a stream of keyed **changes** — an `upsert` (insert
+ * or update, last-write-wins per key) or a `delete`. Collapsing added/changed
+ * into one `upsert` is what makes operators compose: `filter`/`map` become
+ * stateless stream transforms, `join` reuses the equi-join operator, and a
+ * `materialize` sink turns the final stream back into a `{ added, removed,
+ * changed }` diff for the transport.
+ */
+export type Change<T> = {
+    op: 'upsert' | 'delete';
+    key: RowKey;
+    row: T;
+};
+/** A single-input incremental operator: a batch of input changes → output changes. */
+export type Operator<In, Out> = {
+    push: (changes: Change<In>[]) => Change<Out>[];
+};
+/** Lift a table row change into a dataflow change (a graph source). */
+export declare const fromRowChange: <T>(change: RowChange<T>, key: (row: T) => RowKey) => Change<T>;
+/**
+ * Keep only rows matching `predicate`. Stateless: a row that fails the predicate
+ * is emitted as a `delete` (downstream removes it if present, else no-op), so a
+ * row that stops matching leaves correctly.
+ */
+export declare const filterOp: <T>(predicate: (row: T) => boolean) => Operator<T, T>;
+/**
+ * Transform each row. Stateless; preserves identity unless `rekey` is given (to
+ * derive the output key from the mapped row).
+ */
+export declare const mapOp: <In, Out>(transform: (row: In) => Out, rekey?: (row: Out) => RowKey) => Operator<In, Out>;
+/** Compose two operators into one (`a` then `b`). Nest for longer chains. */
+export declare const chain: <A, B, C>(a: Operator<A, B>, b: Operator<B, C>) => Operator<A, C>;
+export type AggregateOpOptions<In> = {
+    /** Input row identity (to track each row's contribution across updates). */
+    key: (row: In) => RowKey;
+    /** Group rows by this key (omit for one `''` group). */
+    groupBy?: (row: In) => RowKey;
+    /** Numeric value for sum/avg/min/max (omit for a count-only aggregate). */
+    value?: (row: In) => number;
+};
+/**
+ * Aggregate a change stream into a stream of group summaries — `count`/`sum`/
+ * `avg`/`min`/`max` per group, maintained incrementally (wraps
+ * {@link createAggregate}). Emits an `upsert` of the group summary for each group
+ * a batch touched, or a `delete` when a group empties. Output is keyed by group,
+ * so it composes downstream like any other operator (e.g. after a join).
+ */
+export declare const aggregateOp: <In>(options: AggregateOpOptions<In>) => Operator<In, AggregateGroup>;
+export type OrderByOptions<T> = {
+    /** Row identity. */
+    key: (row: T) => RowKey;
+    /** Sort comparator (ascending: negative = a before b). */
+    compare: (a: T, b: T) => number;
+    /** Keep at most this many rows (the top-N window). */
+    limit?: number;
+    /** Skip this many rows from the front (pagination). Defaults to 0. */
+    offset?: number;
+};
+/**
+ * Maintain a sorted top-N window: keep only the `[offset, offset + limit)` slice
+ * by `compare`, emitting which rows entered/left the window as input changes.
+ * A single insert can both add a row and evict the one it displaced — both are
+ * emitted. Bounded output (≤ limit upserts per batch); it re-sorts its input, so
+ * place it where the input is already narrowed (e.g. after a filter/join).
+ *
+ * The window is the right *set* of rows; sort them by the same comparator on the
+ * client for display order (cheap for N rows — the diff protocol is unordered).
+ */
+export declare const orderByOp: <T>(options: OrderByOptions<T>) => Operator<T, T>;
+/** A two-input incremental equi-join node. */
+export type JoinNode<L, R, Out> = {
+    hydrate: (left: Iterable<L>, right: Iterable<R>) => void;
+    pushLeft: (changes: Change<L>[]) => Change<Out>[];
+    pushRight: (changes: Change<R>[]) => Change<Out>[];
+    rows: () => Out[];
+};
+export type JoinNodeOptions<L, R, Out> = {
+    leftKey: (left: L) => RowKey;
+    rightKey: (right: R) => RowKey;
+    leftOn: (left: L) => RowKey;
+    rightOn: (right: R) => RowKey;
+    select: (left: L, right: R) => Out;
+    /** Provide for a LEFT join: output for a left row with no match. */
+    selectUnmatched?: (left: L) => Out;
+    /** Output row identity (unique per emitted pair). */
+    key: (out: Out) => RowKey;
+};
+/**
+ * A join as a dataflow node — reuses {@link createEquiJoin} and converts its
+ * `{ added, removed, changed }` deltas into the upsert/delete change stream.
+ */
+export declare const joinNode: <L, R, Out>(options: JoinNodeOptions<L, R, Out>) => JoinNode<L, R, Out>;
+export type Materializer<T> = {
+    /** Replace the set with initial rows (no diff emitted). */
+    hydrate: (rows: Iterable<T>) => void;
+    /** Apply a change stream and return the resulting result-set diff. */
+    apply: (changes: Change<T>[]) => ViewDiff<T>;
+    rows: () => T[];
+};
+/**
+ * The graph sink: maintain a keyed result set from a change stream and emit the
+ * `{ added, removed, changed }` diff each batch produces — the boundary back to
+ * the transport / client.
+ */
+export declare const materialize: <T>(key: (row: T) => RowKey, equals?: (a: T, b: T) => boolean) => Materializer<T>;

package/dist/engine/equiJoin.d.ts

@@ -0,0 +1,51 @@
+import type { RowChange, RowKey, ViewDiff } from './types';
+export type EquiJoinOptions<L, R, Out> = {
+    /** Left row identity. */
+    leftKey: (left: L) => RowKey;
+    /** Right row identity. */
+    rightKey: (right: R) => RowKey;
+    /** Join value on the left (matched against `rightOn`). */
+    leftOn: (left: L) => RowKey;
+    /** Join value on the right (matched against `leftOn`). */
+    rightOn: (right: R) => RowKey;
+    /** Combine a matched pair into an output row. */
+    select: (left: L, right: R) => Out;
+    /**
+     * Provide to make this a LEFT join: a left row with no matching right emits
+     * `selectUnmatched(left)` instead of nothing, and is replaced by matched rows
+     * once a right appears (and reverts when the last right leaves). Omit for an
+     * inner join.
+     */
+    selectUnmatched?: (left: L) => Out;
+    /**
+     * Equality used to detect when a matched pair's output value changed.
+     * Defaults to a shallow compare of own enumerable properties.
+     */
+    equals?: (a: Out, b: Out) => boolean;
+};
+export type EquiJoin<L, R, Out> = {
+    /** Bulk-load both inputs (replaces current state). */
+    hydrate: (left: Iterable<L>, right: Iterable<R>) => void;
+    /** Apply a change to the left input; returns the output diff. */
+    applyLeft: (change: RowChange<L>) => ViewDiff<Out>;
+    /** Apply a change to the right input; returns the output diff. */
+    applyRight: (change: RowChange<R>) => ViewDiff<Out>;
+    /** Current joined rows. */
+    rows: () => Out[];
+    /** Number of joined rows. */
+    size: () => number;
+};
+/**
+ * An incrementally-maintained equi-join (the differential-dataflow core, bounded
+ * to a single two-input equality join). Hydrate both sides, then feed each side's
+ * row changes through {@link EquiJoin.applyLeft} / `applyRight`: it indexes both
+ * inputs by the join value and emits only the `{ added, removed, changed }`
+ * joined rows the change affects — touching the matching pairs, not the whole
+ * result. Inner by default; pass `selectUnmatched` for a LEFT join.
+ *
+ * Output rows are keyed internally by the `(leftKey, rightKey)` pair, so it
+ * handles many-to-many. The consumer keys the emitted rows by its own key; for a
+ * many-to-many join, include both ids in the output so that key is unique
+ * (a many-to-one join can key by the left id alone).
+ */
+export declare const createEquiJoin: <L, R, Out>(options: EquiJoinOptions<L, R, Out>) => EquiJoin<L, R, Out>;

package/dist/engine/graph.d.ts

@@ -0,0 +1,85 @@
+import type { AggregateGroup } from './aggregate';
+import type { CollectionContext } from './collection';
+import type { RowChange, RowKey, ViewDiff } from './types';
+/**
+ * Declarative incremental queries — the front door to the operator graph. Build a
+ * pipeline with {@link query} (`source → filter → map → join → groupBy`); the
+ * engine instantiates it per subscription, hydrates each source, and routes each
+ * table's changes through the wired operators, emitting result diffs.
+ */
+/** A table this query reads. */
+export type GraphSource<Row, P = void, Ctx = CollectionContext> = {
+    table: string;
+    hydrate: (params: P, ctx: Ctx) => Promise<Iterable<Row>> | Iterable<Row>;
+    key: (row: Row) => RowKey;
+    /** Scope incremental changes (a row that fails it leaves). */
+    match?: (row: Row, params: P, ctx: Ctx) => boolean;
+};
+export type JoinOptions<Left, Right, Out> = {
+    /** Join value on the left (current) stream. */
+    on: (left: Left) => RowKey;
+    /** Join value on the right source. */
+    rightOn: (right: Right) => RowKey;
+    /** Combine a matched pair. */
+    select: (left: Left, right: Right) => Out;
+    /**
+     * Provide to make this a LEFT join: output for a left row with no matching
+     * right (e.g. a user with zero orders). Omit for an inner join.
+     */
+    selectUnmatched?: (left: Left) => Out;
+    /** Output row identity (unique per pair). */
+    key: (out: Out) => RowKey;
+};
+export type GroupByOptions<Row> = {
+    /** Input row identity (to track contributions). */
+    key: (row: Row) => RowKey;
+    groupBy?: (row: Row) => RowKey;
+    value?: (row: Row) => number;
+};
+export type OrderByQueryOptions<Row> = {
+    /** Row identity. */
+    key: (row: Row) => RowKey;
+    /** Sort comparator (ascending). */
+    compare: (a: Row, b: Row) => number;
+    /** Keep at most this many rows (top-N). */
+    limit?: number;
+    /** Skip this many from the front (pagination). */
+    offset?: number;
+};
+/** A live, instantiated graph for one subscription. */
+export type GraphInstance<Out> = {
+    tables: string[];
+    hydrate: () => Promise<Out[]>;
+    applyChange: (table: string, change: RowChange<unknown>) => ViewDiff<Out>;
+};
+export type Query<Row, P = void, Ctx = CollectionContext> = {
+    filter: (predicate: (row: Row, params: P, ctx: Ctx) => boolean) => Query<Row, P, Ctx>;
+    map: <Out>(transform: (row: Row) => Out, rekey?: (row: Out) => RowKey) => Query<Out, P, Ctx>;
+    join: <Right, Out>(right: GraphSource<Right, P, Ctx> | Query<Right, P, Ctx>, options: JoinOptions<Row, Right, Out>) => Query<Out, P, Ctx>;
+    /**
+     * LEFT join: like {@link join} but keeps left rows with no match, emitting
+     * `selectUnmatched(left)` for them (required, so the intent is explicit).
+     */
+    leftJoin: <Right, Out>(right: GraphSource<Right, P, Ctx> | Query<Right, P, Ctx>, options: JoinOptions<Row, Right, Out> & {
+        selectUnmatched: (left: Row) => Out;
+    }) => Query<Out, P, Ctx>;
+    groupBy: (options: GroupByOptions<Row>) => Query<AggregateGroup, P, Ctx>;
+    orderBy: (options: OrderByQueryOptions<Row>) => Query<Row, P, Ctx>;
+    /** Source tables this query reads. */
+    tables: () => string[];
+    /** Instantiate the graph for one subscription's params/ctx. */
+    instantiate: (params: P, ctx: Ctx) => GraphInstance<Row>;
+};
+/** Start a query from a source table. */
+export declare const query: <Row, P = void, Ctx = CollectionContext>(source: GraphSource<Row, P, Ctx>) => Query<Row, P, Ctx>;
+/** A collection backed by an incremental operator graph (see {@link query}). */
+export type GraphCollectionDefinition<Out, P = void, Ctx = CollectionContext> = {
+    name: string;
+    kind: 'graph';
+    query: Query<Out, P, Ctx>;
+    authorize?: (params: P, ctx: Ctx) => boolean | Promise<boolean>;
+    /** Output row identity (used by the engine/transport to key result rows). */
+    key: (out: Out) => RowKey;
+};
+/** Define a collection whose result is maintained by an operator graph. */
+export declare const defineGraphCollection: <Out, P = void, Ctx = CollectionContext>(definition: Omit<GraphCollectionDefinition<Out, P, Ctx>, "kind">) => GraphCollectionDefinition<Out, P, Ctx>;

package/dist/engine/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @absolutejs/sync engine (Tier 3 — sync engine MVP, server-side).
+ *
+ * Row-level reactive query results on your own database. Hydrate a query's
+ * result set once, then maintain it incrementally as rows change and push the
+ * diffs to subscribers — instead of refetching the whole query.
+ *
+ * This entry currently exposes the predicate-matching IVM core
+ * ({@link createMaterializedView}); the collection registry, view syncer, diff
+ * transport, and client store land here as the read and write paths fill in.
+ */
+export { createMaterializedView, isEmptyViewDiff } from './materializedView';
+export type { MaterializedView, MaterializedViewOptions } from './materializedView';
+export { createAggregate } from './aggregate';
+export type { Aggregate, AggregateGroup, AggregateOptions } from './aggregate';
+export { createEquiJoin } from './equiJoin';
+export type { EquiJoin, EquiJoinOptions } from './equiJoin';
+export { aggregateOp, chain, filterOp, fromRowChange, joinNode, mapOp, materialize, orderByOp } from './dataflow';
+export type { AggregateOpOptions, Change, JoinNode, JoinNodeOptions, Materializer, Operator, OrderByOptions } from './dataflow';
+export type { ChangeSource, EmitChange, ParsedChange, RowChange, RowKey, RowOp, ViewDiff } from './types';
+export { createPollingChangeSource, parseOutboxRow } from './pollingSource';
+export type { OutboxRow, PollingChangeSourceOptions } from './pollingSource';
+export { defineCollection, defineJoinCollection } from './collection';
+export type { CollectionContext, CollectionDefinition, JoinCollectionDefinition, JoinSide } from './collection';
+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 { 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';