@lenne.tech/nest-server 11.2.0 → 11.4.0

package/src/core/modules/migrate/migration-runner.ts

@@ -0,0 +1,230 @@
+/* eslint-disable no-console */
+// Console output is required for migration runner feedback
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { MongoStateStore } from './mongo-state-store';
+
+/**
+ * Migration file interface
+ */
+export interface MigrationFile {
+  /** Down function */
+  down?: () => Promise<void>;
+  /** File path */
+  filePath: string;
+  /** Timestamp when migration was created */
+  timestamp: number;
+  /** Migration name/title */
+  title: string;
+  /** Up function */
+  up: () => Promise<void>;
+}
+
+/**
+ * Migration runner configuration
+ */
+export interface MigrationRunnerOptions {
+  /** Directory containing migration files */
+  migrationsDirectory: string;
+  /** Pattern to match migration files (default: *.ts, *.js) */
+  pattern?: RegExp;
+  /** State store for tracking migrations */
+  stateStore: MongoStateStore;
+}
+
+/**
+ * Simple migration runner for NestJS applications
+ *
+ * This provides a programmatic way to run migrations without requiring the `migrate` CLI.
+ * It's a lightweight alternative for projects that want to run migrations from code.
+ *
+ * @example
+ * ```typescript
+ * import { MigrationRunner, MongoStateStore } from '@lenne.tech/nest-server';
+ *
+ * const runner = new MigrationRunner({
+ *   stateStore: new MongoStateStore('mongodb://localhost/mydb'),
+ *   migrationsDirectory: './migrations'
+ * });
+ *
+ * // Run all pending migrations
+ * await runner.up();
+ *
+ * // Rollback last migration
+ * await runner.down();
+ * ```
+ */
+export class MigrationRunner {
+  private options: MigrationRunnerOptions;
+  private pattern: RegExp;
+
+  constructor(options: MigrationRunnerOptions) {
+    this.options = options;
+    this.pattern = options.pattern || /\.(ts|js)$/;
+  }
+
+  /**
+   * Load all migration files from the migrations directory
+   */
+  private async loadMigrationFiles(): Promise<MigrationFile[]> {
+    const files = fs
+      .readdirSync(this.options.migrationsDirectory)
+      .filter((file) => this.pattern.test(file))
+      .sort(); // Sort alphabetically (timestamp-based filenames will be in order)
+
+    const migrations: MigrationFile[] = [];
+
+    for (const file of files) {
+      const filePath = path.join(this.options.migrationsDirectory, file);
+
+      const module = require(filePath);
+
+      if (!module.up) {
+        console.warn(`Migration ${file} has no 'up' function, skipping...`);
+        continue;
+      }
+
+      // Extract timestamp from filename (format: TIMESTAMP-name.js)
+      const timestampMatch = file.match(/^(\d+)-/);
+      const timestamp = timestampMatch ? parseInt(timestampMatch[1], 10) : Date.now();
+
+      migrations.push({
+        down: module.down,
+        filePath,
+        timestamp,
+        title: file,
+        up: module.up,
+      });
+    }
+
+    return migrations;
+  }
+
+  /**
+   * Run all pending migrations (up)
+   */
+  async up(): Promise<void> {
+    const allMigrations = await this.loadMigrationFiles();
+    const state = await this.options.stateStore.loadAsync();
+    const completedMigrations = (state.migrations || []).map((m) => m.title);
+
+    const pendingMigrations = allMigrations.filter((m) => !completedMigrations.includes(m.title));
+
+    if (pendingMigrations.length === 0) {
+      console.log('No pending migrations');
+      return;
+    }
+
+    console.log(`Running ${pendingMigrations.length} pending migration(s)...`);
+
+    for (const migration of pendingMigrations) {
+      console.log(`Running migration: ${migration.title}`);
+      await migration.up();
+
+      // Update state
+      const newState = await this.options.stateStore.loadAsync();
+      const migrations = newState.migrations || [];
+      migrations.push({
+        timestamp: migration.timestamp,
+        title: migration.title,
+      });
+
+      await this.options.stateStore.saveAsync({
+        lastRun: migration.title,
+        migrations,
+        up: () => {},
+      } as any);
+
+      console.log(`✓ Migration completed: ${migration.title}`);
+    }
+
+    console.log('All migrations completed successfully');
+  }
+
+  /**
+   * Rollback the last migration (down)
+   */
+  async down(): Promise<void> {
+    const state = await this.options.stateStore.loadAsync();
+    const completedMigrations = state.migrations || [];
+
+    if (completedMigrations.length === 0) {
+      console.log('No migrations to rollback');
+      return;
+    }
+
+    const lastMigration = completedMigrations[completedMigrations.length - 1];
+    const allMigrations = await this.loadMigrationFiles();
+    const migrationToRollback = allMigrations.find((m) => m.title === lastMigration.title);
+
+    if (!migrationToRollback) {
+      throw new Error(`Migration file not found: ${lastMigration.title}`);
+    }
+
+    if (!migrationToRollback.down) {
+      throw new Error(`Migration ${lastMigration.title} has no 'down' function`);
+    }
+
+    console.log(`Rolling back migration: ${migrationToRollback.title}`);
+    await migrationToRollback.down();
+
+    // Update state
+    const newMigrations = completedMigrations.slice(0, -1);
+    await this.options.stateStore.saveAsync({
+      lastRun: newMigrations.length > 0 ? newMigrations[newMigrations.length - 1].title : undefined,
+      migrations: newMigrations,
+      up: () => {},
+    } as any);
+
+    console.log(`✓ Migration rolled back: ${migrationToRollback.title}`);
+  }
+
+  /**
+   * Get migration status
+   */
+  async status(): Promise<{
+    completed: string[];
+    pending: string[];
+  }> {
+    const allMigrations = await this.loadMigrationFiles();
+    const state = await this.options.stateStore.loadAsync();
+    const completedMigrations = (state.migrations || []).map((m) => m.title);
+
+    return {
+      completed: completedMigrations,
+      pending: allMigrations.filter((m) => !completedMigrations.includes(m.title)).map((m) => m.title),
+    };
+  }
+
+  /**
+   * Create a new migration file
+   */
+  static async create(migrationsDirectory: string, name: string): Promise<string> {
+    const timestamp = Date.now();
+    const fileName = `${timestamp}-${name}.ts`;
+    const filePath = path.join(migrationsDirectory, fileName);
+
+    const template = `/**
+ * Migration: ${name}
+ * Created: ${new Date().toISOString()}
+ */
+
+export const up = async () => {
+  // TODO: Implement migration
+  console.log('Running migration: ${name}');
+};
+
+export const down = async () => {
+  // TODO: Implement rollback
+  console.log('Rolling back migration: ${name}');
+};
+`;
+
+    fs.writeFileSync(filePath, template, 'utf-8');
+    console.log(`✓ Created migration: ${fileName}`);
+
+    return filePath;
+  }
+}

package/src/core/modules/migrate/mongo-state-store.ts

@@ -0,0 +1,283 @@
+import { Db, MongoClient } from 'mongodb';
+import { promisify } from 'util';
+
+/**
+ * Migration options interface (compatible with migrate package)
+ */
+export interface MigrationOptions {
+  [key: string]: unknown;
+  stateStore: MongoStateStore;
+}
+
+/**
+ * Migration set interface (compatible with migrate package)
+ */
+export interface MigrationSet {
+  down?: (done?: (err?: Error) => void) => void;
+  lastRun?: string;
+  migrations: Array<{ timestamp?: number; title: string }>;
+  up: (done?: (err?: Error) => void) => void;
+}
+
+/**
+ * Options for MongoStateStore configuration
+ */
+export interface MongoStateStoreOptions {
+  /** Name of the collection to store migration state (default: 'migrations') */
+  collectionName?: string;
+  /**
+   * Optionally specify a collection to use for locking. This is intended for
+   * clusters with multiple nodes to ensure that not more than one migration
+   * can run at any given time. You must use the `synchronizedMigration` or
+   * `synchronizedUp` function, instead of triggering the migration via
+   * `migrate` directly.
+   */
+  lockCollectionName?: string;
+  /** MongoDB connection URI */
+  uri: string;
+}
+
+/**
+ * MongoDB State Store for migration state management
+ *
+ * This class provides a MongoDB-based state store for migration frameworks,
+ * allowing migration states to be persisted directly in MongoDB instead of
+ * in separate files. It supports MongoDB 6+ and provides a locking mechanism
+ * for clustered environments.
+ *
+ * @example
+ * ```typescript
+ * const stateStore = new MongoStateStore('mongodb://localhost/mydb');
+ * // or with options
+ * const stateStore = new MongoStateStore({
+ *   uri: 'mongodb://localhost/mydb',
+ *   collectionName: 'custom_migrations',
+ *   lockCollectionName: 'migration_lock'
+ * });
+ * ```
+ */
+export class MongoStateStore {
+  /** Collection name for storing migration state */
+  private readonly collectionName: string;
+
+  /** MongoDB connection URI */
+  readonly mongodbHost: string;
+
+  /** Optional collection name for locking mechanism */
+  readonly lockCollectionName?: string;
+
+  /**
+   * Creates a new MongoStateStore instance
+   *
+   * @param objectOrHost - MongoDB URI string or configuration object
+   */
+  constructor(objectOrHost: MongoStateStoreOptions | string) {
+    this.mongodbHost = typeof objectOrHost === 'string' ? objectOrHost : objectOrHost.uri;
+    this.collectionName =
+      typeof objectOrHost === 'string' ? 'migrations' : (objectOrHost.collectionName ?? 'migrations');
+    this.lockCollectionName = typeof objectOrHost !== 'string' ? objectOrHost.lockCollectionName : undefined;
+  }
+
+  /**
+   * Loads the migration state from MongoDB
+   *
+   * @param fn - Callback function receiving error or migration set
+   */
+  load(fn: (err?: Error, set?: MigrationSet) => void): void {
+    this.loadAsync()
+      .then((result) => fn(undefined, result))
+      .catch((err) => fn(err));
+  }
+
+  /**
+   * Loads the migration state from MongoDB (async version)
+   *
+   * @returns Promise with migration set
+   */
+  async loadAsync(): Promise<MigrationSet> {
+    return dbRequest(this.mongodbHost, async (db) => {
+      const result = await db.collection(this.collectionName).find({}).toArray();
+
+      if (result.length > 1) {
+        throw new Error(`Expected exactly one result, but got ${result.length}`);
+      }
+
+      if (result.length === 0) {
+        console.debug('No migrations found, probably running the very first time');
+        // Return empty object for compatibility with @nodepit/migrate-state-store-mongodb
+        return {} as MigrationSet;
+      }
+
+      return result[0] as unknown as MigrationSet;
+    });
+  }
+
+  /**
+   * Saves the migration state to MongoDB
+   *
+   * @param set - Migration set to save
+   * @param fn - Callback function receiving optional error
+   */
+  save(set: MigrationSet, fn: (err?: Error) => void): void {
+    this.saveAsync(set)
+      .then(() => fn())
+      .catch((err) => fn(err));
+  }
+
+  /**
+   * Saves the migration state to MongoDB (async version)
+   *
+   * @param set - Migration set to save
+   */
+  async saveAsync(set: MigrationSet): Promise<void> {
+    const { lastRun, migrations } = set;
+    await dbRequest(this.mongodbHost, async (db) => {
+      await db.collection(this.collectionName).replaceOne({}, { lastRun, migrations }, { upsert: true });
+    });
+  }
+}
+
+/**
+ * Wraps migrations with a lock to prevent simultaneous execution in clustered environments
+ *
+ * This function ensures that only one instance can run migrations at a time by using
+ * a MongoDB-based locking mechanism. To use this functionality, you must set the
+ * `lockCollectionName` in the `MongoStateStore` options.
+ *
+ * @param opts - Migration options including state store
+ * @param callback - Callback function that receives the migration set
+ * @throws Error if state store is not configured correctly
+ *
+ * @example
+ * ```typescript
+ * await synchronizedMigration({
+ *   stateStore: new MongoStateStore({
+ *     uri: 'mongodb://localhost/db',
+ *     lockCollectionName: 'migrationlock'
+ *   })
+ * }, async (migrationSet) => {
+ *   // Only one instance at a time will execute this
+ *   await promisify(migrationSet.up).call(migrationSet);
+ * });
+ * ```
+ */
+export async function synchronizedMigration(
+  opts: MigrationOptions,
+  callback: (set: MigrationSet) => Promise<void>,
+): Promise<void> {
+  if (!opts.stateStore) {
+    throw new Error('No `stateStore` in migration options');
+  }
+
+  const stateStore = opts.stateStore;
+
+  if (!(stateStore instanceof MongoStateStore)) {
+    throw new Error('Given `stateStore` is not `MongoStateStore`');
+  }
+
+  const lockCollectionName = stateStore.lockCollectionName;
+
+  if (typeof lockCollectionName !== 'string') {
+    throw new Error('`lockCollectionName` in MongoStateStore is not set');
+  }
+
+  try {
+    await acquireLock(stateStore.mongodbHost, lockCollectionName);
+
+    // Load migration set using async method
+    const set = await stateStore.loadAsync();
+    await callback(set);
+  } finally {
+    await releaseLock(stateStore.mongodbHost, lockCollectionName);
+  }
+}
+
+/**
+ * Executes all pending migrations in a synchronized manner (for clustered environments)
+ *
+ * This is a convenience function that wraps `synchronizedMigration` and automatically
+ * calls the `up` method on the migration set.
+ *
+ * @param opts - Migration options including state store
+ * @throws Error if state store is not configured correctly
+ *
+ * @example
+ * ```typescript
+ * await synchronizedUp({
+ *   stateStore: new MongoStateStore({
+ *     uri: 'mongodb://localhost/db',
+ *     lockCollectionName: 'migrationlock'
+ *   })
+ * });
+ * ```
+ */
+export async function synchronizedUp(opts: MigrationOptions): Promise<void> {
+  await synchronizedMigration(opts, async (loadedSet) => {
+    await promisify(loadedSet.up).call(loadedSet);
+  });
+}
+
+/**
+ * Acquires a lock in MongoDB to ensure only one migration runs at a time
+ *
+ * @param url - MongoDB connection URI
+ * @param lockCollectionName - Name of the collection to use for locking
+ */
+async function acquireLock(url: string, lockCollectionName: string): Promise<void> {
+  await dbRequest(url, async (db) => {
+    const collection = db.collection(lockCollectionName);
+
+    // Create unique index for atomicity
+    // https://docs.mongodb.com/manual/reference/method/db.collection.update/#use-unique-indexes
+    // https://groups.google.com/forum/#!topic/mongodb-user/-fucdS-7kIU
+    // https://stackoverflow.com/questions/33346175/mongodb-upsert-operation-seems-not-atomic-which-throws-duplicatekeyexception/34784533
+    await collection.createIndex({ lock: 1 }, { unique: true });
+
+    let showMessage = true;
+
+    for (;;) {
+      // Use updateOne with upsert for atomic lock acquisition (same as original package)
+      const result = await collection.updateOne({ lock: 'lock' }, { $set: { lock: 'lock' } }, { upsert: true });
+      const lockAcquired = result.upsertedCount > 0;
+
+      if (lockAcquired) {
+        break;
+      }
+
+      if (showMessage) {
+        console.debug('Waiting for migration lock release …');
+        showMessage = false;
+      }
+
+      await promisify(setTimeout)(100);
+    }
+  });
+}
+
+/**
+ * Executes database operations with automatic connection management
+ *
+ * @param url - MongoDB connection URI
+ * @param callback - Callback function to execute with database instance
+ * @returns Promise with callback result
+ */
+async function dbRequest<T>(url: string, callback: (db: Db) => Promise<T> | T): Promise<T> {
+  let client: MongoClient | undefined;
+  try {
+    client = await MongoClient.connect(url);
+    const db = client.db();
+    return await callback(db);
+  } finally {
+    await client?.close();
+  }
+}
+
+/**
+ * Releases a migration lock in MongoDB
+ *
+ * @param url - MongoDB connection URI
+ * @param lockCollectionName - Name of the collection used for locking
+ */
+async function releaseLock(url: string, lockCollectionName: string): Promise<void> {
+  await dbRequest(url, (db) => db.collection(lockCollectionName).deleteOne({ lock: 'lock' }));
+}

package/src/core/modules/migrate/templates/migration-with-helper.template.ts

@@ -0,0 +1,72 @@
+// import { Db } from 'mongodb';
+
+/**
+ * Migration template with helper function
+ *
+ * This template uses the migration helper from @lenne.tech/nest-server.
+ * To use this template, you need to create a helper function in your project
+ * that returns the database connection.
+ *
+ * Example setup in your project's migrations-utils/db.ts:
+ * ```typescript
+ * import config from '../src/config.env';
+ * import { MongoClient } from 'mongodb';
+ *
+ * export const getDb = async () => {
+ *   const client = await MongoClient.connect(config.mongoose.uri);
+ *   return client.db();
+ * };
+ * ```
+ */
+
+// Import your project's database helper
+// import { getDb } from '../migrations-utils/db';
+
+// Or use the nest-server helper with your config:
+// import config from '../src/config.env';
+// import { getDb } from '@lenne.tech/nest-server';
+// const db = await getDb(config.mongoose.uri);
+
+/**
+ * Run migration
+ */
+export const up = async () => {
+  // const db: Db = await getDb();
+  /*
+    Code your update script here!
+
+    Example: Add a new field to all documents
+    await db.collection('users').updateMany(
+      { email: { $exists: false } },
+      { $set: { email: '' } }
+    );
+
+    Example: Create a new collection
+    await db.createCollection('new_collection');
+
+    Example: Create an index
+    await db.collection('users').createIndex({ email: 1 }, { unique: true });
+  */
+};
+
+/**
+ * Rollback migration
+ */
+export const down = async () => {
+  // const db: Db = await getDb();
+  /*
+    Code your downgrade script here!
+
+    Example: Remove the field added in up()
+    await db.collection('users').updateMany(
+      {},
+      { $unset: { email: '' } }
+    );
+
+    Example: Drop the collection
+    await db.dropCollection('new_collection');
+
+    Example: Drop the index
+    await db.collection('users').dropIndex('email_1');
+  */
+};

package/src/core/modules/migrate/templates/migration.template.ts

@@ -0,0 +1,59 @@
+import { Db } from 'mongodb';
+
+/**
+ * Migration template for nest-server
+ *
+ * This template can be used with the migrate CLI:
+ * migrate create --template-file ./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/templates/migration.template.js
+ *
+ * Or copy this file to your project's migrations-utils folder and customize it.
+ */
+
+/**
+ * Get database connection
+ *
+ * IMPORTANT: Replace this function with your actual database connection logic.
+ * This is a placeholder that should import your project's config.
+ */
+const getDb = async (): Promise<Db> => {
+  // TODO: Import your config and return the database connection
+  // Example:
+  // import config from '../src/config.env';
+  // const { MongoClient } = require('mongodb');
+  // const client = await MongoClient.connect(config.mongoose.uri);
+  // return client.db();
+
+  throw new Error(
+    'Please configure the getDb() function in this migration file or use the migration helper from @lenne.tech/nest-server',
+  );
+};
+
+/**
+ * Run migration
+ *
+ * Code your update script here!
+ */
+export const up = async () => {
+  const db: Db = await getDb();
+
+  // Example: Add a new field to all documents in a collection
+  // await db.collection('users').updateMany(
+  //   { email: { $exists: false } },
+  //   { $set: { email: '' } }
+  // );
+};
+
+/**
+ * Rollback migration
+ *
+ * Code your downgrade script here!
+ */
+export const down = async () => {
+  const db: Db = await getDb();
+
+  // Example: Remove the field added in the up() function
+  // await db.collection('users').updateMany(
+  //   {},
+  //   { $unset: { email: '' } }
+  // );
+};