protobuf-fastdsl 0.1.2 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # protobuf-fastdsl
 
-一个 Vite 插件，将 TypeScript protobuf 接口在构建时编译为**完全内联**、零依赖的编解码函数。
+将 TypeScript 接口在构建时编译为**完全内联**、零依赖的 protobuf 编解码函数。
 
 无 `.proto` 文件。无运行时库。无函数调用开销。只需 TypeScript 接口 → 确定化的二进制编解码代码。
 
@@ -8,9 +8,11 @@
 
 - **零运行时** — 所有 wire-format 逻辑在编译时内联
 - **TypeScript 原生** — 用 `pb<N, Type>` 标记接口字段即可定义 schema
+- **跨文件类型** — 支持 `import type` / `import` 引用其他文件的接口定义
 - **泛型单态化** — `Wrapper<Wrapper<string>>` → 自动生成具体编解码函数
 - **重复字段** — `pb_repeated<N, Type>` 编译为 `Type[]`
 - **编译期预计算 Tag** — 字段标签在编译时折叠为字面量字节
+- **安全的 Fallback** — 未经插件转换时运行会直接抛错，不会静默产生错误结果
 
 ## 安装
 
@@ -20,30 +22,24 @@ npm install protobuf-fastdsl
 
 ## 快速开始
 
-**1. 在 `vite.config.ts` 中添加插件：**
+**1. 配置构建工具插件：**
 
 ```ts
-import protobufVite from 'protobuf-fastdsl';
+// vite.config.ts
+import protobufPlugin from 'protobuf-fastdsl/vite';
 
 export default defineConfig({
-  plugins: [protobufVite()],
+  plugins: [protobufPlugin()],
 });
 ```
 
-**2. 在 `tsconfig.json` 中添加类型声明：**
-
-```json
-{
-  "compilerOptions": {
-    "types": ["protobuf-fastdsl/types"]
-  }
-}
-```
-
-**3. 用 TypeScript 接口定义 schema：**
+**2. 定义 protobuf schema（TypeScript 接口）：**
 
 ```ts
-interface UserProfile {
+// schema/user.ts
+import type { pb, pb_repeated, uint_32, bool } from 'protobuf-fastdsl';
+
+export interface UserProfile {
   id:       pb<1, uint_32>;
   username: pb<2, string>;
   active:   pb<3, bool>;
@@ -51,9 +47,12 @@ interface UserProfile {
 }
 ```
 
-**4. 使用 `protobuf_encode` / `protobuf_decode`：**
+**3. 编解码：**
 
 ```ts
+import { protobuf_encode, protobuf_decode } from 'protobuf-fastdsl';
+import type { UserProfile } from './schema/user';
+
 const bytes = protobuf_encode<UserProfile>({
   id: 42,
   username: 'alice',
@@ -65,7 +64,7 @@ const user = protobuf_decode<UserProfile>(bytes);
 // user.id === 42, user.tags === ['admin', 'dev']
 ```
 
-构建时，插件会将上述代码转换为：
+构建时，插件将上述代码转换为：
 
 ```js
 // 预计算的 tag 字面量，内联 varint 循环，零函数调用
@@ -73,6 +72,43 @@ const bytes = protobuf_encode_UserProfile({ id: 42, ... });
 const user = protobuf_decode_UserProfile(bytes);
 ```
 
+如果忘记配置插件，`protobuf_encode` / `protobuf_decode` 会在运行时抛出错误提示。
+
+## 跨文件类型引用
+
+接口定义和编解码调用可以在不同文件中，插件会自动跟踪 import 链：
+
+```ts
+// inner.ts
+import type { pb, uint_32 } from 'protobuf-fastdsl';
+
+export interface Inner {
+  value: pb<1, uint_32>;
+}
+
+// outer.ts
+import { protobuf_encode } from 'protobuf-fastdsl';
+import type { Inner } from './inner';
+import type { pb } from 'protobuf-fastdsl';
+
+interface Outer {
+  inner: pb<1, Inner>;
+}
+
+const bytes = protobuf_encode<Outer>({ inner: { value: 42 } });
+```
+
+支持传递性导入（A → B → C），插件会递归解析所有依赖。
+
+## 别名导入
+
+```ts
+import { protobuf_encode as encode, protobuf_decode as decode } from 'protobuf-fastdsl';
+
+const bytes = encode<UserProfile>(data);  // → protobuf_encode_UserProfile(data)
+const user = decode<UserProfile>(bytes);  // → protobuf_decode_UserProfile(bytes)
+```
+
 ## 泛型单态化
 
 定义泛型 protobuf 模板，使用具体类型实例化：
@@ -95,8 +131,8 @@ const data = protobuf_encode<Wrapper<Wrapper<string>>>({
 |---------------|-----------------|-----------|
 | `uint_32`, `int_32` | `number` | Varint |
 | `uint_64`, `int_64` | `bigint` | Varint |
-| `sint_32` | `number` | Varint |
-| `sint_64` | `bigint` | Varint |
+| `sint_32` | `number` | Varint (ZigZag) |
+| `sint_64` | `bigint` | Varint (ZigZag) |
 | `bool` | `boolean` | Varint |
 | `string` | `string` | LengthDelimited |
 | `bytes` | `Uint8Array` | LengthDelimited |
@@ -111,6 +147,14 @@ const data = protobuf_encode<Wrapper<Wrapper<string>>>({
 
 说明：
 - 所有 64 位整数类型在 TypeScript 中统一映射为 `bigint`
+- `sint_32` / `sint_64` 使用 ZigZag 编码，适用于频繁出现负数的场景
+
+## 包入口
+
+| 路径 | 用途 |
+|------|------|
+| `protobuf-fastdsl` | 用户代码 — `protobuf_encode`、`protobuf_decode`、所有类型 |
+| `protobuf-fastdsl/vite` | Vite 插件 |
 
 ## ⚡ 性能测试
 

package/dist/index.d.ts

@@ -20,8 +20,36 @@ interface ProtobufMessage {
     name: string;
     fields: ProtobufField[];
 }
+/** Generic interface template, e.g. `interface Wrapper<T> { val: pb<1, T>; }` */
+interface GenericProtobufTemplate {
+    name: string;
+    typeParams: string[];
+    fields: GenericFieldTemplate[];
+}
+interface GenericFieldTemplate {
+    name: string;
+    fieldNumber: number;
+    rawTypeName: string;
+    isTypeParam: boolean;
+    isOptional: boolean;
+    isRepeated: boolean;
+}
 type MessageRegistry = Map<string, ProtobufMessage>;
 
+interface ParsedFileEntry {
+    concrete: ProtobufMessage[];
+    templates: Map<string, GenericProtobufTemplate>;
+}
+interface ImportedDefinitions {
+    concrete: ProtobufMessage[];
+    templates: Map<string, GenericProtobufTemplate>;
+}
+/**
+ * Recursively resolve import-type declarations from a source file.
+ * Returns all protobuf interfaces and templates reachable through imports.
+ */
+declare function resolveImports(code: string, importerPath: string, cache: Map<string, ParsedFileEntry>): ImportedDefinitions;
+
 /**
  * Deterministic mangled name for a type node.
  *   `Foo`                → `Foo`
@@ -51,12 +79,12 @@ interface AnalysisResult {
  *
  * Then post-processes: monomorphize → resolve wire types → topo sort.
  */
-declare function analyze(code: string, filePath: string): AnalysisResult;
+declare function analyze(code: string, filePath: string, imported?: ImportedDefinitions): AnalysisResult;
 /**
  * Backward-compatible wrapper: returns only the MessageRegistry.
  * Uses the same single-walk analysis internally.
  */
-declare function analyzeSource(code: string, filePath: string): MessageRegistry;
+declare function analyzeSource(code: string, filePath: string, imported?: ImportedDefinitions): MessageRegistry;
 
 /**
  * Generate fully self-contained encode/decode source code.
@@ -83,4 +111,4 @@ declare function replaceCallSites(code: string, registry: MessageRegistry): {
 
 declare function protobufVitePlugin(): Plugin;
 
-export { analyze, analyzeSource, applyReplacements, protobufVitePlugin as default, generateCode, replaceCallSites, typeNodeToMangledName };
+export { analyze, analyzeSource, applyReplacements, protobufVitePlugin as default, generateCode, replaceCallSites, resolveImports, typeNodeToMangledName };

package/dist/index.js

@@ -166,13 +166,30 @@ function resolveTypeArg(node, sf, templates, out) {
 }
 
 // src/ast/analyzer.ts
-function analyze(code, filePath) {
+function analyze(code, filePath, imported) {
   const sf = ts4.createSourceFile(filePath, code, ts4.ScriptTarget.Latest, true);
   const concrete = [];
   const templates = /* @__PURE__ */ new Map();
   const mono = /* @__PURE__ */ new Map();
   const callSites = [];
   const deferredTypeArgs = [];
+  if (imported) {
+    concrete.push(...imported.concrete);
+    for (const [k, v] of imported.templates) templates.set(k, v);
+  }
+  const CANONICAL = /* @__PURE__ */ new Set(["protobuf_encode", "protobuf_decode"]);
+  const aliasToCanonical = /* @__PURE__ */ new Map();
+  for (const stmt of sf.statements) {
+    if (!ts4.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    const bindings = stmt.importClause.namedBindings;
+    if (!bindings || !ts4.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      const originalName = (el.propertyName ?? el.name).text;
+      if (CANONICAL.has(originalName)) {
+        aliasToCanonical.set(el.name.text, originalName);
+      }
+    }
+  }
   ts4.forEachChild(sf, function visit(node) {
     if (ts4.isInterfaceDeclaration(node)) {
       if (node.typeParameters?.length) {
@@ -185,16 +202,19 @@ function analyze(code, filePath) {
     }
     if (ts4.isCallExpression(node)) {
       const e = node.expression;
-      if (ts4.isIdentifier(e) && (e.text === "protobuf_encode" || e.text === "protobuf_decode")) {
-        const ta = node.typeArguments;
-        if (ta?.length) {
-          deferredTypeArgs.push(ta[0]);
-          callSites.push({
-            fnName: e.text,
-            exprStart: e.getStart(sf),
-            typeArgsEnd: ta.end + 1,
-            firstTypeArg: ta[0]
-          });
+      if (ts4.isIdentifier(e)) {
+        const canonical = CANONICAL.has(e.text) ? e.text : aliasToCanonical.get(e.text);
+        if (canonical) {
+          const ta = node.typeArguments;
+          if (ta?.length) {
+            deferredTypeArgs.push(ta[0]);
+            callSites.push({
+              fnName: canonical,
+              exprStart: e.getStart(sf),
+              typeArgsEnd: ta.end + 1,
+              firstTypeArg: ta[0]
+            });
+          }
         }
       }
     }
@@ -219,8 +239,8 @@ function analyze(code, filePath) {
   }
   return { registry: topoSort(concrete), callSites, sourceFile: sf };
 }
-function analyzeSource(code, filePath) {
-  return analyze(code, filePath).registry;
+function analyzeSource(code, filePath, imported) {
+  return analyze(code, filePath, imported).registry;
 }
 function topoSort(messages) {
   const map = new Map(messages.map((m) => [m.name, m]));
@@ -1107,18 +1127,34 @@ function applyReplacements(code, sf, callSites, registry) {
 function replaceCallSites(code, registry) {
   const sf = ts5.createSourceFile("input.ts", code, ts5.ScriptTarget.Latest, true);
   const callSites = [];
+  const CANONICAL = /* @__PURE__ */ new Set(["protobuf_encode", "protobuf_decode"]);
+  const aliasToCanonical = /* @__PURE__ */ new Map();
+  for (const stmt of sf.statements) {
+    if (!ts5.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    const bindings = stmt.importClause.namedBindings;
+    if (!bindings || !ts5.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      const originalName = (el.propertyName ?? el.name).text;
+      if (CANONICAL.has(originalName)) {
+        aliasToCanonical.set(el.name.text, originalName);
+      }
+    }
+  }
   ts5.forEachChild(sf, function visit(node) {
     if (ts5.isCallExpression(node)) {
       const e = node.expression;
-      if (ts5.isIdentifier(e) && (e.text === "protobuf_encode" || e.text === "protobuf_decode")) {
-        const ta = node.typeArguments;
-        if (ta?.length) {
-          callSites.push({
-            fnName: e.text,
-            exprStart: e.getStart(sf),
-            typeArgsEnd: ta.end + 1,
-            firstTypeArg: ta[0]
-          });
+      if (ts5.isIdentifier(e)) {
+        const canonical = CANONICAL.has(e.text) ? e.text : aliasToCanonical.get(e.text);
+        if (canonical) {
+          const ta = node.typeArguments;
+          if (ta?.length) {
+            callSites.push({
+              fnName: canonical,
+              exprStart: e.getStart(sf),
+              typeArgsEnd: ta.end + 1,
+              firstTypeArg: ta[0]
+            });
+          }
         }
       }
     }
@@ -1127,19 +1163,110 @@ function replaceCallSites(code, registry) {
   return applyReplacements(code, sf, callSites, registry);
 }
 
+// src/ast/import-resolver.ts
+import ts6 from "typescript";
+import { readFileSync, existsSync } from "fs";
+import { dirname, resolve } from "path";
+function extractImports(sf) {
+  const result = [];
+  for (const stmt of sf.statements) {
+    if (!ts6.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    const spec = stmt.moduleSpecifier;
+    if (!ts6.isStringLiteral(spec)) continue;
+    const specifier = spec.text;
+    const clause = stmt.importClause;
+    const names = [];
+    if (clause.namedBindings && ts6.isNamedImports(clause.namedBindings)) {
+      for (const el of clause.namedBindings.elements) {
+        names.push(el.name.text);
+      }
+    }
+    if (names.length > 0) result.push({ names, specifier });
+  }
+  return result;
+}
+function resolveModulePath(specifier, importerPath) {
+  if (!specifier.startsWith(".")) return null;
+  const base = resolve(dirname(importerPath), specifier);
+  if (existsSync(base) && !base.endsWith(".ts") === false) return base;
+  if (base.endsWith(".ts") && existsSync(base)) return base;
+  const withTs = base + ".ts";
+  if (existsSync(withTs)) return withTs;
+  const indexTs = resolve(base, "index.ts");
+  if (existsSync(indexTs)) return indexTs;
+  return null;
+}
+function parseFileForDefinitions(absolutePath) {
+  const code = readFileSync(absolutePath, "utf-8");
+  const sf = ts6.createSourceFile(absolutePath, code, ts6.ScriptTarget.Latest, true);
+  const concrete = [];
+  const templates = /* @__PURE__ */ new Map();
+  for (const stmt of sf.statements) {
+    if (!ts6.isInterfaceDeclaration(stmt)) continue;
+    if (stmt.typeParameters?.length) {
+      const tpl = collectGenericInterface(stmt, sf);
+      if (tpl) templates.set(tpl.name, tpl);
+    } else {
+      const msg = collectInterface(stmt, sf);
+      if (msg) concrete.push(msg);
+    }
+  }
+  return { concrete, templates };
+}
+function resolveImports(code, importerPath, cache) {
+  const concrete = [];
+  const templates = /* @__PURE__ */ new Map();
+  const visiting = /* @__PURE__ */ new Set();
+  function walk(filePath, fileCode) {
+    const abs = resolve(filePath);
+    if (visiting.has(abs)) return;
+    visiting.add(abs);
+    const src = fileCode ?? readFileSync(abs, "utf-8");
+    const sf = ts6.createSourceFile(abs, src, ts6.ScriptTarget.Latest, true);
+    const imports = extractImports(sf);
+    for (const imp of imports) {
+      const resolved = resolveModulePath(imp.specifier, abs);
+      if (!resolved) continue;
+      let entry = cache.get(resolved);
+      if (!entry) {
+        entry = parseFileForDefinitions(resolved);
+        cache.set(resolved, entry);
+      }
+      for (const msg of entry.concrete) {
+        if (!concrete.some((m) => m.name === msg.name)) {
+          concrete.push(msg);
+        }
+      }
+      for (const [name, tpl] of entry.templates) {
+        if (!templates.has(name)) templates.set(name, tpl);
+      }
+      walk(resolved);
+    }
+  }
+  walk(importerPath, code);
+  return { concrete, templates };
+}
+
 // src/index.ts
 function protobufVitePlugin() {
+  const fileCache = /* @__PURE__ */ new Map();
   return {
     name: "vite-plugin-protobuf",
     enforce: "pre",
     transform(code, id) {
       if (!id.endsWith(".ts") || id.endsWith(".d.ts")) return null;
-      const { registry, callSites, sourceFile } = analyze(code, id);
-      if (registry.size === 0) return null;
+      const imported = resolveImports(code, id, fileCache);
+      const { registry, callSites, sourceFile } = analyze(code, id, imported);
+      if (registry.size === 0 && callSites.length === 0) return null;
       const generatedCode = generateCode(registry);
       const { transformedCode, hasReplacements } = applyReplacements(code, sourceFile, callSites, registry);
       if (!hasReplacements && generatedCode === "") return null;
       return { code: generatedCode + "\n" + transformedCode, map: null };
+    },
+    handleHotUpdate({ file }) {
+      if (file.endsWith(".ts")) {
+        fileCache.delete(file);
+      }
     }
   };
 }
@@ -1150,5 +1277,6 @@ export {
   protobufVitePlugin as default,
   generateCode,
   replaceCallSites,
+  resolveImports,
   typeNodeToMangledName
 };

package/dist/runtime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runtime fallback functions.
+ * If the Vite plugin is active, calls to protobuf_encode/decode are replaced
+ * at compile-time with generated type-specific functions.
+ * If NOT transformed, these fallbacks throw to alert the developer.
+ */
+declare function protobuf_encode<T>(_params: T): Uint8Array;
+declare function protobuf_decode<T>(_data: Uint8Array): T;
+
+export { protobuf_decode, protobuf_encode };

package/dist/runtime.js

@@ -0,0 +1,15 @@
+// src/runtime.ts
+function protobuf_encode(_params) {
+  throw new Error(
+    "protobuf_encode<T>() was not transformed by the protobuf-fastdsl Vite plugin. Make sure protobufVitePlugin() is added to your vite.config.ts plugins array."
+  );
+}
+function protobuf_decode(_data) {
+  throw new Error(
+    "protobuf_decode<T>() was not transformed by the protobuf-fastdsl Vite plugin. Make sure protobufVitePlugin() is added to your vite.config.ts plugins array."
+  );
+}
+export {
+  protobuf_decode,
+  protobuf_encode
+};

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "protobuf-fastdsl",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/runtime.js",
+  "types": "protobuf.d.ts",
   "files": [
     "dist",
     "protobuf.d.ts"
   ],
   "exports": {
     ".": {
+      "types": "./protobuf.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./vite": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./protobuf.d.ts"
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
+    "build": "tsup src/index.ts src/runtime.ts --format esm --dts",
     "test": "vitest run",
     "test:watch": "vitest",
     "bench": "npx tsx bench/index.ts"
@@ -29,6 +30,9 @@
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
+  "peerDependenciesMeta": {
+    "vite": { "optional": true }
+  },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "tsup": "^8.0.0",

package/protobuf.d.ts

@@ -1,25 +1,25 @@
-// ── Protobuf field markers ────────────────────────────────────────────
-/** Marks a singular protobuf field: `name: pb<fieldNumber, Type>` */
-type pb<_ProtoNumber extends number, Type> = Type;
-/** Marks a repeated protobuf field: `ids: pb_repeated<fieldNumber, Type>` → Type[] */
-type pb_repeated<_ProtoNumber extends number, Type> = Type[];
-
-// ── Protobuf primitive types ──────────────────────────────────────────
-type uint_32 = number;
-type int_32 = number;
-type uint_64 = bigint;
-type int_64 = bigint;
-type sint_32 = number;
-type sint_64 = bigint;
-type bool = boolean;
-type float = number;
-type double = number;
-type fixed_32 = number;
-type fixed_64 = bigint;
-type sfixed_32 = number;
-type sfixed_64 = bigint;
-type bytes = Uint8Array;
-
-// ── Encode / decode stubs (replaced at compile-time by the vite plugin) ──
-declare function protobuf_encode<T>(params: T): Uint8Array;
-declare function protobuf_decode<T>(data: Uint8Array): T;
+// ── Protobuf field markers ────────────────────────────────────────────
+/** Marks a singular protobuf field: `name: pb<fieldNumber, Type>` */
+export type pb<_ProtoNumber extends number, Type> = Type;
+/** Marks a repeated protobuf field: `ids: pb_repeated<fieldNumber, Type>` → Type[] */
+export type pb_repeated<_ProtoNumber extends number, Type> = Type[];
+
+// ── Protobuf primitive types ──────────────────────────────────────────
+export type uint_32 = number;
+export type int_32 = number;
+export type uint_64 = bigint;
+export type int_64 = bigint;
+export type sint_32 = number;
+export type sint_64 = bigint;
+export type bool = boolean;
+export type float = number;
+export type double = number;
+export type fixed_32 = number;
+export type fixed_64 = bigint;
+export type sfixed_32 = number;
+export type sfixed_64 = bigint;
+export type bytes = Uint8Array;
+
+// ── Encode / decode (replaced at compile-time by the vite plugin) ────
+export function protobuf_encode<T>(params: T): Uint8Array;
+export function protobuf_decode<T>(data: Uint8Array): T;