json-rest-api 1.0.21 → 1.0.22

package/audit/evidence/external/readme-yaser-json-api-nestjs.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 @yaser2us/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 '@yaser2us/json-api-nestjs';
+import {TypeOrmJsonApiModule} from '@yaser2us/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 '@yaser2us/json-api-nestjs';
+import {MicroOrmJsonApiModule} from '@yaser2us/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 '@yaser2us/json-api-nestjs';
+import {
+  ResourceObjectRelationships,
+} from '@yaser2us/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/audit/evidence/external/standard-jsonapi-snippets.txt

@@ -0,0 +1,84 @@
+# JSON:API spec key clauses (captured)
+captured_at=2026-03-01T16:01:55Z
+source=https://jsonapi.org/format/
+
+177:( application/vnd.api+json )
+193: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
+194:“SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this
+204: application/vnd.api+json . 
+236: The JSON:API media type MUST NOT be specified with any media type parameters
+242:profile’s URI SHOULD return documentation that describes its usage. The
+243:values of the ext and profile parameters MUST equal a space-separated
+257: An extension MUST NOT lessen or remove any processing rules, restrictions or
+268:extension MUST define a namespace to guarantee that extensions will never
+270: MUST meet all of the following conditions: 
+273: A namespace MUST contain at least one character. 
+274: A namespace MUST contain only these characters:
+283: An extension MUST NOT define more than one namespace. The namespace used for
+284:all query parameters and document members MUST be the same for any given
+292: Content-Type: application/vnd.api+json;ext= "https://jsonapi.org/ext/version" 
+314: A profile MUST NOT define any query parameters except implementation-specific query parameters . 
+316: A profile MUST NOT alter or remove processing rules that have been defined
+322:parameter , but it could not specify that relationship
+323:names in the include query parameter are
+340: Content-Type: application/vnd.api+json;profile= "https://example.com/resource-timestamps" 
+361: Clients and servers MUST send all JSON:API payloads using the JSON:API media
+364: Clients and servers MUST specify the ext media type parameter in the
+368: Clients and servers MUST specify the profile media type parameters in the
+374: When processing a JSON:API response document, clients MUST ignore any
+399:servers MUST respond with a 415 Unsupported Media Type status code if
+405:parameter contains an unsupported extension URI, the server MUST respond
+415:servers MUST ignore instances of that media type which are modified by a
+418:servers MUST respond with a 406 Not Acceptable status code. If every
+420:at least one unsupported extension URI, the server MUST also respond with a
+423: If the profile parameter is received, a server SHOULD attempt to apply any
+424:requested profile(s) to its response. A server MUST ignore any profiles
+433: Servers that support the ext or profile media type parameters SHOULD 
+453:members MUST comply with the naming requirements specified
+457:extensions MUST NOT contain any additional members. Client and server
+458:implementations MUST ignore non-compliant members. 
+467: A JSON object MUST be at the root of every JSON:API request and response
+470: A document MUST contain at least one of the following top-level members: 
+474: errors : an array of error objects . 
+480: The members data and errors MUST NOT coexist in the same document. 
+487: included : an array of resource objects that are related to the primary
+488:data and/or each other (“included resources”). 
+491: If a document does not contain a top-level data key, the included member
+492: MUST NOT be present either. 
+498:document has extensions or profiles applied to it, this link SHOULD be
+502:resource relationship. 
+513:by the client to generate the response document. This includes but is not
+515: sparse fieldsets , sorting ,
+522: Primary data MUST be either: 
+541: "relationships" : { 
+542: // ... this article's relationships 
+559: A logical collection of resources MUST be represented as an array, even if
+566: A resource object MUST contain at least the following top-level members: 
+575:case, a client MAY include a lid member to uniquely identify the resource
+582: relationships : a relationships object describing relationships between
+586:resource that can not be represented as an attribute or relationship. 
+598: "relationships" : { 
+601: "self" : "/articles/1/relationships/author" , 
+613: As noted above, every resource object MUST contain a
+614: type member. Every resource object MUST also contain an id member,
+617:a lid member MAY be included to uniquely identify the resource by type 
+618: locally within the document. The value of the lid member MUST be
+622: The values of the id , type , and lid members MUST be strings. 
+624: Within a given API, each resource object’s type and id pair MUST 
+629:attributes and relationships. 
+631: The values of type members MUST adhere to the same constraints as
+642: A resource object’s attributes and its relationships are collectively called
+645: Fields for a resource object MUST share a common namespace with each
+647:attribute and relationship with the same name, nor can it have an attribute
+648:or relationship named type or id . 
+652: The value of the attributes key MUST be an object (an “attributes
+659: Keys that reference related resources (e.g. author_id ) SHOULD NOT appear
+660:as attributes. Instead, relationships SHOULD be used. 
+668: The value of the relationships key MUST be an object (a “relationships
+669:object”). Each member of a relationships object represents
+670:a “relationship” from the resource object 
+675: A relationship’s name is given by its key. The value at that key MUST be an
+676:object (“relationship object”). 
+679:A “relationship object” MUST contain at least one of the following: 
+684: self : a link for the relationship itself (a “relationship link”). This
+685:link allows the client to directly manipulate the relationship. For example,