@convex-dev/workpool 0.1.0

package/dist/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/package.json

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

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

@@ -0,0 +1,53 @@
+import { DefaultFunctionArgs, Expand, FunctionReference, FunctionVisibility, GenericDataModel, GenericMutationCtx, GenericQueryCtx } 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 declare class Workpool {
+    private component;
+    private options;
+    constructor(component: UseApi<typeof api>, 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;
+    });
+    enqueueAction<Args extends DefaultFunctionArgs, ReturnType>(ctx: RunMutationCtx, fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>, fnArgs: Args): Promise<WorkId>;
+    enqueueMutation<Args extends DefaultFunctionArgs, ReturnType>(ctx: RunMutationCtx, fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>, fnArgs: Args): Promise<WorkId>;
+    cancel(ctx: RunMutationCtx, id: WorkId): Promise<void>;
+    status(ctx: RunQueryCtx, id: WorkId): Promise<{
+        kind: "pending";
+    } | {
+        kind: "inProgress";
+    } | {
+        kind: "completed";
+        completionStatus: CompletionStatus;
+    }>;
+}
+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]>;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/esm/client/index.js

@@ -0,0 +1,40 @@
+import { createFunctionHandle, getFunctionName, } from "convex/server";
+import { completionStatus } from "../component/schema";
+export { completionStatus };
+export class Workpool {
+    component;
+    options;
+    constructor(component, options) {
+        this.component = component;
+        this.options = options;
+    }
+    async enqueueAction(ctx, fn, fnArgs) {
+        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;
+    }
+    async enqueueMutation(ctx, fn, fnArgs) {
+        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;
+    }
+    async cancel(ctx, id) {
+        await ctx.runMutation(this.component.lib.cancel, { id });
+    }
+    async status(ctx, id) {
+        return await ctx.runQuery(this.component.lib.status, { id });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EAQpB,eAAe,GAChB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,gBAAgB,EAAyB,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAyB,CAAC;AAInD,MAAM,OAAO,QAAQ;IAET;IACA;IAFV,YACU,SAA6B,EAC7B,OAiBP;QAlBO,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAiBd;IACA,CAAC;IACJ,KAAK,CAAC,aAAa,CACjB,GAAmB,EACnB,EAAqE,EACrE,MAAY;QAEZ,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE;YAC3D,QAAQ;YACR,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC;YAC3B,MAAM;YACN,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,OAAO,EAAY,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,eAAe,CACnB,GAAmB,EACnB,EAAuE,EACvE,MAAY;QAEZ,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE;YAC3D,QAAQ;YACR,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC;YAC3B,MAAM;YACN,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,OAAO,EAAY,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,GAAmB,EAAE,EAAU;QAC1C,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,CAAC,MAAM,CACV,GAAgB,EAChB,EAAU;QAMV,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/esm/component/_generated/api.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: import("convex/server").AnyApi;
+export const internal: import("convex/server").AnyApi;
+export const components: {
+    [x: string]: import("../../../node_modules/convex/dist/esm-types/server/components").AnyComponentReference;
+};
+//# sourceMappingURL=api.d.ts.map

package/dist/esm/component/_generated/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,iDAA0B;AAC1B,sDAA+B;AAC/B;;EAA8C"}

package/dist/esm/component/_generated/api.js

@@ -0,0 +1,22 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import { anyApi, componentsGeneric } from "convex/server";
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();
+//# sourceMappingURL=api.js.map

package/dist/esm/component/_generated/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC;AAC1B,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC"}

package/dist/esm/component/_generated/server.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: import("convex/server").QueryBuilder<any, "public">;
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: import("convex/server").QueryBuilder<any, "internal">;
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: import("convex/server").MutationBuilder<any, "public">;
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: import("convex/server").MutationBuilder<any, "internal">;
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: import("convex/server").ActionBuilder<any, "public">;
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: import("convex/server").ActionBuilder<any, "internal">;
+/**
+ * Define a Convex HTTP action.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object
+ * as its second.
+ * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
+ */
+export const httpAction: (func: (ctx: import("convex/server").GenericActionCtx<import("convex/server").GenericDataModel>, request: Request) => Promise<Response>) => import("convex/server").PublicHttpAction;
+//# sourceMappingURL=server.d.ts.map

package/dist/esm/component/_generated/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/server.js"],"names":[],"mappings":"AAqBA;;;;;;;GAOG;AACH,wEAAkC;AAElC;;;;;;;GAOG;AACH,kFAAkD;AAElD;;;;;;;GAOG;AACH,8EAAwC;AAExC;;;;;;;GAOG;AACH,wFAAwD;AAExD;;;;;;;;;;GAUG;AACH,0EAAoC;AAEpC;;;;;GAKG;AACH,oFAAoD;AAEpD;;;;;;GAMG;AACH,8MAA4C"}