rxdb-client-generator

RxDB 客户端代码生成器，从实体定义生成 JavaScript 实体入口和 TypeScript 声明。

功能

• 生成单文件或按实体拆分的客户端代码
• 生成 RxDB、Repository、关系和查询规则类型
• 提供 CLI 与 Vite 插件
• 使用 manifest 只清理由生成器拥有的陈旧输出，不删除输出目录中的其他文件

安装

pnpm add -D @aiao/rxdb-client-generator

CLI

rxdb-client-generator ./rxdb.config.ts

配置文件由 jiti 执行，可以导出一个配置或配置数组：

export default {
  entities: ['./src/entities/**/*.ts'],
  outDir: './src/generated',
  relationQueryDeep: 3,
  splitFiles: true
};

路径相对于配置文件解析。多个不同的输出目录可以并行生成；同一个物理 outDir（包括规范化路径和软链别名）不能出现在多个配置中。需要聚合生成时，请合并 entities patterns，只保留一项输出配置。

默认采用 fail-closed：entities 为空、任一 glob 零匹配或所有文件都没有实体时，保留旧产物并报错。 确实需要空客户端时必须显式设置 allowEmpty: true。

分析器一次把全部实体文件加载进共享 TypeScript Project；跨文件、多层继承不依赖 glob 顺序。 带实体装饰器的父类无法解析时会直接报错，不生成缺少父字段的客户端。

Vite 插件

单配置：

import { rxdbClientGeneratorVitePlugin } from '@aiao/rxdb-client-generator/vite';

export default {
  plugins: [
    rxdbClientGeneratorVitePlugin({
      entities: ['./src/entities/**/*.ts'],
      outDir: './src/generated'
    })
  ]
};

多配置：

rxdbClientGeneratorVitePlugin([
  {
    entities: ['./src/entities/**/*.ts'],
    outDir: './src/generated'
  },
  {
    entities: ['./src/admin/**/*.ts'],
    outDir: './src/generated-admin'
  }
]);

生产构建在 buildStart 生成，产物会参与当前 bundle 的模块解析。开发服务器启动前先生成， 随后监听实体文件的增删改；重建按单飞队列串行执行，成功后触发 full reload，失败显示 Vite error overlay。

自定义 Repository 生成器

GeneratorContext.file 是纯内存 SourceFile。使用 getText() 读取生成文本；磁盘提交由 CLI/Vite 构建器负责，save() 与 saveSync() 会明确抛错。公开结构中可用于声明文件的 scope、可选成员和 rest 参数会被渲染；initializer、definite assignment、async/body 与 decorator 等不适用于 ambient declaration 的字段会 fail-fast，不会静默丢弃。

实体元数据安全边界

实体扫描不会执行装饰器参数。@Entity、@TreeEntity、@GraphEntity 的参数必须是可静态求值的内联对象，只允许：

• 对象、数组
• 字符串、数字、布尔值、null
• PropertyType.*、RelationKind.*、OnDeleteAction.*
• 仅用于类型收窄的括号、as、satisfies

局部变量、函数调用、箭头函数、对象展开、计算属性名和其他动态表达式会直接报错；错误包含文件路径、行和列。配置文件仍按现有合同由 jiti 执行。

输出所有权

每个 outDir 会写入 .rxdb-client-generator-manifest.json。后续生成只删除旧 manifest 中存在、但本次不再生成的文件；手写文件和其他工具输出不会被清理。损坏或越界的 manifest 会直接报错，不会静默忽略。

Fileoverview

RxDB Client Generator RxDB 客户端代码生成器，从实体元数据生成类型定义和实体类代码

主要功能：

• 从 EntityMetadata 生成 .d.ts 类型定义文件
• 生成实体类的 .js 文件（使用装饰器）
• 支持分文件（splitFiles）和单文件两种生成模式
• 通过 repositoryGenerators 装载插件包提供的扩展 Repository 生成器

Classes

Class	Description
RepositoryGeneratorBase	基础 Repository 生成器（抽象基类） 提供通用工具方法，子类继承后生成各自的 Repository 属性和方法
RepositoryMethodsGenerator	Repository 生成器 为所有 Entity 生成通用的 CRUD 属性和方法：get, find, findOne, save, remove 等
RxDBClientGenerator	RxDB Client 生成器

Interfaces

Interface	Description
EntitySourceGetter	从实体源码保留到生成运行时与声明文件的只读 getter。
GeneratorContext	Generator 上下文 包含生成属性和方法所需的所有上下文信息
IRepositoryGenerator	Repository 生成器接口
RepositoryGeneratorSymbols	生成器自报的产物符号
RepositoryGeneratorTypeSymbol	生成器自报的一个顶层类型名。
RuleTypeData	单条查询规则的类型描述。
RxDBClientGeneratorOptions	RxDB 客户端生成器的代码形态与查询类型配置。
SourceFile	生成器使用的轻量源文件接口。

Variables

Variable	Description
NAMESPACE_PUBLIC	生成代码使用的默认 namespace。未提供 namespace 的实体归入此空间。
REPOSITORY_TYPE_GRAPH_REPOSITORY	图 Repository 生成器的注册名称，供插件扩展使用。
REPOSITORY_TYPE_REPOSITORY	内置普通 Repository 生成器的注册名称。
REPOSITORY_TYPE_TREE_REPOSITORY	树 Repository 生成器的注册名称，供插件扩展使用。

Functions

Function	Description
buildRules	把规则数据渲染成规则类型字面量，并顺带登记所需的命名导入。
generateEntityRules	递归收集一个实体（含外键与关系对端）的全部查询规则。