@smartsoft001/crud-shell-nestjs 1.1.90 → 1.2.0

package/.eslintrc

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../../.eslintrc",
+  "rules": {
+    "import/order": "off"
+  },
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser"
+    }
+  ]
+}

package/README.md

@@ -1,7 +1,40 @@
-# crud-shell-nestjs
+# 📦 @smartsoft001/crud-shell-nestjs
 
-This library was generated with [Nx](https://nx.dev).
+![npm](https://img.shields.io/npm/v/@smartsoft001/crud-shell-nestjs) ![downloads](https://img.shields.io/npm/dm/@smartsoft001/crud-shell-nestjs)
 
-## Running unit tests
+## 🚀 Usage
 
-Run `ng test crud-shell-nestjs` to execute the unit tests via [Jest](https://jestjs.io).
+`npm i @smartsoft001/crud-shell-nestjs`
+
+## 🛠️ Modules
+
+### CrudShellNestjsModule
+- Provides the main integration module for CRUD features in a NestJS app.
+- Static method: `forRoot(options)` — Registers controllers, providers, and imports required modules with the given configuration.
+
+### CrudShellNestjsCoreModule
+- Provides a core integration module for CRUD features in a NestJS app.
+- Static method: `forRoot(options)` — Registers providers and imports required modules with the given configuration.
+
+## 🛠️ Controllers & Methods
+
+### CrudController
+<table>
+    <tr><td>POST /</td><td>create — Creates a new entity. Returns the new entity's ID.</td></tr>
+    <tr><td>POST /bulk</td><td>createMany — Creates multiple entities in bulk.</td></tr>
+    <tr><td>GET /:id</td><td>readById — Retrieves an entity by its ID.</td></tr>
+    <tr><td>GET /</td><td>read — Retrieves a list of entities with filtering, CSV, and XLSX export support.</td></tr>
+    <tr><td>PUT /:id</td><td>update — Updates an entity by its ID.</td></tr>
+    <tr><td>PATCH /:id</td><td>updatePartial — Partially updates an entity by its ID.</td></tr>
+    <tr><td>DELETE /:id</td><td>delete — Deletes an entity by its ID.</td></tr>
+    <tr><td>POST /attachments</td><td>uploadAttachment — Uploads an attachment for an entity.</td></tr>
+    <tr><td>GET /attachments/:id</td><td>downloadAttachment — Downloads an attachment by its ID.</td></tr>
+    <tr><td>DELETE /attachments/:id</td><td>deleteAttachment — Deletes an attachment by its ID.</td></tr>
+</table>
+
+## 🛠️ Gateways & Methods
+
+### CrudGateway
+<table>
+    <tr><td>changes (WebSocket)</td><td>handleFilter — Subscribes to changes for entities and streams updates to the client.</td></tr>
+</table>

package/jest.config.ts

@@ -0,0 +1,27 @@
+/* eslint-disable */
+export default {
+  globals: {},
+  transform: {
+    '^.+\\.[tj]sx?$': [
+      'ts-jest',
+      {
+        tsConfig: '<rootDir>/tsconfig.spec.json',
+      },
+    ],
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+  coverageDirectory: '../../../../coverage/packages/crud/shell/nestjs',
+  displayName: 'crud-shell-nestjs',
+  testEnvironment: 'node',
+  preset: '../../../../jest.preset.js',
+  /* TODO: Update to latest Jest snapshotFormat
+   * By default Nx has kept the older style of Jest Snapshot formats
+   * to prevent breaking of any existing tests with snapshots.
+   * It's recommend you update to the latest format.
+   * You can do this by removing snapshotFormat property
+   * and running tests with --update-snapshot flag.
+   * Example: From within the project directory, run "nx test --update-snapshot"
+   * More info: https://jestjs.io/docs/upgrading-to-jest29#snapshot-format
+   */
+  snapshotFormat: { escapeString: true, printBasicPrototype: true },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001/crud-shell-nestjs",
-  "version": "1.1.90",
+  "version": "1.2.0",
   "description": "Utils to crud",
   "repository": {
     "type": "git",
@@ -16,48 +16,5 @@
   "bugs": {
     "url": "https://github.com/emiljuchnikowski/smartsoft/issues"
   },
-  "homepage": "https://github.com/emiljuchnikowski/smartsoft#readme",
-  "dependencies": {
-    "@angular/common": "16.1.3",
-    "@angular/core": "16.1.3",
-    "@angular/platform-browser-dynamic": "16.1.3",
-    "@nestjs/axios": "3.0.0",
-    "@nestjs/common": "^10.0.5",
-    "@nestjs/jwt": "^10.1.0",
-    "@nestjs/passport": "^10.0.0",
-    "@nestjs/terminus": "^10.0.1",
-    "@nestjs/typeorm": "^10.0.0",
-    "@nestjs/websockets": "^10.0.5",
-    "busboy": "^0.3.1",
-    "combined-stream": "^1.0.8",
-    "express": "4.18.2",
-    "flatted": "^3.2.4",
-    "guid-typescript": "1.0.9",
-    "json2csv": "^5.0.5",
-    "lodash": "^4.17.20",
-    "lodash-decorators": "^6.0.1",
-    "md5": "2.3.0",
-    "moment-timezone": "^0.5.43",
-    "mongodb": "5.6.0",
-    "passport-jwt": "4.0.0",
-    "reflect-metadata": "0.1.13",
-    "rxjs": "7.8.1",
-    "socket.io": "4.7.1",
-    "xlsx": "^0.17.0"
-  },
-  "peerDependencies": {
-    "@smartsoft001/crud-domain": "1.1.90",
-    "@smartsoft001/crud-shell-app-services": "1.1.90",
-    "@smartsoft001/crud-shell-dtos": "1.1.90",
-    "@smartsoft001/domain-core": "1.1.90",
-    "@smartsoft001/models": "1.1.90",
-    "@smartsoft001/mongo": "1.1.90",
-    "@smartsoft001/nestjs": "1.1.90",
-    "@smartsoft001/users": "1.1.90",
-    "@smartsoft001/utils": "1.1.90",
-    "util": "0.12.5",
-    "tslib": "2.5.3"
-  },
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts"
+  "homepage": "https://github.com/emiljuchnikowski/smartsoft#readme"
 }

package/project.json

@@ -0,0 +1,43 @@
+{
+  "name": "crud-shell-nestjs",
+  "$schema": "../../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/crud/shell/nestjs/src",
+  "projectType": "library",
+  "generators": {},
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": [
+          "packages/crud/shell/nestjs/**/*.{ts,tsx,js,jsx}",
+          "packages/crud/shell/nestjs/package.json"
+        ],
+        "tsConfig": [
+          "packages/crud/shell/nestjs/tsconfig.lib.json",
+          "packages/crud/shell/nestjs/tsconfig.spec.json"
+        ]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "packages/crud/shell/nestjs/jest.config.ts",
+        "passWithNoTests": true
+      },
+      "outputs": ["{workspaceRoot}/coverage/packages/crud/shell/nestjs"]
+    },
+    "build": {
+      "executor": "@nx/esbuild:esbuild",
+      "options": {
+        "outputPath": "dist/packages/crud/shell/nestjs",
+        "tsConfig": "packages/crud/shell/nestjs/tsconfig.lib.json",
+        "packageJson": "packages/crud/shell/nestjs/package.json",
+        "main": "packages/crud/shell/nestjs/src/index.ts",
+        "assets": ["packages/crud/shell/nestjs/*.md"]
+      },
+      "outputs": ["{options.outputPath}"]
+    }
+  },
+  "tags": ["scope:crud", "type:shell"]
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/nestjs.module';
+export * from './lib/guards/auth/auth.guard';
+export * from './lib/controllers';
+export * from './lib/gateways';

package/src/lib/controllers/crud/crud.controller.spec.ts

@@ -0,0 +1,111 @@
+import { Request } from 'express';
+import * as XLSX from 'xlsx';
+
+import { CrudService } from '@smartsoft001/crud-shell-app-services';
+
+import { CrudController } from './crud.controller';
+import * as q2mModule from './query-to-mongo';
+
+jest.mock('xlsx');
+jest.mock('json2csv', () => ({
+  Parser: jest.fn().mockImplementation(() => ({ parse: jest.fn(() => 'csv') })),
+}));
+
+describe('crud-nestjs: CrudController', () => {
+  let service: jest.Mocked<CrudService<any>>;
+  let controller: CrudController<any>;
+
+  beforeEach(() => {
+    service = {
+      create: jest.fn(),
+      createMany: jest.fn(),
+      readById: jest.fn(),
+      read: jest.fn(),
+      update: jest.fn(),
+      updatePartial: jest.fn(),
+      delete: jest.fn(),
+      uploadAttachment: jest.fn(),
+      getAttachmentInfo: jest.fn(),
+      getAttachmentStream: jest.fn(),
+      deleteAttachment: jest.fn(),
+    } as any;
+    controller = new CrudController(service);
+  });
+
+  describe('constructor', () => {
+    it('should assign service', () => {
+      expect(controller['service']).toBe(service);
+    });
+  });
+
+  describe('static getLink', () => {
+    it('should return correct link', () => {
+      const req = {
+        protocol: 'http',
+        headers: { host: 'localhost' },
+        url: '/api',
+      } as Request;
+      expect(CrudController.getLink(req)).toBe('http://localhost/api');
+    });
+  });
+
+  describe('getQueryObject', () => {
+    it('should call q2m and return result', () => {
+      const query = { a: 1, b: 2 };
+      const result = { criteria: {}, options: {}, links: jest.fn() };
+      jest.spyOn(q2mModule, 'q2m').mockReturnValue(result);
+      expect(controller['getQueryObject'](query)).toBe(result);
+    });
+  });
+
+  describe('parseToCsv', () => {
+    it('should return empty string for empty data', () => {
+      expect(controller['parseToCsv']([])).toBe('');
+    });
+    it('should return csv string for data', () => {
+      const data = [{ a: '1', b: '2' }];
+      jest
+        .spyOn(controller as any, 'getDataWithFields')
+        .mockReturnValue({ res: data, fields: ['a', 'b'] });
+      expect(controller['parseToCsv'](data)).toBe('csv');
+    });
+  });
+
+  describe('parseToXlsx', () => {
+    it('should return empty string for empty data', () => {
+      expect(controller['parseToXlsx']([])).toBe('');
+    });
+    it('should call XLSX utils for data', () => {
+      const data = [{ a: '1', b: '2' }];
+      jest
+        .spyOn(controller as any, 'getDataWithFields')
+        .mockReturnValue({ res: data, fields: ['a', 'b'] });
+      const jsonToSheet = jest
+        .spyOn(XLSX.utils, 'json_to_sheet')
+        .mockReturnValue({} as any);
+      const bookNew = jest
+        .spyOn(XLSX.utils, 'book_new')
+        .mockReturnValue({} as any);
+      const bookAppendSheet = jest
+        .spyOn(XLSX.utils, 'book_append_sheet')
+        .mockImplementation();
+      const write = jest.spyOn(XLSX, 'write').mockReturnValue('buffer' as any);
+      expect(controller['parseToXlsx'](data)).toBe('buffer');
+    });
+  });
+
+  describe('getDataWithFields', () => {
+    it('should flatten fields and remove html', () => {
+      const data = [{ a: '<b>1</b>', b: { c: '2' } }];
+      const result = controller['getDataWithFields'](data);
+      expect(result.fields.includes('a')).toBe(true);
+    });
+    it('should remove keys not in fields', () => {
+      const data = [{ a: '1', b: '2' }];
+      const result = controller['getDataWithFields'](data);
+      expect(
+        Object.keys(result.res[0]).every((k) => result.fields.includes(k)),
+      ).toBe(true);
+    });
+  });
+});

package/src/lib/controllers/crud/crud.controller.ts

@@ -0,0 +1,353 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  NotFoundException,
+  Param,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Req,
+  Res,
+  UseGuards,
+} from '@nestjs/common';
+import { q2m } from './query-to-mongo';
+import { Response, Request } from 'express';
+import { Parser } from 'json2csv';
+import * as _ from 'lodash';
+import * as XLSX from 'xlsx';
+import * as Busboy from 'busboy';
+import { Readable } from 'stream';
+import * as moment from 'moment-timezone';
+
+import { CrudService } from '@smartsoft001/crud-shell-app-services';
+import { IUser } from '@smartsoft001/users';
+import { User } from '@smartsoft001/nestjs';
+import { IEntity } from '@smartsoft001/domain-core';
+import {
+  AuthJwtGuard,
+  AuthOrAnonymousJwtGuard,
+} from '../../guards/auth/auth.guard';
+import { CreateManyMode } from '@smartsoft001/crud-domain';
+import { GuidService } from '@smartsoft001/utils';
+
+@Controller('')
+export class CrudController<T extends IEntity<string>> {
+  constructor(protected readonly service: CrudService<T>) {}
+
+  static getLink(req: Request): string {
+    return req.protocol + '://' + req.headers.host + req.url;
+  }
+
+  @UseGuards(AuthJwtGuard)
+  @Post()
+  @HttpCode(200)
+  async create(
+    @Body() data: T,
+    @User() user: IUser,
+    @Res() res: Response,
+  ): Promise<Response> {
+    const id = await this.service.create(data, user);
+    res.set('Location', CrudController.getLink(res.req) + '/' + id);
+    return res.send({
+      id,
+    });
+  }
+
+  @UseGuards(AuthJwtGuard)
+  @Post('bulk')
+  async createMany(
+    @Body() data: T[],
+    @User() user: IUser,
+    @Res() res: Response,
+    @Query('mode') mode: CreateManyMode,
+  ): Promise<Response> {
+    const result = await this.service.createMany(data, user, { mode });
+    return res.send(result);
+  }
+
+  @UseGuards(AuthOrAnonymousJwtGuard)
+  @Get(':id')
+  async readById(
+    @Param() params: { id: string },
+    @User() user: IUser,
+  ): Promise<T> {
+    const result = await this.service.readById(params.id, user);
+
+    if (!result) {
+      throw new NotFoundException('Invalid id');
+    }
+
+    return result;
+  }
+
+  @UseGuards(AuthOrAnonymousJwtGuard)
+  @Get()
+  async read(
+    @User() user: IUser,
+    @Req() req: Request,
+    @Res() res: Response,
+  ): Promise<void> {
+    const object = this.getQueryObject(req.query);
+
+    const { data, totalCount } = await this.service.read(
+      object.criteria,
+      {
+        ...object.options,
+        allowDiskUse:
+          req.headers['content-type'] === 'text/csv' ||
+          req.headers['content-type'] ===
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      },
+      user,
+    );
+
+    if (req.headers['content-type'] === 'text/csv') {
+      res.set({
+        'Content-Type': 'text/csv',
+      });
+      res.send(this.parseToCsv(data));
+    }
+
+    if (
+      req.headers['content-type'] ===
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    ) {
+      res.set({
+        'Content-Type':
+          'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      });
+      res.send(this.parseToXlsx(data));
+    }
+
+    res.send({
+      data,
+      totalCount,
+      links: object.links(
+        CrudController.getLink(req).split('?')[0],
+        totalCount,
+      ),
+    });
+  }
+
+  @UseGuards(AuthJwtGuard)
+  @Put(':id')
+  async update(
+    @Param() params: { id: string },
+    @Body() data: T,
+    @User() user: IUser,
+  ): Promise<void> {
+    await this.service.update(params.id, data, user);
+  }
+
+  @UseGuards(AuthJwtGuard)
+  @Patch(':id')
+  async updatePartial(
+    @Param() params: { id: string },
+    @Body() data: Partial<T>,
+    @User() user: IUser,
+  ): Promise<void> {
+    await this.service.updatePartial(params.id, data, user);
+  }
+
+  @UseGuards(AuthJwtGuard)
+  @Delete(':id')
+  async delete(
+    @Param() params: { id: string },
+    @User() user: IUser,
+  ): Promise<void> {
+    await this.service.delete(params.id, user);
+  }
+
+  @Post('attachments')
+  uploadAttachment(@Req() request: Request, @Res() response: Response) {
+    const busboy = new Busboy({
+      headers: request.headers,
+    });
+    const id = GuidService.create();
+    const readable = new Readable();
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    readable._read = () => {};
+
+    let fileName, encoding, mimeType;
+
+    busboy.on(
+      'file',
+      (field, file, resultFileName, resultEncoding, resultMimeType) => {
+        fileName = resultFileName;
+        encoding = resultEncoding;
+        mimeType = resultMimeType;
+
+        this.service.uploadAttachment({
+          id,
+          stream: readable,
+          fileName,
+          encoding,
+          mimeType,
+        });
+
+        file.on('data', (data) => {
+          readable.push(data);
+        });
+      },
+    );
+
+    busboy.on('finish', function () {
+      readable.push(null);
+      response.set('Location', CrudController.getLink(response.req) + '/' + id);
+      response.json({
+        id,
+        fileName,
+        contentType: mimeType,
+        length: readable.readableLength,
+      });
+      response.end();
+    });
+
+    return request.pipe(busboy);
+  }
+
+  @Get('attachments/:id')
+  async downloadAttachment(
+    @Param('id') id: string,
+    @Req() request: Request,
+    @Res() response: Response,
+  ) {
+    const fileInfo = await this.service.getAttachmentInfo(id);
+
+    if (request.headers.range) {
+      const range = request.headers.range.substr(6).split('-');
+      const start = parseInt(range[0], 10);
+      const end = parseInt(range[1], 10) || null;
+
+      const readstream = await this.service.getAttachmentStream(id, {
+        start,
+        end,
+      });
+
+      response.status(206);
+      response.set({
+        'Accept-Ranges': 'bytes',
+        'Content-Type': fileInfo.contentType,
+        'Content-Range': `bytes ${start}-${end ? end : fileInfo.length - 1}/${
+          fileInfo.length
+        }`,
+        'Content-Length': (end ? end : fileInfo.length) - start,
+        'Content-Disposition': `attachment; filename="${encodeURI(fileInfo.fileName)}"`,
+      });
+
+      response.on('close', () => {
+        readstream.destroy();
+      });
+
+      readstream.pipe(response);
+    } else {
+      const readstream = await this.service.getAttachmentStream(id);
+
+      response.on('close', () => {
+        readstream.destroy();
+      });
+
+      response.status(200);
+      response.set({
+        'Accept-Range': 'bytes',
+        'Content-Type': fileInfo.contentType,
+        'Content-Length': fileInfo.length,
+        'Content-Disposition': `attachment; filename="${encodeURI(fileInfo.fileName)}"`,
+      });
+
+      readstream.pipe(response);
+    }
+  }
+
+  @Delete('attachments/:id')
+  async deleteAttachment(@Param('id') id: string): Promise<void> {
+    await this.service.deleteAttachment(id);
+  }
+
+  protected getQueryObject(queryObject: any): { criteria; options; links } {
+    let q = '';
+
+    Object.keys(queryObject).forEach((key) => {
+      q += `&${key}=${queryObject[key]}`;
+    });
+
+    const result = q2m(q);
+
+    return result;
+  }
+
+  protected parseToXlsx(data: T[]) {
+    if (!data || !data.length) {
+      return '';
+    }
+
+    const { res } = this.getDataWithFields(data);
+
+    const ws = XLSX.utils.json_to_sheet(res);
+
+    const wb = XLSX.utils.book_new();
+    XLSX.utils.book_append_sheet(wb, ws, 'data');
+
+    return XLSX.write(wb, { bookType: 'xlsx', type: 'buffer' });
+  }
+
+  protected parseToCsv(data: T[]): string {
+    if (!data || !data.length) {
+      return '';
+    }
+
+    const { res, fields } = this.getDataWithFields(data);
+
+    return new Parser(fields).parse(data);
+  }
+
+  protected getDataWithFields(data: Array<T>): { res; fields } {
+    const fields = [];
+
+    const execute = (item, baseKey, baseItem) => {
+      Object.keys(item).forEach((key) => {
+        if (item[key] && typeof item[key] === 'string') {
+          item[key] = item[key].replace(/<[^>]*>?/gm, '');
+        }
+
+        if (item[key] && item[key] instanceof Date) {
+          item[key] = moment(item[key])
+            .tz('Europe/Warsaw')
+            .format('YYYY-MM-DD HH:mm:ss');
+        }
+
+        const val = item[key];
+
+        if (_.isArray(val)) {
+          return;
+        } else if (_.isObject(val) && Object.keys(val).length) {
+          execute(val, baseKey + key + '_', baseItem);
+        } else if (baseKey) {
+          baseItem[baseKey + key] = val;
+          if (!fields.some((f) => f === baseKey + key))
+            fields.push(baseKey + key);
+        } else {
+          if (!fields.some((f) => f === key)) fields.push(key);
+        }
+      });
+    };
+
+    data.forEach((item) => {
+      execute(item, '', item);
+    });
+
+    data.forEach((item) => {
+      Object.keys(item).forEach((key) => {
+        if (!fields.some((f) => f === key)) {
+          delete item[key];
+        }
+      });
+    });
+
+    return { res: data, fields };
+  }
+}

package/src/lib/controllers/crud/query-to-mongo.spec.ts

@@ -0,0 +1,32 @@
+import * as queryToMongo from './query-to-mongo';
+
+describe('crud-nestjs: query-to-mongo', () => {
+  describe('q2m', () => {
+    it('should convert query string to mongo object', () => {
+      const result = queryToMongo.q2m('a=1&b=2');
+      expect(result).toHaveProperty('criteria');
+    });
+    it('should convert query object to mongo object', () => {
+      const result = queryToMongo.q2m({ a: '1', b: '2' });
+      expect(result).toHaveProperty('criteria');
+    });
+    it('should provide links function', () => {
+      const result = queryToMongo.q2m({ a: '1', limit: '2', offset: '0' });
+      expect(typeof result.links).toBe('function');
+    });
+    it('links should return null if no limit', () => {
+      const result = queryToMongo.q2m({ a: '1' });
+      expect(result.links('url', 10)).toBeNull();
+    });
+    it('links should return prev and first if offset > 0', () => {
+      const result = queryToMongo.q2m({ a: '1', limit: '2', offset: '2' });
+      const links = result.links('url', 10);
+      expect(links).toHaveProperty('prev');
+    });
+    it('links should return next and last if more pages', () => {
+      const result = queryToMongo.q2m({ a: '1', limit: '2', offset: '0' });
+      const links = result.links('url', 10);
+      expect(links).toHaveProperty('next');
+    });
+  });
+});