@vllnt/convex-idempotency 0.1.0-canary.6abc175

package/src/client/types.ts

@@ -0,0 +1,87 @@
+/** Public TypeScript surface for the idempotency client. */
+
+/**
+ * Validates and narrows an opaque stored `result` to the host's `TResult` at the
+ * client boundary. Receives the raw value the component replayed (`unknown`) and
+ * MUST return a typed `TResult` or throw. A `convex/values` validator's `.parse`
+ * (or a Zod `.parse`) fits directly; omit it to keep results unvalidated.
+ *
+ * @typeParam TResult - The host's stored outcome type.
+ */
+export type ResultParser<TResult> = (value: unknown) => TResult;
+
+/** Outcome of {@link Idempotency.begin} for a key. */
+export type BeginResult<TResult> =
+  | {
+      /** The key was just minted; do the work, then call `complete`. */
+      state: "fresh";
+    }
+  | {
+      /** Another attempt holds the key; do not re-run. */
+      state: "inflight";
+      /** Absolute ms timestamp when the inflight lease frees. */
+      expiresAt: number;
+      /** How long to back off (ms) before retrying — the crashed-worker self-heal window. */
+      retryAfterMs: number;
+    }
+  | {
+      /** A prior attempt already completed; `result` holds its outcome. */
+      state: "done";
+      /** The recorded outcome (absent if completed without one). */
+      result?: TResult;
+    };
+
+/** Outcome of {@link Idempotency.complete} — discriminated so a lost claim is detectable. */
+export type CompleteResult =
+  | {
+      /** The outcome was written to the ledger. */
+      recorded: true;
+    }
+  | {
+      /** The claim was lost; the work ran but its ledger row was gone. */
+      recorded: false;
+      /**
+       * `missing` — no key for this id/scope. `expired` — the inflight lease
+       * lapsed before completion. `already_done` — a prior attempt won the race.
+       */
+      reason: "missing" | "expired" | "already_done";
+    };
+
+/** Construction options for the {@link Idempotency} client. */
+export interface IdempotencyOptions<TResult> {
+  /** Namespace applied when a call omits `scope`. Default `"global"`. */
+  defaultScope?: string;
+  /**
+   * Inflight lease (ms) applied by `begin` when a call omits `inflightTtlMs`.
+   * Short by design so a crashed worker's claim self-heals. Default `60_000`.
+   */
+  defaultInflightTtlMs?: number;
+  /**
+   * Grace window (ms) applied by `complete` when a call omits `doneTtlMs` —
+   * how long a recorded outcome replays before the key may be re-minted.
+   * Default `86_400_000` (24h).
+   */
+  defaultDoneTtlMs?: number;
+  /**
+   * When set, `complete` upserts the key as `done` even if its inflight row had
+   * vanished (`missing`/`expired`) — recording finished work rather than dropping
+   * it. Default `false`. Overridable per `complete` call.
+   */
+  upsertOnMissing?: boolean;
+  /**
+   * Validates/narrows a stored `result` to `TResult` at the boundary. Applied to
+   * the `result` returned by `begin` (`done` replay) and `get`, and to the
+   * `result` passed into `complete` before it is stored. Throws on a mismatch.
+   */
+  resultValidator?: ResultParser<TResult>;
+}
+
+/** A key's stored state, as returned by {@link Idempotency.get}. */
+export interface KeyState<TResult> {
+  /** `inflight` while an attempt holds the key, `done` once completed. */
+  status: "inflight" | "done";
+  /** The recorded outcome, present only when `status` is `done`. */
+  result?: TResult;
+  /** Absolute ms timestamp after which the key may be re-minted. */
+  expiresAt: number;
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,56 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as crons from "../crons.js";
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as validators from "../validators.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  crons: typeof crons;
+  mutations: typeof mutations;
+  queries: typeof queries;
+  validators: typeof validators;
+}> = 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,67 @@
+/* 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> =
+  {
+    mutations: {
+      begin: FunctionReference<
+        "mutation",
+        "internal",
+        { inflightTtlMs: number; key: string; scope: string },
+        | { state: "fresh" }
+        | { expiresAt: number; retryAfterMs: number; state: "inflight" }
+        | { result?: any; state: "done" },
+        Name
+      >;
+      complete: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          doneTtlMs: number;
+          key: string;
+          result?: any;
+          scope: string;
+          upsertOnMissing: boolean;
+        },
+        | { recorded: true }
+        | { reason: "missing" | "expired" | "already_done"; recorded: false },
+        Name
+      >;
+      purge: FunctionReference<
+        "mutation",
+        "internal",
+        { batch: number; before?: number },
+        number,
+        Name
+      >;
+    };
+    queries: {
+      get: FunctionReference<
+        "query",
+        "internal",
+        { key: string; scope: string },
+        null | { expiresAt: number; result?: any; status: "inflight" | "done" },
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * 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: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * 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: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * 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: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * 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: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * 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: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * 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: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("idempotency");
+
+// Nest official child components here, e.g.:
+// import sharded from "@convex-dev/sharded-counter/convex.config";
+// component.use(sharded);
+
+export default component;

package/src/component/crons.ts

@@ -0,0 +1,23 @@
+import { cronJobs } from "convex/server";
+import { api } from "./_generated/api";
+
+/**
+ * Default sweep cadence and page size for the built-in prune cron. The cron is
+ * the component's own self-healing safety net — a host that wants a different
+ * cadence drives `purge` from its own scheduler instead (the client exposes it).
+ * Convex cron definitions are static per deployment, so cadence is a documented
+ * module constant rather than a mount-time option; the page size bounds each
+ * sweep and `purge` self-reschedules until the expired tail is clean.
+ */
+export const PRUNE_INTERVAL = { hours: 24 } as const;
+
+/** Rows deleted per `purge` pass before the sweep self-reschedules. */
+export const PRUNE_BATCH = 200;
+
+const crons = cronJobs();
+
+crons.interval("idempotency:prune", PRUNE_INTERVAL, api.mutations.purge, {
+  batch: PRUNE_BATCH,
+});
+
+export default crons;

package/src/component/mutations.ts

@@ -0,0 +1,195 @@
+import { ConvexError, v } from "convex/values";
+import { api } from "./_generated/api";
+import { mutation } from "./_generated/server";
+import { beginResult, completeResult, jsonValue } from "./validators";
+
+/**
+ * Claim `key` within `scope`. Time is read from the server (`Date.now()`) inside
+ * the handler — never supplied by the caller — so an adversarial clock cannot
+ * force a key to look expired or live. `inflightTtlMs` bounds the inflight lease:
+ * a crashed worker self-heals once its short lease lapses, after which the key is
+ * re-minted in place (the row id is reused, not deleted and re-inserted).
+ *
+ * **Expiry check order (intentional asymmetry):** `begin` checks expiry BEFORE
+ * the done-state. An expired done key is therefore re-minted `fresh` (the
+ * outcome's grace window has elapsed; the key behaves as never-seen). This is the
+ * correct recovery path — the done grace exists precisely to replay within the
+ * window; outside it the operation may safely re-run.
+ *
+ * @throws `ConvexError({ code: "INVALID_TTL" })` when `inflightTtlMs` is not a
+ *   positive finite number (≤ 0 or non-finite would produce `expiresAt ≤ now`,
+ *   immediately expiring the claim and breaking the dedup window).
+ */
+export const begin = mutation({
+  args: {
+    key: v.string(),
+    scope: v.string(),
+    inflightTtlMs: v.number(),
+  },
+  returns: beginResult,
+  handler: async (ctx, args) => {
+    if (!(args.inflightTtlMs > 0 && isFinite(args.inflightTtlMs))) {
+      throw new ConvexError({
+        code: "INVALID_TTL",
+        message: "inflightTtlMs must be a positive finite number",
+      });
+    }
+
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("keys")
+      .withIndex("by_scope_key", (q) =>
+        q.eq("scope", args.scope).eq("key", args.key),
+      )
+      .unique();
+
+    const expiresAt = now + args.inflightTtlMs;
+
+    if (existing === null) {
+      await ctx.db.insert("keys", {
+        key: args.key,
+        scope: args.scope,
+        status: "inflight",
+        expiresAt,
+      });
+      return { state: "fresh" as const };
+    }
+
+    if (existing.expiresAt <= now) {
+      await ctx.db.patch(existing._id, {
+        status: "inflight",
+        result: undefined,
+        expiresAt,
+      });
+      return { state: "fresh" as const };
+    }
+
+    if (existing.status === "done") {
+      return { state: "done" as const, result: existing.result };
+    }
+
+    return {
+      state: "inflight" as const,
+      expiresAt: existing.expiresAt,
+      retryAfterMs: existing.expiresAt - now,
+    };
+  },
+});
+
+/**
+ * Mark `key` `done`, recording `result` and extending the grace window by
+ * `doneTtlMs`. Returns a discriminated outcome so the host can detect a lost
+ * claim: `recorded: false` with `missing` (key never existed), `expired` (the
+ * inflight lease lapsed before completion), or `already_done` (a prior attempt
+ * won). When `upsertOnMissing` is set, a `missing`/`expired` key is written as
+ * `done` anyway — for hosts that would rather record the finished work than drop
+ * it. Time is server-sourced.
+ *
+ * **Expiry check order (intentional asymmetry):** `complete` checks the
+ * done-state BEFORE expiry. An expired done key therefore returns
+ * `already_done`, not `expired`. This is intentional: a worker that manages to
+ * call `complete` on a key that is already `done` — even if the done row's grace
+ * window has since lapsed — must not overwrite a prior winner's recorded outcome.
+ * The `expired` reason is reserved for inflight keys whose lease lapsed before
+ * the holder could complete; it does not apply to keys already marked done.
+ *
+ * @throws `ConvexError({ code: "INVALID_TTL" })` when `doneTtlMs` is not a
+ *   positive finite number (≤ 0 or non-finite would produce `expiresAt ≤ now`,
+ *   immediately expiring the done grace window on creation).
+ */
+export const complete = mutation({
+  args: {
+    key: v.string(),
+    scope: v.string(),
+    result: v.optional(jsonValue),
+    doneTtlMs: v.number(),
+    upsertOnMissing: v.boolean(),
+  },
+  returns: completeResult,
+  handler: async (ctx, args) => {
+    if (!(args.doneTtlMs > 0 && isFinite(args.doneTtlMs))) {
+      throw new ConvexError({
+        code: "INVALID_TTL",
+        message: "doneTtlMs must be a positive finite number",
+      });
+    }
+
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("keys")
+      .withIndex("by_scope_key", (q) =>
+        q.eq("scope", args.scope).eq("key", args.key),
+      )
+      .unique();
+
+    const expiresAt = now + args.doneTtlMs;
+
+    if (existing === null) {
+      if (args.upsertOnMissing) {
+        await ctx.db.insert("keys", {
+          key: args.key,
+          scope: args.scope,
+          status: "done",
+          result: args.result,
+          expiresAt,
+        });
+        return { recorded: true as const };
+      }
+      return { recorded: false as const, reason: "missing" as const };
+    }
+
+    if (existing.status === "done") {
+      return { recorded: false as const, reason: "already_done" as const };
+    }
+
+    if (existing.expiresAt <= now) {
+      if (args.upsertOnMissing) {
+        await ctx.db.patch(existing._id, {
+          status: "done",
+          result: args.result,
+          expiresAt,
+        });
+        return { recorded: true as const };
+      }
+      return { recorded: false as const, reason: "expired" as const };
+    }
+
+    await ctx.db.patch(existing._id, {
+      status: "done",
+      result: args.result,
+      expiresAt,
+    });
+    return { recorded: true as const };
+  },
+});
+
+/**
+ * Delete up to `batch` keys whose `expiresAt < before`, oldest first via the
+ * `by_expires` index. `before` defaults to the server clock (`Date.now()`) when
+ * omitted, so the built-in cron sweeps exactly the keys expired as of the run —
+ * a caller cannot pass a future cutoff it did not compute. If a full batch was
+ * removed there may be more, so the sweep self-reschedules through
+ * `ctx.scheduler` until a short batch signals the tail is clean. Idempotent:
+ * re-running only ever removes already-expired rows.
+ */
+export const purge = mutation({
+  args: { before: v.optional(v.number()), batch: v.number() },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const before = args.before ?? Date.now();
+    const stale = await ctx.db
+      .query("keys")
+      .withIndex("by_expires", (q) => q.lt("expiresAt", before))
+      .take(args.batch);
+    for (const row of stale) {
+      await ctx.db.delete(row._id);
+    }
+    if (stale.length === args.batch) {
+      await ctx.scheduler.runAfter(0, api.mutations.purge, {
+        before,
+        batch: args.batch,
+      });
+    }
+    return stale.length;
+  },
+});

package/src/component/queries.ts

@@ -0,0 +1,24 @@
+import { v } from "convex/values";
+import { query } from "./_generated/server";
+import { keyState } from "./validators";
+
+export const get = query({
+  args: { key: v.string(), scope: v.string() },
+  returns: v.union(v.null(), keyState),
+  handler: async (ctx, args) => {
+    const row = await ctx.db
+      .query("keys")
+      .withIndex("by_scope_key", (q) =>
+        q.eq("scope", args.scope).eq("key", args.key),
+      )
+      .unique();
+    if (row === null) {
+      return null;
+    }
+    return {
+      status: row.status,
+      result: row.result,
+      expiresAt: row.expiresAt,
+    };
+  },
+});