@convex-dev/workpool 0.2.20-alpha.0 → 0.3.1-alpha.0

package/dist/component/worker.d.ts

@@ -1,16 +1,16 @@
 export declare const runMutationWrapper: import("convex/server").RegisteredMutation<"internal", {
     logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+    fnArgs: any;
     fnHandle: string;
-    workId: import("convex/values").GenericId<"work">;
     fnType: "mutation" | "query";
-    fnArgs: any;
+    workId: import("convex/values").GenericId<"work">;
     attempt: number;
 }, Promise<void>>;
 export declare const runActionWrapper: import("convex/server").RegisteredAction<"internal", {
     logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+    fnArgs: any;
     fnHandle: string;
     workId: import("convex/values").GenericId<"work">;
-    fnArgs: any;
     attempt: number;
 }, Promise<void>>;
 //# sourceMappingURL=worker.d.ts.map

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/workpool/issues"
   },
-  "version": "0.2.20-alpha.0",
+  "version": "0.3.1-alpha.0",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -19,25 +19,23 @@
   ],
   "type": "module",
   "scripts": {
-    "dev": "run-p -r 'dev:backend' 'dev:frontend' 'build:watch'",
-    "dev:backend": "convex dev --live-component-sources --typecheck-components",
+    "dev": "run-p -r 'dev:*'",
+    "dev:backend": "convex dev --typecheck-components",
     "dev:frontend": "cd example && vite --clearScreen false",
+    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'convex codegen --component-dir ./src/component && npm run build' --initial",
     "predev": "npm run dev:backend -- --until-success",
-    "clean": "rm -rf dist tsconfig.build.tsbuildinfo",
-    "build": "tsc --project ./tsconfig.build.json && npm run copy:dts",
-    "copy:dts": "rsync -a --include='*/' --include='*.d.ts' --exclude='*' src/ dist/ || cpy 'src/**/*.d.ts' 'dist/' --parents",
-    "build:watch": "npx chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build' --initial",
-    "typecheck": "tsc --noEmit && tsc -p example/convex",
-    "lint": "eslint src && eslint example/convex",
-    "all": "run-p -r 'dev:backend' 'dev:frontend' 'build:watch' 'test:watch'",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "build": "tsc --project ./tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "all": "run-p -r 'dev:*' 'test:watch'",
     "test": "vitest run --typecheck",
     "test:watch": "vitest --typecheck --clearScreen false",
     "test:debug": "vitest --inspect-brk --no-file-parallelism",
     "test:coverage": "vitest run --coverage --coverage.reporter=text",
-    "attw": "attw $(npm pack -s) --exclude-entrypoints ./convex.config --profile esm-only",
     "prepare": "npm run build",
-    "alpha": "npm run clean && npm ci && run-p test lint typecheck attw && npm version prerelease --preid alpha && npm publish --tag alpha && git push --tags",
-    "release": "npm run clean && npm ci && run-p test lint typecheck attw && npm version patch && npm publish && git push --tags",
+    "alpha": "npm run clean && npm ci && run-p test lint typecheck && npm version prerelease --preid alpha && npm publish --tag alpha && git push --tags",
+    "release": "npm run clean && npm ci && run-p test lint typecheck && npm version patch && npm publish && git push --tags",
     "version": "pbcopy <<<$npm_package_version; vim CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
   },
   "files": [
@@ -47,51 +45,54 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "@convex-dev/component-source": "./src/client/index.ts",
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
     "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
     "./convex.config": {
-      "@convex-dev/component-source": "./src/component/convex.config.ts",
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
       "types": "./dist/component/convex.config.d.ts",
       "default": "./dist/component/convex.config.js"
     }
   },
   "peerDependencies": {
-    "convex": ">=1.25.0 <1.35.0",
+    "convex": "^1.24.8",
     "convex-helpers": "^0.1.94"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "0.18.2",
     "@edge-runtime/vm": "5.0.0",
     "@eslint/eslintrc": "3.3.1",
-    "@eslint/js": "9.38.0",
-    "@types/node": "22.18.11",
+    "@eslint/js": "9.39.1",
+    "@types/node": "20.19.24",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
-    "@vitejs/plugin-react": "5.0.4",
+    "@vitejs/plugin-react": "5.1.0",
     "@vitest/coverage-v8": "3.2.4",
     "chokidar-cli": "3.0.0",
-    "convex": "1.28.0",
+    "convex": "1.29.0",
     "convex-helpers": "0.1.104",
     "convex-test": "0.0.38",
     "cpy-cli": "6.0.0",
-    "eslint": "9.38.0",
-    "eslint-plugin-react-hooks": "7.0.0",
+    "eslint": "9.39.1",
+    "eslint-plugin-react-hooks": "7.0.1",
     "eslint-plugin-react-refresh": "0.4.24",
-    "globals": "16.4.0",
+    "globals": "16.5.0",
     "npm-run-all2": "8.0.4",
     "pkg-pr-new": "0.0.60",
     "prettier": "3.6.2",
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.40.0",
-    "vite": "7.1.10",
+    "typescript-eslint": "8.46.3",
+    "vite": "7.1.12",
     "vitest": "3.2.4"
   },
-  "main": "./dist/commonjs/client/index.js",
-  "types": "./dist/commonjs/client/index.d.ts",
-  "module": "./dist/esm/client/index.js"
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js"
 }

package/src/client/index.ts

@@ -17,7 +17,7 @@ import {
   type VAny,
   type VString,
 } from "convex/values";
-import type { api } from "../component/_generated/api.js";
+import type { ComponentApi } from "../component/_generated/component.js";
 import { DEFAULT_LOG_LEVEL, type LogLevel } from "../component/logging.js";
 import {
   type Config,
@@ -34,11 +34,11 @@ import {
   type RunMutationCtx,
   type RunQueryCtx,
   safeFunctionName,
-  type UseApi,
 } from "./utils.js";
 export { logLevel as vLogLevel, type LogLevel } from "../component/logging.js";
 export { retryBehavior as vRetryBehavior } from "../component/shared.js";
 export { vResultValidator, type RetryBehavior, type RunResult };
+
 export type WorkId = string & { __isWorkId: true };
 export const vWorkIdValidator = v.string() as VString<WorkId>;
 export {
@@ -53,8 +53,7 @@ export const vOnComplete = vOnCompleteArgs(v.any());
 /** @deprecated Use `vOnCompleteArgs()` instead. */
 export const vOnCompleteValidator = vOnCompleteArgs;
 
-// UseApi<api> for jump to definition
-export type WorkpoolComponent = UseApi<typeof api>;
+export type WorkpoolComponent = ComponentApi;
 
 export class Workpool {
   /**
@@ -70,7 +69,7 @@ export class Workpool {
    */
   constructor(
     public component: WorkpoolComponent,
-    public options: WorkpoolOptions
+    public options: WorkpoolOptions,
   ) {}
 
   /**
@@ -87,12 +86,12 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: RetryOption & EnqueueOptions
+    options?: RetryOption & EnqueueOptions,
   ): Promise<WorkId> {
     const retryBehavior = getRetryBehavior(
       this.options.defaultRetryBehavior,
       this.options.retryActionsByDefault,
-      options?.retry
+      options?.retry,
     );
     return enqueue(this.component, ctx, "action", fn, fnArgs, {
       retryBehavior,
@@ -117,12 +116,12 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>,
     argsArray: Array<Args>,
-    options?: RetryOption & EnqueueOptions
+    options?: RetryOption & EnqueueOptions,
   ): Promise<WorkId[]> {
     const retryBehavior = getRetryBehavior(
       this.options.defaultRetryBehavior,
       this.options.retryActionsByDefault,
-      options?.retry
+      options?.retry,
     );
     return enqueueBatch(this.component, ctx, "action", fn, argsArray, {
       retryBehavior,
@@ -148,7 +147,7 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: EnqueueOptions
+    options?: EnqueueOptions,
   ): Promise<WorkId> {
     return enqueue(this.component, ctx, "mutation", fn, fnArgs, {
       ...this.options,
@@ -170,7 +169,7 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>,
     argsArray: Array<Args>,
-    options?: EnqueueOptions
+    options?: EnqueueOptions,
   ): Promise<WorkId[]> {
     return enqueueBatch(this.component, ctx, "mutation", fn, argsArray, {
       ...this.options,
@@ -194,7 +193,7 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"query", FunctionVisibility, Args, ReturnType>,
     fnArgs: Args,
-    options?: EnqueueOptions
+    options?: EnqueueOptions,
   ): Promise<WorkId> {
     return enqueue(this.component, ctx, "query", fn, fnArgs, {
       ...this.options,
@@ -217,7 +216,7 @@ export class Workpool {
     ctx: RunMutationCtx,
     fn: FunctionReference<"query", FunctionVisibility, Args, ReturnType>,
     argsArray: Array<Args>,
-    options?: EnqueueOptions
+    options?: EnqueueOptions,
   ): Promise<WorkId[]> {
     return enqueueBatch(this.component, ctx, "query", fn, argsArray, {
       ...this.options,
@@ -245,7 +244,7 @@ export class Workpool {
    */
   async cancelAll(
     ctx: RunMutationCtx,
-    options?: { limit?: number }
+    options?: { limit?: number },
   ): Promise<void> {
     await ctx.runMutation(this.component.lib.cancelAll, {
       logLevel: this.options.logLevel ?? DEFAULT_LOG_LEVEL,
@@ -310,7 +309,7 @@ export class Workpool {
         workId: WorkId;
         context: Infer<V>;
         result: RunResult;
-      }
+      },
     ) => Promise<void>;
   }): RegisteredMutation<"internal", OnCompleteArgs, null> {
     return internalMutationGeneric({
@@ -471,7 +470,7 @@ const _ = {} as OnCompleteArgs satisfies SharedOnCompleteArgs;
 function getRetryBehavior(
   defaultRetryBehavior: RetryBehavior | undefined,
   retryActionsByDefault: boolean | undefined,
-  retryOverride: boolean | RetryBehavior | undefined
+  retryOverride: boolean | RetryBehavior | undefined,
 ): RetryBehavior | undefined {
   const defaultRetry = defaultRetryBehavior ?? DEFAULT_RETRY_BEHAVIOR;
   const retryByDefault = retryActionsByDefault ?? false;
@@ -490,7 +489,7 @@ async function enqueueArgs(
     | FunctionHandle<FunctionType, DefaultFunctionArgs>,
   opts:
     | (EnqueueOptions & Partial<Config> & { retryBehavior?: RetryBehavior })
-    | undefined
+    | undefined,
 ) {
   const [fnHandle, fnName] =
     typeof fn === "string" && fn.startsWith("function://")
@@ -521,7 +520,7 @@ function getRunAt(
         runAt?: number;
         runAfter?: number;
       }
-    | undefined
+    | undefined,
 ): number {
   if (!options) {
     return Date.now();
@@ -549,7 +548,7 @@ export async function enqueueBatch<
     retryBehavior?: RetryBehavior;
     maxParallelism?: number;
     logLevel?: LogLevel;
-  }
+  },
 ): Promise<WorkId[]> {
   const { config, ...defaults } = await enqueueArgs(fn, options);
   const ids = await ctx.runMutation(component.lib.enqueueBatch, {
@@ -577,7 +576,7 @@ export async function enqueue<
     retryBehavior?: RetryBehavior;
     maxParallelism?: number;
     logLevel?: LogLevel;
-  }
+  },
 ): Promise<WorkId> {
   const id = await ctx.runMutation(component.lib.enqueue, {
     ...(await enqueueArgs(fn, options)),

package/src/client/utils.ts

@@ -1,5 +1,4 @@
 import {
-  type Expand,
   type FunctionArgs,
   type FunctionReference,
   type FunctionReturnType,
@@ -8,50 +7,24 @@ import {
   getFunctionAddress,
   getFunctionName,
 } from "convex/server";
-import type { GenericId, Value } from "convex/values";
 
 /* Type utils follow */
 
 export type RunQueryCtx = {
   runQuery: <Query extends FunctionReference<"query", "internal">>(
     query: Query,
-    args: FunctionArgs<Query>
+    args: FunctionArgs<Query>,
   ) => Promise<FunctionReturnType<Query>>;
 };
 export type RunMutationCtx = RunQueryCtx & {
   runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
     mutation: Mutation,
-    args: FunctionArgs<Mutation>
+    args: FunctionArgs<Mutation>,
   ) => Promise<FunctionReturnType<Mutation>>;
 };
 
-export type OpaqueIds<T> =
-  T extends GenericId<string>
-    ? string
-    : T extends (infer U)[]
-      ? OpaqueIds<U>[]
-      : T extends Record<string, Value | undefined>
-        ? { [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
-  >
-    ? FunctionReference<
-        FType,
-        "internal",
-        OpaqueIds<FArgs>,
-        OpaqueIds<FReturnType>
-      >
-    : UseApi<API[mod]>;
-}>;
-
 export function safeFunctionName(
-  f: FunctionReference<FunctionType, FunctionVisibility>
+  f: FunctionReference<FunctionType, FunctionVisibility>,
 ) {
   const address = getFunctionAddress(f);
   return (

package/src/component/README.md

@@ -4,10 +4,10 @@ Concepts:
 
 - `segment`: A slice of time to process work. All work is bucketed into one.
   This enables us to batch work and avoid database conflicts.
-- `generation`: A monotonically increasing counter to ensure the loop is
-  only running one instance. If two loops start with the same generation,
-  one will successfully increase it, the other will retry and find that the
-  generation has changed and fail out.
+- `generation`: A monotonically increasing counter to ensure the loop is only
+  running one instance. If two loops start with the same generation, one will
+  successfully increase it, the other will retry and find that the generation
+  has changed and fail out.
 - "Retention" is used to refer to situations where a query might have to read
   over a lot of "tombstones" - deleted data that hasn't been vacuumed from the
   underlying database yet. If there are frequent deletions, scanning across them
@@ -65,8 +65,8 @@ flowchart TD
 - Producers (Client, Worker, Recovery) write to a future "segment".
 - Consumers (main) read the current segment.
   - On conflicts, producers will write to progressively higher segments, while
-    the main loop will continue to read the segment originally called with.
-    This means conflicts are less likely on each retry.
+    the main loop will continue to read the segment originally called with. This
+    means conflicts are less likely on each retry.
 - Patch singletons to avoid tombstones.
 - Use segements & cursors to bound reads to latest data.
   - Do scans outside of the critical path (during load).

package/src/component/_generated/api.ts

@@ -0,0 +1,70 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as complete from "../complete.js";
+import type * as crons from "../crons.js";
+import type * as danger from "../danger.js";
+import type * as kick from "../kick.js";
+import type * as lib from "../lib.js";
+import type * as logging from "../logging.js";
+import type * as loop from "../loop.js";
+import type * as recovery from "../recovery.js";
+import type * as shared from "../shared.js";
+import type * as stats from "../stats.js";
+import type * as worker from "../worker.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  complete: typeof complete;
+  crons: typeof crons;
+  danger: typeof danger;
+  kick: typeof kick;
+  lib: typeof lib;
+  logging: typeof logging;
+  loop: typeof loop;
+  recovery: typeof recovery;
+  shared: typeof shared;
+  stats: typeof stats;
+  worker: typeof worker;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,117 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      cancel: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          id: string;
+          logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any,
+        Name
+      >;
+      cancelAll: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          before?: number;
+          limit?: number;
+          logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any,
+        Name
+      >;
+      enqueue: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          config: {
+            logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+            maxParallelism: number;
+          };
+          fnArgs: any;
+          fnHandle: string;
+          fnName: string;
+          fnType: "action" | "mutation" | "query";
+          onComplete?: { context?: any; fnHandle: string };
+          retryBehavior?: {
+            base: number;
+            initialBackoffMs: number;
+            maxAttempts: number;
+          };
+          runAt: number;
+        },
+        string,
+        Name
+      >;
+      enqueueBatch: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          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>,
+        Name
+      >;
+      status: FunctionReference<
+        "query",
+        "internal",
+        { id: string },
+        | { previousAttempts: number; state: "pending" }
+        | { previousAttempts: number; state: "running" }
+        | { state: "finished" },
+        Name
+      >;
+      statusBatch: FunctionReference<
+        "query",
+        "internal",
+        { ids: Array<string> },
+        Array<
+          | { previousAttempts: number; state: "pending" }
+          | { previousAttempts: number; state: "running" }
+          | { state: "finished" }
+        >,
+        Name
+      >;
+    };
+  };