@lenne.tech/nest-server 10.0.3 → 10.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "10.0.3",
+  "version": "10.0.5",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -17,9 +17,9 @@
     "build": "rimraf dist && nest build",
     "build:pack": "npm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
     "build:dev": "npm run build && yalc push --private",
-    "docs": "npm run docs:ci && open ./public/index.html",
+    "docs": "npm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
     "docs:bootstrap": "node extras/update-spectaql-version.mjs && npx -y spectaql ./spectaql.yml",
-    "docs:ci": "ts-node ./scripts/init-server.ts && npm run docs:bootstrap",
+    "docs:ci": "ts-node ./scripts/init-server.ts && npm run docs:bootstrap && compodoc -p tsconfig.json",
     "format": "prettier --write 'src/**/*.ts'",
     "format:staged": "pretty-quick --staged",
     "lint": "eslint \"{src,tests}/**/*.ts\" --fix",
@@ -71,8 +71,8 @@
     "@nestjs/mongoose": "10.0.1",
     "@nestjs/passport": "10.0.0",
     "@nestjs/platform-express": "10.1.3",
-    "@nestjs/schedule": "3.0.1",
-    "@nestjs/terminus": "^10.0.1",
+    "@nestjs/schedule": "3.0.2",
+    "@nestjs/terminus": "10.0.1",
     "apollo-server-core": "3.11.1",
     "apollo-server-express": "3.11.1",
     "bcrypt": "5.1.0",
@@ -102,34 +102,37 @@
     "reflect-metadata": "0.1.13",
     "rfdc": "1.3.0",
     "rimraf": "5.0.1",
-    "rxjs": "7.8.1"
+    "rxjs": "7.8.1",
+    "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
-    "@lenne.tech/eslint-config-ts": "0.0.8",
+    "@babel/plugin-proposal-private-methods": "7.18.6",
+    "@compodoc/compodoc": "1.1.21",
+    "@lenne.tech/eslint-config-ts": "0.0.9",
     "@nestjs/cli": "10.1.11",
-    "@nestjs/schematics": "10.0.1",
+    "@nestjs/schematics": "10.0.2",
     "@nestjs/testing": "10.1.3",
     "@swc/cli": "0.1.62",
-    "@swc/core": "1.3.73",
-    "@swc/jest": "0.2.27",
+    "@swc/core": "1.3.76",
+    "@swc/jest": "0.2.28",
     "@types/compression": "1.7.2",
     "@types/cookie-parser": "1.4.3",
     "@types/cron": "2.0.1",
     "@types/ejs": "3.1.2",
     "@types/express": "4.17.17",
     "@types/jest": "29.5.3",
-    "@types/lodash": "4.14.196",
+    "@types/lodash": "4.14.197",
     "@types/multer": "1.4.7",
-    "@types/node": "20.4.5",
+    "@types/node": "20.4.9",
     "@types/nodemailer": "6.4.9",
     "@types/passport": "1.0.12",
     "@types/supertest": "2.0.12",
-    "@typescript-eslint/eslint-plugin": "6.2.1",
-    "@typescript-eslint/parser": "6.2.1",
+    "@typescript-eslint/eslint-plugin": "6.3.0",
+    "@typescript-eslint/parser": "6.3.0",
     "coffeescript": "2.7.0",
     "eslint": "8.46.0",
-    "eslint-config-prettier": "8.9.0",
-    "eslint-plugin-unused-imports": "^3.0.0",
+    "eslint-config-prettier": "9.0.0",
+    "eslint-plugin-unused-imports": "3.0.0",
     "find-file-up": "2.0.1",
     "grunt": "1.6.1",
     "grunt-bg-shell": "2.3.3",
@@ -140,7 +143,7 @@
     "jest": "29.6.2",
     "npm-watch": "0.11.0",
     "pm2": "5.3.0",
-    "prettier": "3.0.0",
+    "prettier": "3.0.1",
     "pretty-quick": "3.1.3",
     "supertest": "6.3.3",
     "ts-jest": "29.1.1",

package/src/config.env.ts

@@ -57,6 +57,11 @@ const config: { [env: string]: IServerOptions } = {
     },
     healthCheck: {
       enabled: true,
+      configs: {
+        database: {
+          enabled: true,
+        },
+      },
     },
     ignoreSelectionsForPopulate: true,
     jwt: {
@@ -78,6 +83,7 @@ const config: { [env: string]: IServerOptions } = {
       collation: {
         locale: 'de',
       },
+      modelDocumentation: true,
       uri: 'mongodb://127.0.0.1/nest-server-local',
     },
     port: 3000,
@@ -133,6 +139,11 @@ const config: { [env: string]: IServerOptions } = {
     },
     healthCheck: {
       enabled: true,
+      configs: {
+        database: {
+          enabled: true,
+        },
+      },
     },
     ignoreSelectionsForPopulate: true,
     jwt: {
@@ -154,6 +165,7 @@ const config: { [env: string]: IServerOptions } = {
       collation: {
         locale: 'de',
       },
+      modelDocumentation: false,
       uri: 'mongodb://127.0.0.1/nest-server-dev',
     },
     port: 3000,
@@ -209,6 +221,11 @@ const config: { [env: string]: IServerOptions } = {
     },
     healthCheck: {
       enabled: true,
+      configs: {
+        database: {
+          enabled: true,
+        },
+      },
     },
     ignoreSelectionsForPopulate: true,
     jwt: {
@@ -230,6 +247,7 @@ const config: { [env: string]: IServerOptions } = {
       collation: {
         locale: 'de',
       },
+      modelDocumentation: false,
       uri: 'mongodb://127.0.0.1/nest-server-prod',
     },
     port: 3000,

package/src/core/common/helpers/filter.helper.ts

@@ -90,8 +90,10 @@ export function findFilter(options?: {
 
   // Optimizations
   if (!filterOptions[config.type].length) {
+    // If there are no conditions, return an empty object
     filterOptions = {};
   } else if (filterOptions[config.type].length === 1) {
+    // if there is only one condition, integrate it directly into the filter options
     const additionalProperties = filterOptions[config.type][0];
     delete filterOptions[config.type];
     assignPlain(filterOptions, additionalProperties);
@@ -150,22 +152,29 @@ export function generateFilterQuery<T = any>(
   // Process single filter
   if (filter.singleFilter) {
     // Init variables
-    const { not, options, field, convertToObjectId, isReference } = filter.singleFilter;
+    const { not, options, convertToObjectId, isReference } = filter.singleFilter;
+    let field = filter.singleFilter.field;
     let value = filter.singleFilter.value;
 
-    // Convert value to object ID(s)
+    // Convert value to object ID(s), but don't change the name or the filter itself
     if (convertToObjectId || isReference) {
       value = getObjectIds(value);
 
       // Check if value is a string ID and automatic ObjectID filtering is activated
     } else if (config.automaticObjectIdFiltering && checkStringIds(value)) {
-      // Set both the string filter and the ObjectID filtering in an OR construction
-      const alternativeQuery = clone(filter.singleFilter, { circles: false });
-      alternativeQuery.value = getObjectIds(value);
-      const conf = Object.assign({}, config, { automaticObjectIdFiltering: false });
-      return {
-        $or: [generateFilterQuery(filter, conf), generateFilterQuery({ singleFilter: alternativeQuery }, conf)],
-      };
+      if (field === 'id') {
+        // Replace field name id field with _id and convert value to ObjectId
+        field = '_id';
+        value = getObjectIds(value);
+      } else {
+        // For every other fields set both the string filter and the ObjectID filtering in an OR construction
+        const alternativeQuery = clone(filter.singleFilter, { circles: false });
+        alternativeQuery.value = getObjectIds(value);
+        const conf = Object.assign({}, config, { automaticObjectIdFiltering: false });
+        return {
+          $or: [generateFilterQuery(filter, conf), generateFilterQuery({ singleFilter: alternativeQuery }, conf)],
+        };
+      }
     }
 
     // Convert filter

package/src/core/common/interfaces/server-options.interface.ts

@@ -60,7 +60,9 @@ export interface IJwt {
 export interface IServerOptions {
   /**
    * Automatically detect ObjectIds in string values in FilterQueries
-   * and expand them as OR query with string and ObjectId
+   * and expand them as OR query with string and ObjectId.
+   * Fields with the name "id" are renamed to "_id" and the value is converted to ObjectId,
+   * without changing the filter into an OR combined filter.
    * See generateFilterQuery in Filter helper (src/core/common/helpers/filter.helper.ts)
    */
   automaticObjectIdFiltering?: boolean;
@@ -176,26 +178,98 @@ export interface IServerOptions {
    * Whether to activate health check endpoints
    */
   healthCheck?: {
+
+    /**
+     * Whether health check is enabled
+     */
     enabled?: boolean;
+
+    /**
+     * Configuration of single health checks
+     */
     configs?: {
+
+      /**
+       * Configuration for database health check
+       */
       database?: {
-        disabled?: boolean;
+
+        /**
+         * Whether to enable the database health check
+         */
+        enabled?: boolean;
+
+        /**
+         * Key in result JSON
+         */
         key?: string;
+
+        /**
+         * Database health check options
+         */
         options?: MongoosePingCheckSettings;
       };
+
+      /**
+       * Configuration for memory heap health check
+       */
       memoryHeap?: {
-        disabled?: boolean;
+
+        /**
+         * Whether to enable the memory heap health check
+         */
+        enabled?: boolean;
+
+        /**
+         * Key in result JSON
+         */
         key?: string;
+
+        /**
+         * Memory limit in bytes
+         */
         heapUsedThreshold?: number;
       };
+
+      /**
+       * Configuration for memory resident set size health check
+       */
       memoryRss?: {
-        disabled?: boolean;
+
+        /**
+         * Whether to enable the memory resident set size health check
+         */
+        enabled?: boolean;
+
+        /**
+         * Key in result JSON
+         */
         key?: string;
+
+        /**
+         * Memory limit in bytes
+         */
         rssThreshold?: number;
       };
+
+      /**
+       * Configuration for disk space health check
+       */
       storage?: {
-        disabled?: boolean;
+
+        /**
+         * Whether to enable the disk space health check
+         */
+        enabled?: boolean;
+
+        /**
+         * Key in result JSON
+         */
         key?: string;
+
+        /**
+         * Disk health indicator options
+         */
         options?: DiskHealthIndicatorOptions;
       };
     };
@@ -247,8 +321,19 @@ export interface IServerOptions {
    * Configuration for Mongoose
    */
   mongoose?: {
+
+    /**
+     * Collation allows users to specify language-specific rules for string comparison,
+     * such as rules for letter-case and accent marks.
+     */
     collation?: CollationOptions;
 
+    /**
+     * Whether to create SVG-Diagrams of mongoose models
+     * @beta
+     */
+    modelDocumentation?: boolean;
+
     /**
      * Mongoose connection string
      */
@@ -258,6 +343,15 @@ export interface IServerOptions {
      * Mongoose module options
      */
     options?: MongooseModuleOptions;
+
+    /**
+     * Mongoose supports a separate strictQuery option to avoid strict mode for query filters.
+     * This is because empty query filters cause Mongoose to return all documents in the model, which can cause issues.
+     * See: https://github.com/Automattic/mongoose/issues/10763
+     * and: https://mongoosejs.com/docs/guide.html#strictQuery
+     * default: false
+     */
+    strictQuery?: boolean;
   };
 
   /**

package/src/core/common/services/model-doc.service.ts

@@ -0,0 +1,140 @@
+import fs = require('fs');
+import { Injectable, OnApplicationBootstrap } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection } from 'mongoose';
+import YumlDiagram = require('yuml-diagram');
+
+/**
+ * Schema config for yUml creation
+ */
+export interface ModelDocSchemaConfig {
+  isArray: boolean;
+  name: string;
+  ref: string;
+  type: string;
+}
+
+/**
+ * Model documentation as yUML-SVG
+ */
+@Injectable()
+export class ModelDocService implements OnApplicationBootstrap {
+
+  constructor(
+    @InjectConnection() private readonly connection: Connection,
+  ) {
+  }
+
+  /**
+   * Lifecycle hook that is called right after the application has started.
+   */
+  async onApplicationBootstrap() {
+    const schemaJson = this.getSchemaJson();
+    const yUml = this.jsonToYuml(schemaJson);
+    this.yUmlToSvg(yUml);
+  }
+
+  /**
+   * Analyse the mongoose database models and create JSON
+   * @protected
+   */
+  protected getSchemaJson(): Record<string, Record<string, ModelDocSchemaConfig>> {
+
+    // Prepare results
+    const results: Record<string, Record<string, ModelDocSchemaConfig>> = {};
+
+    // Process models
+    const models = this.connection.modelNames();
+    for (const modelName of models) {
+      results[modelName] = {};
+
+      // Process schema
+      const schema = this.connection.model(modelName).schema;
+      Object.keys(schema.paths).forEach((key) => {
+        const obj: any = schema.obj[key] || {};
+        const path = schema.paths[key];
+
+        results[modelName][key] = {
+          isArray: path.instance === 'Array',
+          name: path.path,
+          ref: Array.isArray(obj) ? undefined : obj.ref,
+          type: path.instance === 'Array'
+            ? Array.isArray(obj)
+              ? obj[0]() === '' ? 'String' : obj[0]()
+              : typeof obj.type === 'function' ? obj.type.name : obj.type
+            : path.instance,
+        };
+        if (results[modelName][key].type === 'Mixed') {
+          results[modelName][key].type = 'JSON';
+        }
+      });
+    }
+
+    // Return results
+    return results;
+  }
+
+  /**
+   * Convert JSON to yUML
+   * @param json
+   * @protected
+   */
+  protected jsonToYuml(json: Record<string, Record<string, ModelDocSchemaConfig>>) {
+    // Convert JSON to yUML
+    let yumlText = '// {type:class}';
+    for (const [modelName, properties] of Object.entries(json)) {
+      yumlText += `\n[${modelName} | `;
+      const refs = [];
+      let subYumlText = '';
+      for (const [key, value] of Object.entries(properties)) {
+        let type = value.type;
+        if (value.isArray) {
+          type = `Array<${type}>`;
+        }
+        if (value.ref) {
+          refs.push(`[${modelName}]-${key}>[${value.ref}]`);
+        }
+        if (key.startsWith('__')) {
+          continue;
+        }
+        if (key === '_id') {
+          subYumlText = `id: ObjectId; ${subYumlText}`;
+          continue;
+        }
+        subYumlText += `${key}: ${type}; `;
+      }
+      yumlText += `${subYumlText}]\n`;
+      for (const ref of refs) {
+        yumlText += `${ref}\n`;
+      }
+    }
+    return yumlText;
+  }
+
+  /**
+   * Convert yUML to SVG
+   * @param yUmlText
+   * @protected
+   */
+  protected yUmlToSvg(yUmlText: String) {
+
+    // Create diagrams
+    // see https://github.com/jaime-olivares/yuml-diagram
+    // and https://yuml.me/diagram/scruffy/class/samples
+    const yuml = new YumlDiagram();
+    const svgLightBg = yuml.processYumlDocument(yUmlText, false);
+    const svgDarkBg = yuml.processYumlDocument(yUmlText, true);
+
+    // Save diagrams
+    fs.writeFile('model-doc-light.svg', svgLightBg, (err) => {
+      if (err) {
+        console.error(err);
+      }
+    });
+    fs.writeFile('model-doc-dark.svg', svgDarkBg, (err) => {
+      if (err) {
+        console.error(err);
+      }
+    });
+  }
+}

package/src/core/modules/health-check/core-health-check.service.ts

@@ -27,26 +27,28 @@ export class CoreHealthCheckService {
 
   healthCheck(): Promise<HealthCheckResult> {
     const healthIndicatorFunctions = [];
-    if (!this.config.get<boolean>('healthCheck.configs.database.disabled')) {
+    if (this.config.get<boolean>('healthCheck.configs.database.enabled')) {
       healthIndicatorFunctions.push(() =>
         this.db.pingCheck(
           this.config.get<string>('healthCheck.configs.database.key') ?? 'database',
           this.config.get<MongoosePingCheckSettings>('healthCheck.configs.database.options') ?? { timeout: 300 },
         ));
     }
-    if (!this.config.get<boolean>('healthCheck.configs.memoryHeap.disabled')) {
+    if (this.config.get<boolean>('healthCheck.configs.memoryHeap.enabled')) {
       healthIndicatorFunctions.push(() => this.memory.checkHeap(
         this.config.get<string>('healthCheck.configs.memoryHeap.key') ?? 'memoryHeap',
-        this.config.get<number>('healthCheck.configs.memoryHeap.heapUsedThreshold') ?? 150 * 1024 * 1024,
+        // memory in bytes (4GB default)
+        this.config.get<number>('healthCheck.configs.memoryHeap.heapUsedThreshold') ?? 4 * 1024 * 1024 * 1024,
       ));
     }
-    if (!this.config.get<boolean>('healthCheck.configs.memoryRss.disabled')) {
+    if (this.config.get<boolean>('healthCheck.configs.memoryRss.enabled')) {
       healthIndicatorFunctions.push(() => this.memory.checkRSS(
         this.config.get<string>('healthCheck.configs.memoryRss.key') ?? 'memoryRss',
-        this.config.get<number>('healthCheck.configs.memoryRss.rssThreshold') ?? 150 * 1024 * 1024,
+        // memory in bytes (4GB default)
+        this.config.get<number>('healthCheck.configs.memoryRss.rssThreshold') ?? 4 * 1024 * 1024 * 1024,
       ));
     }
-    if (!this.config.get<boolean>('healthCheck.configs.storage.disabled')) {
+    if (this.config.get<boolean>('healthCheck.configs.storage.enabled')) {
       healthIndicatorFunctions.push(() => this.disk.checkStorage(
         this.config.get<string>('healthCheck.configs.storage.key') ?? 'storage',
         this.config.get<DiskHealthIndicatorOptions>('healthCheck.configs.storage.options') ?? {

package/src/core/modules/user/core-user.model.ts

@@ -52,7 +52,7 @@ export abstract class CoreUserModel extends CorePersistenceModel {
    */
   @Field(type => [String], { description: 'Roles of the user', nullable: true })
   @IsOptional()
-  @Prop()
+  @Prop([String])
   roles: string[] = undefined;
 
   /**

package/src/core.module.ts

@@ -5,6 +5,7 @@ import { GraphQLModule } from '@nestjs/graphql';
 import { MongooseModule } from '@nestjs/mongoose';
 import { Context } from 'apollo-server-core';
 import graphqlUploadExpress = require('graphql-upload/graphqlUploadExpress.js');
+import mongoose from 'mongoose';
 import { merge } from './core/common/helpers/config.helper';
 import { IServerOptions } from './core/common/interfaces/server-options.interface';
 import { MapAndValidatePipe } from './core/common/pipes/map-and-validate.pipe';
@@ -14,6 +15,7 @@ import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { TemplateService } from './core/common/services/template.service';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
+import { ModelDocService } from './core/common/services/model-doc.service';
 
 /**
  * Core module (dynamic)
@@ -127,14 +129,14 @@ export class CoreModule implements NestModule {
     );
 
     // Set providers
-    const providers = [
+    const providers: any[] = [
       // The ConfigService provides access to the current configuration of the module
       {
         provide: ConfigService,
         useValue: new ConfigService(config),
       },
 
-      // [Global] Map plain objects to metatype and validate
+      // [Global] Map plain objects to meta-type and validate
       {
         provide: APP_PIPE,
         useClass: MapAndValidatePipe,
@@ -149,6 +151,15 @@ export class CoreModule implements NestModule {
       ComplexityPlugin,
     ];
 
+    if (config.mongoose?.modelDocumentation) {
+      providers.push(ModelDocService);
+    }
+
+    // Set strict query to false by default
+    // See: https://github.com/Automattic/mongoose/issues/10763
+    // and: https://mongoosejs.com/docs/guide.html#strictQuery
+    mongoose.set('strictQuery', config.mongoose.strictQuery || false);
+
     const imports: any[] = [
       MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options),
       GraphQLModule.forRootAsync<ApolloDriverConfig>(

package/src/index.ts

@@ -64,6 +64,7 @@ export * from './core/common/services/core-cron-jobs.service';
 export * from './core/common/services/crud.service';
 export * from './core/common/services/email.service';
 export * from './core/common/services/mailjet.service';
+export * from './core/common/services/model-doc.service';
 export * from './core/common/services/module.service';
 export * from './core/common/services/template.service';
 export * from './core/common/types/core-model-constructor.type';