@convex-dev/workpool
Version:
A Convex component for managing async work.
236 lines • 8.63 kB
JavaScript
import { createFunctionHandle, getFunctionName, internalMutationGeneric, } from "convex/server";
import { v } from "convex/values";
import { DEFAULT_LOG_LEVEL } from "../component/logging.js";
import { DEFAULT_MAX_PARALLELISM, vResultValidator, } from "../component/shared.js";
export { vResultValidator, };
export { retryBehavior as vRetryBehavior, onComplete as vOnComplete, } from "../component/shared.js";
export { logLevel as vLogLevel } from "../component/logging.js";
export const vWorkIdValidator = v.string();
export {
/** @deprecated Use `vWorkIdValidator` instead. */
vWorkIdValidator as workIdValidator,
/** @deprecated Use `vResultValidator` instead. */
vResultValidator as resultValidator, };
// Attempts will run with delay [0, 250, 500, 1000, 2000] (ms)
export const DEFAULT_RETRY_BEHAVIOR = {
maxAttempts: 5,
initialBackoffMs: 250,
base: 2,
};
export class Workpool {
component;
options;
/**
* Initializes a Workpool.
*
* Note: if you want different pools, you need to *create different instances*
* of Workpool in convex.config.ts. It isn't sufficient to have different
* instances of this class.
*
* @param component - The component to use, like `components.workpool` from
* `./_generated/api.ts`.
* @param options - The {@link WorkpoolOptions} for the Workpool.
*/
constructor(component, // UseApi<api> for jump to definition
options) {
this.component = component;
this.options = options;
}
/**
* Enqueues an action to be run.
*
* @param ctx - The mutation or action context that can call ctx.runMutation.
* @param fn - The action to run, like `internal.example.myAction`.
* @param fnArgs - The arguments to pass to the action.
* @param options - The options for the action to specify retry behavior,
* onComplete handling, and scheduling via `runAt` or `runAfter`.
* @returns The ID of the work that was enqueued.
*/
async enqueueAction(ctx, fn, fnArgs, options) {
const retryBehavior = getRetryBehavior(this.options.defaultRetryBehavior, this.options.retryActionsByDefault, options?.retry);
const onComplete = options?.onComplete
? {
fnHandle: await createFunctionHandle(options.onComplete),
context: options.context,
}
: undefined;
const id = await ctx.runMutation(this.component.lib.enqueue, {
...(await defaultEnqueueArgs(fn, options?.name, this.options)),
fnArgs,
fnType: "action",
runAt: getRunAt(options),
onComplete,
retryBehavior,
});
return id;
}
/**
* Enqueues a mutation to be run.
*
* Note: mutations are not retried by the workpool. Convex automatically
* retries them on database conflicts and transient failures.
* Because they're deterministic, external retries don't provide any benefit.
*
* @param ctx - The mutation or action context that can call ctx.runMutation.
* @param fn - The mutation to run, like `internal.example.myMutation`.
* @param fnArgs - The arguments to pass to the mutation.
* @param options - The options for the mutation to specify onComplete handling
* and scheduling via `runAt` or `runAfter`.
*/
async enqueueMutation(ctx, fn, fnArgs, options) {
const onComplete = options?.onComplete
? {
fnHandle: await createFunctionHandle(options.onComplete),
context: options.context,
}
: undefined;
const id = await ctx.runMutation(this.component.lib.enqueue, {
...(await defaultEnqueueArgs(fn, options?.name, this.options)),
fnArgs,
fnType: "mutation",
runAt: getRunAt(options),
onComplete,
});
return id;
}
async enqueueQuery(ctx, fn, fnArgs, options) {
const onComplete = options?.onComplete
? {
fnHandle: await createFunctionHandle(options.onComplete),
context: options.context,
}
: undefined;
const id = await ctx.runMutation(this.component.lib.enqueue, {
...(await defaultEnqueueArgs(fn, options?.name, this.options)),
fnArgs,
fnType: "query",
runAt: getRunAt(options),
onComplete,
});
return id;
}
/**
* Cancels a work item. If it's already started, it will be allowed to finish
* but will not be retried.
*
* @param ctx - The mutation or action context that can call ctx.runMutation.
* @param id - The ID of the work to cancel.
*/
async cancel(ctx, id) {
await ctx.runMutation(this.component.lib.cancel, {
id,
logLevel: this.options.logLevel ?? DEFAULT_LOG_LEVEL,
});
}
/**
* Cancels all pending work items. See {@link cancel}.
*
* @param ctx - The mutation or action context that can call ctx.runMutation.
*/
async cancelAll(ctx) {
await ctx.runMutation(this.component.lib.cancelAll, {
logLevel: this.options.logLevel ?? DEFAULT_LOG_LEVEL,
});
}
/**
* Gets the status of a work item.
*
* @param ctx - The query context that can call ctx.runQuery.
* @param id - The ID of the work to get the status of.
* @returns The status of the work item. One of:
* - `{ state: "pending", previousAttempts: number }`
* - `{ state: "running", previousAttempts: number }`
* - `{ state: "finished" }`
*/
async status(ctx, id) {
return ctx.runQuery(this.component.lib.status, { id });
}
/**
* Defines a mutation that will be run after a work item completes.
* You can pass this to a call to enqueue* like so:
* ```ts
* export const myOnComplete = workpool.defineOnComplete({
* context: v.literal("myContextValue"), // optional
* handler: async (ctx, {workId, context, result}) => {
* // ... do something with the result
* },
* });
*
* // in some other function:
* const workId = await workpool.enqueueAction(ctx, internal.foo.bar, {
* // ... args to action
* }, {
* onComplete: internal.foo.myOnComplete,
* });
* ```
*/
defineOnComplete({ context, handler, }) {
return internalMutationGeneric({
args: vOnCompleteValidator(context),
handler,
});
}
}
/**
* Returns a validator to use for the onComplete mutation.
* To be used like:
* ```ts
* export const myOnComplete = internalMutation({
* args: vOnCompleteValidator(v.string()),
* handler: async (ctx, {workId, context, result}) => {
* // context has been validated as a string
* // ... do something with the result
* },
* });
* @param context - The context validator. If not provided, it will be `v.any()`.
* @returns The validator for the onComplete mutation.
*/
export function vOnCompleteValidator(context) {
return v.object({
workId: vWorkIdValidator,
context: context ?? v.any(),
result: vResultValidator,
});
}
// ensure OnCompleteArgs satisfies SharedOnCompleteArgs
const _ = {};
//
// Helper functions
//
function getRetryBehavior(defaultRetryBehavior, retryActionsByDefault, retryOverride) {
const defaultRetry = defaultRetryBehavior ?? DEFAULT_RETRY_BEHAVIOR;
const retryByDefault = retryActionsByDefault ?? false;
if (retryOverride === true) {
return defaultRetry;
}
if (retryOverride === false) {
return undefined;
}
return retryOverride ?? (retryByDefault ? defaultRetry : undefined);
}
async function defaultEnqueueArgs(fn, name, { logLevel, maxParallelism }) {
const [fnHandle, fnName] = typeof fn === "string" && fn.startsWith("function://")
? [fn, name ?? fn]
: [await createFunctionHandle(fn), name ?? getFunctionName(fn)];
return {
fnHandle,
fnName,
config: {
logLevel: logLevel ?? DEFAULT_LOG_LEVEL,
maxParallelism: maxParallelism ?? DEFAULT_MAX_PARALLELISM,
},
};
}
function getRunAt(options) {
if (!options) {
return Date.now();
}
if ("runAt" in options && options.runAt !== undefined) {
return options.runAt;
}
if ("runAfter" in options && options.runAfter !== undefined) {
return Date.now() + options.runAfter;
}
return Date.now();
}
//# sourceMappingURL=index.js.map