@convex-dev/workpool 0.1.3-alpha.0 → 0.2.0-alpha.0

package/README.md

@@ -6,6 +6,16 @@
 
 This Convex component pools actions and mutations to restrict parallel requests.
 
+- Configure multiple pools with different parallelism.
+- Retry failed actions (with backoff and jitter) for
+  [idempotent actions](#idempotency), fully configurable (respecting parallelism).
+- An `onComplete` callback so you can build durable, reliable workflows. Called
+  when the work is finished, whether it succeeded, failed, or was canceled.
+
+## Use cases
+
+### Separating and throttling async workloads
+
 Suppose you have some important async work, like sending verification emails,
 and some less important async work, like scraping data from an API. If all of
 these are scheduled with `ctx.scheduler.runAfter`, they'll compete with each
@@ -16,13 +26,14 @@ To resolve this problem, you can separate work into different pools.
 
 ```ts
 const emailPool = new Workpool(components.emailWorkpool, {
-  maxParallelism: 5,
+  maxParallelism: 10,
 });
 const scrapePool = new Workpool(components.scrapeWorkpool, {
-  maxParallelism: 1,
+  maxParallelism: 5,
 });
 
-export const signUp = mutation({
+export const userSignUp = mutation({
+  args: {...},
   handler: async (ctx, args) => {
     const userId = await ctx.db.insert("users", args);
     await emailPool.enqueueAction(ctx, internal.auth.sendEmailVerification, {
@@ -40,6 +51,95 @@ export const downloadLatestWeather = mutation({
 });
 ```
 
+### Durable, reliable workflows meet workpool
+
+#### Retry management
+
+Imagine that the payment processor is a 3rd party API, and they temporarily have an
+outage. Now imagine you implement your own action retrying logic for your busy app.
+You'll find very quickly that your entire backend is overwhelmed with retrying actions.
+This could bog down live traffic with background work, and/or cause you to exceed
+rate limits with the payment provider.
+
+Creating an upper bound on how much work will be done in parallel is a good way to
+mitigate this risk. Actions that are currently backing off awaiting retry will not tie
+up a thread in the workpool.
+
+#### Completion handling
+
+By handing off asynchronous work, it will be guaranteed to run, and with retries
+you can account for temporary failures, while avoiding a "stampeding herd"
+during third party outages.
+
+With the `onComplete` callback, you can define how to proceed after each step,
+whether that enqueues another job to the workpool, updates the database, etc.
+It will always be called, whether the work was successful, failed, or was
+canceled. See [below](#options-for-enqueueing-work) for more info.
+
+Example:
+
+```ts
+const pool = new Workpool(components.emailWorkpool, {
+  retryActionsByDefault: true,
+  defaultRetryBehavior: { maxAttempts: 3, initialBackoffMs: 1000, base: 2 },
+});
+
+//...
+
+await pool.enqueueAction(ctx, internal.email.send, args, {
+  onComplete: internal.email.emailSent,
+  context: { emailType, userId },
+  retry: false, // don't retry this action, as we can't guarantee idempotency.
+});
+
+export const emailSent = internalMutation({
+  args: {
+    workId: workIdValidator,
+    context: v.object({ emailType: v.string(), userId: v.id("users") }),
+    result: runResultValidator,
+  },
+  handler: async (ctx, args) => {
+    if (args.result.kind === "canceled") return;
+    await ctx.db.insert("userEmailLog", {
+      userId: args.context.userId,
+      emailType: args.context.emailType,
+      result: args.result.kind === "success" ? args.result.returnValue : null,
+      error: args.result.kind === "failed" ? args.result.error : null,
+    });
+    if (args.result.kind === "failed") {
+      await pool.enqueueAction(ctx, internal.email.checkResendStatus, args, {
+        retry: { maxAttempts: 10, initialBackoffMs: 250, base: 2 }, // custom
+        onComplete: internal.email.handleEmailStatus,
+        context: args.context,
+      });
+    }
+  },
+});
+```
+
+#### Idempotency?
+
+Idempotent actions are actions that can be run multiple times safely. This typically
+means they don't cause any side effects that would be a problem if executed twice or more.
+
+As an example of an unsafe, non-idempotent action, consider an action that charges
+a user's credit card without providing a unique transaction id to the payment
+processor. The first time the action is run, imagine that the API call succeeds to the
+payment provider, but then the action throws an exception before the transaction is marked
+finished in our Convex database. If the action is run twice, the user may be
+double charged for the transaction!
+
+If we alter this action to provide a consistent transaction id to the payment provider, they
+can simply NOOP the second payment attempt. The this makes the action idempotent, and
+it can safely be retried.
+
+If you're creating complex workflows with many steps involving 3rd party APIs:
+
+1.  You should ensure that each step is an idempotent Convex action.
+2.  You should use this component to manage these actions so it all just works!
+
+### Optimize OCC errors
+
 With limited parallelism, you can reduce
 [OCC errors](https://docs.convex.dev/error#1)
 from mutations that read and write the same data.
@@ -133,6 +233,41 @@ await pool.cancel(id);
 
 See more example usage in [example.ts](./example/convex/example.ts).
 
+### Configuring the Workpool
+
+Check out the [docstrings](./src/client/index.ts), but notable options include:
+
+- `maxParallelism`: How many actions/mutations can run at once within this pool.
+- `retryActionsByDefault`: Whether to retry actions that fail by default.
+- `defaultRetryBehavior`: The default retry behavior for enqueued actions.
+
+You can override the retry behavior per-call with the `retry` option.
+
+### Options for enqueueing work
+
+See the [docstrings](./src/client/index.ts) for more details, but notable options include:
+
+- `retry`: Whether to retry the action if it fails. Overrides defaults.
+  If it's set to `true`, it will use the `defaultRetryBehavior`.
+  If it's set to a custom config, it will use that (and do retries).
+- `onComplete`: A mutation to run after the function finishes.
+- `context`: Any data you want to pass to the `onComplete` mutation.
+- `runAt` and `runAfter`: Similar to `ctx.scheduler.run*`, allows you to
+  schedule the work to run later. By default it's immediate.
+
+### Retry behavior
+
+The retry options work like this:
+
+- The first request runs as it's scheduled.
+- If it fails, it will wait _around_ `initialBackoffMs` and then try again.
+- Each subsequent retry waits `initialBackoffMs * base^<retryNumber - 1>`.
+- The standard base is 2.
+- The actual wait time uses "jitter" to avoid all retries happening at once,
+  if they all failed at the same time.
+
+You can override the retry behavior per-call with the `retry` option.
+
 ## Optimizations with and without Workpool
 
 The benefit of Workpool is that it won't fall over if there are many jobs
@@ -168,23 +303,19 @@ You can read the status of a function by calling `pool.status(id)`.
 
 The status will be one of:
 
-- `{ kind: "pending" }`: The function has not started yet.
-- `{ kind: "inProgress" }`: The function is currently running.
-- `{ kind: "completed"; completionStatus: CompletionStatus }`: The function has
-  finished.
-
-The `CompletionStatus` type is one of:
-
-- `"success"`: The function completed successfully.
-- `"error"`: The function threw an error.
-- `"canceled"`: The function was canceled.
-- `"timeout"`: The function timed out.
+- `{ kind: "pending"; previousAttempts: number }`: The function has not started yet.
+- `{ kind: "running"; previousAttempts: number }`: The function is currently running.
+- `{ kind: "finished" }`: The function has succeeded, failed, or been canceled.
 
 ## Canceling work
 
-You can cancel work by calling `pool.cancel(id)`.
+You can cancel work by calling `pool.cancel(id)` or all of them with
+`pool.cancelAll()`.
 
-This will remove the work from the queue and mark it as canceled.
-If
+This will avoid starting or retrying, but will not stop in-progress work.
 
 <!-- END: Include on https://convex.dev/components -->
+
+```
+
+```

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

@@ -1,53 +1,141 @@
-import { DefaultFunctionArgs, Expand, FunctionReference, FunctionVisibility, GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
-import { GenericId } from "convex/values";
-import { api } from "../component/_generated/api.js";
-import { LogLevel } from "../component/logging.js";
-import { completionStatus, type CompletionStatus } from "../component/schema.js";
-export { completionStatus, type CompletionStatus };
-export type WorkId = string;
+import { DefaultFunctionArgs, FunctionReference, FunctionVisibility } from "convex/server";
+import { VString } from "convex/values";
+import { Mounts } from "../component/_generated/api.js";
+import { runResult as runResultValidator, RunResult, type RetryBehavior, Status } from "../component/shared.js";
+import { type LogLevel } from "../component/logging.js";
+import { RunMutationCtx, RunQueryCtx, UseApi } from "./utils.js";
+export { runResultValidator, type RunResult };
+export declare const DEFAULT_RETRY_BEHAVIOR: RetryBehavior;
+export type WorkId = string & {
+    __isWorkId: true;
+};
+export declare const workIdValidator: VString<WorkId, "required">;
 export declare class Workpool {
     private component;
     private options;
-    constructor(component: UseApi<typeof api>, 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 options for the Workpool.
+     */
+    constructor(component: UseApi<Mounts>, // UseApi<api> for jump to definition
+    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.
+        maxParallelism?: number;
+        /** How much to log. This is updated on each call to `enqueue*`,
+         * `status`, or `cancel*`.
+         * Default is WARN.
          * With INFO, you can see events for started and completed work, which can
-         * be parsed.
+         * be parsed by tools like [Axiom](https://axiom.co) for monitoring.
          * 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.
+        /** Default retry behavior for enqueued actions. */
+        defaultRetryBehavior?: RetryBehavior;
+        /** Whether to retry actions that fail by default. Default: false.
+         * NOTE: Only do this if your actions are idempotent.
+         * See the docs (README.md) for more details.
          */
-        statusTtl?: number;
+        retryActionsByDefault?: boolean;
     });
-    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>;
+    /**
+     * 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.
+     */
+    enqueueAction<Args extends DefaultFunctionArgs, ReturnType>(ctx: RunMutationCtx, fn: FunctionReference<"action", FunctionVisibility, Args, ReturnType>, fnArgs: Args, options?: {
+        /** Whether to retry the action if it fails.
+         * 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.
+         */
+        retry?: boolean | RetryBehavior;
+    } & CallbackOptions & SchedulerOptions): Promise<WorkId>;
+    /**
+     * 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`.
+     */
+    enqueueMutation<Args extends DefaultFunctionArgs, ReturnType>(ctx: RunMutationCtx, fn: FunctionReference<"mutation", FunctionVisibility, Args, ReturnType>, fnArgs: Args, options?: CallbackOptions & SchedulerOptions): Promise<WorkId>;
     cancel(ctx: RunMutationCtx, id: WorkId): Promise<void>;
-    status(ctx: RunQueryCtx, id: WorkId): Promise<{
-        kind: "pending";
-    } | {
-        kind: "inProgress";
-    } | {
-        kind: "completed";
-        completionStatus: CompletionStatus;
-    }>;
+    cancelAll(ctx: RunMutationCtx): Promise<void>;
+    status(ctx: RunQueryCtx, id: WorkId): Promise<Status>;
 }
-type RunQueryCtx = {
-    runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+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 = {
+    /**
+     * 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.
+     * e.g.
+     * ```ts
+     * export const completion = internalMutation({
+     *  args: {
+     *    workId: workIdValidator,
+     *    context: v.any(),
+     *    result: runResult,
+     *  },
+     *  handler: async (ctx, args) => {
+     *    console.log(args.result, "Got Context back -> ", args.context, Date.now() - args.context);
+     *  },
+     * });
+     * ```
+     */
+    onComplete?: FunctionReference<"mutation", FunctionVisibility, OnCompleteArgs> | null;
+    /**
+     * A context object to pass to the `onComplete` mutation.
+     * Useful for passing data from the enqueue site to the onComplete site.
+     */
+    context?: unknown;
 };
-type RunMutationCtx = {
-    runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+export type OnCompleteArgs = {
+    /**
+     * The ID of the work that completed.
+     */
+    workId: WorkId;
+    /**
+     * The context object passed when enqueuing the work.
+     * Useful for passing data from the enqueue site to the onComplete site.
+     */
+    context: unknown;
+    /**
+     * The result of the run that completed.
+     */
+    result: RunResult;
 };
-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/commonjs/client/index.d.ts.map

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

package/dist/commonjs/client/index.js

@@ -1,40 +1,147 @@
 import { createFunctionHandle, getFunctionName, } from "convex/server";
-import { completionStatus, } from "../component/schema.js";
-export { completionStatus };
+import { v } from "convex/values";
+import { runResult as runResultValidator, } from "../component/shared.js";
+import { logLevel } from "../component/logging.js";
+import { DEFAULT_LOG_LEVEL } from "../component/logging.js";
+import { DEFAULT_MAX_PARALLELISM } from "../component/kick.js";
+export { runResultValidator };
+// Attempts will run with delay [0, 250, 500, 1000, 2000] (ms)
+export const DEFAULT_RETRY_BEHAVIOR = {
+    maxAttempts: 5,
+    initialBackoffMs: 250,
+    base: 2,
+};
+export const workIdValidator = v.string();
 export class Workpool {
     component;
     options;
-    constructor(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 options for the Workpool.
+     */
+    constructor(component, // UseApi<api> for jump to definition
+    options) {
         this.component = component;
         this.options = options;
     }
-    async enqueueAction(ctx, fn, fnArgs) {
-        const fnHandle = await createFunctionHandle(fn);
+    /**
+     * 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, {
-            fnHandle,
-            fnName: getFunctionName(fn),
+            ...(await defaultEnqueueArgs(fn, this.options)),
             fnArgs,
             fnType: "action",
-            options: this.options,
+            runAt: getRunAt(options),
+            onComplete,
+            retryBehavior,
         });
         return id;
     }
-    async enqueueMutation(ctx, fn, fnArgs) {
-        const fnHandle = await createFunctionHandle(fn);
+    /**
+     * 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 id = await ctx.runMutation(this.component.lib.enqueue, {
-            fnHandle,
-            fnName: getFunctionName(fn),
+            ...(await defaultEnqueueArgs(fn, this.options)),
             fnArgs,
             fnType: "mutation",
-            options: this.options,
+            runAt: getRunAt(options),
         });
         return id;
     }
     async cancel(ctx, id) {
-        await ctx.runMutation(this.component.lib.cancel, { id });
+        await ctx.runMutation(this.component.lib.cancel, {
+            id,
+            logLevel: this.options.logLevel ?? getDefaultLogLevel(),
+        });
+    }
+    async cancelAll(ctx) {
+        await ctx.runMutation(this.component.lib.cancelAll, {
+            logLevel: this.options.logLevel ?? getDefaultLogLevel(),
+        });
     }
     async status(ctx, id) {
-        return await ctx.runQuery(this.component.lib.status, { id });
+        return ctx.runQuery(this.component.lib.status, { id });
+    }
+}
+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, { logLevel, maxParallelism }) {
+    return {
+        fnHandle: await createFunctionHandle(fn),
+        fnName: getFunctionName(fn),
+        config: {
+            logLevel: logLevel ?? getDefaultLogLevel(),
+            maxParallelism: maxParallelism ?? DEFAULT_MAX_PARALLELISM,
+        },
+    };
+}
+// ensure OnCompleteArgs satisfies SharedOnCompleteArgs
+const _ = {};
+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();
+}
+function getDefaultLogLevel() {
+    if (process.env.WORKPOOL_LOG_LEVEL) {
+        if (!logLevel.members
+            .map((m) => m.value)
+            .includes(process.env.WORKPOOL_LOG_LEVEL)) {
+            console.warn(`Invalid log level (${process.env.WORKPOOL_LOG_LEVEL}), defaulting to "INFO"`);
+        }
+        else {
+            return process.env.WORKPOOL_LOG_LEVEL;
+        }
     }
+    return DEFAULT_LOG_LEVEL;
 }
 //# sourceMappingURL=index.js.map

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

@@ -1 +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,EACL,gBAAgB,GAEjB,MAAM,wBAAwB,CAAC;AAChC,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/client/utils.d.ts

@@ -0,0 +1,16 @@
+import { Expand, FunctionReference, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import { GenericId } from "convex/values";
+import { GenericDataModel } from "convex/server";
+export type RunQueryCtx = {
+    runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+export 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=utils.d.ts.map

package/dist/commonjs/client/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/client/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIjD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,aAAa,CAAC,CAAC;CAClE,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,GACzB,MAAM,GACN,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,SAAS,CAAC,CAAC,CAAC,EAAE,GACd,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACnC,CAAC,CAAC;AAEZ,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC;KAC9B,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,iBAAiB,CACpD,MAAM,KAAK,EACX,QAAQ,EACR,MAAM,KAAK,EACX,MAAM,WAAW,EACjB,MAAM,cAAc,CACrB,GACG,iBAAiB,CACf,KAAK,EACL,UAAU,EACV,SAAS,CAAC,KAAK,CAAC,EAChB,SAAS,CAAC,WAAW,CAAC,EACtB,cAAc,CACf,GACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACrB,CAAC,CAAC"}

package/dist/commonjs/client/utils.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.js.map

package/dist/commonjs/client/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/client/utils.ts"],"names":[],"mappings":""}