@cratestack / cbor-node
原生N-API cor编解码器，用于CrateStack生成的TypeScript RPC客户端
CratestackRpcCodec
由框架自己的支持 cratestack-codec-cbor
通过本地绑定的Rust crate (crates/cratestack-cbor-napi)，
而不是JS的重新实现。编码/解码输出是字节相同的
CrateStack服务器和Rust客户端已经为 application/cbor.
通过。发送预构建的平台二进制文件 optionalDependencies (同样的模式
esbuild/@swc/core use) -不需要Rust工具链来安装或使用这个包。
看到 史诗# 285 和 问题# 286 以获取完整的设计上下文。
使用
import { cborCodec } from "@cratestack/cbor-node";
const bytes = cborCodec.encode({ hello: "world", count: 1 });
const value = cborCodec.decode(bytes);
cborCodec 在结构上满足 CratestackRpcCodec 从 @cratestack/ts-types，所以。
可以传递到任何地方生成的客户端运行时期望一个编解码器-没有显式
依赖 @cratestack/ts-types 运行时必需的，因为它是通过
satisfies，而不是类型再出口。
空处理
cor有一个真实的 null (RFC 8949§3.3，简单值22，字节 0xf6）。 cratestack-codec-cbor的
底层 minicbor-serde 后端有一个记录在案的怪癖，其中一个裸露的Rust单元类型 ()
编码为cor 空数组 标记(0x80)，而不是这个包裹 encode 翻译
每一个JSON null （顶级或嵌套在对象/数组中）通过代码路径
产生真正的cor null，匹配 CborCodec的自己的 Option::None byte-for-byte行为。看到
crates/cratestack-cbor-napi/src/json_value.rs 有关细节。
错误处理
传入的畸形cor字节 decode 抛出一个可捕捉的JS Error -从来没有本地崩溃。
两个本地入口点也都使用了api-rs catch_unwind 转换任何意外的Rust恐慌
转换为可捕获的异常，而不是中止Node进程。
范围
只有单项目编码/解码-没有cor -seq/流支持(这是一个单独的问题；请参阅
史诗般的# 285)。从第746期开始， @cratestack/cbor (这个包的Node一半，通过伞
@cratestack/cbor 再出口) 是 生成的TypeScript RPC客户端的默认编解码器-
--no-native-cbor （TypeScriptGeneratorConfig::native_cbor: false)落回
pure-TypeScript jsonRpcCodec在此包没有附带napi二进制文件的平台上需要
（win32-arm64 ——看 napi.targets 在 package.json）. REST-transport
生成的客户端不会受到任何影响：REST运行时根本没有编解码器接缝。
支持的平台上
napi.targets 在 package.json 是真理的源泉；从cratestack#850开始，它是：
| 平台 | 目标三 | NPM平台包 |
|---|---|---|
| macOS x64 | x86_64-apple-darwin | @cratestack/cbor-node-darwin-x64 |
| macOS arm64 | aarch64-apple-darwin | @cratestack/cbor-node-darwin-arm64 |
| Linux x64 （glibc） | x86_64-unknown-linux-gnu | @cratestack/cbor-node-linux-x64-gnu |
| Linux arm64 （glibc） | aarch64-unknown-linux-gnu | @cratestack/cbor-node-linux-arm64-gnu |
| Linux x64 （musl / Alpine） | x86_64-unknown-linux-musl | @cratestack/cbor-node-linux-x64-musl |
| Linux arm64 （musl / Alpine） | aarch64-unknown-linux-musl | @cratestack/cbor-node-linux-arm64-musl |
| Windows x64 | x86_64-pc-windows-msvc | @cratestack/cbor-node-win32-x64-msvc |
这两个代码都在CI中进行了负载测试，而不仅仅是构建 build-cbor-node 肌肉腿跑
它所针对的运行程序体系结构，在上传任何内容之前，加载 .node 它只是
下生产 node:22-alpine 并通过这个包自己的断言一个固定的编码/解码向量
native.mjs． 因此，在x64上勾选“works on Alpine” 和 Arm64，在真正的硬件上，而不是
模拟，在每个版本构建上。
仍然 不 覆盖: win32-arm64． 也没有wasm/wasi回退-生成的
native.mjs 加载程序包含 wasm32-wasi 分支，但没有发布 .wasi.cjs 或者一个
@cratestack/cbor-node-wasm32-wasi 包，以便分支只能添加另一个
Cannot find module 到错误链。在不受支持的平台上，加载器会引发泛型
"找不到本机绑定。NPM有一个与可选依赖相关的bug……” 错误,
指责国家预防机制，而不是指出真正的原因； --no-native-cbor 是逃生舱口。
上面的每个平台包是一个优化，而不是一个要求：这个包自己的tarball
包每 .node 二进制(files: ["*.node"])，加载器会尝试绑定的
./cratestack-cbor-node.<platform>.node 之前 @cratestack/cbor-node-<platform> 依赖。
子包尚未发布的平台仍然解析工作绑定。