@syncular/server 0.0.6-95 → 0.1.0

package/dist/relay/client-role/pull-engine.js

@@ -0,0 +1,249 @@
+/**
+ * @syncular/server/relay - Pull Engine
+ *
+ * Pulls changes from the main server and stores them locally
+ * on the relay for local clients to access.
+ */
+import { pushCommit } from '@syncular/server';
+import { sql } from 'kysely';
+/**
+ * Pull engine for receiving changes from the main server.
+ */
+export class PullEngine {
+    db;
+    dialect;
+    transport;
+    clientId;
+    tables;
+    scopes;
+    handlers;
+    sequenceMapper;
+    realtime;
+    intervalMs;
+    onError;
+    onPullComplete;
+    running = false;
+    timer = null;
+    cursors = new Map();
+    constructor(options) {
+        this.db = options.db;
+        this.dialect = options.dialect;
+        this.transport = options.transport;
+        this.clientId = options.clientId;
+        this.tables = options.tables;
+        this.scopes = options.scopes;
+        this.handlers = options.handlers;
+        this.sequenceMapper = options.sequenceMapper;
+        this.realtime = options.realtime;
+        this.intervalMs = options.intervalMs ?? 10000;
+        this.onError = options.onError;
+        this.onPullComplete = options.onPullComplete;
+    }
+    /**
+     * Start the pull engine loop.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        void this.loadCursors()
+            .catch((error) => {
+            this.onError?.(error instanceof Error ? error : new Error(String(error)));
+        })
+            .finally(() => {
+            if (this.running) {
+                this.scheduleNext(0);
+            }
+        });
+    }
+    /**
+     * Stop the pull engine.
+     */
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Pull once (for manual/testing use).
+     */
+    async pullOnce() {
+        return this.processOne();
+    }
+    async loadCursors() {
+        try {
+            // Load cursors from config
+            const rowResult = await sql `
+        select value_json
+        from ${sql.table('relay_config')}
+        where key = 'main_cursors'
+        limit 1
+      `.execute(this.db);
+            const row = rowResult.rows[0];
+            if (row?.value_json) {
+                const parsed = JSON.parse(row.value_json);
+                if (typeof parsed === 'object' && parsed !== null) {
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (typeof value === 'number') {
+                            this.cursors.set(key, value);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore - start from scratch
+        }
+    }
+    async saveCursors() {
+        const cursorObj = {};
+        for (const [key, value] of this.cursors) {
+            cursorObj[key] = value;
+        }
+        const valueJson = JSON.stringify(cursorObj);
+        await sql `
+      insert into ${sql.table('relay_config')} (key, value_json)
+      values ('main_cursors', ${valueJson})
+      on conflict (key)
+      do update set value_json = ${valueJson}
+    `.execute(this.db);
+    }
+    scheduleNext(delayMs) {
+        if (!this.running)
+            return;
+        if (this.timer)
+            return;
+        this.timer = setTimeout(async () => {
+            this.timer = null;
+            try {
+                const pulled = await this.processOne();
+                // If we pulled something, immediately try again
+                const nextDelay = pulled ? 0 : this.intervalMs;
+                this.scheduleNext(nextDelay);
+            }
+            catch (err) {
+                this.onError?.(err instanceof Error ? err : new Error(String(err)));
+                this.scheduleNext(this.intervalMs);
+            }
+        }, delayMs);
+    }
+    async processOne() {
+        // Build subscriptions for each table
+        const subscriptionRequests = this.tables.map((table) => ({
+            id: table,
+            table,
+            scopes: this.scopes,
+            cursor: this.cursors.get(table) ?? -1,
+            crdtStateVectors: [],
+        }));
+        let response;
+        try {
+            const combined = await this.transport.sync({
+                clientId: this.clientId,
+                pull: {
+                    schemaVersion: 1,
+                    subscriptions: subscriptionRequests,
+                    limitCommits: 100,
+                },
+            });
+            if (!combined.pull) {
+                return false;
+            }
+            response = combined.pull;
+        }
+        catch {
+            // Network error - will retry
+            return false;
+        }
+        if (!response.ok) {
+            return false;
+        }
+        let hasChanges = false;
+        const affectedTables = new Set();
+        for (const sub of response.subscriptions) {
+            if (sub.status !== 'active')
+                continue;
+            const table = sub.id;
+            // Process commits
+            let canAdvanceCursor = true;
+            for (const commit of sub.commits) {
+                const outcome = await this.applyCommitLocally(commit, table);
+                if (outcome === 'applied') {
+                    hasChanges = true;
+                    affectedTables.add(table);
+                }
+                if (outcome === 'rejected') {
+                    canAdvanceCursor = false;
+                    break;
+                }
+            }
+            // Update cursor
+            if (canAdvanceCursor &&
+                sub.nextCursor > (this.cursors.get(table) ?? -1)) {
+                this.cursors.set(table, sub.nextCursor);
+            }
+        }
+        // Save updated cursors
+        await this.saveCursors();
+        // Notify local clients if we have changes
+        if (hasChanges && affectedTables.size > 0) {
+            const maxCursor = await this.dialect.readMaxCommitSeq(this.db);
+            this.realtime.notifyScopeKeys(Array.from(affectedTables), maxCursor);
+        }
+        // Trigger rate-limited prune after successful pull
+        await this.onPullComplete?.();
+        return hasChanges;
+    }
+    /**
+     * Apply a commit from main server locally.
+     *
+     * This re-applies the commit through the local table handlers
+     * to ensure proper indexing and scope assignment.
+     */
+    async applyCommitLocally(commit, table) {
+        if (commit.changes.length === 0)
+            return 'cached';
+        // Convert changes to operations
+        const operations = commit.changes.map((change) => ({
+            table: change.table,
+            row_id: change.row_id,
+            op: change.op,
+            payload: change.row_json,
+        }));
+        // Generate a unique commit ID for this relay instance
+        const relayCommitId = `main:${commit.commitSeq}:${table}`;
+        // Push through local handler
+        const result = await pushCommit({
+            db: this.db,
+            dialect: this.dialect,
+            handlers: this.handlers,
+            auth: { actorId: commit.actorId },
+            request: {
+                clientId: `relay:${this.clientId}`,
+                clientCommitId: relayCommitId,
+                operations,
+                schemaVersion: 1,
+            },
+        });
+        if (result.response.ok === true &&
+            result.response.status === 'applied' &&
+            typeof result.response.commitSeq === 'number') {
+            // Record sequence mapping
+            await this.sequenceMapper.createConfirmedMapping(result.response.commitSeq, commit.commitSeq);
+            return 'applied';
+        }
+        // Already applied (cached) - that's fine
+        if (result.response.status === 'cached') {
+            return 'cached';
+        }
+        // Rejected - this shouldn't happen for pulls from main
+        // Do not advance cursor; signal error so caller can react.
+        const error = new Error(`Relay: Failed to apply commit ${commit.commitSeq} locally (status=${result.response.status})`);
+        console.warn(`Relay: Failed to apply commit ${commit.commitSeq} locally:`, result.response);
+        this.onError?.(error);
+        return 'rejected';
+    }
+}
+//# sourceMappingURL=pull-engine.js.map

package/dist/relay/client-role/pull-engine.js.map

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

package/dist/relay/client-role/sequence-mapper.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @syncular/server/relay - Sequence Mapper
+ *
+ * Tracks the mapping between relay's local commit_seq
+ * and the main server's global commit_seq.
+ */
+import { type Kysely } from 'kysely';
+import type { RelayDatabase, RelaySequenceMapStatus } from '../schema';
+/**
+ * Sequence mapping entry.
+ */
+export interface SequenceMapping {
+    localCommitSeq: number;
+    mainCommitSeq: number | null;
+    status: RelaySequenceMapStatus;
+}
+/**
+ * Sequence mapper for tracking local to main commit sequence mappings.
+ */
+export declare class SequenceMapper<DB extends RelayDatabase = RelayDatabase> {
+    private readonly db;
+    constructor(options: {
+        db: Kysely<DB>;
+    });
+    /**
+     * Create a pending mapping for a local commit that will be forwarded.
+     */
+    createPendingMapping(localCommitSeq: number): Promise<void>;
+    /**
+     * Mark a mapping as forwarded with the main server's commit_seq.
+     */
+    markForwarded(localCommitSeq: number, mainCommitSeq: number): Promise<void>;
+    /**
+     * Mark a mapping as confirmed (main server acknowledged).
+     */
+    markConfirmed(localCommitSeq: number): Promise<void>;
+    /**
+     * Get the mapping for a local commit sequence.
+     */
+    getMapping(localCommitSeq: number): Promise<SequenceMapping | null>;
+    /**
+     * Get the local commit sequence for a main server commit sequence.
+     */
+    getLocalCommitSeq(mainCommitSeq: number): Promise<number | null>;
+    /**
+     * Get all pending mappings (commits not yet forwarded).
+     */
+    getPendingMappings(): Promise<SequenceMapping[]>;
+    /**
+     * Create a mapping for commits pulled from main (assigned new local commit_seq).
+     *
+     * These mappings go directly to 'confirmed' status since they came from main.
+     */
+    createConfirmedMapping(localCommitSeq: number, mainCommitSeq: number): Promise<void>;
+    /**
+     * Delete confirmed/forwarded sequence mappings older than the given age.
+     * Keeps pending mappings (they haven't been forwarded yet).
+     */
+    pruneOldMappings(maxAgeMs: number): Promise<number>;
+    /**
+     * Get the highest main_commit_seq we've seen (for tracking pull cursor).
+     */
+    getHighestMainCommitSeq(): Promise<number>;
+}
+//# sourceMappingURL=sequence-mapper.d.ts.map

package/dist/relay/client-role/sequence-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence-mapper.d.ts","sourceRoot":"","sources":["../../../src/relay/client-role/sequence-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,cAAc,CAAC,EAAE,SAAS,aAAa,GAAG,aAAa;IAClE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAEhC,YAAY,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,EAEtC;IAED;;OAEG;IACG,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAahE;IAED;;OAEG;IACG,aAAa,CACjB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAUf;IAED;;OAEG;IACG,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzD;IAED;;OAEG;IACG,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAoBxE;IAED;;OAEG;IACG,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASrE;IAED;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAkBrD;IAED;;;;OAIG;IACG,sBAAsB,CAC1B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAuBf;IAED;;;OAGG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASxD;IAED;;OAEG;IACG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS/C;CACF"}

package/dist/relay/client-role/sequence-mapper.js

@@ -0,0 +1,161 @@
+/**
+ * @syncular/server/relay - Sequence Mapper
+ *
+ * Tracks the mapping between relay's local commit_seq
+ * and the main server's global commit_seq.
+ */
+import { sql } from 'kysely';
+/**
+ * Sequence mapper for tracking local to main commit sequence mappings.
+ */
+export class SequenceMapper {
+    db;
+    constructor(options) {
+        this.db = options.db;
+    }
+    /**
+     * Create a pending mapping for a local commit that will be forwarded.
+     */
+    async createPendingMapping(localCommitSeq) {
+        const now = Date.now();
+        await sql `
+      insert into ${sql.table('relay_sequence_map')} (
+        local_commit_seq,
+        main_commit_seq,
+        status,
+        created_at,
+        updated_at
+      )
+      values (${localCommitSeq}, ${null}, 'pending', ${now}, ${now})
+      on conflict (local_commit_seq) do nothing
+    `.execute(this.db);
+    }
+    /**
+     * Mark a mapping as forwarded with the main server's commit_seq.
+     */
+    async markForwarded(localCommitSeq, mainCommitSeq) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_sequence_map')}
+      set
+        main_commit_seq = ${mainCommitSeq},
+        status = 'forwarded',
+        updated_at = ${now}
+      where local_commit_seq = ${localCommitSeq}
+    `.execute(this.db);
+    }
+    /**
+     * Mark a mapping as confirmed (main server acknowledged).
+     */
+    async markConfirmed(localCommitSeq) {
+        const now = Date.now();
+        await sql `
+      update ${sql.table('relay_sequence_map')}
+      set status = 'confirmed', updated_at = ${now}
+      where local_commit_seq = ${localCommitSeq}
+    `.execute(this.db);
+    }
+    /**
+     * Get the mapping for a local commit sequence.
+     */
+    async getMapping(localCommitSeq) {
+        const rowResult = await sql `
+      select local_commit_seq, main_commit_seq, status
+      from ${sql.table('relay_sequence_map')}
+      where local_commit_seq = ${localCommitSeq}
+      limit 1
+    `.execute(this.db);
+        const row = rowResult.rows[0];
+        if (!row)
+            return null;
+        return {
+            localCommitSeq: row.local_commit_seq,
+            mainCommitSeq: row.main_commit_seq,
+            status: row.status,
+        };
+    }
+    /**
+     * Get the local commit sequence for a main server commit sequence.
+     */
+    async getLocalCommitSeq(mainCommitSeq) {
+        const rowResult = await sql `
+      select local_commit_seq
+      from ${sql.table('relay_sequence_map')}
+      where main_commit_seq = ${mainCommitSeq}
+      limit 1
+    `.execute(this.db);
+        return rowResult.rows[0]?.local_commit_seq ?? null;
+    }
+    /**
+     * Get all pending mappings (commits not yet forwarded).
+     */
+    async getPendingMappings() {
+        const rowsResult = await sql `
+      select local_commit_seq, main_commit_seq, status
+      from ${sql.table('relay_sequence_map')}
+      where status = 'pending'
+      order by local_commit_seq asc
+    `.execute(this.db);
+        const rows = rowsResult.rows;
+        return rows.map((row) => ({
+            localCommitSeq: row.local_commit_seq,
+            mainCommitSeq: row.main_commit_seq,
+            status: row.status,
+        }));
+    }
+    /**
+     * Create a mapping for commits pulled from main (assigned new local commit_seq).
+     *
+     * These mappings go directly to 'confirmed' status since they came from main.
+     */
+    async createConfirmedMapping(localCommitSeq, mainCommitSeq) {
+        const now = Date.now();
+        await sql `
+      insert into ${sql.table('relay_sequence_map')} (
+        local_commit_seq,
+        main_commit_seq,
+        status,
+        created_at,
+        updated_at
+      )
+      values (
+        ${localCommitSeq},
+        ${mainCommitSeq},
+        'confirmed',
+        ${now},
+        ${now}
+      )
+      on conflict (local_commit_seq)
+      do update set
+        main_commit_seq = ${mainCommitSeq},
+        status = 'confirmed',
+        updated_at = ${now}
+    `.execute(this.db);
+    }
+    /**
+     * Delete confirmed/forwarded sequence mappings older than the given age.
+     * Keeps pending mappings (they haven't been forwarded yet).
+     */
+    async pruneOldMappings(maxAgeMs) {
+        const threshold = Date.now() - maxAgeMs;
+        const result = await sql `
+      delete from ${sql.table('relay_sequence_map')}
+      where status in ('confirmed', 'forwarded')
+      and updated_at < ${threshold}
+    `.execute(this.db);
+        return Number(result.numAffectedRows ?? 0);
+    }
+    /**
+     * Get the highest main_commit_seq we've seen (for tracking pull cursor).
+     */
+    async getHighestMainCommitSeq() {
+        const rowResult = await sql `
+      select max(main_commit_seq) as max_seq
+      from ${sql.table('relay_sequence_map')}
+      where main_commit_seq is not null
+      limit 1
+    `.execute(this.db);
+        return rowResult.rows[0]?.max_seq ?? 0;
+    }
+}
+//# sourceMappingURL=sequence-mapper.js.map

package/dist/relay/client-role/sequence-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence-mapper.js","sourceRoot":"","sources":["../../../src/relay/client-role/sequence-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAe,GAAG,EAAE,MAAM,QAAQ,CAAC;AAY1C;;GAEG;AACH,MAAM,OAAO,cAAc;IACR,EAAE,CAAa;IAEhC,YAAY,OAA2B;QACrC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,oBAAoB,CAAC,cAAsB;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,CAAA;oBACO,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;;;;;;gBAOnC,cAAc,KAAK,IAAI,gBAAgB,GAAG,KAAK,GAAG;;KAE7D,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa,CACjB,cAAsB,EACtB,aAAqB;QAErB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,CAAA;eACE,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;4BAElB,aAAa;;uBAElB,GAAG;iCACO,cAAc;KAC1C,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa,CAAC,cAAsB;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,CAAA;eACE,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;+CACC,GAAG;iCACjB,cAAc;KAC1C,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,cAAsB;QACrC,MAAM,SAAS,GAAG,MAAM,GAAG,CAIzB;;aAEO,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;iCACX,cAAc;;KAE1C,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE9B,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,OAAO;YACL,cAAc,EAAE,GAAG,CAAC,gBAAgB;YACpC,aAAa,EAAE,GAAG,CAAC,eAAe;YAClC,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CAAC,aAAqB;QAC3C,MAAM,SAAS,GAAG,MAAM,GAAG,CAA8B;;aAEhD,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;gCACZ,aAAa;;KAExC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEnB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,gBAAgB,IAAI,IAAI,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,UAAU,GAAG,MAAM,GAAG,CAI1B;;aAEO,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;;KAGvC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACxB,cAAc,EAAE,GAAG,CAAC,gBAAgB;YACpC,aAAa,EAAE,GAAG,CAAC,eAAe;YAClC,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,sBAAsB,CAC1B,cAAsB,EACtB,aAAqB;QAErB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,CAAA;oBACO,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;;;;;;;UAQzC,cAAc;UACd,aAAa;;UAEb,GAAG;UACH,GAAG;;;;4BAIe,aAAa;;uBAElB,GAAG;KACrB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAgB;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAA;oBACR,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;yBAE1B,SAAS;KAC7B,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEnB,OAAO,MAAM,CAAC,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,uBAAuB;QAC3B,MAAM,SAAS,GAAG,MAAM,GAAG,CAA4B;;aAE9C,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;;;KAGvC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEnB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/relay/evaluation/relay-paths.d.ts

@@ -0,0 +1,41 @@
+interface RelayAppPathEvaluationOptions {
+    iterations?: number;
+    warmupIterations?: number;
+    realtimeConnections?: number;
+}
+interface RelayAppPathMetric {
+    name: string;
+    iterations: number;
+    totalUs: number;
+    minUs: number;
+    avgUs: number;
+    p50Us: number;
+    p95Us: number;
+    maxUs: number;
+}
+interface RelayAppPathEvaluationResult {
+    fixture: {
+        name: string;
+        database: 'bun:sqlite:memory';
+        dialect: '@syncular/server/sqlite';
+        table: 'tasks';
+    };
+    config: {
+        iterations: number;
+        warmupIterations: number;
+        realtimeConnections: number;
+    };
+    counters: {
+        localPushCommits: number;
+        forwardedCommits: number;
+        mainPullAppliedCommits: number;
+        localPullResponses: number;
+        realtimeMessages: number;
+    };
+    metrics: RelayAppPathMetric[];
+    notes: string[];
+}
+export declare function evaluateRelayAppPaths(options?: RelayAppPathEvaluationOptions): Promise<RelayAppPathEvaluationResult>;
+export declare function assertRelayAppPathEvaluation(result: RelayAppPathEvaluationResult): void;
+export {};
+//# sourceMappingURL=relay-paths.d.ts.map

package/dist/relay/evaluation/relay-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-paths.d.ts","sourceRoot":"","sources":["../../../src/relay/evaluation/relay-paths.ts"],"names":[],"mappings":"AA6BA,UAAU,6BAA6B;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,4BAA4B;IACpC,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,OAAO,EAAE,yBAAyB,CAAC;QACnC,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,EAAE;QACR,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAWD,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CA4DvC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,4BAA4B,GACnC,IAAI,CA4BN"}