@hamzasaleemorg/convex-kv 1.0.0

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,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("convexKv");

package/src/component/kv.test.ts

@@ -0,0 +1,51 @@
+/// <reference types="vite/client" />
+
+import { describe, expect, test } from "vitest";
+import { api } from "./_generated/api.js";
+import { initConvexTest } from "./setup.test.js";
+
+
+describe("component kv", () => {
+  test("basic kv operations", async () => {
+    const t = initConvexTest();
+
+    // Set and get
+    await t.mutation(api.kv.set, { key: ["users", "1"], value: { name: "Alice" } });
+    const user = await t.query(api.kv.get, { key: ["users", "1"] });
+    expect(user?.value).toEqual({ name: "Alice" });
+
+
+    // Has
+    const exists = await t.query(api.kv.has, { key: ["users", "1"] });
+    expect(exists).toBe(true);
+    const missing = await t.query(api.kv.has, { key: ["users", "2"] });
+    expect(missing).toBe(false);
+
+    // List with prefix
+    await t.mutation(api.kv.set, { key: ["users", "2"], value: { name: "Bob" } });
+    await t.mutation(api.kv.set, { key: ["posts", "1"], value: { title: "Post 1" } });
+
+    const users = await t.query(api.kv.list, { prefix: ["users"] });
+    expect(users.entries).toHaveLength(2);
+
+    const all = await t.query(api.kv.getAll, { prefix: [] });
+    expect(all).toHaveLength(3);
+
+    // Verify hierarchical isolation
+    await t.mutation(api.kv.set, { key: ["a"], value: "parent" });
+    await t.mutation(api.kv.set, { key: ["a", "b"], value: "child" });
+    await t.mutation(api.kv.set, { key: ["aa"], value: "sibling" });
+
+    const aPrefix = await t.query(api.kv.getAll, { prefix: ["a"] });
+    // Should contain ["a"] and ["a", "b"] but NOT ["aa"]
+    expect(aPrefix.map(e => e.key)).toContainEqual(["a"]);
+    expect(aPrefix.map(e => e.key)).toContainEqual(["a", "b"]);
+    expect(aPrefix.map(e => e.key)).not.toContainEqual(["aa"]);
+    expect(aPrefix.length).toBe(2);
+
+    // Delete
+    await t.mutation(api.kv.remove, { key: ["users", "1"] });
+    const userAfterDelete = await t.query(api.kv.get, { key: ["users", "1"] });
+    expect(userAfterDelete).toBeNull();
+  });
+});

package/src/component/kv.ts

@@ -0,0 +1,249 @@
+import { v } from "convex/values";
+import {
+  mutation,
+  query,
+} from "./_generated/server.js";
+import { api } from "./_generated/api.js";
+
+const DELIMITER = "\x00";
+
+function joinKey(key: string[]): string {
+  return key.join(DELIMITER);
+}
+
+/**
+ * Removes up to 100 expired keys.
+ * Can be scheduled periodically or called by a manager.
+ */
+export const vacuum = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    // Only fetch keys that EXPLICITLY have an expiresAt field and it is in the past
+    const expired = await ctx.db
+      .query("kv")
+      .withIndex("expiresAt", (q) => q.lt("expiresAt", now))
+      .take(100);
+
+    let deleted = 0;
+    for (const doc of expired) {
+      // Double check safety: never delete if expiresAt is missing or in the future
+      if (doc.expiresAt && doc.expiresAt < now) {
+        await ctx.db.delete(doc._id);
+        deleted++;
+      }
+    }
+    return { count: deleted };
+  },
+});
+
+export const get = query({
+  args: { key: v.array(v.string()) },
+  returns: v.union(v.null(), v.object({
+    key: v.array(v.string()),
+    value: v.any(),
+    metadata: v.optional(v.any()),
+    updatedAt: v.number(),
+    expiresAt: v.optional(v.number()),
+  })),
+  handler: async (ctx, args) => {
+    const path = joinKey(args.key);
+    const entry = await ctx.db
+      .query("kv")
+      .withIndex("path", (q) => q.eq("path", path))
+      .unique();
+    if (!entry) return null;
+
+    // Filter expired
+    if (entry.expiresAt && entry.expiresAt < Date.now()) {
+      return null;
+    }
+
+    return {
+      key: entry.key,
+      value: entry.value,
+      metadata: entry.metadata,
+      updatedAt: entry.updatedAt,
+      expiresAt: entry.expiresAt,
+    };
+  },
+});
+
+export const has = query({
+  args: { key: v.array(v.string()) },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const path = joinKey(args.key);
+    const entry = await ctx.db
+      .query("kv")
+      .withIndex("path", (q) => q.eq("path", path))
+      .unique();
+    if (!entry) return false;
+    // Filter expired
+    if (entry.expiresAt && entry.expiresAt < Date.now()) {
+      return false;
+    }
+    return true;
+  },
+});
+
+export const set = mutation({
+  args: {
+    key: v.array(v.string()),
+    value: v.any(),
+    metadata: v.optional(v.any()),
+    ttl: v.optional(v.number()),
+    expiresAt: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const path = joinKey(args.key);
+    const existing = await ctx.db
+      .query("kv")
+      .withIndex("path", (q) => q.eq("path", path))
+      .unique();
+
+    let expiresAt = args.expiresAt;
+    if (args.ttl !== undefined) {
+      expiresAt = Date.now() + args.ttl;
+    }
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        value: args.value,
+        metadata: args.metadata,
+        updatedAt: Date.now(),
+        // Explicitly clear or update expiresAt
+        expiresAt: expiresAt ?? (args.ttl === undefined && args.expiresAt === undefined ? undefined : existing.expiresAt),
+      });
+    } else {
+      await ctx.db.insert("kv", {
+        key: args.key,
+        path,
+        value: args.value,
+        metadata: args.metadata,
+        updatedAt: Date.now(),
+        expiresAt,
+      });
+    }
+
+    return null;
+  },
+});
+
+
+export const remove = mutation({
+  args: { key: v.array(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const path = joinKey(args.key);
+    const existing = await ctx.db
+      .query("kv")
+      .withIndex("path", (q) => q.eq("path", path))
+      .unique();
+    if (existing) {
+      await ctx.db.delete(existing._id);
+    }
+    return null;
+  },
+});
+
+/**
+ * Strict hierarchical range:
+ * If prefix is ["a"], path is "a".
+ * We want "a" and any "a\x00...".
+ * Lexicographically, "a\x00" < "a\x01".
+ * And "ab" > "a\x01".
+ * So [pathPrefix, pathPrefix + "\x01") correctly captures exactly the hierarchy.
+ */
+function getPrefixRange(q: any, pathPrefix: string) {
+  if (pathPrefix.length === 0) return q;
+  return q.gte("path", pathPrefix).lt("path", pathPrefix + "\x01");
+}
+
+export const list = query({
+  args: {
+    prefix: v.array(v.string()),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    includeValues: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const pathPrefix = joinKey(args.prefix);
+    const query = ctx.db.query("kv").withIndex("path", (q) => getPrefixRange(q, pathPrefix));
+
+    const results = await query.paginate({
+      numItems: args.limit ?? 100,
+      cursor: args.cursor ?? null,
+    });
+
+    const now = Date.now();
+    return {
+      entries: results.page
+        .filter(e => !e.expiresAt || e.expiresAt > now)
+        .map(e => ({
+          key: e.key,
+          ...(args.includeValues !== false ? { value: e.value } : {}),
+          metadata: e.metadata,
+          updatedAt: e.updatedAt,
+          expiresAt: e.expiresAt,
+        })),
+      continueCursor: results.continueCursor,
+      isDone: results.isDone,
+    };
+  },
+});
+
+export const getAll = query({
+  args: {
+    prefix: v.array(v.string()),
+    includeValues: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const pathPrefix = joinKey(args.prefix);
+    const entries = await ctx.db.query("kv").withIndex("path", (q) =>
+      getPrefixRange(q, pathPrefix)
+    ).take(1000);
+
+    const now = Date.now();
+    return entries
+      .filter(e => !e.expiresAt || e.expiresAt > now)
+      .map(e => ({
+        key: e.key,
+        ...(args.includeValues !== false ? { value: e.value } : {}),
+        metadata: e.metadata,
+        updatedAt: e.updatedAt,
+        expiresAt: e.expiresAt,
+      }));
+  },
+});
+
+
+
+export const deleteAll = mutation({
+  args: { prefix: v.array(v.string()) },
+  handler: async (ctx, args) => {
+    const pathPrefix = joinKey(args.prefix);
+    const entries = await ctx.db.query("kv").withIndex("path", (q) =>
+      getPrefixRange(q, pathPrefix)
+    ).take(101);
+
+    const toDelete = entries.slice(0, 100);
+    const hasMore = entries.length > 100;
+
+    for (const entry of toDelete) {
+      await ctx.db.delete(entry._id);
+    }
+
+    if (hasMore) {
+      await ctx.scheduler.runAfter(0, api.kv.deleteAll, {
+        prefix: args.prefix,
+      });
+    }
+
+    return {
+      deletedCount: toDelete.length,
+      hasMore,
+    };
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,16 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  kv: defineTable({
+    key: v.array(v.string()), // The hierarchical key as an array of segments
+    path: v.string(), // The key segments joined by a delimiter for prefix scans
+    value: v.any(), // The stored value
+    metadata: v.optional(v.any()), // Internal metadata (e.g., for validation)
+    updatedAt: v.number(),
+    expiresAt: v.optional(v.number()),
+  })
+    .index("path", ["path"])
+    .index("expiresAt", ["expiresAt"]),
+});
+

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "convexKv",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };