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

package/dist/component/_generated/component.js

@@ -0,0 +1,11 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+export {};
+//# sourceMappingURL=component.js.map

package/dist/component/_generated/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/component/_generated/component.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG"}

package/dist/component/_generated/dataModel.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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>;
+//# sourceMappingURL=dataModel.d.ts.map

package/dist/component/_generated/dataModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataModel.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/dataModel.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,6BAA6B,EAC7B,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,MAAM,MAAM,cAAc,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,GAAG,CAAC,SAAS,SAAS,UAAU,IAAI,cAAc,CAC5D,SAAS,EACT,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,EAAE,CAAC,SAAS,SAAS,UAAU,GAAG,gBAAgB,IAC5D,SAAS,CAAC,SAAS,CAAC,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,6BAA6B,CAAC,OAAO,MAAM,CAAC,CAAC"}

package/dist/component/_generated/dataModel.js

@@ -0,0 +1,11 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+export {};
+//# sourceMappingURL=dataModel.js.map

package/dist/component/_generated/dataModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataModel.js","sourceRoot":"","sources":["../../../src/component/_generated/dataModel.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG"}

package/dist/component/_generated/server.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 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 declare const query: QueryBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalQuery: QueryBuilder<DataModel, "internal">;
+/**
+ * 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 declare const mutation: MutationBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalMutation: MutationBuilder<DataModel, "internal">;
+/**
+ * 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 declare const action: ActionBuilder<DataModel, "public">;
+/**
+ * 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 declare const internalAction: ActionBuilder<DataModel, "internal">;
+/**
+ * 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 declare const httpAction: HttpActionBuilder;
+/**
+ * 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>;
+//# sourceMappingURL=server.d.ts.map

package/dist/component/_generated/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAUvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAgB,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CACxC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAmB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,CAC3C,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAiB,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,CACzC,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAqC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC"}

package/dist/component/_generated/server.js

@@ -0,0 +1,78 @@
+/* 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 { actionGeneric, httpActionGeneric, queryGeneric, mutationGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, } from "convex/server";
+/**
+ * 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 = 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 = 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 = 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 = 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 = 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 = 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 = httpActionGeneric;
+//# sourceMappingURL=server.js.map

package/dist/component/_generated/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAaH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsC,YAAY,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,oBAAoB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAyC,eAAe,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAuC,aAAa,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,iBAAiB,CAAC"}

package/dist/component/convex.config.d.ts

@@ -0,0 +1,3 @@
+declare const component: import("convex/server").ComponentDefinition<any, {}>;
+export default component;
+//# sourceMappingURL=convex.config.d.ts.map

package/dist/component/convex.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,SAAS,sDAAiC,CAAC;AAMjD,eAAe,SAAS,CAAC"}

package/dist/component/convex.config.js

@@ -0,0 +1,7 @@
+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;
+//# sourceMappingURL=convex.config.js.map

package/dist/component/convex.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.js","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,SAAS,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;AAEjD,6CAA6C;AAC7C,mEAAmE;AACnE,0BAA0B;AAE1B,eAAe,SAAS,CAAC"}

package/dist/component/crons.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare const PRUNE_INTERVAL: {
+    readonly hours: 24;
+};
+/** Rows deleted per `purge` pass before the sweep self-reschedules. */
+export declare const PRUNE_BATCH = 200;
+declare const crons: import("convex/server").Crons;
+export default crons;
+//# sourceMappingURL=crons.d.ts.map

package/dist/component/crons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crons.d.ts","sourceRoot":"","sources":["../../src/component/crons.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;CAAyB,CAAC;AAErD,uEAAuE;AACvE,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,QAAA,MAAM,KAAK,+BAAa,CAAC;AAMzB,eAAe,KAAK,CAAC"}

package/dist/component/crons.js

@@ -0,0 +1,19 @@
+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 };
+/** 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;
+//# sourceMappingURL=crons.js.map

package/dist/component/crons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crons.js","sourceRoot":"","sources":["../../src/component/crons.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,KAAK,EAAE,EAAE,EAAW,CAAC;AAErD,uEAAuE;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;AAEzB,KAAK,CAAC,QAAQ,CAAC,mBAAmB,EAAE,cAAc,EAAE,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE;IACvE,KAAK,EAAE,WAAW;CACnB,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/dist/component/mutations.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 declare const begin: import("convex/server").RegisteredMutation<"public", {
+    key: string;
+    scope: string;
+    inflightTtlMs: number;
+}, Promise<{
+    state: "fresh";
+    result?: undefined;
+    expiresAt?: undefined;
+    retryAfterMs?: undefined;
+} | {
+    state: "done";
+    result: any;
+    expiresAt?: undefined;
+    retryAfterMs?: undefined;
+} | {
+    state: "inflight";
+    expiresAt: number;
+    retryAfterMs: number;
+    result?: undefined;
+}>>;
+/**
+ * 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 declare const complete: import("convex/server").RegisteredMutation<"public", {
+    result?: any;
+    key: string;
+    scope: string;
+    doneTtlMs: number;
+    upsertOnMissing: boolean;
+}, Promise<{
+    recorded: true;
+    reason?: undefined;
+} | {
+    recorded: false;
+    reason: "missing";
+} | {
+    recorded: false;
+    reason: "already_done";
+} | {
+    recorded: false;
+    reason: "expired";
+}>>;
+/**
+ * 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 declare const purge: import("convex/server").RegisteredMutation<"public", {
+    before?: number | undefined;
+    batch: number;
+}, Promise<number>>;
+//# sourceMappingURL=mutations.d.ts.map

package/dist/component/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../src/component/mutations.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;GAsDhB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;GAgEnB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK;;;mBAoBhB,CAAC"}

package/dist/component/mutations.js

@@ -0,0 +1,177 @@
+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" };
+        }
+        if (existing.expiresAt <= now) {
+            await ctx.db.patch(existing._id, {
+                status: "inflight",
+                result: undefined,
+                expiresAt,
+            });
+            return { state: "fresh" };
+        }
+        if (existing.status === "done") {
+            return { state: "done", result: existing.result };
+        }
+        return {
+            state: "inflight",
+            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 };
+            }
+            return { recorded: false, reason: "missing" };
+        }
+        if (existing.status === "done") {
+            return { recorded: false, reason: "already_done" };
+        }
+        if (existing.expiresAt <= now) {
+            if (args.upsertOnMissing) {
+                await ctx.db.patch(existing._id, {
+                    status: "done",
+                    result: args.result,
+                    expiresAt,
+                });
+                return { recorded: true };
+            }
+            return { recorded: false, reason: "expired" };
+        }
+        await ctx.db.patch(existing._id, {
+            status: "done",
+            result: args.result,
+            expiresAt,
+        });
+        return { recorded: true };
+    },
+});
+/**
+ * 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;
+    },
+});
+//# sourceMappingURL=mutations.js.map

package/dist/component/mutations.js.map

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

package/dist/component/queries.d.ts

@@ -0,0 +1,9 @@
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    key: string;
+    scope: string;
+}, Promise<{
+    status: "inflight" | "done";
+    result: any;
+    expiresAt: number;
+} | null>>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/component/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/component/queries.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,GAAG;;;;;;;UAmBd,CAAC"}