json-rest-api 1.0.22 → 1.0.24

package/audit/evidence/external/readme-yaser-json-api-nestjs.md

@@ -1,447 +0,0 @@
-<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

@@ -1,84 +0,0 @@
-# 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,