@syncular/client 0.0.1-60

package/dist/outbox.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @syncular/client - Sync outbox (commit-based)
+ */
+import type { SyncOperation } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import type { OutboxCommitStatus, SyncClientDb } from './schema';
+export interface OutboxCommit {
+    id: string;
+    client_commit_id: string;
+    status: OutboxCommitStatus;
+    operations: SyncOperation[];
+    last_response_json: string | null;
+    error: string | null;
+    created_at: number;
+    updated_at: number;
+    attempt_count: number;
+    acked_commit_seq: number | null;
+    /** Client schema version when commit was created */
+    schema_version: number;
+}
+export declare function enqueueOutboxCommit<DB extends SyncClientDb>(db: Kysely<DB>, args: {
+    operations: SyncOperation[];
+    clientCommitId?: string;
+    nowMs?: number;
+    /** Client schema version (default: 1) */
+    schemaVersion?: number;
+}): Promise<{
+    id: string;
+    clientCommitId: string;
+}>;
+/**
+ * Atomically claim and return the next sendable outbox commit.
+ *
+ * Uses SELECT then UPDATE with status check to prevent race conditions.
+ * If another tab claims the same commit, retries with a different candidate.
+ */
+export declare function getNextSendableOutboxCommit<DB extends SyncClientDb>(db: Kysely<DB>, options?: {
+    staleTimeoutMs?: number;
+    maxRetries?: number;
+}): Promise<OutboxCommit | null>;
+declare function markOutboxCommitSending<DB extends SyncClientDb>(db: Kysely<DB>, id: string): Promise<void>;
+export declare function markOutboxCommitAcked<DB extends SyncClientDb>(db: Kysely<DB>, args: {
+    id: string;
+    commitSeq?: number | null;
+    responseJson?: string | null;
+}): Promise<void>;
+export declare function markOutboxCommitFailed<DB extends SyncClientDb>(db: Kysely<DB>, args: {
+    id: string;
+    error: string;
+    responseJson?: string | null;
+}): Promise<void>;
+export declare function markOutboxCommitPending<DB extends SyncClientDb>(db: Kysely<DB>, args: {
+    id: string;
+    error?: string | null;
+    responseJson?: string | null;
+}): Promise<void>;
+declare function deleteAckedOutboxCommits<DB extends SyncClientDb>(db: Kysely<DB>): Promise<number>;
+declare function deleteFailedOutboxCommits<DB extends SyncClientDb>(db: Kysely<DB>): Promise<number>;
+declare function clearAllOutboxCommits<DB extends SyncClientDb>(db: Kysely<DB>): Promise<number>;
+/**
+ * Outbox namespace - organized API for outbox operations.
+ *
+ * @example
+ * ```typescript
+ * import { outbox } from '@syncular/client';
+ *
+ * // Enqueue a new commit
+ * const { id } = await outbox.enqueue(db, { operations: [...] });
+ *
+ * // Get next sendable commit
+ * const commit = await outbox.getNextSendable(db);
+ *
+ * // Mark commit status
+ * await outbox.mark.acked(db, { id, commitSeq: 42 });
+ * await outbox.mark.failed(db, { id, error: 'Network error' });
+ * await outbox.mark.pending(db, { id });
+ * await outbox.mark.sending(db, id);
+ *
+ * // Cleanup commits
+ * await outbox.cleanup.acked(db);
+ * await outbox.cleanup.failed(db);
+ * await outbox.cleanup.all(db);
+ * ```
+ */
+export declare const outbox: {
+    /** Enqueue a new commit to the outbox */
+    readonly enqueue: typeof enqueueOutboxCommit;
+    /** Get the next sendable commit (atomically claims it) */
+    readonly getNextSendable: typeof getNextSendableOutboxCommit;
+    /** Mark commit status */
+    readonly mark: {
+        /** Mark commit as sending (in progress) */
+        readonly sending: typeof markOutboxCommitSending;
+        /** Mark commit as acknowledged (successfully synced) */
+        readonly acked: typeof markOutboxCommitAcked;
+        /** Mark commit as failed (permanent error) */
+        readonly failed: typeof markOutboxCommitFailed;
+        /** Mark commit as pending (ready for retry) */
+        readonly pending: typeof markOutboxCommitPending;
+    };
+    /** Cleanup operations */
+    readonly cleanup: {
+        /** Delete all acknowledged commits */
+        readonly acked: typeof deleteAckedOutboxCommits;
+        /** Delete all failed commits */
+        readonly failed: typeof deleteFailedOutboxCommits;
+        /** Delete all commits (clear entire outbox) */
+        readonly all: typeof clearAllOutboxCommits;
+    };
+};
+export {};
+//# sourceMappingURL=outbox.d.ts.map

package/dist/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"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"}

package/dist/outbox.js

@@ -0,0 +1,304 @@
+/**
+ * @syncular/client - Sync outbox (commit-based)
+ */
+import { sql } from 'kysely';
+function randomId() {
+    if (typeof crypto !== 'undefined' &&
+        typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Very small fallback; good enough for tests.
+    return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSyncOperation(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.table !== 'string')
+        return false;
+    if (typeof value.row_id !== 'string')
+        return false;
+    if (value.op !== 'upsert' && value.op !== 'delete')
+        return false;
+    if (value.payload !== null && !isRecord(value.payload))
+        return false;
+    if (!('base_version' in value))
+        return true;
+    return (value.base_version === null ||
+        value.base_version === undefined ||
+        typeof value.base_version === 'number');
+}
+function parseOperations(value) {
+    let parsed = value;
+    if (typeof value === 'string') {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const item of parsed) {
+        if (!isSyncOperation(item))
+            continue;
+        out.push(item);
+    }
+    return out;
+}
+export async function enqueueOutboxCommit(db, args) {
+    const now = args.nowMs ?? Date.now();
+    const id = randomId();
+    const clientCommitId = args.clientCommitId ?? randomId();
+    const schemaVersion = args.schemaVersion ?? 1;
+    await sql `
+    insert into ${sql.table('sync_outbox_commits')} (
+      ${sql.join([
+        sql.ref('id'),
+        sql.ref('client_commit_id'),
+        sql.ref('status'),
+        sql.ref('operations_json'),
+        sql.ref('last_response_json'),
+        sql.ref('error'),
+        sql.ref('created_at'),
+        sql.ref('updated_at'),
+        sql.ref('attempt_count'),
+        sql.ref('acked_commit_seq'),
+        sql.ref('schema_version'),
+    ])}
+    ) values (
+      ${sql.join([
+        sql.val(id),
+        sql.val(clientCommitId),
+        sql.val('pending'),
+        sql.val(JSON.stringify(args.operations ?? [])),
+        sql.val(null),
+        sql.val(null),
+        sql.val(now),
+        sql.val(now),
+        sql.val(0),
+        sql.val(null),
+        sql.val(schemaVersion),
+    ])}
+    )
+  `.execute(db);
+    return { id, clientCommitId };
+}
+/**
+ * Atomically claim and return the next sendable outbox commit.
+ *
+ * Uses SELECT then UPDATE with status check to prevent race conditions.
+ * If another tab claims the same commit, retries with a different candidate.
+ */
+export async function getNextSendableOutboxCommit(db, options) {
+    const staleTimeoutMs = options?.staleTimeoutMs ?? 30000;
+    const maxRetries = options?.maxRetries ?? 3;
+    // Track IDs we've already tried to claim (to avoid retrying the same one)
+    const attemptedIds = new Set();
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const staleThreshold = Date.now() - staleTimeoutMs;
+        const now = Date.now();
+        // Find a candidate to claim, excluding ones we've already tried
+        const attempted = Array.from(attemptedIds);
+        const attemptedFilter = attempted.length === 0
+            ? sql ``
+            : sql `and ${sql.ref('id')} not in (${sql.join(attempted.map((id) => sql.val(id)), sql `, `)})`;
+        const candidateResult = await sql `
+      select ${sql.ref('id')}
+      from ${sql.table('sync_outbox_commits')}
+      where (
+        ${sql.ref('status')} = ${sql.val('pending')}
+        or (
+          ${sql.ref('status')} = ${sql.val('sending')}
+          and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
+        )
+      )
+      ${attemptedFilter}
+      order by ${sql.ref('created_at')} asc
+      limit ${sql.val(1)}
+    `.execute(db);
+        const candidate = candidateResult.rows[0];
+        if (!candidate)
+            return null;
+        attemptedIds.add(candidate.id);
+        // Atomically claim the commit using UPDATE...WHERE with status check
+        const claimResult = await sql `
+      update ${sql.table('sync_outbox_commits')}
+      set
+        ${sql.ref('status')} = ${sql.val('sending')},
+        ${sql.ref('updated_at')} = ${sql.val(now)},
+        ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(1)},
+        ${sql.ref('error')} = ${sql.val(null)},
+        ${sql.ref('last_response_json')} = ${sql.val(null)}
+      where ${sql.ref('id')} = ${sql.val(candidate.id)}
+        and (
+          ${sql.ref('status')} = ${sql.val('pending')}
+          or (
+            ${sql.ref('status')} = ${sql.val('sending')}
+            and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
+          )
+        )
+    `.execute(db);
+        const claimed = Number(claimResult.numAffectedRows ?? 0) > 0;
+        if (claimed) {
+            const rowResult = await sql `
+        select
+          ${sql.ref('id')},
+          ${sql.ref('client_commit_id')},
+          ${sql.ref('status')},
+          ${sql.ref('operations_json')},
+          ${sql.ref('last_response_json')},
+          ${sql.ref('error')},
+          ${sql.ref('created_at')},
+          ${sql.ref('updated_at')},
+          ${sql.ref('attempt_count')},
+          ${sql.ref('acked_commit_seq')},
+          ${sql.ref('schema_version')}
+        from ${sql.table('sync_outbox_commits')}
+        where ${sql.ref('id')} = ${sql.val(candidate.id)}
+      `.execute(db);
+            const row = rowResult.rows[0];
+            if (!row)
+                continue;
+            return {
+                id: row.id,
+                client_commit_id: row.client_commit_id,
+                status: row.status,
+                operations: parseOperations(row.operations_json),
+                last_response_json: row.last_response_json,
+                error: row.error,
+                created_at: row.created_at,
+                updated_at: row.updated_at,
+                attempt_count: row.attempt_count,
+                acked_commit_seq: row.acked_commit_seq,
+                schema_version: row.schema_version ?? 1,
+            };
+        }
+        // Another tab claimed it, retry with next candidate
+    }
+    return null;
+}
+async function markOutboxCommitSending(db, id) {
+    const now = Date.now();
+    await sql `
+    update ${sql.table('sync_outbox_commits')}
+    set
+      ${sql.ref('status')} = ${sql.val('sending')},
+      ${sql.ref('updated_at')} = ${sql.val(now)},
+      ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(1)},
+      ${sql.ref('error')} = ${sql.val(null)},
+      ${sql.ref('last_response_json')} = ${sql.val(null)}
+    where ${sql.ref('id')} = ${sql.val(id)}
+  `.execute(db);
+}
+export async function markOutboxCommitAcked(db, args) {
+    const now = Date.now();
+    await sql `
+    update ${sql.table('sync_outbox_commits')}
+    set
+      ${sql.ref('status')} = ${sql.val('acked')},
+      ${sql.ref('updated_at')} = ${sql.val(now)},
+      ${sql.ref('acked_commit_seq')} = ${sql.val(args.commitSeq ?? null)},
+      ${sql.ref('error')} = ${sql.val(null)},
+      ${sql.ref('last_response_json')} = ${sql.val(args.responseJson ?? null)}
+    where ${sql.ref('id')} = ${sql.val(args.id)}
+  `.execute(db);
+}
+export async function markOutboxCommitFailed(db, args) {
+    const now = Date.now();
+    await sql `
+    update ${sql.table('sync_outbox_commits')}
+    set
+      ${sql.ref('status')} = ${sql.val('failed')},
+      ${sql.ref('updated_at')} = ${sql.val(now)},
+      ${sql.ref('error')} = ${sql.val(args.error)},
+      ${sql.ref('last_response_json')} = ${sql.val(args.responseJson ?? null)}
+    where ${sql.ref('id')} = ${sql.val(args.id)}
+  `.execute(db);
+}
+export async function markOutboxCommitPending(db, args) {
+    const now = Date.now();
+    await sql `
+    update ${sql.table('sync_outbox_commits')}
+    set
+      ${sql.ref('status')} = ${sql.val('pending')},
+      ${sql.ref('updated_at')} = ${sql.val(now)},
+      ${sql.ref('error')} = ${sql.val(args.error ?? null)},
+      ${sql.ref('last_response_json')} = ${sql.val(args.responseJson ?? null)}
+    where ${sql.ref('id')} = ${sql.val(args.id)}
+  `.execute(db);
+}
+async function deleteAckedOutboxCommits(db) {
+    const res = await sql `
+    delete from ${sql.table('sync_outbox_commits')}
+    where ${sql.ref('status')} = ${sql.val('acked')}
+  `.execute(db);
+    return Number(res.numAffectedRows ?? 0);
+}
+async function deleteFailedOutboxCommits(db) {
+    const res = await sql `
+    delete from ${sql.table('sync_outbox_commits')}
+    where ${sql.ref('status')} = ${sql.val('failed')}
+  `.execute(db);
+    return Number(res.numAffectedRows ?? 0);
+}
+async function clearAllOutboxCommits(db) {
+    const res = await sql `delete from ${sql.table('sync_outbox_commits')}`.execute(db);
+    return Number(res.numAffectedRows ?? 0);
+}
+/**
+ * Outbox namespace - organized API for outbox operations.
+ *
+ * @example
+ * ```typescript
+ * import { outbox } from '@syncular/client';
+ *
+ * // Enqueue a new commit
+ * const { id } = await outbox.enqueue(db, { operations: [...] });
+ *
+ * // Get next sendable commit
+ * const commit = await outbox.getNextSendable(db);
+ *
+ * // Mark commit status
+ * await outbox.mark.acked(db, { id, commitSeq: 42 });
+ * await outbox.mark.failed(db, { id, error: 'Network error' });
+ * await outbox.mark.pending(db, { id });
+ * await outbox.mark.sending(db, id);
+ *
+ * // Cleanup commits
+ * await outbox.cleanup.acked(db);
+ * await outbox.cleanup.failed(db);
+ * await outbox.cleanup.all(db);
+ * ```
+ */
+export const outbox = {
+    /** Enqueue a new commit to the outbox */
+    enqueue: enqueueOutboxCommit,
+    /** Get the next sendable commit (atomically claims it) */
+    getNextSendable: getNextSendableOutboxCommit,
+    /** Mark commit status */
+    mark: {
+        /** Mark commit as sending (in progress) */
+        sending: markOutboxCommitSending,
+        /** Mark commit as acknowledged (successfully synced) */
+        acked: markOutboxCommitAcked,
+        /** Mark commit as failed (permanent error) */
+        failed: markOutboxCommitFailed,
+        /** Mark commit as pending (ready for retry) */
+        pending: markOutboxCommitPending,
+    },
+    /** Cleanup operations */
+    cleanup: {
+        /** Delete all acknowledged commits */
+        acked: deleteAckedOutboxCommits,
+        /** Delete all failed commits */
+        failed: deleteFailedOutboxCommits,
+        /** Delete all commits (clear entire outbox) */
+        all: clearAllOutboxCommits,
+    },
+};
+//# sourceMappingURL=outbox.js.map

package/dist/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"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"}

package/dist/plugins/incrementing-version.d.ts

@@ -0,0 +1,34 @@
+import type { SyncClientPlugin } from './types';
+export interface IncrementingVersionPluginOptions {
+    /**
+     * Plugin name (used for debugging).
+     * Defaults to "incrementing-version".
+     */
+    name?: string;
+    /**
+     * Maximum number of rows to track in memory.
+     * Defaults to 10_000.
+     */
+    maxTrackedRows?: number;
+}
+/**
+ * Automatically advances `base_version` for sequential operations on the same row.
+ *
+ * Why this exists:
+ * - UI code often reads a row once and can enqueue multiple updates quickly.
+ * - The server rejects stale `base_version` values (optimistic concurrency).
+ * - When those updates all originate from the same client and are pushed in-order,
+ *   later ops are effectively based on the earlier ops.
+ *
+ * Assumptions:
+ * - The server's row version is an integer that increments by 1 per applied upsert.
+ * - Operations are pushed in commit order for a given client (outbox ordering).
+ *
+ * This plugin:
+ * - Tracks the "next expected server version" per (shape, table, row_id) based on
+ *   successfully applied pushes.
+ * - Rewrites outgoing `base_version` to that expected version when it is higher
+ *   than the caller-provided value, preventing "self-conflicts" on hot rows.
+ */
+export declare function createIncrementingVersionPlugin(options?: IncrementingVersionPluginOptions): SyncClientPlugin;
+//# sourceMappingURL=incrementing-version.d.ts.map

package/dist/plugins/incrementing-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incrementing-version.d.ts","sourceRoot":"","sources":["../../src/plugins/incrementing-version.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,SAAS,CAAC;AAEzE,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,gCAAqC,GAC7C,gBAAgB,CAyElB"}

package/dist/plugins/incrementing-version.js

@@ -0,0 +1,83 @@
+function makeRowKey(op) {
+    return `${op.table}\u001f${op.row_id}`;
+}
+function touchLru(map, key, value, max) {
+    // Maintain insertion order as an LRU.
+    map.delete(key);
+    map.set(key, value);
+    if (map.size <= max)
+        return;
+    const firstKey = map.keys().next().value;
+    if (firstKey)
+        map.delete(firstKey);
+}
+/**
+ * Automatically advances `base_version` for sequential operations on the same row.
+ *
+ * Why this exists:
+ * - UI code often reads a row once and can enqueue multiple updates quickly.
+ * - The server rejects stale `base_version` values (optimistic concurrency).
+ * - When those updates all originate from the same client and are pushed in-order,
+ *   later ops are effectively based on the earlier ops.
+ *
+ * Assumptions:
+ * - The server's row version is an integer that increments by 1 per applied upsert.
+ * - Operations are pushed in commit order for a given client (outbox ordering).
+ *
+ * This plugin:
+ * - Tracks the "next expected server version" per (shape, table, row_id) based on
+ *   successfully applied pushes.
+ * - Rewrites outgoing `base_version` to that expected version when it is higher
+ *   than the caller-provided value, preventing "self-conflicts" on hot rows.
+ */
+export function createIncrementingVersionPlugin(options = {}) {
+    const name = options.name ?? 'incrementing-version';
+    const maxTrackedRows = Math.max(1, Math.min(1_000_000, options.maxTrackedRows ?? 10_000));
+    const nextExpectedBaseVersionByRow = new Map();
+    return {
+        name,
+        beforePush(_ctx, request) {
+            const operations = request.operations.map((op) => {
+                if (typeof op.base_version !== 'number')
+                    return op;
+                const key = makeRowKey(op);
+                const nextExpected = nextExpectedBaseVersionByRow.get(key);
+                if (typeof nextExpected !== 'number')
+                    return op;
+                if (nextExpected > op.base_version) {
+                    return { ...op, base_version: nextExpected };
+                }
+                return op;
+            });
+            return { ...request, operations };
+        },
+        afterPush(_ctx, args) {
+            // Rejected commits are rolled back by the server; nothing is applied.
+            if (args.response.status !== 'applied' &&
+                args.response.status !== 'cached') {
+                return args.response;
+            }
+            for (const result of args.response.results ?? []) {
+                if (result.status !== 'applied')
+                    continue;
+                const op = args.request.operations[result.opIndex];
+                if (!op)
+                    continue;
+                const key = makeRowKey(op);
+                if (op.op === 'delete') {
+                    nextExpectedBaseVersionByRow.delete(key);
+                    continue;
+                }
+                if (typeof op.base_version === 'number') {
+                    touchLru(nextExpectedBaseVersionByRow, key, op.base_version + 1, maxTrackedRows);
+                }
+                else {
+                    // Insert case: most shapes start at version 1.
+                    touchLru(nextExpectedBaseVersionByRow, key, 1, maxTrackedRows);
+                }
+            }
+            return args.response;
+        },
+    };
+}
+//# sourceMappingURL=incrementing-version.js.map

package/dist/plugins/incrementing-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incrementing-version.js","sourceRoot":"","sources":["../../src/plugins/incrementing-version.ts"],"names":[],"mappings":"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"}

package/dist/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export * from './incrementing-version';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,SAAS,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,3 @@
+export * from './incrementing-version';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,SAAS,CAAC"}

package/dist/plugins/types.d.ts

@@ -0,0 +1,49 @@
+import type { SyncPullRequest, SyncPullResponse, SyncPushRequest, SyncPushResponse } from '@syncular/core';
+export interface SyncClientPluginContext {
+    actorId: string;
+    clientId: string;
+}
+/**
+ * Plugin priority levels for ordering execution.
+ * Lower numbers execute first.
+ */
+export declare const PluginPriority: {
+    /** Compression should run early (before encryption) */
+    readonly COMPRESSION: 10;
+    /** Encryption should run after compression but before transport */
+    readonly ENCRYPTION: 20;
+    /** Default priority for general plugins */
+    readonly DEFAULT: 50;
+    /** Logging/telemetry should run last */
+    readonly TELEMETRY: 100;
+};
+export interface SyncClientPlugin {
+    name: string;
+    /**
+     * Plugin priority for ordering. Lower numbers execute first.
+     * @default PluginPriority.DEFAULT (50)
+     */
+    priority?: number;
+    /**
+     * Called before sending a push request to the server.
+     * Use this for client-side encryption, payload shaping, etc.
+     */
+    beforePush?(ctx: SyncClientPluginContext, request: SyncPushRequest): Promise<SyncPushRequest> | SyncPushRequest;
+    /**
+     * Called after receiving a push response from the server.
+     * Receives both the request and the response to allow opIndex correlation.
+     */
+    afterPush?(ctx: SyncClientPluginContext, args: {
+        request: SyncPushRequest;
+        response: SyncPushResponse;
+    }): Promise<SyncPushResponse> | SyncPushResponse;
+    /**
+     * Called after receiving a pull response from the server (and after any
+     * snapshot chunk materialization), but before applying it to the local DB.
+     */
+    afterPull?(ctx: SyncClientPluginContext, args: {
+        request: SyncPullRequest;
+        response: SyncPullResponse;
+    }): Promise<SyncPullResponse> | SyncPullResponse;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB,uDAAuD;;IAEvD,mEAAmE;;IAEnE,2CAA2C;;IAE3C,wCAAwC;;CAEhC,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,UAAU,CAAC,CACT,GAAG,EAAE,uBAAuB,EAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,CACR,GAAG,EAAE,uBAAuB,EAC5B,IAAI,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAC7D,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;IAEhD;;;OAGG;IACH,SAAS,CAAC,CACR,GAAG,EAAE,uBAAuB,EAC5B,IAAI,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAC7D,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;CACjD"}

package/dist/plugins/types.js

@@ -0,0 +1,15 @@
+/**
+ * Plugin priority levels for ordering execution.
+ * Lower numbers execute first.
+ */
+export const PluginPriority = {
+    /** Compression should run early (before encryption) */
+    COMPRESSION: 10,
+    /** Encryption should run after compression but before transport */
+    ENCRYPTION: 20,
+    /** Default priority for general plugins */
+    DEFAULT: 50,
+    /** Logging/telemetry should run last */
+    TELEMETRY: 100,
+};
+//# sourceMappingURL=types.js.map

package/dist/plugins/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,uDAAuD;IACvD,WAAW,EAAE,EAAE;IACf,mEAAmE;IACnE,UAAU,EAAE,EAAE;IACd,2CAA2C;IAC3C,OAAO,EAAE,EAAE;IACX,wCAAwC;IACxC,SAAS,EAAE,GAAG;CACN,CAAC"}