change snapshot pruning to opt-in

Author: ianmacartney

README.md

@@ -44,8 +44,7 @@ Features:
 - Server-side entrypoints for authorizing reads, writes, and snapshots.
 - Create a new document, online or offline.
 - Debounced snapshots allow new clients to avoid reading the full history.
-- Deletion API for old snapshots & steps. By default all steps are kept, but
-  only the original and newest snapshots.
+- Deletion API for old snapshots & steps.
 - Transform the document server-side, enabling easy AI interoperation.
 
 Features that could be added later:
@@ -59,7 +58,6 @@ Features that could be added later:
 - Option to write the concrete value each time a delta is submitted.
 - Pluggable storage for ReactNative, assuming single-session.
 - Warning when closing tab with unsynced changes (works by default?).
-- Vacuuming controls for old deltas & snapshots.
 - Convert it to a ProseMirror plugin instead of a Tiptap extension, so raw
   ProseMirror usecases can also use it.
 - Handling edge cases, such as old clients with local changes on top of an older

example/convex/_generated/api.d.ts

@@ -88,7 +88,12 @@ export declare const components: {
       submitSnapshot: FunctionReference<
         "mutation",
         "internal",
-        { content: string; id: string; version: number },
+        {
+          content: string;
+          id: string;
+          pruneSnapshots?: boolean;
+          version: number;
+        },
         null
       >;
       submitSteps: FunctionReference<

src/client/index.ts

@@ -59,6 +59,16 @@ export class ProsemirrorSync<Id extends string = string> {
     });
   }
 
+  /**
+   * Get the latest document version and content.
+   *
+   * @param ctx - A Convex mutation context.
+   * @param id - The document ID.
+   * @param schema - Your ProseMirror schema.
+   *   For Tiptap, use `getSchema(extensions)`.
+   *   For BlockNote, use `editor.pmSchema`.
+   * @returns The latest ProseMirror doc (Node) and version.
+   */
   async getDoc(ctx: RunMutationCtx, id: Id, schema: Schema) {
     const { transform, version } = await getLatestVersion(
       ctx,
@@ -164,20 +174,46 @@ export class ProsemirrorSync<Id extends string = string> {
    * @returns functions to export, so the `useTiptapSync` hook can use them.
    */
   syncApi<DataModel extends GenericDataModel>(opts?: {
+    /**
+     * Optional callback to check read permissions.
+     * Throw an error if the user is not authorized to read the document.
+     * @param ctx - A Convex query context.
+     * @param id - The document ID.
+     */
     checkRead?: (
       ctx: GenericQueryCtx<DataModel>,
       id: Id
     ) => void | Promise<void>;
+    /**
+     * Optional callback to check write permissions.
+     * Throw an error if the user is not authorized to write to the document.
+     * @param ctx - A Convex mutation context.
+     * @param id - The document ID.
+     */
     checkWrite?: (
       ctx: GenericMutationCtx<DataModel>,
       id: Id
     ) => void | Promise<void>;
+    /**
+     * Optional callback to run when a new snapshot is available.
+     * Version 1 is the initial content.
+     * @param ctx - A Convex mutation context.
+     * @param id - The document ID.
+     * @param snapshot - The snapshot content, as stringified ProseMirror JSON.
+     * @param version - The version this snapshot represents.
+     */
     onSnapshot?: (
       ctx: GenericMutationCtx<DataModel>,
       id: Id,
       snapshot: string,
       version: number
     ) => void | Promise<void>;
+    /**
+     * Whether to prune old snapshots.
+     * If set to true, only the original and newest snapshots are kept.
+     * @default true
+     */
+    pruneSnapshots?: boolean;
   }) {
     const id = v.string() as VString<Id>;
     return {
@@ -216,7 +252,10 @@ export class ProsemirrorSync<Id extends string = string> {
           if (opts?.onSnapshot) {
             await opts.onSnapshot(ctx, args.id, args.content, args.version);
           }
-          await ctx.runMutation(this.component.lib.submitSnapshot, args);
+          await ctx.runMutation(this.component.lib.submitSnapshot, {
+            ...args,
+            pruneSnapshots: opts?.pruneSnapshots,
+          });
         },
       }),
       latestVersion: queryGeneric({

src/component/_generated/api.d.ts

@@ -76,7 +76,12 @@ export type Mounts = {
     submitSnapshot: FunctionReference<
       "mutation",
       "public",
-      { content: string; id: string; version: number },
+      {
+        content: string;
+        id: string;
+        pruneSnapshots?: boolean;
+        version: number;
+      },
       null
     >;
     submitSteps: FunctionReference<

src/component/lib.ts

@@ -8,7 +8,12 @@ const MAX_DELTA_FETCH = 1000;
 const MAX_SNAPSHOT_FETCH = 10;
 
 export const submitSnapshot = mutation({
-  args: { id: v.string(), version: v.number(), content: v.string() },
+  args: {
+    id: v.string(),
+    version: v.number(),
+    content: v.string(),
+    pruneSnapshots: v.optional(v.boolean()),
+  },
   returns: v.null(),
   handler: async (ctx, args) => {
     const existing = await ctx.db
@@ -31,7 +36,7 @@ export const submitSnapshot = mutation({
       version: args.version,
       content: args.content,
     });
-    if (args.version > 1) {
+    if (args.version > 1 && args.pruneSnapshots) {
       // Delete all older snapshots, except the original one.
       await deleteSnapshotsHelper(ctx, {
         id: args.id,