@fatagnus/dink-convex 1.0.0

package/dist/triggers.js

@@ -0,0 +1,705 @@
+/**
+ * Triggers setup for automatic sync on database writes.
+ *
+ * Uses convex-helpers Triggers to intercept database operations and
+ * automatically generate CRDT deltas for synced tables.
+ *
+ * @module triggers
+ */
+import * as Y from "yjs";
+import { Triggers } from "convex-helpers/server/triggers";
+/**
+ * Set of table names that are registered for sync.
+ * Used to check if a table should have triggers applied.
+ */
+const syncedTables = new Set();
+/**
+ * Global sequence counter for delta ordering.
+ * @deprecated Use getNextSeqAsync or createSequenceCounter for persisted sequences.
+ * This in-memory counter resets on redeploy and is kept for backward compatibility.
+ */
+let globalSeq = 0;
+/**
+ * Get the next sequence number for delta ordering.
+ * @deprecated Use getNextSeqAsync or createSequenceCounter for persisted sequences.
+ * This synchronous version uses an in-memory counter that resets on redeploy.
+ * @returns The next sequence number
+ */
+export function getNextSeq() {
+    return ++globalSeq;
+}
+/**
+ * Get the next sequence number by querying the database.
+ * This async version queries _sync_deltas to find the max seq and returns max + 1.
+ *
+ * @param db - Database context with query capability
+ * @param collection - The collection name to get the next sequence for
+ * @returns Promise<number> - The next sequence number
+ */
+export async function getNextSeqAsync(db, collection) {
+    const latest = await db
+        .query("sync_deltas")
+        .withIndex("by_seq", (q) => q.eq("collection", collection))
+        .order("desc")
+        .first();
+    return (latest?.seq ?? 0) + 1;
+}
+/**
+ * Create a sequence counter with request-level caching.
+ *
+ * The counter queries the database once per collection to get the max seq,
+ * then increments locally for subsequent calls within the same request context.
+ * This avoids querying the database on every call while still persisting
+ * sequences across redeploys.
+ *
+ * @returns SequenceCounter - A counter object with getNext and reset methods
+ *
+ * @example
+ * ```typescript
+ * const counter = createSequenceCounter();
+ * const seq1 = await counter.getNext(ctx.db, "tasks"); // Queries DB
+ * const seq2 = await counter.getNext(ctx.db, "tasks"); // Uses cache
+ * const seq3 = await counter.getNext(ctx.db, "users"); // Queries DB (different collection)
+ * ```
+ */
+export function createSequenceCounter() {
+    // Cache of collection -> current sequence number
+    const cache = new Map();
+    return {
+        async getNext(db, collection) {
+            if (cache.has(collection)) {
+                // Increment cached value
+                const next = cache.get(collection) + 1;
+                cache.set(collection, next);
+                return next;
+            }
+            // Query database for max seq
+            const nextSeq = await getNextSeqAsync(db, collection);
+            cache.set(collection, nextSeq);
+            return nextSeq;
+        },
+        reset() {
+            cache.clear();
+        },
+    };
+}
+/**
+ * Register a table for sync.
+ * Tables registered here will have triggers applied to generate CRDT deltas.
+ *
+ * @param tableName - The name of the table to register
+ */
+export function registerSyncedTable(tableName) {
+    syncedTables.add(tableName);
+}
+/**
+ * Check if a table is registered for sync.
+ *
+ * @param tableName - The name of the table to check
+ * @returns True if the table is registered for sync
+ */
+export function isSyncedTable(tableName) {
+    return syncedTables.has(tableName);
+}
+/**
+ * Get sync configuration for a table.
+ * In production, this would query the _sync_config table.
+ *
+ * @param tableName - The name of the table
+ * @returns Sync configuration or null if not synced
+ */
+export function getSyncConfig(tableName) {
+    if (syncedTables.has(tableName)) {
+        return { enabled: true };
+    }
+    return null;
+}
+/**
+ * Check if sync is enabled for a collection by querying _sync_config table.
+ * This is the production-ready version that queries the database.
+ *
+ * @param db - Database context with query capability
+ * @param collection - The collection name to check
+ * @returns Promise<boolean> - True if sync is enabled for this collection
+ */
+export async function checkSyncConfigEnabled(db, collection) {
+    const config = await db
+        .query("sync_config")
+        .withIndex("by_collection", (q) => q.eq("collection", collection))
+        .first();
+    return config?.enabled === true;
+}
+/**
+ * Create a sync config checker function.
+ * Returns a function that can be used to check sync status with caching.
+ *
+ * @returns A checker function that takes (db, collection) and returns Promise<boolean>
+ */
+export function createSyncConfigChecker() {
+    // Cache for sync config lookups within a request
+    const cache = new Map();
+    return async (db, collection) => {
+        // Check cache first
+        if (cache.has(collection)) {
+            return cache.get(collection);
+        }
+        // Query the database
+        const enabled = await checkSyncConfigEnabled(db, collection);
+        cache.set(collection, enabled);
+        return enabled;
+    };
+}
+/**
+ * Serialize a value to a format suitable for Yjs.
+ * Handles nested objects, arrays, and primitive types.
+ */
+function serializeValue(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(serializeValue);
+    }
+    if (typeof value === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = serializeValue(v);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Generate a CRDT delta for a newly inserted document.
+ * Creates a Yjs document with all fields set.
+ *
+ * @param doc - The inserted document
+ * @returns CRDT delta as Uint8Array
+ */
+export function generateInsertDelta(doc) {
+    const ydoc = new Y.Doc();
+    const ymap = ydoc.getMap("root");
+    // Add all fields to the Yjs document
+    for (const [key, value] of Object.entries(doc)) {
+        // Skip internal Convex fields
+        if (key === "_id" || key === "_creationTime") {
+            continue;
+        }
+        ymap.set(key, serializeValue(value));
+    }
+    // Encode the state as an update (delta)
+    return Y.encodeStateAsUpdate(ydoc);
+}
+/**
+ * Generate a CRDT delta for an updated document.
+ * Creates a delta containing only the changed fields.
+ *
+ * @param oldDoc - The document before update
+ * @param newDoc - The document after update
+ * @returns CRDT delta as Uint8Array
+ */
+export function generateUpdateDelta(oldDoc, newDoc) {
+    const ydoc = new Y.Doc();
+    const ymap = ydoc.getMap("root");
+    // Find changed fields and add them to the delta
+    for (const [key, newValue] of Object.entries(newDoc)) {
+        // Skip internal Convex fields
+        if (key === "_id" || key === "_creationTime") {
+            continue;
+        }
+        const oldValue = oldDoc[key];
+        // Check if the value has changed
+        if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+            ymap.set(key, serializeValue(newValue));
+        }
+    }
+    // Check for deleted fields
+    for (const key of Object.keys(oldDoc)) {
+        if (key === "_id" || key === "_creationTime") {
+            continue;
+        }
+        if (!(key in newDoc)) {
+            ymap.delete(key);
+        }
+    }
+    return Y.encodeStateAsUpdate(ydoc);
+}
+/**
+ * Generate a tombstone CRDT delta for a deleted document.
+ * Creates a special delta indicating the document was deleted.
+ *
+ * @param doc - The deleted document
+ * @returns CRDT delta as Uint8Array representing a tombstone
+ */
+export function generateDeleteDelta(doc) {
+    const ydoc = new Y.Doc();
+    const ymap = ydoc.getMap("root");
+    // Mark as deleted with tombstone flag
+    ymap.set("_deleted", true);
+    ymap.set("syncId", doc.syncId);
+    ymap.set("_deletedAt", Date.now());
+    return Y.encodeStateAsUpdate(ydoc);
+}
+/**
+ * Create a delta record for storage in _sync_deltas.
+ *
+ * @param input - Delta record input
+ * @returns Complete delta record with timestamp
+ */
+export function createDeltaRecord(input) {
+    return {
+        collection: input.collection,
+        docId: input.docId,
+        bytes: input.bytes,
+        seq: input.seq,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Create an outbox record for storage in _sync_outbox.
+ *
+ * @param input - Outbox record input
+ * @returns Complete outbox record with status and timestamps
+ */
+export function createOutboxRecord(input) {
+    return {
+        collection: input.collection,
+        docId: input.docId,
+        delta: input.delta,
+        seq: input.seq,
+        status: "pending",
+        retries: 0,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Create a sync trigger handler for a specific table.
+ * This handler generates CRDT deltas and stores them on database changes.
+ *
+ * @param tableName - The name of the table to handle
+ * @returns Trigger handler function
+ */
+export function createSyncTriggerHandler(tableName) {
+    return async function syncTriggerHandler(ctx, change) {
+        // Check if table is synced (in-memory check)
+        if (!isSyncedTable(tableName)) {
+            return;
+        }
+        const seq = getNextSeq();
+        let delta;
+        let docId;
+        switch (change.operation) {
+            case "insert":
+                if (!change.newDoc)
+                    return;
+                delta = generateInsertDelta(change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "update":
+                if (!change.oldDoc || !change.newDoc)
+                    return;
+                delta = generateUpdateDelta(change.oldDoc, change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "delete":
+                if (!change.oldDoc)
+                    return;
+                delta = generateDeleteDelta(change.oldDoc);
+                docId = change.oldDoc.syncId;
+                break;
+            default:
+                return;
+        }
+        // Create records for storage
+        const deltaRecord = createDeltaRecord({
+            collection: tableName,
+            docId,
+            bytes: delta,
+            seq,
+        });
+        const outboxRecord = createOutboxRecord({
+            collection: tableName,
+            docId,
+            delta,
+            seq,
+        });
+        // Store in sync_deltas and sync_outbox
+        // Convert Uint8Array to ArrayBuffer for Convex v.bytes() compatibility
+        const bytesBuffer = delta.buffer.slice(delta.byteOffset, delta.byteOffset + delta.byteLength);
+        await ctx.innerDb.insert("sync_deltas", { ...deltaRecord, bytes: bytesBuffer });
+        await ctx.innerDb.insert("sync_outbox", { ...outboxRecord, delta: bytesBuffer });
+    };
+}
+/**
+ * Create a sync trigger handler that uses persisted sequence numbers.
+ * This async version queries the database to get the max sequence number,
+ * ensuring sequences persist across redeploys.
+ *
+ * @param tableName - The name of the table to handle
+ * @returns Trigger handler function that uses async sequence generation
+ */
+export function createSyncTriggerHandlerAsync(tableName) {
+    // Create a sequence counter for this handler
+    const sequenceCounter = createSequenceCounter();
+    return async function syncTriggerHandlerAsync(ctx, change) {
+        // Check if table is synced (in-memory check)
+        if (!isSyncedTable(tableName)) {
+            return;
+        }
+        // Get persisted sequence number
+        const seq = await sequenceCounter.getNext(ctx.db, tableName);
+        let delta;
+        let docId;
+        switch (change.operation) {
+            case "insert":
+                if (!change.newDoc)
+                    return;
+                delta = generateInsertDelta(change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "update":
+                if (!change.oldDoc || !change.newDoc)
+                    return;
+                delta = generateUpdateDelta(change.oldDoc, change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "delete":
+                if (!change.oldDoc)
+                    return;
+                delta = generateDeleteDelta(change.oldDoc);
+                docId = change.oldDoc.syncId;
+                break;
+            default:
+                return;
+        }
+        // Create records for storage
+        const deltaRecord = createDeltaRecord({
+            collection: tableName,
+            docId,
+            bytes: delta,
+            seq,
+        });
+        const outboxRecord = createOutboxRecord({
+            collection: tableName,
+            docId,
+            delta,
+            seq,
+        });
+        // Store in sync_deltas and sync_outbox
+        // Convert Uint8Array to ArrayBuffer for Convex v.bytes() compatibility
+        const bytesBuffer = delta.buffer.slice(delta.byteOffset, delta.byteOffset + delta.byteLength);
+        await ctx.innerDb.insert("sync_deltas", { ...deltaRecord, bytes: bytesBuffer });
+        await ctx.innerDb.insert("sync_outbox", { ...outboxRecord, delta: bytesBuffer });
+    };
+}
+/**
+ * Map-like wrapper that provides backward compatibility for registered triggers.
+ * Wraps the object-based `registered` property from convex-helpers Triggers
+ * to provide Map-like `has()` and `get()` methods.
+ */
+class RegisteredTriggersMap {
+    _storage;
+    constructor() {
+        this._storage = new Map();
+    }
+    has(tableName) {
+        return this._storage.has(tableName);
+    }
+    get(tableName) {
+        return this._storage.get(tableName);
+    }
+    set(tableName, handlers) {
+        this._storage.set(tableName, handlers);
+    }
+    getOrCreate(tableName) {
+        if (!this._storage.has(tableName)) {
+            this._storage.set(tableName, []);
+        }
+        return this._storage.get(tableName);
+    }
+}
+/**
+ * Sync triggers wrapper that uses convex-helpers Triggers internally.
+ * Provides backward compatibility with Map-like `registered` property
+ * while leveraging the real Triggers implementation.
+ */
+class SyncTriggersWrapper {
+    /**
+     * Internal Triggers instance from convex-helpers.
+     * Uses GenericDataModel for flexibility across different Convex apps.
+     */
+    _triggers;
+    /**
+     * Map-like storage for backward compatibility with existing tests.
+     */
+    registered;
+    constructor() {
+        this._triggers = new Triggers();
+        this.registered = new RegisteredTriggersMap();
+    }
+    /**
+     * Register a trigger for a table.
+     * Registers with both the internal Triggers instance and the Map for compatibility.
+     */
+    register(tableName, handler) {
+        // Add to Map-like storage for backward compatibility
+        const handlers = this.registered.getOrCreate(tableName);
+        handlers.push(handler);
+        // Also register with the real Triggers instance
+        // Cast is needed because GenericDataModel doesn't have specific table names
+        this._triggers.register(tableName, handler);
+    }
+    /**
+     * Wrap DB to apply triggers.
+     * Uses the real Triggers.wrapDB from convex-helpers.
+     */
+    wrapDB(ctx) {
+        // Use the real wrapDB from convex-helpers Triggers
+        // Cast through unknown to handle the generic type conversion safely
+        return this._triggers.wrapDB(ctx);
+    }
+    /**
+     * Get the underlying Triggers instance for advanced usage.
+     */
+    getTriggersInstance() {
+        return this._triggers;
+    }
+}
+/**
+ * Sync triggers instance.
+ * Uses convex-helpers Triggers internally for real database wrapping
+ * while maintaining backward compatibility with Map-like `registered` property.
+ */
+export const syncTriggers = new SyncTriggersWrapper();
+/**
+ * Create a new Triggers instance for sync operations.
+ * This factory function creates a real convex-helpers Triggers instance
+ * that can be used to wrap database operations with trigger support.
+ *
+ * @returns A new Triggers instance with register and wrapDB methods
+ *
+ * @example
+ * ```typescript
+ * import { createSyncTriggers } from "@fatagnus/dink-convex";
+ * import { customMutation } from "convex-helpers/server/customFunctions";
+ * import { mutation as rawMutation } from "./_generated/server";
+ *
+ * const triggers = createSyncTriggers();
+ * triggers.register("tasks", async (ctx, change) => {
+ *   console.log("Task changed:", change);
+ * });
+ *
+ * export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
+ * ```
+ */
+export function createSyncTriggers() {
+    return new Triggers();
+}
+/**
+ * Create a Triggers instance with sync handlers pre-registered for specified tables.
+ * This is a convenience function that creates a Triggers instance and automatically
+ * registers sync trigger handlers that generate CRDT deltas for the specified tables.
+ *
+ * @param tableNames - Array of table names to register sync handlers for
+ * @returns A Triggers instance with sync handlers registered
+ *
+ * @example
+ * ```typescript
+ * import { createSyncTriggersWithHandlers } from "@fatagnus/dink-convex";
+ * import { customMutation } from "convex-helpers/server/customFunctions";
+ * import { mutation as rawMutation } from "./_generated/server";
+ *
+ * // Creates triggers with sync handlers for tasks and users tables
+ * const triggers = createSyncTriggersWithHandlers(["tasks", "users"]);
+ *
+ * export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
+ * ```
+ */
+export function createSyncTriggersWithHandlers(tableNames) {
+    const triggers = new Triggers();
+    // Register sync handlers for each table
+    for (const tableName of tableNames) {
+        // Register the table for sync tracking
+        registerSyncedTable(tableName);
+        // Create and register the sync trigger handler
+        const handler = createSyncTriggerHandler(tableName);
+        triggers.register(tableName, handler);
+    }
+    return triggers;
+}
+/**
+ * Create a sync trigger handler that checks _sync_config before processing.
+ * This is the production version that queries the database for config.
+ *
+ * @param tableName - The name of the table to handle
+ * @returns Trigger handler function that checks _sync_config
+ */
+export function createConfigAwareSyncTriggerHandler(tableName) {
+    return async function configAwareSyncTriggerHandler(ctx, change) {
+        // Check _sync_config table for this collection
+        const isEnabled = await checkSyncConfigEnabled(ctx.db, tableName);
+        if (!isEnabled) {
+            return;
+        }
+        const seq = getNextSeq();
+        let delta;
+        let docId;
+        switch (change.operation) {
+            case "insert":
+                if (!change.newDoc)
+                    return;
+                delta = generateInsertDelta(change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "update":
+                if (!change.oldDoc || !change.newDoc)
+                    return;
+                delta = generateUpdateDelta(change.oldDoc, change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "delete":
+                if (!change.oldDoc)
+                    return;
+                delta = generateDeleteDelta(change.oldDoc);
+                docId = change.oldDoc.syncId;
+                break;
+            default:
+                return;
+        }
+        // Create records for storage
+        const deltaRecord = createDeltaRecord({
+            collection: tableName,
+            docId,
+            bytes: delta,
+            seq,
+        });
+        const outboxRecord = createOutboxRecord({
+            collection: tableName,
+            docId,
+            delta,
+            seq,
+        });
+        // Store in sync_deltas and sync_outbox
+        // Convert Uint8Array to ArrayBuffer for Convex v.bytes() compatibility
+        const bytesBuffer = delta.buffer.slice(delta.byteOffset, delta.byteOffset + delta.byteLength);
+        await ctx.innerDb.insert("sync_deltas", { ...deltaRecord, bytes: bytesBuffer });
+        await ctx.innerDb.insert("sync_outbox", { ...outboxRecord, delta: bytesBuffer });
+    };
+}
+/**
+ * Schedule immediate outbox processing.
+ *
+ * This helper function calls scheduler.runAfter(0, ...) to trigger
+ * immediate processing of the outbox. It's designed to be called
+ * after inserting to _sync_outbox to provide near real-time sync.
+ *
+ * If scheduler is null/undefined, this is a no-op (graceful degradation
+ * for contexts where scheduling isn't available).
+ *
+ * @param scheduler - The Convex scheduler object or null/undefined
+ * @returns Promise that resolves when scheduling is complete
+ */
+export async function scheduleImmediateProcessing(scheduler) {
+    if (!scheduler) {
+        return;
+    }
+    // Use a placeholder for the function reference
+    // In actual Convex usage, this would be internal.outboxProcessor.processOutboxBatch
+    // The actual function reference needs to be passed by the caller in production
+    scheduler.runAfter(0, "internal.outboxProcessor.processOutboxBatch", {});
+}
+/**
+ * Create a sync trigger handler with immediate scheduling support.
+ *
+ * This handler generates CRDT deltas, stores them, and schedules
+ * immediate outbox processing for near real-time sync.
+ *
+ * @param tableName - The name of the table to handle
+ * @returns Trigger handler function with scheduling support
+ */
+export function createSyncTriggerHandlerWithScheduling(tableName) {
+    return async function syncTriggerHandlerWithScheduling(ctx, change) {
+        // Check if table is synced (in-memory check)
+        if (!isSyncedTable(tableName)) {
+            return;
+        }
+        const seq = getNextSeq();
+        let delta;
+        let docId;
+        switch (change.operation) {
+            case "insert":
+                if (!change.newDoc)
+                    return;
+                delta = generateInsertDelta(change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "update":
+                if (!change.oldDoc || !change.newDoc)
+                    return;
+                delta = generateUpdateDelta(change.oldDoc, change.newDoc);
+                docId = change.newDoc.syncId;
+                break;
+            case "delete":
+                if (!change.oldDoc)
+                    return;
+                delta = generateDeleteDelta(change.oldDoc);
+                docId = change.oldDoc.syncId;
+                break;
+            default:
+                return;
+        }
+        // Create records for storage
+        const deltaRecord = createDeltaRecord({
+            collection: tableName,
+            docId,
+            bytes: delta,
+            seq,
+        });
+        const outboxRecord = createOutboxRecord({
+            collection: tableName,
+            docId,
+            delta,
+            seq,
+        });
+        // Store in sync_deltas and sync_outbox
+        // Convert Uint8Array to ArrayBuffer for Convex v.bytes() compatibility
+        const bytesBuffer = delta.buffer.slice(delta.byteOffset, delta.byteOffset + delta.byteLength);
+        await ctx.innerDb.insert("sync_deltas", { ...deltaRecord, bytes: bytesBuffer });
+        await ctx.innerDb.insert("sync_outbox", { ...outboxRecord, delta: bytesBuffer });
+        // Schedule immediate outbox processing if scheduler is available
+        await scheduleImmediateProcessing(ctx.scheduler);
+    };
+}
+/**
+ * Custom mutation wrapper that includes trigger logic.
+ *
+ * This is a factory function that creates mutations with sync triggers enabled.
+ * In production, this would use customMutation from convex-helpers combined with
+ * the syncTriggers.wrapDB function.
+ *
+ * @example
+ * ```typescript
+ * import { customMutation } from "@fatagnus/dink-convex";
+ *
+ * export const createTask = customMutation({
+ *   args: { text: v.string() },
+ *   handler: async (ctx, args) => {
+ *     return await ctx.db.insert("tasks", {
+ *       text: args.text,
+ *       syncId: generateSyncId(),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export function customMutation(config) {
+    return {
+        args: config.args,
+        handler: async (ctx, args) => {
+            // Wrap the context with triggers
+            const wrappedCtx = syncTriggers.wrapDB(ctx);
+            return config.handler(wrappedCtx, args);
+        },
+    };
+}
+//# sourceMappingURL=triggers.js.map