@nilejs /客户端
类型安全的前端客户端 尼罗河Js 后端。
功能
- 类型安全的: 为服务、操作和有效负载检查使用共享或cli生成的后端类型。
- 优雅的错误处理： 返回与Nile Js后端相同的Result模式(
isOk，isErr，value，error)，而不是抛出异常。 - 小: HTTP调用使用平台
fetch． 唯一的运行时依赖项是socket.io-client，用于套接字客户端。 - 灵活: 支持每个请求的自定义标头、凭据和超时。
安装
# Using npm
npm install @nilejs/client
# Using pnpm
pnpm add @nilejs/client
# Using bun
bun add @nilejs/client
使用
1. 创建客户端
import { createNileClient } from "@nilejs/client";
const nile = createNileClient({
baseUrl: "http://localhost:8000/api",
credentials: "include",
});
2. 调用动作
const result = await nile.invoke({
service: "tasks",
action: "create",
payload: { title: "Buy milk" },
});
if (result.isErr) {
console.error("Action failed:", result.error);
} else {
console.log("Success:", result.value);
}
3. 全型安全（推荐）
使用Nile CLI生成类型：
nile generate schema --output ./src/generated
然后使用生成的 ServicePayloads 地图:
import { createNileClient } from "@nilejs/client";
import type { ServicePayloads } from "./generated/types";
const nile = createNileClient<ServicePayloads>({
baseUrl: "/api"
});
// Full autocomplete and type-checking for service, action, and payload
await nile.invoke({
service: "tasks",
action: "create",
payload: { title: "Buy milk" }
});
4. 发现与反思
// Explore services and actions
const services = await nile.explore({ service: "*", action: "*" });
if (services.isOk) {
console.log(services.value);
}
// Fetch action schemas
const schemas = await nile.schema({ service: "tasks", action: "*" });
if (schemas.isOk) {
console.log(schemas.value);
}
API
createNileClient<T>(config)
返回一个Nile客户端实例。
config.baseUrl：你的Nile API的基础URL(例如：http://localhost:8000/api）。config.credentials：请求凭证(include，omit，same-origin）。config.headers：每个请求中包含的全局标头。config.timeout：默认请求超时时间，单位为毫秒（默认：30000）。
方法
所有方法都返回 Promise<ClientResult<T>>． 调用从不抛出：
- 成功:
{ isOk: true, isErr: false, value: T, error: null, message? },在那里messageHTTP调用的服务器成功消息是什么 - 失败:
{ isOk: false, isErr: true, value: null, error: string, details },在那里details保存服务器附加的任何数据，例如验证问题。网络故障和超时也是故障。
检查 isErr 首先，然后阅读 error 或者 value． 年长的 data 字段仍然作为弃用别名存在(成功时的值， null （当失败时），现有的代码继续工作。
invoke(params)：执行特定的服务动作。explore(params)：使用通配符发现服务/操作。schema(params)：以JSON模式获取动作模式。
传入每个呼叫设置 fetchOptions． 报头与客户端配置的报头合并；无论大小写如何，每次调用的值都会覆盖相同的标头。两个 Headers 支持实例和头元组。超时包括读取响应体和连接；一个可选的 signal 可以取消通话。
const controller = new AbortController();
const result = await nile.invoke({
service: "tasks",
action: "create",
payload: { title: "Ship the next feature" },
fetchOptions: {
headers: { Authorization: "Bearer your-session-token" },
timeout: 5000,
signal: controller.signal,
},
});
尼罗河1.0.3响应
HTTP响应包含 status， message 和 data． 客户端将这些映射到其现有的Result API；它保留自定义消息、Zod的美化验证消息和生成的诊断引用。默认的成功消息为 Action completed.
对于验证失败， result.error 消息是否可读 result.details 包含 { errorCode, issues }. ValidationFailureData 为缩小此未知故障数据的应用程序导出。其他的失败可能会带来不同的细节，所以在使用它之前检查它的形状。诊断故障可能包括 Error Code: <unique-code> - <message> 在留言中。将代码视为与后端日志共享的引用；不要将其作为固定的错误类别。
套接字。IO操作和主题
创建一个单独的套接字客户端。它拥有连接；您不需要在每次调用中传递套接字。使用共享类型、生成的操作类型，或者显式地定义你的前端契约。还必须在后端配置主题定义和授权策略。
import { createNileSocketClient } from "@nilejs/client";
import type { ServicePayloads } from "./generated/types";
type Topics = {
"tasks.changed": {
data: { taskId: string; status: string };
};
};
const socket = createNileSocketClient<ServicePayloads, Topics>({
baseUrl: "http://localhost:8000",
auth: () => {
return { token: "your-session-token" };
},
});
const subscription = await socket.receive({
topic: "tasks.changed",
onMessage: (message) => {
console.log(message.data.taskId, message.data.status);
},
});
const result = await socket.invoke({
service: "tasks",
action: "create",
payload: { title: "Ship the next feature" },
});
const publication = await socket.send({
topic: "tasks.changed",
data: { taskId: "task-123", status: "done" },
});
if (subscription.isOk) {
await subscription.value.unsubscribe();
}
socket.close();
只要应用程序需要实时更新，就保持客户端打开。连接是惰性的，订阅在重新连接后重新加入，并且不自动缓冲或重试断开的写操作。从提供的类型中检查主题名称、数据和任何所需的范围；Nile对它们进行验证，并在后端执行策略。服务器可以同时公开HTTP和套接字。看到 尚 用于服务器设置。
上传
const result = await nile.upload({
service: "documents",
action: "upload",
files: { document: file },
fields: { title: "Invoice" },
fetchOptions: { timeout: 60000 },
});
多部分调用与JSON调用共享相同的取消、截止日期和结果行为。Content-Type由运行时设置，因此多部分边界是正确的。
兼容性
版本1.0.1支持Nile 1.0.3和1.0.4，同时保留现有的HTTP和套接字客户端api。它修复了标头合并、取消和超时清理；它不会在Nile的有线合同中增加油田。
许可证
麻省理工学院