@outfitter/config 0.3.3 → 0.4.0

package/README.md

@@ -59,11 +59,13 @@ if (result.isOk()) {
 ```
 
 **Parameters:**
+
 - `appName` - Application name for XDG directory lookup
 - `schema` - Zod schema for validation
 - `options.searchPaths` - Custom search paths (overrides XDG defaults)
 
 **Search Order:**
+
 1. Custom `searchPaths` if provided
 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
 3. `~/.config/{appName}/config.{ext}`
@@ -88,6 +90,7 @@ const result = resolveConfig(AppSchema, {
 ```
 
 **Parameters:**
+
 - `schema` - Zod schema for validation
 - `sources` - Configuration sources to merge
 
@@ -113,6 +116,7 @@ if (result.isOk()) {
 ```
 
 **Parameters:**
+
 - `content` - Raw file content
 - `filename` - Filename (extension determines parser)
 
@@ -179,6 +183,7 @@ const merged = deepMerge(defaults, overrides);
 ```
 
 **Merge Behavior:**
+
 - Recursively merges nested plain objects
 - Arrays are replaced (not concatenated)
 - `null` explicitly replaces the target value
@@ -194,10 +199,10 @@ Configuration sources for multi-layer resolution.
 
 ```typescript
 interface ConfigSources<T> {
-  defaults?: Partial<T>;  // Lowest precedence
-  file?: Partial<T>;      // From config file
-  env?: Partial<T>;       // Environment variables
-  flags?: Partial<T>;     // CLI flags (highest)
+  defaults?: Partial<T>; // Lowest precedence
+  file?: Partial<T>; // From config file
+  env?: Partial<T>; // Environment variables
+  flags?: Partial<T>; // CLI flags (highest)
 }
 ```
 
@@ -207,7 +212,7 @@ Options for `loadConfig()`.
 
 ```typescript
 interface LoadConfigOptions {
-  searchPaths?: string[];  // Custom search paths
+  searchPaths?: string[]; // Custom search paths
 }
 ```
 
@@ -256,11 +261,11 @@ 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"` |
+| Setting     | `development` | `production` | `test`   |
+| ----------- | ------------- | ------------ | -------- |
+| logLevel    | `"debug"`     | `null`       | `null`   |
+| verbose     | `true`        | `false`      | `false`  |
+| errorDetail | `"full"`      | `"message"`  | `"full"` |
 
 ### Types
 
@@ -286,12 +291,12 @@ interface EnvironmentDefaults {
 
 This package follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for locating configuration files.
 
-| Variable | macOS/Linux Default | Purpose |
-|----------|---------------------|---------|
-| `XDG_CONFIG_HOME` | `~/.config` | User-specific configuration |
-| `XDG_DATA_HOME` | `~/.local/share` | User-specific data files |
-| `XDG_CACHE_HOME` | `~/.cache` | Non-essential cached data |
-| `XDG_STATE_HOME` | `~/.local/state` | Persistent state (logs, history) |
+| Variable          | macOS/Linux Default | Purpose                          |
+| ----------------- | ------------------- | -------------------------------- |
+| `XDG_CONFIG_HOME` | `~/.config`         | User-specific configuration      |
+| `XDG_DATA_HOME`   | `~/.local/share`    | User-specific data files         |
+| `XDG_CACHE_HOME`  | `~/.cache`          | Non-essential cached data        |
+| `XDG_STATE_HOME`  | `~/.local/state`    | Persistent state (logs, history) |
 
 ---
 
@@ -317,13 +322,13 @@ Higher precedence sources override lower ones. Nested objects are deep-merged.
 
 ## Supported File Formats
 
-| Extension | Parser | Notes |
-|-----------|--------|-------|
-| `.toml` | smol-toml | Preferred for configuration |
-| `.yaml`, `.yml` | yaml | YAML anchors/aliases supported |
-| `.json` | JSON.parse | Strict parsing |
-| `.jsonc` | json5 | JSON with comments and trailing commas |
-| `.json5` | json5 | Comments and trailing commas allowed |
+| Extension       | Parser     | Notes                                  |
+| --------------- | ---------- | -------------------------------------- |
+| `.toml`         | smol-toml  | Preferred for configuration            |
+| `.yaml`, `.yml` | yaml       | YAML anchors/aliases supported         |
+| `.json`         | JSON.parse | Strict parsing                         |
+| `.jsonc`        | json5      | JSON with comments and trailing commas |
+| `.json5`        | json5      | Comments and trailing commas allowed   |
 
 ---
 

package/dist/index.d.ts

@@ -1,443 +1,10 @@
-/**
-* 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 {
-	/** How much error detail to include in output. */
-	errorDetail: "full" | "message";
-	/** 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;
-}
-/**
-* 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.
-*
-* Validates that a string contains only digits, then transforms
-* to a number and validates the port range.
-*
-* @example
-* ```typescript
-* const schema = z.object({ PORT: portSchema });
-* schema.parse({ PORT: "3000" }); // { PORT: 3000 }
-* schema.parse({ PORT: "invalid" }); // throws
-* schema.parse({ PORT: "99999" }); // throws (out of range)
-* ```
-*/
-declare const portSchema: z.ZodType<number, string>;
-/**
-* Boolean schema with proper string coercion.
-*
-* Accepts: "true", "false", "1", "0", ""
-* - "true" or "1" -> true
-* - "false", "0", or "" -> false
-*
-* @example
-* ```typescript
-* const schema = z.object({ DEBUG: booleanSchema });
-* schema.parse({ DEBUG: "true" }); // { DEBUG: true }
-* schema.parse({ DEBUG: "1" }); // { DEBUG: true }
-* schema.parse({ DEBUG: "false" }); // { DEBUG: false }
-* schema.parse({ DEBUG: "" }); // { DEBUG: false }
-* ```
-*/
-declare const booleanSchema: z.ZodType<boolean, string>;
-/**
-* Optional boolean schema - returns undefined if not set.
-*
-* Unlike `booleanSchema`, this returns `undefined` for missing
-* or empty values, allowing callers to distinguish between
-* "explicitly set to false" and "not set".
-*
-* @example
-* ```typescript
-* const schema = z.object({ NO_COLOR: optionalBooleanSchema });
-* schema.parse({ NO_COLOR: "true" }); // { NO_COLOR: true }
-* schema.parse({ NO_COLOR: "" }); // { NO_COLOR: undefined }
-* schema.parse({ NO_COLOR: undefined }); // { NO_COLOR: undefined }
-* ```
-*/
-declare const optionalBooleanSchema: z.ZodType<boolean | undefined, string | undefined>;
-/**
-* Parse and validate environment variables against a Zod schema.
-*
-* By default reads from `process.env`, but accepts a custom env
-* object for testing.
-*
-* @typeParam T - The Zod schema shape
-* @param schema - Zod object schema to validate against
-* @param envObj - Environment object (defaults to process.env)
-* @returns Validated and transformed environment object
-* @throws {z.ZodError} When validation fails
-*
-* @example
-* ```typescript
-* const AppEnv = z.object({
-*   PORT: portSchema,
-*   DEBUG: booleanSchema,
-* });
-*
-* const env = parseEnv(AppEnv);
-* console.log(env.PORT); // number
-* console.log(env.DEBUG); // boolean
-* ```
-*/
-declare function parseEnv<T extends z.ZodRawShape>(schema: z.ZodObject<T>, envObj?: Record<string, string | undefined>): z.infer<z.ZodObject<T>>;
-type AppEnvShape = {
-	NODE_ENV: z.ZodDefault<z.ZodEnum<{
-		development: "development";
-		test: "test";
-		production: "production";
-	}>>;
-	NO_COLOR: typeof optionalBooleanSchema;
-	FORCE_COLOR: typeof optionalBooleanSchema;
-	CI: typeof optionalBooleanSchema;
-	TERM: z.ZodOptional<z.ZodString>;
-	XDG_CONFIG_HOME: z.ZodOptional<z.ZodString>;
-	XDG_DATA_HOME: z.ZodOptional<z.ZodString>;
-	XDG_STATE_HOME: z.ZodOptional<z.ZodString>;
-	XDG_CACHE_HOME: z.ZodOptional<z.ZodString>;
-	HOME: z.ZodOptional<z.ZodString>;
-};
-/**
-* Schema for common application environment variables.
-*/
-declare const appEnvSchema: z.ZodObject<AppEnvShape>;
-/**
-* Type for the pre-parsed application environment.
-*/
-type Env = z.infer<typeof appEnvSchema>;
-/**
-* Pre-parsed application environment.
-*
-* Access common environment variables with proper typing:
-* - `env.NODE_ENV`: "development" | "test" | "production"
-* - `env.NO_COLOR`: boolean | undefined
-* - `env.FORCE_COLOR`: boolean | undefined
-* - `env.CI`: boolean | undefined
-* - `env.TERM`: string | undefined
-* - `env.XDG_*`: string | undefined
-* - `env.HOME`: string | undefined
-*
-* @example
-* ```typescript
-* import { env } from "@outfitter/config";
-*
-* if (env.CI) {
-*   console.log("Running in CI environment");
-* }
-*
-* if (env.NO_COLOR) {
-*   // Disable color output
-* }
-* ```
-*/
-declare const env: Env;
-/**
-* Reads an optional boolean from process.env at call time.
-*
-* Unlike `env.NO_COLOR` (which is static), this reads dynamically
-* for use cases where env vars may change at runtime (e.g., tests).
-*
-* @param key - The environment variable name to read
-* @returns `true` if "true"/"1", `false` if "false"/"0", `undefined` otherwise
-*
-* @example
-* ```typescript
-* // For terminal detection that needs dynamic behavior
-* if (getEnvBoolean("NO_COLOR")) {
-*   // colors disabled
-* }
-* ```
-*/
-declare function getEnvBoolean(key: "NO_COLOR" | "FORCE_COLOR" | "CI"): boolean | undefined;
-import { TaggedErrorClass } from "@outfitter/contracts";
-import { NotFoundError, Result, ValidationError } from "@outfitter/contracts";
+import { Env, booleanSchema, env, getEnvBoolean, optionalBooleanSchema, parseEnv, portSchema } from "./shared/@outfitter/config-veqxf02x.js";
+import { EnvironmentDefaults, OutfitterEnv, getEnvironment, getEnvironmentDefaults } from "./shared/@outfitter/config-wawavx3r.js";
+import { getCacheDir, getConfigDir, getDataDir, getStateDir } from "./shared/@outfitter/config-6449x3br.js";
+import { LoadConfigOptions, loadConfig } from "./shared/@outfitter/config-7dyshh4r.js";
+import { CircularExtendsError, ParseError, deepMerge, parseConfigFile } from "./shared/@outfitter/config-sp6gradd.js";
+import { Result, ValidationError } from "@outfitter/contracts";
 import { ZodSchema } from "zod";
-type ParseErrorFields = {
-	/** Human-readable error message describing the parse failure */
-	message: string;
-	/** Name of the file that failed to parse */
-	filename: string;
-	/** Line number where the error occurred (if available) */
-	line?: number;
-	/** Column number where the error occurred (if available) */
-	column?: number;
-};
-declare const ParseErrorBase: TaggedErrorClass<"ParseError", ParseErrorFields>;
-/**
-* Error thrown when a configuration file cannot be parsed.
-*
-* Contains details about the parse failure including the filename
-* and optionally the line/column where the error occurred.
-*
-* @example
-* ```typescript
-* const result = parseConfigFile("invalid toml [", "config.toml");
-* if (result.isErr() && result.error._tag === "ParseError") {
-*   console.error(`Parse error in ${result.error.filename}: ${result.error.message}`);
-* }
-* ```
-*/
-declare class ParseError extends ParseErrorBase {
-	readonly category: "validation";
-}
-type CircularExtendsErrorFields = {
-	/** Human-readable error message */
-	message: string;
-	/** The config file paths that form the circular reference */
-	chain: string[];
-};
-declare const CircularExtendsErrorBase: TaggedErrorClass<"CircularExtendsError", CircularExtendsErrorFields>;
-/**
-* Error thrown when a circular extends reference is detected.
-*/
-declare class CircularExtendsError extends CircularExtendsErrorBase {
-	readonly category: "validation";
-}
-/**
-* Get the XDG config directory for an application.
-*
-* Uses `XDG_CONFIG_HOME` if set, otherwise defaults to `~/.config`.
-* This follows the XDG Base Directory Specification for storing
-* user-specific configuration files.
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's config directory
-*
-* @example
-* ```typescript
-* // With XDG_CONFIG_HOME="/custom/config"
-* getConfigDir("myapp"); // "/custom/config/myapp"
-*
-* // Without XDG_CONFIG_HOME (uses default)
-* getConfigDir("myapp"); // "/home/user/.config/myapp"
-* ```
-*/
-declare function getConfigDir(appName: string): string;
-/**
-* Get the XDG data directory for an application.
-*
-* Uses `XDG_DATA_HOME` if set, otherwise defaults to `~/.local/share`.
-* This follows the XDG Base Directory Specification for storing
-* user-specific data files (databases, generated content, etc.).
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's data directory
-*
-* @example
-* ```typescript
-* // With XDG_DATA_HOME="/custom/data"
-* getDataDir("myapp"); // "/custom/data/myapp"
-*
-* // Without XDG_DATA_HOME (uses default)
-* getDataDir("myapp"); // "/home/user/.local/share/myapp"
-* ```
-*/
-declare function getDataDir(appName: string): string;
-/**
-* Get the XDG cache directory for an application.
-*
-* Uses `XDG_CACHE_HOME` if set, otherwise defaults to `~/.cache`.
-* This follows the XDG Base Directory Specification for storing
-* non-essential cached data that can be regenerated.
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's cache directory
-*
-* @example
-* ```typescript
-* // With XDG_CACHE_HOME="/custom/cache"
-* getCacheDir("myapp"); // "/custom/cache/myapp"
-*
-* // Without XDG_CACHE_HOME (uses default)
-* getCacheDir("myapp"); // "/home/user/.cache/myapp"
-* ```
-*/
-declare function getCacheDir(appName: string): string;
-/**
-* Get the XDG state directory for an application.
-*
-* Uses `XDG_STATE_HOME` if set, otherwise defaults to `~/.local/state`.
-* This follows the XDG Base Directory Specification for storing
-* state data that should persist between restarts (logs, history, etc.).
-*
-* @param appName - Application name used as subdirectory
-* @returns Absolute path to the application's state directory
-*
-* @example
-* ```typescript
-* // With XDG_STATE_HOME="/custom/state"
-* getStateDir("myapp"); // "/custom/state/myapp"
-*
-* // Without XDG_STATE_HOME (uses default)
-* getStateDir("myapp"); // "/home/user/.local/state/myapp"
-* ```
-*/
-declare function getStateDir(appName: string): string;
-/**
-* Deep merge two objects with configurable merge semantics.
-*
-* Merge behavior:
-* - Recursively merges nested plain objects
-* - Arrays are replaced (not concatenated)
-* - `null` explicitly replaces the target value
-* - `undefined` is skipped (does not override)
-*
-* @typeParam T - The type of the target object
-* @param target - Base object to merge into (not mutated)
-* @param source - Object with values to merge
-* @returns New object with merged values
-*
-* @example
-* ```typescript
-* const defaults = { server: { port: 3000, host: "localhost" } };
-* const overrides = { server: { port: 8080 } };
-*
-* const merged = deepMerge(defaults, overrides);
-* // { server: { port: 8080, host: "localhost" } }
-* ```
-*
-* @example
-* ```typescript
-* // Arrays replace, not merge
-* const target = { tags: ["a", "b"] };
-* const source = { tags: ["c"] };
-* deepMerge(target, source); // { tags: ["c"] }
-*
-* // undefined is skipped
-* const base = { a: 1, b: 2 };
-* deepMerge(base, { a: undefined, b: 3 }); // { a: 1, b: 3 }
-*
-* // null explicitly replaces
-* deepMerge(base, { a: null }); // { a: null, b: 2 }
-* ```
-*/
-declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
-/**
-* Parse configuration file content based on filename extension.
-*
-* Supports multiple formats:
-* - `.toml` - Parsed with smol-toml (preferred for config)
-* - `.yaml`, `.yml` - Parsed with yaml (merge key support enabled)
-* - `.json` - Parsed with strict JSON.parse
-* - `.jsonc` - Parsed with json5 compatibility (comments/trailing commas)
-* - `.json5` - Parsed with json5 (comments and trailing commas allowed)
-*
-* @param content - Raw file content to parse
-* @param filename - Filename used to determine format (by extension)
-* @returns Result containing parsed object or ParseError
-*
-* @example
-* ```typescript
-* const toml = `
-* [server]
-* port = 3000
-* host = "localhost"
-* `;
-*
-* const result = parseConfigFile(toml, "config.toml");
-* if (result.isOk()) {
-*   console.log(result.value.server.port); // 3000
-* }
-* ```
-*
-* @example
-* ```typescript
-* // YAML with anchors/aliases
-* const yaml = `
-* defaults: &defaults
-*   timeout: 5000
-* server:
-*   <<: *defaults
-*   port: 3000
-* `;
-*
-* const result = parseConfigFile(yaml, "config.yaml");
-* if (result.isOk()) {
-*   console.log(result.value.server.timeout); // 5000
-* }
-* ```
-*/
-declare function parseConfigFile(content: string, filename: string): Result<Record<string, unknown>, InstanceType<typeof ParseError>>;
 /**
 * Configuration sources for multi-layer resolution.
 *
@@ -503,73 +70,6 @@ interface ConfigSources<T> {
 */
 declare function resolveConfig<T>(schema: ZodSchema<T>, sources: ConfigSources<T>): Result<T, InstanceType<typeof ValidationError> | InstanceType<typeof ParseError>>;
 /**
-* Options for the {@link loadConfig} function.
-*
-* @example
-* ```typescript
-* const options: LoadConfigOptions = {
-*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
-* };
-* ```
-*/
-interface LoadConfigOptions {
-	/**
-	* Custom search paths to check for config files.
-	* When provided, overrides the default XDG-based search paths.
-	* Paths are searched in order; first match wins.
-	*/
-	searchPaths?: string[];
-}
-/**
-* Load configuration for an application from XDG-compliant paths.
-*
-* Search order (first found wins):
-* 1. Custom `searchPaths` if provided in options
-* 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
-* 3. `~/.config/{appName}/config.{ext}`
-*
-* File format preference: `.toml` > `.yaml` > `.yml` > `.json` > `.jsonc` > `.json5`
-*
-* @typeParam T - The configuration type (inferred from schema)
-* @param appName - Application name for XDG directory lookup
-* @param schema - Zod schema for validation
-* @param options - Optional configuration (custom search paths)
-* @returns Result containing validated config or NotFoundError/ValidationError/ParseError
-*
-* @example
-* ```typescript
-* import { loadConfig } from "@outfitter/config";
-* import { z } from "zod";
-*
-* const AppConfigSchema = z.object({
-*   apiKey: z.string(),
-*   timeout: z.number().default(5000),
-*   features: z.object({
-*     darkMode: z.boolean().default(false),
-*   }),
-* });
-*
-* // Searches ~/.config/myapp/config.{toml,yaml,json,...}
-* const result = await loadConfig("myapp", AppConfigSchema);
-*
-* if (result.isOk()) {
-*   console.log("API Key:", result.value.apiKey);
-*   console.log("Timeout:", result.value.timeout);
-* } else {
-*   console.error("Failed to load config:", result.error.message);
-* }
-* ```
-*
-* @example
-* ```typescript
-* // With custom search paths
-* const result = await loadConfig("myapp", AppConfigSchema, {
-*   searchPaths: ["/etc/myapp", "/opt/myapp/config"],
-* });
-* ```
-*/
-declare function loadConfig<T>(appName: string, schema: ZodSchema<T>, options?: LoadConfigOptions): Result<T, InstanceType<typeof NotFoundError> | InstanceType<typeof ValidationError> | InstanceType<typeof ParseError> | InstanceType<typeof CircularExtendsError>>;
-/**
 * Map environment variables to config object based on prefix.
 *
 * Environment variables are mapped as follows: