@lenne.tech/nest-server 12.0.0 → 12.1.0

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "type": "module",
-  "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).",
+  "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy and an AI assistant.",
   "keywords": [
     "node",
     "nest",
+    "nestjs",
     "server",
     "mongodb",
+    "postgresql",
+    "mysql",
+    "mariadb",
     "graphql",
+    "rest",
+    "multi-tenancy",
     "typescript"
   ],
   "author": "lenne.Tech <info@lenne.tech> (https://lenne.tech)",
@@ -27,14 +33,16 @@
     "check": "node scripts/check.mjs",
     "check:consumer": "node scripts/check-consumer.mjs",
     "check:esm": "node scripts/check-esm-core.mjs",
-    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
+    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:without-mongodb && pnpm run check:server-start",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:mutations": "node scripts/check-mutations.mjs",
-    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
+    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:without-mongodb && pnpm run check:server-start",
     "check:overrides": "node scripts/check-overrides.mjs",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run typecheck:vendor && pnpm run check:esm && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:without-mongodb && pnpm run check:server-start",
     "check:server-start": "cross-env NODE_ENV=local node scripts/check-server-start.mjs --entry=dist/main.js --port-env=NSC__PORT --ready=\"Server starte[dt] at\" --path=/",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
+    "check:without-mongodb": "node scripts/check-without-mongodb.mjs --dist",
+    "check:without-mongodb:package": "node scripts/check-without-mongodb.mjs --package",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && node scripts/open.mjs http://127.0.0.1:8080/ ./public/index.html && compodoc -p tsconfig.json -s",
     "docs:bootstrap": "node extras/update-spectaql-version.mjs && node scripts/run-spectaql.mjs",
@@ -95,16 +103,15 @@
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.2.0",
     "@modelcontextprotocol/sdk": "1.32.2",
-    "@nestjs/apollo": "14.0.3",
-    "@nestjs/common": "12.2.0",
-    "@nestjs/core": "12.2.0",
-    "@nestjs/graphql": "14.0.3",
+    "@nestjs/apollo": "14.1.1",
+    "@nestjs/common": "12.3.2",
+    "@nestjs/core": "12.3.2",
+    "@nestjs/graphql": "14.1.0",
     "@nestjs/jwt": "12.0.3",
-    "@nestjs/mongoose": "12.0.0",
     "@nestjs/passport": "12.0.0",
-    "@nestjs/platform-express": "12.2.0",
+    "@nestjs/platform-express": "12.3.2",
     "@nestjs/schedule": "12.0.2",
-    "@nestjs/swagger": "12.0.4",
+    "@nestjs/swagger": "12.0.5",
     "@nestjs/terminus": "12.1.0",
     "@tus/file-store": "2.1.1",
     "@tus/server": "2.4.6",
@@ -121,14 +128,12 @@
     "graphql": "16.14.2",
     "graphql-query-complexity": "2.0.0",
     "graphql-subscriptions": "3.0.0",
-    "graphql-upload": "15.0.2",
+    "graphql-upload": "17.1.0",
     "graphql-ws": "6.3.0",
     "jose": "6.2.13",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.7.0",
-    "mongoose": "9.11.4",
     "multer": "2.5.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "10.2.1",
@@ -149,11 +154,19 @@
     "@aws-sdk/s3-request-presigner": ">=3.1045.0 <4",
     "@better-auth/core": ">=1.7.12 <1.8.0",
     "@better-auth/passkey": ">=1.7.12 <1.8.0",
+    "@nestjs/mongoose": ">=12.0.0 <13",
     "@swc/core": ">=1.10.0 <2",
     "@tus/s3-store": ">=2.0.5 <3",
     "better-auth": ">=1.7.12 <1.8.0",
     "bullmq": ">=5.16.0 <7",
-    "ioredis": ">=5.0.0 <7"
+    "drizzle-orm": "1.0.0-rc.5",
+    "ioredis": ">=5.0.0 <7",
+    "kysely": ">=0.29.0 <0.30.0",
+    "mongodb": ">=7.7.0 <8",
+    "mongoose": ">=9.11.4 <10",
+    "mysql2": ">=3.24.6 <4",
+    "pg": ">=8.23.0 <9",
+    "typeorm": ">=1.1.0 <2"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -171,6 +184,9 @@
     "@better-auth/passkey": {
       "optional": false
     },
+    "@nestjs/mongoose": {
+      "optional": true
+    },
     "@swc/core": {
       "optional": true
     },
@@ -183,21 +199,43 @@
     "bullmq": {
       "optional": true
     },
+    "drizzle-orm": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
+    },
+    "kysely": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "typeorm": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1156.0",
-    "@aws-sdk/lib-storage": "3.1156.0",
-    "@aws-sdk/s3-request-presigner": "3.1156.0",
-    "@better-auth/core": "1.7.13",
-    "@better-auth/passkey": "1.7.13",
+    "@aws-sdk/client-s3": "3.1158.0",
+    "@aws-sdk/lib-storage": "3.1158.0",
+    "@aws-sdk/s3-request-presigner": "3.1158.0",
+    "@better-auth/core": "1.7.14",
+    "@better-auth/passkey": "1.7.14",
     "@compodoc/compodoc": "2.0.0",
-    "@nestjs/cli": "12.0.10",
-    "@nestjs/schematics": "12.0.10",
-    "@nestjs/testing": "12.2.0",
-    "@swc/cli": "0.8.1",
+    "@nestjs/cli": "12.0.11",
+    "@nestjs/mongoose": "12.0.0",
+    "@nestjs/schematics": "12.0.12",
+    "@nestjs/testing": "12.3.2",
+    "@swc/cli": "0.8.2",
     "@swc/core": "1.16.20",
     "@tus/s3-store": "2.0.9",
     "@types/compression": "1.8.1",
@@ -208,20 +246,28 @@
     "@types/multer": "2.3.0",
     "@types/node": "26.6.5",
     "@types/passport": "1.0.17",
+    "@types/pg": "8.23.1",
     "@vitest/coverage-v8": "5.0.5",
-    "better-auth": "1.7.13",
-    "bullmq": "6.4.2",
+    "better-auth": "1.7.14",
+    "bullmq": "6.5.0",
     "cross-env": "10.1.0",
+    "drizzle-orm": "1.0.0-rc.5",
     "ioredis": "6.0.0",
+    "kysely": "0.29.7",
+    "mongodb": "7.7.0",
+    "mongoose": "9.11.4",
+    "mysql2": "3.24.6",
     "nodemon": "3.1.14",
     "otpauth": "9.5.2",
-    "oxfmt": "0.74.0",
-    "oxlint": "1.89.0",
+    "oxfmt": "0.75.0",
+    "oxlint": "1.90.0",
     "oxlint-tsgolint": "7.0.2005",
+    "pg": "8.23.1",
     "rimraf": "6.1.3",
     "smtp-server": "3.21.1",
     "tsx": "4.23.15",
     "tus-js-client": "4.3.1",
+    "typeorm": "1.1.2",
     "typescript": "6.0.3",
     "unplugin-swc": "2.0.0",
     "vite": "8.3.4",

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

@@ -1,5 +1,6 @@
 import { Field, FieldOptions, HideField, TypeMetadataStorage } from '@nestjs/graphql';
-import { Prop, PropOptions } from '@nestjs/mongoose';
+import type { PropOptions } from '@nestjs/mongoose';
+import { Prop } from '../persistence/mongo/mongoose-compat.js';
 import { ApiHideProperty, ApiProperty, ApiPropertyOptions } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
 import {
@@ -178,6 +179,11 @@ export interface UnifiedFieldOptions {
   isOptional?: boolean;
   /** Whether to apply Mongoose @Prop decorator. Optional, used for database models. Default: false */
   mongoose?: boolean | PropOptions;
+  /**
+   * Previous name of a persisted field. A SQL data store renames the column instead of adding a new, empty one;
+   * MongoDB is not affected (its documents keep the old key until a migration moves it). Needs `mongoose`.
+   */
+  renamedFrom?: string;
   /** Restricted roles */
   roles?: RestrictedType | RoleEnum | RoleEnum[];
   /** Options for swagger api documentation */
@@ -563,6 +569,10 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
         propOptions.type = [baseType];
       }
 
+      if (opts.renamedFrom && typeof propOptions === 'object' && !Array.isArray(propOptions)) {
+        propOptions.renamedFrom = opts.renamedFrom;
+      }
+
       Prop(propOptions)(target, propertyKey);
     }
   };

package/src/core/common/filters/mongoose-cast-error.filter.ts

@@ -8,9 +8,11 @@ import {
   Logger,
   NotFoundException,
 } from '@nestjs/common';
-import { Error as MongooseError } from 'mongoose';
+import type { Error as MongooseError } from 'mongoose';
 
 import { ErrorCode } from '../../modules/error-code/error-codes.js';
+import { optionalMongoPackages } from '../persistence/mongo/mongo-packages.js';
+import { QueryCastError } from '../persistence/sql/sql-errors.js';
 
 import type { GqlContextType } from '@nestjs/graphql';
 import type { Request, Response } from 'express';
@@ -221,7 +223,11 @@ export function classifyGraphQlCastError(value: unknown, args: unknown): CastErr
  * - a `BSONError` from `new Types.ObjectId(bad)` in service code carries no value to classify; such code
  *   should check the id itself (see `CoreFileService.isMalformedFileId()`).
  */
-@Catch(MongooseError.CastError)
+/** A cast failure from either store: Mongoose's `CastError`, or the SQL store's `QueryCastError` (same rules, same fields) */
+export type CastFailure = MongooseError.CastError | QueryCastError;
+
+// Mongoose's CastError only where Mongoose is installed: a project on PostgreSQL alone raises QueryCastError only
+@Catch(...[optionalMongoPackages()?.mongoose.Error.CastError, QueryCastError].filter((type) => !!type))
 export class MongooseCastErrorFilter implements ExceptionFilter {
   protected static readonly logger = new Logger('MongooseCastErrorFilter');
 
@@ -231,7 +237,7 @@ export class MongooseCastErrorFilter implements ExceptionFilter {
    */
   protected static readonly unknownErrorLogger = new Logger('ExceptionsHandler');
 
-  catch(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+  catch(exception: CastFailure, host: ArgumentsHost): HttpException | undefined {
     const type = host.getType<GqlContextType>();
     if (type === 'graphql') {
       return this.catchGraphQl(exception, host);
@@ -247,7 +253,7 @@ export class MongooseCastErrorFilter implements ExceptionFilter {
    * GraphQL: the returned exception becomes the field error. Returning nothing hands the error back to
    * Nest's external exception handler, which logs and rethrows it — what happened before this filter.
    */
-  protected catchGraphQl(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+  protected catchGraphQl(exception: CastFailure, host: ArgumentsHost): HttpException | undefined {
     const origin = classifyGraphQlCastError(exception.value, host.getArgByIndex(1));
     if (origin === 'server') {
       return undefined;
@@ -259,7 +265,7 @@ export class MongooseCastErrorFilter implements ExceptionFilter {
    * REST: a filter that matched must answer the request itself — Nest does not fall back to its own
    * handler afterwards.
    */
-  protected catchHttp(exception: MongooseError.CastError, host: ArgumentsHost): void {
+  protected catchHttp(exception: CastFailure, host: ArgumentsHost): void {
     const ctx = host.switchToHttp();
     const response = ctx.getResponse<Response>();
     const origin = classifyHttpCastError(exception.value, ctx.getRequest<Request>());
@@ -280,7 +286,7 @@ export class MongooseCastErrorFilter implements ExceptionFilter {
    * The client error a request-supplied cast failure is answered with. The Mongoose message stays in
    * the server log (debug level): it names the model, which is none of the client's business.
    */
-  protected toHttpException(exception: MongooseError.CastError, origin: 'identifier' | 'input'): HttpException {
+  protected toHttpException(exception: CastFailure, origin: 'identifier' | 'input'): HttpException {
     MongooseCastErrorFilter.logger.debug(
       `Cast failed on a value from the request (${origin === 'identifier' ? 404 : 400}): ${exception.message}`,
     );

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

@@ -1,13 +1,16 @@
 import { FieldNode, GraphQLResolveInfo, SelectionNode } from 'graphql';
-import { Document, Model, PopulateOptions, Query, Types } from 'mongoose';
+import type { Document, Model, PopulateOptions, Query } from 'mongoose';
 
 import { ResolveSelector } from '../interfaces/resolve-selector.interface.js';
 import { CoreModel } from '../models/core-model.model.js';
+import { isWellFormedId } from '../persistence/id-format.js';
 import { FieldSelection } from '../types/field-selection.type.js';
 import { IdsType } from '../types/ids.type.js';
 import { StringOrObjectId } from '../types/string-or-object-id.type.js';
 import { equalIds, getObjectIds, getStringIds } from './id.helper.js';
 import { removePropertiesDeep } from './input.helper.js';
+import { isMongooseQuery } from '../persistence/mongo/mongoose-compat.js';
+import { isObjectIdLike } from './id.helper.js';
 
 /**
  * The ID helpers moved to `./id.helper` and are re-exported here so every existing import path keeps
@@ -67,10 +70,10 @@ export function addIds(
     if (
       result.length &&
       convert === 'auto' &&
-      ((result[0] instanceof Types.ObjectId && !(ids instanceof Types.ObjectId)) ||
+      ((isObjectIdLike(result[0]) && !isObjectIdLike(ids)) ||
         (typeof result[0] === 'string' && typeof ids !== 'string'))
     ) {
-      const converted = result[0] instanceof Types.ObjectId ? getObjectIds(ids) : getStringIds(ids);
+      const converted = isObjectIdLike(result[0]) ? getObjectIds(ids) : getStringIds(ids);
       result.push(...(converted as any));
     } else {
       // Add ID
@@ -100,7 +103,7 @@ export function checkStringIds(ids: string | string[]): boolean {
   }
   try {
     for (const id of ids) {
-      if (typeof id !== 'string' || id.length !== 24 || !Types.ObjectId.isValid(id)) {
+      if (typeof id !== 'string' || !isWellFormedId(id)) {
         return false;
       }
     }
@@ -310,7 +313,7 @@ export function objectIdsToStrings(element: any, prepared: WeakMap<any, any> = n
   }
 
   // ObjectId to string
-  if (element instanceof Types.ObjectId) {
+  if (isObjectIdLike(element)) {
     return element.toHexString();
   }
 
@@ -339,6 +342,32 @@ export function objectIdsToStrings(element: any, prepared: WeakMap<any, any> = n
 /**
  * Set populates, execute and map result
  */
+/**
+ * A field selection (populate paths, GraphQL selection nodes or resolve info) as populate options — the form both
+ * Mongoose populate and the neutral populate of the SQL store read.
+ */
+export function toPopulateOptions(populate: FieldSelection): PopulateOptions[] {
+  if (!populate) {
+    return [];
+  }
+  if (
+    Array.isArray(populate) &&
+    (typeof (populate as string[])[0] === 'string' || typeof (populate as PopulateOptions[])[0]?.path === 'string')
+  ) {
+    return populate as PopulateOptions[];
+  }
+  if (Array.isArray(populate) && typeof (populate as SelectionNode[])[0]?.kind === 'string') {
+    return getPopulatOptionsFromSelections(populate as SelectionNode[]);
+  }
+  if ((populate as ResolveSelector).info) {
+    return getPopulateOptions((populate as ResolveSelector).info, (populate as ResolveSelector).select);
+  }
+  if (typeof populate === 'string' || (populate as PopulateOptions).path) {
+    return [populate as PopulateOptions];
+  }
+  return [];
+}
+
 export async function popAndMap<T extends CoreModel>(
   queryOrDocument: Document | Document[] | Query<any, any>,
   populate: FieldSelection,
@@ -349,26 +378,12 @@ export async function popAndMap<T extends CoreModel>(
   },
 ): Promise<T | T[]> {
   let result;
-  let populateOptions: PopulateOptions[] = [];
+  const populateOptions = toPopulateOptions(populate);
   const ignoreSelections = options?.ignoreSelections;
-  if (populate) {
-    if (
-      Array.isArray(populate) &&
-      (typeof (populate as string[])[0] === 'string' || typeof (populate as PopulateOptions[])[0]?.path === 'string')
-    ) {
-      populateOptions = populate as PopulateOptions[];
-    } else if (Array.isArray(populate) && typeof (populate as SelectionNode[])[0]?.kind === 'string') {
-      populateOptions = getPopulatOptionsFromSelections(populate as SelectionNode[]);
-    } else if ((populate as ResolveSelector).info) {
-      populateOptions = getPopulateOptions((populate as ResolveSelector).info, (populate as ResolveSelector).select);
-    } else if (typeof populate === 'string' || (populate as PopulateOptions).path) {
-      populateOptions = [populate as PopulateOptions];
-    }
-  }
-  if (queryOrDocument instanceof Query) {
+  if (isMongooseQuery(queryOrDocument)) {
     // Get result
     result = await setPopulates(queryOrDocument, populateOptions, mongooseModel);
-    if (result instanceof Query) {
+    if (isMongooseQuery(result)) {
       result = await result.exec();
     }
 
@@ -473,7 +488,7 @@ export function removeUnresolvedReferences<T = any>(
 
     // populatedOptions is a string — leaf operation, no deep recursion risk
     if (typeof populatedOptions === 'string') {
-      if (!['_id', 'id'].includes(populatedOptions) && populated[populatedOptions] instanceof Types.ObjectId) {
+      if (!['_id', 'id'].includes(populatedOptions) && isObjectIdLike(populated[populatedOptions])) {
         populated[populatedOptions] = null;
       }
       return populated;
@@ -482,7 +497,7 @@ export function removeUnresolvedReferences<T = any>(
     // populatedOptions is a PopulateOptions object
     if (populatedOptions.path) {
       const key = populatedOptions.path;
-      if (!['_id', 'id'].includes(key) && populated[key] instanceof Types.ObjectId) {
+      if (!['_id', 'id'].includes(key) && isObjectIdLike(populated[key])) {
         populated[key] = null;
       } else if (populatedOptions.populate) {
         // Prevent circular reference loops when descending into nested populates
@@ -527,7 +542,7 @@ export async function setPopulates<T = Document | Query<any, any>>(
   }
 
   // Query => Chaining
-  if (queryOrDocument instanceof Query) {
+  if (isMongooseQuery(queryOrDocument)) {
     for (const populateOption of populateOptions) {
       queryOrDocument = (queryOrDocument as any).populate(populateOption);
     }

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

@@ -1,6 +1,6 @@
 import { ExecutionContext } from '@nestjs/common';
 import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
-import { PopulateOptions } from 'mongoose';
+import type { PopulateOptions } from 'mongoose';
 
 import { getPopulateOptions } from './db.helper.js';
 import { removePropertiesDeep } from './input.helper.js';

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

@@ -1,4 +1,5 @@
-import { QueryFilter, QueryOptions } from 'mongoose';
+import type { QueryFilter } from 'mongoose';
+import type { QueryOptions } from 'mongoose';
 
 import { FilterArgs } from '../args/filter.args.js';
 import { ComparisonOperatorEnum } from '../enums/comparison-operator.enum.js';

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

@@ -1,8 +1,8 @@
-import { mongo, Types } from 'mongoose';
+import type { mongo, Types } from 'mongoose';
 import { Readable } from 'stream';
+import { newObjectId } from '../persistence/mongo/mongoose-compat.js';
 
 // Use Mongoose's MongoDB types to avoid BSON version conflicts
-const ObjectId = Types.ObjectId;
 
 /**
  * GridFS File Info interface matching the structure from GridFS
@@ -166,7 +166,7 @@ export class GridFSHelper {
       let downloadStream: GridFSBucketReadStream;
 
       if (options._id) {
-        const objectId = typeof options._id === 'string' ? new ObjectId(options._id) : options._id;
+        const objectId = typeof options._id === 'string' ? newObjectId(options._id) : options._id;
         downloadStream = bucket.openDownloadStream(objectId);
       } else if (options.filename) {
         downloadStream = bucket.openDownloadStreamByName(options.filename);
@@ -191,8 +191,15 @@ export class GridFSHelper {
   /**
    * Find file metadata by ID
    */
-  static async findFileById(bucket: GridFSBucket, id: string | Types.ObjectId): Promise<GridFSFileInfo | null> {
-    const objectId = typeof id === 'string' ? new ObjectId(id) : id;
+  static async findFileById(
+    bucket: GridFSBucket | undefined,
+    id: string | Types.ObjectId,
+  ): Promise<GridFSFileInfo | null> {
+    // No bucket without MongoDB: a GridFS read finds nothing there, as for an empty bucket
+    if (!bucket) {
+      return null;
+    }
+    const objectId = typeof id === 'string' ? newObjectId(id) : id;
     const files = await bucket.find({ _id: objectId }).toArray();
     return files.length > 0 ? GridFSHelper.normalizeFileInfo(files[0]) : null;
   }
@@ -213,7 +220,11 @@ export class GridFSHelper {
    * and only corrects the document describing them. `_id` breaks the tie, so two files written in
    * the same millisecond still order totally.
    */
-  static async findFileByName(bucket: GridFSBucket, filename: string): Promise<GridFSFileInfo | null> {
+  static async findFileByName(bucket: GridFSBucket | undefined, filename: string): Promise<GridFSFileInfo | null> {
+    // No bucket without MongoDB: a GridFS read finds nothing there, as for an empty bucket
+    if (!bucket) {
+      return null;
+    }
     // `uploadDate` FIRST: MongoDB applies sort keys in document order, so leading with `_id` would
     // make the tie-break the primary key and could disagree with the driver's own by-name revision
     // order (which sorts on `uploadDate` alone).
@@ -237,7 +248,15 @@ export class GridFSHelper {
    * pre-switch files on any other. That is exactly the "switching drivers is
    * forward-only, no migration" promise failing for one field.
    */
-  static async findFiles(bucket: GridFSBucket, filter: any = {}, options: any = {}): Promise<GridFSFileInfo[]> {
+  static async findFiles(
+    bucket: GridFSBucket | undefined,
+    filter: any = {},
+    options: any = {},
+  ): Promise<GridFSFileInfo[]> {
+    // No bucket without MongoDB: a GridFS read finds nothing there, as for an empty bucket
+    if (!bucket) {
+      return [];
+    }
     const query = GridFSHelper.mapContentTypeKeys(filter);
     const findOptions =
       options && options.sort ? { ...options, sort: GridFSHelper.mapContentTypeKeys(options.sort) } : options;
@@ -274,7 +293,7 @@ export class GridFSHelper {
    * Delete a file from GridFS
    */
   static async deleteFile(bucket: GridFSBucket, id: string | Types.ObjectId): Promise<void> {
-    const objectId = typeof id === 'string' ? new ObjectId(id) : id;
+    const objectId = typeof id === 'string' ? newObjectId(id) : id;
     await bucket.delete(objectId);
   }
 
@@ -282,7 +301,7 @@ export class GridFSHelper {
    * Open download stream by ID
    */
   static openDownloadStream(bucket: GridFSBucket, id: string | Types.ObjectId): GridFSBucketReadStream {
-    const objectId = typeof id === 'string' ? new ObjectId(id) : id;
+    const objectId = typeof id === 'string' ? newObjectId(id) : id;
     return bucket.openDownloadStream(objectId);
   }
 

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

@@ -29,9 +29,23 @@
  * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
  */
 import _ from 'lodash';
-import { Types } from 'mongoose';
+import type { Types } from 'mongoose';
 
 import { IdsType } from '../types/ids.type.js';
+import { newObjectId } from '../persistence/mongo/mongoose-compat.js';
+
+/**
+ * Whether a value is an ObjectId, recognised by bson's own type tag instead of by class identity, so
+ * an ObjectId from a second installed copy of bson counts too. A mongoose `Types.ObjectId` is one.
+ */
+export function isObjectIdLike(value: unknown): value is { toHexString(): string } {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    (value as { _bsontype?: unknown })._bsontype === 'ObjectId' &&
+    typeof (value as { toHexString?: unknown }).toHexString === 'function'
+  );
+}
 
 /**
  * Checks if all IDs are equal
@@ -96,9 +110,9 @@ export function getObjectIds(ids: any[]): Types.ObjectId[];
 export function getObjectIds(ids: any): Types.ObjectId;
 export function getObjectIds<T extends any | any[]>(ids: T): Types.ObjectId | Types.ObjectId[] {
   if (Array.isArray(ids)) {
-    return ids.map((id) => new Types.ObjectId(getStringId(id)));
+    return ids.map((id) => newObjectId(getStringId(id)));
   }
-  return new Types.ObjectId(getStringId(ids));
+  return newObjectId(getStringId(ids));
 }
 
 /**
@@ -175,7 +189,10 @@ function getStringId(element: any): string {
 
   // Object handling
   if (typeof element === 'object') {
-    if (element instanceof Types.ObjectId) {
+    // By bson type tag rather than `instanceof Types.ObjectId`: an ObjectId from another bson copy
+    // fails `instanceof`, and its `id` bytes are a plain Uint8Array outside Node — the branch below
+    // would then stringify the bytes ("101,31,0,…") instead of returning the hex id.
+    if (isObjectIdLike(element)) {
       return element.toHexString();
     }
 

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

@@ -1,6 +1,5 @@
-import { Types } from 'mongoose';
-
 import { clone, plainToInstanceClean } from './input.helper.js';
+import { isObjectIdLike } from './id.helper.js';
 
 /**
  * Helper class for models
@@ -135,7 +134,7 @@ export function mapClasses<T = Record<string, any>>(
         for (const item of value) {
           if (item instanceof targetClass) {
             arr.push(item);
-          } else if (item instanceof Types.ObjectId) {
+          } else if (isObjectIdLike(item)) {
             config.objectIdsToString ? arr.push(item.toHexString()) : arr.push(item);
           } else if (typeof item === 'object') {
             if (targetClass.map) {
@@ -150,7 +149,7 @@ export function mapClasses<T = Record<string, any>>(
         target[prop] = arr as any;
 
         // Process ObjectId
-      } else if (value instanceof Types.ObjectId) {
+      } else if (isObjectIdLike(value)) {
         target[prop] = config.objectIdsToString ? value.toHexString() : value;
 
         // Process object
@@ -222,7 +221,7 @@ export async function mapClassesAsync<T = Record<string, any>>(
         for (const item of value) {
           if (item instanceof targetClass) {
             arr.push(item);
-          } else if (item instanceof Types.ObjectId) {
+          } else if (isObjectIdLike(item)) {
             config.objectIdsToString ? arr.push(item.toHexString()) : arr.push(item);
           } else if (typeof item === 'object') {
             if (targetClass.map) {
@@ -237,7 +236,7 @@ export async function mapClassesAsync<T = Record<string, any>>(
         target[prop] = arr as any;
 
         // Process ObjectId
-      } else if (value instanceof Types.ObjectId) {
+      } else if (isObjectIdLike(value)) {
         target[prop] = config.objectIdsToString ? value.toHexString() : value;
 
         // Process object

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

@@ -1,7 +1,6 @@
 import bcrypt from 'bcrypt';
 import { sha256 } from 'js-sha256';
 import _ from 'lodash';
-import { Types } from 'mongoose';
 
 import { RoleEnum } from '../enums/role.enum.js';
 import { accessDeniedException } from '../exceptions/access-denied.exception.js';
@@ -12,6 +11,7 @@ import { ServiceOptions } from '../interfaces/service-options.interface.js';
 import { ConfigService } from '../services/config.service.js';
 import { getStringIds } from './db.helper.js';
 import { clone, plainToInstanceClean, processDeep } from './input.helper.js';
+import { isObjectIdLike } from './id.helper.js';
 
 // Secret field names for recursive removal in prepareOutput — allocated once, never change.
 // Only fields that are NEVER needed internally (hashed passwords, one-time tokens).
@@ -136,7 +136,7 @@ export async function prepareInput<T = any>(
     input = processDeep(
       input,
       (property) => {
-        if (property instanceof Types.ObjectId) {
+        if (isObjectIdLike(property)) {
           property = getStringIds(property);
         }
         return property;
@@ -272,7 +272,7 @@ export async function prepareOutput<T = { [key: string]: any; map: (...args: any
     output = processDeep(
       output,
       (property) => {
-        if (doObjectIds && property instanceof Types.ObjectId) {
+        if (doObjectIds && isObjectIdLike(property)) {
           return property.toHexString();
         }
         if (doSecrets && property && typeof property === 'object' && !Array.isArray(property)) {