@lenne.tech/nest-server 11.43.3 → 12.1.0

package/src/core/common/persistence/data-store.interface.ts

@@ -0,0 +1,155 @@
+/**
+ * The data store port: the neutral operations every database implements.
+ *
+ * Import-free on purpose (types only), like every leaf the persistence layer and its DI tokens depend on.
+ *
+ * Records are plain objects with the id as a string under `id` (never `_id`, never a driver type). Filters
+ * and updates use the Mongo-operator subset the codebase already speaks: MongoDB executes them as they
+ * are, a SQL store compiles them and refuses what it cannot express — it never drops a condition.
+ */
+
+/**
+ * Neutral filter: implicit equality, dot paths into embedded objects, and the operators
+ * `$eq $ne $gt $gte $lt $lte $in $nin $exists $regex/$options $and $or $nor $not $all $size $elemMatch`.
+ * The id is addressed as `id`.
+ */
+export type Where<T = Record<string, any>> = { [K in keyof T]?: any } & {
+  [path: string]: any;
+  $and?: Where<T>[];
+  $nor?: Where<T>[];
+  $or?: Where<T>[];
+};
+
+/**
+ * Neutral update: a partial record (equivalent to `$set`), or the operators `$set $unset $inc $push
+ * $pull $addToSet $setOnInsert`.
+ */
+export type DataStoreUpdate<T = Record<string, any>> =
+  | Partial<T>
+  | {
+      $addToSet?: Record<string, unknown>;
+      $inc?: Record<string, number>;
+      $pull?: Record<string, unknown>;
+      $push?: Record<string, unknown>;
+      $set?: Partial<T> & Record<string, unknown>;
+      $setOnInsert?: Partial<T> & Record<string, unknown>;
+      $unset?: Record<string, '' | 1 | true>;
+    };
+
+/** A stored record: the model's fields plus its id as a string. */
+export type StoredRecord<T = Record<string, any>> = T & { id: string };
+
+export interface FindOptions {
+  /** Language-specific string comparison (MongoDB collation; mapped by SQL stores where supported) */
+  collation?: Record<string, unknown>;
+  limit?: number;
+  /**
+   * Return this many records chosen at random from the page — after filter, sort, skip and limit, as MongoDB's `$sample`
+   * stage follows them in `CrudService.findAndCount()`. A positive integer; a sample larger than the page returns the
+   * whole page. The order of the result is random too.
+   */
+  sample?: number;
+  /**
+   * Field names to leave out (MongoDB's `-name` projection); everything else the model returns by default is read.
+   * Not combinable with `select`, as MongoDB does not combine them either.
+   */
+  exclude?: readonly string[];
+  /** Field names to return; the id is always returned */
+  select?: readonly string[];
+  skip?: number;
+  /** Field → 1 (ascending) or -1 (descending), applied in declaration order */
+  sort?: Record<string, -1 | 1>;
+}
+
+export interface UpdateOptions {
+  /**
+   * `false` leaves the update time (`updatedAt`) as it is — for bookkeeping writes such as a last-used stamp, which
+   * must not read as a change of the record (Mongoose's `timestamps: false`). @default true
+   */
+  timestamps?: boolean;
+}
+
+export interface PushOptions {
+  /** Insert position (MongoDB `$position`) */
+  position?: number;
+  /** Keep only this many items after the push: negative = the last n, positive = the first n */
+  slice?: number;
+  /** Sort the array after the push */
+  sort?: Record<string, -1 | 1>;
+}
+
+/**
+ * What a store can do. Features ask the store, never the driver name; an unavailable capability fails at
+ * boot when it is configured and at the call with a named error otherwise.
+ */
+export interface StoreCapabilities {
+  /** `aggregate()` with a MongoDB pipeline */
+  aggregatePipeline: boolean;
+  /** Change streams / logical replication feed */
+  changeFeed: boolean;
+  /** GridFS file storage */
+  gridfs: boolean;
+  /** Mongoose documents and populate — the CrudService pipeline's MongoDB path */
+  mongoosePopulate: boolean;
+  /** A raw driver filter is passed through untouched */
+  rawFilterArm: boolean;
+  /** Row-level security enforced by the database */
+  rls: boolean;
+  /** Full-text search */
+  textSearch: boolean;
+  /** Multi-statement transactions */
+  transactions: boolean;
+  /** Format of generated ids */
+  idType: 'objectId';
+}
+
+export interface DataStore<T = Record<string, any>> {
+  readonly capabilities: StoreCapabilities;
+  /** The database behind the store (`mongodb`, `postgres`, …) */
+  readonly driver: string;
+  readonly modelName: string;
+
+  count(where?: Where<T>): Promise<number>;
+  deleteById(id: string): Promise<null | StoredRecord<T>>;
+  /** Remove every record matching `where`; returns how many were removed. */
+  deleteMany(where: Where<T>): Promise<number>;
+  /**
+   * Remove the first record matching `where`, atomically (MongoDB's `findOneAndDelete`), and return it; `null` when
+   * nothing matches.
+   */
+  deleteOne(where: Where<T>): Promise<null | StoredRecord<T>>;
+  distinct(field: string, where?: Where<T>): Promise<unknown[]>;
+  find(where?: Where<T>, options?: FindOptions): Promise<StoredRecord<T>[]>;
+  findById(id: string, options?: Pick<FindOptions, 'exclude' | 'select'>): Promise<null | StoredRecord<T>>;
+  findOne(where: Where<T>, options?: Omit<FindOptions, 'limit' | 'skip'>): Promise<null | StoredRecord<T>>;
+  insert(record: Partial<T>): Promise<StoredRecord<T>>;
+  /**
+   * Tier 2 access: the database library's own API for this model (the Mongoose model on MongoDB), bound
+   * to the current unit of work. The reason is mandatory and logged.
+   */
+  native<N = unknown>(reason: string): N;
+  /** Remove every array item matching `condition` from `field`, atomically. */
+  pullFromArray(id: string, field: string, condition: unknown): Promise<void>;
+  /** Append `items` to the array `field`, atomically. */
+  pushToArray(id: string, field: string, items: readonly unknown[], options?: PushOptions): Promise<void>;
+  /**
+   * Tier 3 access: the raw driver (the MongoDB collection on MongoDB). Bypasses every policy of the
+   * store; the reason is mandatory and logged as a security event.
+   */
+  raw<N = unknown>(reason: string): N;
+  /**
+   * How many records match `where`, and the total of the numeric `field` over them (a missing value adds 0) — counted
+   * by the database, so only the result crosses the wire (MongoDB's `$group`, SQL's `count`/`sum`).
+   */
+  sum(field: string, where?: Where<T>): Promise<{ count: number; sum: number }>;
+  /** Apply `update` to the record and return it as stored afterwards; `null` when there is none. */
+  updateById(id: string, update: DataStoreUpdate<T>, options?: UpdateOptions): Promise<null | StoredRecord<T>>;
+  /** Apply `update` to every record matching `where`; returns how many records matched. */
+  updateMany(where: Where<T>, update: DataStoreUpdate<T>): Promise<number>;
+  /**
+   * Apply `update` to the first record matching `where`, atomically: the record still matches when it is changed, and
+   * concurrent callers never change the same record on the strength of one match (MongoDB's `findOneAndUpdate`).
+   * Returns the record as stored afterwards; `null` when nothing matches.
+   */
+  updateOne(where: Where<T>, update: DataStoreUpdate<T>): Promise<null | StoredRecord<T>>;
+}

package/src/core/common/persistence/expiry-sweep.ts

@@ -0,0 +1,105 @@
+import type { Logger } from '@nestjs/common';
+
+import { defaultSqlLockStore } from './infrastructure-locks.js';
+import type { ModelDescriptor } from './model-descriptor.interface.js';
+
+/**
+ * How often expired rows are removed from SQL tables. MongoDB's TTL monitor does this for its collections about once a
+ * minute; on SQL nothing does it unless the framework does. Nothing depends on it for correctness — every reader checks
+ * the expiry itself — so the interval only bounds how long expired rows take up space.
+ */
+export const EXPIRY_SWEEP_INTERVAL_MS = 15 * 60_000;
+
+/**
+ * The records of a model whose TTL has passed, decided as MongoDB's TTL monitor decides it: a non-array date field plus
+ * its TTL lies before `now` — a record without that date never expires — and, for a PARTIAL TTL index, the record also
+ * matches the index's `partialFilterExpression`, because MongoDB expires nothing outside it. `undefined` when the model
+ * declares no TTL.
+ *
+ * The partial filter is not decoration: `{ expireAfterSeconds, partialFilterExpression: { verified: false } }` expires
+ * unverified accounts only, and a sweep that dropped the filter deleted every verified one as well. A filter the SQL
+ * where compiler cannot express makes the delete fail, so nothing is deleted rather than too much.
+ */
+export function expiredRecordsFilter(model: ModelDescriptor, now: Date): Record<string, unknown> | undefined {
+  const conditions = Object.values(model.fields)
+    .filter(
+      (field) =>
+        field.kind === 'date' &&
+        !field.isArray &&
+        Number.isFinite(field.expiresAfterSeconds) &&
+        field.expiresAfterSeconds >= 0,
+    )
+    .map((field) => {
+      const expired = { [field.name]: { $lt: new Date(now.getTime() - field.expiresAfterSeconds * 1000) } };
+      const ttlIndex = model.indexes.find(
+        (index) =>
+          Object.keys(index.fields).length === 1 && field.name in index.fields && 'expireAfterSeconds' in index.options,
+      );
+      const partial = ttlIndex?.options.partialFilterExpression as Record<string, unknown> | undefined;
+      return partial ? { $and: [expired, partial] } : expired;
+    });
+  if (!conditions.length) {
+    return undefined;
+  }
+  return conditions.length === 1 ? conditions[0] : { $or: conditions };
+}
+
+/** A scheduled sweep */
+export interface ExpirySweep {
+  /** Sweep at once, without the lease — after the sweep that may be running has finished */
+  runNow(): Promise<void>;
+  /** End the timer and wait for a sweep that is still running */
+  stop(): Promise<void>;
+}
+
+/**
+ * Run `sweep` now and then every `intervalMs` — on one replica per interval when the default source is a SQL database
+ * (the lease `expiry-sweep:<key>` in its lease table, never released, so the next replica takes it once it expired),
+ * otherwise on every replica. Running it on several is harmless: a sweep only deletes what has already expired.
+ *
+ * Fails open: a sweep or a lease that fails is logged and tried again at the next interval, it never stops the
+ * application.
+ */
+export function scheduleExpirySweep(
+  key: string,
+  sweep: () => Promise<void>,
+  options: { intervalMs?: number; logger: Logger },
+): ExpirySweep {
+  const intervalMs = options.intervalMs ?? EXPIRY_SWEEP_INTERVAL_MS;
+  const owner = `expiry-sweep:${process.pid}:${Math.random().toString(36).slice(2)}`;
+  let running: Promise<void> | undefined;
+
+  const tick = async (): Promise<void> => {
+    try {
+      const locks = await defaultSqlLockStore('expiry-sweep');
+      if (locks && !(await locks.tryAcquire(key, owner, Math.max(1, Math.floor(intervalMs / 1000))))) {
+        return;
+      }
+      await sweep();
+    } catch (error) {
+      options.logger.warn(
+        `Expiry sweep "${key}" failed, trying again in ${Math.max(1, Math.round(intervalMs / 60_000))} min: ${(error as Error)?.message ?? error}`,
+      );
+    }
+  };
+  const run = () => {
+    // One sweep at a time: an interval that elapses during a slow sweep is skipped, not queued
+    running ??= tick().finally(() => {
+      running = undefined;
+    });
+  };
+
+  run();
+  const timer = setInterval(run, intervalMs);
+  timer.unref();
+  return {
+    runNow: async () => {
+      await running;
+      await sweep();
+    },
+    stop: async () => {
+      clearInterval(timer);
+      await running;
+    },
+  };
+}

package/src/core/common/persistence/id-format.ts

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+
+import { isObjectIdLike } from '../helpers/id.helper.js';
+
+export { isObjectIdLike } from '../helpers/id.helper.js';
+
+/**
+ * The stored id format, the same on every database: 24 hex characters — an ObjectId's hex string.
+ * On MongoDB that IS the ObjectId; on SQL the application generates it (plan §3.5), so ids, URLs and
+ * validators stay identical across the fleet and survive a data move between databases.
+ */
+const STORED_ID = /^[0-9a-f]{24}$/i;
+
+/**
+ * Whether a value is a well-formed stored id: an ObjectId (from any bson copy) or its 24-character hex
+ * string.
+ *
+ * Deliberately stricter than `Types.ObjectId.isValid()`, which also accepts any 12-character string
+ * (a 12-byte ObjectId seed) — no stored id ever has that form. For strings this is exactly the rule
+ * `checkStringIds()` and `CoreFileService.isMalformedFileId()` applied as `length === 24 && isValid()`.
+ */
+export function isWellFormedId(value: unknown): boolean {
+  if (typeof value === 'string') {
+    return STORED_ID.test(value);
+  }
+  return isObjectIdLike(value);
+}
+
+const PROCESS_UNIQUE = randomBytes(5);
+let counter = randomBytes(3).readUIntBE(0, 3);
+
+/**
+ * A new id in the stored format, generated by the application (plan §3.5): an ObjectId — 4 bytes of seconds,
+ * 5 random bytes per process, a 3-byte counter — so ids stay sortable by creation time like MongoDB's.
+ */
+export function generateId(): string {
+  const bytes = Buffer.alloc(12);
+  bytes.writeUInt32BE(Math.floor(Date.now() / 1000) >>> 0, 0);
+  PROCESS_UNIQUE.copy(bytes, 4);
+  counter = (counter + 1) % 0x1000000;
+  bytes.writeUIntBE(counter, 9, 3);
+  return bytes.toString('hex');
+}

package/src/core/common/persistence/infrastructure-locks.ts

@@ -0,0 +1,66 @@
+import type { Collection } from 'mongodb';
+
+import type { LockStore } from './lock-store.interface.js';
+import { MongoLockStore } from './mongo-lock-store.js';
+import { getPersistenceRuntime } from './persistence-runtime.registry.js';
+
+/**
+ * The framework's own locks — the system-setup claim, the cron lease and the migration lock — on a `LockStore`.
+ *
+ * On MongoDB each one keeps the document 12.0.0 wrote (same collection, same key, same timestamp field): during a
+ * rolling deploy an older replica still claims through its own code, and only one document per lock lets both
+ * versions see the same lease. The `MongoLockStore` options below encode each format. On a SQL default source the
+ * locks live in the lease table, namespaced per consumer.
+ */
+
+/** Cron leases: `{ _id: <tick key>, expiresAt }` — already the lease format, so no legacy rule is needed */
+export const CRON_LOCK_COLLECTION = 'cron-locks';
+
+export const SYSTEM_SETUP_LOCK_COLLECTION = 'system-setup-locks';
+export const SYSTEM_SETUP_LOCK_KEY = 'initial-admin';
+/** The claim is taken over once it is this old: a replica killed between claiming and creating must not block setup */
+export const SYSTEM_SETUP_CLAIM_STALE_AFTER_MS = 5 * 60_000;
+
+export const MIGRATION_LOCK_KEY = 'lock';
+/** A migration lock whose holder stopped heart-beating this long ago is broken */
+export const MIGRATION_LOCK_STALE_AFTER_MS = 60_000;
+
+export function cronMongoLocks(collection: Collection<any>): LockStore {
+  return new MongoLockStore(collection);
+}
+
+/** `{ _id: 'initial-admin', claimedAt }` — expired once `claimedAt` is older than the stale period */
+export function systemSetupMongoLocks(collection: Collection<any>): LockStore {
+  return new MongoLockStore(collection, {
+    legacyTimestamp: { field: 'claimedAt', staleAfterMs: SYSTEM_SETUP_CLAIM_STALE_AFTER_MS },
+  });
+}
+
+/**
+ * `{ lock: 'lock', owner, acquiredAt }` with a unique index on `lock` — `acquiredAt` is the holder's heartbeat, and
+ * a renewal refreshes it so an older waiter does not break a live lock
+ */
+export function migrationMongoLocks(collection: Collection<any>): LockStore {
+  return new MongoLockStore(collection, {
+    keyField: 'lock',
+    legacyTimestamp: { field: 'acquiredAt', staleAfterMs: MIGRATION_LOCK_STALE_AFTER_MS },
+  });
+}
+
+/**
+ * The lease store of the default data source when it is a SQL database, its keys prefixed with `namespace` so the
+ * consumers sharing the one lease table cannot collide; `undefined` when the default source is MongoDB
+ */
+export async function defaultSqlLockStore(namespace: string): Promise<LockStore | undefined> {
+  const locks = await getPersistenceRuntime()?.defaultLockStore();
+  return locks ? namespacedLocks(locks, namespace) : undefined;
+}
+
+export function namespacedLocks(locks: LockStore, namespace: string): LockStore {
+  const key = (name: string) => `${namespace}:${name}`;
+  return {
+    release: (name, owner) => locks.release(key(name), owner),
+    renew: (name, owner, ttlSeconds) => locks.renew(key(name), owner, ttlSeconds),
+    tryAcquire: (name, owner, ttlSeconds) => locks.tryAcquire(key(name), owner, ttlSeconds),
+  };
+}

package/src/core/common/persistence/inject-store.decorator.ts

@@ -0,0 +1,16 @@
+import { Inject } from '@nestjs/common';
+
+import { getStoreToken } from './persistence.tokens.js';
+
+/**
+ * Inject the data store of a model registered with `CorePersistenceModule.forFeature()` — the
+ * database-neutral counterpart of `@InjectModel()`.
+ *
+ * @example
+ * ```typescript
+ * constructor(@InjectStore(Project) private readonly projects: DataStore<Project>) {}
+ * ```
+ */
+export function InjectStore(model: Function | string): ParameterDecorator & PropertyDecorator {
+  return Inject(getStoreToken(typeof model === 'string' ? model : model.name));
+}

package/src/core/common/persistence/lock-store.interface.ts

@@ -0,0 +1,17 @@
+/**
+ * Leases shared by every replica: "exactly one of N does this, and if it dies, somebody takes over".
+ *
+ * Expiry is part of the decision, never left to a background monitor: an expired lease is taken over by
+ * exactly one contender at the moment it is claimed. Import-free leaf (types only).
+ */
+export interface LockStore {
+  /** Release the lease — only by its owner. `true` when this owner held it. */
+  release(key: string, owner: string): Promise<boolean>;
+  /** Extend a lease this owner still holds. `false` when it expired or someone else took it. */
+  renew(key: string, owner: string, ttlSeconds: number): Promise<boolean>;
+  /**
+   * Take the lease when it is free or expired. Of N concurrent contenders exactly one gets `true`; a lease
+   * that is held and unexpired is never taken.
+   */
+  tryAcquire(key: string, owner: string, ttlSeconds: number): Promise<boolean>;
+}

package/src/core/common/persistence/model-descriptor.interface.ts

@@ -0,0 +1,90 @@
+/**
+ * Database-neutral description of a persisted model.
+ *
+ * The SQL side builds tables, columns, indexes and value mappings from these descriptors; the
+ * parity matrix and the Hub read them too. They describe what is STORED, not what the API exposes:
+ * a field without a persistence declaration is not part of a descriptor.
+ *
+ * Import-free on purpose (types only): every persistence file may depend on it without creating an
+ * import cycle — see `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * The storage kind of a field.
+ *
+ * - `enum`: a value from `enumValues`, stored as `enumBase`
+ * - `id`: an identifier of this or another record WITHOUT a declared target model
+ * - `ref`: an identifier of a record of the model named in `ref`
+ * - `object`: an embedded object whose shape is declared (`nested` holds its fields)
+ * - `json`: a value whose shape is NOT declared (Mixed, Map, a plain class without `@Schema`)
+ */
+export type FieldKind =
+  | 'bigint'
+  | 'boolean'
+  | 'buffer'
+  | 'date'
+  | 'decimal'
+  | 'enum'
+  | 'id'
+  | 'json'
+  | 'number'
+  | 'object'
+  | 'ref'
+  | 'string'
+  | 'uuid';
+
+export interface FieldDescriptor {
+  /** Literal default value; absent when the default is computed (a function) */
+  default?: unknown;
+  /** Base type of an enum's values */
+  enumBase?: 'number' | 'string';
+  /** Allowed values of an enum */
+  enumValues?: readonly unknown[];
+  /** TTL: the record expires this many seconds after the field's date */
+  expiresAfterSeconds?: number;
+  /** Whether a default exists at all (literal or computed) */
+  hasDefault: boolean;
+  /** Whether a single-field index exists on this field (declared, unique or TTL) */
+  index: boolean;
+  /** Whether the field holds a list of `kind` values */
+  isArray: boolean;
+  kind: FieldKind;
+  /** Values are lowercased before they are stored */
+  lowercase: boolean;
+  name: string;
+  /** Fields of an embedded object (`kind: 'object'`) */
+  nested?: Record<string, FieldDescriptor>;
+  /** Target model of a reference (`kind: 'ref'`) */
+  ref?: string;
+  /**
+   * The field's previous name: a SQL store renames the column instead of adding a new, empty one. Declared, never
+   * guessed (plan §3.12) — MongoDB documents keep the old key until a migration moves it.
+   */
+  renamedFrom?: string;
+  required: boolean;
+  /** `false` when the field is excluded from reads unless explicitly selected (`select: false`) */
+  select: boolean;
+  sparse: boolean;
+  /** Values are trimmed before they are stored */
+  trim: boolean;
+  unique: boolean;
+}
+
+export interface IndexDescriptor {
+  /** Field → direction or index type (`1`, `-1`, `'text'`, …), in declaration order */
+  fields: Record<string, number | string>;
+  /** Index options as declared (`unique`, `sparse`, `expireAfterSeconds`, `partialFilterExpression`, …) */
+  options: Record<string, unknown>;
+}
+
+export interface ModelDescriptor {
+  /** Explicit collection / table name, when the model declares one */
+  collection?: string;
+  fields: Record<string, FieldDescriptor>;
+  indexes: IndexDescriptor[];
+  name: string;
+  /** Whether the model carries a `tenantId` — the same criterion the tenant plugin uses */
+  tenantScoped: boolean;
+  /** `createdAt` / `updatedAt` maintenance: `true`, `false`, or the configured field names */
+  timestamps: boolean | { createdAt: false | string; updatedAt: false | string };
+}