@convex-dev/workpool 0.2.18-alpha.3 → 0.2.19-alpha.0

package/src/client/index.ts

@@ -52,6 +52,9 @@ export const DEFAULT_RETRY_BEHAVIOR: RetryBehavior = {
   base: 2,
 };
 
+// UseApi<api> for jump to definition
+export type WorkpoolComponent = UseApi<Mounts>;
+
 export class Workpool {
   /**
    * Initializes a Workpool.
@@ -65,9 +68,10 @@ export class Workpool {
    * @param options - The {@link WorkpoolOptions} for the Workpool.
    */
   constructor(
-    private component: UseApi<Mounts>, // UseApi<api> for jump to definition
+    public component: WorkpoolComponent,
     public options: WorkpoolOptions
   ) {}
+
   /**
    * Enqueues an action to be run.
    *
@@ -82,28 +86,48 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: RetryOption & CallbackOptions & SchedulerOptions & NameOption
+    options?: RetryOption & EnqueueOptions
   ): Promise<WorkId> {
     const retryBehavior = getRetryBehavior(
       this.options.defaultRetryBehavior,
       this.options.retryActionsByDefault,
       options?.retry
     );
-    const onComplete: OnComplete | undefined = 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,
+    return enqueue(this.component, ctx, "action", fn, fnArgs, {
+      retryBehavior,
+      ...this.options,
+      ...options,
+    });
+  }
+
+  /**
+   * Enqueues a batch of actions to be run.
+   * Each action will be run independently, and the onComplete handler will
+   * be called for each action.
+   *
+   * @param ctx - The mutation or action ctx that can call ctx.runMutation.
+   * @param fn - The action to run, like `internal.example.myAction`.
+   * @param argsArray - The arguments to pass to the action.
+   * @param options - The options for the actions to specify retry behavior,
+   *   onComplete handling, and scheduling via `runAt` or `runAfter`.
+   * @returns The IDs of the work that was enqueued.
+   */
+  async enqueueActionBatch<Args extends DefaultFunctionArgs, ReturnType>(
+    ctx: RunMutationCtx,
+    fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>,
+    argsArray: Array<Args>,
+    options?: RetryOption & EnqueueOptions
+  ): Promise<WorkId[]> {
+    const retryBehavior = getRetryBehavior(
+      this.options.defaultRetryBehavior,
+      this.options.retryActionsByDefault,
+      options?.retry
+    );
+    return enqueueBatch(this.component, ctx, "action", fn, argsArray, {
       retryBehavior,
+      ...this.options,
+      ...options,
     });
-    return id as WorkId;
   }
 
   /**
@@ -123,44 +147,81 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: CallbackOptions & SchedulerOptions & NameOption
+    options?: EnqueueOptions
   ): Promise<WorkId> {
-    const onComplete: OnComplete | undefined = 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 enqueue(this.component, ctx, "mutation", fn, fnArgs, {
+      ...this.options,
+      ...options,
+    });
+  }
+  /**
+   * Enqueues a batch of mutations to be run.
+   * Each mutation will be run independently, and the onComplete handler will
+   * be called for each mutation.
+   *
+   * @param ctx - The mutation or action context that can call ctx.runMutation.
+   * @param fn - The mutation to run, like `internal.example.myMutation`.
+   * @param argsArray - The arguments to pass to the mutations.
+   * @param options - The options for the mutations to specify onComplete handling
+   *   and scheduling via `runAt` or `runAfter`.
+   */
+  async enqueueMutationBatch<Args extends DefaultFunctionArgs, ReturnType>(
+    ctx: RunMutationCtx,
+    fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>,
+    argsArray: Array<Args>,
+    options?: EnqueueOptions
+  ): Promise<WorkId[]> {
+    return enqueueBatch(this.component, ctx, "mutation", fn, argsArray, {
+      ...this.options,
+      ...options,
     });
-    return id as WorkId;
   }
 
+  /**
+   * Enqueues a query to be run.
+   * Usually not what you want, but it can be useful during workflows.
+   * The query is run in a mutation and the result is returned to the caller,
+   * so it can conflict if other mutations are writing the value.
+   *
+   * @param ctx - The mutation or action context that can call ctx.runMutation.
+   * @param fn - The query to run, like `internal.example.myQuery`.
+   * @param fnArgs - The arguments to pass to the query.
+   * @param options - The options for the query to specify onComplete handling
+   *   and scheduling via `runAt` or `runAfter`.
+   */
   async enqueueQuery<Args extends DefaultFunctionArgs, ReturnType>(
     ctx: RunMutationCtx,
     fn: FunctionReference<"query", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: CallbackOptions & SchedulerOptions & NameOption
+    options?: EnqueueOptions
   ): Promise<WorkId> {
-    const onComplete: OnComplete | undefined = 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 enqueue(this.component, ctx, "query", fn, fnArgs, {
+      ...this.options,
+      ...options,
+    });
+  }
+
+  /**
+   * Enqueues a batch of queries to be run.
+   * Each query will be run independently, and the onComplete handler will
+   * be called for each query.
+   *
+   * @param ctx - The mutation or action context that can call ctx.runMutation.
+   * @param fn - The query to run, like `internal.example.myQuery`.
+   * @param argsArray - The arguments to pass to the queries.
+   * @param options - The options for the queries to specify onComplete handling
+   *   and scheduling via `runAt` or `runAfter`.
+   */
+  async enqueueQueryBatch<Args extends DefaultFunctionArgs, ReturnType>(
+    ctx: RunMutationCtx,
+    fn: FunctionReference<"query", FunctionVisibility, Args, ReturnType>,
+    argsArray: Array<Args>,
+    options?: EnqueueOptions
+  ): Promise<WorkId[]> {
+    return enqueueBatch(this.component, ctx, "query", fn, argsArray, {
+      ...this.options,
+      ...options,
     });
-    return id as WorkId;
   }
 
   /**
@@ -181,9 +242,13 @@ export class Workpool {
    *
    * @param ctx - The mutation or action context that can call ctx.runMutation.
    */
-  async cancelAll(ctx: RunMutationCtx): Promise<void> {
+  async cancelAll(
+    ctx: RunMutationCtx,
+    options?: { limit?: number }
+  ): Promise<void> {
     await ctx.runMutation(this.component.lib.cancelAll, {
       logLevel: this.options.logLevel ?? DEFAULT_LOG_LEVEL,
+      ...options,
     });
   }
   /**
@@ -200,6 +265,17 @@ export class Workpool {
     return ctx.runQuery(this.component.lib.status, { id });
   }
 
+  /**
+   * Gets the status of a batch of work items.
+   *
+   * @param ctx - The query context that can call ctx.runQuery.
+   * @param ids - The IDs of the work to get the status of.
+   * @returns The status of the work items.
+   */
+  async statusBatch(ctx: RunQueryCtx, ids: WorkId[]): Promise<Status[]> {
+    return ctx.runQuery(this.component.lib.statusBatch, { ids });
+  }
+
   /**
    * Defines a mutation that will be run after a work item completes.
    * You can pass this to a call to enqueue* like so:
@@ -269,17 +345,9 @@ export function vOnCompleteArgs<
   });
 }
 
-export type NameOption = {
-  /**
-   * The name of the function. By default, if you pass in api.foo.bar.baz,
-   * it will use "foo/bar:baz" as the name. If you pass in a function handle,
-   * it will use the function handle directly.
-   */
-  name?: string;
-};
-
 export type RetryOption = {
   /** Whether to retry the action if it fails.
+   * If false, the action won’t be retried.
    * If true, it will use the default retry behavior.
    * If custom behavior is provided, it will retry using that behavior.
    * If unset, it will use the Workpool's configured default.
@@ -315,25 +383,14 @@ export type WorkpoolRetryOptions = {
    */
   retryActionsByDefault?: boolean;
 };
-export type SchedulerOptions =
-  | {
-      /**
-       * The time (ms since epoch) to run the action at.
-       * If not provided, the action will be run as soon as possible.
-       * Note: this is advisory only. It may run later.
-       */
-      runAt?: number;
-    }
-  | {
-      /**
-       * The number of milliseconds to run the action after.
-       * If not provided, the action will be run as soon as possible.
-       * Note: this is advisory only. It may run later.
-       */
-      runAfter?: number;
-    };
 
-export type CallbackOptions = {
+export type EnqueueOptions = {
+  /**
+   * The name of the function. By default, if you pass in api.foo.bar.baz,
+   * it will use "foo/bar:baz" as the name. If you pass in a function handle,
+   * it will use the function handle directly.
+   */
+  name?: string;
   /**
    * A mutation to run after the function succeeds, fails, or is canceled.
    * The context type is for your use, feel free to provide a validator for it.
@@ -368,7 +425,24 @@ export type CallbackOptions = {
    * Useful for passing data from the enqueue site to the onComplete site.
    */
   context?: unknown;
-};
+} & (
+  | {
+      /**
+       * The time (ms since epoch) to run the action at.
+       * If not provided, the action will be run as soon as possible.
+       * Note: this is advisory only. It may run later.
+       */
+      runAt?: number;
+    }
+  | {
+      /**
+       * The number of milliseconds to run the action after.
+       * If not provided, the action will be run as soon as possible.
+       * Note: this is advisory only. It may run later.
+       */
+      runAfter?: number;
+    }
+);
 
 export type OnCompleteArgs = {
   /**
@@ -412,36 +486,105 @@ function getRetryBehavior(
   return retryOverride ?? (retryByDefault ? defaultRetry : undefined);
 }
 
-async function defaultEnqueueArgs(
+async function enqueueArgs(
   fn:
     | FunctionReference<FunctionType, FunctionVisibility>
     | FunctionHandle<FunctionType, DefaultFunctionArgs>,
-  name: string | undefined,
-  { logLevel, maxParallelism }: Partial<Config>
+  opts:
+    | (EnqueueOptions & Partial<Config> & { retryBehavior?: RetryBehavior })
+    | undefined
 ) {
   const [fnHandle, fnName] =
     typeof fn === "string" && fn.startsWith("function://")
-      ? [fn, name ?? fn]
-      : [await createFunctionHandle(fn), name ?? safeFunctionName(fn)];
+      ? [fn, opts?.name ?? fn]
+      : [await createFunctionHandle(fn), opts?.name ?? safeFunctionName(fn)];
+  const onComplete: OnComplete | undefined = opts?.onComplete
+    ? {
+        fnHandle: await createFunctionHandle(opts.onComplete),
+        context: opts.context,
+      }
+    : undefined;
   return {
     fnHandle,
     fnName,
+    onComplete,
+    runAt: getRunAt(opts),
+    retryBehavior: opts?.retryBehavior,
     config: {
-      logLevel: logLevel ?? DEFAULT_LOG_LEVEL,
-      maxParallelism: maxParallelism ?? DEFAULT_MAX_PARALLELISM,
+      logLevel: opts?.logLevel ?? DEFAULT_LOG_LEVEL,
+      maxParallelism: opts?.maxParallelism ?? DEFAULT_MAX_PARALLELISM,
     },
   };
 }
 
-function getRunAt(options?: SchedulerOptions): number {
+function getRunAt(
+  options:
+    | {
+        runAt?: number;
+        runAfter?: number;
+      }
+    | undefined
+): number {
   if (!options) {
     return Date.now();
   }
-  if ("runAt" in options && options.runAt !== undefined) {
+  if (options.runAt !== undefined) {
     return options.runAt;
   }
-  if ("runAfter" in options && options.runAfter !== undefined) {
+  if (options.runAfter !== undefined) {
     return Date.now() + options.runAfter;
   }
   return Date.now();
 }
+
+export async function enqueueBatch<
+  FnType extends FunctionType,
+  Args extends DefaultFunctionArgs,
+  ReturnType,
+>(
+  component: UseApi<Mounts>,
+  ctx: RunMutationCtx,
+  fnType: FnType,
+  fn: FunctionReference<FnType, FunctionVisibility, Args, ReturnType>,
+  fnArgsArray: Array<Args>,
+  options: EnqueueOptions & {
+    retryBehavior?: RetryBehavior;
+    maxParallelism?: number;
+    logLevel?: LogLevel;
+  }
+): Promise<WorkId[]> {
+  const { config, ...defaults } = await enqueueArgs(fn, options);
+  const ids = await ctx.runMutation(component.lib.enqueueBatch, {
+    items: fnArgsArray.map((fnArgs) => ({
+      ...defaults,
+      fnArgs,
+      fnType,
+    })),
+    config,
+  });
+  return ids as WorkId[];
+}
+
+export async function enqueue<
+  FnType extends FunctionType,
+  Args extends DefaultFunctionArgs,
+  ReturnType,
+>(
+  component: UseApi<Mounts>,
+  ctx: RunMutationCtx,
+  fnType: FnType,
+  fn: FunctionReference<FnType, FunctionVisibility, Args, ReturnType>,
+  fnArgs: Args,
+  options: EnqueueOptions & {
+    retryBehavior?: RetryBehavior;
+    maxParallelism?: number;
+    logLevel?: LogLevel;
+  }
+): Promise<WorkId> {
+  const id = await ctx.runMutation(component.lib.enqueue, {
+    ...(await enqueueArgs(fn, options)),
+    fnArgs,
+    fnType,
+  });
+  return id as WorkId;
+}

package/src/component/_generated/api.d.ts

@@ -89,6 +89,30 @@ export type Mounts = {
       },
       string
     >;
+    enqueueBatch: FunctionReference<
+      "mutation",
+      "public",
+      {
+        config: {
+          logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+          maxParallelism: number;
+        };
+        items: Array<{
+          fnArgs: any;
+          fnHandle: string;
+          fnName: string;
+          fnType: "action" | "mutation" | "query";
+          onComplete?: { context?: any; fnHandle: string };
+          retryBehavior?: {
+            base: number;
+            initialBackoffMs: number;
+            maxAttempts: number;
+          };
+          runAt: number;
+        }>;
+      },
+      Array<string>
+    >;
     status: FunctionReference<
       "query",
       "public",
@@ -97,6 +121,16 @@ export type Mounts = {
       | { previousAttempts: number; state: "running" }
       | { state: "finished" }
     >;
+    statusBatch: FunctionReference<
+      "query",
+      "public",
+      { ids: Array<string> },
+      Array<
+        | { previousAttempts: number; state: "pending" }
+        | { previousAttempts: number; state: "running" }
+        | { state: "finished" }
+      >
+    >;
   };
 };
 // For now fullApiWithMounts is only fullApi which provides

package/src/component/kick.ts

@@ -9,6 +9,8 @@ import {
   fromSegment,
   getCurrentSegment,
   getNextSegment,
+  SECOND,
+  toSegment,
 } from "./shared.js";
 
 /**
@@ -40,7 +42,7 @@ export async function kickMainLoop(
       );
       return next;
     }
-    if (runStatus.state.segment <= next) {
+    if (runStatus.state.segment <= toSegment(Date.now() + SECOND)) {
       console.debug(
         `[${source}] main is scheduled to run soon enough, so we don't need to kick it`
       );