@lenne.tech/nest-server 11.43.3 → 12.1.0

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 { ResolveSelector } from '../interfaces/resolve-selector.interface';
-import { CoreModel } from '../models/core-model.model';
-import { FieldSelection } from '../types/field-selection.type';
-import { IdsType } from '../types/ids.type';
-import { StringOrObjectId } from '../types/string-or-object-id.type';
-import { equalIds, getObjectIds, getStringIds } from './id.helper';
-import { removePropertiesDeep } from './input.helper';
+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
@@ -17,7 +20,7 @@ import { removePropertiesDeep } from './input.helper';
  * line away from an SWC temporal-dead-zone crash. `id.helper` imports no framework code, so it can
  * never be part of a cycle. Do NOT move them back.
  */
-export { equalIds, getIncludedIds, getObjectIds, getStringIds } from './id.helper';
+export { equalIds, getIncludedIds, getObjectIds, getStringIds } from './id.helper.js';
 
 // =====================================================================================================================
 // Export functions
@@ -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,9 +1,9 @@
 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';
-import { removePropertiesDeep } from './input.helper';
+import { getPopulateOptions } from './db.helper.js';
+import { removePropertiesDeep } from './input.helper.js';
 
 /**
  * Decorator function to get current user for Controller (http context) and Resolver (graphql context)

package/src/core/common/helpers/execution-context-request.helper.ts

@@ -85,8 +85,8 @@ export function resolveGuardRequest(
   }
 
   if (isSubscriptionContext(gqlContext)) {
-    // Normalize the two names the transports use, so a guard reads `headers` unconditionally:
-    // `graphql-ws` gets them from CoreModule's onConnect, `subscriptions-transport-ws` from its own,
+    // Normalize the names a context may carry, so a guard reads `headers` unconditionally:
+    // `graphql-ws` gets them from CoreModule's onConnect, a custom onConnect may set `headers` itself,
     // and the raw upgrade request is the fallback for a custom onConnect that forwards neither.
     if (!gqlContext.headers) {
       gqlContext.headers = gqlContext.connectionParams ?? gqlContext.request?.headers ?? {};

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

@@ -5,7 +5,7 @@ import { diskStorage, memoryStorage } from 'multer';
 import { extname } from 'path';
 import { Readable } from 'stream';
 
-import type { FileUploadSource } from '../../modules/file/interfaces/file-upload.interface';
+import type { FileUploadSource } from '../../modules/file/interfaces/file-upload.interface.js';
 
 /**
  * What an upload endpoint accepts: exact mimetypes and exact file extensions.

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

@@ -1,14 +1,15 @@
-import { QueryFilter, QueryOptions } from 'mongoose';
-
-import { FilterArgs } from '../args/filter.args';
-import { ComparisonOperatorEnum } from '../enums/comparison-operator.enum';
-import { LogicalOperatorEnum } from '../enums/logical-operator.enum';
-import { SortOrderEnum } from '../enums/sort-order.emum';
-import { FilterInput } from '../inputs/filter.input';
-import { SortInput } from '../inputs/sort.input';
-import { ConfigService } from '../services/config.service';
-import { checkStringIds, getObjectIds } from './db.helper';
-import { assignPlain, clone } from './input.helper';
+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';
+import { LogicalOperatorEnum } from '../enums/logical-operator.enum.js';
+import { SortOrderEnum } from '../enums/sort-order.emum.js';
+import { FilterInput } from '../inputs/filter.input.js';
+import { SortInput } from '../inputs/sort.input.js';
+import { ConfigService } from '../services/config.service.js';
+import { checkStringIds, getObjectIds } from './db.helper.js';
+import { assignPlain, clone } from './input.helper.js';
 
 /**
  * Helper for filter handling

package/src/core/common/helpers/graceful-shutdown.helper.ts

@@ -1,6 +1,6 @@
 import { INestApplication, Logger } from '@nestjs/common';
 
-import { ConfigService } from '../services/config.service';
+import { ConfigService } from '../services/config.service.js';
 
 /** Signals an orchestrator uses to ask a container to stop */
 const SHUTDOWN_SIGNALS: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];

package/src/core/common/helpers/graphql-ws-connection.helper.ts

@@ -1,7 +1,7 @@
 import { Logger } from '@nestjs/common';
 
-import { ConfigService } from '../services/config.service';
-import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry';
+import { ConfigService } from '../services/config.service.js';
+import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry.js';
 
 /**
  * The authorization lifecycle of an OPEN GraphQL WebSocket connection.
@@ -41,6 +41,30 @@ import { getTenantContextResolver, ResolvedTenantContext } from '../services/cor
  */
 export const WS_AUTHORIZATION_CHANGED_CLOSE_CODE = 4403;
 
+/**
+ * Close code for a handshake whose credential does not authenticate: graphql-ws's `CloseCode.Unauthorized`.
+ * Unlike 4403 its client does NOT retry it — the same credential would only be refused again.
+ */
+export const WS_UNAUTHORIZED_CLOSE_CODE = 4401;
+
+/**
+ * Refuse a graphql-ws handshake from `onConnect` because its credential does not authenticate. Returns
+ * `false`, which `onConnect` must return.
+ *
+ * graphql-ws offers two ways to refuse, and neither fits: returning `false` closes with 4403, which its
+ * client retries — with the same refused credential, again and again — and throwing makes its ws adapter
+ * log "Internal error occurred during message handling. Please check your implementation." and close
+ * with 4500, a SERVER error for a client's expired token. Until 12.0.0 `onConnect` threw, so every
+ * expired token printed that line with a stack trace, in production too. Closing with 4401 first turns
+ * the close graphql-ws issues after a `false` into a no-op on a socket that is already closing.
+ *
+ * Without a socket (a transport that hands none to `onConnect`) the `false` alone refuses, with 4403.
+ */
+export function refuseWsHandshake(socket: IWsConnectionSocket | undefined, reason = 'Unauthorized'): false {
+  socket?.close(WS_UNAUTHORIZED_CLOSE_CODE, reason);
+  return false;
+}
+
 /** Default for `graphQl.subscriptionRevalidationMs`. */
 export const DEFAULT_SUBSCRIPTION_REVALIDATION_MS = 30_000;
 
@@ -53,8 +77,8 @@ export interface IWsConnectionSocket {
 export interface IWsConnectionRegistration {
   /**
    * The object every operation of the connection receives as its GraphQL context: `extra` for
-   * graphql-ws, the object `onConnect` returns for subscriptions-transport-ws (which copies it per
-   * operation — the registration survives that copy).
+   * graphql-ws, or whatever object a project's own transport hands each operation — the registration
+   * survives a shallow per-operation copy of it.
    */
   carrier: object;
 
@@ -106,8 +130,9 @@ export interface WsConnection {
 /**
  * Module-private and not `Symbol.for()`: nothing a client sends — `connectionParams` are JSON — can
  * produce it, so a registration cannot be forged or overwritten from outside. Enumerable on purpose:
- * subscriptions-transport-ws hands each operation an `Object.assign` copy of the connection context,
- * and only enumerable own properties survive that.
+ * a transport that hands each operation an `Object.assign` copy of the connection context (as
+ * subscriptions-transport-ws did until `@nestjs/graphql` 14 removed it) keeps only enumerable own
+ * properties.
  */
 const WS_CONNECTION = Symbol('ltWsConnection');
 

package/src/core/common/helpers/graphql-ws-context.helper.ts

@@ -3,17 +3,17 @@
 // to a second copy of the module (a bundler's interop namespace, or a duplicated install), and the
 // wrapper would then reject the very schema it was handed. The repo already uses this form for
 // `graphql-upload` and `lodash` for the same reason.
-import graphql = require('graphql');
+import * as graphql from 'graphql';
 
-import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry';
-import { IRequestContext, RequestContext } from '../services/request-context.service';
+import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry.js';
+import { IRequestContext, RequestContext } from '../services/request-context.service.js';
 import {
   ensureWsConnectionCurrent,
   getWsConnection,
   noteWsConnectionTenant,
   readWsTenantHeader,
   WsConnection,
-} from './graphql-ws-connection.helper';
+} from './graphql-ws-connection.helper.js';
 
 /**
  * A `RequestContext` for GraphQL operations that arrive over a WEBSOCKET.
@@ -33,8 +33,8 @@ import {
  * schema is touched without a tenant) never fired, because there was no context to notice.
  *
  * WHERE IT HOOKS IN: `GqlSubscriptionService` reads `execute` and `subscribe` off the GraphQL module
- * options and hands them to BOTH WebSocket transports (`graphql-ws` and `subscriptions-transport-ws`),
- * defaulting to graphql-js's own. Those two functions are the only place where the whole WS operation
+ * options and hands them to the graphql-ws server — the only WebSocket transport since
+ * `@nestjs/graphql` 14 removed `subscriptions-transport-ws` — defaulting to graphql-js's own. Those two functions are the only place where the whole WS operation
  * — including every field resolver and the `resolve`/`filter` callbacks of a subscription — is
  * reachable as one call. HTTP does not go through them (Apollo runs its own pipeline), so wrapping
  * them touches the WS path only.
@@ -64,11 +64,10 @@ type ExecuteFn = (args: GraphQlArgs) => any;
 /**
  * Read the tenant header out of whatever the transport left on the context.
  *
- * Both WS transports are covered, and the reason there are three sources is that they genuinely
- * differ: `graphql-ws` gets `extra.headers` from `CoreModule`'s `onConnect` (the client's
- * `connectionParams`), `subscriptions-transport-ws` returns `{ headers }` from its own `onConnect`,
- * and the raw upgrade request is the fallback for a project with a custom `onConnect` that forwards
- * neither. Header names are matched case-insensitively — `connectionParams` are client-supplied JSON
+ * There are three sources because the shapes genuinely differ: `graphql-ws` gets `extra.headers`
+ * from `CoreModule`'s `onConnect` (the client's `connectionParams`), a project's own `onConnect` may
+ * return `{ headers }` (the shape `subscriptions-transport-ws` used until `@nestjs/graphql` 14 removed
+ * it), and the raw upgrade request is the fallback for a custom `onConnect` that forwards neither. Header names are matched case-insensitively — `connectionParams` are client-supplied JSON
  * and arrive with whatever casing the client used, unlike Node's lower-cased HTTP headers.
  *
  * Lives in `graphql-ws-connection.helper.ts`, because a connection's re-check has to resolve the

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

@@ -12,7 +12,7 @@ import {
   ValueNode,
   VariableNode,
 } from 'graphql';
-import _ = require('lodash');
+import _ from 'lodash';
 
 /**
  * Interface for GraphQLFieldsConfig

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

@@ -28,10 +28,24 @@
  * `db.helper` re-exports all four public functions, so every existing import path keeps working.
  * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
  */
-import _ = require('lodash');
-import { Types } from 'mongoose';
+import _ from 'lodash';
+import type { Types } from 'mongoose';
 
-import { IdsType } from '../types/ids.type';
+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/input.helper.ts

@@ -1,17 +1,17 @@
 import { BadRequestException, ForbiddenException } from '@nestjs/common';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
-import { ValidatorOptions } from 'class-validator/types/validation/ValidatorOptions';
-import { Kind } from 'graphql/index';
+import type { ValidatorOptions } from 'class-validator';
+import { Kind } from 'graphql';
 
-import { checkRestricted } from '../decorators/restricted.decorator';
-import { ProcessType } from '../enums/process-type.enum';
-import { RoleEnum } from '../enums/role.enum';
-import { accessDeniedException } from '../exceptions/access-denied.exception';
-import { ErrorCode } from '../../modules/error-code/error-codes';
-import { clone } from './clone.helper';
-import { merge } from './config.helper';
-import { equalIds } from './id.helper';
+import { checkRestricted } from '../decorators/restricted.decorator.js';
+import { ProcessType } from '../enums/process-type.enum.js';
+import { RoleEnum } from '../enums/role.enum.js';
+import { accessDeniedException } from '../exceptions/access-denied.exception.js';
+import { ErrorCode } from '../../modules/error-code/error-codes.js';
+import { clone } from './clone.helper.js';
+import { merge } from './config.helper.js';
+import { equalIds } from './id.helper.js';
 
 /**
  * `clone` and `deepFreeze` moved to `./clone.helper` and are re-exported here so every existing
@@ -21,7 +21,7 @@ import { equalIds } from './id.helper';
  * that is one top-level line away from an SWC temporal-dead-zone crash. `clone.helper` imports no
  * framework code, so it can never be part of a cycle. Do NOT move them back.
  */
-export { clone, deepFreeze } from './clone.helper';
+export { clone, deepFreeze } from './clone.helper.js';
 
 /**
  * Helper class for inputs

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

@@ -1,8 +1,8 @@
 import { ExecutionContext } from '@nestjs/common';
-import { GqlExecutionContext } from '@nestjs/graphql';
+import { GqlExecutionContext, TypeMetadataStorage } from '@nestjs/graphql';
 
-import { RESPONSE_MODEL_KEY } from '../decorators/response-model.decorator';
-import { CoreModel } from '../models/core-model.model';
+import { RESPONSE_MODEL_KEY } from '../decorators/response-model.decorator.js';
+import { CoreModel } from '../models/core-model.model.js';
 
 // Cache: handler function → resolved model class (or null)
 // Handler references are stable per route, so the cache is bounded by the number of routes.
@@ -66,12 +66,9 @@ function resolveResponseModelClassUncached(
  */
 function resolveFromGraphQlMetadata(context: ExecutionContext): (new (...args: any[]) => CoreModel) | null {
   try {
-    // Uses @nestjs/graphql internal path to access TypeMetadataStorage — the only way to resolve
-    // @Query/@Mutation return types at runtime. This path has been stable since @nestjs/graphql v10.
-    // Wrapped in try/catch so a path change in a future version degrades gracefully (returns null).
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { TypeMetadataStorage } = require('@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage.js');
-
+    // TypeMetadataStorage from the package root (public export, the same instance the deep
+    // `dist/schema-builder/storages/type-metadata.storage.js` path held — that one existed only for `require()`).
+    // Wrapped in try/catch so a shape change in a future version degrades gracefully (returns null).
     const handler = context.getHandler();
     const target = context.getClass();
     const methodName = handler.name;

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

@@ -1,6 +1,5 @@
-import { Types } from 'mongoose';
-
-import { clone, plainToInstanceClean } from './input.helper';
+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/module-location.helper.ts

@@ -0,0 +1,33 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Directory of the file that calls this function — the replacement for `__dirname` in the core.
+ *
+ * The core's source must be valid as CommonJS (this package, CommonJS projects) AND as ESM (ESM projects that
+ * vendor it). `__dirname` exists only in CommonJS, `import.meta.dirname` only in ESM, and `tsc` refuses
+ * `import.meta` in a file it emits as CommonJS (TS1470) — so neither can be written in source that has to be
+ * both. V8 knows the calling file either way: as a path (CommonJS, and a TypeScript source run) or as a `file:`
+ * URL (ESM).
+ *
+ * Call it synchronously from the module whose location you need — after an `await` the caller's frame is gone.
+ *
+ * @param depth how many further frames up to go: 0 = the caller, 1 = the caller's caller (for a helper that
+ *   resolves paths on behalf of whoever called IT)
+ */
+export function callerDirectory(depth = 0): string {
+  const original = Error.prepareStackTrace;
+  let file: null | string | undefined;
+  try {
+    Error.prepareStackTrace = (_error, frames) => frames;
+    const holder: { stack?: unknown } = {};
+    Error.captureStackTrace(holder, callerDirectory);
+    file = (holder.stack as NodeJS.CallSite[] | undefined)?.[depth]?.getFileName();
+  } finally {
+    Error.prepareStackTrace = original;
+  }
+  if (!file) {
+    throw new Error(`callerDirectory(): no calling file at depth ${depth}`);
+  }
+  return dirname(file.startsWith('file:') ? fileURLToPath(file) : file);
+}

package/src/core/common/helpers/outbound-url.helper.ts

@@ -2,8 +2,8 @@ import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
 import { BlockList, isIP } from 'node:net';
 import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
 
-import { ConfigService } from '../services/config.service';
-import { isLocalEnv } from './cookies.helper';
+import { ConfigService } from '../services/config.service.js';
+import { isLocalEnv } from './cookies.helper.js';
 
 /**
  * Requests to a URL a USER entered — a webhook, an export target, an ERP address.