@lenne.tech/nest-server 11.43.3 → 12.1.0

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

@@ -2,14 +2,13 @@ import { ApolloDriverConfig } from '@nestjs/apollo';
 import { Type } from '@nestjs/common';
 import { GqlModuleAsyncOptions } from '@nestjs/graphql';
 import { JwtModuleOptions } from '@nestjs/jwt';
-import type { JwtSignOptions } from '@nestjs/jwt/dist/interfaces/index.js';
-import { MongooseModuleOptions } from '@nestjs/mongoose';
+import type { JwtSignOptions } from '@nestjs/jwt';
+import type { MongooseModuleOptions } from '@nestjs/mongoose';
 import { ServeStaticOptions } from '@nestjs/platform-express/interfaces/serve-static-options.interface';
 import { CronExpression } from '@nestjs/schedule';
-import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health.js';
-import type { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type.js';
+import type { DiskHealthIndicatorOptions, MongoosePingCheckSettings } from '@nestjs/terminus';
 import compression from 'compression';
-import { CollationOptions } from 'mongodb';
+import type { CollationOptions } from 'mongodb';
 import type { Connection } from 'mongoose';
 import type * as JSONTransport from 'nodemailer/lib/json-transport';
 import type * as SendmailTransport from 'nodemailer/lib/sendmail-transport';
@@ -18,12 +17,13 @@ import type * as SMTPPool from 'nodemailer/lib/smtp-pool';
 import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 import type * as StreamTransport from 'nodemailer/lib/stream-transport';
 
-import { Falsy } from '../types/falsy.type';
-import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface';
-import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface';
-import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface';
-import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
-import { MailjetOptions } from './mailjet-options.interface';
+import type { DataStore } from '../persistence/data-store.interface.js';
+import { Falsy } from '../types/falsy.type.js';
+import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface.js';
+import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface.js';
+import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface.js';
+import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface.js';
+import { MailjetOptions } from './mailjet-options.interface.js';
 
 /**
  * Better-Auth field type definition
@@ -800,8 +800,9 @@ export interface IBetterAuthPasskeyConfig {
   userVerification?: 'discouraged' | 'preferred' | 'required';
 
   /**
-   * Custom cookie name for WebAuthn challenge storage.
-   * Only used when challengeStorage is 'cookie'.
+   * Key of Better-Auth's WebAuthn challenge cookie. Better-Auth puts its cookie prefix in front of it
+   * (`iam.better-auth-passkey` by default); with database challenge storage the server reads the token from that
+   * cookie and maps it to the `challengeId` it returns instead.
    * @default 'better-auth-passkey'
    */
   webAuthnChallengeCookie?: string;
@@ -1263,8 +1264,10 @@ export interface IFileConfig {
    *
    * **Left unset, it is derived**, most capable first:
    * 1. `'s3'` when `s3.bucket` is configured
-   * 2. `'gridfs'` when a database is configured
-   * 3. `'filesystem'` when neither is
+   * 2. `'filesystem'` when `database` routes the file metadata to a SQL source — GridFS would put bytes and
+   *    metadata into MongoDB. Pod-local: mount `storageDir` as a volume, or configure `s3`
+   * 3. `'gridfs'` when a database is configured
+   * 4. `'filesystem'` when none is
    *
    * A configured-but-unreachable database is an error in its own right (Mongoose
    * fails the boot), never a reason to fall through to the disk.
@@ -1546,7 +1549,10 @@ export interface IMultiTenancy {
    *
    * Return `false` for an inactive tenant; any other value (including `undefined`) counts as active.
    * `context.connection` is the main database connection, for a lookup in the project's own tenant
-   * collection. Answers are cached for {@link cacheTtlMs}; after switching a tenant on or off, call
+   * collection; `context.store(modelName)` is the database-neutral alternative for a tenant model registered with
+   * `CorePersistenceModule.forFeature()`, and the one that works when that model is stored in a SQL database. It
+   * throws for a model not registered that way, so a misnamed or missing tenant model refuses the request rather than
+   * counting every tenant as active. Answers are cached for {@link cacheTtlMs}; after switching a tenant on or off, call
    * `CoreTenantGuard.invalidateTenant(tenantId)` (broadcast to every replica when Redis is
    * configured). A function cannot arrive through `NSC__*` / `NEST_SERVER_CONFIG` — set it in
    * `config.env.ts`.
@@ -1554,15 +1560,30 @@ export interface IMultiTenancy {
    * @example
    * ```typescript
    * multiTenancy: {
-   *   isTenantActive: async (tenantId, { connection }) =>
-   *     (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+   *   // Any database: the tenant model registered with CorePersistenceModule.forFeature()
+   *   isTenantActive: async (tenantId, { store }) => (await store('Tenant').findById(tenantId))?.active !== false,
+   *   // MongoDB only
+   *   // isTenantActive: async (tenantId, { connection }) =>
+   *   //   (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
    * }
    * ```
    *
    * @default undefined (every tenant is active)
    * @since 11.42.0
    */
-  isTenantActive?: (tenantId: string, context: { connection: Connection }) => boolean | Promise<boolean>;
+  isTenantActive?: (
+    tenantId: string,
+    context: {
+      connection: Connection;
+      /**
+       * The data store of a model registered with `CorePersistenceModule.forFeature()` — the database-neutral lookup,
+       * also when the tenant model lives in a SQL database (`connection` reaches MongoDB only). Throws a
+       * `DataSourceConfigError` for a model that is not registered that way: an `undefined` here would read as
+       * "active" in a hook written with `?.`, and open every deactivated tenant.
+       */
+      store: (modelName: string) => DataStore<any>;
+    },
+  ) => boolean | Promise<boolean>;
 }
 
 /**
@@ -2152,6 +2173,73 @@ export interface IAi {
   systemPrompt?: string;
 }
 
+/**
+ * Library that executes the framework's SQL on a SQL data source. The framework compiles every query,
+ * policy and schema change itself, so the engine decides only what projects use for native queries —
+ * switching it on the same database is a configuration change.
+ */
+export type DatabaseSqlEngine = 'drizzle' | 'kysely' | 'typeorm';
+
+/**
+ * One data source: a connection URL plus, for SQL databases, the engine.
+ */
+export interface IDatabaseSourceConfig {
+  /**
+   * Connection URL of the role that OWNS the tables — used only to bring the schema up to date at boot, never for
+   * requests. Only valid on SQL URLs. Without it the application role only verifies the schema and the boot stops
+   * while changes are pending (plan §3.9: the application role owns nothing, so row-level security binds it).
+   */
+  ownerUrl?: string;
+
+  /**
+   * SQL engine for this source. Only valid on SQL URLs.
+   * @default the top-level `sqlEngine`, else 'typeorm'
+   */
+  sqlEngine?: DatabaseSqlEngine;
+
+  /**
+   * Connection URL. The scheme selects the database: `mongodb://`, `mongodb+srv://`, `postgres://`,
+   * `postgresql://`, `mysql://`, `mariadb://`.
+   */
+  url: string;
+}
+
+/**
+ * Data sources and which model is stored where.
+ *
+ * One default source serves every model; `sources` adds further ones and `models` lists the exceptions.
+ * A model may also name its source in code with `@PersistedModel({ dataSource })`; the configuration
+ * wins, so operations can move a model without a code change.
+ */
+export interface IDatabaseConfig {
+  /**
+   * Model name → source name, for the models that do not use the default source.
+   */
+  models?: Record<string, string>;
+
+  /**
+   * Owner connection of the default source (see `IDatabaseSourceConfig.ownerUrl`). Needs `url` beside it: an
+   * `NSC__DATABASE__OWNER_URL` replaces a `database` given as a URL string, so the boot refuses `ownerUrl` alone.
+   */
+  ownerUrl?: string;
+
+  /**
+   * Further sources by name, each a URL or a source configuration. The name `default` is reserved.
+   */
+  sources?: Record<string, IDatabaseSourceConfig | string>;
+
+  /**
+   * SQL engine for every SQL source that does not set its own.
+   * @default 'typeorm'
+   */
+  sqlEngine?: DatabaseSqlEngine;
+
+  /**
+   * URL of the default source. Without it, the `mongoose` configuration stays the default source.
+   */
+  url?: string;
+}
+
 /**
  * Options for the server
  */
@@ -2498,6 +2586,25 @@ export interface IServerOptions {
     CronExpression | CronJobConfigWithTimeZone | CronJobConfigWithUtcOffset | Date | Falsy | string
   >;
 
+  /**
+   * Data sources: where models are stored.
+   *
+   * - absent: the `mongoose` configuration is the only data source — exactly as before
+   * - a URL (`'postgres://…'`): that database is the default source for every model
+   * - an object: a default source plus further `sources` and per-model exceptions (`models`)
+   * - `false`: no database at all
+   *
+   * When this sets a default source and the project ALSO configures `mongoose` explicitly, that
+   * MongoDB becomes the additional source named `mongoose`. Connection URLs are never logged with
+   * their credentials.
+   *
+   * Which databases this version can actually wire is checked at boot; anything it cannot is refused
+   * with a named error before any connection is attempted.
+   *
+   * @default undefined (the `mongoose` configuration)
+   */
+  database?: false | IDatabaseConfig | string;
+
   /**
    * When true, logs a debug message when prepareInput() changes the input type during process().
    * Enable only for debugging — has performance cost due to JSON.stringify on every process() call.
@@ -2900,10 +3007,15 @@ export interface IServerOptions {
     };
 
   /**
-   * Load local configuration
-   * false: no local configuration is loaded,
-   * true: it tries to load ./config.json or ../config.json,
-   * string: path to configuration
+   * Load a local configuration file and merge it over this environment's configuration
+   * - `false` / unset: nothing is loaded
+   * - `true`: `config.json` in the working directory, else `src/config.json`
+   * - string: path to the file, relative to the working directory. `.json` is read as JSON, anything else is loaded
+   *   as a module and its default export used
+   *
+   * Read synchronously, merged before `getEnvironmentConfig()` returns. Until 12.0.0 the file was searched next to
+   * nest-server's own config helper and merged asynchronously, so it never reached the configuration.
+   * @default false
    */
   loadLocalConfig?: boolean | string;
 

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

@@ -1,9 +1,9 @@
-import { CollationOptions } from 'mongodb';
-import { Model, PopulateOptions } from 'mongoose';
+import type { CollationOptions } from 'mongodb';
+import type { Model, PopulateOptions } from 'mongoose';
 
-import { FieldSelection } from '../types/field-selection.type';
-import { PrepareInputOptions } from './prepare-input-options.interface';
-import { PrepareOutputOptions } from './prepare-output-options.interface';
+import { FieldSelection } from '../types/field-selection.type.js';
+import { PrepareInputOptions } from './prepare-input-options.interface.js';
+import { PrepareOutputOptions } from './prepare-output-options.interface.js';
 
 /**
  * General service options

package/src/core/common/middleware/request-context.middleware.ts

@@ -1,7 +1,7 @@
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { IRequestContext, RequestContext } from '../services/request-context.service';
+import { IRequestContext, RequestContext } from '../services/request-context.service.js';
 
 /**
  * Middleware that wraps each request in a RequestContext (AsyncLocalStorage).

package/src/core/common/middlewares/security-headers.middleware.ts

@@ -1,8 +1,8 @@
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import { Response as ExpressResponse, NextFunction, Request } from 'express';
 
-import { ISecurityHeaders } from '../interfaces/server-options.interface';
-import { ConfigService } from '../services/config.service';
+import { ISecurityHeaders } from '../interfaces/server-options.interface.js';
+import { ConfigService } from '../services/config.service.js';
 
 /**
  * Sets the standard browser security headers on every response.

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

@@ -1,4 +1,4 @@
-import { map } from '../helpers/model.helper';
+import { map } from '../helpers/model.helper.js';
 
 /**
  * Core Model

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

@@ -1,12 +1,12 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema } from '@nestjs/mongoose';
-import { Types } from 'mongoose';
+import { Schema } from '../persistence/mongo/mongoose-compat.js';
 
-import { Restricted } from '../decorators/restricted.decorator';
-import { UnifiedField } from '../decorators/unified-field.decorator';
-import { RoleEnum } from '../enums/role.enum';
-import { getStringIds } from '../helpers/db.helper';
-import { CoreModel } from './core-model.model';
+import { Restricted } from '../decorators/restricted.decorator.js';
+import { UnifiedField } from '../decorators/unified-field.decorator.js';
+import { RoleEnum } from '../enums/role.enum.js';
+import { getStringIds } from '../helpers/db.helper.js';
+import { CoreModel } from './core-model.model.js';
+import { newObjectId } from '../persistence/mongo/mongoose-compat.js';
 
 /**
  * Metadata for persistent objects
@@ -33,7 +33,7 @@ export abstract class CorePersistenceModel extends CoreModel {
 
   @Restricted(RoleEnum.S_EVERYONE)
   get _id() {
-    return new Types.ObjectId(this.id);
+    return newObjectId(this.id);
   }
 
   /**

package/src/core/common/models/pagination-info.model.ts

@@ -1,6 +1,6 @@
 import { ObjectType } from '@nestjs/graphql';
 
-import { UnifiedField } from '../decorators/unified-field.decorator';
+import { UnifiedField } from '../decorators/unified-field.decorator.js';
 
 /**
  * Pagination information for paginated queries

package/src/core/common/persistence/core-persistence.lifecycle.ts

@@ -0,0 +1,47 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
+
+import { type ExpirySweep, scheduleExpirySweep } from './expiry-sweep.js';
+import { getPersistenceRuntime } from './persistence-runtime.registry.js';
+
+/**
+ * Opens the framework's lease store, releases the owner connections once the application is up, removes expired rows
+ * from SQL tables, and closes the connections of every SQL data source on shutdown. Registered by `CoreModule` only
+ * when a SQL source is configured; the sources themselves are opened while Nest creates the stores, so a misconfigured
+ * one stops the boot.
+ */
+@Injectable()
+export class CorePersistenceLifecycle implements OnApplicationBootstrap, OnApplicationShutdown, OnModuleInit {
+  protected readonly logger = new Logger('DataSources');
+  protected expirySweep?: ExpirySweep;
+
+  async onModuleInit(): Promise<void> {
+    // The lease table of the default source, while the boot's owner connection is still open — and an unsafe
+    // application role stops the boot here even when no model of the default source is registered
+    await getPersistenceRuntime()?.defaultLockStore();
+  }
+
+  async onApplicationBootstrap(): Promise<void> {
+    const runtime = getPersistenceRuntime();
+    // Every store exists by now: providers are created before any bootstrap hook runs
+    await runtime?.releaseBootConnections();
+    if (runtime) {
+      // A model's TTL (`expires`, `index: { expireAfterSeconds }`) is a plain index on SQL — this does the deleting
+      this.expirySweep = scheduleExpirySweep(
+        'models',
+        async () => {
+          for (const { deleted, model } of await runtime.sweepExpired()) {
+            if (deleted) {
+              this.logger.debug(`Removed ${deleted} expired ${model} record(s)`);
+            }
+          }
+        },
+        { logger: this.logger },
+      );
+    }
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.expirySweep?.stop();
+    await getPersistenceRuntime()?.close();
+  }
+}

package/src/core/common/persistence/core-persistence.module.ts

@@ -0,0 +1,109 @@
+import { DynamicModule, Module, Provider } from '@nestjs/common';
+import type { ModelDefinition } from '@nestjs/mongoose';
+import { getConnectionToken, getModelToken } from './mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
+
+import { registerModelSchema } from './model-metadata.registry.js';
+import { MongooseDataStore } from './mongoose-data-store.js';
+import { getPersistedModelOptions, getPersistedModelOptionsByName } from './persisted-model.decorator.js';
+import {
+  bindStoreToModel,
+  getPersistenceRuntime,
+  registerDataStore,
+  registerPersistedModel,
+} from './persistence-runtime.registry.js';
+import { getStoreToken } from './persistence.tokens.js';
+import { guardRoutedModel, isStandInModel, standInModel } from './routed-model.guard.js';
+import { unavailableStore } from './unavailable-store.js';
+
+/**
+ * Database-neutral model registration — the counterpart of `MongooseModule.forFeature()`.
+ *
+ * Registers the models exactly as `MongooseModule.forFeature()` does (so `@InjectModel()` keeps working),
+ * records each model's descriptor, and provides a data store per model for `@InjectStore()`.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [CorePersistenceModule.forFeature([{ name: Project.name, schema: ProjectSchema }])],
+ *   providers: [ProjectService],
+ * })
+ * export class ProjectModule {}
+ * ```
+ */
+/** A model definition, plus where it is stored when the configuration does not say */
+export interface PersistenceModelDefinition extends ModelDefinition {
+  /** Source name (a key of `database.sources`); the configuration's `database.models` wins */
+  dataSource?: string;
+  /**
+   * The model class — its `@PersistedModel({ dataSource })` is read when `dataSource` is not given. Without it, the
+   * `@PersistedModel` class named like the model (`name`) is read
+   */
+  model?: abstract new (...args: any[]) => any;
+}
+
+@Module({})
+export class CorePersistenceModule {
+  static forFeature(models: PersistenceModelDefinition[]): DynamicModule {
+    for (const model of models) {
+      registerModelSchema(model.name, model.schema);
+      registerPersistedModel({
+        declaredSource:
+          model.dataSource ??
+          (model.model ? getPersistedModelOptions(model.model) : getPersistedModelOptionsByName(model.name))
+            ?.dataSource,
+        name: model.name,
+        schema: model.schema,
+      });
+    }
+    // The Mongoose models, as `MongooseModule.forFeature()` registers them (`createMongooseProviders()` of
+    // @nestjs/mongoose) — but without requiring a connection: where no MongoDB is configured (`NoMongoConnectionModule`,
+    // or none at all) the token gets a stand-in that refuses data access, and the model runs on its routed store.
+    const mongooseModels: Provider[] = models.flatMap((model) => [
+      {
+        inject: [{ optional: true, token: getConnectionToken() }],
+        provide: getModelToken(model.name),
+        useFactory: (connection?: null | { model: Function; models: Record<string, unknown> }) =>
+          connection
+            ? (connection.models[model.name] ?? connection.model(model.name, model.schema, model.collection))
+            : standInModel(model.name, model.schema),
+      },
+      ...(model.discriminators ?? []).map((discriminator) => ({
+        inject: [getModelToken(model.name)],
+        provide: getModelToken(discriminator.name),
+        useFactory: (parent: { discriminator: Function }) =>
+          parent.discriminator(discriminator.name, discriminator.schema, discriminator.value),
+      })),
+    ]);
+    const stores: Provider[] = models.map((model) => ({
+      inject: [getModelToken(model.name)],
+      provide: getStoreToken(model.name),
+      // Routed when the store is created, not when the module is declared: feature modules are usually evaluated
+      // before `CoreModule.forRoot()` has read the configuration
+      useFactory: async (mongooseModel: Model<any>) => {
+        const runtime = getPersistenceRuntime();
+        const store = runtime
+          ? await runtime.resolveStore(model.name, mongooseModel)
+          : isStandInModel(mongooseModel)
+            ? // No SQL source and no MongoDB connection: the project runs without a database (`database: false`)
+              unavailableStore(model.name, 'the project runs without a database (`database: false`)')
+            : new MongooseDataStore(mongooseModel);
+        registerDataStore(model.name, store);
+        bindStoreToModel(mongooseModel, store);
+        // A stand-in already refuses, naming the cause; a real Mongoose model of a model routed elsewhere is made to
+        if (!store.capabilities.mongoosePopulate && !isStandInModel(mongooseModel)) {
+          guardRoutedModel(mongooseModel, store);
+        }
+        return store;
+      },
+    }));
+    return {
+      exports: [
+        ...mongooseModels.map((provider) => (provider as { provide: string }).provide),
+        ...stores.map((store) => (store as { provide: string }).provide),
+      ],
+      module: CorePersistenceModule,
+      providers: [...mongooseModels, ...stores],
+    };
+  }
+}