@outfitter/config 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+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 { 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";
+}
+/**
+* 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
+* - `.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.
+*
+* Sources are merged in precedence order (lowest to highest):
+* `defaults` < `file` < `env` < `flags`
+*
+* @typeParam T - The configuration type
+*
+* @example
+* ```typescript
+* const sources: ConfigSources<AppConfig> = {
+*   defaults: { timeout: 5000, debug: false },
+*   file: loadedFromDisk,
+*   env: { timeout: parseInt(process.env.TIMEOUT!) },
+*   flags: { debug: cliArgs.debug },
+* };
+* ```
+*/
+interface ConfigSources<T> {
+	/** Default values (lowest precedence) */
+	defaults?: Partial<T>;
+	/** Values loaded from config file */
+	file?: Partial<T>;
+	/** Values from environment variables */
+	env?: Partial<T>;
+	/** CLI flag values (highest precedence) */
+	flags?: Partial<T>;
+}
+/**
+* Resolve configuration from multiple sources with precedence.
+*
+* Merges sources in order: `defaults` < `file` < `env` < `flags`.
+* Higher precedence sources override lower ones. Nested objects
+* are deep-merged; arrays are replaced.
+*
+* The merged result is validated against the provided Zod schema.
+*
+* @typeParam T - The configuration type (inferred from schema)
+* @param schema - Zod schema for validation
+* @param sources - Configuration sources to merge
+* @returns Result containing validated config or ValidationError/ParseError
+*
+* @example
+* ```typescript
+* const AppSchema = z.object({
+*   port: z.number().min(1).max(65535),
+*   host: z.string(),
+*   debug: z.boolean().default(false),
+* });
+*
+* const result = resolveConfig(AppSchema, {
+*   defaults: { port: 3000, host: "localhost" },
+*   file: { port: 8080 },
+*   env: { debug: true },
+*   flags: { port: 9000 },
+* });
+*
+* if (result.isOk()) {
+*   // { port: 9000, host: "localhost", debug: true }
+*   console.log(result.value);
+* }
+* ```
+*/
+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` > `.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>>;
+export { resolveConfig, portSchema, parseEnv, parseConfigFile, optionalBooleanSchema, loadConfig, getStateDir, getEnvBoolean, getDataDir, getConfigDir, getCacheDir, env, deepMerge, booleanSchema, ParseError, LoadConfigOptions, Env, ConfigSources };