convex-deployment-kv

Tenant-scoped key-value store for Convex: TTL, optimistic revision CAS, and JSON prefix queries.

This is a Convex component. Install it with app.use(...). Call it from your app's queries and mutations — do not expose these functions directly to clients. Put auth in those wrappers.

vs @hamzasaleemorg/convex-kv

| | @hamzasaleemorg/convex-kv | convex-deployment-kv | |--|----------------------------|------------------------| | Key model | Hierarchical array keys | namespace + string key | | Multi-tenant | No built-in tenant partition | tenantId on every row | | TTL units | Milliseconds | Seconds | | Optimistic CAS | No | setIfRevisionMatches | | JSON queries | Prefix list / paginated scan | queryJsonByPrefix with sort/filter |

Use this package when you need tenant isolation, revision CAS, or prefix JSON queries from a Convex app or Node backend.

Install

npm install convex-deployment-kv

// convex/convex.config.ts
import { defineApp } from "convex/server";
import deploymentKv from "convex-deployment-kv/convex.config.js";

const app = defineApp();
app.use(deploymentKv);
export default app;

// convex/kv.ts — app wrapper (add your own auth here)
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";

export const get = query({
  args: { namespace: v.string(), key: v.string(), tenantId: v.optional(v.string()) },
  handler: async (ctx, args) => ctx.runQuery(components.deploymentKv.kv.get, args),
});

export const set = mutation({
  args: {
    namespace: v.string(),
    key: v.string(),
    value: v.any(),
    tenantId: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    // e.g. require ctx.auth or an API key before writing
    return ctx.runMutation(components.deploymentKv.kv.set, args);
  },
});

tenantId defaults to "default" when omitted.