@lenne.tech/nest-server 11.2.0 → 11.4.0

package/src/core/modules/migrate/cli/migrate-cli.ts

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+
+/**
+ * Migration CLI - Compatible with `migrate` package CLI
+ *
+ * This provides a drop-in replacement for the `migrate` CLI without requiring
+ * the external `migrate` package as a dependency.
+ *
+ * Usage (same as migrate package):
+ *   migrate create <name> [options]
+ *   migrate up [name] [options]
+ *   migrate down [name] [options]
+ *   migrate list [options]
+ *
+ * Options:
+ *   --migrations-dir, -d    Directory containing migrations (default: ./migrations)
+ *   --store, -s            Path to state store module
+ *   --compiler, -c         Compiler to use (e.g., ts:./path/to/ts-compiler.js)
+ *   --template-file, -t    Template file for creating migrations
+ */
+
+/* eslint-disable no-console */
+// Console output is required for CLI functionality
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { MigrationRunner } from '../migration-runner';
+import { MongoStateStore } from '../mongo-state-store';
+
+interface CliOptions {
+  compiler?: string;
+  migrationsDir: string;
+  store?: string;
+  templateFile?: string;
+}
+
+/**
+ * Create a new migration file
+ */
+async function createMigration(name: string, options: CliOptions) {
+  if (!name) {
+    console.error('Error: Migration name is required');
+    console.log('Usage: migrate create <name> [options]');
+    process.exit(1);
+  }
+
+  const timestamp = Date.now();
+  const fileName = `${timestamp}-${name}.ts`;
+  const filePath = path.join(options.migrationsDir, fileName);
+
+  // Create migrations directory if it doesn't exist
+  if (!fs.existsSync(options.migrationsDir)) {
+    fs.mkdirSync(options.migrationsDir, { recursive: true });
+  }
+
+  let template: string;
+
+  // Use custom template if provided
+  if (options.templateFile) {
+    const templatePath = path.resolve(process.cwd(), options.templateFile);
+    template = fs.readFileSync(templatePath, 'utf-8');
+  } else {
+    // Default template
+    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}`);
+}
+
+/**
+ * List migration status
+ */
+async function listMigrations(options: CliOptions) {
+  registerCompiler(options.compiler);
+  const stateStore = loadStateStore(options.store);
+
+  const runner = new MigrationRunner({
+    migrationsDirectory: options.migrationsDir,
+    stateStore,
+  });
+
+  const status = await runner.status();
+
+  console.log('\nMigration Status:');
+  console.log('=================\n');
+
+  if (status.completed.length > 0) {
+    console.log('Completed:');
+    status.completed.forEach((name) => {
+      console.log(`  ✓ ${name}`);
+    });
+    console.log('');
+  }
+
+  if (status.pending.length > 0) {
+    console.log('Pending:');
+    status.pending.forEach((name) => {
+      console.log(`  ⋯ ${name}`);
+    });
+    console.log('');
+  }
+
+  if (status.completed.length === 0 && status.pending.length === 0) {
+    console.log('No migrations found\n');
+  }
+}
+
+/**
+ * Load state store from module
+ */
+function loadStateStore(storePath: string | undefined): MongoStateStore {
+  if (!storePath) {
+    throw new Error('--store option is required for up/down/list commands');
+  }
+
+  const absolutePath = path.resolve(process.cwd(), storePath);
+
+  const StoreClass = require(absolutePath);
+
+  // Handle different export patterns
+  if (StoreClass.default) {
+    return new StoreClass.default();
+  } else if (typeof StoreClass === 'function') {
+    return new StoreClass();
+  } else {
+    throw new Error(`Invalid state store module at ${storePath}`);
+  }
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  const { command, name, options } = parseArgs();
+
+  try {
+    switch (command) {
+      case '--help':
+
+      case '-h':
+
+      case 'help':
+        showHelp();
+        break;
+
+      case 'create':
+        await createMigration(name!, options);
+        break;
+      case 'down':
+        await runDown(options);
+        break;
+
+      case 'list':
+      case 'status':
+        await listMigrations(options);
+        break;
+      case 'up':
+        await runUp(options);
+        break;
+
+      default:
+        if (!command) {
+          showHelp();
+        } else {
+          console.error(`Unknown command: ${command}`);
+          console.log('Run "migrate --help" for usage information');
+          process.exit(1);
+        }
+    }
+  } catch (error) {
+    console.error('Error:', (error as Error).message);
+    if (process.env.DEBUG) {
+      console.error((error as Error).stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(): { command: string; name?: string; options: CliOptions } {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  let name: string | undefined;
+  const options: CliOptions = {
+    migrationsDir: './migrations',
+  };
+
+  // Check if second arg is a name (not a flag)
+  if (args[1] && !args[1].startsWith('-')) {
+    name = args[1];
+  }
+
+  // Parse flags
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--migrations-dir' || arg === '-d') {
+      options.migrationsDir = args[++i];
+    } else if (arg === '--store' || arg === '-s') {
+      options.store = args[++i];
+    } else if (arg === '--compiler' || arg === '-c') {
+      options.compiler = args[++i];
+    } else if (arg === '--template-file' || arg === '-t') {
+      options.templateFile = args[++i];
+    }
+  }
+
+  return { command, name, options };
+}
+
+/**
+ * Register TypeScript compiler if specified
+ */
+function registerCompiler(compiler: string | undefined) {
+  if (!compiler) {
+    return;
+  }
+
+  // Format: "ts:./path/to/compiler.js"
+  const [type, compilerPath] = compiler.split(':');
+
+  if (type === 'ts' && compilerPath) {
+    const absolutePath = path.resolve(process.cwd(), compilerPath);
+
+    const register = require(absolutePath);
+    if (typeof register === 'function') {
+      register();
+    }
+  }
+}
+
+/**
+ * Run migrations down
+ */
+async function runDown(options: CliOptions) {
+  registerCompiler(options.compiler);
+  const stateStore = loadStateStore(options.store);
+
+  const runner = new MigrationRunner({
+    migrationsDirectory: options.migrationsDir,
+    stateStore,
+  });
+
+  await runner.down();
+}
+
+/**
+ * Run migrations up
+ */
+async function runUp(options: CliOptions) {
+  registerCompiler(options.compiler);
+  const stateStore = loadStateStore(options.store);
+
+  const runner = new MigrationRunner({
+    migrationsDirectory: options.migrationsDir,
+    stateStore,
+  });
+
+  await runner.up();
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+Migration CLI - Compatible with migrate package
+
+Usage:
+  migrate create <name> [options]    Create a new migration
+  migrate up [options]               Run all pending migrations
+  migrate down [options]             Rollback the last migration
+  migrate list [options]             List migration status
+
+Options:
+  --migrations-dir, -d <path>        Directory containing migrations (default: ./migrations)
+  --store, -s <path>                 Path to state store module
+  --compiler, -c <compiler>          Compiler to use (e.g., ts:./path/to/ts-compiler.js)
+  --template-file, -t <path>         Template file for creating migrations
+
+Examples:
+  migrate create add-user-email
+  migrate create add-user-email --template-file ./migrations-utils/template.ts
+  migrate up --store ./migrations-utils/migrate.js --migrations-dir ./migrations
+  migrate down --store ./migrations-utils/migrate.js
+  migrate list --store ./migrations-utils/migrate.js
+
+Environment Variables:
+  NODE_ENV                           Set environment (e.g., development, production)
+`);
+}
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+export { main };

package/src/core/modules/migrate/helpers/migration.helper.ts

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import { Db, GridFSBucket, MongoClient, ObjectId } from 'mongodb';
+import * as path from 'path';
+
+/**
+ * Migration helper functions for database operations
+ */
+
+/**
+ * Get database connection
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @returns Promise with database instance
+ *
+ * @example
+ * ```typescript
+ * const db = await getDb('mongodb://localhost/mydb');
+ * await db.collection('users').updateMany(...);
+ * ```
+ */
+export const getDb = async (mongoUrl: string): Promise<Db> => {
+  const client: MongoClient = await MongoClient.connect(mongoUrl);
+  return client.db();
+};
+
+/**
+ * Upload file to GridFS
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @param relativePath - Relative path to the file
+ * @param options - Optional bucket name and filename
+ * @returns Promise with ObjectId of uploaded file
+ *
+ * @example
+ * ```typescript
+ * const fileId = await uploadFileToGridFS(
+ *   'mongodb://localhost/mydb',
+ *   '../assets/image.png',
+ *   { bucketName: 'images', filename: 'logo.png' }
+ * );
+ * ```
+ */
+export const uploadFileToGridFS = async (
+  mongoUrl: string,
+  relativePath: string,
+  options?: { bucketName?: string; filename?: string },
+): Promise<ObjectId> => {
+  if (!relativePath) {
+    throw new Error('relativePath is required');
+  }
+
+  const { bucketName, filename } = {
+    bucketName: 'fs',
+    filename: relativePath.split('/')[relativePath.split('/').length - 1],
+    ...options,
+  };
+
+  return new Promise<ObjectId>(async (resolve, reject) => {
+    let client: MongoClient | undefined;
+    try {
+      client = await MongoClient.connect(mongoUrl);
+      const db = client.db();
+      const bucket = new GridFSBucket(db, { bucketName });
+      const writeStream = bucket.openUploadStream(filename);
+
+      const rs = fs.createReadStream(path.resolve(__dirname, relativePath)).pipe(writeStream);
+
+      rs.on('finish', () => {
+        resolve(writeStream.id as ObjectId);
+      });
+
+      rs.on('error', (err) => {
+        reject(err);
+      });
+    } catch (err) {
+      reject(err);
+    } finally {
+      // Note: Connection will be closed when stream finishes
+      // but we keep the client reference for proper error handling
+    }
+  });
+};
+
+/**
+ * Create a migration state store factory
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @param collectionName - Optional collection name (default: 'migrations')
+ * @param lockCollectionName - Optional lock collection name for cluster environments
+ * @returns MongoStateStore class that can be used with migrate CLI
+ *
+ * @example
+ * ```typescript
+ * // In migrations-utils/migrate.js:
+ * const { createMigrationStore } = require('@lenne.tech/nest-server');
+ * const config = require('../src/config.env');
+ *
+ * module.exports = createMigrationStore(config.default.mongoose.uri);
+ * ```
+ */
+export const createMigrationStore = (
+  mongoUrl: string,
+  collectionName: string = 'migrations',
+  lockCollectionName?: string,
+) => {
+  const { MongoStateStore } = require('../mongo-state-store');
+
+  return class MigrationStateStore extends MongoStateStore {
+    constructor() {
+      super({
+        collectionName,
+        lockCollectionName,
+        uri: mongoUrl,
+      });
+    }
+  };
+};

package/src/core/modules/migrate/helpers/ts-compiler.js

@@ -0,0 +1,14 @@
+/**
+ * TypeScript compiler for migrate CLI
+ *
+ * This file registers ts-node to allow TypeScript migrations to be executed.
+ *
+ * Usage with migrate CLI:
+ * migrate --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+ *
+ * Or copy this file to your project's migrations-utils folder.
+ */
+
+const tsNode = require('ts-node');
+
+module.exports = tsNode.register;

package/src/core/modules/migrate/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Migration module exports
+ *
+ * This module provides MongoDB-based state storage for migration frameworks.
+ * It is compatible with the @nodepit/migrate-state-store-mongodb package
+ * and supports MongoDB 6+.
+ *
+ * @example
+ * ```typescript
+ * import { MongoStateStore, synchronizedUp, createMigrationStore } from '@lenne.tech/nest-server';
+ *
+ * // Basic usage
+ * const stateStore = new MongoStateStore('mongodb://localhost/mydb');
+ *
+ * // With custom collection names
+ * const stateStore = new MongoStateStore({
+ *   uri: 'mongodb://localhost/mydb',
+ *   collectionName: 'my_migrations',
+ *   lockCollectionName: 'migration_lock'
+ * });
+ *
+ * // Using synchronized migration for clustered environments
+ * await synchronizedUp({
+ *   stateStore: new MongoStateStore({
+ *     uri: 'mongodb://localhost/mydb',
+ *     lockCollectionName: 'migration_lock'
+ *   })
+ * });
+ *
+ * // Create a migration store for use with migrate CLI
+ * // In your project's migrations-utils/migrate.js:
+ * const { createMigrationStore } = require('@lenne.tech/nest-server');
+ * const config = require('../src/config.env');
+ * module.exports = createMigrationStore(config.default.mongoose.uri);
+ * ```
+ */
+
+export * from './cli/migrate-cli';
+export * from './helpers/migration.helper';
+export * from './migration-runner';
+export * from './mongo-state-store';