@absolutejs/sync 1.5.0 → 1.6.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/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';