@convex-dev/table-history 0.1.3

package/dist/esm/component/lib.js

@@ -0,0 +1,316 @@
+import { v } from "convex/values";
+import { internalMutation, mutation, query } from "./_generated/server";
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "./schema.js";
+import { paginationOptsValidator } from "convex/server";
+import { internal } from "./_generated/api";
+export const serializabilityValidator = v.union(
+/// "table" serializability means all writes to the table are serialized,
+/// so the timestamps are in causal order. This gives the strictest guarantees
+/// but can cause OCC conflicts if the table updates frequently.
+/// Writes to different tables are not serialized.
+v.literal("table"), 
+/// "document" serializability means all writes to the same document are serialized,
+/// but writes to different documents may have out-of-order timestamps.
+v.literal("document"), 
+/// "wallclock" serializability means the timestamp is set to the current time
+/// according to the server's clock. This provides no guarantees, but it's
+/// usually in causal order and causes no OCC conflicts.
+/// Wallclock serializability is the default.
+v.literal("wallclock"));
+export const historyEntryValidator = v.object({
+    id: v.string(),
+    doc: v.any(),
+    ts: v.number(),
+    isDeleted: v.boolean(),
+    attribution: v.any(),
+});
+async function newTimestamp(ctx, serializability, id) {
+    switch (serializability) {
+        case "table": {
+            const latest = await ctx.db.query("history").withIndex("ts").order("desc").first();
+            if (latest) {
+                return Math.max(latest.ts + 1, Date.now());
+            }
+            else {
+                return Date.now();
+            }
+        }
+        case "document": {
+            const latest = await ctx.db.query("history").withIndex("id", (q) => q.eq("id", id)).order("desc").first();
+            if (latest) {
+                return Math.max(latest.ts + 1, Date.now());
+            }
+            else {
+                return Date.now();
+            }
+        }
+        case "wallclock": {
+            return Date.now();
+        }
+    }
+}
+export const update = mutation({
+    args: {
+        id: v.string(),
+        doc: v.union(v.any(), v.null()),
+        serializability: serializabilityValidator,
+        attribution: v.any(),
+    },
+    returns: v.number(),
+    handler: async (ctx, args) => {
+        let ts = await newTimestamp(ctx, args.serializability, args.id);
+        const existing = await ctx.db.query("history").withIndex("id", (q) => q.eq("id", args.id).eq("ts", ts)).first();
+        if (existing) {
+            ts = existing.ts + 1;
+        }
+        await ctx.db.insert("history", {
+            id: args.id,
+            doc: args.doc,
+            ts,
+            isDeleted: args.doc === null,
+            attribution: args.attribution,
+        });
+        return ts;
+    },
+});
+function paginationResultValidator(itemValidator) {
+    return v.object({
+        continueCursor: v.string(),
+        isDone: v.boolean(),
+        page: v.array(itemValidator),
+        pageStatus: v.optional(v.union(v.null(), v.literal("SplitRequired"), v.literal("SplitRecommended"))),
+        splitCursor: v.optional(v.union(v.null(), v.string())),
+    });
+}
+export const listHistory = query({
+    args: {
+        maxTs: v.number(),
+        paginationOpts: paginationOptsValidator,
+    },
+    returns: paginationResultValidator(historyEntryValidator),
+    handler: async (ctx, args) => {
+        const results = await paginator(ctx.db, schema)
+            .query("history")
+            .withIndex("ts", (q) => q.lte("ts", args.maxTs))
+            .order("desc")
+            .paginate(args.paginationOpts);
+        return {
+            ...results,
+            page: results.page.map(extractHistoryEntry),
+        };
+    },
+});
+function extractHistoryEntry(h) {
+    return {
+        id: h.id,
+        doc: h.doc,
+        ts: h.ts,
+        isDeleted: h.isDeleted,
+        attribution: h.attribution,
+    };
+}
+export const listDocumentHistory = query({
+    args: {
+        id: v.string(),
+        maxTs: v.number(),
+        paginationOpts: paginationOptsValidator,
+    },
+    returns: paginationResultValidator(historyEntryValidator),
+    handler: async (ctx, args) => {
+        const results = await paginator(ctx.db, schema)
+            .query("history")
+            .withIndex("id", (q) => q.eq("id", args.id).lte("ts", args.maxTs))
+            .order("desc")
+            .paginate(args.paginationOpts);
+        return {
+            ...results,
+            page: results.page.map(extractHistoryEntry),
+        };
+    },
+});
+// Sentinel value for end of cursor.
+const END_CURSOR = "END_CURSOR";
+export const listSnapshot = query({
+    args: {
+        snapshotTs: v.number(),
+        currentTs: v.number(),
+        paginationOpts: paginationOptsValidator,
+    },
+    returns: paginationResultValidator(historyEntryValidator),
+    handler: async (ctx, args) => {
+        const pageSize = args.paginationOpts.numItems;
+        const page = [];
+        if (args.paginationOpts.cursor === END_CURSOR) {
+            return {
+                continueCursor: END_CURSOR,
+                isDone: true,
+                page: [],
+            };
+        }
+        if (pageSize <= 0) {
+            throw new Error("pageSize must be positive");
+        }
+        if (args.currentTs < args.snapshotTs) {
+            throw new Error("currentTs must be >= snapshotTs");
+        }
+        const vacuumed = await ctx.db.query("vacuumed").first();
+        if (vacuumed && vacuumed.minTsToKeep > args.snapshotTs) {
+            throw new Error("invalid snapshotTs, snapshot has been vacuumed");
+        }
+        const targetEndCursor = args.paginationOpts.endCursor ?? null;
+        let prevId = args.paginationOpts.cursor;
+        const allIdsSeen = [];
+        const allIdsBeforeCurrentTs = [];
+        while (allIdsBeforeCurrentTs.length < pageSize || targetEndCursor !== null) {
+            const itemWithNextId = await ctx.db.query("history").withIndex("id", (q) => prevId !== null ? q.lt("id", prevId) : q).order("desc").first();
+            if (itemWithNextId === null) {
+                return {
+                    continueCursor: END_CURSOR,
+                    isDone: true,
+                    page,
+                    ...maybeSplit(allIdsSeen, pageSize),
+                };
+            }
+            allIdsSeen.push(itemWithNextId.id);
+            prevId = itemWithNextId.id;
+            if (targetEndCursor !== null && targetEndCursor !== END_CURSOR && itemWithNextId.id < targetEndCursor) {
+                // We've reached the end of the page.
+                return {
+                    continueCursor: targetEndCursor,
+                    isDone: targetEndCursor === END_CURSOR,
+                    page,
+                    ...maybeSplit(allIdsSeen, pageSize),
+                };
+            }
+            let revision = itemWithNextId;
+            if (itemWithNextId.ts > args.snapshotTs) {
+                // Find the revision as it existed at args.ts
+                const itemAtSnapshotTs = await ctx.db.query("history").withIndex("id", (q) => q.eq("id", itemWithNextId.id).lte("ts", args.snapshotTs)).order("desc").first();
+                if (itemAtSnapshotTs === null) {
+                    // The item doesn't exist in the snapshotTs snapshot.
+                    // Check if it exists as of currentTs
+                    const itemAtCurrentTs = await ctx.db.query("history").withIndex("id", (q) => q.eq("id", itemWithNextId.id).lte("ts", args.currentTs)).order("desc").first();
+                    if (itemAtCurrentTs === null) {
+                        // It was created after currentTs, so we should treat it like it doesn't exist.
+                        // prevId has advanced, but it never gets returned.
+                        continue;
+                    }
+                    else {
+                        // It was created between snapshotTs and currentTs, so it counts toward the limit and can be in the cursor, but it's not in the page.
+                        revision = null;
+                    }
+                }
+                else {
+                    revision = itemAtSnapshotTs;
+                }
+            }
+            if (revision && revision.isDeleted) {
+                // If it's deleted, we don't want to include it in the page, but it counts toward the limit and can be in the cursor.
+                revision = null;
+            }
+            allIdsBeforeCurrentTs.push(itemWithNextId.id);
+            if (revision) {
+                page.push(extractHistoryEntry(revision));
+            }
+        }
+        const output = {
+            continueCursor: allIdsBeforeCurrentTs[allIdsBeforeCurrentTs.length - 1],
+            isDone: false,
+            page,
+            ...maybeSplit(allIdsSeen, pageSize),
+        };
+        return output;
+    },
+});
+function maybeSplit(allIdsSeen, pageSize) {
+    if (allIdsSeen.length >= pageSize * 2) {
+        return {
+            splitCursor: allIdsSeen[pageSize - 1],
+            pageStatus: "SplitRecommended",
+        };
+    }
+    return {};
+}
+/**
+ * Deletes history of state that was gone (overwritten or deleted) before
+ * minTsToKeep.
+ *
+ * After `vacuumHistory` is called, `listSnapshot` with `ts` before `minTsToKeep` will not
+ * necessarily be correct.
+ *
+ * This mutation does not delete history atomically. It may take a while with
+ * async operations.
+ *
+ * NOTE: `usePaginatedQuery` on `listSnapshot` may yield pages that have gaps or
+ * overlap if a reactive query is subscribed when `vacuumHistory` runs.
+ */
+export const vacuumHistory = mutation({
+    args: {
+        minTsToKeep: v.number(),
+    },
+    handler: async (ctx, args) => {
+        // Ensure that no one relies on vacuuming running immediately by waiting
+        // 100ms.
+        // This also avoids race conditions where `args.minTsToKeep` is so recent
+        // that new entries with earlier timestamps are still being added to the
+        // history table.
+        await ctx.scheduler.runAfter(100, internal.lib.vacuumHistoryRecursive, {
+            minTsToKeep: args.minTsToKeep,
+            paginationOpts: {
+                numItems: 100,
+                cursor: null,
+            },
+        });
+    },
+});
+export const vacuumHistoryRecursive = internalMutation({
+    args: {
+        minTsToKeep: v.number(),
+        paginationOpts: paginationOptsValidator,
+    },
+    handler: async (ctx, args) => {
+        const vacuumed = await ctx.db.query("vacuumed").first();
+        const startTs = vacuumed?.minTsToKeep ?? 0;
+        if (startTs >= args.minTsToKeep) {
+            return;
+        }
+        const toDelete = await paginator(ctx.db, schema)
+            .query("history")
+            .withIndex("ts", (q) => q.gt("ts", startTs).lte("ts", args.minTsToKeep))
+            .order("asc")
+            .paginate(args.paginationOpts);
+        let maxTs = startTs;
+        for (const h of toDelete.page) {
+            const prevRev = await ctx.db.query("history").withIndex("id", (q) => q.eq("id", h.id).lt("ts", h.ts)).order("desc").first();
+            if (prevRev !== null) {
+                await ctx.db.delete(prevRev._id);
+            }
+            if (h.isDeleted) {
+                await ctx.db.delete(h._id);
+            }
+            maxTs = Math.max(maxTs, h.ts);
+        }
+        if (vacuumed === null) {
+            await ctx.db.insert("vacuumed", {
+                minTsToKeep: maxTs,
+            });
+        }
+        else {
+            await ctx.db.patch(vacuumed._id, {
+                minTsToKeep: maxTs,
+            });
+        }
+        if (toDelete.isDone) {
+            return;
+        }
+        await ctx.scheduler.runAfter(0, internal.lib.vacuumHistoryRecursive, {
+            minTsToKeep: args.minTsToKeep,
+            paginationOpts: {
+                numItems: args.paginationOpts.numItems,
+                cursor: toDelete.continueCursor,
+            }
+        });
+    },
+});
+//# sourceMappingURL=lib.js.map

package/dist/esm/component/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../../src/component/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAoB,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAY,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK;AAC7C,yEAAyE;AACzE,8EAA8E;AAC9E,gEAAgE;AAChE,kDAAkD;AAClD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;AAClB,oFAAoF;AACpF,uEAAuE;AACvE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;AACrB,8EAA8E;AAC9E,0EAA0E;AAC1E,wDAAwD;AACxD,6CAA6C;AAC7C,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CACvB,CAAC;AAGF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE;IACZ,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,GAAG,EAAE;CACrB,CAAC,CAAC;AAGH,KAAK,UAAU,YAAY,CACzB,GAAa,EACb,eAAgC,EAChC,EAAU;IAEV,QAAQ,eAAe,EAAE,CAAC;QACxB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YACnF,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7C,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;YACpB,CAAC;QACH,CAAC;QACD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YAC1G,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7C,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;YACpB,CAAC;QACH,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE;QACJ,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,eAAe,EAAE,wBAAwB;QACzC,WAAW,EAAE,CAAC,CAAC,GAAG,EAAE;KACrB;IACD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QAChH,IAAI,QAAQ,EAAE,CAAC;YACb,EAAE,GAAG,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;QACvB,CAAC;QACD,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE;YAC7B,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,EAAE;YACF,SAAS,EAAE,IAAI,CAAC,GAAG,KAAK,IAAI;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;CACF,CAAC,CAAC;AAEH,SAAS,yBAAyB,CAAI,aAA+C;IACnF,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;QAC1B,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;QACnB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;QAC5B,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;QACpG,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;KACvD,CAAC,CAAC;AACL,CAAC;AAGD,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAC;IAC/B,IAAI,EAAE;QACJ,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,cAAc,EAAE,uBAAuB;KACxC;IACD,OAAO,EAAE,yBAAyB,CAAC,qBAAqB,CAAC;IACzD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC;aAC5C,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;aAC/C,KAAK,CAAC,MAAM,CAAC;aACb,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACjC,OAAO;YACL,GAAG,OAAO;YACV,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC;SAC5C,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH,SAAS,mBAAmB,CAAC,CAAiB;IAC5C,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,WAAW,EAAE,CAAC,CAAC,WAAW;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;IACvC,IAAI,EAAE;QACJ,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,cAAc,EAAE,uBAAuB;KACxC;IACD,OAAO,EAAE,yBAAyB,CAAC,qBAAqB,CAAC;IACzD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC;aAC5C,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;aACjE,KAAK,CAAC,MAAM,CAAC;aACb,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACjC,OAAO;YACL,GAAG,OAAO;YACV,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC;SAC5C,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH,oCAAoC;AACpC,MAAM,UAAU,GAAG,YAAY,CAAC;AAEhC,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAC;IAChC,IAAI,EAAE;QACJ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,uBAAuB;KACxC;IACD,OAAO,EAAE,yBAAyB,CAAC,qBAAqB,CAAC;IACzD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC;QAC9C,MAAM,IAAI,GAAmB,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC9C,OAAO;gBACL,cAAc,EAAE,UAAU;gBAC1B,MAAM,EAAE,IAAI;gBACZ,IAAI,EAAE,EAAE;aACT,CAAC;QACJ,CAAC;QACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,CAAC;QACxD,IAAI,QAAQ,IAAI,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,IAAI,IAAI,CAAC;QAC9D,IAAI,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;QACxC,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,qBAAqB,GAAa,EAAE,CAAC;QAC3C,OAAO,qBAAqB,CAAC,MAAM,GAAG,QAAQ,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;YAC3E,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CACzE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CACzC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YACxB,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO;oBACL,cAAc,EAAE,UAAU;oBAC1B,MAAM,EAAE,IAAI;oBACZ,IAAI;oBACJ,GAAG,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC;iBACpC,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YACnC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;YAC3B,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,UAAU,IAAI,cAAc,CAAC,EAAE,GAAG,eAAe,EAAE,CAAC;gBACtG,qCAAqC;gBACrC,OAAO;oBACL,cAAc,EAAE,eAAe;oBAC/B,MAAM,EAAE,eAAe,KAAK,UAAU;oBACtC,IAAI;oBACJ,GAAG,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC;iBACpC,CAAC;YACJ,CAAC;YACD,IAAI,QAAQ,GAA0B,cAAc,CAAC;YACrD,IAAI,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBACxC,6CAA6C;gBAC7C,MAAM,gBAAgB,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;gBAC9J,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;oBAC9B,qDAAqD;oBACrD,qCAAqC;oBACrC,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;oBAC5J,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;wBAC7B,+EAA+E;wBAC/E,mDAAmD;wBACnD,SAAS;oBACX,CAAC;yBAAM,CAAC;wBACN,qIAAqI;wBACrI,QAAQ,GAAG,IAAI,CAAC;oBAClB,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,QAAQ,GAAG,gBAAgB,CAAC;gBAC9B,CAAC;YACH,CAAC;YACD,IAAI,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACnC,qHAAqH;gBACrH,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;YACD,qBAAqB,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YAC9C,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAmC;YAC7C,cAAc,EAAE,qBAAqB,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,CAAC;YACvE,MAAM,EAAE,KAAK;YACb,IAAI;YACJ,GAAG,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC;SACpC,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,UAAoB,EAAE,QAAgB;IAIxD,IAAI,UAAU,CAAC,MAAM,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACtC,OAAO;YACL,WAAW,EAAE,UAAU,CAAC,QAAQ,GAAC,CAAC,CAAC;YACnC,UAAU,EAAE,kBAAkB;SAC/B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE;QACJ,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;KACxB;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,wEAAwE;QACxE,SAAS;QACT,yEAAyE;QACzE,wEAAwE;QACxE,iBAAiB;QACjB,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,sBAAsB,EAAE;YACrE,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,cAAc,EAAE;gBACd,QAAQ,EAAE,GAAG;gBACb,MAAM,EAAE,IAAI;aACb;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;IACrD,IAAI,EAAE;QACJ,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,cAAc,EAAE,uBAAuB;KACxC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,QAAQ,EAAE,WAAW,IAAI,CAAC,CAAC;QAC3C,IAAI,OAAO,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC;aAC7C,KAAK,CAAC,SAAS,CAAC;aAChB,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;aACvE,KAAK,CAAC,KAAK,CAAC;aACZ,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACjC,IAAI,KAAK,GAAG,OAAO,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YAC5H,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;gBAChB,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9B,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE;gBAC/B,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,sBAAsB,EAAE;YACnE,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,cAAc,EAAE;gBACd,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,QAAQ;gBACtC,MAAM,EAAE,QAAQ,CAAC,cAAc;aAChC;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/esm/component/schema.d.ts

@@ -0,0 +1,25 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    history: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        id: string;
+        ts: number;
+        doc: any;
+        isDeleted: boolean;
+        attribution: any;
+    }, {
+        id: import("convex/values").VString<string, "required">;
+        ts: import("convex/values").VFloat64<number, "required">;
+        doc: import("convex/values").VUnion<any, [import("convex/values").VAny<any, "required", string>, import("convex/values").VNull<null, "required">], "required", string>;
+        isDeleted: import("convex/values").VBoolean<boolean, "required">;
+        attribution: import("convex/values").VAny<any, "required", string>;
+    }, "required", "id" | "ts" | "doc" | "isDeleted" | "attribution" | `doc.${string}` | `attribution.${string}`>, {
+        ts: ["ts", "_creationTime"];
+        id: ["id", "ts", "_creationTime"];
+    }, {}, {}>;
+    vacuumed: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        minTsToKeep: number;
+    }, {
+        minTsToKeep: import("convex/values").VFloat64<number, "required">;
+    }, "required", "minTsToKeep">, {}, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/component/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/component/schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAGA,wBAaG"}

package/dist/esm/component/schema.js

@@ -0,0 +1,17 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    history: defineTable({
+        id: v.string(),
+        ts: v.number(),
+        doc: v.union(v.any(), v.null()),
+        isDeleted: v.boolean(),
+        attribution: v.any(),
+    })
+        .index("ts", ["ts"])
+        .index("id", ["id", "ts"]),
+    vacuumed: defineTable({
+        minTsToKeep: v.number(),
+    }),
+});
+//# sourceMappingURL=schema.js.map

package/dist/esm/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,eAAe,YAAY,CAAC;IAC1B,OAAO,EAAE,WAAW,CAAC;QACnB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;QACtB,WAAW,EAAE,CAAC,CAAC,GAAG,EAAE;KACrB,CAAC;SACC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;SACnB,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,QAAQ,EAAE,WAAW,CAAC;QACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;KACxB,CAAC;CACH,CAAC,CAAC"}

package/dist/esm/react/index.d.ts

@@ -0,0 +1,2 @@
+export declare function subtract(a: number, b: number): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAKA,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/esm/react/index.js

@@ -0,0 +1,8 @@
+// This is where React components go.
+if (typeof window === "undefined") {
+    throw new Error("this is frontend code, but it's running somewhere else!");
+}
+export function subtract(a, b) {
+    return a - b;
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;IAClC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@convex-dev/table-history",
+  "description": "A table history component for Convex.",
+  "repository": "github:get-convex/table-history",
+  "homepage": "https://github.com/get-convex/table-history#readme",
+  "bugs": {
+    "email": "support@convex.dev",
+    "url": "https://github.com/get-convex/table-history/issues"
+  },
+  "version": "0.1.3",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:esm",
+    "build:esm": "tsc --project ./esm.json",
+    "dev": "convex dev",
+    "dev:frontend": "cd example && vite",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/esm/client/index.d.ts",
+      "default": "./dist/esm/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/esm/react/index.d.ts",
+      "default": "./dist/esm/react/index.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/esm/component/_generated/component.d.ts",
+      "default": "./dist/esm/component/_generated/component.js"
+    },
+    "./convex.config": {
+      "types": "./dist/esm/component/convex.config.d.ts",
+      "default": "./dist/esm/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/esm/component/convex.config.d.ts",
+      "default": "./dist/esm/component/convex.config.js"
+    }
+  },
+  "dependencies": {
+    "convex-helpers": "^0.1.100"
+  },
+  "peerDependencies": {
+    "convex": ">= 1.18.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.1.0",
+    "@eslint/js": "^9.9.1",
+    "@types/node": "^20.19.37",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "convex": "1.34.1",
+    "convex-test": "^0.0.33",
+    "eslint": "^9.9.1",
+    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+    "eslint-plugin-react-refresh": "^0.4.9",
+    "globals": "^15.9.0",
+    "prettier": "3.2.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "5.8.3",
+    "typescript-eslint": "^8.4.0",
+    "vite": "^5.4.1",
+    "vitest": "^2.1.4"
+  },
+  "types": "./dist/esm/client/index.d.ts",
+  "module": "./dist/esm/client/index.js"
+}

package/src/client/index.ts

@@ -0,0 +1,174 @@
+import {
+  DocumentByName,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  PaginationOptions,
+  TableNamesInDataModel,
+} from "convex/server";
+import { GenericId } from "convex/values";
+import type { Serializability } from "../component/lib.js";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+export class TableHistory<
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> {
+  public options: {
+    serializability: Serializability;
+  };
+  constructor(
+    public component: ComponentApi,
+    options?: {
+      serializability?: Serializability;
+    }
+  ) {
+    this.options = {
+      serializability: options?.serializability ?? "wallclock",
+    };
+  }
+
+  /**
+   * Write a new history entry.
+   *
+   * @argument attribution an arbitrary object that will be stored with the
+   *   history entry. Attribution can include actor/user identity, reason for
+   *   change, etc.
+   */
+  async update(
+    ctx: RunMutationCtx,
+    id: GenericId<TableName>,
+    doc: DocumentByName<DataModel, TableName> | null,
+    attribution: unknown = null
+  ) {
+    return ctx.runMutation(this.component.lib.update, {
+      id,
+      doc,
+      serializability: this.options.serializability,
+      attribution,
+    });
+  }
+
+  /**
+   * Paginate the history of the table, from newest to oldest.
+   *
+   * @argument maxTs To keep pages contiguous, set `maxTs` to a fixed timestamp
+   *   (milliseconds since epoch, like Date.now()) and keep
+   *   it the same for subsequent pages.
+   */
+  async listHistory(
+    ctx: RunQueryCtx,
+    maxTs: number,
+    paginationOpts: PaginationOptions
+  ) {
+    return ctx.runQuery(this.component.lib.listHistory, {
+      maxTs,
+      paginationOpts,
+    });
+  }
+  /**
+   * Paginate the history of a single document, from newest to oldest.
+   *
+   * @argument maxTs To keep pages contiguous, set `maxTs` to a fixed timestamp
+   *   (milliseconds since epoch, like Date.now()) and keep
+   *   it the same for subsequent pages.
+   */
+  async listDocumentHistory(
+    ctx: RunQueryCtx,
+    id: GenericId<TableName>,
+    maxTs: number,
+    paginationOpts: PaginationOptions
+  ) {
+    return ctx.runQuery(this.component.lib.listDocumentHistory, {
+      id,
+      maxTs,
+      paginationOpts,
+    });
+  }
+  /**
+   * Paginate a snapshot of the table at a fixed timestamp.
+   *
+   * @argument ts the snapshot at which you want to list the table (milliseconds since epoch)
+   * @argument currentTs a fixed recent timestamp (milliseconds since epoch, like Date.now())
+   *   which should be the same for subsequent pages.
+   */
+  async listSnapshot(
+    ctx: RunQueryCtx,
+    snapshotTs: number,
+    currentTs: number,
+    paginationOpts: PaginationOptions
+  ) {
+    return ctx.runQuery(this.component.lib.listSnapshot, {
+      snapshotTs,
+      currentTs,
+      paginationOpts,
+    });
+  }
+
+  /**
+   * Delete old history entries.
+   *
+   * @argument minTsToKeep the timestamp (milliseconds since epoch) of the oldest
+   *   snapshot of history that should be kept.
+   */
+  async vacuumHistory(ctx: RunMutationCtx, minTsToKeep: number) {
+    return ctx.runMutation(this.component.lib.vacuumHistory, { minTsToKeep });
+  }
+
+  /**
+   * For use with `Triggers` from "convex-helpers/server/triggers".
+   */
+  trigger<Ctx extends RunMutationCtx>(): Trigger<Ctx, DataModel, TableName> {
+    return async (ctx, change) => {
+      let attribution: unknown = null;
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (ctx as any).auth &&
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        typeof (ctx as any).auth.getUserIdentity === "function"
+      ) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        attribution = await (ctx as any).auth.getUserIdentity();
+      }
+      await this.update(ctx, change.id, change.newDoc, attribution);
+    };
+  }
+}
+
+/* Type utils follow */
+
+export type Trigger<
+  Ctx,
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> = (ctx: Ctx, change: Change<DataModel, TableName>) => Promise<void>;
+
+export type Change<
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> = {
+  id: GenericId<TableName>;
+} & (
+  | {
+      operation: "insert";
+      oldDoc: null;
+      newDoc: DocumentByName<DataModel, TableName>;
+    }
+  | {
+      operation: "update";
+      oldDoc: DocumentByName<DataModel, TableName>;
+      newDoc: DocumentByName<DataModel, TableName>;
+    }
+  | {
+      operation: "delete";
+      oldDoc: DocumentByName<DataModel, TableName>;
+      newDoc: null;
+    }
+);
+
+type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+type RunMutationCtx = {
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+};