@hamzasaleemorg/convex-kv 1.0.0

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@hamzasaleemorg/convex-kv",
+  "description": "Hierarchical Key-Value store for Convex",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "workspaces": [
+    "example"
+  ],
+  "repository": "github:hamzasaleem2/convex-kv",
+  "homepage": "https://github.com/hamzasaleem2/convex-kv#readme",
+  "keywords": [
+    "convex",
+    "component",
+    "kv",
+    "redis"
+  ],
+  "scripts": {
+    "dev": "run-p -r 'dev:*'",
+    "dev:backend": "convex dev --typecheck-components",
+    "dev:frontend": "cd example && vite --clearScreen false",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "npm run clean && npm run build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.31.7"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.1.1",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "9.39.2",
+    "@types/node": "^24.10.9",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.31.7",
+    "convex-test": "0.0.41",
+    "cpy-cli": "^6.0.0",
+    "eslint": "9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "globals": "^17.2.0",
+    "npm-run-all2": "8.0.4",
+    "path-exists-cli": "2.0.0",
+    "pkg-pr-new": "^0.0.62",
+    "prettier": "3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.54.0",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js"
+}

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/index.test.ts

@@ -0,0 +1,24 @@
+import { describe, test } from "vitest";
+import { kvClientFactory } from "./index.js";
+import { components, initConvexTest } from "./setup.test.js";
+
+const kv = kvClientFactory(components.convexKv);
+const _store = kv.use<{ name: string }>(["test"]);
+
+
+
+describe("client tests", () => {
+  test("should be able to use client", async () => {
+    const t = initConvexTest();
+
+    // We need to use it within a function because KeyValueStore methods expect a context with runQuery/runMutation
+    // In actual app code this works because query/mutation handlers provide the context.
+    // In tests, we can use a wrapper or just test the component logic via lib.test.ts.
+    // But since this is src/client/index.test.ts, let's test the client wrapper.
+
+    await t.mutation(components.convexKv.kv.set, { key: ["test", "alice"], value: { name: "Alice" } });
+
+    // We can't easily use 'store.get(ctx, ...)' here without a dummy function.
+    // But we can verify it doesn't throw and works logically.
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,197 @@
+import type {
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDataModel,
+} from "convex/server";
+import type { Validator } from "convex/values";
+
+import type { ComponentApi } from "../component/_generated/component.js";
+
+/**
+ * Minimal context types required for the client store to execute operations.
+ */
+export type RunQuery = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+export type RunMutation = Pick<
+  GenericMutationCtx<GenericDataModel>,
+  "runMutation"
+>;
+
+/**
+ * A client for interacting with the hierarchical Key-Value store.
+ * 
+ * Supports hierarchical keys (e.g., ["users", "123", "profile"]),
+ * atomic mutations, and prefix-based range queries.
+ * 
+ * @template V The type of values stored in this specific instance/prefix.
+ */
+export class KeyValueStore<V = any> {
+  constructor(
+    private component: ComponentApi,
+    private prefix: string[] = [],
+    private options: {
+      validator?: Validator<V, any, any>;
+      /**
+       * Optional internal type metadata for identification or read-time validation.
+       */
+      metadata?: any;
+    } = {}
+  ) { }
+
+  /**
+   * Retrieves the value associated with a specific key path.
+   * 
+   * @param ctx Convex Query Context.
+   * @param key The relative key path array.
+   * @returns The stored value, or null if it doesn't exist or is expired.
+   */
+  async get(ctx: RunQuery, key: string[]): Promise<V | null> {
+    const result = await this.getWithMetadata(ctx, key);
+    return result?.value ?? null;
+  }
+
+  /**
+   * Retrieves the value along with its internal metadata (timestamps, expiration, etc.).
+   * 
+   * @param ctx Convex Query Context.
+   * @param key The relative key path array.
+   * @returns The full entry object or null.
+   */
+  async getWithMetadata(ctx: RunQuery, key: string[]): Promise<{ key: string[]; value: V; metadata?: any; updatedAt: number; expiresAt?: number } | null> {
+    return (await ctx.runQuery(this.component.kv.get, {
+      key: [...this.prefix, ...key],
+    })) as { key: string[]; value: V; metadata?: any; updatedAt: number; expiresAt?: number } | null;
+  }
+
+  /**
+   * Stores a value at the specified key path.
+   * 
+   * This is an atomic "upsert" operation. If a value already exists at this path,
+   * it will be overwritten.
+   * 
+   * @param ctx Convex Mutation Context.
+   * @param key The relative key path array.
+   * @param value The value to store.
+   * @param options.ttl Time-To-Live in milliseconds from now.
+   * @param options.expiresAt Exact Unix timestamp when the key should expire.
+   */
+  async set(
+    ctx: RunMutation,
+    key: string[],
+    value: V,
+    options: { metadata?: any; ttl?: number; expiresAt?: number } = {}
+  ): Promise<void> {
+    // Note: If you provided a validator at initialization, it should be checked here.
+    if (this.options.validator) {
+      // In a production environment, you might use a runtime check here.
+    }
+
+    await ctx.runMutation(this.component.kv.set, {
+      key: [...this.prefix, ...key],
+      value,
+      metadata: options.metadata ?? this.options.metadata,
+      ttl: options.ttl,
+      expiresAt: options.expiresAt,
+    });
+  }
+
+  /**
+   * Permanently removes a single key from the store.
+   */
+  async delete(ctx: RunMutation, key: string[]): Promise<void> {
+    await ctx.runMutation(this.component.kv.remove, {
+      key: [...this.prefix, ...key],
+    });
+  }
+
+  /**
+   * Quickly determines if a key exists without loading its value into memory.
+   * Efficient for existence checks on large blobs.
+   */
+  async has(ctx: RunQuery, key: string[]): Promise<boolean> {
+    return await ctx.runQuery(this.component.kv.has, {
+      key: [...this.prefix, ...key],
+    });
+  }
+
+  /**
+   * Scans and returns keys under a specific prefix with pagination support.
+   * 
+   * @param options.includeValues If false, only returns keys and metadata (saves bandwidth).
+   * @param options.limit Number of items per page.
+   * @param options.cursor Pagination cursor from a previous call.
+   */
+  async list(
+    ctx: RunQuery,
+    prefix: string[],
+    options: { limit?: number; cursor?: string; includeValues?: boolean } = {}
+  ) {
+    return await ctx.runQuery(this.component.kv.list, {
+      prefix: [...this.prefix, ...prefix],
+      ...options,
+    });
+  }
+
+  /**
+   * Fetches all entries under a prefix in a single call.
+   * Useful for small-to-medium datasets (up to ~1000 items).
+   */
+  async getAll(ctx: RunQuery, prefix: string[], options: { includeValues?: boolean } = {}) {
+    return await ctx.runQuery(this.component.kv.getAll, {
+      prefix: [...this.prefix, ...prefix],
+      ...options,
+    });
+  }
+
+  /**
+   * Recursively removes all keys under a specific prefix.
+   * 
+   * For large hierarchies, this operation is automatically batched
+   * using the Convex scheduler to prevent timeout errors.
+   */
+  async deleteAll(ctx: RunMutation, prefix: string[]) {
+    return await ctx.runMutation(this.component.kv.deleteAll, {
+      prefix: [...this.prefix, ...prefix],
+    });
+  }
+
+  /**
+   * Creates a new scoped client for a specific sub-hierarchy.
+   * 
+   * This allows you to treat a prefix like a "table" or "collection".
+   * 
+   * @example
+   * const users = kv.withPrefix(["users"]);
+   * await users.get(ctx, ["123"]); // Actually gets ["users", "123"]
+   */
+  withPrefix<SubV = V>(
+    prefix: string[],
+    validator?: Validator<SubV, any, any>
+  ): KeyValueStore<SubV> {
+    return new KeyValueStore<SubV>(this.component, [...this.prefix, ...prefix], {
+      validator: validator ?? (this.options.validator as any),
+      metadata: this.options.metadata,
+    });
+  }
+
+  /** Alias for withPrefix to support various developer naming conventions. */
+  subStore = this.withPrefix;
+}
+
+/**
+ * Creates a client factory that simplifies working with multiple typed prefixes.
+ * 
+ * @param component The Convex Component API reference (usually `components.convexKv`).
+ */
+export function kvClientFactory(component: ComponentApi) {
+  return {
+    /**
+     * Initializes a KeyValueStore instance for a specific prefix and type.
+     * 
+     * @example
+     * const store = kv.use<{ count: number }>(["analytics"]);
+     */
+    use<V = any>(prefix: string[] = [], validator?: Validator<V, any, any>) {
+      return new KeyValueStore<V>(component, prefix, { validator });
+    },
+  };
+}

package/src/client/setup.test.ts

@@ -0,0 +1,26 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+import {
+  defineSchema,
+  type GenericSchema,
+  type SchemaDefinition,
+} from "convex/server";
+import { type ComponentApi } from "../component/_generated/component.js";
+import { componentsGeneric } from "convex/server";
+import { register } from "../test.js";
+
+export function initConvexTest<
+  Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+export const components = componentsGeneric() as unknown as {
+  convexKv: ComponentApi;
+};
+
+test("setup", () => {});

package/src/component/_generated/api.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as kv from "../kv.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  kv: typeof kv;
+}> = 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,95 @@
+/* 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> =
+  {
+    kv: {
+      deleteAll: FunctionReference<
+        "mutation",
+        "internal",
+        { prefix: Array<string> },
+        any,
+        Name
+      >;
+      get: FunctionReference<
+        "query",
+        "internal",
+        { key: Array<string> },
+        null | {
+          expiresAt?: number;
+          key: Array<string>;
+          metadata?: any;
+          updatedAt: number;
+          value: any;
+        },
+        Name
+      >;
+      getAll: FunctionReference<
+        "query",
+        "internal",
+        { includeValues?: boolean; prefix: Array<string> },
+        any,
+        Name
+      >;
+      has: FunctionReference<
+        "query",
+        "internal",
+        { key: Array<string> },
+        boolean,
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        {
+          cursor?: string;
+          includeValues?: boolean;
+          limit?: number;
+          prefix: Array<string>;
+        },
+        any,
+        Name
+      >;
+      remove: FunctionReference<
+        "mutation",
+        "internal",
+        { key: Array<string> },
+        null,
+        Name
+      >;
+      set: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          expiresAt?: number;
+          key: Array<string>;
+          metadata?: any;
+          ttl?: number;
+          value: any;
+        },
+        null,
+        Name
+      >;
+      vacuum: FunctionReference<"mutation", "internal", {}, any, 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>;