@hamzasaleemorg/convex-kv

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

Convex 的分级密钥- Value 商店

中文使用文档
文档目录9 节
  1. 安装
  2. 快速启动: 过期邀请链接 QQ
  3. 为什么用这个?
  4. API 参考
  5. 初始化客户端
  6. 核心业务
  7. 等级范围操作( R)
  8. 开发和测试
  9. 许可证

Convex KV 组件

npm version npm downloads License

一个分级的,为Convex订购的密钥价值商店. 将相干锅炉取而代之 get编号 :set API,以自动TTL和递归前缀删除为主.

安装

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;

管理一次性的魔法链接或邀请代码,而不克扣您的主要策略或写出清除逻辑.

// 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]);
  },
});

为什么用这个?

  1. 0舍马维护: 立即存储任何 JSON 序列数据 。 没有新的表格,没有索引等待.
  2. 有组织的等级制度: 使用数组密钥, 如 ["org", orgId, "settings"] 自然分离数据.
  3. 自动 TTL: 设置 ttl 任何密钥上,一旦失效,就会从询问中消失.
  4. 有序扫描: 密钥以词典来存储. 立即用前缀扫描数百万个密钥.
  5. 插件删除: 用 deleteAll(["prefix"])它自动处理背景中的大数据集.

API 参考

初始化客户端

您可以使用全局客户端或将其范围限制到特定的递归命名空间:

const kv = kvClientFactory(components.convexKv);

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

核心业务

方法说明
get(key)返回值或 null 如果丢失/过期.
set(key, val, options?)存储值 。 选项 : ttl (单位:百万美元), expiresAt, (中文(简体) ), metadata。 。 。 .
has(key)快速布尔检查是否存在( 过期返回为假) .
delete(key)删除特定的密钥.

等级范围操作( R)

方法说明
list(prefix, options?)在命名空间内进行分层扫描 .
getAll(prefix)返回前缀下的所有条目( 最大 1000).
deleteAll(prefix)递归式删除。在背景中安全清除整个前缀树.

开发和测试

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

许可证

阿帕奇 - 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 是什么?

Convex 的分级密钥- Value 商店

如何安装 @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 和提交记录判断。