@abdssamie/convex-checkpoints 0.1.1

package/dist/component/lib.js

@@ -0,0 +1,91 @@
+import { v } from "convex/values";
+import { internalQuery, mutation, query } from "./_generated/server.js";
+import schema from "./schema.js";
+const checkpointValidator = schema.tables.checkpoints.validator.extend({
+    _id: v.id("checkpoints"),
+    _creationTime: v.number(),
+});
+export const record = mutation({
+    args: {
+        name: v.string(),
+        userId: v.optional(v.string()),
+        payload: v.optional(v.any()),
+        idempotencyKey: v.optional(v.string()),
+        reachedAt: v.optional(v.number()),
+    },
+    returns: v.object({
+        checkpointId: v.id("checkpoints"),
+        created: v.boolean(),
+    }),
+    handler: async (ctx, args) => {
+        if (args.idempotencyKey !== undefined) {
+            const existing = await ctx.db
+                .query("checkpoints")
+                .withIndex("by_idempotencyKey", (q) => q.eq("idempotencyKey", args.idempotencyKey))
+                .unique();
+            if (existing !== null) {
+                return { checkpointId: existing._id, created: false };
+            }
+        }
+        const now = Date.now();
+        const checkpointId = await ctx.db.insert("checkpoints", {
+            name: args.name,
+            userId: args.userId,
+            payload: args.payload,
+            idempotencyKey: args.idempotencyKey,
+            reachedAt: args.reachedAt ?? now,
+            receivedAt: now,
+        });
+        return { checkpointId, created: true };
+    },
+});
+export const listRecent = query({
+    args: {
+        limit: v.optional(v.number()),
+    },
+    returns: v.array(checkpointValidator),
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("checkpoints")
+            .order("desc")
+            .take(args.limit ?? 100);
+    },
+});
+export const listByName = query({
+    args: {
+        name: v.string(),
+        limit: v.optional(v.number()),
+    },
+    returns: v.array(checkpointValidator),
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("checkpoints")
+            .withIndex("by_name_and_reachedAt", (q) => q.eq("name", args.name))
+            .order("desc")
+            .take(args.limit ?? 100);
+    },
+});
+export const listByUser = query({
+    args: {
+        userId: v.string(),
+        limit: v.optional(v.number()),
+    },
+    returns: v.array(checkpointValidator),
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("checkpoints")
+            .withIndex("by_userId_and_reachedAt", (q) => q.eq("userId", args.userId))
+            .order("desc")
+            .take(args.limit ?? 100);
+    },
+});
+export const get = internalQuery({
+    args: {
+        checkpointId: v.id("checkpoints"),
+    },
+    returns: v.union(v.null(), checkpointValidator),
+    handler: async (ctx, args) => {
+        return await ctx.db.get("checkpoints", args.checkpointId);
+    },
+});
+//# sourceMappingURL=lib.js.map

package/dist/component/lib.js.map

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

package/dist/component/schema.d.ts

@@ -0,0 +1,23 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    checkpoints: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        userId?: string | undefined;
+        idempotencyKey?: string | undefined;
+        payload?: any;
+        name: string;
+        reachedAt: number;
+        receivedAt: number;
+    }, {
+        name: import("convex/values").VString<string, "required">;
+        userId: import("convex/values").VString<string | undefined, "optional">;
+        payload: import("convex/values").VAny<any, "optional", string>;
+        idempotencyKey: import("convex/values").VString<string | undefined, "optional">;
+        reachedAt: import("convex/values").VFloat64<number, "required">;
+        receivedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "name" | "userId" | "idempotencyKey" | "payload" | "reachedAt" | "receivedAt" | `payload.${string}`>, {
+        by_name_and_reachedAt: ["name", "reachedAt", "_creationTime"];
+        by_userId_and_reachedAt: ["userId", "reachedAt", "_creationTime"];
+        by_idempotencyKey: ["idempotencyKey", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

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

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

package/dist/component/schema.js

@@ -0,0 +1,16 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    checkpoints: defineTable({
+        name: v.string(),
+        userId: v.optional(v.string()),
+        payload: v.optional(v.any()),
+        idempotencyKey: v.optional(v.string()),
+        reachedAt: v.number(),
+        receivedAt: v.number(),
+    })
+        .index("by_name_and_reachedAt", ["name", "reachedAt"])
+        .index("by_userId_and_reachedAt", ["userId", "reachedAt"])
+        .index("by_idempotencyKey", ["idempotencyKey"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/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,WAAW,EAAE,WAAW,CAAC;QACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QAC5B,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACtC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;KACvB,CAAC;SACC,KAAK,CAAC,uBAAuB,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;SACrD,KAAK,CAAC,yBAAyB,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;SACzD,KAAK,CAAC,mBAAmB,EAAE,CAAC,gBAAgB,CAAC,CAAC;CAClD,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@abdssamie/convex-checkpoints",
+  "description": "A Convex component for event-driven user checkpoints.",
+  "repository": "github:abdssamie/convex-checkpoints",
+  "homepage": "https://github.com/abdssamie/convex-checkpoints#readme",
+  "bugs": {
+    "url": "https://github.com/abdssamie/convex-checkpoints/issues"
+  },
+  "version": "0.1.1",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component",
+    "events",
+    "checkpoints"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.36.1"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.2.2",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "9.39.4",
+    "@types/node": "^24.12.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.36.1",
+    "convex-test": "0.0.49",
+    "eslint": "9.39.4",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.5.0",
+    "pkg-pr-new": "^0.0.66",
+    "prettier": "3.8.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.58.2",
+    "vite": "8.0.9",
+    "vitest": "4.1.4"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "scripts": {
+    "dev": "convex dev --start 'npm run dev:build'",
+    "dev:frontend": "cd example && vite",
+    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
+    "predev": "convex init && npm run build:codegen",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "preversion": "npm ci && npm run build:clean && npm run test && npm run lint && npm run typecheck",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "version": "(npm whoami || npm login) && vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+  }
+}

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/index.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test, vi } from "vitest";
+import { anyApi, mutationGeneric, type ApiFromModules } from "convex/server";
+import { v } from "convex/values";
+import { ConvexCheckpoints } from "./index.js";
+import { components, initConvexTest } from "./setup.test.js";
+
+const checkpoints = new ConvexCheckpoints<{
+  "post.created": { postId: string };
+}>(components.convexCheckpoints);
+
+checkpoints.on("post.created", async () => {});
+
+export const { listByUser } = checkpoints.api();
+export const submitPostCreated = mutationGeneric({
+  args: {
+    userId: v.string(),
+    postId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await checkpoints.submit(ctx, {
+      name: "post.created",
+      userId: args.userId,
+      payload: { postId: args.postId },
+    });
+  },
+});
+
+const signupHandler = vi.fn();
+const idempotentCheckpoints = new ConvexCheckpoints<{
+  "user.signup": { userId: string };
+}>(components.convexCheckpoints);
+idempotentCheckpoints.on("user.signup", signupHandler);
+export const submitSignup = mutationGeneric({
+  args: {
+    userId: v.string(),
+    idempotencyKey: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    return await idempotentCheckpoints.submit(ctx, {
+      name: "user.signup",
+      userId: args.userId,
+      payload: { userId: args.userId },
+      idempotencyKey: args.idempotencyKey,
+    });
+  },
+});
+
+const testApi = (
+  anyApi as unknown as ApiFromModules<{
+    "index.test": {
+      submitPostCreated: typeof submitPostCreated;
+      submitSignup: typeof submitSignup;
+      listByUser: typeof listByUser;
+    };
+  }>
+)["index.test"];
+
+function assertSubmitTypes(
+  ctx: Parameters<
+    ConvexCheckpoints<{ "post.created": { postId: string } }>["submit"]
+  >[0],
+) {
+  void checkpoints.submit(ctx, {
+    name: "post.created",
+    payload: { postId: "post1" },
+  });
+
+  void checkpoints.submit(ctx, {
+    // @ts-expect-error checkpoint names must exist in the checkpoint registry
+    name: "user.signup",
+    payload: { postId: "post1" },
+  });
+
+  void checkpoints.submit(ctx, {
+    name: "post.created",
+    // @ts-expect-error payload must match the checkpoint name
+    payload: { userId: "user1" },
+  });
+}
+
+void assertSubmitTypes;
+
+describe("client tests", () => {
+  test("exports submit and list functions from checkpoint definitions", async () => {
+    const t = initConvexTest();
+    await t.mutation(testApi.submitPostCreated, {
+      userId: "user1",
+      postId: "post1",
+    });
+
+    const checkpointsForUser = await t.query(testApi.listByUser, {
+      userId: "user1",
+    });
+    expect(checkpointsForUser).toHaveLength(1);
+    expect(checkpointsForUser[0].name).toBe("post.created");
+  });
+
+  test("does not re-run handlers for duplicate idempotency keys", async () => {
+    signupHandler.mockClear();
+    const t = initConvexTest();
+    await t.mutation(testApi.submitSignup, {
+      userId: "user1",
+      idempotencyKey: "signup:user1",
+    });
+    await t.mutation(testApi.submitSignup, {
+      userId: "user1",
+      idempotencyKey: "signup:user1",
+    });
+
+    expect(signupHandler).toHaveBeenCalledOnce();
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,264 @@
+import { httpActionGeneric, httpRouter, queryGeneric } from "convex/server";
+import { v } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+import {
+  ConvexCheckpoints as CheckpointDispatcher,
+  type CheckpointHandler,
+} from "../component/checkpointDispatcher.js";
+
+type CheckpointRegistry = Record<string, unknown>;
+type CheckpointName<TCheckpointRegistry extends CheckpointRegistry> = Extract<
+  keyof TCheckpointRegistry,
+  string
+>;
+
+type BaseSubmitArgs = {
+  userId?: string;
+  idempotencyKey?: string;
+  reachedAt?: number;
+};
+
+type UntypedSubmitArgs = BaseSubmitArgs & {
+  name: string;
+  payload?: unknown;
+};
+
+type SubmitArgs<
+  TCheckpointRegistry extends CheckpointRegistry,
+  TCheckpoint extends CheckpointName<TCheckpointRegistry>,
+> = BaseSubmitArgs & {
+  name: TCheckpoint;
+  payload: TCheckpointRegistry[TCheckpoint];
+};
+
+export class ConvexCheckpoints<
+  TCheckpointRegistry extends CheckpointRegistry,
+> extends CheckpointDispatcher<TCheckpointRegistry> {
+  constructor(private component: ComponentApi) {
+    super();
+  }
+
+  public async submit<TCheckpoint extends CheckpointName<TCheckpointRegistry>>(
+    ctx: Parameters<ConvexCheckpoints<TCheckpointRegistry>["trigger"]>[0],
+    args: SubmitArgs<TCheckpointRegistry, TCheckpoint>,
+  ) {
+    const result = await ctx.runMutation(this.component.lib.record, args);
+    if (result.created) {
+      await this.trigger(ctx, args.name, args.payload);
+    }
+    return result.checkpointId;
+  }
+
+  public api() {
+    return {
+      listRecent: queryGeneric({
+        args: { limit: v.optional(v.number()) },
+        handler: async (ctx, args) => {
+          return await ctx.runQuery(this.component.lib.listRecent, args);
+        },
+      }),
+      listByName: queryGeneric({
+        args: { name: v.string(), limit: v.optional(v.number()) },
+        handler: async (ctx, args) => {
+          return await ctx.runQuery(this.component.lib.listByName, args);
+        },
+      }),
+      listByUser: queryGeneric({
+        args: { userId: v.string(), limit: v.optional(v.number()) },
+        handler: async (ctx, args) => {
+          return await ctx.runQuery(this.component.lib.listByUser, args);
+        },
+      }),
+    };
+  }
+
+  public http(path = "/checkpoints") {
+    const http = httpRouter();
+    http.route({
+      path,
+      method: "POST",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const args = await readSubmitArgsFromBody(request);
+        if (args === null) {
+          return json({ error: "invalid_checkpoint" }, 400);
+        }
+
+        const result = await this.submitFromArgs(ctx, args);
+
+        return json(
+          { checkpointId: result.checkpointId, created: result.created },
+          202,
+        );
+      }),
+    });
+    http.route({
+      path,
+      method: "OPTIONS",
+      handler: httpActionGeneric(async () => corsResponse()),
+    });
+
+    const pathPrefix = path.endsWith("/") ? path : `${path}/`;
+    http.route({
+      pathPrefix,
+      method: "POST",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const checkpointName = readCheckpointNameFromPath(request, pathPrefix);
+        if (checkpointName === null) {
+          return json({ error: "invalid_checkpoint_path" }, 400);
+        }
+
+        const args = await readSubmitArgsFromPath(request, checkpointName);
+        if (args === null) {
+          return json({ error: "invalid_checkpoint" }, 400);
+        }
+
+        const result = await this.submitFromArgs(ctx, args);
+
+        return json(
+          { checkpointId: result.checkpointId, created: result.created },
+          202,
+        );
+      }),
+    });
+    http.route({
+      pathPrefix,
+      method: "OPTIONS",
+      handler: httpActionGeneric(async () => corsResponse()),
+    });
+    return http;
+  }
+
+  private async submitFromArgs(
+    ctx: Parameters<ConvexCheckpoints<TCheckpointRegistry>["trigger"]>[0],
+    args: UntypedSubmitArgs,
+  ) {
+    const result = await ctx.runMutation(this.component.lib.record, args);
+    if (result.created) {
+      await this.trigger(
+        ctx,
+        args.name as CheckpointName<TCheckpointRegistry>,
+        args.payload as TCheckpointRegistry[CheckpointName<TCheckpointRegistry>],
+      );
+    }
+    return result;
+  }
+}
+
+export type { CheckpointHandler };
+
+async function readSubmitArgsFromBody(
+  request: Request,
+): Promise<UntypedSubmitArgs | null> {
+  const checkpoint = await readJsonObject(request);
+  if (checkpoint === null || typeof checkpoint.name !== "string") {
+    return null;
+  }
+  return readSubmitArgs(checkpoint.name, checkpoint, checkpoint.payload);
+}
+
+async function readSubmitArgsFromPath(
+  request: Request,
+  name: string,
+): Promise<UntypedSubmitArgs | null> {
+  const checkpoint = await readJsonObject(request);
+  if (checkpoint === null) {
+    return null;
+  }
+
+  return readSubmitArgs(name, checkpoint, checkpoint);
+}
+
+function readSubmitArgs(
+  name: string,
+  checkpoint: Record<string, unknown>,
+  payload: unknown,
+): UntypedSubmitArgs | null {
+  if (
+    checkpoint.userId !== undefined &&
+    typeof checkpoint.userId !== "string"
+  ) {
+    return null;
+  }
+  if (
+    checkpoint.idempotencyKey !== undefined &&
+    typeof checkpoint.idempotencyKey !== "string"
+  ) {
+    return null;
+  }
+  if (
+    checkpoint.reachedAt !== undefined &&
+    typeof checkpoint.reachedAt !== "number"
+  ) {
+    return null;
+  }
+
+  return {
+    name,
+    userId: checkpoint.userId,
+    payload,
+    idempotencyKey: checkpoint.idempotencyKey,
+    reachedAt: checkpoint.reachedAt,
+  };
+}
+
+async function readJsonObject(
+  request: Request,
+): Promise<Record<string, unknown> | null> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return null;
+  }
+
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return null;
+  }
+
+  return body as Record<string, unknown>;
+}
+
+function readCheckpointNameFromPath(request: Request, pathPrefix: string) {
+  const path = new URL(request.url).pathname;
+  if (!path.startsWith(pathPrefix)) {
+    return null;
+  }
+  const encodedCheckpointName = path.slice(pathPrefix.length);
+  if (
+    encodedCheckpointName.length === 0 ||
+    encodedCheckpointName.includes("/")
+  ) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(encodedCheckpointName);
+  } catch {
+    return null;
+  }
+}
+
+function json(body: unknown, status: number) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      ...corsHeaders(),
+    },
+  });
+}
+
+function corsResponse() {
+  return new Response(null, {
+    status: 204,
+    headers: corsHeaders(),
+  });
+}
+
+function corsHeaders() {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+  };
+}

package/src/client/setup.test.ts

@@ -0,0 +1,26 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+import {
+  defineSchema,
+  type GenericSchema,
+  type SchemaDefinition,
+} from "convex/server";
+import { type ComponentApi } from "../component/_generated/component.js";
+import { componentsGeneric } from "convex/server";
+import { register } from "../test.js";
+
+export function initConvexTest<
+  Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+export const components = componentsGeneric() as unknown as {
+  convexCheckpoints: ComponentApi;
+};
+
+test("setup", () => {});