@lenne.tech/nest-server 11.43.2 → 12.0.0

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

@@ -24,8 +24,18 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MigrationRunner, parseStrictEnv } from '../migration-runner';
-import { MongoStateStore } from '../mongo-state-store';
+import { MigrationRunner, parseStrictEnv } from '../migration-runner.js';
+import { MongoStateStore } from '../mongo-state-store.js';
+import { createRequire } from 'node:module';
+import { callerDirectory } from '../../../common/helpers/module-location.helper.js';
+
+/**
+ * Loads a file the CLI was pointed at (store, `--compiler`) by absolute path. `createRequire` instead of `require`:
+ * the core's source is valid as CommonJS and as ESM, and only the former has a `require` in scope.
+ */
+function requireFromProject(absolutePath: string): any {
+  return createRequire(path.join(process.cwd(), 'package.json'))(absolutePath);
+}
 
 interface CliOptions {
   compiler?: string;
@@ -35,10 +45,59 @@ interface CliOptions {
   templateFile?: string;
 }
 
+const FRAMEWORK_PACKAGE = '@lenne.tech/nest-server';
+
+/**
+ * The import specifier a migration created in `migrationsDir` must use for the framework's helpers.
+ *
+ * The shipped template imports `getDb` / `uploadFileToGridFS` from `@lenne.tech/nest-server`. A
+ * vendor-mode project has no such package — its core lives in `src/core/` — so a migration created
+ * from the unchanged template fails with TS2307 in the IDE and `tsc`, and with MODULE_NOT_FOUND at run time.
+ * Returns the relative path from the migrations directory to the vendored core when the package does
+ * not resolve from `cwd` AND this CLI runs from a vendored core (one with its own `index` next to
+ * `modules/`, as the vendor flatten-fix leaves it); otherwise `undefined`, i.e. keep the package name.
+ * In npm mode the package resolves, and in this framework repo `src/core/` has no `index`, so neither
+ * is rewritten.
+ *
+ * @param migrationsDir - Directory the migration is written to, absolute or relative to `cwd`
+ * @param cwd - Project directory the package is resolved from
+ * @param coreRoot - Root of the core this CLI belongs to
+ */
+export function vendoredFrameworkSpecifier(
+  migrationsDir: string,
+  cwd: string = process.cwd(),
+  coreRoot: string = path.resolve(callerDirectory(), '..', '..', '..'),
+): string | undefined {
+  try {
+    createRequire(path.join(cwd, 'package.json')).resolve(FRAMEWORK_PACKAGE);
+    return undefined;
+  } catch {
+    // Not installed — the vendor-mode case, if the core below has an entry point of its own.
+  }
+  if (!['index.ts', 'index.js'].some((entry) => fs.existsSync(path.join(coreRoot, entry)))) {
+    return undefined;
+  }
+  const relativePath = path.relative(path.resolve(cwd, migrationsDir), coreRoot).split(path.sep).join('/');
+  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}
+
+/**
+ * Replaces the exact `@lenne.tech/nest-server` specifier (`from '…'`, `require('…')`, single or double
+ * quotes) in a migration template. Subpaths of the package are left alone.
+ */
+export function rewriteFrameworkSpecifier(template: string, specifier: string): string {
+  return template.replace(
+    /(['"])@lenne\.tech\/nest-server\1/g,
+    (_match, quote: string) => `${quote}${specifier}${quote}`,
+  );
+}
+
 /**
  * Create a new migration file
+ *
+ * @param coreRoot - Root of the core this CLI belongs to; defaults to the one it runs from (tests only)
  */
-async function createMigration(name: string, options: CliOptions) {
+async function createMigration(name: string, options: CliOptions, coreRoot?: string) {
   if (!name) {
     console.error('Error: Migration name is required');
     console.log('Usage: migrate create <name> [options]');
@@ -60,6 +119,10 @@ async function createMigration(name: string, options: CliOptions) {
   if (options.templateFile) {
     const templatePath = path.resolve(process.cwd(), options.templateFile);
     template = fs.readFileSync(templatePath, 'utf-8');
+    const specifier = vendoredFrameworkSpecifier(options.migrationsDir, process.cwd(), coreRoot);
+    if (specifier) {
+      template = rewriteFrameworkSpecifier(template, specifier);
+    }
   } else {
     // Default template
     template = `/**
@@ -141,7 +204,7 @@ function loadStateStore(storePath: string | undefined): MongoStateStore {
 
   const absolutePath = path.resolve(process.cwd(), storePath);
 
-  const StoreClass = require(absolutePath);
+  const StoreClass = requireFromProject(absolutePath);
 
   // Handle different export patterns
   if (StoreClass.default) {
@@ -255,7 +318,7 @@ function registerCompiler(compiler: string | undefined) {
   if (type === 'ts' && compilerPath) {
     const absolutePath = path.resolve(process.cwd(), compilerPath);
 
-    const register = require(absolutePath);
+    const register = requireFromProject(absolutePath);
     if (typeof register === 'function') {
       register();
     }
@@ -395,9 +458,10 @@ const runCli = async (): Promise<void> => {
 
 // Run CLI if executed directly (`node migrate-cli.js`). The bin shim calls
 // runCli() itself, so this only covers a direct invocation of the compiled file.
-if (require.main === module) {
+// `typeof` first: as ESM neither `require` nor `module` exists, and reading them would throw at load time.
+if (typeof require !== 'undefined' && typeof module !== 'undefined' && require.main === module) {
   void runCli();
 }
 
 // parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
-export { flushAndExit, main, parseArgs, runCli };
+export { createMigration, flushAndExit, main, parseArgs, runCli };

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

@@ -1,287 +1,10 @@
-import * as fs from 'fs';
-import { Db, GridFSBucket, MongoClient, ObjectId } from 'mongodb';
-import * as path from 'path';
-
-import { MongoStateStore } from '../mongo-state-store';
-
 /**
- * Migration helper functions for database operations
- */
-
-// Store active connections for auto-cleanup
-const activeConnections = new Set<MongoClient>();
-
-// Track if we're in a migration context
-let inMigrationContext = false;
-
-/**
- * Mark the start of a migration
- * @internal Used by migration runner
- */
-export const _startMigration = () => {
-  inMigrationContext = true;
-};
-
-/**
- * Mark the end of a migration and close all connections
- * @internal Used by migration runner
- */
-export const _endMigration = async () => {
-  inMigrationContext = false;
-  // Close all active connections
-  const promises = Array.from(activeConnections).map((client) => client.close());
-  activeConnections.clear();
-  await Promise.all(promises);
-};
-
-/**
- * Get database connection
- *
- * When used in migrations, connections are automatically closed after the migration completes.
- * For manual usage outside migrations, you must close the connection manually.
- *
- * @param mongoUrl - MongoDB connection URI
- * @returns Promise with database instance
- *
- * @example
- * ```typescript
- * // In migrations - connection auto-closes after migration
- * const db = await getDb('mongodb://localhost/mydb');
- * await db.collection('users').updateMany(...);
- *
- * // Outside migrations - must close manually
- * const db = await getDb('mongodb://localhost/mydb');
- * try {
- *   await db.collection('users').updateMany(...);
- * } finally {
- *   await db.client.close();
- * }
- * ```
- */
-export const getDb = async (mongoUrl: string): Promise<Db> => {
-  const client: MongoClient = await MongoClient.connect(mongoUrl);
-
-  // Track connection for auto-cleanup in migrations
-  if (inMigrationContext) {
-    activeConnections.add(client);
-  }
-
-  return client.db();
-};
-
-/**
- * Throw unless every chunk of a stored GridFS file is present.
- *
- * A GridFS upload is not one write but many: N chunk documents plus the files
- * document that describes them. The write stream's `'finish'` event says the
- * stream ended — it does not prove every chunk is durably there, and a
- * connection that goes away at the wrong moment can leave a files document
- * behind that promises more bytes than exist. The upload then "succeeds", the
- * caller stores the id, and the defect only surfaces much later as a broken
- * download from a record that looks perfectly healthy.
- *
- * Counts documents rather than reading bytes, so a chunk that was written but
- * truncated still passes. Catching that would mean streaming the whole file
- * back on every upload; the cheap count catches the failure that actually
- * occurs (a missing chunk) and is index-only via the GridFS default index.
- *
- * @param db - Database holding the bucket
- * @param bucketName - GridFS bucket name, i.e. the prefix of `<bucket>.files` / `<bucket>.chunks`
- * @param id - `_id` of the files document
- * @param label - Optional human-readable name for the error message; defaults to the id
- * @throws Error if the files document is missing or fewer chunks are stored than its length implies
- *
- * @example
- * ```typescript
- * await assertGridFsFileComplete(db, 'images', fileId, 'logo.png');
- * ```
- */
-export const assertGridFsFileComplete = async (
-  db: Db,
-  bucketName: string,
-  id: ObjectId,
-  label?: string,
-): Promise<void> => {
-  const name = label || String(id);
-  const fileDoc = await db.collection(`${bucketName}.files`).findOne({ _id: id });
-  if (!fileDoc) {
-    throw new Error(`GridFS file '${name}' has no file document (id ${String(id)})`);
-  }
-
-  const chunkSize: number = fileDoc.chunkSize || 255 * 1024;
-  // NO `Math.max(1, …)` floor here: GridFS stores ZERO chunk documents for a
-  // zero-byte file — the driver's `writeRemnant()` returns early on `pos === 0`
-  // rather than inserting an empty chunk. A floor of 1 would reject every
-  // legitimately empty asset, and because the container entrypoint defaults to
-  // `MIGRATE_FAILURE_POLICY=abort`, that failure would keep the server from
-  // starting at all.
-  const expected = Math.ceil((fileDoc.length || 0) / chunkSize);
-  const actual = await db
-    .collection(`${bucketName}.chunks`)
-    // Read from the primary: this is a read-your-own-write, and a URI carrying
-    // `readPreference=secondaryPreferred` would otherwise fail a healthy upload
-    // against a secondary that has not caught up yet.
-    .countDocuments({ files_id: id }, { readPreference: 'primary' });
-  if (actual < expected) {
-    throw new Error(`GridFS file '${name}' is incomplete: ${actual} of ${expected} chunks stored (id ${String(id)})`);
-  }
-};
-
-/**
- * Upload file to GridFS
- *
- * Resolves only once the upload is verified complete (see
- * {@link assertGridFsFileComplete}); rejects — rather than hanging — when the
- * source file cannot be read. Closes its own connection either way.
- *
- * @param mongoUrl - MongoDB connection URI
- * @param relativePath - Path to the file, resolved against this module's directory
- * @param options - Optional bucket name and filename
- * @returns Promise with ObjectId of uploaded file
- * @throws Error if the source cannot be read, or if the stored file is incomplete
- *
- * @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,
-  };
-
-  const client = await MongoClient.connect(mongoUrl);
-  // Registered unconditionally — unlike `getDb()`, which only registers inside a
-  // migration context. This client is always ours to close, so `_endMigration()`
-  // stays a backstop for the case where the upload throws before `settle()` runs.
-  activeConnections.add(client);
-
-  const db = client.db();
-  const bucket = new GridFSBucket(db, { bucketName });
-  const writeStream = bucket.openUploadStream(filename);
-
-  const readStream = fs.createReadStream(path.resolve(__dirname, relativePath));
-  const rs = readStream.pipe(writeStream);
-
-  /**
-   * Read errors need their own handler — `pipe()` does not forward them.
-   *
-   * An unreadable source (missing file, wrong path inside a container image)
-   * emits on the READ stream, where nothing was listening: the write stream
-   * never finished, the promise below never settled, and the migration hung
-   * until something else timed out. Destroying the write stream routes it into
-   * the rejection path so the caller sees the actual cause.
-   */
-  readStream.on('error', (err) => {
-    writeStream.destroy(err);
-  });
-
-  /**
-   * Close the connection before settling.
-   *
-   * This client used to be opened and never closed, and it was not registered
-   * either — so `_endMigration()` could not reach it. Every uploaded file left a
-   * live connection behind, and a live connection keeps an SDAM monitor timer
-   * alive, which keeps the Node event loop busy: `migrate up` finished its work,
-   * printed "All migrations completed successfully" and then never exited. That
-   * is invisible on a developer machine and blocks a CI job until its timeout.
-   *
-   * A failing `close()` must never become the error the caller sees: the reason
-   * the upload ended is what matters, and the settle path is also reached while
-   * rejecting. So the close error is logged and swallowed, and `settled` keeps a
-   * second call (success path falling into `.catch`) from closing twice.
-   */
-  let settled = false;
-  const settle = async <T>(action: () => T): Promise<T> => {
-    if (!settled) {
-      settled = true;
-      try {
-        await client.close();
-      } catch (closeErr) {
-        console.warn('Failed to close migration connection:', closeErr);
-      } finally {
-        activeConnections.delete(client);
-      }
-    }
-    return action();
-  };
-
-  return new Promise<ObjectId>((resolve, reject) => {
-    rs.on('finish', () => {
-      const id = writeStream.id as ObjectId;
-      // Verify BEFORE closing: the check needs the same open client, and a
-      // failure has to reject rather than hand back an id that points at nothing.
-      assertGridFsFileComplete(db, bucketName, id, filename)
-        .then(() => settle(() => id))
-        .then(resolve)
-        .catch((err: unknown) => {
-          // Drop the incomplete file, otherwise every re-run of the migration
-          // leaves another orphaned files document (plus its partial chunks)
-          // behind, since a retry uploads under a fresh ObjectId.
-          bucket
-            .delete(id)
-            .catch(() => undefined)
-            .then(() => settle(() => undefined))
-            .finally(() => reject(err));
-        });
-    });
-
-    rs.on('error', (err) => {
-      settle(() => undefined).finally(() => reject(err));
-    });
-  });
-};
-
-/**
- * Create a migration state store factory
- *
- * The lock collection is set by DEFAULT, so `migrate up` from N replicas booting at
- * the same time serializes instead of applying the same migration twice (the container
- * entrypoint runs migrations on every boot). Pass an empty string to opt out.
- *
- * @param mongoUrl - MongoDB connection URI
- * @param collectionName - Optional collection name (default: 'migrations')
- * @param lockCollectionName - Lock collection name (default: 'migrations_lock'); `''` disables locking
- * @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');
+ * Forwarder kept at the path existing projects load (`migrations-utils/migrate.js`, which the lt CLI generates for
+ * vendor-mode projects, requires `src/core/modules/migrate/helpers/migration.helper`). The helper itself moved to
+ * `../migration.helper.ts` in 12.0.0.
  *
- * module.exports = createMigrationStore(config.default.mongoose.uri);
- * ```
+ * This directory is CommonJS (`helpers/package.json`), so this file compiles to CommonJS. No module of the core may
+ * import it: a CommonJS module inside the core's ES module graph that loads other core modules breaks `require()` of
+ * the package from a CommonJS project. Core modules import `../migration.helper.js`.
  */
-export const createMigrationStore = (
-  mongoUrl: string,
-  collectionName: string = 'migrations',
-  lockCollectionName: string = 'migrations_lock',
-  // Explicit return type: the returned class is anonymous to the declaration emitter, and
-  // MongoStateStore has private members, so an inferred type cannot be written to the .d.ts
-  // (TS4094).
-): new () => MongoStateStore => {
-  return class MigrationStateStore extends MongoStateStore {
-    constructor() {
-      super({
-        collectionName,
-        lockCollectionName: lockCollectionName || undefined,
-        uri: mongoUrl,
-      });
-    }
-  };
-};
+export * from '../migration.helper.js';

package/src/core/modules/migrate/helpers/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/src/core/modules/migrate/helpers/ts-compiler-hooks.mjs

@@ -0,0 +1,90 @@
+/**
+ * ESM hooks of the framework's TypeScript loader, registered by `ts-compiler.cjs` through `module.register()`.
+ *
+ * - `resolve`: a relative `./x.js` from a TypeScript file finds `x.ts` when no `x.js` exists (ESM requires the
+ *   extension of the EMITTED file, so sources written for both module systems name files that exist only after a
+ *   build). A real `.js` file always wins.
+ * - `load`: a TypeScript file in ESM scope (`.mts`, or `.ts` under `"type": "module"`) is compiled with SWC to ESM,
+ *   with the options of the CommonJS hook. One in CommonJS scope is handed back to the CommonJS loader, where the
+ *   `require` hook compiles it — the same file must not be compiled two different ways.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { loadSwc, SOURCE_EXTENSIONS, SWC_OPTIONS } = require('./ts-compiler.cjs');
+
+const TYPESCRIPT = /\.(c|m)?ts$/;
+const packageTypes = new Map();
+let swc;
+
+/** `"module"` or `"commonjs"`, from the nearest package.json — how Node itself decides a `.ts` file's format. */
+function packageType(directory) {
+  if (packageTypes.has(directory)) {
+    return packageTypes.get(directory);
+  }
+  let type = 'commonjs';
+  try {
+    type = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8')).type === 'module' ? 'module' : 'commonjs';
+  } catch {
+    const parent = dirname(directory);
+    type = parent === directory ? 'commonjs' : packageType(parent);
+  }
+  packageTypes.set(directory, type);
+  return type;
+}
+
+function formatOf(filename) {
+  if (filename.endsWith('.mts')) {
+    return 'module';
+  }
+  if (filename.endsWith('.cts')) {
+    return 'commonjs';
+  }
+  return packageType(dirname(filename));
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (error) {
+    const extension = specifier.match(/\.(c|m)?js$/)?.[0];
+    const fromTypeScript = TYPESCRIPT.test(context.parentURL ?? '');
+    const pathLike = /^\.{0,2}\//.test(specifier) || specifier.startsWith('file:');
+    if (error?.code !== 'ERR_MODULE_NOT_FOUND' || !extension || !fromTypeScript || !pathLike) {
+      throw error;
+    }
+    const sources = { ...SOURCE_EXTENSIONS, '.mjs': ['.mts'] }[extension] ?? [];
+    for (const sourceExtension of sources) {
+      try {
+        return await nextResolve(specifier.slice(0, -extension.length) + sourceExtension, context);
+      } catch {
+        // try the next one; the original error is the one worth reporting
+      }
+    }
+    throw error;
+  }
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith('file:') || !TYPESCRIPT.test(new URL(url).pathname)) {
+    return nextLoad(url, context);
+  }
+  const filename = fileURLToPath(url);
+  if (formatOf(filename) === 'commonjs') {
+    // No source: Node loads it with the CommonJS loader, i.e. through the `require` hook.
+    return { format: 'commonjs', shortCircuit: true };
+  }
+  swc ??= loadSwc();
+  const { code } = swc.transformSync(readFileSync(filename, 'utf8'), {
+    ...SWC_OPTIONS,
+    filename,
+    // SWC drops import attributes unless told to keep them, and Node refuses a JSON import without
+    // `with { type: 'json' }` (ERR_IMPORT_ATTRIBUTE_MISSING) — `import pkg from '../package.json' with { type: 'json' }`.
+    jsc: { ...SWC_OPTIONS.jsc, experimental: { keepImportAssertions: true } },
+    module: { type: 'es6' },
+  });
+  return { format: 'module', shortCircuit: true, source: code };
+}