@evumi/berth-config

读取 Berth 项目 Config 的客户端。第一次读取时拉一次整份配置，之后都从内存读；后台用一个长轮询保持最新。零运行时依赖，支持 Node ≥ 18、Bun、Deno 和不带 Node 内置模块的 edge 运行时。

不要放机密。 Config 对组织成员可读。密码、密钥放到服务变量里。

此 SDK 用于服务端（包括服务端组件、API 路由和 edge Worker）。BERTH_CONFIG_TOKEN 是服务端凭据，同时用于环境的 KV 和队列等接口，不能下发到浏览器。前端需要配置或 KV 数据时，由应用后端校验权限并仅返回所需字段。不要把 Token 复制到 NEXT_PUBLIC_*、VITE_*、打包器环境变量映射或客户端 props；不要在客户端组件里使用此 SDK。

用法

Berth 会给容器注入 BERTH_CONFIG_URL 和 BERTH_CONFIG_TOKEN，直接用默认导出：

import { config } from '@evumi/berth-config';

const enabled = await config.get<boolean>('newCheckout');
const all = await config.getAll();
const unsubscribe = config.subscribe((doc) => console.log('config changed', doc));

自己建客户端：

import { createClient } from '@evumi/berth-config';

const cfg = createClient({
  url: process.env.BERTH_CONFIG_URL,   // 默认读环境变量
  token: process.env.BERTH_CONFIG_TOKEN,
  fallback: './config.local.json',     // 本地开发或启动时连不上服务器时使用
  timeoutMs: 5000,
  onError: (err) => console.warn('config:', err.code, err.message), // 默认什么都不打
});

| 方法 | 说明 | |---|---| | get<T>(key) | 某个顶层字段，不存在时返回 undefined | | getAll<T>(keys?) | 整份文档，或只取给出的字段 | | has(key) | 字段是否存在 | | digest() | 当前 ETag（不带引号）；用的是 fallback 时为 "" | | version() | 当前版本号；还没有配置或用的是 fallback 时为 0 | | subscribe(cb) | 配置变化时回调，返回取消函数 | | close() | 停止长轮询并中断进行中的请求 |

返回值是副本，改了不影响缓存。

行为

• 第一次调用任意方法时拉取 GET /v1/config，并发调用共用这一次请求；失败了下次调用会重试。
• 之后后台只有一个长轮询（?wait=55 + If-None-Match），变化时立即更新并通知订阅者。
• 出错时按指数退避重试（带抖动，最长 30 秒）；429 按 Retry-After 等待。
• Node 里长轮询的连接和定时器都已 unref，不会让进程退出不了；脚本里也不需要手动 close()。
• 错误都是 BerthConfigError，带 code（unauthorized、not_found、unavailable、rate_limited、timeout、network、missing_env、fallback 等）和 status。令牌不会出现在错误或日志里。

Next.js

// app/page.tsx（服务端组件）
import { config } from '@evumi/berth-config';

export default async function Page() {
  const banner = await config.get<string>('banner');
  return <main>{banner && <p>{banner}</p>}</main>;
}

Edge 运行时也能用，fallback 只能传对象（edge 没有文件系统）。

Express

import express from 'express';
import { config } from '@evumi/berth-config';

const app = express();
app.get('/', async (_req, res) => {
  const { maxItems = 20 } = await config.getAll<{ maxItems?: number }>();
  res.json({ maxItems });
});
app.listen(3000);

本地开发

本地没有 BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN 时读 fallback：

const cfg = createClient({ fallback: './config.local.json' });   // 文件（Node/Bun/Deno）
const cfg2 = createClient({ fallback: { newCheckout: true } });  // 或直接给对象

没有环境变量也没有 fallback 时，读取会抛 missing_env。

开发

pnpm install
pnpm test    # 先构建，再跑 vitest（含 ESM/CJS 子进程退出测试）
pnpm build   # dist/esm + dist/cjs