@convex-dev/workpool 0.1.0

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

@@ -0,0 +1,149 @@
+import { Infer } from "convex/values";
+export declare const completionStatus: import("convex/values").VUnion<"success" | "error" | "canceled" | "timeout", [import("convex/values").VLiteral<"success", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"canceled", "required">, import("convex/values").VLiteral<"timeout", "required">], "required", never>;
+export type CompletionStatus = Infer<typeof completionStatus>;
+/**
+Data flow:
+
+- The mutation `mainLoop` runs periodically and serially.
+- Several tables act as queues, with client-driven mutations enqueueing at high
+  timestamps and `mainLoop` popping at low timestamps:
+  pendingStart, pendingCompletion, and pendingCancelation.
+  - The `enqueue` mutation writes to pendingStart.
+  - The `cancel` mutation writes to pendingCancelation.
+  - The `saveResult` mutation, run as part of scheduled work, writes to pendingCompletion.
+- mainLoop processes the queues:
+  - pendingStart => inProgressWork.
+  - pendingCompletion and pendingCancelation => completedWork.
+  - inProgressWork that finishes uncleanly (timeout or system failure) => completedWork.
+- `mainLoop` schedules itself to run.
+- `enqueue`, `cancel`, and `saveResult` mutations check when `mainLoop` is scheduled to run,
+  and if it's too far in the future, they schedule it to run sooner.
+- `status` query reads from pendingWork and completedWork.
+- `cleanup` mutation deletes old rows from completedWork.
+
+To avoid OCCs, we restrict which mutations can read and write from each table:
+- pools: read by all, written only when static Workpool options change.
+- mainLoop (table): read by all, written mostly by `mainLoop`.
+  If `mainLoop` will not run for a while, mainLoop table is written by `enqueue`, `cancel`, or `saveResult`.
+- pendingWork: `enqueue` inserts at high timestamps, `mainLoop` pops at low timestamps. `status` query does point-reads.
+- pendingCompletion: `saveResult` inserts at high timestamps, `mainLoop` pops at low timestamps.
+- pendingCancelation: `cancel` inserts at high timestamps, `mainLoop` pops at low timestamps.
+- inProgressWork: `mainLoop` inserts, reads all, and deletes.
+- completedWork: `mainLoop` inserts at hight timestamps, `status` query reads, `cleanup` deletes at low timestamps.
+
+ */
+declare const _default: import("convex/server").SchemaDefinition<{
+    pool: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        maxParallelism: number;
+        statusTtl: number;
+        logLevel: "DEBUG" | "INFO" | "WARN" | "ERROR";
+    }, {
+        maxParallelism: import("convex/values").VFloat64<number, "required">;
+        statusTtl: import("convex/values").VFloat64<number, "required">;
+        logLevel: import("convex/values").VUnion<"DEBUG" | "INFO" | "WARN" | "ERROR", [import("convex/values").VLiteral<"DEBUG", "required">, import("convex/values").VLiteral<"INFO", "required">, import("convex/values").VLiteral<"WARN", "required">, import("convex/values").VLiteral<"ERROR", "required">], "required", never>;
+    }, "required", "maxParallelism" | "statusTtl" | "logLevel">, {}, {}, {}>;
+    mainLoop: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        state: {
+            kind: "running";
+        } | {
+            kind: "scheduled";
+            runAtTime: number;
+            fn: import("convex/values").GenericId<"_scheduled_functions">;
+        } | {
+            kind: "idle";
+        };
+    }, {
+        state: import("convex/values").VUnion<{
+            kind: "running";
+        } | {
+            kind: "scheduled";
+            runAtTime: number;
+            fn: import("convex/values").GenericId<"_scheduled_functions">;
+        } | {
+            kind: "idle";
+        }, [import("convex/values").VObject<{
+            kind: "running";
+        }, {
+            kind: import("convex/values").VLiteral<"running", "required">;
+        }, "required", "kind">, import("convex/values").VObject<{
+            kind: "scheduled";
+            runAtTime: number;
+            fn: import("convex/values").GenericId<"_scheduled_functions">;
+        }, {
+            kind: import("convex/values").VLiteral<"scheduled", "required">;
+            runAtTime: import("convex/values").VFloat64<number, "required">;
+            fn: import("convex/values").VId<import("convex/values").GenericId<"_scheduled_functions">, "required">;
+        }, "required", "kind" | "runAtTime" | "fn">, import("convex/values").VObject<{
+            kind: "idle";
+        }, {
+            kind: import("convex/values").VLiteral<"idle", "required">;
+        }, "required", "kind">], "required", "kind" | "runAtTime" | "fn">;
+    }, "required", "state" | "state.kind" | "state.runAtTime" | "state.fn">, {}, {}, {}>;
+    work: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        fnType: "action" | "mutation";
+        fnHandle: string;
+        fnName: string;
+        fnArgs: any;
+    }, {
+        fnType: import("convex/values").VUnion<"action" | "mutation", [import("convex/values").VLiteral<"action", "required">, import("convex/values").VLiteral<"mutation", "required">], "required", never>;
+        fnHandle: import("convex/values").VString<string, "required">;
+        fnName: import("convex/values").VString<string, "required">;
+        fnArgs: import("convex/values").VAny<any, "required", string>;
+    }, "required", "fnType" | "fnHandle" | "fnName" | "fnArgs" | `fnArgs.${string}`>, {}, {}, {}>;
+    pendingStart: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        workId: import("convex/values").GenericId<"work">;
+    }, {
+        workId: import("convex/values").VId<import("convex/values").GenericId<"work">, "required">;
+    }, "required", "workId">, {
+        workId: ["workId", "_creationTime"];
+    }, {}, {}>;
+    pendingCompletion: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        workId: import("convex/values").GenericId<"work">;
+        generation: number;
+        completionStatus: "success" | "error" | "canceled" | "timeout";
+    }, {
+        generation: import("convex/values").VFloat64<number, "required">;
+        completionStatus: import("convex/values").VUnion<"success" | "error" | "canceled" | "timeout", [import("convex/values").VLiteral<"success", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"canceled", "required">, import("convex/values").VLiteral<"timeout", "required">], "required", never>;
+        workId: import("convex/values").VId<import("convex/values").GenericId<"work">, "required">;
+    }, "required", "workId" | "generation" | "completionStatus">, {
+        workId: ["workId", "_creationTime"];
+        generation: ["generation", "_creationTime"];
+    }, {}, {}>;
+    pendingCancelation: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        workId: import("convex/values").GenericId<"work">;
+    }, {
+        workId: import("convex/values").VId<import("convex/values").GenericId<"work">, "required">;
+    }, "required", "workId">, {}, {}, {}>;
+    inProgressWork: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        running: import("convex/values").GenericId<"_scheduled_functions">;
+        workId: import("convex/values").GenericId<"work">;
+        timeoutMs: number | null;
+    }, {
+        running: import("convex/values").VId<import("convex/values").GenericId<"_scheduled_functions">, "required">;
+        timeoutMs: import("convex/values").VUnion<number | null, [import("convex/values").VFloat64<number, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+        workId: import("convex/values").VId<import("convex/values").GenericId<"work">, "required">;
+    }, "required", "running" | "workId" | "timeoutMs">, {
+        workId: ["workId", "_creationTime"];
+    }, {}, {}>;
+    inProgressCount: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        count: number;
+    }, {
+        count: import("convex/values").VFloat64<number, "required">;
+    }, "required", "count">, {}, {}, {}>;
+    completedWork: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        workId: import("convex/values").GenericId<"work">;
+        completionStatus: "success" | "error" | "canceled" | "timeout";
+    }, {
+        completionStatus: import("convex/values").VUnion<"success" | "error" | "canceled" | "timeout", [import("convex/values").VLiteral<"success", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"canceled", "required">, import("convex/values").VLiteral<"timeout", "required">], "required", never>;
+        workId: import("convex/values").VId<import("convex/values").GenericId<"work">, "required">;
+    }, "required", "workId" | "completionStatus">, {
+        workId: ["workId", "_creationTime"];
+    }, {}, {}>;
+    completionGeneration: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        generation: number;
+    }, {
+        generation: import("convex/values").VFloat64<number, "required">;
+    }, "required", "generation">, {}, {}, {}>;
+}, 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":"AACA,OAAO,EAAE,KAAK,EAAK,MAAM,eAAe,CAAC;AAGzC,eAAO,MAAM,gBAAgB,sUAK5B,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,wBA0DG"}

package/dist/esm/component/schema.js

@@ -0,0 +1,85 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { logLevel } from "./logging";
+export const completionStatus = v.union(v.literal("success"), v.literal("error"), v.literal("canceled"), v.literal("timeout"));
+/**
+Data flow:
+
+- The mutation `mainLoop` runs periodically and serially.
+- Several tables act as queues, with client-driven mutations enqueueing at high
+  timestamps and `mainLoop` popping at low timestamps:
+  pendingStart, pendingCompletion, and pendingCancelation.
+  - The `enqueue` mutation writes to pendingStart.
+  - The `cancel` mutation writes to pendingCancelation.
+  - The `saveResult` mutation, run as part of scheduled work, writes to pendingCompletion.
+- mainLoop processes the queues:
+  - pendingStart => inProgressWork.
+  - pendingCompletion and pendingCancelation => completedWork.
+  - inProgressWork that finishes uncleanly (timeout or system failure) => completedWork.
+- `mainLoop` schedules itself to run.
+- `enqueue`, `cancel`, and `saveResult` mutations check when `mainLoop` is scheduled to run,
+  and if it's too far in the future, they schedule it to run sooner.
+- `status` query reads from pendingWork and completedWork.
+- `cleanup` mutation deletes old rows from completedWork.
+
+To avoid OCCs, we restrict which mutations can read and write from each table:
+- pools: read by all, written only when static Workpool options change.
+- mainLoop (table): read by all, written mostly by `mainLoop`.
+  If `mainLoop` will not run for a while, mainLoop table is written by `enqueue`, `cancel`, or `saveResult`.
+- pendingWork: `enqueue` inserts at high timestamps, `mainLoop` pops at low timestamps. `status` query does point-reads.
+- pendingCompletion: `saveResult` inserts at high timestamps, `mainLoop` pops at low timestamps.
+- pendingCancelation: `cancel` inserts at high timestamps, `mainLoop` pops at low timestamps.
+- inProgressWork: `mainLoop` inserts, reads all, and deletes.
+- completedWork: `mainLoop` inserts at hight timestamps, `status` query reads, `cleanup` deletes at low timestamps.
+
+ */
+export default defineSchema({
+    // Statically configured, singleton.
+    pool: defineTable({
+        maxParallelism: v.number(),
+        statusTtl: v.number(),
+        logLevel,
+    }),
+    mainLoop: defineTable({
+        state: v.union(v.object({ kind: v.literal("running") }), v.object({
+            kind: v.literal("scheduled"),
+            runAtTime: v.number(),
+            fn: v.id("_scheduled_functions"),
+        }), v.object({ kind: v.literal("idle") })),
+    }),
+    work: defineTable({
+        fnType: v.union(v.literal("action"), v.literal("mutation")),
+        fnHandle: v.string(),
+        fnName: v.string(),
+        fnArgs: v.any(),
+    }),
+    pendingStart: defineTable({
+        workId: v.id("work"),
+    }).index("workId", ["workId"]),
+    pendingCompletion: defineTable({
+        generation: v.number(),
+        completionStatus,
+        workId: v.id("work"),
+    })
+        .index("workId", ["workId"])
+        .index("generation", ["generation"]),
+    pendingCancelation: defineTable({
+        workId: v.id("work"),
+    }),
+    inProgressWork: defineTable({
+        running: v.id("_scheduled_functions"),
+        timeoutMs: v.union(v.number(), v.null()),
+        workId: v.id("work"),
+    }).index("workId", ["workId"]),
+    inProgressCount: defineTable({
+        count: v.number(),
+    }),
+    completedWork: defineTable({
+        completionStatus,
+        workId: v.id("work"),
+    }).index("workId", ["workId"]),
+    completionGeneration: defineTable({
+        generation: 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":"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"}

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

@@ -0,0 +1,37 @@
+import { Doc } from "./_generated/dataModel";
+/**
+ * Record stats about work execution. Intended to be queried by Axiom or Datadog.
+ */
+/**
+ * Sample axiom dashboard query:
+
+workpool
+| extend parsed_message = iff(
+    isnotnull(parse_json(trim("'", tostring(["data.message"])))),
+    parse_json(trim("'", tostring(["data.message"]))),
+    parse_json('{}')
+)
+| extend lagSinceEnqueued = parsed_message["lagSinceEnqueued"]
+| extend fnName = parsed_message["fnName"]
+| summarize avg(todouble(lagSinceEnqueued)) by bin_auto(_time), tostring(fnName)
+
+ */
+export declare function recordStarted(work: Doc<"work">): string;
+export declare function recordCompleted(work: Doc<"work">, status: "success" | "error" | "canceled" | "timeout"): string;
+/**
+ * Warning: this should not be used from a mutation, as it will cause conflicts.
+ * Use this to debug or diagnose your queue length when it's backed up.
+ */
+export declare const queueLength: import("convex/server").RegisteredQuery<"internal", {}, Promise<any>>;
+/**
+ * Warning: this should not be used from a mutation, as it will cause conflicts.
+ * Use this while developing to see the state of the queue.
+ */
+export declare const debugCounts: import("convex/server").RegisteredQuery<"internal", {}, Promise<{
+    pendingStart: any;
+    inProgressWork: any;
+    pendingCompletion: any;
+    pendingCancelation: any;
+    active: number;
+}>>;
+//# sourceMappingURL=stats.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/component/stats.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAG7C;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CASvD;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EACjB,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GACnD,MAAM,CASR;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,uEAOtB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;GAwBtB,CAAC"}

package/dist/esm/component/stats.js

@@ -0,0 +1,75 @@
+import { v } from "convex/values";
+import { internalQuery } from "./_generated/server";
+/**
+ * Record stats about work execution. Intended to be queried by Axiom or Datadog.
+ */
+/**
+ * Sample axiom dashboard query:
+
+workpool
+| extend parsed_message = iff(
+    isnotnull(parse_json(trim("'", tostring(["data.message"])))),
+    parse_json(trim("'", tostring(["data.message"]))),
+    parse_json('{}')
+)
+| extend lagSinceEnqueued = parsed_message["lagSinceEnqueued"]
+| extend fnName = parsed_message["fnName"]
+| summarize avg(todouble(lagSinceEnqueued)) by bin_auto(_time), tostring(fnName)
+
+ */
+export function recordStarted(work) {
+    return JSON.stringify({
+        workId: work._id,
+        event: "started",
+        fnName: work.fnName,
+        enqueuedAt: work._creationTime,
+        startedAt: Date.now(),
+        lagSinceEnqueued: Date.now() - work._creationTime,
+    });
+}
+export function recordCompleted(work, status) {
+    return JSON.stringify({
+        workId: work._id,
+        event: "completed",
+        fnName: work.fnName,
+        completedAt: Date.now(),
+        status,
+        lagSinceEnqueued: Date.now() - work._creationTime,
+    });
+}
+/**
+ * Warning: this should not be used from a mutation, as it will cause conflicts.
+ * Use this to debug or diagnose your queue length when it's backed up.
+ */
+export const queueLength = internalQuery({
+    args: {},
+    returns: v.number(),
+    handler: async (ctx) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return ctx.db.query("pendingStart").count();
+    },
+});
+/**
+ * Warning: this should not be used from a mutation, as it will cause conflicts.
+ * Use this while developing to see the state of the queue.
+ */
+export const debugCounts = internalQuery({
+    args: {},
+    returns: v.any(),
+    handler: async (ctx) => {
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        const inProgressWork = await ctx.db.query("inProgressWork").count();
+        const pendingStart = await ctx.db.query("pendingStart").count();
+        const pendingCompletion = await ctx.db.query("pendingCompletion").count();
+        const pendingCancelation = await ctx.db.query("pendingCancelation").count();
+        return {
+            pendingStart,
+            inProgressWork,
+            pendingCompletion,
+            pendingCancelation,
+            active: inProgressWork - pendingCompletion - pendingCancelation,
+        };
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+    },
+});
+//# sourceMappingURL=stats.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/component/stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AAEH,MAAM,UAAU,aAAa,CAAC,IAAiB;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,EAAE,IAAI,CAAC,GAAG;QAChB,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,aAAa;QAC9B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa;KAClD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,IAAiB,EACjB,MAAoD;IAEpD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,EAAE,IAAI,CAAC,GAAG;QAChB,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;QACvB,MAAM;QACN,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa;KAClD,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;IACvC,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACrB,8DAA8D;QAC9D,OAAQ,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,CAAS,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC;CACF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;IACvC,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE;IAChB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACrB,uDAAuD;QACvD,MAAM,cAAc,GAAG,MACrB,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAC9B,CAAC,KAAK,EAAE,CAAC;QACV,MAAM,YAAY,GAAG,MAAO,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,CAAS,CAAC,KAAK,EAAE,CAAC;QACzE,MAAM,iBAAiB,GAAG,MACxB,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,mBAAmB,CACjC,CAAC,KAAK,EAAE,CAAC;QACV,MAAM,kBAAkB,GAAG,MACzB,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAClC,CAAC,KAAK,EAAE,CAAC;QACV,OAAO;YACL,YAAY;YACZ,cAAc;YACd,iBAAiB;YACjB,kBAAkB;YAClB,MAAM,EAAE,cAAc,GAAG,iBAAiB,GAAG,kBAAkB;SAChE,CAAC;QACF,sDAAsD;IACxD,CAAC;CACF,CAAC,CAAC"}

package/dist/esm/package.json

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

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@convex-dev/workpool",
+  "description": "A Convex component for managing async work.",
+  "repository": "github:get-convex/workpool",
+  "homepage": "https://github.com/get-convex/workpool#readme",
+  "bugs": {
+    "email": "support@convex.dev",
+    "url": "https://github.com/get-convex/workpool/issues"
+  },
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "queue",
+    "pool",
+    "component",
+    "async",
+    "work"
+  ],
+  "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/commonjs/package.json",
+    "dev": "cd example; npm run dev",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepack": "node node10stubs.mjs",
+    "postpack": "node node10stubs.mjs --cleanup",
+    "test": "vitest run",
+    "lint": "tsc --noEmit && eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text"
+  },
+  "files": [
+    "dist",
+    "src",
+    "react"
+  ],
+  "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": {
+      "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"
+      }
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.17.0 || ^1.18.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.1",
+    "@types/node": "^18.17.0",
+    "convex-test": "^0.0.35",
+    "eslint": "^9.9.1",
+    "globals": "^15.9.0",
+    "prettier": "3.2.5",
+    "typescript": "~5.0.3",
+    "typescript-eslint": "^8.4.0",
+    "vitest": "^2.1.4"
+  },
+  "main": "./dist/commonjs/client/index.js",
+  "types": "./dist/commonjs/client/index.d.ts",
+  "module": "./dist/esm/client/index.js",
+  "dependencies": {
+    "@convex-dev/crons": "^0.1.5"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,121 @@
+import {
+  createFunctionHandle,
+  DefaultFunctionArgs,
+  Expand,
+  FunctionReference,
+  FunctionVisibility,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  getFunctionName,
+} from "convex/server";
+import { GenericId } from "convex/values";
+import { api } from "../component/_generated/api";
+import { LogLevel } from "../component/logging";
+import { completionStatus, type CompletionStatus } from "../component/schema";
+export { completionStatus, type CompletionStatus };
+
+export type WorkId = string;
+
+export class Workpool {
+  constructor(
+    private component: UseApi<typeof api>,
+    private options: {
+      /** How many actions/mutations can be running at once within this pool.
+       * Min 1, Max 300.
+       */
+      maxParallelism: number;
+      /** How much to log.
+       * Default WARN.
+       * With INFO, you can see events for started and completed work, which can
+       * be parsed.
+       * With DEBUG, you can see timers and internal events for work being
+       * scheduled.
+       */
+      logLevel?: LogLevel;
+      /** How long to keep completed work in the database, for access by `status`.
+       * Default 1 day.
+       */
+      statusTtl?: number;
+    }
+  ) {}
+  async enqueueAction<Args extends DefaultFunctionArgs, ReturnType>(
+    ctx: RunMutationCtx,
+    fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>,
+    fnArgs: Args
+  ): Promise<WorkId> {
+    const fnHandle = await createFunctionHandle(fn);
+    const id = await ctx.runMutation(this.component.lib.enqueue, {
+      fnHandle,
+      fnName: getFunctionName(fn),
+      fnArgs,
+      fnType: "action",
+      options: this.options,
+    });
+    return id as WorkId;
+  }
+  async enqueueMutation<Args extends DefaultFunctionArgs, ReturnType>(
+    ctx: RunMutationCtx,
+    fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>,
+    fnArgs: Args
+  ): Promise<WorkId> {
+    const fnHandle = await createFunctionHandle(fn);
+    const id = await ctx.runMutation(this.component.lib.enqueue, {
+      fnHandle,
+      fnName: getFunctionName(fn),
+      fnArgs,
+      fnType: "mutation",
+      options: this.options,
+    });
+    return id as WorkId;
+  }
+  async cancel(ctx: RunMutationCtx, id: WorkId): Promise<void> {
+    await ctx.runMutation(this.component.lib.cancel, { id });
+  }
+  async status(
+    ctx: RunQueryCtx,
+    id: WorkId
+  ): Promise<
+    | { kind: "pending" }
+    | { kind: "inProgress" }
+    | { kind: "completed"; completionStatus: CompletionStatus }
+  > {
+    return await ctx.runQuery(this.component.lib.status, { id });
+  }
+}
+
+/* Type utils follow */
+
+type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+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]>;
+}>;