@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/sql/sql-schema.shared.ts

@@ -0,0 +1,105 @@
+import { defaultCollectionName } from '../mongo/collection-name.js';
+import type { FieldDescriptor, ModelDescriptor } from '../model-descriptor.interface.js';
+import { columnName } from './sql-naming.js';
+
+/**
+ * The dialect-free half of the SQL schema (plan §3.12): how a model names its table and the framework names its
+ * indexes and constraints, the lease table every SQL schema carries, and how a schema change is reported. The
+ * PostgreSQL and MySQL / MariaDB compilers share it, so a model has one table name on every SQL database.
+ */
+
+const lockField = (name: string, kind: 'date' | 'id' | 'string'): FieldDescriptor => ({
+  hasDefault: false,
+  index: false,
+  isArray: false,
+  kind,
+  lowercase: false,
+  name,
+  required: false,
+  select: true,
+  sparse: false,
+  trim: false,
+  unique: false,
+});
+
+/** The framework's lease table (`PostgresLockStore`), created with every SQL schema */
+export const LOCK_MODEL: ModelDescriptor = Object.freeze({
+  collection: 'lt_locks',
+  fields: {
+    _id: lockField('_id', 'id'),
+    acquiredAt: lockField('acquiredAt', 'date'),
+    expiresAt: lockField('expiresAt', 'date'),
+    owner: lockField('owner', 'string'),
+  },
+  indexes: [],
+  name: 'LtLock',
+  tenantScoped: false,
+  timestamps: false,
+});
+
+/**
+ * The table of a model: the collection MongoDB would use, in snake_case. A hyphen becomes an underscore (`s3-files` →
+ * `s3_files`): MongoDB allows it in a collection name, SQL not in an unquoted identifier
+ */
+export function tableName(model: ModelDescriptor): string {
+  const collection = model.collection ?? defaultCollectionName(model.name);
+  return columnName(collection.replace(/-/g, '_'));
+}
+
+/** `prefix_table__parts`, shortened with a hash when it would exceed Postgres' 63-character identifier limit */
+export function shortName(prefix: string, table: string, parts: string[]): string {
+  const full = `${prefix}_${table}__${parts.join('_')}`;
+  return full.length <= 63 ? full : `${full.slice(0, 54)}_${schemaHash(full)}`;
+}
+
+/** FNV-1a, 8 hex characters: a stable short name for a definition */
+export function schemaHash(text: string): string {
+  let value = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    value ^= text.charCodeAt(i);
+    value = Math.imul(value, 0x01000193) >>> 0;
+  }
+  return value.toString(16).padStart(8, '0');
+}
+
+export type SchemaChangeKind = 'automatic' | 'migration' | 'notice';
+
+export interface SchemaChange {
+  description: string;
+  kind: SchemaChangeKind;
+  /** What would apply it (for `migration`: the suggestion `migrate:create --sql` writes) */
+  statements: string[];
+  table?: string;
+}
+
+export class SchemaMigrationRequiredError extends Error {
+  override readonly name = 'SchemaMigrationRequiredError';
+
+  constructor(readonly changes: SchemaChange[]) {
+    super(
+      `The database schema needs changes that are never applied automatically:\n${changes
+        .map(
+          (change) =>
+            `  - ${change.description}${change.statements.map((statement) => `\n      suggested: ${statement}`).join('')}`,
+        )
+        .join('\n')}\n` +
+        'Write a migration for them (`migrate create <name> --sql`), review the suggested statements — they may ' +
+        'rewrite or reject stored rows — and run it before this version starts.',
+    );
+  }
+}
+
+export class SchemaOutOfDateError extends Error {
+  override readonly name = 'SchemaOutOfDateError';
+
+  constructor(readonly changes: SchemaChange[]) {
+    super(
+      `The database schema is not up to date and no owner connection is configured to update it:\n${changes.map((change) => `  - ${change.description}`).join('\n')}\n` +
+        'Configure `database.ownerUrl` (the role that owns the tables) or apply the changes with the migration runner.',
+    );
+  }
+}
+
+export class UnsafeDatabaseRoleError extends Error {
+  override readonly name = 'UnsafeDatabaseRoleError';
+}

package/src/core/common/persistence/sql/sql-session.ts

@@ -0,0 +1,158 @@
+import { Logger } from '@nestjs/common';
+
+import type { SqlQueryResult, SqlStatement, SqlTenantScope } from './sql-executor.interface.js';
+
+/**
+ * Connection-level safety and the per-statement tenant scope, shared by every SQL engine.
+ *
+ * Both are framework-owned on purpose: an engine that hands a broken connection back to its pool, or a scope
+ * that outlives its transaction, would leak one request's tenant into the next (plan §3.4, A10).
+ */
+
+/**
+ * Writes the tenant scope into the CURRENT transaction (`is_local = true`): it ends with the transaction and can
+ * never reach the next statement on a pooled connection. One statement for all three settings, so applying the
+ * scope costs nothing beyond the pipeline it travels in.
+ */
+export const APPLY_SCOPE_SQL =
+  "SELECT set_config('app.tenant_scope', $1, true), set_config('app.tenant_id', $2, true), set_config('app.tenant_ids', $3, true)";
+
+/** The three settings for a scope, in the order of {@link APPLY_SCOPE_SQL}'s parameters. */
+export function scopeParams(scope: SqlTenantScope): [string, string, string] {
+  switch (scope.kind) {
+    case 'system':
+      return ['system', '', ''];
+    case 'tenant':
+      return ['tenant', scope.tenantId, ''];
+    case 'tenants':
+      return ['tenants', '', JSON.stringify(scope.tenantIds)];
+    default:
+      return ['none', '', ''];
+  }
+}
+
+type ErrorListener = (error: Error) => void;
+
+interface PgClientLike {
+  _activeQuery?: unknown;
+  _queryQueue?: unknown[];
+  _sentQueryQueue?: unknown[];
+  getTransactionStatus?(): null | string;
+  on?(event: 'error', listener: ErrorListener): unknown;
+  query(text: string, params?: readonly unknown[]): Promise<{ rowCount: null | number; rows: any[] }>;
+  release(error?: Error | boolean): void;
+  removeListener?(event: 'error', listener: ErrorListener): unknown;
+}
+
+interface PgPoolLike {
+  connect(): Promise<PgClientLike>;
+  connect(
+    callback: (error: Error | undefined, client: PgClientLike, release: (error?: Error | boolean) => void) => void,
+  ): void;
+  listenerCount?(event: 'error'): number;
+  on?(event: 'error', listener: ErrorListener): unknown;
+}
+
+const poolLogger = new Logger('SqlPool');
+const guardedPools = new WeakSet<object>();
+
+/** Whether {@link guardPool} protects `pool`. */
+export function isGuardedPool(pool: unknown): boolean {
+  return typeof pool === 'object' && pool !== null && guardedPools.has(pool);
+}
+
+/**
+ * Make a node-postgres pool destroy every connection that is handed back inside a transaction, with a query still
+ * in flight, or after it died, instead of re-using it — and keep a dying connection from ending the process.
+ *
+ * Measured (A10): after a client-side query timeout TypeORM 1.1 released broken connections (the pool then hung)
+ * and Kysely 0.29 released a connection still inside the dead transaction — the next request read the previous
+ * request's tenant. pg-pool binds `client.release` after emitting `acquire`, so the guard wraps `connect` and covers
+ * both the promise form (Kysely, Drizzle, the framework) and the callback form (TypeORM).
+ *
+ * "In flight" is node-postgres' own busy test: an active query, or one queued or already sent — on a pipelined
+ * client the sent ones wait in `_sentQueryQueue`, not in `_activeQuery`.
+ *
+ * pg-pool listens for `error` only on IDLE connections. A connection that dies while checked out — terminated by
+ * the server, or destroyed by node-postgres itself when a pipelined query times out — emits `error` with nobody
+ * listening, and Node ends the process on an unhandled `error` event. The guard listens for the whole checkout and
+ * hands that error to the release, so the pool destroys the connection. An IDLE connection's error is re-emitted
+ * by the pool, which is just as fatal without a listener: Kysely and Drizzle attach none (TypeORM does, and keeps
+ * its own), so the guard adds one where nobody listens.
+ */
+export function guardPool<P>(pool: P): P {
+  const target = pool as unknown as PgPoolLike;
+  if (guardedPools.has(target)) {
+    return pool;
+  }
+  const connect = target.connect.bind(target) as (...args: any[]) => any;
+  const unhealthy = (client: PgClientLike): Error | undefined =>
+    (client.getTransactionStatus?.() ?? 'I') !== 'I' ||
+    client._activeQuery ||
+    client._sentQueryQueue?.length ||
+    client._queryQueue?.length
+      ? new Error('released inside a transaction or with a query in flight')
+      : undefined;
+  const wrap = (client: PgClientLike) => {
+    const release = client.release.bind(client);
+    let died: Error | undefined;
+    const onError: ErrorListener = (error) => {
+      died = error;
+    };
+    client.on?.('error', onError);
+    client.release = (error?: Error | boolean) => {
+      client.removeListener?.('error', onError);
+      return release(error ?? died ?? unhealthy(client));
+    };
+    return client.release;
+  };
+  (target as any).connect = (callback?: (...args: any[]) => void) =>
+    typeof callback === 'function'
+      ? connect((error: Error | undefined, client: PgClientLike, release: any) =>
+          callback(error, client, error ? release : wrap(client)),
+        )
+      : connect().then((client: PgClientLike) => {
+          wrap(client);
+          return client;
+        });
+  if (!target.listenerCount?.('error')) {
+    target.on?.('error', (error) =>
+      poolLogger.warn(`An idle database connection failed and was removed from the pool: ${error.message}`),
+    );
+  }
+  guardedPools.add(target);
+  return pool;
+}
+
+/**
+ * Run ONE statement in its own transaction with `scope` applied: `BEGIN` · scope · statement · `COMMIT`, pipelined
+ * into a single round trip on a pool created with `pipeline: true` (plan §3.8, A13).
+ *
+ * Every step is awaited before the connection goes back, so the pool never receives a connection mid-pipeline. A
+ * failed statement aborts the transaction; Postgres then answers the `COMMIT` with a rollback, and the statement's
+ * own error is what the caller sees.
+ */
+export async function runInOwnTransaction<R>(
+  pool: unknown,
+  statement: SqlStatement,
+  scope: SqlTenantScope,
+): Promise<SqlQueryResult<R>> {
+  const client = await (pool as PgPoolLike).connect();
+  try {
+    const [begin, applied, result, commit] = await Promise.allSettled([
+      client.query('BEGIN'),
+      client.query(APPLY_SCOPE_SQL, scopeParams(scope)),
+      client.query(statement.text, statement.params),
+      client.query('COMMIT'),
+    ]);
+    for (const step of [begin, applied, result, commit]) {
+      if (step.status === 'rejected') {
+        throw step.reason;
+      }
+    }
+    const value = (result as PromiseFulfilledResult<{ rowCount: null | number; rows: R[] }>).value;
+    return { rowCount: value.rowCount ?? value.rows.length, rows: value.rows };
+  } finally {
+    client.release();
+  }
+}

package/src/core/common/persistence/sql/where-shared.ts

@@ -0,0 +1,118 @@
+import type { FieldDescriptor, FieldKind } from '../model-descriptor.interface.js';
+import { UnsupportedQueryError } from './sql-errors.js';
+import { isPathSegment } from './sql-naming.js';
+
+/**
+ * The dialect-free half of the filter compilers (`postgres/postgres-where.compiler.ts`, `mysql/mysql-where.compiler.ts`):
+ * what a filter MEANS — which values are operator objects, which paths are valid, which BSON type a `$type` names — so
+ * every SQL database reads a filter the same way and only the SQL it compiles to differs.
+ */
+
+export const SCALAR_KINDS = new Set<FieldKind>([
+  'bigint',
+  'boolean',
+  'buffer',
+  'date',
+  'decimal',
+  'enum',
+  'id',
+  'number',
+  'ref',
+  'string',
+  'uuid',
+]);
+export const REGEX_KINDS = new Set<FieldKind>(['enum', 'ref', 'string']);
+export const COMPARISON = { $gt: '>', $gte: '>=', $lt: '<', $lte: '<=' } as const;
+export type ComparisonOperator = keyof typeof COMPARISON;
+
+export type BsonType = 'array' | 'bool' | 'date' | 'null' | 'number' | 'object' | 'objectId' | 'string';
+
+const BSON_TYPE_ALIASES: Record<number | string, BsonType> = {
+  1: 'number',
+  10: 'null',
+  16: 'number',
+  18: 'number',
+  19: 'number',
+  2: 'string',
+  3: 'object',
+  4: 'array',
+  7: 'objectId',
+  8: 'bool',
+  9: 'date',
+  array: 'array',
+  bool: 'bool',
+  date: 'date',
+  decimal: 'number',
+  double: 'number',
+  int: 'number',
+  long: 'number',
+  null: 'null',
+  number: 'number',
+  object: 'object',
+  objectId: 'objectId',
+  string: 'string',
+};
+
+/** Which column kinds hold a value of a BSON type */
+export const COLUMN_TYPES: Partial<Record<BsonType, (field: FieldDescriptor) => boolean>> = {
+  bool: (field) => field.kind === 'boolean',
+  date: (field) => field.kind === 'date',
+  number: (field) =>
+    ['bigint', 'decimal', 'number'].includes(field.kind) || (field.kind === 'enum' && field.enumBase === 'number'),
+  objectId: (field) => field.kind === 'id' || field.kind === 'ref',
+  string: (field) => ['string', 'uuid'].includes(field.kind) || (field.kind === 'enum' && field.enumBase !== 'number'),
+};
+
+export function bsonType(path: string, value: unknown): BsonType {
+  const type =
+    (typeof value === 'string' || typeof value === 'number') &&
+    Object.prototype.hasOwnProperty.call(BSON_TYPE_ALIASES, value)
+      ? BSON_TYPE_ALIASES[value]
+      : undefined;
+  if (!type) {
+    throw new UnsupportedQueryError(`$type ${JSON.stringify(value)} at "${path}"`);
+  }
+  return type;
+}
+
+export function splitPath(path: string): string[] {
+  const segments = path.split('.');
+  for (const segment of segments) {
+    if (!isPathSegment(segment)) {
+      throw new UnsupportedQueryError(`Invalid path "${path}"`);
+    }
+  }
+  return segments;
+}
+
+export function itemOf(field: FieldDescriptor): FieldDescriptor {
+  return { ...field, isArray: false };
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** An object of operators. Mixing operators and fields is refused, as MongoDB refuses it. */
+export function isOperatorObject(value: unknown): boolean {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  const operators = keys.filter((key) => key.startsWith('$')).length;
+  if (operators && operators !== keys.length) {
+    throw new UnsupportedQueryError('An object may not mix operators and fields');
+  }
+  return operators > 0;
+}
+
+/** JSON for a JSON parameter: dates as ISO strings and ids as hex (their `toJSON`), bigints as numbers or strings */
+export function toJson(value: unknown): string {
+  return JSON.stringify(value, (_key, item) =>
+    typeof item === 'bigint' ? (Number.isSafeInteger(Number(item)) ? Number(item) : item.toString()) : item,
+  );
+}

package/src/core/common/persistence/store-guards.ts

@@ -0,0 +1,73 @@
+import { UnsupportedQueryError } from './sql/sql-errors.js';
+
+/**
+ * Argument checks every data store applies the same way, so a call refused on one database is refused on all.
+ */
+
+/** native() / raw(): the reason is logged, so it has to say something */
+export function assertAccessReason(reason: string, method: string): void {
+  if (!reason?.trim() || reason.trim().length < 20) {
+    throw new Error(`${method}() requires a meaningful reason (min 20 chars) — explain why native access is needed`);
+  }
+}
+
+/** find({ sample }): a positive integer — MongoDB refuses anything else in `$sample`, so every store does */
+export function assertSampleSize(sample: unknown): number {
+  if (typeof sample !== 'number' || !Number.isInteger(sample) || sample < 1) {
+    throw new Error(`sample must be a positive integer, got ${String(sample)}`);
+  }
+  return sample;
+}
+
+/** A whole number for a SQL clause (`limit`, `skip`, a push `position` or `slice`) */
+export function assertInteger(value: unknown, name: string): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new UnsupportedQueryError(`${name} must be an integer`);
+  }
+  return value;
+}
+
+export function assertNonNegativeInteger(value: unknown, name: string): number {
+  const result = assertInteger(value, name);
+  if (result < 0) {
+    throw new UnsupportedQueryError(`${name} must not be negative`);
+  }
+  return result;
+}
+
+/** pushToArray() / pullFromArray(): a field name, never an operator */
+export function assertArrayField(field: string, method: string): void {
+  if (typeof field !== 'string' || !field || field.startsWith('$') || field.includes('\0')) {
+    throw new Error(`${method}: invalid field name "${field}"`);
+  }
+}
+
+const SELECTABLE = /^[A-Za-z_]\w*$/;
+
+/**
+ * `select`: plain field names only. MongoDB joins them into a projection string, where `+name` forces a
+ * `select: false` field (a password hash) into the result and `-name` turns the projection into an exclusion —
+ * a caller passing names through must not be able to do either by accident.
+ */
+export function assertSelectFields(select: readonly string[] | undefined): void {
+  for (const field of select ?? []) {
+    if (typeof field !== 'string' || !SELECTABLE.test(field)) {
+      throw new Error(`select: invalid field name "${String(field)}"`);
+    }
+  }
+}
+
+/**
+ * `select` and `exclude` together: plain field names each, and never both — MongoDB refuses a projection that
+ * includes and excludes at once. The id cannot be left out: every record carries it.
+ */
+export function assertProjection(options: { exclude?: readonly string[]; select?: readonly string[] }): void {
+  assertSelectFields(options.select);
+  assertSelectFields(options.exclude);
+  if (options.select?.length && options.exclude?.length) {
+    throw new Error('select and exclude cannot be combined');
+  }
+  if (options.exclude?.some((field) => field === 'id' || field === '_id')) {
+    throw new Error('exclude: the id is always returned');
+  }
+}

package/src/core/common/persistence/store-upsert.ts

@@ -0,0 +1,36 @@
+import type { DataStore, StoredRecord, Where } from './data-store.interface.js';
+
+/**
+ * Set fields on the record matching `where`, or create it — MongoDB's `updateOne(…, { upsert: true })` on any store.
+ *
+ * The store port has no upsert of its own (an `INSERT … ON CONFLICT` needs the conflict target, which only the caller
+ * knows), so this composes it: an atomic `updateOne`, and an `insert` when nothing matched. `where` must name a unique
+ * key of the model — that index is what turns a concurrent second insert into a duplicate-key error, after which the
+ * record exists and the update is applied to it.
+ *
+ * `onInsert` are fields only a new record gets (MongoDB's `$setOnInsert`).
+ */
+export async function upsertRecord<T>(
+  store: DataStore<T>,
+  where: Where<T> & Record<string, unknown>,
+  set: Record<string, unknown>,
+  onInsert: Record<string, unknown> = {},
+): Promise<StoredRecord<T>> {
+  const updated = await store.updateOne(where, { $set: set } as any);
+  if (updated) {
+    return updated;
+  }
+  try {
+    return await store.insert({ ...where, ...onInsert, ...set } as any);
+  } catch (error) {
+    if ((error as { code?: unknown })?.code !== 11000) {
+      throw error;
+    }
+    // Another caller created it between the two steps: it exists now
+    const retried = await store.updateOne(where, { $set: set } as any);
+    if (!retried) {
+      throw error;
+    }
+    return retried;
+  }
+}

package/src/core/common/persistence/unavailable-store.ts

@@ -0,0 +1,63 @@
+import type { DataStore } from './data-store.interface.js';
+import { UnsupportedCapabilityError } from './unsupported-capability.error.js';
+
+/** The data methods of the `DataStore` port */
+const STORE_METHODS = new Set([
+  'count',
+  'deleteById',
+  'deleteMany',
+  'deleteOne',
+  'distinct',
+  'find',
+  'findById',
+  'findOne',
+  'insert',
+  'native',
+  'pullFromArray',
+  'pushToArray',
+  'raw',
+  'sum',
+  'updateById',
+  'updateMany',
+  'updateOne',
+]);
+
+/**
+ * The store of a model no database can hold — the project runs with `database: false`, so a model registered with
+ * `CorePersistenceModule.forFeature()` (the framework registers its file metadata, for one) has nowhere to go. Every
+ * data method refuses with the reason; nothing fails while the application merely boots.
+ */
+export function unavailableStore<T = Record<string, any>>(modelName: string, reason: string): DataStore<T> {
+  const capabilities = {
+    aggregatePipeline: false,
+    changeFeed: false,
+    gridfs: false,
+    idType: 'objectId' as const,
+    mongoosePopulate: false,
+    rawFilterArm: false,
+    rls: false,
+    textSearch: false,
+    transactions: false,
+  };
+  return new Proxy({} as DataStore<T>, {
+    get(_target, property) {
+      if (property === 'modelName') {
+        return modelName;
+      }
+      if (property === 'driver') {
+        return 'none';
+      }
+      if (property === 'capabilities') {
+        return capabilities;
+      }
+      // Only the port's methods refuse: Nest probes every provider for lifecycle hooks (`onModuleInit`, …), and a
+      // promise check reads `then` — those must find nothing
+      if (typeof property !== 'string' || !STORE_METHODS.has(property)) {
+        return undefined;
+      }
+      return () => {
+        throw new UnsupportedCapabilityError(`${modelName}.${property}(): ${reason}`);
+      };
+    },
+  });
+}

package/src/core/common/persistence/unsupported-capability.error.ts

@@ -0,0 +1,7 @@
+/**
+ * An operation the model's data store cannot perform (plan §3.6: features ask the store, never the driver name).
+ * Named, so a call that would need MongoDB on a SQL-stored model fails loudly instead of reaching another database.
+ */
+export class UnsupportedCapabilityError extends Error {
+  override readonly name = 'UnsupportedCapabilityError';
+}