跳到主要内容

Export:通向生态的桥

读完你能带走: nudo export 的命令面、每种产物的验证走读(.d.ts / 守卫 / Zod / Standard Schema),以及一行分工。

schema 管边界;Nudo 管内部。

nudo check 只做校验。产物来自 nudo export —— Abs 的单向、有损投影。Abs 保持真理源;没有任何东西把投影读回来。

JS 代码(+ 可选侧车契约) → Abs → nudo export → 运行时校验器 / .d.ts / schema

Export 是一次性出货命令——没有 --watch。

命令面​

nudo export <path> [--format dts|guard|schema|standard|all] [--dialect zod] [--out dir]

--dialect zod 作用于 --format schema|all。--out dir 写出文件;不带它时 export 打印到 stdout。Flag / 退出码契约:CLI 参考。

格式产物投影输入何时用
dtsTypeScript 声明(默认)契约与 case/调用点证据:参数放宽,返回保持精度JS 包给 TS 编辑器 / npm 的类型
guard零依赖 typeof 守卫函数调用点 Abs 的 join内联运行时检查、零依赖
schema--dialect(目前 zod)可直接 import 的 Zod 模块 → *.nudo.schema.zod.ts逐 case Abs(call@L… / entry@L…)自己组装 schema 模块
standardStandard Schema v1 模块(~standard,vendor nudo)侧车 / @nudo:contract 契约域,否则合并调用点 Abs接入任何 Standard Schema 库——无需 Zod 依赖
alldts + guard + schema + standard—出全套

契约先行:从侧车生成校验器​

最强的工作流:在侧车里声明一次域,让 export 从中生成运行时门禁。

// src/api/users.js
export function createUser(input) {
return { id: 123, name: input.name, age: input.age };
}
// src/api/users.nudo.js — contract (also plain JS)
import { number, string, shape, fn } from "@nudojs/core";

export const createUser = fn(
{ input: shape({ name: string(), age: number().ge(0) }) },
shape({ id: number(), name: string(), age: number() })
);
nudo export src/api/users.js --format standard --out dist
# 写入 dist/createUser.nudo.standard.ts

生成的模块为每个参数导出一个校验器(<fn>_<param>),另有返回值校验器——返回值校验器恒叫 <fn>Output,与 zod 面同名(名字不再随「有无返回契约」在 <fn>Return / <fn>Output 之间翻转)。契约约束直接烘焙进校验器——age: number().ge(0) 变成 numBound { op: "ge", n: 0 } 检查,lit(42) 契约则钉死确切值:

// dist/createUser.nudo.standard.ts(节选)
// (另导出 createUserOutput —— 侧车返回 shape 校验器)
export const createUser_input = {
"~standard": {
version: 1,
vendor: "nudo",
validate(value) {
const issues = [];
__nudoCheck({"k":"obj","slots":[
{"key":"name","node":{"k":"prim","type":"string","refinements":[]}},
{"key":"age","node":{"k":"prim","type":"number","refinements":[{"kind":"numBound","op":"ge","n":0}]}}
]}, value, [], issues);
return issues.length ? { issues } : { value };
},
},
} as const;

在任何支持 Standard Schema 的地方消费——不需要 Zod/Valibot 依赖:

import { createUser_input } from "./dist/createUser.nudo.standard.js";

const r = createUser_input["~standard"].validate(body);
if (r.issues) return Response.json({ errors: r.issues }, { status: 400 });
const user = createUser(r.value);

它是运行时门禁——不是 nudo check 的替代品。CI 仍在 Abs 上检查同一份契约。

证据驱动:从调用点生成校验器​

没有侧车时,export 投影观测到的调用点 Abs 的 join——你的代码实际传入的东西,而不是手写类型:

// src/api/inline.js
export function createUser(input) {
return { id: 123, name: input.name, age: input.age };
}

createUser({ name: "Ada", age: 36 });
nudo export src/api/inline.js --format standard --out dist

调用点观测到的字面量会钉死确切值(z.literal / lit 节点 / === "Ada" 检查)。想要契约界(gt/ge/lt/le、int、字符串长度)而不是观测字面量时,加上侧车。

诚实边界:显式契约优先投影——侧车或 @nudo:contract 钉住的参数/返回与调用点无关、直接进投影。只有完全无证据(无契约、无调用点)的导出才回退 entry@L…——这些参数在 Nudo 域是 any(无约束),但 TS 投影面输出 unknown(TS 的 top,不是关闭检查的 any;2026-11-06 裁定,见 Abs / any 与 unknown);nudo check 的展示面仍打印 any,两个概念在那里继续区分:不做猜测(导出面与 check 面共用同一份签名数据源——契约 / 调用点证据 / entry@ 入口兜底;@nudo:case 调试见证不进发布面)。这是 --from 天花板(Limits),不是推断 bug。any/unknown 的分工是产品契约(docs/design/cli-semantics.md §2)。

Zod 方言 schema(--format schema)​

Schema 导出是可直接 import 的 JS 模块(import { z } from "zod" + export const),不是注释堆:

nudo export src/api/inline.js --format schema --dialect zod
# 或直接写盘:
nudo export src/api/inline.js --format schema --dialect zod --out dist
# 写入 dist/inline.nudo.schema.zod.ts
// @generated by nudo export --format schema — dialect: zod
// One-way lossy projection of Abs; do not edit. nudo check remains the gate.

import { z } from "zod";

export const createUserInput = z.object({ input: z.object({ name: z.string(), age: z.number() }) });

export const createUserOutput = z.object({ id: z.number(), name: z.string(), age: z.number() });

每个函数导出 <fn>Input(命名参数构成的 z.object)和 <fn>Output。Abs 上可表达的常量数值界 / int / 字符串长度 pred 会被投影;不可表达的出现在 dropped preds。与你喜欢的 resolver 一起用:

import { createUserInput } from "./inline.nudo.schema.zod";
import { zodResolver } from "@hookform/resolvers/zod";
const { register, handleSubmit } = useForm({ resolver: zodResolver(createUserInput) });

零依赖守卫(--format guard)​

守卫是纯 typeof 检查,无外部导入、无 schema 解释——每个导出函数一个,命名为 is<Fn>Output:

nudo export src/api/inline.js --format guard
# 或直接写盘:
nudo export src/api/inline.js --format guard --out dist
# 写入 dist/inline.nudo.guard.ts
// === createUser Type Guards ===
export function iscreateUserOutput(data) {
return typeof data === "object" && data !== null && data.id === 123 && data.name === "Ada" && data.age === 36;
}

把打印出的函数存进模块(src/api/users.guard.js)再导入。选择前用你的实际载荷形状分别测一下 guard 与 schema 两条路径;权衡点是错误信息丰富度 vs 零依赖。

TypeScript 声明(--format dts)​

每个函数一个放宽后的签名。参数位(逆变)把字面量放宽到基类型,让调用方可以传任何兼容值;返回类型保持推断精度:

nudo export src/api/inline.js --format dts
/**
* Case: call@L5 ({ name: "Ada"; age: 36 }) => { id: 123; name: "Ada"; age: 36 }
* @param input - { name: string; age: number }
* @returns { id: 123; name: "Ada"; age: 36 }
*/
export declare function createUser(input: { name: string; age: number }): { id: 123; name: "Ada"; age: 36 };

多个 case 时签名仍保持单个——参数跨 case 取并集并放宽;每个 case 的精确结果保留在 Case: JSDoc 行里(调试用外延笔记,不是契约产品)。写 .d.ts 文件到目录:nudo export <file> --format dts --out <dir>。

dts 投影的是模块导出面——只有 export / export default / CJS exports 绑定会出现,非导出的顶层函数保持内部。契约与调用点喂同一份签名(与 nudo check 同数据源);@nudo:case 调试见证不进发布面——nudo export 与门禁一样以 caseMode: "none" 分析:没有契约/调用点证据的参数在 nudo check 展示面是 any,在 .d.ts 投影面输出 TS unknown(nudo any ≈ TS unknown,2026-11-06 归一)——两面同源,只是作用域不同。

校验 vs 投影​

nudo checknudo export
角色Abs 上的静态蕴含门禁Abs 的单向投影
方向读源码 + 契约写产物;没人把它们读回来
失败形态L1/L2 错误退出 1仅 usage / IO 错误退出 1
watch支持 --watch一次性出货命令

Abs 只算一次;check 门禁它,export 出货它的视图。绝不把投影当作第二套类型语言 —— 改源码契约或代码,再重新 export。

分工​

Zod / ArkType / TypeBox / ValibotNudo
何时在 API / 表单 / IO 边界 parse / safeParse在 CI 里对逻辑 + 契约跑 nudo check
什么进入数据的形状对计算结果的 Pred 义务 + 入口 throws
真理schema 对象Abs(shape × term × pred × conf)

它们可以组合:export 把 Abs 投影进 schema 方言,让边界代码与 CI 对同一批事实达成一致。schema 是运行时门禁;Nudo 是静态蕴含门禁。不要把任何一方当作第二套类型语言。

  • 边界校验 —— 在不可信数据进入的边缘保留 Zod / ArkType / TypeBox。
  • 静态蕴含 —— 把 nudo check 留在内部计算(x>0 ⇒ x+1>1)、L1 契约,以及 L2 入口 may-throw 上。
  • 当你希望产物能接进任何符合规范的库、又不想引入 Zod 依赖时,优先 Standard Schema 输出。

Nudo 的诚实边界(以及什么时候不要用它):竞争格局。

CI 集成​

先门禁、再出货产物 —— export 在绿树上是确定性的:

# .github/workflows/nudo.yml
jobs:
nudo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm i -g nudojs
- run: npx nudojs check src/
- run: npx nudojs export src/api.js --format all --out dist
# 随你的包发布 dist/

或者把生成接进 package scripts,产出不进 review:

{
"scripts": {
"generate": "nudo export src/api/users.js --format standard --out src/generated",
"gate": "nudo check src/"
}
}

export 成功退出 0、usage / IO 错误退出 1 —— 它不会重跑契约门禁。与 check 配对(固化了 call@ 用例时可再加 health)。流水线用的机器可读事实来自 nudo check --json / nudo test --json——见 CLI 参考。配方:Recipes。

迁移备注​

把遗留 JS 包带上 Nudo 的过程中,L2 入口 may-throw 可能很吵。命名门禁档位可以保持 L1 严格、只软化 L2:

nudo check src/ --profile adoption # L2 → warning;L1 契约违例仍是 error
nudo check src/ --profile strict # 默认:L1 + L2 error

显式 --entry-throws error|warning|off 覆盖档位。见 nudo check。

下一步​