API 文档

TSFFI.B 的完整接口参考

宏注解

#[tsffi::callback]

将 Rust 函数声明为 TypeScript 可调用的回调。TS 端注册回调后，Rust 可主动调用。

Rust
rust
#[tsffi::callback]
fn on_progress(pct: f64) -> bool {
    pct < 100.0
}
生成 TypeScript
ts
declare function onProgress(
  callback: (pct: number) => boolean
): void;

#[tsffi::export]

将 Rust 函数导出为 TypeScript 可调用的函数。自动处理类型转换和错误映射。

Rust
rust
#[tsffi::export]
fn process_file(path: String) -> Result<String> {
    let data = fs::read_to_string(&path)?;
    Ok(transform(&data))
}
生成 TypeScript
ts
declare function processFile(
  path: string
): string;

#[tsffi::struct]

将 Rust 结构体导出为 TypeScript 接口。所有字段自动映射类型。

Rust
rust
#[tsffi::struct]
pub struct TaskResult {
    pub id: u32,
    pub name: String,
    pub status: TaskStatus,
}
生成 TypeScript
ts
interface TaskResult {
  id: number;
  name: string;
  status: TaskStatus;
}

#[tsffi::enum]

将 Rust 枚举导出为 TypeScript 联合类型。支持简单枚举和带数据枚举。

Rust
rust
#[tsffi::enum]
pub enum TaskStatus {
    Pending,
    Running,
    Completed,
    Failed(String),
}
生成 TypeScript
ts
type TaskStatus =
  | "Pending"
  | "Running"
  | "Completed"
  | { Failed: string };

类型映射

RustTypeScript
i32number
i64bigint
f64number
boolboolean
Stringstring
Vec<u8>Buffer
Vec<T>T[]
Option<T>T | null
Result<T, E>T | Error
HashMap<K, V>Record<K, V>

CLI 命令

tsffib init <name> --template=<t>使用指定模板初始化新项目
tsffib dev启动开发模式，文件变更自动重新构建
tsffib build构建生产版本原生模块
tsffib template列出所有可用项目模板

运行时 API

CallbackHandle<T>

回调句柄，管理 TypeScript 函数在 Rust 侧的引用生命周期。自动释放，防止内存泄漏。

CallbackScheduler

回调调度器，控制回调执行队列与并发策略。支持优先级排序和背压控制。

PanicHook

Rust panic 捕获钩子。将 panic 转换为 JavaScript Error，阻止 Node.js 进程崩溃。

LifecycleManager

生命周期管理器，追踪原生资源的创建与销毁，确保跨语言资源正确释放。