fix: Build ESM migrations for JS

Including jsdoc for typehinting
Add esm as an option in the migrate cli
Update the documentation for the JS migrations

Closes: typeorm#10801

docs/migrations.md

@@ -258,8 +258,6 @@ export class PostRefactoringTIMESTAMP implements MigrationInterface {
 Alternatively you can also output your migrations as Javascript files using the `o` (alias for `--outputJs`) flag. This is useful for Javascript only projects in which TypeScript additional packages are not installed. This command, will generate a new migration file `{TIMESTAMP}-PostRefactoring.js` with the following content:
 
 ```javascript
-const { MigrationInterface, QueryRunner } = require("typeorm")
-
 module.exports = class PostRefactoringTIMESTAMP {
     async up(queryRunner) {
         await queryRunner.query(
@@ -273,6 +271,24 @@ module.exports = class PostRefactoringTIMESTAMP {
         )
     }
 }
+
+```
+By default, it generates CommonJS JavaScript code with the `o` (alias for `--outputJs`) flag, but you can generate also ESM code with the `esm` flag. This is useful for Javascript projects that use ESM modules:
+
+```javascript
+export class PostRefactoringTIMESTAMP {
+    async up(queryRunner) {
+        await queryRunner.query(
+            `ALTER TABLE "post" ALTER COLUMN "title" RENAME TO "name"`,
+        )
+    }
+
+    async down(queryRunner) {
+        await queryRunner.query(
+            `ALTER TABLE "post" ALTER COLUMN "name" RENAME TO "title"`,
+        )
+    }
+}
 ```
 
 See, you don't need to write the queries on your own.

src/commands/MigrationCreateCommand.ts

@@ -26,6 +26,12 @@ export class MigrationCreateCommand implements yargs.CommandModule {
                 describe:
                     "Generate a migration file on Javascript instead of Typescript",
             })
+            .option("esm", {
+                type: "boolean",
+                default: false,
+                describe:
+                    "Generate a migration file on ESM instead of CommonJS",
+            })
             .option("t", {
                 alias: "timestamp",
                 type: "number",
@@ -48,6 +54,7 @@ export class MigrationCreateCommand implements yargs.CommandModule {
                 ? MigrationCreateCommand.getJavascriptTemplate(
                       filename,
                       timestamp,
+                      args.esm,
                   )
                 : MigrationCreateCommand.getTemplate(filename, timestamp)
 
@@ -97,14 +104,26 @@ export class ${camelCase(
     protected static getJavascriptTemplate(
         name: string,
         timestamp: number,
+        esm: boolean,
     ): string {
-        return `const { MigrationInterface, QueryRunner } = require("typeorm");
+        const exportMethod = esm ? "export" : "module.exports ="
+        return `/**
+ * @typedef {import('typeorm').QueryRunner} QueryRunner
+ */
 
-module.exports = class ${camelCase(name, true)}${timestamp} {
+${exportMethod} class ${camelCase(name, true)}${timestamp} {
 
+    /**
+     * @param {QueryRunner} queryRunner
+     * @returns {Promise<void>}
+     */
     async up(queryRunner) {
     }
 
+    /**
+     * @param {QueryRunner} queryRunner
+     * @returns {Promise<void>}
+     */
     async down(queryRunner) {
     }
 

src/commands/MigrationGenerateCommand.ts

@@ -43,6 +43,12 @@ export class MigrationGenerateCommand implements yargs.CommandModule {
                 describe:
                     "Generate a migration file on Javascript instead of Typescript",
             })
+            .option("esm", {
+                type: "boolean",
+                default: false,
+                describe:
+                    "Generate a migration file on ESM instead of CommonJS",
+            })
             .option("dr", {
                 alias: "dryrun",
                 type: "boolean",
@@ -162,6 +168,7 @@ export class MigrationGenerateCommand implements yargs.CommandModule {
                       timestamp,
                       upSqls,
                       downSqls.reverse(),
+                      args.esm,
                   )
                 : MigrationGenerateCommand.getTemplate(
                       path.basename(fullPath),
@@ -264,19 +271,32 @@ ${downSqls.join(`
         timestamp: number,
         upSqls: string[],
         downSqls: string[],
+        esm: boolean,
     ): string {
         const migrationName = `${camelCase(name, true)}${timestamp}`
 
-        return `const { MigrationInterface, QueryRunner } = require("typeorm");
+        const exportMethod = esm ? "export" : "module.exports ="
+
+        return `/**
+ * @typedef {import('typeorm').QueryRunner} QueryRunner
+ */
 
-module.exports = class ${migrationName} {
+${exportMethod} class ${migrationName} {
     name = '${migrationName}'
 
+    /**
+     * @param {QueryRunner} queryRunner
+     * @returns {Promise<void>}
+     */
     async up(queryRunner) {
 ${upSqls.join(`
 `)}
     }
 
+    /**
+     * @param {QueryRunner} queryRunner
+     * @returns {Promise<void>}
+     */
     async down(queryRunner) {
 ${downSqls.join(`
 `)}