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

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+## 10.0.0-beta.4 (2025-05-23)
+
+### 🚀 Features
+
+- **json-api-nestjs:** Update package.json dep ([87519a0](https://github.com/klerick/nestjs-json-api/commit/87519a0))
+
+### ❤️ Thank You
+
+- Alex H
+
+## 10.0.0-beta.3 (2025-05-23)
+
+### 🚀 Features
+
+- **json-api-nestjs,json-api-nestjs-microorm,json-api-nestjs-sdk,json-api-nestjs-shared,json-api-nestjs-typeorm:** up nestjs ([42b6b82](https://github.com/klerick/nestjs-json-api/commit/42b6b82))
+
+### ❤️ Thank You
+
+- Alex H
+
+## 10.0.0-beta.0 (2025-05-21)
+
+### 🚀 Features
+
+- ⚠️  **json-api-nestjs:** remove module and refactoring ([f202ebc](https://github.com/klerick/nestjs-json-api/commit/f202ebc))
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Some fix for swagger ([9a0f190](https://github.com/klerick/nestjs-json-api/commit/9a0f190))
+- **json-api-nestjs:** Use correct options for check is debug or not ([e52cc92](https://github.com/klerick/nestjs-json-api/commit/e52cc92))
+- **json-api-nestjs:** fix type in some place ([61f45e6](https://github.com/klerick/nestjs-json-api/commit/61f45e6))
+
+### ⚠️  Breaking Changes
+
+- **json-api-nestjs:** Change type signature, rename npm package
+
+### ❤️ Thank You
+
+- Alex H
+
+# 9.0.0 (2025-02-12)
+
+### 🚀 Features
+
+- **json-api-nestjs:** Microro orm ([4696f51](https://github.com/klerick/nestjs-json-api/commit/4696f51))
+- **json-api-nestjs:** Microro orm ([18f4a0c](https://github.com/klerick/nestjs-json-api/commit/18f4a0c))
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Fix circular type for query obkect ([e492cd1](https://github.com/klerick/nestjs-json-api/commit/e492cd1))
+
+### ❤️ Thank You
+
+- Alex H
+
+# 8.0.0 (2024-12-18)
+
+### 🚀 Features
+
+- **json-api-nestjs:** Return meta info in atomic operation ([1b61fb3](https://github.com/klerick/nestjs-json-api/commit/1b61fb3))
+- **json-api-nestjs:** Allow set id from request for postOne ([6202c22](https://github.com/klerick/nestjs-json-api/commit/6202c22))
+- **json-api-nestjs:** Extend validate for array, json and datetime, use nullable if possible ([a8c6f83](https://github.com/klerick/nestjs-json-api/commit/a8c6f83))
+- **json-api-nestjs:** Allow call interceptor for each operation in atomic endpoint ([9e0f066](https://github.com/klerick/nestjs-json-api/commit/9e0f066))
+- **json-api-nestjs:** Add wrapper transaction options ([8e498a8](https://github.com/klerick/nestjs-json-api/commit/8e498a8))
+- **nestjs-json-rpc:** Add support soft delete ([c3b9322](https://github.com/klerick/nestjs-json-api/commit/c3b9322))
+
+### ❤️ Thank You
+
+- Alex H
+
+## 7.0.4 (2024-10-27)
+
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Add filter by null ([3af99ff](https://github.com/klerick/nestjs-json-api/commit/3af99ff))
+
+
+### ❤️  Thank You
+
+- Alex H
+
+## 7.0.3 (2024-05-15)
+
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Resource Relationship not allowing data key. ([f648422](https://github.com/klerick/nestjs-json-api/commit/f648422))
+
+
+### ❤️  Thank You
+
+- Alex H
+
+## 7.0.2 (2024-04-21)
+
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Fix validation ([e5e9936](https://github.com/klerick/nestjs-json-api/commit/e5e9936))
+
+- **json-api-nestjs:** Fix validate for patch method ([40b0303](https://github.com/klerick/nestjs-json-api/commit/40b0303))
+
+- **json-api-nestjs:** Fix validate for patch method ([2caa2d8](https://github.com/klerick/nestjs-json-api/commit/2caa2d8))
+
+
+### ❤️  Thank You
+
+- Alex H
+
+## 7.0.1 (2024-04-06)
+
+
+### 🩹 Fixes
+
+- **json-api-nestjs:** Fix validation ([1d048a8](https://github.com/klerick/nestjs-json-api/commit/1d048a8))
+
+
+### ❤️  Thank You
+
+- Alex H
+
+# 7.0.0 (2024-03-08)
+
+
+### 🚀 Features
+
+- ⚠️  **json-api-nestjs:** new version json-api ([66076a3](https://github.com/klerick/nestjs-json-api/commit/66076a3))
+
+
+#### ⚠️  Breaking Changes
+
+- **json-api-nestjs:** - remove ajv and use zod for validation
+
+### ❤️  Thank You
+
+- Alex H

package/README.md

@@ -0,0 +1,447 @@
+<p align='center'>
+  <a href="https://www.npmjs.com/package/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/v/json-api-nestjs.svg" alt="NPM Version" /></a>
+  <a href="https://www.npmjs.com/package/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/l/json-api-nestjs.svg" alt="Package License" /></a>
+  <a href="https://www.npmjs.com/package/json-api-nestjs" target="_blank"><img src="https://img.shields.io/npm/dm/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
+  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  
+  } ;
+}
+```
+
+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

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.4",
   "type": "commonjs",
   "description": "JsonApi Plugin for NestJs",
   "keywords": [
@@ -29,9 +14,10 @@
   ],
   "dependencies": {
     "@anatine/zod-openapi": "^2.2.3",
-    "@nestjs/common": "^11.0.10",
-    "@nestjs/core": "^11.0.10",
-    "@nestjs/swagger": "^11.0.4",
+    "@klerick/json-api-nestjs-shared": "1.0.0-beta.3",
+    "@nestjs/common": "^11.1.0",
+    "@nestjs/core": "^11.1.0",
+    "@nestjs/swagger": "^11.2.0",
     "change-case-commonjs": "^5.4.4",
     "reflect-metadata": "^0.1.12 || ^0.2.0",
     "rxjs": "^7.1.0",
@@ -40,19 +26,33 @@
     "zod": "^3.24.1",
     "zod-validation-error": "^3.4.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@klerick/json-api-nestjs-shared": "1.0.0-beta.1"
-  },
   "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"
+  }
 }