vv-typescript
Skill12 starsChanged yesterdayApache-2.0View on GitHub
在 VibeValley 里写、改、评审服务端和各个包的 TypeScript:服务是工厂函数加一个接口、依赖从参数进来;预期的拒绝抛 ApiError(带 bizCode),模块自己的失败是 Error 子类、用 instanceof 接;长操作收 AbortSignal,后台任务进 @vibevalley/async 的 TaskGroup,资源用 await using;时间经 Clock;运行时校验只用 Zod(契约、查询的行、落盘的 JSON、配置、工具入参);库只经 db/generated 生成的函数;HTTP 是 Hono。用在:写或改 apps/server、apps/cli、packages/* 的代码;评审一段异步代码(打断、收尾、并发、错误)。
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- create-verification-skillSkill
- vv-acceptanceSkill
- vv-commentsSkill
- vv-governanceSkill
- vv-prSkill
- vv-simplifySkill
- vv-tailwindSkill
The file
Files
在这个仓库写普通 TypeScript
服务端、命令行和各个包都是普通 TypeScript:async/await、AbortSignal、await using、工厂函数,运行时校验只用 Zod。为什么不用 Effect 见地基。
1. 服务:工厂函数加一个接口
一个模块对外一个深的服务:接口和模块同名(Issue、Session),只留调用方用的(同一件事的几种做法是一个成员的标签),里面的部分不露出去,判断写成纯函数;工厂叫 make<名字>,依赖是一个对象参数,只放它用到的、排在它前面的服务(architecture.md)。
// apps/server/src/modules/issue/issue.ts
import type * as T from "@vibevalley/protocol";
export interface Issue {
readonly get: (id: T.IssueId) => Promise<T.Issue>;
/** Each change to an issue, from now on. */
readonly changes: () => Subscription<IssueChange>;
/** At startup, after the modules below it booted. */
readonly boot: () => Promise<void>;
readonly close: () => Promise<void>;
}
export interface IssueDeps {
readonly config: ServerConfig;
readonly clock: Clock;
readonly db: Db;
readonly core: Core;
readonly session: Session;
}
export async function makeIssue(deps: IssueDeps): Promise<Issue> {
const tasks = new TaskGroup({ name: "issue" });
// …
return { get, changes, boot, close: () => tasks.close() };
}- 别处要它的类型写
Issue;和它同名的协议形状写T.Issue。 services.ts照模块次序一个个await make…(deps),拼成Farm;全部建好以后按次序调各自的boot()(开机做的事叫boot,start只指开始干一件事,命名);farm.close()倒着调close()。Farm是AsyncDisposable,测试里await using farm = await world()。- 没有全局的单例:时钟、库、配置都从
deps进来,测试换它们只换参数。 - 一个服务的接口很大时(频道),接口放同模块的
contracts.ts。
2. 错误
- 对调用方的拒绝(参数不对、不让做、找不到):抛
ApiError(@vibevalley/protocol/api),带bizCode。base/errors.ts的帮手:throw refused(t("…"));找不到时throw missing(t("…"), [lookIn.issue])(missing(what, next, bizCode?):next必填,是去哪列出有的那些,lookIn.<概念>或memoriesOf(agent);不给bizCode时按next[0]取对应的…NotFound),查表的结果用orMissing(what, next)(found)。网关把它写成{ bizCode, message, error? }。 模块自己的、调用方要分辨的失败:一个
Error子类,name和类名一样、全仓唯一,用instanceof接:export class HireRefused extends Error { override readonly name = "HireRefused"; constructor(readonly reason: string, readonly retainedWork = false) { super(reason); } } try { await hire(…); } catch (e) { if (!(e instanceof HireRefused)) throw e; … }- 预期的、不是错误的结果(找到或没找到、合进去或冲突):返回一个判别联合(
{ kind: "merged" } | { kind: "conflict"; files }),不抛。 - 意外:照常抛(
throw new Error、invariant),网关答 500 并记日志。不要用catch {}吞掉;要吞的写明为什么,并记一行日志。
3. 打断、后台任务、资源
- 长操作收
signal?: AbortSignal,作为最后一个参数,往下传给fetch、子进程、clock.sleep、queue.take。被打断就让AbortError往上抛;判断用isAbort(e, signal)。 - 后台任务进
TaskGroup(@vibevalley/async):每个服务一个,tasks.run(name, async (signal) => …);关服务时await tasks.close(),它中止每个任务并等它们结束。不要void someAsync()放着不管(no-floating-promises查)。- 同一个键只许一个在跑:
tasks.keyed(key, …),新的先停掉旧的。 - 要拿结果的:
const t = tasks.spawn(name, f); await t.result。
- 同一个键只许一个在跑:
- 资源成对:返回资源的函数返回带
[Symbol.asyncDispose]的对象,调用方await using;几个资源一起用AsyncDisposableStack。没法写成资源的,用try { … } finally { … }。 - 不许被打断的一段:不把
signal传进去,注释写为什么。
4. 并发和时间
| 要做的 | 写法(@vibevalley/async) |
| 一个一个来 | for (const x of xs) await f(x) |
| 一起来,等全部 | await Promise.all(xs.map(f)) |
| 一起来,最多 n 个 | await mapConcurrent(xs, n, f) |
| 一把锁、n 个名额 | const lock = new Semaphore(1); await lock.with(() => …) |
| 跨异步的状态 | 普通的变量或字段;有 await 夹在读和写之间时,读改写包进同一把锁 |
| 一条队列 | Queue(unbounded、sliding、dropping) |
| 给很多读者的新闻 | Hub;读者 using sub = hub.subscribe(),for await (const x of sub) |
| 一串值 | AsyncIterable,写成 async function*;merge、lines、collect、mapConcurrent |
| 等一个将来的值 | Promise.withResolvers() |
| 现在几点、等一会儿 | deps.clock.now()、await deps.clock.sleep(ms, signal);不直接 Date.now()、setTimeout(lint 查) |
| 超时 | await withTimeout((signal) => f(signal), ms, { clock }) |
| 重试 | await retry(f, { retries: 3, delay: exponential(200), when: (e) => …, clock, signal }) |
5. 运行时校验:只用 Zod
契约(packages/protocol 的 schema.ts)、HTTP 入参、SSE、查询的每一行、落盘的 JSON、配置、工具入参都用 Zod 4 解,进门一次,门内是类型。
- 契约由手写的类型定:
shapes.ts是手写的类型,schema.ts里每个 Schema 写成export const Issue = z.object({ … }) satisfies Codec<T.Issue>(Codec<A>是z.ZodType<A, Wire<A>>,在packages/protocol/src/codec.ts),两边对不上就编不过。用satisfies而不是: Codec<…>:Schema 保住自己的类型(对象的.shape、.extend,接口的入参要拼它)。 - 可选字段用
z.exactOptional(x)(仓库开着exactOptionalPropertyTypes,.optional()会多出| undefined)。 - 品牌主键:手写类型是
string & { readonly [brand]: "IssueId" };Schema 用common/schema.ts的branded<T.IssueId>();门内造一个用issueId(s)。 - 解的时候:门口用
X.parse(v)(错了抛ZodError,网关答InvalidInput);要自己处理错的用X.safeParse(v)。不要as一个没解过的值。 - JSON 列和落盘文件:Schema 里写
jsonString(X)(@vibevalley/protocol/schema:z.string()转JSON.parse再pipe(X));服务端读一列用base/json.ts的storedJsonOrUndefined(X, "表.列"),坏了当场失败,带表名和列名,不吞。 - 工具给模型的参数:
z.toJSONSchema(X)。 - 密钥:
Secret(toJSON抛错,toString是[secret]),落盘的读进来时用 Zod 的z.codec封成Secret(setting/provider.ts的StoredKey)。
6. 库
- SQL 只写在
apps/server/db/queries/<表>.sql,每条-- name: GetIssue :one|:many|:exec;vp run --filter @vibevalley/server db:generate写出db/generated/<表>.sql.ts:每条查询一个参数类型、一个结果行的 Zod Schema、一个函数getIssue(sql, params)。代码里只调生成的函数。 Db(infra/db.ts)给出sql(一个Sql),事务是await db.tx(async () => { … }),里面照样传db.sql。一个事务里的写一个接一个await,不要Promise.all。提交以后才做的事(发新闻、通知)用db.afterCommit(hook):回滚了就不做。- 出库的每一行都经结果 Schema 解;对不上抛错,不在读的地方兜底旧数据(内部不留兼容)。
- 一条语句失败抛
SqlError,默认就让它抛(网关答 500)。只有失败要告诉调用方或重试的地方才catch (e) { if (e instanceof SqlError) … },这些地方和理由列在infra/db.test.ts的catching表里;多一处要在表里加一行。 db.tx里调到的函数照样用db.sql:它自己知道在不在事务里(嵌套的是保存点)。不要把事务对象一路传下去。
7. HTTP 和订阅
- 网关是 Hono,只听 127.0.0.1。接口仍由
packages/protocol的<概念>/api.ts定:endpoints列出op、input、result(Zod)、can;处理函数的类型是(input) => Promise<Result>,在gateway/http/handlers/<概念>.ts里只做转发。 - 订阅是 SSE:
subscriptions列出每条订阅的入参和每个事件的 Schema,服务端写async function*,客户端读EventSource的流并用 Schema 解。 - 出去的请求用
fetch(全局的,或从deps.fetch进来以便测试换掉),带上signal。
8. 日志、配置、度量
- 日志:
deps.log(infra/log.ts的Logger:debug、info、warn、error,带模块名)。服务端不直接console.*(lint 查)。 - 配置:
infra/config.ts用 Zod 解环境和vibevalley.yaml,得到ServerConfig,从deps.config进来。 - 度量:
infra/metrics.ts的计数器(counter(name).add(n)),测试读它守热路径的预算。
9. 测试
vite-plus/test的test、describe、expect;异步测试直接写async。- 整农场:
await using farm = await world({ … })(src/testing/world.ts),帮工是 oar 的scriptedRuntime,模型是照脚本回答的 DeepSeek(farm.deepseek.use(scriptedLLM(…).llm),src/testing/model.ts),不连网。 - 时间:
vi.useFakeTimers()加vi.advanceTimersByTimeAsync(ms);或者给deps.clock一个测试时钟(world({ clock: shiftedTime() }))。不在测试里真等。 - 等一个条件:
@vibevalley/testkit/until的until、waitFor;整农场的状态用testing/layers.ts的whenState。 - 修缺陷补的测试以
regression:开头,删改它要在 PR 里点名说明。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

