@absolutejs/sync 1.5.0 → 1.7.0

package/dist/engine/pollingSource.d.ts

@@ -33,6 +33,13 @@ export type PollingChangeSourceOptions = {
     onProcessed?: (uptoSeq: number) => void | Promise<void>;
     /** Called if a poll throws (the loop keeps running). Defaults to a warning. */
     onError?: (error: unknown) => void;
+    /**
+     * Called when an outbox row fails to parse (custom `parse` returned
+     * undefined, malformed JSON in `payload`, unknown `op`, etc). Default:
+     * silently dropped. Provide this to surface skipped rows so you notice
+     * malformed entries in the changelog table.
+     */
+    onSkip?: (row: OutboxRow, reason: 'parse-failed') => void;
 };
 /**
  * Create a polling {@link ChangeSource} over a changelog table. Connect it with

package/dist/engine/sandbox.d.ts

@@ -12,13 +12,27 @@
  * - First call per mutation pays a Worker spawn + compile (~30 ms). Every
  *   subsequent call reuses the isolate and only spends ~0.5 ms creating a
  *   fresh context.
- * - Timeout terminates the isolate (v1 of isolated-jsc trade-off — the
- *   sandbox runner detects this and lazily re-spawns on the next call).
+ * - Timeout terminates the isolate (the sandbox runner detects this and
+ *   lazily re-spawns on the next call). On the FFI backend timeouts throw
+ *   a TerminationException without killing the isolate; sync's runner
+ *   treats both shapes the same.
  * - Each per-call context retains some JSC metadata until the isolate's
- *   next GC sweep. Empirically ~2 MB residual per call. For long-lived
- *   mutations choose `memoryLimit` ≥ 128 (the default 32 trips after a
- *   few dozen calls without pressure for GC). v2 will let us trigger
- *   sweep explicitly from the host; for now, size up.
+ *   next GC sweep. Empirically ~2 MB residual per call (Worker backend).
+ *   For long-lived mutations choose `memoryLimit` ≥ 128 (the default 32
+ *   trips after a few dozen calls without pressure for GC).
+ *
+ * **Backend default: `'worker'`** — required so far because the `actions`
+ * machinery (insert/update/delete/change) crosses the host boundary as
+ * **async** References (they return Promises that go through the engine's
+ * writer + diff path). The isolated-jsc FFI backend only supports SYNC
+ * host fns today (per its 0.3 documented limit); calling
+ * `actions.insert(...)` from a sandboxed handler on FFI would surface as
+ * a Promise-cannot-unwrap error. Pin to Worker.
+ *
+ * Read-only sandboxed mutations that don't call `actions.*` (e.g. compute
+ * a derived value from `args` + `ctx` and `return` it) CAN opt into FFI
+ * via `sandbox: { backend: 'ffi' }` — they get the ~300 KB cold heap and
+ * interrupt-driven timeouts. Document this clearly when you do.
  *
  * The runner is built lazily per-mutation: nothing is spawned until the
  * mutation actually runs for the first time. No engine teardown hook is
@@ -31,6 +45,22 @@ export type SandboxConfig = {
     memoryLimit?: number;
     /** Wall-clock cap per call (ms). Default 5000. */
     timeout?: number;
+    /**
+     * isolated-jsc backend. Defaults to `'worker'` because the engine's
+     * `actions.insert/update/delete/change` cross the sandbox boundary as
+     * async References — and isolated-jsc's FFI backend doesn't pump
+     * async host fns (its 0.3 documented limit). The Worker backend
+     * supports both sync and async host fns.
+     *
+     * Opt into `'ffi'` only for **read-only** sandboxed handlers — ones
+     * that compute a derived value from `args` + `ctx` and return it
+     * without calling any `actions.*`. Those get the FFI cold-heap
+     * (~300 KB vs ~46 MB) + interrupt-driven timeout benefits.
+     *
+     * `'auto'` resolves to FFI when libJSC is reachable and Worker
+     * otherwise; same async-actions caveat applies on the FFI path.
+     */
+    backend?: 'auto' | 'ffi' | 'worker';
 };
 /**
  * Build a lazy runner for one mutation's sandboxed source. The first call

package/dist/engine/syncEngine.d.ts

@@ -187,7 +187,81 @@ export type SyncEngine = {
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.
      */
     onActivity: (listener: (event: EngineActivity) => void) => () => void;
+    /**
+     * Outbound CDC stream — yield every committed change as a {@link LoggedChange},
+     * historical first (entries with `version > since`) then continuously tailing
+     * live commits. Use it to feed downstream pipelines (Kafka, search indexers,
+     * audit logs, analytics warehouses).
+     *
+     * The iterator is notify-driven (no polling): it parks on a Promise that
+     * resolves the instant a new commit lands.
+     *
+     * If `since` falls before the oldest entry retained in the bounded change
+     * log, the iterator throws {@link MissedChangesError} so the consumer
+     * notices the gap instead of silently skipping commits. Resubscribe with
+     * `since = engine.inspect().recentChanges[0].version` after re-bootstrapping.
+     *
+     * If the consumer iterates slower than the engine commits and the in-flight
+     * buffer overflows (`maxBuffer`, default 10000), the iterator throws
+     * {@link CdcConsumerSlowError} for the same reason.
+     *
+     * @example
+     * for await (const entry of engine.streamChanges({ since: lastCursor })) {
+     *   await kafka.send('sync.changes', JSON.stringify(entry));
+     *   lastCursor = entry.version;
+     * }
+     */
+    streamChanges: (options?: StreamChangesOptions) => AsyncIterable<LoggedChange>;
+};
+/**
+ * A single committed change as it appears in the engine's change log and on
+ * the {@link SyncEngine.streamChanges} CDC stream. Versions are monotonic
+ * across the engine: a single mutation that writes N rows emits N entries
+ * all sharing the same `version`.
+ */
+export type LoggedChange = {
+    version: number;
+    table: string;
+    change: RowChange<unknown>;
 };
+/** Thrown by {@link SyncEngine.streamChanges} when `since` is older than the
+ * oldest entry retained in the bounded change log (i.e. the consumer was
+ * disconnected long enough that the engine has lost the diff). The consumer
+ * should re-bootstrap from a fresh hydrate and resume from `availableSince`. */
+export declare class MissedChangesError extends Error {
+    readonly requestedSince: number;
+    readonly availableSince: number;
+    constructor(requestedSince: number, availableSince: number);
+}
+/** Options for {@link SyncEngine.streamChanges}. */
+export type StreamChangesOptions = {
+    /**
+     * Last version the consumer has already processed. The stream yields
+     * entries with `version > since`. Defaults to `0` (replay everything in
+     * the log, then tail).
+     */
+    since?: number;
+    /**
+     * Cancel the stream cleanly. When the signal aborts, the iterator
+     * resolves to `done` on its next yield and unregisters its subscriber.
+     */
+    signal?: AbortSignal;
+    /**
+     * Hard cap on the in-flight buffer for this consumer. If the engine
+     * commits faster than the consumer iterates and the buffer overflows,
+     * the stream rejects so the consumer notices instead of silently
+     * skipping entries. Defaults to 10000.
+     */
+    maxBuffer?: number;
+};
+/** Thrown by {@link SyncEngine.streamChanges} when the consumer fell so far
+ * behind that the in-flight buffer overflowed. Resubscribe from the last
+ * cursor the consumer successfully processed. */
+export declare class CdcConsumerSlowError extends Error {
+    readonly maxBuffer: number;
+    readonly lastDeliveredVersion: number;
+    constructor(maxBuffer: number, lastDeliveredVersion: number);
+}
 export type SyncEngineOptions = {
     /**
      * How many recent changes to retain for resumable reconnects. A client that

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { sync } from './plugin';
 export type { SyncPluginOptions, SyncRequestContext } from './plugin';
 export { syncSocket } from './engine/socket';
 export type { SyncSocketOptions } from './engine/socket';
+export { syncCdc } from './engine/cdc';
+export type { SyncCdcOptions } from './engine/cdc';
 export { syncDevtools } from './devtools';
 export type { SyncDevtoolsOptions } from './devtools';
 export { createPresenceHub } from './engine/presence';