@hodfords/nestjs-grpc-helper 11.4.0 → 11.5.1

package/README.md

@@ -3,33 +3,83 @@
 </p>
 
 <p align="center">
-<b>nestjs-grpc-helper</b> simplifies gRPC integration in NestJS, allowing seamless communication between services. It enables easy setup of gRPC clients and servers, and supports building SDK packages that any service can import and use, ensuring consistent API interaction across your microservices architecture.
+<b>nestjs-grpc-helper</b> simplifies gRPC integration in NestJS. Define your microservices with decorators, and the library generates the proto files, a fully typed TypeScript SDK, interactive documentation, and mock data — keeping every consumer of your services consistent and type-safe.
 </p>
 
-## Installation 🤖
+## Table of Contents 📚
+
+- [How It Works](#how-it-works-)
+- [Installation](#installation-)
+- [Quick Start](#quick-start-)
+- [Defining DTOs and Responses](#defining-dtos-and-responses-)
+- [Decorator Reference](#decorator-reference-)
+- [Type Helpers](#type-helpers-)
+- [Mock Data](#mock-data-)
+- [Generating an SDK](#generating-an-sdk-)
+- [Using a Generated SDK](#using-a-generated-sdk-)
+- [Documentation UI](#documentation-ui-)
+- [Custom gRPC Client](#custom-grpc-client-)
+- [Translation Support](#translation-support-)
+- [AI Agent Skill](#ai-agent-skill-)
+- [License](#license-)
+
+## How It Works 🧠
+
+The library follows a metadata-driven code generation flow:
 
-Install the `nestjs-grpc-helper` package with:
+1. **Decorators** such as `@RegisterGrpcMicroservice`, `@GrpcAction`, and `@Property` attach metadata to your classes at
+   load time.
+2. From that metadata, the library can generate a **`.proto` file**, a **TypeScript SDK package** that other services
+   import for type-safe calls, an **interactive documentation UI**, and **mock implementations** for testing.
+
+You write your service once; everything downstream is derived from it.
+
+## Installation 🤖
 
 ```bash
 npm install @hodfords/nestjs-grpc-helper --save
 ```
 
-Next, automatically generate the proto file and include it in main.ts before starting the application:
+Responses must follow the [@hodfords/nestjs-response](https://www.npmjs.com/package/@hodfords/nestjs-response)
+conventions, and the `make-sdk` / `update-ai-skill` commands run through
+[@hodfords/nestjs-command](https://www.npmjs.com/package/@hodfords/nestjs-command).
+
+## Quick Start 🚀
+
+### 1. Define a request DTO and a response
 
 ```typescript
-import { generateProtoService } from '@hodfords/nestjs-grpc-helper';
+import { Property } from '@hodfords/nestjs-grpc-helper';
+import { IsString, IsOptional } from 'class-validator';
 
-generateProtoService(camelCase(env.APP_NAME), env.ROOT_PATH + '/../');
-```
+export class GetUserByIdDto {
+    @Property({ type: String, description: 'User id to look up' })
+    @IsString()
+    userId: string;
+}
 
-## Usage 🚀
+export class UserResponse {
+    @Property({ type: String, required: false })
+    @IsString()
+    @IsOptional()
+    name?: string;
 
-### Creating microservices
+    @Property({ type: Boolean, required: false })
+    isAdmin?: boolean;
+}
+```
 
-Create microservices using the `@GrpcMicroservice` decorator, similar to how you would use a Controller. Ensure that the response adheres to the [nestjs-response](https://www.npmjs.com/package/@hodfords/nestjs-response) rules:
+### 2. Define the microservice
+
+A gRPC microservice is declared like a controller. Each `@GrpcAction` method becomes an rpc in the generated proto and a
+method in the generated SDK:
 
 ```typescript
-@GrpcMicroservice()
+import { GrpcAction, GrpcValue, RegisterGrpcMicroservice } from '@hodfords/nestjs-grpc-helper';
+import { ResponseModel } from '@hodfords/nestjs-response';
+
+@Controller()
+@RegisterGrpcMicroservice('User microservice')
 export class UserMicroservice {
     constructor(private userService: UserService) {}
 
@@ -41,160 +91,417 @@ export class UserMicroservice {
 }
 ```
 
-### Any Type
+`@ResponseModel` supports single models, arrays, primitives, and nullable results:
 
-You can use any type if fixed types are not an option. However, since it’s passed as JSON, the performance may not be as optimal as with binary. Consider using binary if performance is a concern.
+```typescript
+@ResponseModel(UserResponse)                        // single object
+@ResponseModel(UserResponse, true)                  // array of objects
+@ResponseModel(String)                              // primitive (String, Number, Boolean)
+@ResponseModel(UserResponse, { isAllowEmpty: true }) // object or null
+```
+
+### 3. Generate the proto file and start the gRPC server
+
+Generate the proto file before the application starts, then connect the gRPC microservice:
 
 ```typescript
-@Property({ type: String, format: 'any', required: false })
+import { generateProtoService } from '@hodfords/nestjs-grpc-helper';
+import { Transport } from '@nestjs/microservices';
+import path from 'path';
+
+generateProtoService('packageName', path.join(__dirname, '../../proto'));
+
+async function bootstrap() {
+    const app = await NestFactory.create(AppModule);
+    app.connectMicroservice<GrpcOptions>({
+        transport: Transport.GRPC,
+        options: {
+            url: '0.0.0.0:50059',
+            package: 'packageName',
+            protoPath: path.join(__dirname, '../../proto/microservice.proto')
+        }
+    });
+    await app.startAllMicroservices();
+    await app.listen(3000);
+}
+```
+
+## Defining DTOs and Responses 📦
+
+`@Property` is the single source of truth for a field. It registers the field for proto generation, SDK generation, and
+Swagger documentation at the same time.
+
+```typescript
+export class FindManyDto {
+    @Property({ type: 'string', description: 'Name of user to search' })
+    @IsString()
+    name: string;
+
+    @Property({ type: ParamNestedDto, isArray: true, required: true })
+    nestedDto: ParamNestedDto[];
+
+    @Property({ type: String, required: false, enum: UserTypeEnum, enumName: 'UserTypeEnum' })
+    @IsEnum(UserTypeEnum)
+    @IsOptional()
+    type?: UserTypeEnum;
+}
+```
+
+Commonly used options (all [ApiPropertyOptions](https://docs.nestjs.com/openapi/types-and-parameters) are also
+accepted):
+
+| Option              | Description                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| `type`              | `String`, `Number`, `Boolean`, a class reference, a lazy `() => Class`, or a string literal |
+| `isArray`           | Marks the field as repeated                                                                 |
+| `required`          | `false` makes the field optional in the proto and SDK                                       |
+| `description`       | Description used in documentation and the AI skill                                          |
+| `format`            | Refines numbers (`'int32'`, `'float'`, …) or marks a string as dynamic JSON (`'any'`)       |
+| `enum` / `enumName` | Declares an enum field; `enumName` names the generated enum                                 |
+
+### Dynamic (`any`) fields
+
+For values without a fixed schema, combine `format: 'any'` with `@AnyType`. The value is serialized to JSON on the wire
+and parsed back transparently:
+
+```typescript
+@Property({ type: 'string', format: 'any' })
 @AnyType()
 data: any;
 ```
 
-### Create SDK
+## Decorator Reference 🏷️
+
+### Service and method decorators
+
+| Decorator                                 | Description                                                                                 |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `@RegisterGrpcMicroservice(description?)` | Marks a class as a gRPC microservice                                                        |
+| `@GrpcAction(description?)`               | Marks a method as a gRPC action/endpoint                                                    |
+| `@SdkFlattenParams()`                     | Flattens the request DTO's properties into individual arguments in the generated SDK method |
+
+### Request parameter decorators
+
+| Decorator            | Description                                                                   |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `@GrpcValue()`       | Marks a parameter as the request body (used with a DTO type)                  |
+| `@GrpcParam(option)` | Defines a direct request parameter with name, type, and validation decorators |
+| `@GrpcId(name)`      | Shortcut for a required UUID string parameter (`IsNotEmpty` + `IsUUID`)       |
+| `@GrpcIds(name)`     | Shortcut for a required array of UUID strings                                 |
+| `@GrpcEnum(option)`  | Enum parameter with automatic type detection and `IsEnum` validation          |
+| `@GrpcEnums(option)` | Array variant of `@GrpcEnum`                                                  |
+| `@GrpcPagination()`  | Built-in pagination parameter (`page`, `perPage`)                             |
+| `@GrpcSort()`        | Built-in sort parameter (`sortField`, `sortDirection: 'ASC' \| 'DESC'`)       |
+
+Direct parameters can be mixed with a `@GrpcValue` body and gRPC metadata in the same method:
+
+```typescript
+@GrpcAction('List users with pagination, sorting, and workspace scoping')
+@ResponseModel(UserResponse, true)
+listUsers(
+    @GrpcValue() param: FilterDto,
+    @GrpcPagination() pagination: PaginationDto,
+    @GrpcSort() sortParam: SortDto,
+    @GrpcMetadataId('workspace-id') workspaceId: string
+): Promise<UserResponse[]> { ... }
+```
+
+### Metadata decorators
+
+| Decorator               | Description                                        |
+| ----------------------- | -------------------------------------------------- |
+| `@GrpcMetadata(option)` | Extracts a value from gRPC metadata (like headers) |
+| `@GrpcMetadataId(name)` | Shortcut for a UUID metadata field                 |
 
-To generate a TypeScript SDK for your gRPC services, you can use the `make-sdk` command. This command will automatically generate the necessary proto files and package them into a JavaScript SDK.
-You also need the following configuration in your sdk-config.json file:
+### Property and type decorators
+
+| Decorator             | Description                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `@Property(option)`   | Defines a DTO/response field with type, validation, and Swagger metadata                  |
+| `@AnyType(option?)`   | JSON serialization for dynamic `any` fields (`{ isDto: true }` parses into the DTO class) |
+| `@ExtendType(Parent)` | Inherits the parent's property metadata when extending a composed type                    |
+| `@SdkExpose()`        | Forces a class into the generated SDK even when no rpc references it                      |
+
+## Type Helpers 🧬
+
+Compose DTOs while preserving the property metadata needed for proto and SDK generation. These mirror the
+`@nestjs/swagger` mapped types:
+
+```typescript
+import {
+    PickResponseType,
+    OmitResponseType,
+    PartialResponseType,
+    IntersectionResponseType
+} from '@hodfords/nestjs-grpc-helper';
+
+export class UserSummary extends PickResponseType(UserResponse, ['id', 'name']) {}
+export class UserWithoutEmail extends OmitResponseType(UserResponse, ['email']) {}
+export class UpdateUserDto extends PartialResponseType(UserResponse) {}
+export class FullUser extends IntersectionResponseType(UserResponse, ProfileResponse) {}
+```
+
+## Mock Data 🎭
+
+Mock generation powers both the documentation UI and the mock SDK module. Property-level decorators describe how each
+field is faked; response-level decorators override the result of a whole method.
+
+### Property-level decorators
+
+| Decorator                    | Description                                  |
+| ---------------------------- | -------------------------------------------- |
+| `@MockMethod(method, args?)` | Generates the value with a Faker method      |
+| `@MockSample(value)`         | Uses a fixed value                           |
+| `@MockNested(maxSize?)`      | Generates nested objects (or arrays of them) |
+
+```typescript
+export class UserResponse {
+    @Property({ type: String, required: false })
+    @MockMethod('faker.person.firstName')
+    name?: string;
+
+    @Property({ type: String, enum: UserTypeEnum, enumName: 'UserTypeEnum' })
+    @MockSample(UserTypeEnum.STANDARD)
+    type: UserTypeEnum;
+
+    @Property({ type: AddressResponse, isArray: true })
+    @MockNested(5)
+    addresses: AddressResponse[];
+}
+```
+
+### Response-level decorators
+
+| Decorator                            | Description                                                         |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `@MockResponseSample(value)`         | The mocked method returns this fixed value                          |
+| `@MockResponseMethod(method, args?)` | The mocked method returns the result of a Faker method              |
+| `@MockResponseCallback(callback)`    | Full control: receives the request arguments plus `(sample, model)` |
+
+```typescript
+@GrpcAction('Check if a user is active')
+@ResponseModel(Boolean)
+@MockResponseSample(true)
+checkUserActive(@GrpcValue() param: AnyDto): Promise<boolean> { ... }
+
+@GrpcAction('Count users')
+@ResponseModel(Number)
+@MockResponseMethod('faker.number.int', [{ min: 1, max: 100 }])
+countUsers(@GrpcValue() param: AnyDto): Promise<number> { ... }
+
+@GrpcAction('Get users by name')
+@ResponseModel(UserResponse, true)
+@MockResponseCallback((param: AnyDto, sample, model) => sample(model))
+getUsersByName(@GrpcValue() param: AnyDto): Promise<UserResponse[]> { ... }
+```
+
+### Generating mock instances programmatically
+
+```typescript
+import { sample } from '@hodfords/nestjs-grpc-helper';
+
+const mockUser = sample(UserResponse);
+```
+
+## Generating an SDK 🛠️
+
+The `make-sdk` command collects every request and response type reachable from your `@GrpcAction` methods, generates the
+proto file, and packages everything into a TypeScript SDK that other services install like any npm package.
+
+Add an `sdk-config.json` to your project root:
 
 ```json
 {
-  "name": "sdkName",
-  "packageName": "@hodfords/package-name",
-  "format": true,
-  "build": true,
-  "output": "sdk",
-  "outputBuild": "sdkBuild",
-  "removeOutput": true,
-  "addAllowDecorator": true,
-  "tsconfig": {
-    "extends": "./tsconfig.json",
-    "compilerOptions": {
-      "outDir": "sdkBuild"
+    "name": "sdkName",
+    "packageName": "@hodfords/package-name",
+    "format": true,
+    "build": true,
+    "output": "sdk",
+    "outputBuild": "sdkBuild",
+    "removeOutput": true,
+    "addAllowDecorator": true,
+    "aiSkill": {
+        "name": "sdkName",
+        "description": "A description of the SDK"
     },
-    "include": ["sdk"]
-  }
+    "tsconfig": {
+        "extends": "./tsconfig.json",
+        "compilerOptions": {
+            "outDir": "sdkBuild"
+        },
+        "include": ["sdk"]
+    }
 }
 ```
-Details of the configuration:
-
-| Field             | Description                                           |
-|-------------------|-------------------------------------------------------|
-| name              | Name of the SDK                                       |
-| packageName       | Name of the package                                   |
-| format            | Format the generated code                             |
-| build             | Build the generated code                              |
-| output            | Output directory for the generated code               |
-| outputBuild       | Output directory for the built code                   |
-| removeOutput      | Remove the output directory                           |
-| addAllowDecorator | Add the allow decorator, need class-validator package |
-| tsconfig          | TypeScript configuration                              |
 
+| Field               | Description                                                                      |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `name`              | SDK name; also used as the proto package and gRPC service prefix                 |
+| `packageName`       | npm package name of the generated SDK                                            |
+| `format`            | Format the generated code with Prettier                                          |
+| `build`             | Compile the generated code after generation                                      |
+| `output`            | Output directory for the generated source                                        |
+| `outputBuild`       | Output directory for the compiled build                                          |
+| `removeOutput`      | Clear the output directory before generating                                     |
+| `addAllowDecorator` | Add `@Allow()` to generated models (requires `class-validator`)                  |
+| `tsconfig`          | TypeScript configuration used to build the SDK                                   |
+| `aiSkill`           | Optional. Generates `SKILL.md` and `skill.json` describing the SDK for AI agents |
+
+Then run:
 
-To generate the SDK, run the following command:
 ```shell
 npm run wz-command make-sdk
 ```
 
-#### What this command does
+The generated package contains the proto file, a typed service class per microservice, all models and enums, a dynamic
+module for registration, and a mock module for testing. It is published under the name and version from your
+`package.json`, and its method names, arguments, and response types match your service definitions exactly.
+
+### Generating only the proto file
+
+To generate just the proto file, without building the whole SDK, use the `make:proto` command. It reuses the same
+`sdk-config.json`: `name` is used as the proto package and `output` as the destination directory.
+
+```shell
+npm run wz-command make:proto
+```
+
+Both arguments are optional:
 
-This command will:
+```shell
+npm run wz-command make:proto sdk-config.json ./proto
+```
 
-1. **Collect all request and response types**: It gathers all `@GrpcValue` request and response types from your project.
-2. **Generate proto file**: Automatically generates the necessary proto files based on the collected types.
-3. **Create JavaScript Package**: Packages the generated code into a JavaScript SDK. The SDK will be published using the name and version specified in your package.json, making it available for other services to import and use. The arguments, response structure, and method names remain consistent with the definitions in your gRPC service, ensuring seamless integration and functionality across services.
+| Argument     | Description                                                                                                 |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `configFile` | Config file to read. Defaults to `sdk-config.json`                                                          |
+| `outputPath` | Directory the `microservice.proto` file is written into. Defaults to the `output` field of the config file   |
 
-### SDK usage
+## Using a Generated SDK 📥
 
-After publishing the SDK, other services can easily integrate it. Here’s an example of how to use the generated SDK
+### 1. Register the SDK module
 
-1. **Import the sdk package**
+```typescript
+SdkNameModule.register({
+    url: env.GRPC_URL,
+    timeout: 5000
+});
+```
 
-2. **Register the microservice module**: Configure the microservice in `AppModule` with the appropriate gRPC URL and timeout settings.
+Available options (`MicroserviceModuleOptionType`):
 
-    ```typescript
-    UserModule.register({
-        url: env.GRPC_URL,
-        timeout: 5000
-    });
-    ```
+| Option                    | Description                                                              |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `url`                     | gRPC server address                                                      |
+| `timeout`                 | Request timeout in milliseconds                                          |
+| `ssl`                     | Use SSL credentials                                                      |
+| `maxReceiveMessageLength` | Max incoming message size (default 4MB)                                  |
+| `shouldLoadEmptyArray`    | Deserialize absent repeated fields as `[]`                               |
+| `requestInitializer`      | Callback to enrich the outgoing `Metadata` (auth tokens, request ids, …) |
+| `…`                       | Any other `@grpc/grpc-js` channel option is passed through               |
 
-3. **Use the SDK in another service**: Import the SDK and use it to interact with your gRPC services.
+### 2. Inject the service and call it
 
-    ```typescript
-    export class OtherService {
-        constructor(private userMicroservice: UserMicroservice) {}
+```typescript
+export class OtherService {
+    constructor(private userMicroservice: UserMicroservice) {}
 
-        async doTask(userId: string): Promise<void> {
-            const user = await this.userMicroservice.findUserById({ id: userId });
-            // Process user information as needed
-        }
+    async doTask(userId: string): Promise<void> {
+        const user = await this.userMicroservice.findUserById({ userId });
     }
-    ```
+}
+```
 
-In this example, `OtherService` uses the `UserMicroservice` class from the SDK to call the `findUserById` method.
+Calls are fully typed, request DTOs are serialized through their models, responses are transformed back into model
+instances, and gRPC errors are translated into NestJS `HttpException`s (including timeouts).
 
-### Mock response
+### 3. Mock module for tests
 
-To effectively generate and handle mock data in your application, you can use the `@MockMethod`, `@MockSample`, and `@MockNested` decorators.
+Every SDK ships a mock module that provides the same service classes backed by the mock decorators — no gRPC server
+required:
 
-##### Generate dynamic data with `@MockMethod`
+```typescript
+imports: [MockSdkNameModule];
+```
 
-Use `@MockMethod` to apply Faker methods for generating random values.
+## Documentation UI 🖥️
 
-For example, to create a random string of 10 characters
+The library serves an interactive UI for browsing and testing your gRPC services at
+`http://your-host/microservice-documents`:
 
 ```typescript
-@Property({ type: String, required: false })
-@MockMethod('faker.datatype.string', [10])
-@IsString()
-name: string;
+MicroserviceDocumentModule.register({
+    isEnable: env.NODE_ENV !== 'production',
+    packageName: 'packageName',
+    clientOptions: {
+        customClass: CustomGrpcClient,
+        options: {
+            url: '0.0.0.0:50059',
+            package: 'packageName',
+            protoPath: path.join(__dirname, '../../proto/microservice.proto')
+        }
+    }
+});
 ```
 
-##### Set fixed values with `@MockSample`
+| Option          | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| `isEnable`      | Toggles the module (pass `false` to disable it entirely) |
+| `packageName`   | The proto package name                                   |
+| `clientOptions` | gRPC client options used by the "try it" feature         |
+| `prefix`        | Optional URL prefix for the documentation routes         |
+| `waitingTime`   | Optional delay before the client connects on startup     |
 
-If you need to set a fixed value for a property, use the `@MockSample` decorator. This is useful for enumerations or other predefined values.
+## Custom gRPC Client 🔌
 
-For example, to set a fixed user type
+`CustomGrpcClient` extends NestJS's `ClientGrpcProxy` with per-service client caching and support for every gRPC channel
+option:
 
 ```typescript
-@Property({
-    type: String,
-    enum: UserTypeEnum,
-    enumName: 'UserTypeEnum'
-})
-@MockSample(UserTypeEnum.STANDARD)
-@IsEnum(UserTypeEnum)
-type: UserTypeEnum;
+import { CustomGrpcClient } from '@hodfords/nestjs-grpc-helper';
+
+{
+    customClass: CustomGrpcClient,
+    options: {
+        maxSendMessageLength: 1024 * 1024 * 50,    // 50MB max outgoing message
+        maxReceiveMessageLength: 1024 * 1024 * 50, // 50MB max incoming message
+        keepaliveTimeMs: 120000,                   // Keepalive ping interval
+        keepaliveTimeoutMs: 20000,                 // Keepalive timeout
+        keepalivePermitWithoutCalls: 1             // Allow pings without active calls
+    }
+}
 ```
 
-##### Generate nested data
+Generated SDK modules use it automatically.
 
-Use `@MockNested` to generate mock data for nested objects or arrays of nested objects.
+## Translation Support 🌍
 
-For example, to create an array of 5 nested objects
+Use `GrpcTranslationInterceptor` to extract the caller's language from gRPC metadata and run the handler in that
+language context (via
+[@hodfords/nestjs-cls-translation](https://www.npmjs.com/package/@hodfords/nestjs-cls-translation)):
 
 ```typescript
-@Property({ type: UserResponse, isArray: true })
-@IsArray()
-@ValidateNested()
-@Type(() => UserResponse)
-@MockNested(5)
-users: UserResponse[];
+@UseInterceptors(GrpcTranslationInterceptor)
+@GrpcAction('Get user')
+@ResponseModel(UserResponse)
+getUser(@GrpcValue() dto: GetUserDto): Promise<UserEntity> {
+    return this.userService.getUser(dto.id);
+}
 ```
 
-### Document for GRPC
+## AI Agent Skill 🤝
 
-You can go to `http://xyz/microservice-documents` to check and try to call the gRPC method
+When `aiSkill` is configured in `sdk-config.json`, the generated SDK ships with a `SKILL.md` and `skill.json` that
+describe your services, models, and enums in a format AI agents can consume. Consumers of the SDK can install those
+skills into their project with:
 
-```typescript
-MicroserviceDocumentModule.register({
-    isEnable: true,
-    prefix: <app-prefix>,
-    packageName: camelCase(<package-name>),
-    clientOptions: { ...microserviceGrpcConfig, customClass: CustomGrpcClient, transport: undefined }
-})
+```shell
+npm run wz-command update-ai-skill "@hodfords/*" claude
 ```
 
+The first argument is a package name pattern matched against `node_modules`; the second selects the agent — `claude`
+(installs into `.claude/skills`) or `antigravity` (installs into `.agent/skills`).
+
 ## License 📝
 
 This project is licensed under the MIT License