@absolutejs/sync 0.7.0 → 0.8.0

package/README.md

@@ -33,9 +33,10 @@ top-N ordering are maintained incrementally through a composable operator graph
 > write-behind cache), Tier 2 (Drizzle + Prisma topic adapters, `createLiveQuery`),
 > and Tier 3 (sync engine: collections, WebSocket diff transport, optimistic
 > mutations + offline queue, a local-first client cache, declarative row-level
-> permissions, live full-text + vector search, scheduled functions, CDC for
-> Postgres/MySQL/SQLite, incremental aggregations + joins, and a declarative
-> operator graph) are in place. Everything ships as subpaths of this one package.
+> permissions, live full-text + vector search, scheduled functions, a live
+> devtools dashboard, CDC for Postgres/MySQL/SQLite, incremental aggregations +
+> joins, and a declarative operator graph) are in place. Everything ships as
+> subpaths of this one package.
 
 ## Install
 
@@ -332,13 +333,14 @@ it, ~3 store round-trips every 20ms ran the voice pipeline far slower than real
 
 ### `@absolutejs/sync`
 
-| Export                                                                                     | What it is                                                                                                                                                       |
-| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createReactiveHub()`                                                                      | In-memory topic pub/sub (`publish`, `subscribe`, `subscriberCount`).                                                                                             |
-| `sync({ hub, path?, resolveTopics?, heartbeatMs? })`                                       | Elysia plugin: SSE stream of hub events.                                                                                                                         |
-| `syncSocket({ engine, path?, resolveContext? })`                                           | Elysia WebSocket plugin for the sync engine.                                                                                                                     |
-| `scheduled({ engine, prefix?, onError? })` _(`/scheduled` subpath)_                        | Elysia plugin: fires the engine's registered schedules on their cron patterns (via `@elysiajs/cron`). Kept off the main entry so `syncSocket` needs no cron dep. |
-| `createWriteBehindCache({ load, persist, remove?, debounceMs?, evict?, onPersistError? })` | In-memory cache + write-behind persistence.                                                                                                                      |
+| Export                                                                                     | What it is                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createReactiveHub()`                                                                      | In-memory topic pub/sub (`publish`, `subscribe`, `subscriberCount`).                                                                                                           |
+| `sync({ hub, path?, resolveTopics?, heartbeatMs? })`                                       | Elysia plugin: SSE stream of hub events.                                                                                                                                       |
+| `syncSocket({ engine, path?, resolveContext? })`                                           | Elysia WebSocket plugin for the sync engine.                                                                                                                                   |
+| `scheduled({ engine, prefix?, onError? })` _(`/scheduled` subpath)_                        | Elysia plugin: fires the engine's registered schedules on their cron patterns (via `@elysiajs/cron`). Kept off the main entry so `syncSocket` needs no cron dep.               |
+| `syncDevtools({ engine, path?, snapshotMs? })`                                             | Elysia plugin: a live devtools dashboard (collections, subscription counts, mutations, schedules, change feed) over SSE. Backed by `engine.inspect()` + `engine.onActivity()`. |
+| `createWriteBehindCache({ load, persist, remove?, debounceMs?, evict?, onPersistError? })` | In-memory cache + write-behind persistence.                                                                                                                                    |
 
 ### `@absolutejs/sync/client`
 

package/dist/devtools.d.ts

@@ -0,0 +1,69 @@
+import { Elysia } from 'elysia';
+import type { SyncEngine } from './engine/syncEngine';
+export type SyncDevtoolsOptions = {
+    /** The engine to inspect. */
+    engine: SyncEngine;
+    /** Route the dashboard is served from (its SSE feed is `<path>/stream`). Default `/sync/devtools`. */
+    path?: string;
+    /** Snapshot refresh interval (ms) — keeps subscription counts/version current. Default 2000. */
+    snapshotMs?: number;
+};
+/**
+ * Elysia plugin: a live devtools dashboard for a {@link SyncEngine}. Mount it and
+ * open `path` in a browser to watch registered collections (kind, source tables,
+ * live subscription counts), mutations, schedules, readers/writers, the
+ * change-feed version, and a streaming log of changes + mutation outcomes — over
+ * Server-Sent Events. Read-only; safe to leave mounted in dev.
+ */
+export declare const syncDevtools: ({ engine, path, snapshotMs }: SyncDevtoolsOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/engine/devtools.d.ts

@@ -0,0 +1,55 @@
+import type { RowOp } from './types';
+/**
+ * Devtools introspection — a live window into a running {@link SyncEngine}: what
+ * collections are registered, how many clients subscribe to each, which
+ * mutations/schedules/readers/writers exist, the change-feed version, and a tail
+ * of recent changes. Paired with the activity stream ({@link EngineActivity}) it
+ * powers the `syncDevtools` dashboard. Read-only — purely observational.
+ */
+export type CollectionKind = 'view' | 'join' | 'graph' | 'reactive' | 'search';
+/** One registered collection's current state. */
+export type CollectionInspection = {
+    name: string;
+    kind: CollectionKind;
+    /** Source tables it reads (empty for a reactive query — its deps are dynamic). */
+    tables: string[];
+    /** Active client subscriptions to it right now. */
+    subscriptions: number;
+};
+/** A point-in-time snapshot of the engine (see {@link SyncEngine.inspect}). */
+export type EngineInspection = {
+    /** Current change-feed version (monotonic). */
+    version: number;
+    collections: CollectionInspection[];
+    mutations: string[];
+    schedules: {
+        name: string;
+        pattern: string;
+    }[];
+    /** Tables with a registered reader / writer. */
+    readers: string[];
+    writers: string[];
+    /** Most recent changes from the change log (oldest first). */
+    recentChanges: {
+        version: number;
+        table: string;
+        op: RowOp;
+    }[];
+};
+/**
+ * A live engine event (see {@link SyncEngine.onActivity}): a committed change or
+ * a mutation outcome. `at` is `Date.now()`. (Live subscription counts come from
+ * the {@link EngineInspection} snapshot.)
+ */
+export type EngineActivity = {
+    type: 'change';
+    at: number;
+    table: string;
+    op: RowOp;
+    version: number;
+} | {
+    type: 'mutation';
+    at: number;
+    name: string;
+    status: 'ok' | 'error';
+};

package/dist/engine/index.d.ts

@@ -44,6 +44,7 @@ export { defineMutation } from './mutation';
 export type { MutationActions, MutationDefinition, MutationHandler, TableWriter, TransactionRunner } from './mutation';
 export { createSyncEngine, UnauthorizedError } from './syncEngine';
 export type { SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
+export type { CollectionInspection, CollectionKind, EngineActivity, EngineInspection } from './devtools';
 export { hydrateRoute, mutateRoute } from './routes';
 export type { SyncRouteContext } from './routes';
 export { createSyncConnection } from './connection';

package/dist/engine/index.js

@@ -1090,6 +1090,12 @@ var createSyncEngine = (options = {}) => {
   const changeLogSize = options.changeLogSize ?? 1024;
   const changeLog = [];
   let version = 0;
+  const activityListeners = new Set;
+  const emitActivity = (event) => {
+    for (const listener of activityListeners) {
+      listener(event);
+    }
+  };
   const runInTransaction = options.transaction;
   const instanceId = globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
   let clusterBus;
@@ -1412,6 +1418,13 @@ var createSyncEngine = (options = {}) => {
     version += 1;
     const changeVersion = version;
     logChange(changeVersion, { version: changeVersion, table, change });
+    emitActivity({
+      type: "change",
+      at: Date.now(),
+      table,
+      op: change.op,
+      version: changeVersion
+    });
     const emissions = [];
     for (const subscription of subscriptionsForTable(table)) {
       const diff = await subscriptionDiff(subscription, table, change);
@@ -1440,6 +1453,13 @@ var createSyncEngine = (options = {}) => {
     const reactiveChanges = [];
     for (const { table, change } of changes) {
       logChange(batchVersion, { version: batchVersion, table, change });
+      emitActivity({
+        type: "change",
+        at: Date.now(),
+        table,
+        op: change.op,
+        version: batchVersion
+      });
       reactiveChanges.push({
         table,
         key: changedKeyFor(table, change),
@@ -1816,13 +1836,29 @@ var createSyncEngine = (options = {}) => {
         }
       }
       const runHandler = async (tx) => {
-        const { actions, buffered: buffered2 } = makeActions(tx, ctx, true);
-        const result2 = await mutation.handler(args, ctx, actions);
-        return { buffered: buffered2, result: result2 };
+        const { actions, buffered } = makeActions(tx, ctx, true);
+        const result = await mutation.handler(args, ctx, actions);
+        return { buffered, result };
       };
-      const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
-      await applyChangeBatch(buffered);
-      return result;
+      try {
+        const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
+        await applyChangeBatch(buffered);
+        emitActivity({
+          type: "mutation",
+          at: Date.now(),
+          name,
+          status: "ok"
+        });
+        return result;
+      } catch (error) {
+        emitActivity({
+          type: "mutation",
+          at: Date.now(),
+          name,
+          status: "error"
+        });
+        throw error;
+      }
     },
     registerSchedule: (schedule) => {
       schedules.set(schedule.name, schedule);
@@ -1841,6 +1877,53 @@ var createSyncEngine = (options = {}) => {
       };
       const buffered = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
       await applyChangeBatch(buffered);
+    },
+    inspect: () => {
+      const collections = [...registry.entries()].map(([name, def]) => {
+        const kind = def.kind ?? "view";
+        let tables = [];
+        if (kind === "join") {
+          const join = def;
+          tables = [join.left.table, join.right.table];
+        } else if (kind === "graph") {
+          tables = def.query.tables();
+        } else if (kind === "search") {
+          tables = [
+            def.table
+          ];
+        } else if (kind === "view") {
+          tables = def.tables ?? [name];
+        }
+        return {
+          name,
+          kind,
+          tables,
+          subscriptions: active.get(name)?.size ?? 0
+        };
+      });
+      const DEVTOOLS_RECENT = 50;
+      return {
+        version,
+        collections,
+        mutations: [...mutations.keys()],
+        schedules: [...schedules.values()].map((schedule) => ({
+          name: schedule.name,
+          pattern: schedule.pattern
+        })),
+        readers: [...readers.keys()],
+        writers: [...writers.keys()],
+        recentChanges: changeLog.slice(-DEVTOOLS_RECENT).map((entry) => ({
+          version: entry.version,
+          table: entry.table,
+          op: entry.change.op
+        }))
+      };
+    },
+    onActivity: (listener) => {
+      activityListeners.add(listener);
+      return () => {
+        activityListeners.delete(listener);
+      };
     }
   };
 };
@@ -2115,5 +2198,5 @@ export {
   SEARCH_SCORE_FIELD
 };
 
-//# debugId=54AD7964887E323764756E2164756E21
+//# debugId=B0B398375CBCC30B64756E2164756E21
 //# sourceMappingURL=index.js.map