@absolutejs/sync 0.5.0 → 0.6.0

package/README.md

@@ -33,9 +33,9 @@ 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, 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, 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
 
@@ -280,6 +280,32 @@ await orders.mutate({
     });
     ```
 
+- **Scheduled functions.** Register server-side work that runs on a cron pattern;
+  whatever it writes via `ctx.actions` goes live through the change feed (and it can
+  read current state via `ctx.db`). Cron decides _when_ (via `@elysiajs/cron`, an
+  optional peer); the engine makes the effect _live_. It doesn't reinvent jobs —
+  for durable, retryable work a schedule can `enqueue` into
+  [`@absolutejs/queue`](https://github.com/absolutejs/queue).
+
+    ```ts
+    import { scheduled } from '@absolutejs/sync';
+
+    engine.registerSchedule({
+    	name: 'digest',
+    	pattern: '0 8 * * 1', // Mondays 08:00 (6-field for seconds: '*/5 * * * * *')
+    	run: async ({ db, actions }) => {
+    		const stale = await db.all('reports');
+    		await actions.insert('digests', {
+    			id: crypto.randomUUID(),
+    			at: Date.now()
+    		});
+    		// or: queue.enqueue('email.send', { … }) for durable delivery
+    	}
+    });
+
+    new Elysia().use(syncSocket({ engine })).use(scheduled({ engine })); // wires cron
+    ```
+
 ## Write-behind cache — keep a remote store off your hot path
 
 ```ts
@@ -306,12 +332,13 @@ 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.                         |
-| `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? })`                                                 | Elysia plugin: fires the engine's registered schedules on their cron patterns (via `@elysiajs/cron`). |
+| `createWriteBehindCache({ load, persist, remove?, debounceMs?, evict?, onPersistError? })` | In-memory cache + write-behind persistence.                                                           |
 
 ### `@absolutejs/sync/client`
 
@@ -377,6 +404,7 @@ mutate({
 | `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.                                                   |
+| `defineSchedule({ name, pattern, run })` + `registerSchedule` / `runSchedule`            | Scheduled function: `run({ db, actions })` fires on a cron `pattern`; its writes go live through the change feed. Wire triggers with the `scheduled` plugin (or call `runSchedule(name)` on demand).                   |
 
 ### `@absolutejs/sync/postgres`
 

package/dist/engine/index.d.ts

@@ -38,6 +38,8 @@ export { createTextIndex } from './textIndex';
 export type { TextIndexOptions } from './textIndex';
 export { createVectorIndex } from './vectorIndex';
 export type { VectorIndexOptions, VectorMetric } from './vectorIndex';
+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';

package/dist/engine/index.js

@@ -1035,6 +1035,8 @@ var createVectorIndex = (options) => {
     }
   };
 };
+// src/engine/schedule.ts
+var defineSchedule = (definition) => definition;
 // src/engine/mutation.ts
 var defineMutation = (definition) => definition;
 // src/engine/syncEngine.ts
@@ -1070,6 +1072,7 @@ var createSyncEngine = (options = {}) => {
   const mutations = new Map;
   const writers = new Map;
   const readers = new Map;
+  const schedules = new Map;
   const permissions = new Map;
   for (const [table, rules] of Object.entries(options.permissions ?? {})) {
     permissions.set(table, rules);
@@ -1201,7 +1204,7 @@ var createSyncEngine = (options = {}) => {
   };
   const depKey = (table, key) => `${table} ${key}`;
   const changedKeyFor = (table, change) => readers.get(table)?.key?.(change.row);
-  const makeReadHandle = (ctx, readTables, readKeys, rangeDeps) => {
+  const makeReadHandle = (ctx, readTables, readKeys, rangeDeps, applyRules = true) => {
     const readerFor = (table) => {
       const reader = readers.get(table);
       if (reader === undefined) {
@@ -1209,11 +1212,12 @@ var createSyncEngine = (options = {}) => {
       }
       return reader;
     };
+    const ruleFor = (table) => applyRules ? readRuleFor(table) : undefined;
     return {
       all: async (table) => {
         readTables.add(table);
         const rows = [...await readerFor(table).all(ctx)];
-        const rule = readRuleFor(table);
+        const rule = ruleFor(table);
         return rule ? rows.filter((row) => rule(ctx, row)) : rows;
       },
       get: async (table, key) => {
@@ -1227,12 +1231,12 @@ var createSyncEngine = (options = {}) => {
           readTables.add(table);
         }
         const row = await reader.get(key, ctx);
-        const rule = readRuleFor(table);
+        const rule = ruleFor(table);
         return rule && row !== undefined && !rule(ctx, row) ? undefined : row;
       },
       where: async (table, predicate) => {
         const reader = readerFor(table);
-        const rule = readRuleFor(table);
+        const rule = ruleFor(table);
         const effective = rule ? (row) => predicate(row) && rule(ctx, row) : predicate;
         const matched = [...await reader.all(ctx)].filter(effective);
         if (reader.key !== undefined) {
@@ -1249,6 +1253,71 @@ var createSyncEngine = (options = {}) => {
       }
     };
   };
+  const writerFor = (table) => {
+    const writer = writers.get(table);
+    if (writer === undefined) {
+      throw new Error(`No writer registered for table "${table}" \u2014 register one with engine.registerWriter, or use actions.change`);
+    }
+    return writer;
+  };
+  const authorizeWrite = async (table, op, value, ctx) => {
+    const rule = writeRuleFor(table, op);
+    if (rule === undefined) {
+      return;
+    }
+    let subject = value;
+    if (op !== "insert") {
+      const reader = readers.get(table);
+      if (reader?.get !== undefined) {
+        const id = reader.key ? reader.key(value) : value.id;
+        if (id !== undefined) {
+          const existing = await reader.get(id, ctx);
+          if (existing !== undefined) {
+            subject = existing;
+          }
+        }
+      }
+    }
+    if (!rule(ctx, subject)) {
+      throw new UnauthorizedError(`${op} on table "${table}"`);
+    }
+  };
+  const makeActions = (tx, ctx, enforce) => {
+    const buffered = [];
+    const actions = {
+      change: (collection, change) => {
+        buffered.push({
+          table: collection,
+          change
+        });
+        return Promise.resolve();
+      },
+      insert: async (table, data) => {
+        if (enforce) {
+          await authorizeWrite(table, "insert", data, ctx);
+        }
+        const row = await writerFor(table).insert(data, ctx, tx);
+        buffered.push({ table, change: { op: "insert", row } });
+        return row;
+      },
+      update: async (table, data) => {
+        if (enforce) {
+          await authorizeWrite(table, "update", data, ctx);
+        }
+        const row = await writerFor(table).update(data, ctx, tx);
+        buffered.push({ table, change: { op: "update", row } });
+        return row;
+      },
+      delete: async (table, row) => {
+        if (enforce) {
+          await authorizeWrite(table, "delete", row, ctx);
+        }
+        await writerFor(table).delete(row, ctx, tx);
+        buffered.push({ table, change: { op: "delete", row } });
+      }
+    };
+    return { actions, buffered };
+  };
   const diffRerun = (sub, rows, equals = shallowEqual4) => {
     const next = new Map;
     for (const row of rows) {
@@ -1746,69 +1815,32 @@ var createSyncEngine = (options = {}) => {
           throw new UnauthorizedError(`run mutation "${name}"`);
         }
       }
-      const writerFor = (table) => {
-        const writer = writers.get(table);
-        if (writer === undefined) {
-          throw new Error(`No writer registered for table "${table}" \u2014 register one with engine.registerWriter, or use actions.change`);
-        }
-        return writer;
-      };
-      const authorizeWrite = async (table, op, value) => {
-        const rule = writeRuleFor(table, op);
-        if (rule === undefined) {
-          return;
-        }
-        let subject = value;
-        if (op !== "insert") {
-          const reader = readers.get(table);
-          if (reader?.get !== undefined) {
-            const id = reader.key ? reader.key(value) : value.id;
-            if (id !== undefined) {
-              const existing = await reader.get(id, ctx);
-              if (existing !== undefined) {
-                subject = existing;
-              }
-            }
-          }
-        }
-        if (!rule(ctx, subject)) {
-          throw new UnauthorizedError(`${op} on table "${table}"`);
-        }
-      };
       const runHandler = async (tx) => {
-        const buffered2 = [];
-        const actions = {
-          change: (collection, change) => {
-            buffered2.push({
-              table: collection,
-              change
-            });
-            return Promise.resolve();
-          },
-          insert: async (table, data) => {
-            await authorizeWrite(table, "insert", data);
-            const row = await writerFor(table).insert(data, ctx, tx);
-            buffered2.push({ table, change: { op: "insert", row } });
-            return row;
-          },
-          update: async (table, data) => {
-            await authorizeWrite(table, "update", data);
-            const row = await writerFor(table).update(data, ctx, tx);
-            buffered2.push({ table, change: { op: "update", row } });
-            return row;
-          },
-          delete: async (table, row) => {
-            await authorizeWrite(table, "delete", row);
-            await writerFor(table).delete(row, ctx, tx);
-            buffered2.push({ table, change: { op: "delete", row } });
-          }
-        };
-        const handlerResult = await mutation.handler(args, ctx, actions);
-        return { buffered: buffered2, result: handlerResult };
+        const { actions, buffered: buffered2 } = makeActions(tx, ctx, true);
+        const result2 = await mutation.handler(args, ctx, actions);
+        return { buffered: buffered2, result: result2 };
       };
       const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
       await applyChangeBatch(buffered);
       return result;
+    },
+    registerSchedule: (schedule) => {
+      schedules.set(schedule.name, schedule);
+    },
+    listSchedules: () => [...schedules.values()],
+    runSchedule: async (name) => {
+      const schedule = schedules.get(name);
+      if (schedule === undefined) {
+        throw new Error(`Unknown schedule "${name}"`);
+      }
+      const runHandler = async (tx) => {
+        const { actions, buffered: buffered2 } = makeActions(tx, {}, false);
+        const db = makeReadHandle({}, new Set, new Set, [], false);
+        await schedule.run({ actions, db });
+        return buffered2;
+      };
+      const buffered = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
+      await applyChangeBatch(buffered);
     }
   };
 };
@@ -2060,6 +2092,7 @@ export {
   fromRowChange,
   filterOp,
   defineSearchCollection,
+  defineSchedule,
   defineReactiveQuery,
   definePermissions,
   defineMutation,
@@ -2082,5 +2115,5 @@ export {
   SEARCH_SCORE_FIELD
 };
 
-//# debugId=28E08370F43FEBAE64756E2164756E21
+//# debugId=54AD7964887E323764756E2164756E21
 //# sourceMappingURL=index.js.map