@convex-dev/crons 0.0.1

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

@@ -0,0 +1,98 @@
+import { FunctionHandle } from "convex/server";
+export type Schedule = {
+    kind: "cron";
+    cronspec: string;
+} | {
+    kind: "interval";
+    ms: number;
+};
+export type CronInfo = {
+    id: string;
+    name?: string;
+    functionHandle: FunctionHandle<"mutation" | "action">;
+    args: Record<string, unknown>;
+    schedule: Schedule;
+};
+/**
+ * Schedule a mutation or action to run on a cron schedule or interval.
+ *
+ * @param name - Optional unique name for the job. Will throw if a name is
+ *        provided and a job with the same name already exists.
+ * @param schedule - Either a cron specification string or an interval in
+ *        milliseconds. For intervals, ms must be >= 1000.
+ * @param functionHandle - A {@link FunctionHandle} string for the function to
+ *        schedule.
+ * @param args - The arguments to the function.
+ * @returns The ID of the scheduled job.
+ */
+export declare const register: import("convex/server").RegisteredMutation<"public", {
+    name?: string | undefined;
+    functionHandle: string;
+    args: Record<string, any>;
+    schedule: {
+        kind: "interval";
+        ms: number;
+    } | {
+        kind: "cron";
+        cronspec: string;
+    };
+}, Promise<import("convex/values").GenericId<"crons">>>;
+/**
+ * List all user space cron jobs.
+ *
+ * @returns List of `cron` table rows.
+ */
+export declare const list: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+    functionHandle: string;
+    args: Record<string, any>;
+    schedule: {
+        kind: "interval";
+        ms: number;
+    } | {
+        kind: "cron";
+        cronspec: string;
+    };
+    name?: string | undefined;
+    id: import("convex/values").GenericId<"crons">;
+}[]>>;
+/**
+ * Get an existing cron job by id or name.
+ *
+ * @param identifier - Either the ID or name of the cron job.
+ * @returns Cron job document or null if not found.
+ */
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    identifier: {
+        id: import("convex/values").GenericId<"crons">;
+    } | {
+        name: string;
+    };
+}, Promise<{
+    functionHandle: string;
+    args: Record<string, any>;
+    schedule: {
+        kind: "interval";
+        ms: number;
+    } | {
+        kind: "cron";
+        cronspec: string;
+    };
+    name?: string | undefined;
+    id: import("convex/values").GenericId<"crons">;
+} | null>>;
+/**
+ * Delete and deschedule a cron job by id or name.
+ *
+ * @param identifier - Either the ID or name of the cron job.
+ */
+export declare const del: import("convex/server").RegisteredMutation<"public", {
+    identifier: {
+        id: import("convex/values").GenericId<"crons">;
+    } | {
+        name: string;
+    };
+}, Promise<void>>;
+export declare const rescheduler: import("convex/server").RegisteredMutation<"internal", {
+    id: import("convex/values").GenericId<"crons">;
+}, Promise<void>>;
+//# sourceMappingURL=public.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/component/public.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAa/C,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAGrC,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,cAAc,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC;IACtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AASF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;uDAiCnB,CAAC;AAyCH;;;;GAIG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;KAaf,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;UAyBd,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,GAAG;;;;;;iBAoCd,CAAC;AASH,eAAO,MAAM,WAAW;;iBA4DtB,CAAC"}

package/dist/esm/component/public.js

@@ -0,0 +1,225 @@
+// Implementation of crons in user space.
+//
+// See ../client/index.ts for the public API.
+import { v } from "convex/values";
+import { mutation, query, internalMutation, } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import parser from "cron-parser";
+import schema from "./schema.js";
+const scheduleValidator = schema.tables.crons.validator.fields.schedule;
+const cronInfoValidator = v.object({
+    id: v.id("crons"),
+    name: v.optional(v.string()),
+    functionHandle: v.string(),
+    args: v.record(v.string(), v.any()),
+    schedule: scheduleValidator,
+});
+/**
+ * Schedule a mutation or action to run on a cron schedule or interval.
+ *
+ * @param name - Optional unique name for the job. Will throw if a name is
+ *        provided and a job with the same name already exists.
+ * @param schedule - Either a cron specification string or an interval in
+ *        milliseconds. For intervals, ms must be >= 1000.
+ * @param functionHandle - A {@link FunctionHandle} string for the function to
+ *        schedule.
+ * @param args - The arguments to the function.
+ * @returns The ID of the scheduled job.
+ */
+export const register = mutation({
+    args: {
+        name: v.optional(v.string()),
+        schedule: scheduleValidator,
+        functionHandle: v.string(),
+        args: v.record(v.string(), v.any()),
+    },
+    returns: v.id("crons"),
+    handler: async (ctx, { name, schedule, functionHandle, args }) => {
+        if (name &&
+            (await ctx.db
+                .query("crons")
+                .withIndex("name", (q) => q.eq("name", name))
+                .unique())) {
+            throw new Error(`Cron with name "${name}" already exists`);
+        }
+        validateSchedule(schedule);
+        const id = await ctx.db.insert("crons", {
+            functionHandle,
+            args,
+            name,
+            schedule,
+        });
+        console.log(`Scheduling cron "${name}" (${id}) on schedule ${JSON.stringify(schedule)}`);
+        await scheduleNextRun(ctx, id, new Date(), schedule);
+        return id;
+    },
+});
+function validateSchedule(schedule) {
+    if (schedule.kind === "interval" && schedule.ms < 1000) {
+        throw new Error("Interval must be >= 1000ms");
+    }
+    if (schedule.kind === "cron") {
+        try {
+            parser.parseExpression(schedule.cronspec);
+        }
+        catch {
+            throw new Error(`Invalid cronspec: "${schedule.cronspec}"`);
+        }
+    }
+}
+async function scheduleNextRun(ctx, id, lastScheduled, schedule) {
+    const nextRun = calculateNextRun(lastScheduled, schedule);
+    const schedulerJobId = await ctx.scheduler.runAt(nextRun, internal.public.rescheduler, { id });
+    await ctx.db.patch(id, { schedulerJobId });
+}
+function calculateNextRun(lastScheduled, schedule) {
+    if (schedule.kind === "interval") {
+        return new Date(lastScheduled.getTime() + schedule.ms);
+    }
+    else {
+        const cron = parser.parseExpression(schedule.cronspec, {
+            currentDate: lastScheduled,
+        });
+        return cron.next().toDate();
+    }
+}
+/**
+ * List all user space cron jobs.
+ *
+ * @returns List of `cron` table rows.
+ */
+export const list = query({
+    args: {},
+    returns: v.array(cronInfoValidator),
+    handler: async (ctx) => {
+        const crons = await ctx.db.query("crons").collect();
+        return crons.map((cron) => ({
+            id: cron._id,
+            ...(cron.name && { name: cron.name }),
+            functionHandle: cron.functionHandle,
+            args: cron.args,
+            schedule: cron.schedule,
+        }));
+    },
+});
+/**
+ * Get an existing cron job by id or name.
+ *
+ * @param identifier - Either the ID or name of the cron job.
+ * @returns Cron job document or null if not found.
+ */
+export const get = query({
+    args: {
+        identifier: v.union(v.object({ id: v.id("crons") }), v.object({ name: v.string() })),
+    },
+    returns: v.union(cronInfoValidator, v.null()),
+    handler: async (ctx, { identifier }) => {
+        const cron = "id" in identifier
+            ? await ctx.db.get(identifier.id)
+            : await ctx.db
+                .query("crons")
+                .withIndex("name", (q) => q.eq("name", identifier.name))
+                .unique();
+        if (!cron)
+            return null;
+        return {
+            id: cron._id,
+            ...(cron.name && { name: cron.name }),
+            functionHandle: cron.functionHandle,
+            args: cron.args,
+            schedule: cron.schedule,
+        };
+    },
+});
+/**
+ * Delete and deschedule a cron job by id or name.
+ *
+ * @param identifier - Either the ID or name of the cron job.
+ */
+export const del = mutation({
+    args: {
+        identifier: v.union(v.object({ id: v.id("crons") }), v.object({ name: v.string() })),
+    },
+    returns: v.null(),
+    handler: async (ctx, { identifier }) => {
+        let cron;
+        if ("id" in identifier) {
+            cron = await ctx.db.get(identifier.id);
+            if (!cron) {
+                throw new Error(`Cron ${identifier.id} not found`);
+            }
+        }
+        else {
+            cron = await ctx.db
+                .query("crons")
+                .withIndex("name", (q) => q.eq("name", identifier.name))
+                .unique();
+            if (!cron) {
+                throw new Error(`Cron "${identifier.name}" not found`);
+            }
+        }
+        if (!cron.schedulerJobId) {
+            throw new Error(`Cron ${cron._id} not scheduled`);
+        }
+        console.log(`Canceling scheduler job ${cron.schedulerJobId}`);
+        await ctx.scheduler.cancel(cron.schedulerJobId);
+        if (cron.executionJobId) {
+            console.log(`Canceling execution job ${cron.executionJobId}`);
+            await ctx.scheduler.cancel(cron.executionJobId);
+        }
+        console.log(`Deleting cron ${cron._id}`);
+        await ctx.db.delete(cron._id);
+    },
+});
+// Continue rescheduling a cron job.
+//
+// This is the main worker function that does the scheduling but also schedules
+// the target function so that it runs in a different context. As a result this
+// function probably *shouldn't* fail since it isn't doing much, but under heavy
+// OCC contention it's possible it may eventually fail. In this case the cron
+// will be lost and we'll need a janitor job to recover it.
+export const rescheduler = internalMutation({
+    args: {
+        id: v.id("crons"),
+    },
+    returns: v.null(),
+    handler: async (ctx, { id }) => {
+        // Cron job is the logical concept we're rescheduling repeatedly.
+        const cronJob = await ctx.db.get(id);
+        if (!cronJob) {
+            throw Error(`Cron ${id} not found`);
+        }
+        if (!cronJob.schedulerJobId) {
+            throw Error(`Cron ${id} not scheduled`);
+        }
+        // Scheduler job is the job that's running right now, that we use to trigger
+        // repeated executions.
+        const schedulerJob = await ctx.db.system.get(cronJob.schedulerJobId);
+        if (!schedulerJob) {
+            throw Error(`Scheduler job ${cronJob.schedulerJobId} not found`);
+        }
+        if (schedulerJob.state.kind !== "pending" &&
+            schedulerJob.state.kind !== "inProgress") {
+            throw Error(`We are running in job ${schedulerJob._id} but state is ${schedulerJob.state.kind}`);
+        }
+        // Execution job is the previous job used to actually do the work of the cron.
+        let stillRunning = false;
+        if (cronJob.executionJobId) {
+            const executionJob = await ctx.db.system.get(cronJob.executionJobId);
+            if (executionJob &&
+                (executionJob.state.kind === "pending" ||
+                    executionJob.state.kind === "inProgress")) {
+                stillRunning = true;
+            }
+        }
+        if (stillRunning) {
+            console.log(`Cron ${cronJob._id} still running, skipping this run.`);
+        }
+        else {
+            console.log(`Running cron ${cronJob._id}.`);
+            await ctx.scheduler.runAfter(0, cronJob.functionHandle, cronJob.args);
+        }
+        await scheduleNextRun(ctx, id, new Date(schedulerJob.scheduledTime), cronJob.schedule);
+    },
+});
+//# sourceMappingURL=public.js.map

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

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

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

@@ -0,0 +1,45 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    crons: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        name?: string | undefined;
+        schedulerJobId?: import("convex/values").GenericId<"_scheduled_functions"> | undefined;
+        executionJobId?: import("convex/values").GenericId<"_scheduled_functions"> | undefined;
+        functionHandle: string;
+        args: Record<string, any>;
+        schedule: {
+            kind: "interval";
+            ms: number;
+        } | {
+            kind: "cron";
+            cronspec: string;
+        };
+    }, {
+        name: import("convex/values").VString<string | undefined, "optional">;
+        functionHandle: import("convex/values").VString<string, "required">;
+        args: import("convex/values").VRecord<Record<string, any>, import("convex/values").VString<string, "required">, import("convex/values").VAny<any, "required", string>, "required", string>;
+        schedule: import("convex/values").VUnion<{
+            kind: "interval";
+            ms: number;
+        } | {
+            kind: "cron";
+            cronspec: string;
+        }, [import("convex/values").VObject<{
+            kind: "interval";
+            ms: number;
+        }, {
+            kind: import("convex/values").VLiteral<"interval", "required">;
+            ms: import("convex/values").VFloat64<number, "required">;
+        }, "required", "kind" | "ms">, import("convex/values").VObject<{
+            kind: "cron";
+            cronspec: string;
+        }, {
+            kind: import("convex/values").VLiteral<"cron", "required">;
+            cronspec: import("convex/values").VString<string, "required">;
+        }, "required", "kind" | "cronspec">], "required", "kind" | "ms" | "cronspec">;
+        schedulerJobId: import("convex/values").VId<import("convex/values").GenericId<"_scheduled_functions"> | undefined, "optional">;
+        executionJobId: import("convex/values").VId<import("convex/values").GenericId<"_scheduled_functions"> | undefined, "optional">;
+    }, "required", "name" | "functionHandle" | "args" | "schedule" | "schedulerJobId" | "executionJobId" | `args.${string}` | "schedule.kind" | "schedule.ms" | "schedule.cronspec">, {
+        name: ["name", "_creationTime"];
+    }, {}, {}>;
+}, 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,wBAmBG"}

package/dist/esm/component/schema.js

@@ -0,0 +1,20 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    // User space crons.
+    crons: defineTable({
+        name: v.optional(v.string()),
+        functionHandle: v.string(),
+        args: v.record(v.string(), v.any()),
+        schedule: v.union(v.object({
+            kind: v.literal("interval"),
+            ms: v.float64(), // milliseconds
+        }), v.object({
+            kind: v.literal("cron"),
+            cronspec: v.string(), // "* * * * *"
+        })),
+        schedulerJobId: v.optional(v.id("_scheduled_functions")),
+        executionJobId: v.optional(v.id("_scheduled_functions")), // async job to run the function
+    }).index("name", ["name"]),
+});
+//# 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,oBAAoB;IACpB,KAAK,EAAE,WAAW,CAAC;QACjB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;QAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;QACnC,QAAQ,EAAE,CAAC,CAAC,KAAK,CACf,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;YAC3B,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,eAAe;SACjC,CAAC,EACF,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;YACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,cAAc;SACrC,CAAC,CACH;QACD,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,sBAAsB,CAAC,CAAC;QACxD,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,sBAAsB,CAAC,CAAC,EAAE,gCAAgC;KAC3F,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;CAC3B,CAAC,CAAC"}

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

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

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

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

package/dist/esm/frontend/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/frontend/index.js.map

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

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@convex-dev/crons",
+  "version": "0.0.1",
+  "description": "Convex component for scheduling periodic jobs.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc --project ./esm.json && echo '{\\n  \"type\": \"module\"\\n}' > dist/esm/package.json",
+    "build:cjs": "tsc --project ./commonjs.json && echo '{\\n  \"type\": \"commonjs\"\\n}' > dist/esm/package.json",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/esm/client/index.d.ts",
+        "default": "./dist/esm/client/index.js"
+      },
+      "require": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/commonjs/client/index.d.ts",
+        "default": "./dist/commonjs/client/index.js"
+      }
+    },
+    "./convex.config.js": {
+      "import": {
+        "@convex-dev/component-source": "./src/component/convex.config.ts",
+        "types": "./dist/esm/component/convex.config.d.ts",
+        "default": "./dist/esm/component/convex.config.js"
+      }
+    }
+  },
+  "dependencies": {
+    "convex": "^1.16.1",
+    "cron-parser": "^4.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.1",
+    "@types/node": "^18.17.0",
+    "eslint": "^9.9.1",
+    "globals": "^15.9.0",
+    "prettier": "3.2.5",
+    "typescript": "~5.0.3",
+    "typescript-eslint": "^8.4.0"
+  },
+  "main": "./dist/commonjs/client/index.js",
+  "types": "./dist/commonjs/client/index.d.ts",
+  "module": "./dist/esm/client/index.js"
+}

package/src/client/index.ts

@@ -0,0 +1,128 @@
+// Client side implementation of the Crons component.
+
+import {
+  createFunctionHandle,
+  FunctionArgs,
+  FunctionHandle,
+  SchedulableFunctionReference,
+} from "convex/server";
+import { api } from "../component/_generated/api.js";
+import { CronInfo, Schedule } from "../component/public.js";
+import { RunMutationCtx, RunQueryCtx, UseApi } from "./utils.js";
+
+export type { CronInfo };
+
+// TODO (james): should we add helpers for minutely, hourly, etc schedules?
+
+// Implementation of crons in user space.
+//
+// Supports intervals in ms as well as cron schedules with the same format as
+// the unix `cron` command:
+//
+//  *  *  *  *  *  *
+//  ┬  ┬  ┬  ┬  ┬  ┬
+//  │  │  │  │  │  |
+//  │  │  │  │  │  └── day of week (0 - 7, 1L - 7L) (0 or 7 is Sun)
+//  │  │  │  │  └───── month (1 - 12)
+//  │  │  │  └──────── day of month (1 - 31, L)
+//  │  │  └─────────── hour (0 - 23)
+//  │  └────────────── minute (0 - 59)
+//  └───────────────── second (0 - 59, optional)
+//
+// Crons can be registered at runtime via the `register` function.
+//
+// If you'd like to statically define cronjobs like in the built-in `crons.ts`
+// Convex feature you can do so via an init script that idempotently registers a
+// cron with a given name. e.g., in an `init.ts` file that gets run on every
+// deploy via `convex dev --run init`:
+//
+// const crons = new Crons(components.crons);
+// ...
+// if ((await crons.get(ctx, { name: "daily" })) === null) {
+//   await crons.register(
+//     ctx,
+//     { kind: "cron", cronspec: "0 0 * * *" },
+//     internal.example.logStuff,
+//     { message: "daily cron" },
+//     "daily"
+//   );
+// }
+export class Crons {
+  constructor(private component: UseApi<typeof api>) {}
+
+  /**
+   * Schedule a mutation or action to run on a cron schedule or interval.
+   *
+   * @param ctx - The mutation context from the calling Convex mutation.
+   * @param schedule - Either a cron specification string or an interval in
+   *        milliseconds. For intervals, ms must be >= 1000.
+   * @param func - A function reference to the mutation or action to schedule.
+   * @param args - The arguments to the function.
+   * @param name - Optional unique name for the cron. Will throw if a name is
+   *        provided and a cron with the same name already exists.
+   * @returns A string identifier for the cron job.
+   */
+  async register<F extends SchedulableFunctionReference>(
+    ctx: RunMutationCtx,
+    schedule: Schedule,
+    func: F,
+    args: FunctionArgs<F>,
+    name?: string
+  ): Promise<string> {
+    return ctx.runMutation(this.component.public.register, {
+      name,
+      schedule,
+      functionHandle: await createFunctionHandle(func),
+      args,
+    });
+  }
+
+  /**
+   * List all user space cron jobs.
+   *
+   * @returns List of `cron` table rows.
+   */
+  async list(ctx: RunQueryCtx): Promise<CronInfo[]> {
+    const crons = await ctx.runQuery(this.component.public.list, {});
+    return crons.map((cron) => ({
+      ...cron,
+      functionHandle: cron.functionHandle as FunctionHandle<
+        "mutation" | "action"
+      >,
+    }));
+  }
+
+  /**
+   * Get an existing cron job by id or name.
+   *
+   * @param identifier - Either the ID or name of the cron job.
+   * @returns Cron job document.
+   */
+  async get(
+    ctx: RunQueryCtx,
+    identifier: { id: string } | { name: string }
+  ): Promise<CronInfo | null> {
+    const cron = await ctx.runQuery(this.component.public.get, { identifier });
+    if (cron === null) {
+      return null;
+    }
+    return {
+      ...cron,
+      functionHandle: cron.functionHandle as FunctionHandle<
+        "mutation" | "action"
+      >,
+    };
+  }
+
+  /**
+   * Delete and deschedule a cron job by id or name.
+   *
+   * @param identifier - Either the ID or name of the cron job.
+   */
+  async del(
+    ctx: RunMutationCtx,
+    identifier: { id: string } | { name: string }
+  ): Promise<null> {
+    return ctx.runMutation(this.component.public.del, { identifier });
+  }
+}

package/src/client/utils.ts

@@ -0,0 +1,44 @@
+// Type utilities for component clients.
+
+import {
+  Expand,
+  FunctionReference,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import { GenericId } from "convex/values";
+
+export type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+export type RunMutationCtx = {
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+};
+
+export type OpaqueIds<T> =
+  T extends GenericId<infer _T>
+    ? string
+    : T extends (infer U)[]
+      ? OpaqueIds<U>[]
+      : T extends object
+        ? { [K in keyof T]: OpaqueIds<T[K]> }
+        : T;
+
+export type UseApi<API> = Expand<{
+  [mod in keyof API]: API[mod] extends FunctionReference<
+    infer FType,
+    "public",
+    infer FArgs,
+    infer FReturnType,
+    infer FComponentPath
+  >
+    ? FunctionReference<
+        FType,
+        "internal",
+        OpaqueIds<FArgs>,
+        OpaqueIds<FReturnType>,
+        FComponentPath
+      >
+    : UseApi<API[mod]>;
+}>;