@nmakarov/cli-toolkit 0.23.0 → 0.27.0

package/dist/index.js

@@ -1689,46 +1689,83 @@ var Params = class _Params {
   paramGetters = [];
   trackedParams = [];
   _currentModule = "script";
-  /** Resolved early in constructor so cleanup does not read params lazily */
-  _showUsedParams = false;
+  /**
+   * Resolved early in constructor so cleanup does not read params lazily.
+   * One of: false (off) | "end" (print at exit) | "top" (print after init,
+   * via context.showUsedParamsIfNeeded()).
+   */
+  _showUsedParamsMode = false;
+  /** Guard so the dump prints at most once (top OR end, never both). */
+  _usedParamsPrinted = false;
   constructor(context, options = {}) {
     this.context = context;
     this.args = context.args;
     if (Object.keys(options).length > 0) {
       this.configure(options);
     }
-    this._showUsedParams = this.get("showUsedParams", "boolean default false");
+    this._resolveShowUsedParams();
     if (context && typeof context.registerCleanup === "function") {
       context.registerCleanup((ctx) => {
-        if (!ctx.params.getShowUsedParams()) return;
-        const byModule = ctx.params.getFiguredByModule();
-        const modules = Object.keys(byModule).sort();
-        if (modules.length === 0) return;
-        const logger = ctx.logger;
-        logger.debug("[Params]: list of used params:");
-        if (typeof logger.highlight !== "function") {
-          for (const mod of modules) {
-            logger.debug(`  [${mod}]`);
-            for (const [key, entry] of Object.entries(byModule[mod])) {
-              logger.debug(`    ${key}: ${JSON.stringify(entry.value)} (${entry.source})`);
-            }
-          }
-          return;
-        }
-        for (const mod of modules) {
-          logger.debug(`  [${mod}]`);
-          for (const [key, entry] of Object.entries(byModule[mod])) {
-            const valueStr = JSON.stringify(entry.value);
-            const display = entry.source === "default" ? valueStr : logger.highlight(valueStr);
-            logger.debug(`    ${key}: ${display} (${entry.source})`);
-          }
-        }
+        if (!ctx.params.getShowUsedParamsMode()) return;
+        ctx.params.printUsedParams(ctx.logger);
       });
     }
   }
-  /** Whether --showUsedParams was requested (resolved in constructor). */
+  /**
+   * Resolve the --showUsedParams mode. The flag is intentionally dual-typed:
+   *   (absent) / --no-showUsedParams / =false   -> false  (off)
+   *   --showUsedParams / =true                   -> "end"  (print at exit)
+   *   --showUsedParams=top                       -> "top"  (print after init)
+   * Read raw (uncoerced) from args so the string "top" isn't forced to a
+   * boolean, then track it under the "script" module for the dump itself.
+   */
+  _resolveShowUsedParams() {
+    const raw = this.args.get("showUsedParams");
+    const source = this.args.getSource?.("showUsedParams") ?? "default";
+    let mode = false;
+    if (raw === void 0 || raw === null) {
+      mode = false;
+    } else if (typeof raw === "string" && raw.trim().toLowerCase() === "top") {
+      mode = "top";
+    } else {
+      const s = typeof raw === "string" ? raw.trim().toLowerCase() : raw;
+      const falsey = s === false || s === "false" || s === "0" || s === "no" || s === "off";
+      mode = falsey ? false : "end";
+    }
+    this._showUsedParamsMode = mode;
+    this.trackParam("showUsedParams", "string", mode, raw === void 0 ? "default" : source, "script");
+    return mode;
+  }
+  /** Whether --showUsedParams was requested in any mode (truthy = on). */
   getShowUsedParams() {
-    return this._showUsedParams;
+    return this._showUsedParamsMode !== false;
+  }
+  /** Resolved mode: false | "end" | "top". */
+  getShowUsedParamsMode() {
+    return this._showUsedParamsMode;
+  }
+  /**
+   * Print the module-grouped list of figured params (the --showUsedParams
+   * dump). Idempotent: only the first call prints, so callers can invoke it
+   * at the top (long-running services) without double-printing at exit.
+   */
+  printUsedParams(logger) {
+    if (this._usedParamsPrinted) return;
+    const byModule = this.getFiguredByModule();
+    const modules = Object.keys(byModule).sort();
+    if (modules.length === 0) return;
+    this._usedParamsPrinted = true;
+    logger = logger ?? this.context?.logger ?? console;
+    const hasHighlight = typeof logger.highlight === "function";
+    logger.debug("[Params]: list of used params:");
+    for (const mod of modules) {
+      logger.debug(`  [${mod}]`);
+      for (const [key, entry] of Object.entries(byModule[mod])) {
+        const valueStr = JSON.stringify(entry.value);
+        const display = hasHighlight && entry.source !== "default" ? logger.highlight(valueStr) : valueStr;
+        logger.debug(`    ${key}: ${display} (${entry.source})`);
+      }
+    }
   }
   /**
    * Configure parameters
@@ -1996,6 +2033,18 @@ var Params = class _Params {
       this._currentModule = prev;
     }
   }
+  /**
+   * Async variant of {@link runWithModule} for modules that await params.get().
+   */
+  async runWithModuleAsync(moduleName, fn) {
+    const prev = this._currentModule;
+    this._currentModule = moduleName;
+    try {
+      return await fn();
+    } finally {
+      this._currentModule = prev;
+    }
+  }
   /**
    * Infer module name from call stack: first caller outside params/index gives path like .../src/<moduleName>/...
    */
@@ -3259,38 +3308,71 @@ var KNEX_DEFAULTS = {
 };
 var Db = class {
   static async init(context, options = {}) {
-    const defs = {
-      dbName: "string",
-      dbConnectionString: "string",
-      dbProfile: "boolean default false"
-    };
-    const discovered = context?.params?.getAllForModule?.("db", defs) ?? {};
-    const merged = { ...discovered, ...options };
-    let { dbName, dbConnectionString } = merged;
-    const { dbProfile } = merged;
-    if (!dbName && !dbConnectionString) {
-      dbName = "local";
-    }
-    if (dbName && /^(postgresql|mysql):\/\//.test(dbName)) {
-      dbConnectionString = dbName;
-      dbName = void 0;
-    }
-    if (dbName && !dbConnectionString) {
-      const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
-      dbConnectionString = await context.params.get(paramName, "string");
+    const buildConfig = async () => {
+      const defs = {
+        dbName: "string",
+        dbProfile: "boolean default false"
+      };
+      const discovered = context?.params?.getAllForModule?.("db", defs) ?? {};
+      const merged = { ...discovered, ...options };
+      let { dbName, dbProfile } = merged;
+      let dbConnectionString = options.dbConnectionString ?? options.connectionString;
+      let connectionParam = dbConnectionString ? "options" : null;
       if (!dbConnectionString) {
-        throw new ParamError(
-          `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
-        );
+        const src = context?.args?.getSource?.("dbConnectionString");
+        if (src === "cli" || src === "overrides" || src === "config") {
+          dbConnectionString = await context.params.get("dbConnectionString", "string");
+          connectionParam = "dbConnectionString";
+        }
       }
-    }
-    const config2 = {
-      ...KNEX_DEFAULTS,
-      connectionString: dbConnectionString,
-      name: dbName || merged.name || "default",
-      profile: !!dbProfile,
-      logger: context.logger
+      if (!dbConnectionString && dbName && /^(postgresql|mysql):\/\//.test(dbName)) {
+        dbConnectionString = dbName;
+        dbName = void 0;
+      }
+      if (!dbConnectionString && dbName) {
+        const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
+        dbConnectionString = await context.params.get(paramName, "string");
+        connectionParam = paramName;
+        if (!dbConnectionString) {
+          throw new ParamError(
+            `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
+          );
+        }
+      }
+      if (!dbConnectionString) {
+        dbConnectionString = await context.params.get("dbConnectionString", "string");
+        if (dbConnectionString) {
+          connectionParam = "dbConnectionString";
+        }
+      }
+      if (!dbConnectionString) {
+        if (!dbName) {
+          dbName = "local";
+        }
+        const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
+        dbConnectionString = await context.params.get(paramName, "string");
+        connectionParam = paramName;
+        if (!dbConnectionString) {
+          throw new ParamError(
+            `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
+          );
+        }
+      }
+      const displayName = resolveDbDisplayName(
+        dbName,
+        connectionParam,
+        context?.args?.env,
+        merged.name
+      );
+      return {
+        ...KNEX_DEFAULTS,
+        connectionString: dbConnectionString,
+        name: displayName,
+        profile: !!dbProfile,
+        logger: context.logger
+      };
     };
+    const config2 = context?.params?.runWithModuleAsync ? await context.params.runWithModuleAsync("db", buildConfig) : await buildConfig();
     return dbConnect(context, config2);
   }
   constructor(config2) {
@@ -3307,7 +3389,6 @@ var Db = class {
       acquireConnectionTimeout: 1e4,
       ssl: { rejectUnauthorized: false },
       logger: console,
-      name: "default",
       ...config2
     };
     this.logger = this.config.logger;
@@ -3407,9 +3488,7 @@ var Db = class {
         await this.testConnection();
       }
       this.isConnected = true;
-      this.logger.debug?.(
-        `[Db] Connected to database "${this.config.name || this.config.connectionString}"`
-      );
+      this.logger.debug?.(formatDbConnectMessage(this.config.name, this.config.connectionString));
     } catch (error) {
       if (error instanceof ParamError) {
         throw error;
@@ -3427,9 +3506,7 @@ var Db = class {
       this.knexInstance = null;
       this.isConnected = false;
       this.queriesLog = [];
-      this.logger.debug?.(
-        `[Db] Disconnected from database "${this.config.name || this.config.connectionString}"`
-      );
+      this.logger.debug?.(formatDbDisconnectMessage(this.config.name, this.config.connectionString));
     } catch (error) {
       const errorMsg = this.getErrorMessage(error);
       this.logger.error?.(`[Db] Error disconnecting: ${errorMsg}`);
@@ -3558,15 +3635,74 @@ var Db = class {
 function capitalizeFirstLetter(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+function resolveDbDisplayName(dbName, connectionParam, argsEnv, mergedName) {
+  if (dbName) {
+    return dbName;
+  }
+  if (mergedName) {
+    return mergedName;
+  }
+  if (connectionParam?.startsWith("dbConnectionString") && connectionParam.length > "dbConnectionString".length) {
+    return connectionParam.slice("dbConnectionString".length).toLowerCase();
+  }
+  if (connectionParam === "dbConnectionString" && argsEnv) {
+    return argsEnv;
+  }
+  return void 0;
+}
+function formatDbConnectMessage(name, connectionString) {
+  const endpointSuffix = formatConnectionEndpointSuffix(connectionString);
+  if (name) {
+    return `[Db] Connected to database "${name}"${endpointSuffix}`;
+  }
+  return `[Db] Connected${endpointSuffix}`;
+}
+function formatDbDisconnectMessage(name, connectionString) {
+  const endpointSuffix = formatConnectionEndpointSuffix(connectionString);
+  if (name) {
+    return `[Db] Disconnected from database "${name}"${endpointSuffix}`;
+  }
+  return `[Db] Disconnected${endpointSuffix}`;
+}
+function formatDbInstanceMessage(action, name) {
+  if (name) {
+    return `[Db] instance "${name}" ${action}`;
+  }
+  return `[Db] instance ${action}`;
+}
+function formatConnectionEndpointSuffix(connectionString) {
+  const endpoint = formatConnectionEndpoint(connectionString);
+  return endpoint ? ` (${endpoint})` : "";
+}
+function formatConnectionEndpoint(connectionString) {
+  try {
+    const url = new URL(connectionString);
+    const host = url.hostname;
+    if (!host) {
+      return null;
+    }
+    let port = url.port;
+    if (!port) {
+      if (url.protocol === "postgresql:") {
+        port = "5432";
+      } else if (url.protocol === "mysql:") {
+        port = "3306";
+      }
+    }
+    return port ? `${host}:${port}` : host;
+  } catch {
+    return null;
+  }
+}
 async function dbConnect(context, config2) {
   try {
     const db = new Db(config2);
     context.registerCleanup(async () => {
       await db.disconnect();
-      context.logger.debug?.(`[Db] instance "${config2.name}" disconnected`);
+      context.logger.debug?.(formatDbInstanceMessage("disconnected", config2.name));
     });
     await db.connect();
-    context.logger.debug?.(`[Db] instance "${config2.name}" initialized`);
+    context.logger.debug?.(formatDbInstanceMessage("initialized", config2.name));
     return db;
   } catch (error) {
     if (error instanceof ParamError) {
@@ -4176,7 +4312,16 @@ function setup(opts = {}) {
     emitter: partialContext.emitter,
     isStop: partialContext.isStop,
     cleanupFunctions: partialContext.cleanupFunctions,
-    registerCleanup: partialContext.registerCleanup
+    registerCleanup: partialContext.registerCleanup,
+    // For long-running scripts (servers): with --showUsedParams=top, print
+    // the used-params list now (after the script has initialized all its
+    // own components), instead of at exit. No-op for the default mode,
+    // which prints at exit via the cleanup registered by Params.
+    showUsedParamsIfNeeded: () => {
+      if (params.getShowUsedParamsMode?.() === "top") {
+        params.printUsedParams(logger);
+      }
+    }
   };
   logger.debug("[setup] completed successfully");
   return context;