@dudousxd/nestjs-codegen (英语)

NestJS——路线,API客户端的可广泛打入客户端代码和验证计划.

nestjs-codegen 读你的NestJS控制器, defineContract 合同,DTO,以及 (可选) Inertia 页面通过 ts-形态,建立中性计划 红外线,并发出a 全类型客户端: 路由图,图约风格的API客户端,以及 客户端验证计划。 有用吗 不论有无,每个移动 部分是可插件的 — 验证库、 HTTP 客户端、 序列器和查询 层.

安装

pnpm add -D @dudousxd/nestjs-codegen
# a validation adapter (no adapter is bundled in core) — zod shown; or -valibot / -arktype:
pnpm add -D @dudousxd/nestjs-codegen-zod
# the runtime the generated client imports its Fetcher type from:
pnpm add @dudousxd/nestjs-client

生成的 api.ts 进口 Fetcher 类型从 @dudousxd/nestjs-client,所以这是一个 实时依赖. @nestjs/common, (中文(简体) ), tsx,以及 typescript 是同伴的依赖关系 (单位:千美元)@nestjs/common 财务报告和审定财务报表 tsx 是可选的, 您的 Nest 应用程序已经拥有了 .

快开始

导入 NestjsCodegenModule 输入您的根模块。 代码源始于您的 Dev 服务器 在您编辑控制器时重生客户端 — 没有配置文件, 没有额外进程. 监视器是一个 dev/CI 关切,所以模块在 NODE_ENV === 'production'。 。 。 .

import { Module } from '@nestjs/common';
import { NestjsCodegenModule } from '@dudousxd/nestjs-codegen/nest';
import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';

@Module({
  imports: [
    NestjsCodegenModule.forRoot({
      // controllers to scan for routes + contracts
      contracts: { glob: 'src/**/*.controller.ts' },
      // output directory for the generated files
      codegen: { outDir: 'src/generated' },

      validation: zodAdapter, // zodAdapter | valibotAdapter | arktypeAdapter
    }),
  ],
})
export class AppModule {}

生成的 api.ts 出口a createApi(fetcher) 工厂 - 创建客户端一次, 注射你的取水器。 每个终点都是 统一可等待的手柄: 一个懒惰的,被纪念的 Promise —— 说 await 它(或从一株取回) mutationFn运行请求.

import { createApi } from '../generated/api';
import { createFetcher } from '@dudousxd/nestjs-client';

export const api = createApi(createFetcher({ baseUrl: '/api' }));

const users = await api.users.list();              // typed User[]
const created = await api.users.create({ body });  // typed body + response

它会产生什么

代码将这些文件写入您的输出目录 :

• routes.ts a 包括: ROUTES 地图, a RouteName 结合,并输入 route() 帮手.
• api.ts -图约式的 createApi(fetcher) 工厂,以路由名称为巢,完全打字.
• forms.ts ——每个验证的终点的验证计划,在您选择的 lib 中.
• pages.d.ts 编号 : components.json ——当Inertia集成启用时.

扩展和生态系统

核心之外的一切都是可插接的. 扩展通过 extensions: [...]· ; 验证适配器通过 validation: ...。 。 。 .

import { NestjsCodegenModule } from '@dudousxd/nestjs-codegen/nest';
import { tanstackQuery } from '@dudousxd/nestjs-codegen-tanstack';
import { nestjsFilterCodegen } from '@dudousxd/nestjs-filter-codegen';
import { nestjsInertiaCodegen } from '@dudousxd/nestjs-inertia-codegen-extension';
import { arktypeAdapter } from '@dudousxd/nestjs-codegen-arktype';

NestjsCodegenModule.forRoot({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  validation: arktypeAdapter, // render the IR as arktype instead of zod
  extensions: [tanstackQuery(), nestjsFilterCodegen(), nestjsInertiaCodegen()],
});

TanStack扩展注册后,每个生成的叶子都成为了统一的柄: await api.users.show({ params }) 执行请求,以及 不变 手柄载具 .queryOptions() 编号 : .mutationOptions() 编号 : .infiniteQueryOptions() 编号 : .queryKey()。 。 。 .

import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '../lib/api';

const users = useQuery(api.users.list().queryOptions());
const create = useMutation(api.users.create().mutationOptions());

Generative-UI 沙盒套件(装入)

genuiSandboxKit() 写沙盒- kit 文档 @dudousxd/nestjs-agent 用于制造 你设计系统中的基因UI 组件的名称和道具(从它们读取) TypeScript 类型, 以及您的样式, 转到 .genui/sandbox-kit.json这发生在 每个生成和监视模式。 它需要可选的对等点 @dudousxd/nestjs-agent-core (>=0.53.

import { defineConfig, genuiSandboxKit } from '@dudousxd/nestjs-codegen';

export default defineConfig({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  extensions: [genuiSandboxKit({ components: 'web/components/ui', styles: 'web/styles/globals.css' })],
});

选项( 与代理的 Vite 插件相同 ) :

• components (默认: 第一个阴影) components/ui 找到目录 , styles, (中文(简体) ), wrapper, (中文(简体) ), stylesDocs, (中文(简体) ), tsconfig· ;
• output (默认) .genui/sandbox-kit.json,相对于应用程序 cwd;
• generate,以注入文件撰写器.

写你自己对 @dudousxd/nestjs-codegen/extension 合同:

import { defineExtension, type CodegenExtension } from '@dudousxd/nestjs-codegen/extension';

国 际

对于 CI( 在部署前) 您想要一个一发, 无监视运行, 如果 忠实的客户已经漂移。 包裹运送 nestjs-codegen CLI: 爱丽丝

npx nestjs-codegen codegen   # one-shot generate (CI); pair with `git diff --exit-code`
npx nestjs-codegen init      # scaffold nestjs-codegen.config.ts
npx nestjs-codegen doctor    # diagnose your setup

CLI读取 nestjs-codegen.config.ts (遗产) nestjs-inertia.config.ts 名称是 从您的工程根。 通过撰写选项保留一个单一的真相来源 与 defineConfig 输入到 forRoot()数字 :

import { defineConfig } from '@dudousxd/nestjs-codegen';
import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';

export default defineConfig({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  validation: zodAdapter,
});

npx nestjs-codegen codegen
git diff --exit-code src/generated   # non-zero if the client is stale

文档

完整文件——启动、配置、验证适配器、取取取器和 展期合同——居住在repo:

• 仓库和文件 : https://github.com/Davide Carvalho/nestjs-codegen 互联网档案馆的存檔,存档日期2013-12-22

许可证

麻省理工学院