@hamzasaleemorg/convex-kv

中文文档
1.0.3发布于 2026/03/09Apache-2.0TypeScriptES Module零依赖近 30 天下载 1.7万

Hierarchical Key-Value store for Convex

原始使用文档
文档目录9 节
  1. Installation
  2. Quick Start: Expiring Invite Links 🚀
  3. 🛠️ Why use this?
  4. API Reference
  5. Initializing the Client
  6. Core Operations
  7. Hierarchical & Range Operations
  8. Development & Testing
  9. License

Convex KV Component

npm version npm downloads License

A hierarchical, ordered key-value store for Convex. Replace relational boilerplate with a simple get/set API, featuring automatic TTL and recursive prefix deletion.

Installation

npm install @hamzasaleemorg/convex-kv
// convex/convex.config.ts
import { defineApp } from "convex/server";
import convexKv from "@hamzasaleemorg/convex-kv/convex.config.js";

const app = defineApp();
app.use(convexKv);

export default app;

Manage one-time magic links or invite codes without cluttering your main schema or writing cleanup logic.

// convex/invites.ts
import { kvClientFactory } from "@hamzasaleemorg/convex-kv";
import { components } from "./_generated/api";
import { mutation } from "./_generated/server";
import { v } from "convex/values";

const kv = kvClientFactory(components.convexKv);
const invites = kv.use<{ email: string; role: string }>(["invites"]);

export const createInvite = mutation({
  args: { email: v.string(), role: v.string() },
  handler: async (ctx, args) => {
    const inviteCode = Math.random().toString(36).substring(7);
    
    // Store invite that automatically EXPIRES in 48 hours
    await invites.set(ctx, [inviteCode], { 
      email: args.email, 
      role: args.role 
    }, { ttl: 48 * 60 * 60 * 1000 });
    
    return inviteCode;
  },
});

export const acceptInvite = mutation({
  args: { code: v.string() },
  handler: async (ctx, args) => {
    // If the link is older than 48hrs, .get() returns null automatically
    const invite = await invites.get(ctx, [args.code]);
    if (!invite) throw new Error("Invite invalid or expired");
    
    // ... create membership logic ...

    await invites.delete(ctx, [args.code]);
  },
});

🛠️ Why use this?

  1. Zero Schema Maintenance: Store any JSON-serializable data instantly. No new tables, no indexes to wait for.
  2. Organized Hierarchy: Use array keys like ["org", orgId, "settings"] to naturally isolate data.
  3. Automatic TTL: Set a ttl (ms) on any key and it disappear from queries as soon as it expires.
  4. Ordered Scans: Keys are stored lexicographically. Scan through millions of keys by prefix instantly.
  5. Batched Deletes: Clear an entire "folder" of data with deleteAll(["prefix"]). It automatically handles large datasets in the background.

API Reference

Initializing the Client

You can use the global client or scope it to a specific recursive namespace:

const kv = kvClientFactory(components.convexKv);

// Everything sent through 'users' will stay in that folder
const users = kv.use<{ email: string }>(["users"]);

Core Operations

MethodDescription
get(key)Returns value or null if missing/expired.
set(key, val, options?)Stores value. Options: ttl (ms), expiresAt, metadata.
has(key)Fast boolean check for existence (returns false if expired).
delete(key)Removes a specific key.

Hierarchical & Range Operations

MethodDescription
list(prefix, options?)Paginated scan within a namespace.
getAll(prefix)Returns all entries under a prefix (max 1000).
deleteAll(prefix)Recursive Delete. Safely clears an entire prefix tree in the background.

Development & Testing

npm install
npm run dev   # Starts the KV Explorer & Build Watcher
npm test      # Runs full suite (Unit + Component Integration)

License

Apache-2.0

版本与发布记录

@hamzasaleemorg/convex-kv 共发布 4 个版本,首次发布于 2026/01/31;过去 12 个月发布了 4 个版本。

版本发布日期距今
1.0.3latest2026/03/098 个月前
1.0.22026/01/319 个月前
1.0.12026/01/319 个月前
1.0.02026/01/319 个月前

关于 @hamzasaleemorg/convex-kv 的常见问题

@hamzasaleemorg/convex-kv 是什么?

Hierarchical Key-Value store for Convex

如何安装 @hamzasaleemorg/convex-kv?

在项目目录运行 npm install @hamzasaleemorg/convex-kv,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:convex(^1.31.7)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hamzasaleemorg/convex-kv 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hamzasaleemorg/convex-kv 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hamzasaleemorg/convex-kv 可以商用吗?

@hamzasaleemorg/convex-kv 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hamzasaleemorg/convex-kv 的下载量有多少?

根据 npm 官方下载统计,@hamzasaleemorg/convex-kv 在 2026/10/17 – 2026/11/15 这 30 天内被下载 17,499 次,日均约 583 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hamzasaleemorg/convex-kv 还在维护吗?

最新版本 1.0.3 发布于 2026/03/09(8 个月前);至今共发布 4 个版本,其中过去 12 个月发布了 4 个;首次发布于 2026/01/31。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。