@fbrpc/fbrpc-core 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * fbrpc 错误类型。
+ * handler 内部 throw RpcError 时，框架自动转为统一错误响应。
+ */
+export declare class RpcError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAGxB,IAAI,EAAE,MAAM;gBADnB,OAAO,EAAE,MAAM,EACR,IAAI,GAAE,MAAoB;CAKpC"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/**
+ * fbrpc 错误类型。
+ * handler 内部 throw RpcError 时，框架自动转为统一错误响应。
+ */
+export class RpcError extends Error {
+    code;
+    constructor(message, code = "API_ERROR") {
+        super(message);
+        this.code = code;
+        this.name = "RpcError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGxB;IAFT,YACE,OAAe,EACR,OAAe,WAAW;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,SAAI,GAAJ,IAAI,CAAsB;QAGjC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ApiDef, ReqOf, ResOf, Protocol, ApiCall, StreamCall, ApiHandler, StreamHandler, AnyApiHandler, AnyStreamHandler, ServiceHandlers, ApiModule, SuccResponse, ErrResponse, ApiResponse, } from "./types.js";
+export { RpcError } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,MAAM,EACN,KAAK,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { RpcError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * fbrpc-core — 核心类型定义，零依赖。
+ *
+ * 设计目标：AI 打开一个文件就能理解全部 API 契约。
+ * 协议层只用纯 TS 接口，不引入任何框架类型。
+ */
+/** 单个 API 的请求/响应类型对 */
+export interface ApiDef<Req = unknown, Res = unknown> {
+    req: Req;
+    res: Res;
+}
+/** 从 ApiDef 提取请求类型 */
+export type ReqOf<D extends ApiDef> = D["req"];
+/** 从 ApiDef 提取响应类型 */
+export type ResOf<D extends ApiDef> = D["res"];
+/** 协议映射：{ 方法名: ApiDef } */
+export type Protocol = Record<string, ApiDef>;
+/**
+ * 普通 RPC 调用的 call 对象。
+ * handler 通过 call.succ() / call.error() 回传结果，
+ * 不抛异常、不 return 值。
+ */
+export interface ApiCall<D extends ApiDef = ApiDef> {
+    /** 请求参数（协议定义的 req 类型） */
+    req: D["req"];
+    /**
+     * 元数据——由服务器鉴权函数注入。
+     * 通常包含 userId、sessionId 等横切信息。
+     */
+    meta: Record<string, unknown>;
+    /** 成功响应 */
+    succ(data: D["res"]): void;
+    /** 业务错误 */
+    error(message: string, code?: string): void;
+}
+/**
+ * SSE 流式调用的 call 对象。
+ * handler 调用 call.stream(fn)，框架负责把 yield 转成 SSE 事件。
+ */
+export interface StreamCall<D extends ApiDef<unknown, void> = ApiDef<unknown, void>> {
+    req: D["req"];
+    meta: Record<string, unknown>;
+    /**
+     * 启动流式输出。
+     * fn 接收 send 函数，每次 send(chunk) 输出一个 SSE 事件。
+     */
+    stream(fn: (send: (chunk: unknown) => Promise<void> | void) => Promise<void>): void;
+    /** 流式错误 */
+    error(message: string): void;
+}
+/** 普通 RPC 处理器（泛型——用于单一定义） */
+export type ApiHandler<D extends ApiDef = ApiDef> = (call: ApiCall<D>) => Promise<void>;
+/** SSE 流式处理器（泛型——用于单一定义） */
+export type StreamHandler<D extends ApiDef<unknown, void> = ApiDef<unknown, void>> = (call: StreamCall<D>) => void;
+/** 宽松版 handler——接受任意 ApiCall，用于模块导出 */
+export type AnyApiHandler = (call: ApiCall<any>) => Promise<void>;
+export type AnyStreamHandler = (call: StreamCall<any>) => void;
+/**
+ * 从 Protocol 推导类型安全的 handler 映射。
+ *
+ * 用于 services 目录下各 api.ts 的 handlers 导出——
+ * `satisfies ServiceHandlers<Protocol>` 确保：
+ * 1. 所有协议方法都被实现（无遗漏）
+ * 2. key 精确对齐（无多余）
+ * 3. 每个 handler 的 call 参数自动推导 req/res 类型
+ *
+ * 配合 call 参数的类型注解（如 `ApiCall<Protocol["method"]>`），
+ * 达成全链路编译期类型安全。
+ */
+export type ServiceHandlers<P> = {
+    [K in keyof P & string]: P[K] extends ApiDef<infer Req, infer Res> ? (call: ApiCall<ApiDef<Req, Res>>) => Promise<void> : never;
+};
+/**
+ * 一个服务模块的导出。
+ * services/<name>/api.ts 必须导出这个形状。
+ */
+export interface ApiModule {
+    /** 普通 RPC 处理器。key = 方法名。 */
+    handlers: Record<string, AnyApiHandler>;
+    /** SSE 流式处理器。key = 方法名。 */
+    streams: Record<string, AnyStreamHandler>;
+}
+/** 统一成功响应 */
+export interface SuccResponse<T = unknown> {
+    ok: true;
+    data: T;
+}
+/** 统一错误响应 */
+export interface ErrResponse {
+    ok: false;
+    error: {
+        message: string;
+        code: string;
+    };
+}
+/** 统一响应 */
+export type ApiResponse<T = unknown> = SuccResponse<T> | ErrResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * fbrpc-core — 核心类型定义，零依赖。
+ *
+ * 设计目标：AI 打开一个文件就能理解全部 API 契约。
+ * 协议层只用纯 TS 接口，不引入任何框架类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fbrpc/fbrpc-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "description": "fbrpc core types — protocol definition, ApiCall, StreamCall, ApiModule. Zero dependencies.",
+  "author": "birderr",
+  "license": "MIT",
+  "keywords": [
+    "rpc",
+    "fastify",
+    "type-safe",
+    "protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fbrpc/fbrpc"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,13 @@
+/**
+ * fbrpc 错误类型。
+ * handler 内部 throw RpcError 时，框架自动转为统一错误响应。
+ */
+export class RpcError extends Error {
+  constructor(
+    message: string,
+    public code: string = "API_ERROR",
+  ) {
+    super(message);
+    this.name = "RpcError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export type {
+  ApiDef,
+  ReqOf,
+  ResOf,
+  Protocol,
+  ApiCall,
+  StreamCall,
+  ApiHandler,
+  StreamHandler,
+  AnyApiHandler,
+  AnyStreamHandler,
+  ServiceHandlers,
+  ApiModule,
+  SuccResponse,
+  ErrResponse,
+  ApiResponse,
+} from "./types.js";
+export { RpcError } from "./errors.js";

package/src/types.ts

@@ -0,0 +1,123 @@
+/**
+ * fbrpc-core — 核心类型定义，零依赖。
+ *
+ * 设计目标：AI 打开一个文件就能理解全部 API 契约。
+ * 协议层只用纯 TS 接口，不引入任何框架类型。
+ */
+
+// ── API 定义 ──
+
+/** 单个 API 的请求/响应类型对 */
+export interface ApiDef<Req = unknown, Res = unknown> {
+  req: Req;
+  res: Res;
+}
+
+/** 从 ApiDef 提取请求类型 */
+export type ReqOf<D extends ApiDef> = D["req"];
+
+/** 从 ApiDef 提取响应类型 */
+export type ResOf<D extends ApiDef> = D["res"];
+
+/** 协议映射：{ 方法名: ApiDef } */
+export type Protocol = Record<string, ApiDef>;
+
+// ── call 对象 ──
+
+/**
+ * 普通 RPC 调用的 call 对象。
+ * handler 通过 call.succ() / call.error() 回传结果，
+ * 不抛异常、不 return 值。
+ */
+export interface ApiCall<D extends ApiDef = ApiDef> {
+  /** 请求参数（协议定义的 req 类型） */
+  req: D["req"];
+  /**
+   * 元数据——由服务器鉴权函数注入。
+   * 通常包含 userId、sessionId 等横切信息。
+   */
+  meta: Record<string, unknown>;
+  /** 成功响应 */
+  succ(data: D["res"]): void;
+  /** 业务错误 */
+  error(message: string, code?: string): void;
+}
+
+/**
+ * SSE 流式调用的 call 对象。
+ * handler 调用 call.stream(fn)，框架负责把 yield 转成 SSE 事件。
+ */
+export interface StreamCall<D extends ApiDef<unknown, void> = ApiDef<unknown, void>> {
+  req: D["req"];
+  meta: Record<string, unknown>;
+  /**
+   * 启动流式输出。
+   * fn 接收 send 函数，每次 send(chunk) 输出一个 SSE 事件。
+   */
+  stream(fn: (send: (chunk: unknown) => Promise<void> | void) => Promise<void>): void;
+  /** 流式错误 */
+  error(message: string): void;
+}
+
+// ── 处理器 ──
+
+/** 普通 RPC 处理器（泛型——用于单一定义） */
+export type ApiHandler<D extends ApiDef = ApiDef> = (call: ApiCall<D>) => Promise<void>;
+
+/** SSE 流式处理器（泛型——用于单一定义） */
+export type StreamHandler<D extends ApiDef<unknown, void> = ApiDef<unknown, void>> = (call: StreamCall<D>) => void;
+
+/** 宽松版 handler——接受任意 ApiCall，用于模块导出 */
+export type AnyApiHandler = (call: ApiCall<any>) => Promise<void>;
+export type AnyStreamHandler = (call: StreamCall<any>) => void;
+
+/**
+ * 从 Protocol 推导类型安全的 handler 映射。
+ *
+ * 用于 services 目录下各 api.ts 的 handlers 导出——
+ * `satisfies ServiceHandlers<Protocol>` 确保：
+ * 1. 所有协议方法都被实现（无遗漏）
+ * 2. key 精确对齐（无多余）
+ * 3. 每个 handler 的 call 参数自动推导 req/res 类型
+ *
+ * 配合 call 参数的类型注解（如 `ApiCall<Protocol["method"]>`），
+ * 达成全链路编译期类型安全。
+ */
+export type ServiceHandlers<P> = {
+  [K in keyof P & string]: P[K] extends ApiDef<infer Req, infer Res>
+    ? (call: ApiCall<ApiDef<Req, Res>>) => Promise<void>
+    : never
+};
+
+// ── 模块描述 ──
+
+/**
+ * 一个服务模块的导出。
+ * services/<name>/api.ts 必须导出这个形状。
+ */
+export interface ApiModule {
+  /** 普通 RPC 处理器。key = 方法名。 */
+  handlers: Record<string, AnyApiHandler>;
+  /** SSE 流式处理器。key = 方法名。 */
+  streams: Record<string, AnyStreamHandler>;
+}
+
+// ── 响应格式 ──
+
+/** 统一成功响应 */
+export interface SuccResponse<T = unknown> {
+  ok: true;
+  data: T;
+}
+
+/** 统一错误响应 */
+export interface ErrResponse {
+  ok: false;
+  error: {
+    message: string;
+    code: string;
+  };
+}
+
+/** 统一响应 */
+export type ApiResponse<T = unknown> = SuccResponse<T> | ErrResponse;

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}