@absolutejs/sync 1.8.1 → 1.9.0

package/dist/engine/pack.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Sync packs — Convex Components without the lock-in. A pack bundles
+ * schemas + collections + mutations + scheduled + permissions + readers/
+ * writers + CRDT field declarations into one npm-distributable module
+ * registered with a single {@link SyncEngine.registerPack} call.
+ *
+ * See `syncPacks.design.md` for the rationale and the worked examples.
+ *
+ * Pack design rules (enforced at register time):
+ *
+ * - A pack declares which tables it `ownsTables`. Two registered packs
+ *   cannot claim the same table; the host app's directly-registered
+ *   tables are NOT counted (host registrations always win).
+ * - Name construction (namespacing) is the pack's job — each published
+ *   pack ships as a factory `create<Name>Pack(config)` that builds names
+ *   from a `tablePrefix` and the host's user/auth context.
+ * - Packs compose via the subscription layer (read each other's
+ *   collections), never via cross-pack `runMutation` calls.
+ */
+import type { CollectionDefinition, JoinCollectionDefinition } from './collection';
+import type { GraphCollectionDefinition } from './graph';
+import type { MutationDefinition, TableWriter } from './mutation';
+import type { PermissionsDefinition } from './permissions';
+import type { ReactiveQueryDefinition, TableReader } from './reactive';
+import type { ScheduleDefinition } from './schedule';
+import type { SchemaDefinition } from './schema';
+import type { SearchCollectionDefinition } from './search';
+import type { CrdtMergeable } from '../crdt';
+/**
+ * Same shape as the engine's per-table CRDT field map (see
+ * {@link SyncEngine.registerCrdt}). A pack declares CRDT field types
+ * here; the engine wires them on registration.
+ */
+export type CrdtFieldsMap = Record<string, Record<string, CrdtMergeable<unknown>>>;
+/**
+ * A pack — a self-contained bundle of every registration the engine
+ * already accepts. The engine's `registerPack(pack)` dispatches each
+ * field to the matching `engine.register*` method. There is no new
+ * persistence path; packs are pure composition.
+ */
+export type SyncPack = {
+    /**
+     * Pack identifier. Used for devtools labelling and conflict
+     * diagnostics. Should match the npm package name (e.g.
+     * "@absolutejs/sync-pack-presence").
+     */
+    name: string;
+    /**
+     * Pack semver. Surfaced in {@link EngineInspection.packs} and in
+     * conflict diagnostics (e.g. "table 'comments' is owned by
+     * sync-pack-comments@2.1.0").
+     */
+    version: string;
+    /**
+     * Tables this pack OWNS. The engine rejects another pack that also
+     * claims one of these. Direct host registrations (e.g.
+     * `engine.registerSchema("foo", ...)`) are NOT tracked as ownership,
+     * so the host can still extend a pack's table or override its
+     * schema/permissions.
+     */
+    ownsTables: string[];
+    /**
+     * Tables this pack reads but does NOT own (e.g. a comments pack
+     * reads the host's `users` table for author info). Reported in
+     * {@link EngineInspection.packs}; not enforced unless
+     * {@link requireDependencies} is `true`.
+     */
+    readsTables?: string[];
+    /**
+     * When `true`, the engine throws {@link PackMissingDependencyError}
+     * at register time if any table in `readsTables` has no registered
+     * reader. Default `false` — host-app reads can be wired lazily.
+     */
+    requireDependencies?: boolean;
+    schemas?: SchemaDefinition;
+    permissions?: PermissionsDefinition<any>;
+    readers?: Record<string, TableReader<any>>;
+    writers?: Record<string, TableWriter<any, any, any>>;
+    crdt?: CrdtFieldsMap;
+    collections?: CollectionDefinition<any, any, any>[];
+    joinCollections?: JoinCollectionDefinition<any, any, any, any, any>[];
+    graphCollections?: GraphCollectionDefinition<any, any, any>[];
+    searchCollections?: SearchCollectionDefinition<any, any, any>[];
+    reactiveQueries?: ReactiveQueryDefinition<any, any, any>[];
+    mutations?: MutationDefinition<any, any, any>[];
+    schedules?: ScheduleDefinition[];
+};
+/**
+ * Pack metadata stored on the engine and surfaced via
+ * {@link EngineInspection.packs}.
+ */
+export type RegisteredPack = {
+    name: string;
+    version: string;
+    ownsTables: string[];
+    readsTables: string[];
+};
+/**
+ * Thrown by {@link SyncEngine.registerPack} when a pack claims a table
+ * that another registered pack already owns. The message names both
+ * packs and the colliding table so the operator can pick a
+ * `tablePrefix`.
+ */
+export declare class PackTableConflictError extends Error {
+    readonly table: string;
+    readonly existingPack: string;
+    readonly newPack: string;
+    constructor(table: string, existingPack: string, newPack: string);
+}
+/**
+ * Thrown by {@link SyncEngine.registerPack} when a pack has
+ * `requireDependencies: true` and at least one table in
+ * {@link SyncPack.readsTables} has no registered reader at register
+ * time. Pack authors opt into this when their pack cannot function
+ * without the host having wired the dependency up front.
+ */
+export declare class PackMissingDependencyError extends Error {
+    readonly pack: string;
+    readonly missingTable: string;
+    constructor(pack: string, missingTable: string);
+}
+/**
+ * Identity helper. A pack is plain data — the helper exists for type
+ * inference, not for runtime behavior.
+ *
+ * @example
+ * export const createPresencePack = (config: PresencePackConfig) =>
+ *   defineSyncPack({
+ *     name: '@absolutejs/sync-pack-presence',
+ *     version: '0.1.0',
+ *     ownsTables: [resolveTableName('presence', config.tablePrefix)],
+ *     schemas: { ... },
+ *     collections: [ ... ],
+ *     mutations: [ ... ],
+ *     schedules: [ ... ],
+ *   });
+ */
+export declare const defineSyncPack: (pack: SyncPack) => SyncPack;

package/dist/engine/schedule.d.ts

@@ -1,5 +1,6 @@
 import type { MutationActions } from './mutation';
 import type { ReadHandle } from './reactive';
+import type { RetryPolicy } from './retry';
 /**
  * Scheduled functions — server-triggered work whose effects flow through the
  * change feed, so what a schedule writes goes live to subscribers with no extra
@@ -30,6 +31,19 @@ export type ScheduleDefinition = {
     pattern: string;
     /** The work to run on each fire. Writes via `ctx.actions` go live. */
     run: (ctx: ScheduleContext) => Promise<void> | void;
+    /**
+     * Opt-in retry of the whole handler on classified-as-retryable errors —
+     * same shape and defaults as {@link MutationDefinition.retry}. When set
+     * and `run` throws a retryable error, the engine discards the buffered
+     * changes, awaits a backoff, and re-runs the handler with a fresh
+     * transaction. The handler MUST be idempotent under retry (external
+     * side effects fire more than once).
+     *
+     * For per-item retry (e.g. one of many emails failing), write that
+     * loop inside the handler — this outer retry covers transient
+     * infrastructure failures of the whole fire, not per-item logic.
+     */
+    retry?: RetryPolicy;
 };
 /**
  * Define a scheduled function. Identity at runtime (for type inference). Register

package/dist/engine/syncEngine.d.ts

@@ -4,6 +4,7 @@ import type { MutationDefinition, TableWriter, TransactionRunner } from './mutat
 import type { ReactiveQueryDefinition, TableReader } from './reactive';
 import { type BridgeFetchConfig, type HandlerMetricsHook } from './sandbox';
 import type { PermissionsDefinition, TablePermissions } from './permissions';
+import type { SyncPack } from './pack';
 import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
 import type { EngineActivity, EngineInspection } from './devtools';
@@ -213,6 +214,18 @@ export type SyncEngine = {
      * }
      */
     streamChanges: (options?: StreamChangesOptions) => AsyncIterable<LoggedChange>;
+    /**
+     * Register a {@link SyncPack} — a self-contained bundle of schemas,
+     * permissions, readers/writers, collections, mutations, and schedules.
+     * Dispatches each field to the matching `register*` method. Rejects
+     * with {@link PackTableConflictError} if the pack claims a table
+     * another registered pack already owns; with
+     * {@link PackMissingDependencyError} if `requireDependencies` is set
+     * and a `readsTables` entry has no registered reader.
+     *
+     * See `syncPacks.design.md` for the rationale.
+     */
+    registerPack: (pack: SyncPack) => void;
 };
 /**
  * A single committed change as it appears in the engine's change log and on

package/dist/index.js

@@ -935,6 +935,32 @@ var fireMetrics = (hook, record) => {
   }
 };
 
+// src/engine/pack.ts
+class PackTableConflictError extends Error {
+  table;
+  existingPack;
+  newPack;
+  constructor(table, existingPack, newPack) {
+    super(`Pack "${newPack}" claims table "${table}", but "${existingPack}" already owns it. Use a tablePrefix on one of them.`);
+    this.name = "PackTableConflictError";
+    this.table = table;
+    this.existingPack = existingPack;
+    this.newPack = newPack;
+  }
+}
+
+class PackMissingDependencyError extends Error {
+  pack;
+  missingTable;
+  constructor(pack, missingTable) {
+    super(`Pack "${pack}" requires a reader for table "${missingTable}" but none is registered. Call engine.registerReader("${missingTable}", ...) before engine.registerPack.`);
+    this.name = "PackMissingDependencyError";
+    this.pack = pack;
+    this.missingTable = missingTable;
+  }
+}
+var defineSyncPack = (pack) => pack;
+
 // src/engine/search.ts
 var SEARCH_SCORE_FIELD = "_score";
 var defineSearchCollection = (definition) => ({
@@ -1044,6 +1070,8 @@ var createSyncEngine = (options = {}) => {
   const writers = new Map;
   const readers = new Map;
   const schedules = new Map;
+  const packTableOwners = new Map;
+  const registeredPacks = [];
   const permissions = new Map;
   for (const [table, rules] of Object.entries(options.permissions ?? {})) {
     permissions.set(table, rules);
@@ -1775,7 +1803,7 @@ var createSyncEngine = (options = {}) => {
       }
     };
   };
-  return {
+  const engine = {
     register: (collection) => {
       registry.set(collection.name, collection);
       for (const table of collection.tables ?? [collection.name]) {
@@ -2050,13 +2078,136 @@ var createSyncEngine = (options = {}) => {
         throw new Error(`Unknown schedule "${name}"`);
       }
       const runHandler = async (tx) => {
-        const { actions, buffered: buffered2 } = makeActions(tx, {}, false);
+        const { actions, buffered } = makeActions(tx, {}, false);
         const db = makeReadHandle({}, new Set, new Set, [], false);
         await schedule.run({ actions, db });
-        return buffered2;
+        return buffered;
       };
-      const buffered = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
-      await applyChangeBatch(buffered);
+      const retry = schedule.retry;
+      const maxAttempts = retry === undefined ? 1 : retry.maxAttempts ?? 5;
+      const isRetryable = retry?.isRetryable ?? isSerializationFailure;
+      const computeDelay = retry?.backoff ?? exponentialBackoff();
+      const maxElapsedMs = retry?.maxElapsedMs ?? 30000;
+      const startedAt = Date.now();
+      let lastError;
+      let attemptsMade = 0;
+      for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+        attemptsMade = attempt;
+        try {
+          const buffered = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
+          await applyChangeBatch(buffered);
+          emitActivity({
+            type: "schedule",
+            at: Date.now(),
+            name,
+            status: "ok"
+          });
+          return;
+        } catch (error) {
+          lastError = error;
+          const elapsedMs = Date.now() - startedAt;
+          const canRetry = attempt < maxAttempts && isRetryable(error) && elapsedMs < maxElapsedMs;
+          if (!canRetry)
+            break;
+          const rawDelay = computeDelay(attempt);
+          const remaining = maxElapsedMs - elapsedMs;
+          if (remaining <= 0)
+            break;
+          const delayMs = Math.max(0, Math.min(rawDelay, remaining));
+          emitActivity({
+            type: "scheduleRetry",
+            at: Date.now(),
+            name,
+            attempt,
+            delayMs,
+            errorName: error instanceof Error ? error.name : "Error",
+            errorMessage: error instanceof Error ? error.message : String(error)
+          });
+          if (delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+          }
+        }
+      }
+      emitActivity({
+        type: "schedule",
+        at: Date.now(),
+        name,
+        status: "error"
+      });
+      if (attemptsMade > 1) {
+        throw new RetriesExhaustedError(attemptsMade, Date.now() - startedAt, lastError);
+      }
+      throw lastError;
+    },
+    registerPack: (pack) => {
+      for (const table of pack.ownsTables) {
+        const existing = packTableOwners.get(table);
+        if (existing !== undefined) {
+          throw new PackTableConflictError(table, existing, pack.name);
+        }
+      }
+      if (pack.requireDependencies === true) {
+        for (const table of pack.readsTables ?? []) {
+          if (!readers.has(table)) {
+            throw new PackMissingDependencyError(pack.name, table);
+          }
+        }
+      }
+      if (pack.schemas !== undefined) {
+        for (const [table, schema] of Object.entries(pack.schemas)) {
+          engine.registerSchema(table, schema);
+        }
+      }
+      if (pack.permissions !== undefined) {
+        for (const [table, rules] of Object.entries(pack.permissions)) {
+          engine.registerPermissions(table, rules);
+        }
+      }
+      if (pack.readers !== undefined) {
+        for (const [table, reader] of Object.entries(pack.readers)) {
+          engine.registerReader(table, reader);
+        }
+      }
+      if (pack.writers !== undefined) {
+        for (const [table, writer] of Object.entries(pack.writers)) {
+          engine.registerWriter(table, writer);
+        }
+      }
+      if (pack.crdt !== undefined) {
+        for (const [table, fields] of Object.entries(pack.crdt)) {
+          engine.registerCrdt(table, fields);
+        }
+      }
+      for (const collection of pack.collections ?? []) {
+        engine.register(collection);
+      }
+      for (const collection of pack.joinCollections ?? []) {
+        engine.registerJoin(collection);
+      }
+      for (const collection of pack.graphCollections ?? []) {
+        engine.registerGraph(collection);
+      }
+      for (const collection of pack.searchCollections ?? []) {
+        engine.registerSearch(collection);
+      }
+      for (const query of pack.reactiveQueries ?? []) {
+        engine.registerReactive(query);
+      }
+      for (const mutation of pack.mutations ?? []) {
+        engine.registerMutation(mutation);
+      }
+      for (const schedule of pack.schedules ?? []) {
+        engine.registerSchedule(schedule);
+      }
+      for (const table of pack.ownsTables) {
+        packTableOwners.set(table, pack.name);
+      }
+      registeredPacks.push({
+        name: pack.name,
+        version: pack.version,
+        ownsTables: [...pack.ownsTables],
+        readsTables: [...pack.readsTables ?? []]
+      });
     },
     inspect: () => {
       const collections = [...registry.entries()].map(([name, def]) => {
@@ -2096,6 +2247,12 @@ var createSyncEngine = (options = {}) => {
           version: entry.version,
           table: entry.table,
           op: entry.change.op
+        })),
+        packs: registeredPacks.map((pack) => ({
+          name: pack.name,
+          version: pack.version,
+          ownsTables: [...pack.ownsTables],
+          readsTables: [...pack.readsTables]
         }))
       };
     },
@@ -2182,6 +2339,7 @@ var createSyncEngine = (options = {}) => {
       };
     }
   };
+  return engine;
 };
 
 // src/engine/cdc.ts
@@ -2460,5 +2618,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=DDC1D4CC66583DD464756E2164756E21
+//# debugId=483AEB81CDF95A5764756E2164756E21
 //# sourceMappingURL=index.js.map