@lenne.tech/nest-server 12.0.0 → 12.1.0

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 };
+}

package/src/core/common/persistence/model-metadata.registry.ts

@@ -0,0 +1,285 @@
+import type { FieldDescriptor, FieldKind, IndexDescriptor, ModelDescriptor } from './model-descriptor.interface.js';
+import { declaredSchemaView } from './mongo/declared-schema.view.js';
+import { type DeclaredSchema, isDeclaredSchema } from './mongo/model-declarations.js';
+import { SchemaFactory } from './mongo/mongoose-compat.js';
+
+/**
+ * Registry of database-neutral model descriptors.
+ *
+ * The descriptors are derived from the model's Mongoose schema where Mongoose is installed — what MongoDB stores,
+ * and therefore the most faithful source: it covers fields declared through `@UnifiedField({ mongoose })` and through
+ * a plain `@Prop()` alike, which consumer projects mix freely. `SchemaFactory.createForClass` works without a
+ * connection, so a descriptor exists before any database is reached. Where Mongoose is NOT installed (12.1.0+, a
+ * project on PostgreSQL alone), the schema is the recorded declaration (`DeclaredSchema`), read through a view that
+ * builds the paths and indexes exactly as Mongoose would (`mongo/declared-schema.view.ts`); the snapshot of every
+ * model the framework ships proves both sources agree.
+ *
+ * Only the schema's own declarations are read — never documents — so describing a model is free of
+ * side effects and safe at boot.
+ */
+
+const descriptorsByName = new Map<string, ModelDescriptor>();
+const descriptorsByClass = new WeakMap<object, ModelDescriptor>();
+
+/** Mongoose's version key is bookkeeping of the Mongo driver, not model data. */
+const IGNORED_PATHS = new Set(['__v']);
+
+/**
+ * Minimal structural view of a Mongoose schema — `import type` would tie the descriptor to the
+ * installed mongoose version's generics, and only these members are read.
+ */
+interface SchemaLike {
+  eachPath(fn: (path: string, schemaType: any) => void): unknown;
+  get(key: string): unknown;
+  indexes(): Array<[Record<string, number | string>, Record<string, unknown>?]>;
+  path(path: string): unknown;
+}
+
+/**
+ * Describe a schema under the given model name.
+ */
+export function describeSchema(name: string, given: DeclaredSchema | SchemaLike): ModelDescriptor {
+  const schema: SchemaLike = isDeclaredSchema(given) ? declaredSchemaView(given) : given;
+  const indexes = describeIndexes(schema);
+  const descriptor: ModelDescriptor = {
+    fields: describeFields(schema, indexes),
+    indexes,
+    name,
+    tenantScoped: !!schema.path('tenantId'),
+    timestamps: describeTimestamps(schema.get('timestamps')),
+  };
+  const collection = schema.get('collection');
+  if (typeof collection === 'string' && collection) {
+    descriptor.collection = collection;
+  }
+  return descriptor;
+}
+
+/**
+ * Describe a model class (decorated with `@Schema()`), cached per class.
+ *
+ * The model name is the class name — the name `MongooseModule.forFeature([{ name: X.name, … }])` uses.
+ */
+export function describeModelClass(modelClass: abstract new (...args: any[]) => any): ModelDescriptor {
+  const cached = descriptorsByClass.get(modelClass);
+  if (cached) {
+    return cached;
+  }
+  const descriptor = describeSchema(modelClass.name, SchemaFactory.createForClass(modelClass as any));
+  descriptorsByClass.set(modelClass, descriptor);
+  return descriptor;
+}
+
+/**
+ * Register the schema a model is persisted with, under its model name. A later registration under
+ * the same name replaces the earlier one — the last `forFeature` wins, as it does in Mongoose.
+ */
+export function registerModelSchema(name: string, schema: DeclaredSchema | SchemaLike): ModelDescriptor {
+  const descriptor = describeSchema(name, schema);
+  descriptorsByName.set(name, descriptor);
+  return descriptor;
+}
+
+/** The descriptor registered under a model name, if any. */
+export function getModelDescriptor(name: string): ModelDescriptor | undefined {
+  return descriptorsByName.get(name);
+}
+
+/** Every registered descriptor, keyed by model name. */
+export function getModelDescriptors(): ReadonlyMap<string, ModelDescriptor> {
+  return descriptorsByName;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------------------------
+
+function describeIndexes(schema: SchemaLike): IndexDescriptor[] {
+  return schema.indexes().map(([fields, options]) => ({ fields: { ...fields }, options: { ...options } }));
+}
+
+function describeTimestamps(value: unknown): ModelDescriptor['timestamps'] {
+  if (value && typeof value === 'object') {
+    const config = value as { createdAt?: boolean | string; updatedAt?: boolean | string };
+    const name = (option: boolean | string | undefined, fallback: string): false | string =>
+      option === false ? false : typeof option === 'string' ? option : fallback;
+    return { createdAt: name(config.createdAt, 'createdAt'), updatedAt: name(config.updatedAt, 'updatedAt') };
+  }
+  return value === true;
+}
+
+/**
+ * Collect the schema's paths into fields. Dotted paths of a raw nested object (`{ meta: { score } }`
+ * becomes `meta.score`) are grouped back into one object field, because that is what is stored: one
+ * embedded object, not columns named with dots.
+ */
+function describeFields(schema: SchemaLike, indexes: IndexDescriptor[]): Record<string, FieldDescriptor> {
+  const entries: Array<[string, any]> = [];
+  schema.eachPath((path, schemaType) => {
+    // `labels.$*` is the value type of a Map, which the Map field itself already stands for
+    if (IGNORED_PATHS.has(path) || path.includes('$*')) {
+      return;
+    }
+    entries.push([path, schemaType]);
+  });
+  return buildFields(entries, indexes, '');
+}
+
+function buildFields(
+  entries: Array<[string, any]>,
+  indexes: IndexDescriptor[],
+  prefix: string,
+): Record<string, FieldDescriptor> {
+  const fields: Record<string, FieldDescriptor> = {};
+  const groups = new Map<string, Array<[string, any]>>();
+  for (const [path, schemaType] of entries) {
+    const dot = path.indexOf('.');
+    if (dot === -1) {
+      fields[path] = describeField(path, schemaType, indexes, `${prefix}${path}`);
+      continue;
+    }
+    const head = path.slice(0, dot);
+    const group = groups.get(head) ?? [];
+    group.push([path.slice(dot + 1), schemaType]);
+    groups.set(head, group);
+  }
+  for (const [head, group] of groups) {
+    fields[head] = clean({
+      ...baseField(head),
+      kind: 'object',
+      nested: buildFields(group, indexes, `${prefix}${head}.`),
+    });
+  }
+  return fields;
+}
+
+function describeField(name: string, schemaType: any, indexes: IndexDescriptor[], fullPath: string): FieldDescriptor {
+  const options: Record<string, any> = schemaType?.options ?? {};
+  const field: FieldDescriptor = {
+    ...baseField(name),
+    ...describeKind(schemaType, options),
+    lowercase: options.lowercase === true,
+    renamedFrom: typeof options.renamedFrom === 'string' ? options.renamedFrom : undefined,
+    required: !!schemaType?.isRequired,
+    select: options.select !== false,
+    sparse: !!options.sparse,
+    trim: options.trim === true,
+    unique: options.unique === true || (Array.isArray(options.unique) && options.unique[0] === true),
+  };
+
+  const defaultValue = schemaType?.defaultValue ?? options.default;
+  if (defaultValue !== undefined) {
+    field.hasDefault = true;
+    if (typeof defaultValue !== 'function') {
+      field.default = defaultValue;
+    }
+  }
+
+  // Read the TTL from the schema's index list: Mongoose has already turned `expires: '1h'` into seconds there
+  const ttl = indexes.find(
+    (index) =>
+      Object.keys(index.fields).length === 1 && fullPath in index.fields && 'expireAfterSeconds' in index.options,
+  );
+  if (ttl) {
+    field.expiresAfterSeconds = Number(ttl.options.expireAfterSeconds);
+  }
+  field.index = !!options.index || field.unique || !!ttl;
+
+  return clean(field);
+}
+
+function baseField(name: string): FieldDescriptor {
+  return {
+    hasDefault: false,
+    index: false,
+    isArray: false,
+    kind: 'json',
+    lowercase: false,
+    name,
+    required: false,
+    select: true,
+    sparse: false,
+    trim: false,
+    unique: false,
+  };
+}
+
+type KindPart = Pick<FieldDescriptor, 'enumBase' | 'enumValues' | 'isArray' | 'kind' | 'nested' | 'ref'>;
+
+function describeKind(schemaType: any, options: Record<string, any>): KindPart {
+  // An array of sub-documents declared with @Schema
+  if (schemaType?.$isMongooseDocumentArray && schemaType.schema) {
+    return { isArray: true, kind: 'object', nested: nestedFields(schemaType.schema) };
+  }
+  // A single sub-document declared with @Schema
+  if (schemaType?.$isSingleNested && schemaType.schema) {
+    return { isArray: false, kind: 'object', nested: nestedFields(schemaType.schema) };
+  }
+  if (schemaType?.instance === 'Array') {
+    const element = schemaType.embeddedSchemaType ?? schemaType.caster;
+    // An array of arrays has no column shape; it is stored as JSON
+    if (!element || element.instance === 'Array') {
+      return { isArray: false, kind: 'json' };
+    }
+    return { ...scalarKind(element, element.options ?? {}), isArray: true };
+  }
+  return { ...scalarKind(schemaType, options), isArray: false };
+}
+
+function scalarKind(schemaType: any, options: Record<string, any>): Omit<KindPart, 'isArray'> {
+  // A reference is recognised by its declaration, not by its type: `type: Types.ObjectId` (the bson
+  // class rather than `Schema.Types.ObjectId`) makes Mongoose report the path as Mixed, yet it is a ref.
+  if (options.ref !== undefined || options.refPath !== undefined) {
+    const ref = typeof options.ref === 'string' ? options.ref : options.ref?.modelName;
+    return ref ? { kind: 'ref', ref } : { kind: 'ref' };
+  }
+  const instance: string | undefined = schemaType?.instance;
+  if (instance === 'String' || instance === 'Number') {
+    const base = instance === 'String' ? 'string' : 'number';
+    const values = enumValuesOf(schemaType, options, base);
+    return values ? { enumBase: base, enumValues: values, kind: 'enum' } : { kind: base };
+  }
+  const kinds: Record<string, FieldKind> = {
+    BigInt: 'bigint',
+    Boolean: 'boolean',
+    Buffer: 'buffer',
+    Date: 'date',
+    Decimal128: 'decimal',
+    Double: 'number',
+    Int32: 'number',
+    ObjectId: 'id',
+    UUID: 'uuid',
+  };
+  // Mixed, Map and anything unknown carry no declared shape
+  return { kind: (instance && kinds[instance]) || 'json' };
+}
+
+function enumValuesOf(schemaType: any, options: Record<string, any>, base: 'number' | 'string'): unknown[] | undefined {
+  if (Array.isArray(schemaType?.enumValues) && schemaType.enumValues.length) {
+    return [...schemaType.enumValues];
+  }
+  const declared = options.enum?.values ?? options.enum;
+  if (Array.isArray(declared)) {
+    return declared.length ? [...declared] : undefined;
+  }
+  if (declared && typeof declared === 'object') {
+    // A TypeScript numeric enum maps both ways (`{ A: 0, 0: 'A' }`): keep only the values of the base type
+    const values = Object.values(declared).filter((value) => typeof value === base);
+    return values.length ? values : undefined;
+  }
+  return undefined;
+}
+
+function nestedFields(schema: SchemaLike): Record<string, FieldDescriptor> {
+  return describeFields(schema, describeIndexes(schema));
+}
+
+/** Drop optional keys that are `undefined`, so descriptors compare and print without noise. */
+function clean(field: FieldDescriptor): FieldDescriptor {
+  for (const key of Object.keys(field) as Array<keyof FieldDescriptor>) {
+    if (field[key] === undefined) {
+      delete field[key];
+    }
+  }
+  return field;
+}

package/src/core/common/persistence/mongo/collection-name.ts

@@ -0,0 +1,87 @@
+import { optionalMongoPackages } from './mongo-packages.js';
+
+/**
+ * The collection name MongoDB gives a model that declares none — and therefore the name of its SQL table
+ * (`postgres-schema.compiler.ts` → `tableName()`), so a model keeps one name on every database.
+ *
+ * Where Mongoose is installed its CURRENT pluralizer decides, a project's own `mongoose.pluralize(fn)` (or `null`,
+ * which keeps the name) included. Without Mongoose the legacy rules below decide — Mongoose's default
+ * (`lib/helpers/pluralize.js`, MIT, © LearnBoost and Automattic, extracted by TJ Holowaychuk from `_ext.js`), copied
+ * unchanged so a model is named alike whether or not the project installs Mongoose;
+ * `tests/unit/collection-name.spec.ts` compares the two.
+ */
+export function defaultCollectionName(modelName: string): string {
+  const packages = optionalMongoPackages();
+  if (packages) {
+    const pluralize = packages.mongoose.pluralize();
+    return pluralize ? pluralize(modelName) : modelName;
+  }
+  return legacyPluralize(modelName);
+}
+
+const RULES: Array<[RegExp, string]> = [
+  [/human$/gi, 'humans'],
+  [/(m|wom)an$/gi, '$1en'],
+  [/(pe)rson$/gi, '$1ople'],
+  [/(child)$/gi, '$1ren'],
+  [/^(ox)$/gi, '$1en'],
+  [/(ax|test)is$/gi, '$1es'],
+  [/(octop|cact|foc|fung|nucle)us$/gi, '$1i'],
+  [/(alias|status|virus)$/gi, '$1es'],
+  [/(bu)s$/gi, '$1ses'],
+  [/(buffal|tomat|potat)o$/gi, '$1oes'],
+  [/([ti])um$/gi, '$1a'],
+  [/sis$/gi, 'ses'],
+  [/(?:([^f])fe|([lr])f)$/gi, '$1$2ves'],
+  [/(hive)$/gi, '$1s'],
+  [/([^aeiouy]|qu)y$/gi, '$1ies'],
+  [/(x|ch|ss|sh)$/gi, '$1es'],
+  [/(matr|vert|ind)ix|ex$/gi, '$1ices'],
+  [/([m|l])ouse$/gi, '$1ice'],
+  [/(kn|w|l)ife$/gi, '$1ives'],
+  [/(quiz)$/gi, '$1zes'],
+  [/^goose$/i, 'geese'],
+  [/s$/gi, 's'],
+  [/([^a-z])$/, '$1'],
+  [/$/gi, 's'],
+];
+
+const UNCOUNTABLES = new Set([
+  'advice',
+  'energy',
+  'excretion',
+  'digestion',
+  'cooperation',
+  'health',
+  'justice',
+  'labour',
+  'machinery',
+  'equipment',
+  'information',
+  'pollution',
+  'sewage',
+  'paper',
+  'money',
+  'species',
+  'series',
+  'rain',
+  'rice',
+  'fish',
+  'sheep',
+  'moose',
+  'deer',
+  'news',
+  'expertise',
+  'status',
+  'media',
+]);
+
+/** Mongoose's legacy pluralizer: lowercased, then the first matching rule */
+export function legacyPluralize(name: string): string {
+  const lower = name.toLowerCase();
+  if (UNCOUNTABLES.has(lower)) {
+    return lower;
+  }
+  const rule = RULES.find(([pattern]) => lower.match(pattern));
+  return rule ? lower.replace(rule[0], rule[1]) : lower;
+}