@absolutejs/sync 0.7.0 → 0.9.0

package/README.md

@@ -33,7 +33,8 @@ 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
+> permissions, schema validation + lazy migrations, 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.
 
@@ -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`
 
@@ -401,6 +403,7 @@ mutate({
 | `defineGraphCollection({ name, query, key, authorize? })`                                | Run a `query` as a live collection.                                                                                                                                                                                    |
 | `defineReactiveQuery({ name, run, key })` + `registerReactive` / `registerReader`        | Read-set-tracked query: `run(ctx)` reads via `ctx.db` (`all`/`get`/`where`) and re-runs only when the rows/ranges it read change — no `match`, no manual emit.                                                         |
 | `definePermissions({ [table]: { read?, insert?, update?, delete?, write? } })`           | Declarative row-level access control. Pass as `createSyncEngine({ permissions })` or `registerPermissions(table, rules)`. Read rules filter every row emitted; write rules gate `actions.insert/update/delete`.        |
+| `defineSchema({ [table]: { fields, version?, migrate? } })` + `field` kit                | Declarative row schema. Pass as `createSyncEngine({ schemas })` or `registerSchema(table, schema)`. Writes are validated (bad write → `SchemaError`); `migrate` lazily upcasts rows on read (no DB migration needed).  |
 | `defineSearchCollection({ name, table, index, source, key, limit? })` + `registerSearch` | Live search collection: the subscription's `params` are the query (string/vector), the ranked top-K stream back as a normal collection, re-ranked as rows change. Each row carries its score under `_score`.           |
 | `createTextIndex({ key, fields, tokenize?, stopwords?, k1?, b? })`                       | Incremental BM25 full-text index (keyword search). Implements `SearchIndex`; usable standalone or inside a search collection.                                                                                          |
 | `createVectorIndex({ key, embedding, metric? })`                                         | Incremental vector index (cosine/dot/euclidean exact k-NN) for semantic search — pairs with `@absolutejs/ai` / `@absolutejs/rag` for RAG retrieval on your own data.                                                   |

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

@@ -42,8 +42,11 @@ export { defineSchedule } from './schedule';
 export type { ScheduleContext, ScheduleDefinition } from './schedule';
 export { defineMutation } from './mutation';
 export type { MutationActions, MutationDefinition, MutationHandler, TableWriter, TransactionRunner } from './mutation';
-export { createSyncEngine, UnauthorizedError } from './syncEngine';
+export { createSyncEngine, SchemaError, UnauthorizedError } from './syncEngine';
 export type { SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
+export { defineSchema, field } from './schema';
+export type { FieldValidator, SchemaDefinition, TableSchema } from './schema';
+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

@@ -1046,6 +1046,13 @@ class UnauthorizedError extends Error {
     this.name = "UnauthorizedError";
   }
 }
+
+class SchemaError extends Error {
+  constructor(table, fieldName) {
+    super(`Schema violation on "${table}": invalid field "${fieldName}"`);
+    this.name = "SchemaError";
+  }
+}
 var defaultKey = (row) => row.id;
 var shallowEqual4 = (a, b) => {
   if (a === b) {
@@ -1082,6 +1089,30 @@ var createSyncEngine = (options = {}) => {
     const rules = permissions.get(table);
     return rules?.[op] ?? rules?.write;
   };
+  const schemas = new Map;
+  for (const [table, schema] of Object.entries(options.schemas ?? {})) {
+    schemas.set(table, schema);
+  }
+  const validateWrite = (table, op, row) => {
+    const schema = schemas.get(table);
+    if (schema === undefined || typeof row !== "object" || row === null) {
+      return;
+    }
+    const record = row;
+    for (const [fieldName, validate] of Object.entries(schema.fields)) {
+      const present = fieldName in record;
+      if (op === "update" && !present) {
+        continue;
+      }
+      if (!validate(record[fieldName])) {
+        throw new SchemaError(table, fieldName);
+      }
+    }
+  };
+  const migrateRow = (table, row) => {
+    const migrate = schemas.get(table)?.migrate;
+    return migrate ? migrate(row) : row;
+  };
   const reactiveSubs = new Set;
   const searchSubs = new Set;
   const searchIndexes = new Map;
@@ -1090,6 +1121,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;
@@ -1216,7 +1253,7 @@ var createSyncEngine = (options = {}) => {
     return {
       all: async (table) => {
         readTables.add(table);
-        const rows = [...await readerFor(table).all(ctx)];
+        const rows = [...await readerFor(table).all(ctx)].map((row) => migrateRow(table, row));
         const rule = ruleFor(table);
         return rule ? rows.filter((row) => rule(ctx, row)) : rows;
       },
@@ -1230,7 +1267,8 @@ var createSyncEngine = (options = {}) => {
         } else {
           readTables.add(table);
         }
-        const row = await reader.get(key, ctx);
+        const raw = await reader.get(key, ctx);
+        const row = raw === undefined ? undefined : migrateRow(table, raw);
         const rule = ruleFor(table);
         return rule && row !== undefined && !rule(ctx, row) ? undefined : row;
       },
@@ -1238,7 +1276,7 @@ var createSyncEngine = (options = {}) => {
         const reader = readerFor(table);
         const rule = ruleFor(table);
         const effective = rule ? (row) => predicate(row) && rule(ctx, row) : predicate;
-        const matched = [...await reader.all(ctx)].filter(effective);
+        const matched = [...await reader.all(ctx)].map((row) => migrateRow(table, row)).filter(effective);
         if (reader.key !== undefined) {
           const key = reader.key;
           rangeDeps.push({
@@ -1293,6 +1331,7 @@ var createSyncEngine = (options = {}) => {
         return Promise.resolve();
       },
       insert: async (table, data) => {
+        validateWrite(table, "insert", data);
         if (enforce) {
           await authorizeWrite(table, "insert", data, ctx);
         }
@@ -1301,6 +1340,7 @@ var createSyncEngine = (options = {}) => {
         return row;
       },
       update: async (table, data) => {
+        validateWrite(table, "update", data);
         if (enforce) {
           await authorizeWrite(table, "update", data, ctx);
         }
@@ -1412,6 +1452,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 +1487,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),
@@ -1705,8 +1759,13 @@ var createSyncEngine = (options = {}) => {
       const key = definition.key ?? defaultKey;
       const match = definition.match;
       const tables = definition.tables ?? [collection];
-      const readRule = tables.length === 1 ? readRuleFor(tables[0]) : undefined;
-      const rehydrate = readRule ? async () => [...await definition.hydrate(params, ctx)].filter((row) => readRule(ctx, row)) : async () => definition.hydrate(params, ctx);
+      const scopedTable = tables.length === 1 ? tables[0] : undefined;
+      const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
+      const rehydrate = async () => {
+        const raw = [...await definition.hydrate(params, ctx)];
+        const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
+        return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
+      };
       const incremental = match !== undefined && tables.length === 1;
       const boundMatch = incremental ? (row) => match(row, params, ctx) && (readRule ? readRule(ctx, row) : true) : () => true;
       const view = createMaterializedView({
@@ -1754,9 +1813,11 @@ var createSyncEngine = (options = {}) => {
           throw new UnauthorizedError(`hydrate collection "${collection}"`);
         }
       }
-      const rows = [...await definition.hydrate(params, ctx)];
+      const raw = [...await definition.hydrate(params, ctx)];
       const tables = definition.tables ?? [collection];
-      const readRule = tables.length === 1 ? readRuleFor(tables[0]) : undefined;
+      const scopedTable = tables.length === 1 ? tables[0] : undefined;
+      const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
+      const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
       return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
     },
     applyChange: (table, change) => applyChange(table, change),
@@ -1804,6 +1865,10 @@ var createSyncEngine = (options = {}) => {
     registerPermissions: (table, rules) => {
       permissions.set(table, rules);
     },
+    registerSchema: (table, schema) => {
+      schemas.set(table, schema);
+    },
+    migrate: (table, row) => migrateRow(table, row),
     runMutation: async (name, args, ctx) => {
       const mutation = mutations.get(name);
       if (mutation === undefined) {
@@ -1816,13 +1881,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,9 +1922,68 @@ 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);
+      };
     }
   };
 };
+// src/engine/schema.ts
+var defineSchema = (schemas) => schemas;
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var field = {
+  string: (value) => typeof value === "string",
+  number: isFiniteNumber,
+  boolean: (value) => typeof value === "boolean",
+  any: () => true,
+  optional: (inner) => (value) => value === undefined || inner(value),
+  array: (inner) => (value) => Array.isArray(value) && value.every(inner),
+  enum: (...values) => (value) => values.includes(value)
+};
 // src/engine/routes.ts
 var emptyContext = () => ({});
 var hydrateRoute = (engine, collection, resolveContext = emptyContext) => {
@@ -2091,7 +2231,9 @@ export {
   hydrateRoute,
   fromRowChange,
   filterOp,
+  field,
   defineSearchCollection,
+  defineSchema,
   defineSchedule,
   defineReactiveQuery,
   definePermissions,
@@ -2112,8 +2254,9 @@ export {
   chain,
   aggregateOp,
   UnauthorizedError,
+  SchemaError,
   SEARCH_SCORE_FIELD
 };
 
-//# debugId=54AD7964887E323764756E2164756E21
+//# debugId=B040890280D3C67864756E2164756E21
 //# sourceMappingURL=index.js.map