cosveti-sync 0.0.1

package/dist/component/lib.js

@@ -0,0 +1,272 @@
+import { v } from 'convex/values';
+import { mutation, query } from './_generated/server.js';
+import { vClientId } from './schema.js';
+import { api } from './_generated/api.js';
+const MAX_DELTA_FETCH = 100;
+const MAX_SNAPSHOT_FETCH = 10;
+export const submitSnapshot = mutation({
+    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
+            .query('snapshots')
+            .withIndex('id_version', (q) => q.eq('id', args.id).eq('version', args.version))
+            .first();
+        if (existing) {
+            if (existing.content === args.content) {
+                return;
+            }
+            throw new Error(`Snapshot ${args.id} at version ${args.version} already exists ` +
+                `with different content: ${existing.content} !== ${args.content}`);
+        }
+        await ctx.db.insert('snapshots', {
+            id: args.id,
+            version: args.version,
+            content: args.content
+        });
+        if (args.version > 1 && args.pruneSnapshots) {
+            // Delete all older snapshots, except the original one.
+            await deleteSnapshotsHelper(ctx, {
+                id: args.id,
+                afterVersion: 1,
+                beforeVersion: args.version
+            });
+        }
+    }
+});
+export const latestVersion = query({
+    args: { id: v.string() },
+    returns: v.union(v.null(), v.number()),
+    handler: async (ctx, args) => {
+        const latestDelta = await ctx.db
+            .query('deltas')
+            .withIndex('id_version', (q) => q.eq('id', args.id))
+            .order('desc')
+            .first();
+        if (latestDelta) {
+            return latestDelta.version;
+        }
+        const latestSnapshot = await ctx.db
+            .query('snapshots')
+            .withIndex('id_version', (q) => q.eq('id', args.id))
+            .order('desc')
+            .first();
+        return latestSnapshot?.version ?? null;
+    }
+});
+export const submitSteps = mutation({
+    args: {
+        id: v.string(),
+        version: v.number(),
+        clientId: vClientId,
+        steps: v.array(v.string())
+    },
+    returns: v.union(v.object({
+        status: v.literal('needs-rebase'),
+        clientIds: v.array(vClientId),
+        steps: v.array(v.string())
+    }), v.object({ status: v.literal('synced') })),
+    handler: async (ctx, args) => {
+        const changes = await ctx.db
+            .query('deltas')
+            .withIndex('id_version', (q) => q.eq('id', args.id).gt('version', args.version))
+            .take(MAX_DELTA_FETCH);
+        if (changes.length > 0) {
+            const [steps, clientIds] = stepsAndClientIds(changes);
+            return { status: 'needs-rebase', clientIds, steps };
+        }
+        await ctx.db.insert('deltas', {
+            id: args.id,
+            version: args.version + args.steps.length,
+            clientId: args.clientId,
+            steps: args.steps
+        });
+        return { status: 'synced' };
+    }
+});
+function stepsAndClientIds(deltas) {
+    const clientIds = [];
+    const steps = [];
+    for (const delta of deltas) {
+        for (const step of delta.steps) {
+            clientIds.push(delta.clientId);
+            steps.push(step);
+        }
+    }
+    return [steps, clientIds];
+}
+export const getSnapshot = query({
+    args: { id: v.string(), version: v.optional(v.number()) },
+    returns: v.union(v.object({
+        content: v.null(),
+        version: v.null()
+    }), v.object({
+        content: v.string(),
+        version: v.number()
+    })),
+    handler: async (ctx, args) => {
+        const snapshot = await ctx.db
+            .query('snapshots')
+            .withIndex('id_version', (q) => q.eq('id', args.id).lte('version', args.version ?? Infinity))
+            .order('desc')
+            .first();
+        if (!snapshot) {
+            return {
+                content: null,
+                version: null
+            };
+        }
+        return {
+            content: snapshot.content,
+            version: snapshot.version
+        };
+    }
+});
+async function fetchSteps(ctx, id, afterVersion, targetVersion) {
+    const deltas = await ctx.db
+        .query('deltas')
+        .withIndex('id_version', (q) => q
+        .eq('id', id)
+        .gt('version', afterVersion)
+        .lte('version', targetVersion ?? Infinity))
+        .take(MAX_DELTA_FETCH);
+    if (deltas.length > 0) {
+        const firstDelta = deltas[0];
+        if (firstDelta.version - firstDelta.steps.length > afterVersion) {
+            throw new Error(`Missing steps ${afterVersion + 1}...${firstDelta.version - firstDelta.steps.length}`);
+        }
+        else if (firstDelta.version - firstDelta.steps.length < afterVersion) {
+            firstDelta.steps = firstDelta.steps.slice(afterVersion - (firstDelta.version - firstDelta.steps.length));
+        }
+    }
+    const [steps, clientIds] = stepsAndClientIds(deltas);
+    if (deltas.length === MAX_DELTA_FETCH) {
+        console.warn(`Max delta fetch reached: ${id} ${afterVersion}...${targetVersion ?? 'end'} stopped at ${deltas[deltas.length - 1].version}`);
+        return [steps, clientIds];
+    }
+    const lastDelta = deltas[deltas.length - 1];
+    if (targetVersion && (!lastDelta || lastDelta.version < targetVersion)) {
+        const nextDelta = await ctx.db
+            .query('deltas')
+            .withIndex('id_version', (q) => q.eq('id', id).gt('version', lastDelta.version))
+            .first();
+        if (!nextDelta) {
+            throw new Error(`Missing steps ${lastDelta ? lastDelta.version + 1 : afterVersion}...${targetVersion}`);
+        }
+        for (let i = 0; i < targetVersion - lastDelta.version; i++) {
+            steps.push(nextDelta.steps[i]);
+            clientIds.push(nextDelta.clientId);
+        }
+    }
+    if (targetVersion && steps.length !== targetVersion - afterVersion) {
+        throw new Error(`Steps mismatch ${afterVersion}...${targetVersion}: ${steps.length}`);
+    }
+    return [steps, clientIds];
+}
+export const getSteps = query({
+    args: { id: v.string(), version: v.number() },
+    returns: v.object({
+        steps: v.array(v.string()),
+        clientIds: v.array(vClientId),
+        version: v.number()
+    }),
+    handler: async (ctx, args) => {
+        const [steps, clientIds] = await fetchSteps(ctx, args.id, args.version);
+        return { steps, clientIds, version: args.version + steps.length };
+    }
+});
+/**
+ * Delete snapshots in the given range, not including the bounds.
+ * To clean up old snapshots, call this with the current version as the
+ * beforeVersion and the first version (1) as the afterVersion.
+ */
+export const deleteSnapshots = mutation({
+    args: {
+        id: v.string(),
+        afterVersion: v.optional(v.number()),
+        beforeVersion: v.optional(v.number())
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await deleteSnapshotsHelper(ctx, args);
+    }
+});
+async function deleteSnapshotsHelper(ctx, args) {
+    const versions = await ctx.db
+        .query('snapshots')
+        .withIndex('id_version', (q) => {
+        const eq = q.eq('id', args.id);
+        const after = args.afterVersion !== undefined ? eq.gt('version', args.afterVersion) : eq;
+        const before = args.beforeVersion !== undefined ? after.lt('version', args.beforeVersion) : after;
+        return before;
+    })
+        .take(MAX_SNAPSHOT_FETCH);
+    await Promise.all(versions.map((doc) => ctx.db.delete(doc._id)));
+    if (versions.length === MAX_SNAPSHOT_FETCH) {
+        await ctx.scheduler.runAfter(0, api.lib.deleteSnapshots, {
+            id: args.id,
+            beforeVersion: args.beforeVersion,
+            afterVersion: versions[versions.length - 1].version
+        });
+    }
+}
+/**
+ * Delete steps before some timestamp.
+ * To clean up old steps, call this with a date in the past for beforeTs.
+ * By default it will ensure that all steps are older than the latest snapshot.
+ */
+export const deleteSteps = mutation({
+    args: {
+        id: v.string(),
+        afterVersion: v.optional(v.number()),
+        beforeTs: v.number(),
+        deleteNewerThanLatestSnapshot: v.optional(v.boolean())
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        let beforeTs = args.beforeTs;
+        if (!args.deleteNewerThanLatestSnapshot) {
+            const latestSnapshot = await ctx.db
+                .query('snapshots')
+                .withIndex('id_version', (q) => q.eq('id', args.id))
+                .order('desc')
+                .first();
+            if (latestSnapshot) {
+                beforeTs = Math.min(beforeTs, latestSnapshot._creationTime);
+            }
+        }
+        const deltas = (await ctx.db
+            .query('deltas')
+            .withIndex('id_version', (q) => q.eq('id', args.id).gt('version', args.afterVersion ?? -Infinity))
+            .take(MAX_DELTA_FETCH)).filter((doc) => doc._creationTime < beforeTs);
+        await Promise.all(deltas.map((doc) => ctx.db.delete(doc._id)));
+        if (deltas.length === MAX_DELTA_FETCH) {
+            await ctx.scheduler.runAfter(0, api.lib.deleteSteps, {
+                id: args.id,
+                beforeTs,
+                // We already checked that the timestamp is before
+                deleteNewerThanLatestSnapshot: true
+            });
+        }
+    }
+});
+/**
+ * Delete a document and all its snapshots & steps.
+ */
+export const deleteDocument = mutation({
+    args: { id: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.runMutation(api.lib.deleteSnapshots, { id: args.id });
+        await ctx.scheduler.runAfter(0, api.lib.deleteSteps, {
+            id: args.id,
+            beforeTs: Infinity,
+            deleteNewerThanLatestSnapshot: true
+        });
+    }
+});

package/dist/component/schema.d.ts

@@ -0,0 +1,28 @@
+export declare const vClientId: import("convex/values").VUnion<string | number, [import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">], "required", never>;
+declare const _default: import("convex/server").SchemaDefinition<{
+    snapshots: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        id: string;
+        version: number;
+        content: string;
+    }, {
+        id: import("convex/values").VString<string, "required">;
+        version: import("convex/values").VFloat64<number, "required">;
+        content: import("convex/values").VString<string, "required">;
+    }, "required", "id" | "version" | "content">, {
+        id_version: ["id", "version", "_creationTime"];
+    }, {}, {}>;
+    deltas: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        id: string;
+        version: number;
+        clientId: string | number;
+        steps: string[];
+    }, {
+        id: import("convex/values").VString<string, "required">;
+        version: import("convex/values").VFloat64<number, "required">;
+        clientId: import("convex/values").VUnion<string | number, [import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">], "required", never>;
+        steps: import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">;
+    }, "required", "id" | "version" | "clientId" | "steps">, {
+        id_version: ["id", "version", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;

package/dist/component/schema.js

@@ -0,0 +1,17 @@
+import { defineSchema, defineTable } from 'convex/server';
+import { v } from 'convex/values';
+export const vClientId = v.union(v.string(), v.number());
+export default defineSchema({
+    snapshots: defineTable({
+        id: v.string(),
+        version: v.number(),
+        content: v.string()
+    }).index('id_version', ['id', 'version']),
+    deltas: defineTable({
+        id: v.string(),
+        // The version of the last step.
+        version: v.number(),
+        clientId: vClientId,
+        steps: v.array(v.string())
+    }).index('id_version', ['id', 'version'])
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useTiptapSync } from './tiptap/index.js';
+export type { UseSyncOptions, InitialState, SyncContext } from './tiptap/types.js';
+export type { SyncApi } from './client/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// Reexport your entry components here
+// Main entry point for @feavel/svelte-convex-tiptap-sync package
+export { useTiptapSync } from './tiptap/index.js';

package/dist/tiptap/doSync.d.ts

@@ -0,0 +1,5 @@
+import { type Editor } from '@tiptap/core';
+import type { SyncApi } from '../client/index.js';
+import type { InitialState } from './types.js';
+import type { ConvexClient } from 'convex/browser';
+export declare function doSync(editor: Editor, convex: ConvexClient, syncApi: SyncApi, id: string, serverVersion: number | null, initialState: InitialState, debug?: boolean): Promise<boolean>;

package/dist/tiptap/doSync.js

@@ -0,0 +1,75 @@
+import {} from '@tiptap/core';
+import * as collab from '@tiptap/pm/collab';
+import { Step } from '@tiptap/pm/transform';
+import { receiveSteps } from './reciveSteps.js';
+import { MAX_STEPS_SYNC } from './index.js';
+export async function doSync(editor, convex, syncApi, id, serverVersion, initialState, debug) {
+    const log = debug ? console.debug : () => { };
+    if (serverVersion === null) {
+        if (initialState.initialVersion != undefined && initialState.initialVersion <= 1) {
+            // This is a new document, so we can create it on the server.
+            // Note: this should only happen if the initial version is loaded from
+            // a local cache. Creating a new document on the client will set the
+            // initial version to 1 optimistically.
+            log('Syncing new document', { id });
+            await convex.mutation(syncApi.submitSnapshot, {
+                id,
+                version: initialState.initialVersion,
+                content: JSON.stringify(initialState.initialContent)
+            });
+        }
+        else {
+            // TODO: Handle deletion gracefully
+            throw new Error("Syncing a document that doesn't exist server-side");
+        }
+    }
+    const version = collab.getVersion(editor.state);
+    if (serverVersion !== null && serverVersion > version) {
+        log('Updating to server version', {
+            id,
+            version,
+            serverVersion
+        });
+        const steps = await convex.query(syncApi.getSteps, {
+            id,
+            version
+        });
+        receiveSteps(editor, steps.steps.map((step) => Step.fromJSON(editor.schema, JSON.parse(step))), steps.clientIds);
+    }
+    let anyChanges = false;
+    while (true) {
+        const sendable = collab.sendableSteps(editor.state);
+        if (!sendable) {
+            break;
+        }
+        const steps = sendable.steps
+            .slice(0, MAX_STEPS_SYNC)
+            .map((step) => JSON.stringify(step.toJSON()));
+        log('Sending steps', { steps, version: sendable.version });
+        const result = await convex.mutation(syncApi.submitSteps, {
+            id,
+            steps,
+            version: sendable.version,
+            clientId: sendable.clientID
+        });
+        if (result.status === 'synced') {
+            anyChanges = true;
+            // We replay the steps locally to avoid refetching them.
+            receiveSteps(editor, steps.map((step) => Step.fromJSON(editor.schema, JSON.parse(step))), steps.map(() => sendable.clientID));
+            log('Synced', {
+                steps,
+                version,
+                newVersion: collab.getVersion(editor.state)
+            });
+            continue;
+        }
+        if (result.status === 'needs-rebase') {
+            receiveSteps(editor, result.steps.map((step) => Step.fromJSON(editor.schema, JSON.parse(step))), result.clientIds);
+            log('Rebased', {
+                steps,
+                newVersion: collab.getVersion(editor.state)
+            });
+        }
+    }
+    return anyChanges;
+}

package/dist/tiptap/getCachedState.d.ts

@@ -0,0 +1,2 @@
+import type { InitialState } from './types.js';
+export declare function getCachedState(id: string, cacheKeyPrefix?: string): InitialState | undefined;

package/dist/tiptap/getCachedState.js

@@ -0,0 +1,23 @@
+export function getCachedState(id, cacheKeyPrefix) {
+    // Check if we're in a browser environment before accessing sessionStorage
+    if (typeof window === 'undefined' || !window.sessionStorage) {
+        return undefined;
+    }
+    const cacheKey = `${cacheKeyPrefix ?? 'convex-sync'}-${id}`;
+    const cache = localStorage.getItem(cacheKey);
+    if (cache) {
+        try {
+            const { content, version, steps } = JSON.parse(cache);
+            return {
+                initialContent: content,
+                initialVersion: Number(version),
+                restoredSteps: (steps ?? [])
+            };
+        }
+        catch (e) {
+            console.warn('Failed to parse cached state', e);
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/tiptap/index.d.ts

@@ -0,0 +1,17 @@
+import type { InitialState, UseSyncOptions } from './types.js';
+import { type Writable } from 'svelte/store';
+import type { SyncApi } from '../client/index.js';
+import type { JSONContent } from '@tiptap/core';
+import type { ConvexClient } from 'convex/browser';
+export declare const MAX_STEPS_SYNC = 10;
+export declare const SNAPSHOT_DEBOUNCE_MS = 1000;
+export declare function useTiptapSync(convex: ConvexClient, syncApi: SyncApi, id: string, opts?: UseSyncOptions): {
+    isSyncEnabled: Writable<boolean>;
+    isLoading: import("svelte/store").Readable<boolean>;
+    initialContent: import("svelte/store").Readable<string | JSONContent | JSONContent[] | null>;
+    extension: import("svelte/store").Readable<import("@tiptap/core").AnyExtension | null>;
+    create: (content: JSONContent) => Promise<void>;
+};
+export declare function createInitialStateStore(convex: ConvexClient, syncApi: SyncApi, id: string, cacheKeyPrefix?: string): Writable<InitialState & {
+    loading: boolean;
+}>;

package/dist/tiptap/index.js

@@ -0,0 +1,134 @@
+import { getCachedState } from './getCachedState.js';
+import { derived, writable } from 'svelte/store';
+import { syncExtension } from './syncExtension.js';
+// import { useConvexClient } from 'convex-svelte';
+export const MAX_STEPS_SYNC = 10;
+export const SNAPSHOT_DEBOUNCE_MS = 1000;
+export function useTiptapSync(convex, syncApi, id, opts) {
+    // console.log('Use tiptap sync with document id: ' + id);
+    // const convex = useConvexClient();
+    const initialStateStore = createInitialStateStore(convex, syncApi, id);
+    const isSyncEnabled = writable(true);
+    const optimisticUpdate = (localQueryStore, args) => {
+        const existing = localQueryStore.getQuery(syncApi.getSnapshot, { id: args.id });
+        console.log('Existing content:' + existing);
+        if (!existing?.content) {
+            localQueryStore.setQuery(syncApi.getSnapshot, { id: args.id }, {
+                version: args.version,
+                content: args.content
+            });
+        }
+        const version = localQueryStore.getQuery(syncApi.latestVersion, { id: args.id });
+        if (version === null) {
+            localQueryStore.setQuery(syncApi.latestVersion, { id: args.id }, args.version);
+        }
+    };
+    // Submit snapshot mutation with optimistic update
+    const submitSnapshot = (args) => convex.mutation(syncApi.submitSnapshot, args, { optimisticUpdate });
+    // Create function (stable reference - no useCallback needed)
+    const create = async (content) => {
+        console.log('Creating new document', { id });
+        await submitSnapshot({
+            id,
+            version: 1,
+            content: JSON.stringify(content)
+        });
+    };
+    const state = derived([initialStateStore], ([$initialState]) => {
+        if ($initialState.loading) {
+            // console.log('$initialState.loading');
+            return {
+                isLoading: true,
+                initialContent: null,
+                extension: null
+            };
+        }
+        if (!$initialState.initialContent) {
+            console.log('No content found for this document yet');
+            return {
+                isLoading: false,
+                initialContent: null,
+                extension: null
+            };
+        }
+        const extension = syncExtension(convex, id, syncApi, $initialState, opts, isSyncEnabled);
+        return {
+            isLoading: false,
+            initialContent: $initialState.initialContent,
+            extension
+        };
+    });
+    const isLoading = derived(state, ($s) => $s.isLoading);
+    const initialContent = derived(state, ($s) => $s.initialContent);
+    const extension = derived(state, ($s) => $s.extension);
+    return { isSyncEnabled, isLoading, initialContent, extension, create };
+}
+export function createInitialStateStore(convex, syncApi, id, cacheKeyPrefix) {
+    // const convex = useConvexClient();
+    const store = writable({
+        loading: true,
+        initialContent: null
+    });
+    // Try cached state first (will return immediately)
+    const cachedState = getCachedState(id, cacheKeyPrefix);
+    if (cachedState) {
+        console.log('Loaded from cache!');
+        store.set({
+            loading: false,
+            ...cachedState
+        });
+    }
+    // Currently unsupproted because convex.onUpdate doesn't have same 'skip' parameter as convex-svelte useQuery
+    // So the store will be set first, then a newer version from server will arrive
+    // const queryArgs = cachedState ? 'skip' : { id };
+    const queryArgs = { id };
+    convex
+        .query(syncApi.getSnapshot, queryArgs)
+        .then((result) => {
+        // Handle missing document case
+        if (!result) {
+            store.set({ loading: false, initialContent: null });
+            return;
+        }
+        const { content, version } = result;
+        // Handle explicit null content
+        if (content === null) {
+            store.set({ loading: false, initialContent: null });
+            return;
+        }
+        // Validate content type before parsing
+        if (typeof content !== 'string') {
+            const errorMsg = `Invalid content type received: ${typeof content}`;
+            console.error(errorMsg, { content, version });
+            throw new Error(errorMsg); // Propagate to catch block for unified error handling
+        }
+        try {
+            // Safely parse and validate structure
+            const parsedContent = JSON.parse(content);
+            // Optional: Add runtime type validation here if Content has specific structure
+            // if (!isValidContent(parsedContent)) throw new Error('Invalid content structure');
+            store.set({
+                loading: false,
+                initialContent: parsedContent, // Assert only after validation
+                initialVersion: version
+            });
+        }
+        catch (parseError) {
+            console.error('Content parsing failed:', parseError, { rawContent: content });
+            throw new Error(`JSON parse error: ${parseError instanceof Error ? parseError.message : 'Unknown error'}`);
+        }
+    })
+        .catch((error) => {
+        console.error('Snapshot load failed:', error);
+        // Unified error state update (covers query errors, type errors, parse errors)
+        store.set({
+            loading: false,
+            initialContent: null
+            // Optional: Add error tracking if your store supports it
+            // error: error instanceof Error ? error.message : 'Unknown snapshot error'
+        });
+        // Re-throw if caller needs to handle errors (remove if errors should be fully absorbed)
+        // throw error;
+    });
+    return store;
+}

package/dist/tiptap/reciveSteps.d.ts

@@ -0,0 +1,3 @@
+import { Step } from '@tiptap/pm/transform';
+import type { Editor } from '@tiptap/core';
+export declare function receiveSteps(editor: Editor, steps: Step[], clientIds: (string | number)[]): void;

package/dist/tiptap/reciveSteps.js

@@ -0,0 +1,7 @@
+import { Step } from '@tiptap/pm/transform';
+import * as collab from '@tiptap/pm/collab';
+export function receiveSteps(editor, steps, clientIds) {
+    editor.view.dispatch(collab.receiveTransaction(editor.state, steps, clientIds, {
+        mapSelectionBackward: true
+    }));
+}

package/dist/tiptap/syncExtension.d.ts

@@ -0,0 +1,6 @@
+import { type AnyExtension } from '@tiptap/core';
+import type { SyncApi } from '../client/index.js';
+import type { InitialState, UseSyncOptions } from './types.js';
+import type { ConvexClient } from 'convex/browser';
+import { type Writable } from 'svelte/store';
+export declare function syncExtension(convex: ConvexClient, id: string, syncApi: SyncApi, initialState: InitialState, opts?: UseSyncOptions, isSyncEnabled?: Writable<boolean>): AnyExtension;