@lenne.tech/nest-server 11.2.0 → 11.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.2.0",
+  "version": "11.4.0",
   "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",
@@ -67,18 +67,18 @@
     "node": ">= 20"
   },
   "dependencies": {
-    "@apollo/gateway": "2.11.3",
+    "@apollo/gateway": "2.12.0",
     "@getbrevo/brevo": "3.0.1",
     "@nestjs/apollo": "13.1.0",
-    "@nestjs/common": "11.1.6",
-    "@nestjs/core": "11.1.6",
+    "@nestjs/common": "11.1.8",
+    "@nestjs/core": "11.1.8",
     "@nestjs/graphql": "13.1.0",
     "@nestjs/jwt": "11.0.1",
     "@nestjs/mongoose": "11.0.3",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.6",
+    "@nestjs/platform-express": "11.1.8",
     "@nestjs/schedule": "6.0.1",
-    "@nestjs/swagger": "11.2.0",
+    "@nestjs/swagger": "11.2.1",
     "@nestjs/terminus": "11.0.0",
     "apollo-server-core": "3.13.0",
     "apollo-server-express": "3.13.0",
@@ -89,55 +89,52 @@
     "cookie-parser": "1.4.7",
     "dotenv": "17.2.3",
     "ejs": "3.1.10",
-    "graphql": "16.11.0",
+    "graphql": "16.12.0",
     "graphql-query-complexity": "1.1.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
-    "light-my-request": "6.6.0",
     "lodash": "4.17.21",
-    "mongodb": "6.20.0",
-    "mongoose": "8.19.1",
+    "mongodb": "7.0.0",
+    "mongoose": "8.19.3",
     "multer": "2.0.2",
-    "node-mailjet": "6.0.9",
-    "nodemailer": "7.0.9",
-    "nodemon": "3.1.10",
+    "node-mailjet": "6.0.11",
+    "nodemailer": "7.0.10",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
-    "rimraf": "6.0.1",
     "rxjs": "7.8.2",
     "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
     "@babel/plugin-proposal-private-methods": "7.18.6",
-    "@compodoc/compodoc": "1.1.31",
-    "@lenne.tech/eslint-config-ts": "2.1.3",
+    "@compodoc/compodoc": "1.1.32",
+    "@lenne.tech/eslint-config-ts": "2.1.4",
     "@nestjs/cli": "11.0.10",
     "@nestjs/schematics": "11.0.9",
-    "@nestjs/testing": "11.1.6",
-    "@swc/cli": "0.7.8",
-    "@swc/core": "1.13.5",
+    "@nestjs/testing": "11.1.8",
+    "@swc/cli": "0.7.9",
+    "@swc/core": "1.15.0",
     "@swc/jest": "0.2.39",
     "@types/compression": "1.8.1",
-    "@types/cookie-parser": "1.4.9",
+    "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "4.17.21",
     "@types/jest": "30.0.0",
     "@types/lodash": "4.17.20",
     "@types/multer": "2.0.0",
-    "@types/node": "24.7.1",
-    "@types/nodemailer": "7.0.2",
+    "@types/node": "24.10.0",
+    "@types/nodemailer": "7.0.3",
     "@types/passport": "1.0.17",
     "@types/supertest": "6.0.3",
-    "@typescript-eslint/eslint-plugin": "8.46.0",
-    "@typescript-eslint/parser": "8.46.0",
+    "@typescript-eslint/eslint-plugin": "8.46.3",
+    "@typescript-eslint/parser": "8.46.3",
     "coffeescript": "2.7.0",
-    "eslint": "9.37.0",
+    "eslint": "9.39.1",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-unused-imports": "4.2.0",
+    "eslint-plugin-unused-imports": "4.3.0",
     "find-file-up": "2.0.1",
     "grunt": "1.6.1",
     "grunt-bg-shell": "2.3.3",
@@ -146,14 +143,16 @@
     "grunt-sync": "0.8.2",
     "husky": "9.1.7",
     "jest": "30.2.0",
+    "nodemon": "3.1.10",
     "npm-watch": "0.13.0",
     "pm2": "6.0.13",
     "prettier": "3.6.2",
     "pretty-quick": "4.2.2",
+    "rimraf": "6.1.0",
     "supertest": "7.1.4",
     "ts-jest": "29.4.5",
     "ts-loader": "9.5.4",
-    "ts-morph": "27.0.0",
+    "ts-morph": "27.0.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "typescript": "5.9.3",
@@ -164,7 +163,7 @@
       "flat": "5.0.2",
       "mime": "2.6.0"
     },
-    "ts-morph": "27.0.0"
+    "ts-morph": "27.0.2"
   },
   "jest": {
     "collectCoverage": true,
@@ -183,9 +182,14 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "nest-migrate": "./bin/migrate.js",
+    "migrate": "./bin/migrate.js"
+  },
   "files": [
     "dist/**/*",
-    "src/**/*"
+    "src/**/*",
+    "bin/**/*"
   ],
   "watch": {
     "build:dev": "src"

package/src/core/common/decorators/unified-field.decorator.ts

@@ -1,4 +1,5 @@
 import { Field, FieldOptions } from '@nestjs/graphql';
+import { Prop, PropOptions } from '@nestjs/mongoose';
 import { ApiProperty, ApiPropertyOptions } from '@nestjs/swagger';
 import { EnumAllowedTypes } from '@nestjs/swagger/dist/interfaces/schema-object-metadata.interface';
 import { Type } from 'class-transformer';
@@ -38,6 +39,8 @@ export interface UnifiedFieldOptions {
   isArray?: boolean;
   /** Default: false */
   isOptional?: boolean;
+  /** Whether to apply Mongoose @Prop decorator. Optional, used for database models. Default: false */
+  mongoose?: boolean | PropOptions;
   /** Restricted roles */
   roles?: RestrictedType | RoleEnum | RoleEnum[];
   /** Options for swagger api documentation */
@@ -48,8 +51,12 @@ export interface UnifiedFieldOptions {
    *
    * Enums should be defined via the enum option.
    *
+   * For array fields, you can use either:
+   * - `type: () => ItemType` (recommended, decorator adds array wrapping automatically)
+   * - `type: () => [ItemType]` (also supported, decorator extracts ItemType to avoid double-nesting)
+   *
    * Supports:
-   * - A factory function that returns the type: `() => MyType`
+   * - A factory function that returns the type: `() => MyType` or `() => [MyType]`
    * - A GraphQL scalar: `GraphQLScalarType`
    * - A class constructor: `MyClass`
    * */
@@ -96,7 +103,16 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
       return metadataType;
     };
 
-    const baseType = resolvedTypeFn();
+    // Resolve the type and extract item type if user provided array syntax
+    const resolvedType = resolvedTypeFn();
+
+    // If this is an array field and the user provided type: () => [ItemType],
+    // extract the ItemType to avoid double-nesting (e.g., [[ItemType]])
+    // We check: isArrayField (should be array) && Array.isArray (is actually an array) && length === 1 (GraphQL array syntax)
+    const baseType =
+      isArrayField && Array.isArray(resolvedType) && resolvedType.length === 1
+        ? resolvedType[0] // Extract item type from [ItemType]
+        : resolvedType; // Use as-is
 
     // Prepare merged options
     const gqlOpts: FieldOptions = { ...opts.gqlOptions };
@@ -161,8 +177,14 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
     }
 
     // Type function for gql
+    // We need to keep the factory pattern (calling resolvedTypeFn inside the arrow function)
+    // to support circular references. But we also need to extract array item types to avoid double-nesting.
     const gqlTypeFn = isArrayField
-      ? () => [opts.enum?.enum || opts.gqlType || resolvedTypeFn()]
+      ? () => {
+          const resolved = opts.enum?.enum || opts.gqlType || resolvedTypeFn();
+          // Extract item type if user provided [ItemType] syntax to avoid [[ItemType]]
+          return [Array.isArray(resolved) && resolved.length === 1 ? resolved[0] : resolved];
+        }
       : () => opts.enum?.enum || opts.gqlType || resolvedTypeFn();
 
     // Gql decorator
@@ -178,7 +200,7 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
 
     // Completely skip validation if its any
     if (opts.validator) {
-      opts.validator(valOpts).forEach(d => d(target, propertyKey));
+      opts.validator(valOpts).forEach((d) => d(target, propertyKey));
     } else if (!opts.isAny) {
       const validator = getBuiltInValidator(baseType, valOpts, isArrayField, target);
       if (validator) {
@@ -199,6 +221,23 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
       const rolesArr = Array.isArray(opts.roles) ? opts.roles : [opts.roles];
       Restricted(...rolesArr)(target, propertyKey);
     }
+
+    // Mongoose @Prop decorator (optional)
+    if (opts.mongoose) {
+      const propOptions: any = typeof opts.mongoose === 'object' ? opts.mongoose : {};
+
+      // Set type for Prop if not already defined in propOptions
+      if (typeof propOptions === 'object' && !Array.isArray(propOptions) && !propOptions.type && baseType) {
+        propOptions.type = baseType;
+      }
+
+      // Apply array type if needed
+      if (typeof propOptions === 'object' && !Array.isArray(propOptions) && isArrayField && !propOptions.type) {
+        propOptions.type = [baseType];
+      }
+
+      Prop(propOptions)(target, propertyKey);
+    }
   };
 }
 
@@ -228,12 +267,12 @@ function getBuiltInValidator(
 function isGraphQLScalar(type: any): boolean {
   // CustomScalar check (The CustomScalar interface implements these functions below)
   return (
-    (type
-      && typeof type === 'function'
-      && typeof type.prototype?.serialize === 'function'
-      && typeof type.prototype?.parseValue === 'function'
-      && typeof type.prototype?.parseLiteral === 'function')
-    || type instanceof GraphQLScalarType
+    (type &&
+      typeof type === 'function' &&
+      typeof type.prototype?.serialize === 'function' &&
+      typeof type.prototype?.parseValue === 'function' &&
+      typeof type.prototype?.parseLiteral === 'function') ||
+    type instanceof GraphQLScalarType
   );
 }
 

package/src/core/common/models/core-persistence.model.ts

@@ -1,5 +1,5 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Prop, Schema } from '@nestjs/mongoose';
+import { Schema } from '@nestjs/mongoose';
 import { Types } from 'mongoose';
 
 import { Restricted } from '../decorators/restricted.decorator';
@@ -85,10 +85,10 @@ export abstract class CorePersistenceModel extends CoreModel {
   /**
    * Created date, is set automatically by mongoose
    */
-  @Prop()
   @UnifiedField({
     description: 'Created date',
     isOptional: true,
+    mongoose: true,
     roles: RoleEnum.S_EVERYONE,
     swaggerApiOptions: { example: 1740037703939, format: 'int64', type: Date },
     type: Date,
@@ -98,10 +98,10 @@ export abstract class CorePersistenceModel extends CoreModel {
   /**
    * Updated date is set automatically by mongoose
    */
-  @Prop()
   @UnifiedField({
     description: 'Updated date',
     isOptional: true,
+    mongoose: true,
     roles: RoleEnum.S_EVERYONE,
     swaggerApiOptions: { example: 1740037703939, format: 'int64', type: Date },
     type: Date,

package/src/core/modules/file/core-file-info.model.ts

@@ -1,8 +1,8 @@
-import { Field, ObjectType } from '@nestjs/graphql';
-import { Prop } from '@nestjs/mongoose';
+import { ObjectType } from '@nestjs/graphql';
 import { Types } from 'mongoose';
 
 import { Restricted } from '../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
 import { CoreModel } from '../../common/models/core-model.model';
 
@@ -25,37 +25,55 @@ export class CoreFileInfo extends CoreModel {
   // Properties
   // ===========================================================================
 
-  @Field(() => String, { description: 'ID of the file' })
-  @Restricted(RoleEnum.S_EVERYONE)
+  @UnifiedField({
+    description: 'ID of the file',
+    roles: RoleEnum.S_EVERYONE,
+    type: () => String,
+  })
   id: string = undefined;
 
-  @Field(() => Number, {
+  @UnifiedField({
     description:
-      'The size of each chunk in bytes. GridFS divides the document into chunks of size chunkSize, '
-      + 'except for the last, which is only as large as needed. The default size is 255 kilobytes (kB)',
-    nullable: true,
+      'The size of each chunk in bytes. GridFS divides the document into chunks of size chunkSize, ' +
+      'except for the last, which is only as large as needed. The default size is 255 kilobytes (kB)',
+    isOptional: true,
+    mongoose: { required: false, type: Number },
+    roles: RoleEnum.S_EVERYONE,
+    type: () => Number,
   })
-  @Prop({ required: false, type: Number })
-  @Restricted(RoleEnum.S_EVERYONE)
   chunkSize: number = undefined;
 
-  @Field(() => String, { description: 'Content type', nullable: true })
-  @Prop({ required: false, type: String })
-  @Restricted(RoleEnum.S_EVERYONE)
+  @UnifiedField({
+    description: 'Content type',
+    isOptional: true,
+    mongoose: { required: false, type: String },
+    roles: RoleEnum.S_EVERYONE,
+  })
   contentType?: string = undefined;
 
-  @Field(() => String, { description: 'Name of the file', nullable: true })
-  @Prop({ required: false, type: String })
-  @Restricted(RoleEnum.S_EVERYONE)
+  @UnifiedField({
+    description: 'Name of the file',
+    isOptional: true,
+    mongoose: { required: false, type: String },
+    roles: RoleEnum.S_EVERYONE,
+  })
   filename?: string = undefined;
 
-  @Field(() => Number, { description: 'The size of the document in bytes', nullable: true })
-  @Prop({ required: false, type: Number })
-  @Restricted(RoleEnum.S_EVERYONE)
+  @UnifiedField({
+    description: 'The size of the document in bytes',
+    isOptional: true,
+    mongoose: { required: false, type: Number },
+    roles: RoleEnum.S_EVERYONE,
+    type: () => Number,
+  })
   length: number = undefined;
 
-  @Field(() => Date, { description: 'The date the file was first stored', nullable: true })
-  @Prop({ required: false, type: Date })
-  @Restricted(RoleEnum.S_EVERYONE)
+  @UnifiedField({
+    description: 'The date the file was first stored',
+    isOptional: true,
+    mongoose: { required: false, type: Date },
+    roles: RoleEnum.S_EVERYONE,
+    type: () => Date,
+  })
   uploadDate: Date = undefined;
 }

package/src/core/modules/migrate/MIGRATION_FROM_NODEPIT.md

@@ -0,0 +1,219 @@
+# Migration from @nodepit/migrate-state-store-mongodb
+
+This guide provides step-by-step instructions to migrate from `@nodepit/migrate-state-store-mongodb` to the built-in nest-server migration system.
+
+## Prerequisites
+
+Current state of nest-server-starter projects:
+- Using `@nodepit/migrate-state-store-mongodb` for state storage
+- Using external `migrate` package for CLI
+- Custom migration utilities in `migrations-utils/`
+
+## Migration Steps
+
+### Step 1: Update Dependencies
+
+**File:** `package.json`
+
+Remove old migration packages:
+```bash
+npm uninstall migrate @nodepit/migrate-state-store-mongodb ts-migrate-mongoose
+```
+
+Ensure latest nest-server is installed:
+```bash
+npm install @lenne.tech/nest-server@latest
+```
+
+### Step 2: Update Migration State Store
+
+**File:** `migrations-utils/migrate.js`
+
+**Before:**
+```javascript
+import config from '../src/config.env';
+const migrate = require('migrate');
+const { MongoStateStore } = require('@nodepit/migrate-state-store-mongodb');
+
+const MONGO_URL = config.mongoose.uri;
+const COLLECTION_NAME = 'migrations';
+
+module.exports = class MyMongoStateStore extends MongoStateStore {
+  constructor() {
+    super({ uri: MONGO_URL, collectionName: COLLECTION_NAME });
+  }
+};
+```
+
+**After:**
+```javascript
+const { createMigrationStore } = require('@lenne.tech/nest-server');
+const config = require('../src/config.env');
+
+module.exports = createMigrationStore(
+  config.default.mongoose.uri,
+  'migrations' // optional, default is 'migrations'
+);
+```
+
+### Step 3: Update Database Helper
+
+**File:** `migrations-utils/db.ts`
+
+**Before:**
+```typescript
+import * as fs from 'fs';
+import { GridFSBucket, MongoClient, ObjectId } from 'mongodb';
+import * as path from 'path';
+import config from '../src/config.env';
+
+const MONGO_URL = config.mongoose.uri;
+
+export const getDb = async () => {
+  const client: MongoClient = await MongoClient.connect(MONGO_URL);
+  return client.db();
+};
+
+export const uploadFile = async (
+  relativePath,
+  options?: { bucketName?: string; filename?: string },
+): Promise<ObjectId> => {
+  // ... implementation
+};
+```
+
+**After:**
+```typescript
+import config from '../src/config.env';
+import { getDb as getDbHelper, uploadFileToGridFS } from '@lenne.tech/nest-server';
+import { Db, ObjectId } from 'mongodb';
+
+const MONGO_URL = config.mongoose.uri;
+
+/**
+ * Get database connection
+ */
+export const getDb = async (): Promise<Db> => {
+  return getDbHelper(MONGO_URL);
+};
+
+/**
+ * Upload file to GridFS
+ */
+export const uploadFile = async (
+  relativePath: string,
+  options?: { bucketName?: string; filename?: string }
+): Promise<ObjectId> => {
+  return uploadFileToGridFS(MONGO_URL, relativePath, options);
+};
+```
+
+### Step 4: Verify package.json Scripts
+
+**File:** `package.json`
+
+Scripts should remain unchanged - they will work with the built-in CLI:
+
+```json
+{
+  "scripts": {
+    "migrate:create": "migrate create --template-file ./migrations-utils/template.ts --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\"",
+    "migrate:up": "migrate --store=./migrations-utils/migrate.js --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\" up",
+    "migrate:develop:up": "NODE_ENV=develop migrate --store=./migrations-utils/migrate.js --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\" up",
+    "migrate:test:up": "NODE_ENV=test migrate --store=./migrations-utils/migrate.js --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\" up",
+    "migrate:preview:up": "NODE_ENV=preview migrate --store=./migrations-utils/migrate.js --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\" up",
+    "migrate:prod:up": "NODE_ENV=production migrate --store=./migrations-utils/migrate.js --migrations-dir=\"./migrations\" --compiler=\"ts:./migrations-utils/ts-compiler.js\" up"
+  }
+}
+```
+
+Note: The `migrate` command now comes from `@lenne.tech/nest-server` - no external package needed.
+
+### Step 5: Test Migration
+
+```bash
+# Install dependencies
+npm install
+
+# Test migration creation
+npm run migrate:create -- test-migration
+
+# Test migration execution (if safe in current environment)
+npm run migrate:up
+```
+
+## Verification Checklist
+
+- [ ] `migrate` package removed from package.json
+- [ ] `@nodepit/migrate-state-store-mongodb` removed from package.json
+- [ ] `ts-migrate-mongoose` removed from package.json
+- [ ] `migrations-utils/migrate.js` updated to use `createMigrationStore`
+- [ ] `migrations-utils/db.ts` updated to use nest-server helpers
+- [ ] `npm install` completed successfully
+- [ ] `npm run migrate:create -- test` works
+- [ ] Existing migrations still in database (no data loss)
+
+## What Stays the Same
+
+- ✅ All migration files in `migrations/` folder
+- ✅ All migration data in MongoDB
+- ✅ All npm scripts in package.json
+- ✅ Migration file format (up/down functions)
+- ✅ Template files (if using custom templates)
+
+## What Changes
+
+- ✅ `migrations-utils/migrate.js` - simplified (3 lines)
+- ✅ `migrations-utils/db.ts` - uses nest-server helpers
+- ✅ package.json dependencies - 2-3 packages removed
+- ✅ CLI comes from nest-server instead of external package
+
+## Rollback (if needed)
+
+If you need to rollback:
+
+```bash
+# Reinstall old packages
+npm install --save-dev migrate @nodepit/migrate-state-store-mongodb
+
+# Revert migrations-utils/migrate.js to old version from git
+git checkout migrations-utils/migrate.js
+
+# Revert migrations-utils/db.ts to old version from git
+git checkout migrations-utils/db.ts
+```
+
+## Benefits After Migration
+
+1. **One less dependency** - No external `migrate` package needed
+2. **Simplified code** - ~90% less boilerplate in migrations-utils
+3. **Better TypeScript** - Native TypeScript implementation
+4. **MongoDB 7.x support** - Works with latest MongoDB versions
+5. **Central maintenance** - Updates come with nest-server
+
+## Support
+
+If issues occur during migration:
+- Check that `@lenne.tech/nest-server` is at version 11.3.0 or higher
+- Verify `ts-node` is installed as devDependency
+- Ensure `migrations-utils/migrate.js` exports the state store correctly
+- Test with `migrate --help` to verify CLI is available
+
+## File Structure After Migration
+
+```
+project-root/
+├── migrations/                    # Unchanged
+│   └── TIMESTAMP-*.ts            # Your migrations
+├── migrations-utils/
+│   ├── migrate.js                # Updated (3 lines)
+│   ├── db.ts                     # Updated (uses nest-server helpers)
+│   ├── template.ts               # Unchanged (optional)
+│   └── ts-compiler.js            # Unchanged (optional, can be removed)
+└── package.json                  # Dependencies removed
+```
+
+Note: `ts-compiler.js` can optionally be removed and replaced with:
+```
+--compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+```