@theholocron/env-utils 1.7.0 → 1.8.0

package/README.md

@@ -38,6 +38,14 @@ export const config = map((get) => ({
 }));
 ```
 
+### Logging
+
+Debug output (key-loaded counts, missing-key warnings, deprecation notices) goes to `console.info`/`console.warn` by default. Pass an `EnvLogger` (any object shaped `{ info(message, meta?), warn(message, meta?) }`) to route it elsewhere:
+
+```typescript
+const { get } = createEnvParser({ appName: "my-app", logger: myLogger });
+```
+
 ## Documentation
 
 Check out [The Holocron Archive](https://docs.theholocron.dev/projects/utils/) for more information.

package/dist/index.d.mts

@@ -20,7 +20,7 @@ interface EnvLookup {
  *   return createEnvLookup(source);
  * }
  */
-declare function createEnvLookup(source?: Record<string, string | undefined>): EnvLookup;
+export declare function createEnvLookup(source?: Record<string, string | undefined>): EnvLookup;
 //#endregion
 //#region src/types.d.ts
 type Primitive = string | number | boolean;
@@ -34,6 +34,17 @@ type EnvObject = {
 interface EnvLoader {
   load(): Record<string, string | undefined>;
 }
+/**
+ * Minimal structural logger seam — accept any object shaped like this
+ * (including a real `@theholocron/observability` `Logger` via a thin
+ * adapter) without this package taking a dependency on it. Defaults to
+ * `console.info`/`console.warn` so behavior is unchanged when nothing
+ * is injected.
+ */
+interface EnvLogger {
+  info(message: string, meta?: unknown): void;
+  warn(message: string, meta?: unknown): void;
+}
 interface EnvParserOptions {
   /**
    * Display name for this app — used in debug output.
@@ -76,6 +87,11 @@ interface EnvParserOptions {
    * createEnvParser({ appName: "my-cli", namespaces: ["MY_TOOL"] })
    */
   namespaces?: string[];
+  /**
+   * Structured logger for debug output (key-loaded counts, missing-key
+   * warnings, deprecation notices). Defaults to `console.info`/`console.warn`.
+   */
+  logger?: EnvLogger;
 }
 interface EnvParser<T extends EnvObject = EnvObject> {
   /**
@@ -157,12 +173,12 @@ interface EnvParser<T extends EnvObject = EnvObject> {
  *   auth: get("auth0"), // returns the whole auth0 namespace object
  * }));
  */
-declare function createEnvParser<T extends EnvObject = EnvObject>(options: EnvParserOptions): EnvParser<T>;
+export declare function createEnvParser<T extends EnvObject = EnvObject>(options: EnvParserOptions): EnvParser<T>;
 //#endregion
 //#region src/environment.d.ts
-declare const ENVIRONMENTS: readonly ["local", "dev", "qa", "prod"];
-declare const DEFAULT_ENVIRONMENT: Environment;
-declare const DEPLOYED_ENVIRONMENTS: Set<"local" | "dev" | "qa" | "prod">;
+export declare const ENVIRONMENTS: readonly ["local", "dev", "qa", "prod"];
+export declare const DEFAULT_ENVIRONMENT: Environment;
+export declare const DEPLOYED_ENVIRONMENTS: Set<"local" | "dev" | "qa" | "prod">;
 /**
  * Normalize a string into a canonical Environment.
  * Returns undefined if the value is not recognized.
@@ -171,11 +187,11 @@ declare function normalizeEnvironment(value: string): Environment | undefined;
 /**
  * Resolve the current environment from input or process.env.
  */
-declare function getEnvironment(): Environment;
-declare const environment: {
+declare function getEnvironment(logger?: Pick<EnvLogger, "warn">): Environment;
+export declare const environment: {
   get: typeof getEnvironment;
   normalize: typeof normalizeEnvironment;
-  isDeployed: () => boolean;
+  isDeployed: (logger?: Pick<EnvLogger, "warn">) => boolean;
 };
 type Environment = (typeof ENVIRONMENTS)[number];
 //#endregion
@@ -187,7 +203,7 @@ type Environment = (typeof ENVIRONMENTS)[number];
  * Swap this out via `createEnvParser({ loader: new MyLoader() })`
  * if you ever need Vault, AWS SSM, dotenvx, etc.
  */
-declare class DotenvLoader implements EnvLoader {
+export declare class DotenvLoader implements EnvLoader {
   load(): Record<string, string | undefined>;
 }
 //#endregion
@@ -203,7 +219,7 @@ declare class DotenvLoader implements EnvLoader {
  * filterByNamespace({ HOLOCRON_DEBUG: "true", PORT: "3000" }, "HOLOCRON")
  * // → { DEBUG: "true" }
  */
-declare function filterByNamespace(raw: Record<string, string | undefined>, namespace: string): Record<string, string | undefined>;
+export declare function filterByNamespace(raw: Record<string, string | undefined>, namespace: string): Record<string, string | undefined>;
 /**
  * Merge multiple namespace-filtered views of a raw env record.
  *
@@ -216,6 +232,6 @@ declare function filterByNamespace(raw: Record<string, string | undefined>, name
  * // HOLOCRON_DEBUG is the org-wide default; CLI_TEMPLATE_DEBUG overrides it.
  * mergeNamespaces(raw, ["HOLOCRON", "CLI_TEMPLATE"])
  */
-declare function mergeNamespaces(raw: Record<string, string | undefined>, namespaces: string[]): Record<string, string | undefined>;
+export declare function mergeNamespaces(raw: Record<string, string | undefined>, namespaces: string[]): Record<string, string | undefined>;
 //#endregion
-export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, type EnvLoader, type EnvLookup, type EnvObject, type EnvParser, type EnvParserOptions, type Environment, type Primitive, createEnvLookup, createEnvParser, environment, filterByNamespace, mergeNamespaces };
+export type { EnvLoader, EnvLogger, EnvLookup, EnvObject, EnvParser, EnvParserOptions, Environment, Primitive };

package/dist/index.mjs

@@ -48,14 +48,15 @@ function normalizeEnvironment(value) {
 		production: "prod"
 	})).get(value.toLowerCase());
 }
+const consoleWarn = { warn: (message) => console.warn(message) };
 /**
 * Resolve the current environment from input or process.env.
 */
-function getEnvironment() {
+function getEnvironment(logger = consoleWarn) {
 	const raw = process.env["ENVIRONMENT"] || process.env["ENV"] || process.env["NODE_ENV"] || "prod";
 	const normalized = normalizeEnvironment(String(raw));
 	if (!normalized) {
-		console.warn(`[@theholocron/utils-env] Unknown environment "${raw}", falling back to "${DEFAULT_ENVIRONMENT}"`);
+		logger.warn(`[@theholocron/utils-env] Unknown environment "${raw}", falling back to "${DEFAULT_ENVIRONMENT}"`);
 		return DEFAULT_ENVIRONMENT;
 	}
 	return normalized;
@@ -63,7 +64,7 @@ function getEnvironment() {
 const environment = {
 	get: getEnvironment,
 	normalize: normalizeEnvironment,
-	isDeployed: () => DEPLOYED_ENVIRONMENTS.has(getEnvironment())
+	isDeployed: (logger) => DEPLOYED_ENVIRONMENTS.has(getEnvironment(logger))
 };
 //#endregion
 //#region src/utils/coerce-value.ts
@@ -216,6 +217,10 @@ function normalizeKey(key) {
 }
 //#endregion
 //#region src/debug.ts
+const consoleLogger = {
+	info: (message, meta) => meta === void 0 ? console.info(message) : console.info(message, meta),
+	warn: (message, meta) => meta === void 0 ? console.warn(message) : console.warn(message, meta)
+};
 function isDebugEnabled() {
 	const raw = process.env["DEBUG"];
 	if (!raw) return false;
@@ -225,21 +230,21 @@ function isDebugEnabled() {
 		"yes"
 	].includes(raw.toLowerCase());
 }
-function debugLog(appName, env) {
+function debugLog(appName, env, logger = consoleLogger) {
 	if (environment.isDeployed()) return;
 	if (!isDebugEnabled()) return;
 	const keys = collectKeys(env);
-	console.info(`[@theholocron/utils-env] (debugLog) - ${appName} loaded ${keys.length} key(s) from environment`, { keys });
+	logger.info(`[@theholocron/utils-env] (debugLog) - ${appName} loaded ${keys.length} key(s) from environment`, { keys });
 }
-function warnMissingKey(appName, key) {
+function warnMissingKey(appName, key, logger = consoleLogger) {
 	if (environment.isDeployed()) return;
 	if (!isDebugEnabled()) return;
-	console.warn(`[@theholocron/utils-env] (warnMissingKey) - ${appName} key not found: "${key}" — returned undefined`);
+	logger.warn(`[@theholocron/utils-env] (warnMissingKey) - ${appName} key not found: "${key}" — returned undefined`);
 }
-function debugDeprecation(appName, oldKey, newKey, env) {
+function debugDeprecation(appName, oldKey, newKey, env, logger = consoleLogger) {
 	if (environment.isDeployed()) return;
 	if (!(oldKey in env)) return;
-	console.warn(`[@theholocron/utils-env] (debugDeprecation) - ${appName} "${oldKey}" is deprecated; migrate to "${newKey}"`);
+	logger.warn(`[@theholocron/utils-env] (debugDeprecation) - ${appName} "${oldKey}" is deprecated; migrate to "${newKey}"`);
 }
 const debug = {
 	log: debugLog,
@@ -286,14 +291,14 @@ var DotenvLoader = class {
 * }));
 */
 function createEnvParser(options) {
-	const { appName, loader = new DotenvLoader(), parseValues = true, namespaces } = options;
+	const { appName, loader = new DotenvLoader(), parseValues = true, namespaces, logger } = options;
 	const loaded = loader.load();
 	const env = buildEnvObject(namespaces && namespaces.length > 0 ? mergeNamespaces(loaded, namespaces) : loaded, parseValues);
-	debug.log(appName, env);
+	debug.log(appName, env, logger);
 	function get(key) {
 		const path = normalizeKey(key);
 		const value = getByPath(env, path);
-		if (value === void 0) debug.warn(appName, key);
+		if (value === void 0) debug.warn(appName, key, logger);
 		return value;
 	}
 	return {
@@ -305,7 +310,7 @@ function createEnvParser(options) {
 			return fn(get);
 		},
 		deprecate(oldKey, newKey) {
-			debug.deprecate(appName, oldKey, newKey, env);
+			debug.deprecate(appName, oldKey, newKey, env, logger);
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/env-utils",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Runtime environment detection and typed env-var parsing.",
   "keywords": [
     "env",
@@ -30,13 +30,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/tsdown-config": "^7.24.1",
-    "@theholocron/vitest-config": "^7.24.1",
+    "@theholocron/tsdown-config": "^8.2.0",
+    "@theholocron/vitest-config": "^8.2.0",
     "@tsconfig/node-lts": "^24.0.1",
     "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "^4.1.10",
     "dotenv": "^17.4.2",
-    "tsdown": "^0.22.14",
+    "tsdown": "^0.23.0",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {