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

package/src/component/schema.ts

@@ -0,0 +1,21 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { jsonValue } from "./validators";
+
+/**
+ * Sandboxed tables — the idempotency ledger's own concern. A `key` is unique
+ * within a `scope`; `result` carries the opaque host-owned outcome (never
+ * inspected). `expiresAt` is an absolute ms timestamp that bounds the grace
+ * window after which a key may be re-minted.
+ */
+export default defineSchema({
+  keys: defineTable({
+    key: v.string(),
+    scope: v.string(),
+    status: v.union(v.literal("inflight"), v.literal("done")),
+    result: v.optional(jsonValue),
+    expiresAt: v.number(),
+  })
+    .index("by_scope_key", ["scope", "key"])
+    .index("by_expires", ["expiresAt"]),
+});

package/src/component/validators.ts

@@ -0,0 +1,56 @@
+import { v } from "convex/values";
+
+/**
+ * Opaque host-owned outcome stored against a completed key. The component never
+ * inspects it — last-resort arbitrary data, aliased here rather than left bare
+ * in function signatures. The host narrows it at the {@link Idempotency} client
+ * boundary via an optional `resultValidator`.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the
+ * lint rule `convex-rules/no-bare-v-any` is satisfied by routing every arbitrary
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export const jsonValue = v.any();
+
+/**
+ * Result of {@link begin}. `fresh` — the key was just minted, the caller should
+ * do the work and then `complete`. `inflight` — another attempt holds the key;
+ * `expiresAt` is when the lease frees and `retryAfterMs` how long to back off
+ * before retrying. `done` — a prior attempt already completed; `result` carries
+ * the recorded outcome for a short-circuit replay.
+ */
+export const beginResult = v.union(
+  v.object({ state: v.literal("fresh") }),
+  v.object({
+    state: v.literal("inflight"),
+    expiresAt: v.number(),
+    retryAfterMs: v.number(),
+  }),
+  v.object({ state: v.literal("done"), result: v.optional(jsonValue) }),
+);
+
+/**
+ * Result of {@link complete}. `recorded: true` — the outcome was written.
+ * `recorded: false` — the claim was lost; `reason` distinguishes a never-claimed
+ * key (`missing`), a lease that expired before completion (`expired`), and a key
+ * already marked done by a prior attempt (`already_done`). A host that sees
+ * `recorded: false` knows its work finished but the ledger row was gone.
+ */
+export const completeResult = v.union(
+  v.object({ recorded: v.literal(true) }),
+  v.object({
+    recorded: v.literal(false),
+    reason: v.union(
+      v.literal("missing"),
+      v.literal("expired"),
+      v.literal("already_done"),
+    ),
+  }),
+);
+
+/** Stored projection of a key returned by {@link get}. */
+export const keyState = v.object({
+  status: v.union(v.literal("inflight"), v.literal("done")),
+  result: v.optional(jsonValue),
+  expiresAt: v.number(),
+});

package/src/shared.ts

@@ -0,0 +1,21 @@
+/** Shared constants used by both `client/` and `component/`. */
+
+export const COMPONENT_NAME = "idempotency";
+
+/** Default namespace when the host does not scope a key. */
+export const DEFAULT_SCOPE = "global";
+
+/**
+ * Default inflight lease: 60 seconds, in milliseconds. Short by design so a
+ * crashed worker's claim self-heals quickly and the key can be re-minted.
+ */
+export const DEFAULT_INFLIGHT_TTL_MS = 60_000;
+
+/**
+ * Default done grace window: 24 hours, in milliseconds. How long a recorded
+ * outcome replays before the key may be re-minted.
+ */
+export const DEFAULT_DONE_TTL_MS = 86_400_000;
+
+/** Default page size for a `purge` pass before the sweep self-reschedules. */
+export const DEFAULT_PURGE_BATCH = 200;

package/src/test.ts

@@ -0,0 +1,12 @@
+import type { TestConvex } from "convex-test";
+import schema from "./component/schema";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register this component with a `convex-test` instance so consuming apps can
+ * test integration: `import { register } from "@vllnt/convex-idempotency/test"`.
+ */
+export function register(t: TestConvex<typeof schema>, name = "idempotency"): void {
+  t.registerComponent(name, schema, modules);
+}