@klerick/json-api-nestjs 10.0.0-beta.1 → 10.0.0-beta.11

package/README.md

@@ -0,0 +1,614 @@
+<p align='center'>
+  <a href="https://www.npmjs.com/package/@klerick/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/v/@klerick/json-api-nestjs.svg" alt="NPM Version" /></a>
+  <a href="https://www.npmjs.com/package/@klerick/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/l/@klerick/json-api-nestjs.svg" alt="Package License" /></a>
+  <a href="https://www.npmjs.com/package/@klerick/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/dm/@klerick/json-api-nestjs.svg" alt="NPM Downloads" /></a>
+  <a href="http://commitizen.github.io/cz-cli/" target="_blank"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen friendly" /></a>
+  <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/klerick/02a4c98cf7008fea2af70dc2d50f4cb7/raw/json-api-nestjs.json" alt="Coverage Badge" />
+</p>
+
+# json-api-nestjs
+
+This plugin works upon **TypeOrm** or **MicroOrm** library, which is used as the main database abstraction layer tool. The module
+automatically generates an API according to JSON API specification from the database structure (**TypeOrm** or **MicroOrm** entities). It
+supports features such as requests validation based on database fields types, request filtering, endpoints extending,
+data relations control and much more. Our module significantly reduces the development time of REST services by removing
+the need to negotiate the mechanism of client-server interaction and implementing automatic API generation without the
+need to write any code.
+
+## Installation
+
+```bash  
+$ npm install @klerick/json-api-nestjs
+```  
+
+## Example
+
+Once the installation process is complete, we can import the **JsonApiModule** into the root **AppModule**.
+### TypeOrm
+```typescript
+import {Module} from '@nestjs/common';
+import {JsonApiModule} from '@klerick/json-api-nestjs';
+import {TypeOrmJsonApiModule} from '@klerick/json-api-nestjs-typeorm';
+import {Users} from 'type-orm/database';
+
+@Module({
+  imports: [
+    JsonApiModule.forRoot(TypeOrmJsonApiModule, {
+      entities: [Users]
+    }),
+  ],
+})
+export class AppModule {
+}
+```
+
+### MicroOrm
+```typescript
+import {Module} from '@nestjs/common';
+import {JsonApiModule} from '@klerick/json-api-nestjs';
+import {MicroOrmJsonApiModule} from '@klerick/json-api-nestjs-microorm';
+import {Users} from 'micro-orm/database';
+
+@Module({
+  imports: [
+    JsonApiModule.forRoot(MicroOrmJsonApiModule, {
+      entities: [Users]
+    }),
+  ],
+})
+export class AppModule {
+}
+```
+
+After this, you have to prepare CRUDs with ready-to-use endpoints:
+
+- GET /users
+- POST /users
+- GET /users/:id
+- PATCH /users/:id
+- DELETE /users/:id
+- GET /users/{id}/relationships/{relName}
+- POST /users/{id}/relationships/{relName}
+- PATCH /users/{id}/relationships/{relName}
+- DELETE /users/{id}/relationships/{relName}
+
+## Configuration params
+
+The following interface is using for the configuration:
+
+```typescript
+export interface ModuleOptions {
+  entities: Entity[]; // List of typeOrm Entity
+  excludeControllers?: Entity[]; // List of entities to exclude from automatic controller generation
+  controllers?: NestController[];  // List of controller, if you need extend default present
+  connectionName?: string; // Type orm connection name: "default" is default name
+  providers?: NestProvider[]; // List of addition provider for useing in custom controller
+  imports?: NestImport[]; // List of addition module for useing in custom controller
+  options?: {
+    requiredSelectField?: boolean; // Need list of select field in get endpoint, try is default
+    debug?: boolean; // Debug info in result object, like error message
+    pipeForId?: Type<PipeTransform> // Nestjs pipe for validate id params, by default ParseIntPipe
+    operationUrl?: string // Url for atomic operation https://jsonapi.org/ext/atomic/
+    // You can add params for MicroOrm or TypeOrm adapter
+  } ;
+}
+```
+
+### Excluding Controllers
+
+If you need to register entities for relationships but don't want automatic controller generation for some of them, use `excludeControllers`:
+
+```typescript
+import {Module} from '@nestjs/common';
+import {JsonApiModule} from '@klerick/json-api-nestjs';
+import {TypeOrmJsonApiModule} from '@klerick/json-api-nestjs-typeorm';
+import {Users, Roles, AuditLog} from 'database';
+
+@Module({
+  imports: [
+    JsonApiModule.forRoot(TypeOrmJsonApiModule, {
+      entities: [Users, Roles, AuditLog],
+      excludeControllers: [AuditLog], // AuditLog entity will not have auto-generated controller
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+This is useful when:
+- You want to manage certain entities only through relationships
+- You need custom controller implementation without the auto-generated one
+- Some entities should be internal and not exposed via REST API
+
+You can extend the default controller:
+
+```typescript
+import {Get, Param, Inject, BadRequestException} from '@nestjs/common';
+
+import {Users} from 'database';
+import {
+  JsonApi,
+  excludeMethod,
+  JsonBaseController,
+  InjectService,
+  JsonApiService,
+  Query,
+} from '@klerick/json-api-nestjs';
+import {
+  ResourceObjectRelationships,
+} from '@klerick/json-api-nestjs-shared';
+import {ExampleService} from '../../service/example/example.service';
+
+@JsonApi(Users, {
+  allowMethod: excludeMethod(['deleteRelationship']),
+  requiredSelectField: true,
+  overrideRoute: 'user',
+})
+export class ExtendUserController extends JsonBaseController<Users, 'id'> {
+  @InjectService() public service: JsonApiService<Users>;
+  @Inject(ExampleService) protected exampleService: ExampleService;
+
+  public override getAll(query: Query<Users, 'id'>): Promise<ResourceObject<Users, 'array'>> {
+    if (!this.exampleService.someCheck(query)) {
+      throw new BadRequestException({});
+    }
+    return this.service.getAll(query);// OR call parent method: super.getAll(query);
+  }
+
+  public override patchRelationship<Rel extends EntityRelation<Users>>(
+    id: string | number,
+    relName: Rel,
+    input: PatchRelationshipData
+  ): Promise<ResourceObjectRelationships<Users, 'id', Rel>> {
+    return super.patchRelationship(id, relName, input);
+  }
+
+  @Get(':id/example')
+  testOne(@Param('id') id: string): string {
+    return this.exampleService.testMethode(id);
+  }
+}
+```
+
+You can overwrite the default config for the current controller using options in the decorator **JsonAPi**.
+Also you can specify an API method necessary for you, using **allowMethod**
+Defulat validation check only simple type and database structure.
+If you need custom pipe validation you can your owner pipe like this:
+
+```typescript
+
+import { Query } from '@nestjs/common';
+import {
+  JsonApi,
+  excludeMethod,
+  JsonBaseController,
+  InjectService,
+  JsonApiService,
+  Query as QueryType,
+} from 'json-api-nestjs';
+
+@JsonApi(Users, {
+  allowMethod: excludeMethod(['deleteRelationship']),
+  requiredSelectField: true,
+  overrideRoute: 'user',
+})
+export class ExtendUserController extends JsonBaseController<Users, 'id'> {
+  @InjectService() public service: JsonApiService<Users>;
+  @Inject(ExampleService) protected exampleService: ExampleService;
+
+  public override getAll(
+    @Query(ExamplePipe) query: QueryType<Users, 'id'>
+  ): Promise<ResourceObject<Users, 'array'>> {
+    return super.getAll(query);
+  }
+}
+```
+
+```typescript
+import { ArgumentMetadata, PipeTransform } from '@nestjs/common';
+
+import { Query } from 'json-api-nestjs';
+import { Users } from 'database';
+
+export class ExamplePipe implements PipeTransform<Query<Users, 'id'>, Query<Users, 'id'>> {
+  transform(value: Query<Users, 'id'>, metadata: ArgumentMetadata): Query<Users, 'id'> {
+    return value;
+  }
+}
+```
+
+## Swagger UI
+
+For using swagger, you should only add [@nestjs/swagger](https://docs.nestjs.com/openapi/introduction) and configure it
+```typescript
+const app = await NestFactory.create(AppModule);
+
+const config = new DocumentBuilder()
+  .setOpenAPIVersion('3.1.0')
+  .setTitle('JSON API swagger example')
+  .setDescription('The JSON API list example')
+  .setVersion('1.0')
+  .build();
+
+SwaggerModule.setup(
+  'swagger',
+  app,
+  () => SwaggerModule.createDocument(app, config), // !!!Important: document as factory
+  {}
+);
+
+```
+
+## Available endpoint method
+
+Using **Users** entity and relation **Roles** entity as example
+
+### List item of Users
+
+  ```
+  GET /users
+  ```
+
+Available query params:
+
+- **include** - you can extend result with relations (aka join)
+   ```
+   GET /users?include=roles
+   ```
+  result of request will have role relation for each **Users** item
+
+- **fields** - you can specify required fields of result query
+
+  ```
+   GET /users?fields[target]=login,lastName&fileds[roles]=name,key
+   ```
+  The "target" is **Users** entity
+  The "roles" is **Roles** entity
+  So, result of request will be have only fields  *login* and *lastName* for **Users** entity and fields *name* and *
+  key* for **Roles** entity
+- **sort** - you can sort result of the request
+
+  ```
+   GET /users?sort=target.name,-roles.key
+   ```
+  The "target" is **Users** entity
+  The "roles" is **Roles** entity
+  So, result of the request will be sorted by field *name* of **Users** by *ASC* and field *key* of **Roles** entity
+  by **DESC**.
+- **page** - pagination for you request
+
+  ```
+  GET /users?page[number]=1page[size]=20
+  ```
+- **filter** - filter for query
+
+  ```
+  GET /users?filter[name][eq]=1&filter[roles.name][ne]=test&filter[roles.status][eq]=true
+  ```
+  The "name" is a field of **Users** entity
+  The "roles.name" is *name* field of **Roles** entity
+  The "eq", "ne" is *[Filter operand](#filter-operand)*
+
+  So, this query will be transformed like sql:
+  ```sql
+   WHERE users.name = 1 AND roles.name <> 'test' AND roles.status = true
+  ```
+
+## Filter operand
+
+```typescript
+type FilterOperand
+{
+  in:string[] // is equal to the conditional of query "WHERE 'attribute_name' IN ('value1', 'value2')"
+  nin: string[] // is equal to the conditional of query "WHERE 'attribute_name' NOT IN ('value1', 'value1')"
+  eq: string // is equal to the conditional of query "WHERE 'attribute_name' = 'value1'
+  ne: string // is equal to the conditional of query "WHERE 'attribute_name' <> 'value1'
+  gte: string // is equal to the conditional of query "WHERE 'attribute_name' >= 'value1'
+  gt: string // is equal to the conditional of query "WHERE 'attribute_name' > 'value1'
+  lt: string // is equal to the conditional of query "WHERE 'attribute_name' < 'value1'
+  lte:string // is equal to the conditional of query "WHERE 'attribute_name' <= 'value1'
+  regexp: string // is equal to the conditional of query "WHERE 'attribute_name' ~* value1
+  some: string // is equal to the conditional of query "WHERE 'attribute_name' && [value1]
+}
+```
+
+### Get item of Users
+
+  ```
+  GET /users/:id
+  ```
+- **include** - you can extend result with relations (aka join)
+   ```
+   GET /users?include=roles
+   ```
+  result of request will have role relation for each **Users** item
+
+- **fields** - you can specify required fields of result query
+
+  ```
+   GET /users?fields[target]=login,lastName&fileds[roles]=name,key
+   ```
+  The "target" is **Users** entity
+  The "roles" is **Roles** entity
+  So, result of request will be have only fields  *login* and *lastName* for **Users** entity and fields *name* and *
+  key* for **Roles** entity
+
+### Create item of Users
+  ```
+  POST /users
+  ```
+
+- **body** - Create new User and add link to address
+
+```json
+{
+  "data": {
+    "type": "users",
+    "attributes": {
+      "id": 0,
+      "login": "string",
+      "firstName": "string",
+      "lastName": "string",
+      "isActive": true,
+      "createdAt": "2023-12-08T10:32:27.352Z",
+      "updatedAt": "2023-12-08T10:32:27.352Z"
+    },
+    "relationships": {
+      "addresses": {
+        "id": "1",
+        "type": "addresses"
+      }
+    }
+  }
+}
+```
+### Update item of Users
+  ```
+  PATCH /users/:id
+  ```
+
+- **body** - Update User with id 1 and update link to address and manager
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "id": 0,
+      "login": "string",
+      "firstName": "string",
+      "lastName": "string",
+      "isActive": true,
+      "createdAt": "2023-12-08T10:34:57.752Z",
+      "updatedAt": "2023-12-08T10:34:57.752Z"
+    },
+    "relationships": {
+      "addresses": {
+        "id": "2",
+        "type": "addresses"
+      },
+      "manager": {
+        "id": "2",
+        "type": "users"
+      }
+    }
+  }
+}
+
+```
+
+### Atomic operation
+You can more information find [here](https://jsonapi.org/ext/atomic/)
+But you have additinal feature.
+For example: you will need create new **Roles**, then - create new **Users** and assign new **Roles** to new **Users**.
+If use native json api you need send 3 http request:
+- POST /roles
+- POST /users
+
+but [Atomic operation](https://jsonapi.org/ext/atomic/) allow for one request.
+```json
+
+{
+   "atomic:operations":[
+      {
+         "op":"add",
+         "ref":{
+            "type":"roles",
+            "tmpId":10000
+         },
+         "data":{
+            "type":"roles",
+            "attributes":{
+               "name":"testRolesAgain",
+               "key":"testRolesAgain"
+            }
+         }
+      },
+      {
+         "op":"add",
+         "ref":{
+            "type":"users"
+         },
+         "data":{
+            "type":"users",
+            "attributes":{
+               "login":"newLogin"
+            },
+            "relationships":{
+               "addresses":{
+                  "type":"addresses",
+                  "id":"1"
+               },
+               "roles":[
+                  {
+                     "type":"roles",
+                     "id":"10000"
+                  }
+               ]
+            }
+         }
+      }
+   ]
+}
+
+```
+**tmpId** - is params for operation **add**, should be unique for all operations.
+
+If you have Interceptor you can check call it from **AtomicOperation**
+
+
+
+```ts
+@Injectable()
+export class AtomicInterceptor<T> implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler<T>): Observable<T> {
+    const isAtomic = context.getArgByIndex(3)
+    if (isAtomic) {
+      console.log('call from atomic operation')
+    }
+    return next.handle();
+  }
+}
+```
+**isAtomic** - is array of params of method
+
+## Resource Linkage for To-One Relations
+
+According to the [JSON:API specification](https://jsonapi.org/format/#document-resource-object-linkage), relationships should include a `data` member containing resource linkage (the `id` and `type` of the related resource).
+
+For **to-one relations** (ManyToOne, OneToOne), if your entity has an FK field (foreign key), the library will automatically include `relationships.{relation}.data` in responses **even without using `include`**.
+
+**Example response:**
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "comments",
+    "attributes": { "text": "Hello" },
+    "relationships": {
+      "user": {
+        "links": { "self": "/api/comments/1/relationships/user" },
+        "data": { "id": "5", "type": "users" }
+      }
+    }
+  }
+}
+```
+
+If the FK field is `null`, then `data` will also be `null`:
+```json
+"relationships": {
+  "user": {
+    "links": { "self": "/api/comments/1/relationships/user" },
+    "data": null
+  }
+}
+```
+
+**Note:** TypeORM and MikroORM implement FK field detection differently. See the respective adapter documentation for details on how to define FK fields in your entities.
+
+## Field Access Control Decorators
+
+The library provides two decorators to control field accessibility in POST and PATCH operations:
+
+### @JsonApiReadOnly()
+
+Fields marked with `@JsonApiReadOnly()` are completely excluded from input validation schemas. They cannot be set via POST or PATCH requests and are not shown in Swagger documentation for input.
+
+**Use case:** Server-managed fields like `createdAt`, `updatedAt`, computed fields.
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
+import { JsonApiReadOnly } from '@klerick/json-api-nestjs';
+
+@Entity()
+export class Users {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  login: string;
+
+  @JsonApiReadOnly()
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @JsonApiReadOnly()
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+```
+
+With this configuration:
+- **POST /users** - `createdAt` and `updatedAt` fields are not accepted
+- **PATCH /users/:id** - `createdAt` and `updatedAt` fields are not accepted
+
+### @JsonApiImmutable()
+
+Fields marked with `@JsonApiImmutable()` can be optionally set during creation (POST) but cannot be modified after (PATCH).
+
+**Use case:** Fields that should be set once and never changed, like `externalId`, `slug`, or `username`.
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
+import { JsonApiImmutable } from '@klerick/json-api-nestjs';
+
+@Entity()
+export class Users {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @JsonApiImmutable()
+  @Column({ unique: true })
+  login: string;
+
+  @Column()
+  firstName: string;
+
+  @Column()
+  lastName: string;
+}
+```
+
+With this configuration:
+- **POST /users** - `login` is optional, can be provided or omitted
+- **PATCH /users/:id** - `login` is not accepted (cannot be changed)
+
+### Combining Decorators
+
+You can use both decorators in the same entity:
+
+```typescript
+@Entity()
+export class Article {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @JsonApiImmutable()
+  @Column({ unique: true })
+  slug: string;
+
+  @Column()
+  title: string;
+
+  @Column()
+  content: string;
+
+  @JsonApiReadOnly()
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @JsonApiReadOnly()
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+```
+
+| Field | POST | PATCH |
+|-------|------|-------|
+| `slug` | Optional | Not accepted |
+| `title` | Required | Optional |
+| `content` | Required | Optional |
+| `createdAt` | Not accepted | Not accepted |
+| `updatedAt` | Not accepted | Not accepted |

package/package.json

@@ -1,21 +1,6 @@
 {
   "name": "@klerick/json-api-nestjs",
-  "version": "10.0.0-beta.1",
-  "license": "MIT",
-  "private": false,
-  "contributors": [
-    {
-      "email": "klerick666@gmain.com",
-      "name": "Aleksandr Kharkovey"
-    }
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/klerick/nestjs-json-api.git"
-  },
-  "engines": {
-    "node": ">= 20.0.0"
-  },
+  "version": "10.0.0-beta.11",
   "type": "commonjs",
   "description": "JsonApi Plugin for NestJs",
   "keywords": [
@@ -27,32 +12,51 @@
     "microorm",
     "CRUD"
   ],
-  "dependencies": {
-    "@anatine/zod-openapi": "^2.2.3",
-    "@nestjs/common": "^11.0.10",
-    "@nestjs/core": "^11.0.10",
-    "@nestjs/swagger": "^11.0.4",
-    "change-case-commonjs": "^5.4.4",
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.0",
+    "@nestjs/core": "^11.1.0",
+    "@nestjs/swagger": "^11.2.0",
     "reflect-metadata": "^0.1.12 || ^0.2.0",
     "rxjs": "^7.1.0",
-    "ts-toolbelt": "^9.6.0",
-    "tslib": ">2.3.0",
-    "zod": "^3.24.1",
-    "zod-validation-error": "^3.4.0"
+    "tslib": ">2.3.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "@klerick/json-api-nestjs-shared": "^1.0.0-beta.4",
+    "zod": "^4.1.0",
+    "zod-validation-error": "^4.0.0"
   },
-  "peerDependencies": {
-    "@klerick/json-api-nestjs-shared": "1.0.0-beta.1"
+  "overrides": {
+    "mikro-orm-pglite": {
+      "@mikro-orm/postgresql": "^6.4.0"
+    }
   },
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "types": "./../../../dist/libs/json-api/json-api-nestjs-shared/libs/json-api/json-api-nestjs/src/index.d.ts",
-      "default": "./../../../dist/libs/json-api/json-api-nestjs-shared/libs/json-api/json-api-nestjs/src/index.js"
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
     }
   },
-  "types": "./../../../dist/libs/json-api/json-api-nestjs-shared/libs/json-api/json-api-nestjs/src/index.d.ts",
-  "main": "./../../../dist/libs/json-api/json-api-nestjs-shared/libs/json-api/json-api-nestjs/src/index.js"
+  "types": "./src/index.d.ts",
+  "main": "./src/index.js",
+  "license": "MIT",
+  "contributors": [
+    {
+      "email": "klerick666@gmain.com",
+      "name": "Aleksandr Kharkovey"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klerick/nestjs-json-api.git"
+  },
+  "engines": {
+    "node": ">= 20.0.0"
+  },
+  "files": [
+    "**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }