@outfitter/config 0.2.0 → 0.3.0

package/README.md

@@ -227,6 +227,61 @@ class ParseError {
 
 ---
 
+## Environment Profiles
+
+Unified environment detection for consistent defaults across all Outfitter packages.
+
+### `getEnvironment()`
+
+Reads `OUTFITTER_ENV` and returns the current profile. Falls back to `"production"` when unset or invalid.
+
+```typescript
+import { getEnvironment } from "@outfitter/config";
+
+const env = getEnvironment();
+// "development" | "production" | "test"
+```
+
+### `getEnvironmentDefaults(env)`
+
+Returns profile-specific defaults for an environment.
+
+```typescript
+import { getEnvironmentDefaults } from "@outfitter/config";
+
+const defaults = getEnvironmentDefaults("development");
+// { logLevel: "debug", verbose: true, errorDetail: "full" }
+
+const prodDefaults = getEnvironmentDefaults("production");
+// { logLevel: null, verbose: false, errorDetail: "message" }
+```
+
+| Setting | `development` | `production` | `test` |
+|---------|--------------|-------------|--------|
+| logLevel | `"debug"` | `null` | `null` |
+| verbose | `true` | `false` | `false` |
+| errorDetail | `"full"` | `"message"` | `"full"` |
+
+### Types
+
+#### `OutfitterEnv`
+
+```typescript
+type OutfitterEnv = "development" | "production" | "test";
+```
+
+#### `EnvironmentDefaults`
+
+```typescript
+interface EnvironmentDefaults {
+  logLevel: "debug" | "info" | "warn" | "error" | null;
+  verbose: boolean;
+  errorDetail: "full" | "message";
+}
+```
+
+---
+
 ## XDG Base Directory Specification
 
 This package follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for locating configuration files.

package/dist/index.d.ts

@@ -1,3 +1,92 @@
+/**
+* Unified environment profiles for Outfitter packages.
+*
+* Provides a shared "environment" concept that cascades defaults
+* across all Outfitter packages. The environment is determined by
+* the `OUTFITTER_ENV` environment variable, falling back to
+* `"production"` when unset or invalid.
+*
+* @example
+* ```typescript
+* import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
+*
+* const env = getEnvironment(); // "development" | "production" | "test"
+* const defaults = getEnvironmentDefaults(env);
+*
+* if (defaults.verbose) {
+*   console.log("Verbose mode enabled");
+* }
+* ```
+*
+* @module
+*/
+/**
+* Valid Outfitter environment names.
+*
+* - `"development"` — Local development with verbose output and debug logging
+* - `"production"` — Production deployments with minimal output
+* - `"test"` — Test runs with full error detail but no logging
+*/
+type OutfitterEnv = "development" | "production" | "test";
+/**
+* Profile-specific defaults for an environment.
+*
+* These defaults provide sensible starting values that individual
+* packages can override or extend.
+*/
+interface EnvironmentDefaults {
+	/** Default log level. `null` means logging is disabled by default. */
+	logLevel: "debug" | "info" | "warn" | "error" | null;
+	/** Whether verbose output is enabled by default. */
+	verbose: boolean;
+	/** How much error detail to include in output. */
+	errorDetail: "full" | "message";
+}
+/**
+* Determine the current Outfitter environment.
+*
+* Reads the `OUTFITTER_ENV` environment variable. If set to a valid
+* value (`"development"`, `"production"`, or `"test"`), returns that
+* value. Otherwise falls back to `"production"`.
+*
+* @returns The current environment
+*
+* @example
+* ```typescript
+* // With OUTFITTER_ENV=development
+* getEnvironment(); // "development"
+*
+* // With OUTFITTER_ENV unset or invalid
+* getEnvironment(); // "production"
+* ```
+*/
+declare function getEnvironment(): OutfitterEnv;
+/**
+* Get the default settings for an environment profile.
+*
+* Returns a shallow copy of the defaults for the given environment.
+* These defaults are intended as starting values that individual
+* packages can override via their own configuration.
+*
+* | Setting | `development` | `production` | `test` |
+* |---------|--------------|-------------|--------|
+* | logLevel | `"debug"` | `null` | `null` |
+* | verbose | `true` | `false` | `false` |
+* | errorDetail | `"full"` | `"message"` | `"full"` |
+*
+* @param env - The environment to get defaults for
+* @returns Profile-specific default settings
+*
+* @example
+* ```typescript
+* const defaults = getEnvironmentDefaults("development");
+* // { logLevel: "debug", verbose: true, errorDetail: "full" }
+*
+* const prodDefaults = getEnvironmentDefaults("production");
+* // { logLevel: null, verbose: false, errorDetail: "message" }
+* ```
+*/
+declare function getEnvironmentDefaults(env: OutfitterEnv): EnvironmentDefaults;
 import { z } from "zod";
 /**
 * Port number schema (1-65535) with string-to-number coercion.
@@ -509,4 +598,4 @@ declare function loadConfig<T>(appName: string, schema: ZodSchema<T>, options?:
 * ```
 */
 declare function mapEnvToConfig<T>(prefix: string, _schema?: ZodSchema<T>): Partial<T>;
-export { resolveConfig, portSchema, parseEnv, parseConfigFile, optionalBooleanSchema, mapEnvToConfig, loadConfig, getStateDir, getEnvBoolean, getDataDir, getConfigDir, getCacheDir, env, deepMerge, booleanSchema, ParseError, LoadConfigOptions, Env, ConfigSources, CircularExtendsError };
+export { resolveConfig, portSchema, parseEnv, parseConfigFile, optionalBooleanSchema, mapEnvToConfig, loadConfig, getStateDir, getEnvironmentDefaults, getEnvironment, getEnvBoolean, getDataDir, getConfigDir, getCacheDir, env, deepMerge, booleanSchema, ParseError, OutfitterEnv, LoadConfigOptions, EnvironmentDefaults, Env, ConfigSources, CircularExtendsError };

package/dist/index.js

@@ -8034,6 +8034,39 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify2;
 });
 
+// src/environment.ts
+var VALID_ENVIRONMENTS = new Set([
+  "development",
+  "production",
+  "test"
+]);
+var ENVIRONMENT_DEFAULTS = {
+  development: {
+    logLevel: "debug",
+    verbose: true,
+    errorDetail: "full"
+  },
+  production: {
+    logLevel: null,
+    verbose: false,
+    errorDetail: "message"
+  },
+  test: {
+    logLevel: null,
+    verbose: false,
+    errorDetail: "full"
+  }
+};
+function getEnvironment() {
+  const value = process.env["OUTFITTER_ENV"];
+  if (value !== undefined && VALID_ENVIRONMENTS.has(value)) {
+    return value;
+  }
+  return "production";
+}
+function getEnvironmentDefaults(env) {
+  return { ...ENVIRONMENT_DEFAULTS[env] };
+}
 // src/env.ts
 import { z } from "zod";
 var portSchema = z.string().regex(/^\d+$/).transform(Number).pipe(z.number().int().positive().max(65535));
@@ -9356,6 +9389,8 @@ export {
   mapEnvToConfig,
   loadConfig,
   getStateDir,
+  getEnvironmentDefaults,
+  getEnvironment,
   getEnvBoolean,
   getDataDir,
   getConfigDir,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/config",
   "description": "XDG-compliant config loading with schema validation for Outfitter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist"
@@ -9,12 +9,24 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./environment": {
+      "import": {
+        "types": "./dist/environment.d.ts",
+        "default": "./dist/environment.js"
+      }
+    },
     ".": {
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
     },
+    "./env": {
+      "import": {
+        "types": "./dist/env.d.ts",
+        "default": "./dist/env.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,