@outfitter/config 0.1.0-rc.3 → 0.2.0

package/README.md

@@ -68,7 +68,7 @@ if (result.isOk()) {
 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
 3. `~/.config/{appName}/config.{ext}`
 
-**File Format Preference:** `.toml` > `.yaml` > `.yml` > `.json` > `.json5`
+**File Format Preference:** `.toml` > `.yaml` > `.yml` > `.json` > `.jsonc` > `.json5`
 
 **Returns:** `Result<T, NotFoundError | ValidationError | ParseError>`
 
@@ -267,6 +267,7 @@ Higher precedence sources override lower ones. Nested objects are deep-merged.
 | `.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

@@ -171,6 +171,19 @@ declare const ParseErrorBase: TaggedErrorClass<"ParseError", ParseErrorFields>;
 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.
 *
@@ -297,6 +310,7 @@ declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
 * - `.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
@@ -425,7 +439,7 @@ interface LoadConfigOptions {
 * 2. `$XDG_CONFIG_HOME/{appName}/config.{ext}`
 * 3. `~/.config/{appName}/config.{ext}`
 *
-* File format preference: `.toml` > `.yaml` > `.yml` > `.json` > `.json5`
+* 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
@@ -465,5 +479,34 @@ interface LoadConfigOptions {
 * });
 * ```
 */
-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 };
+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:
+* - `PREFIX_KEY` -> `{ key: value }`
+* - `PREFIX_NESTED__KEY` -> `{ nested: { key: value } }`
+*
+* Only returns values for keys that have matching env vars set.
+* Values are returned as strings; use Zod coercion for type conversion.
+*
+* @param prefix - Environment variable prefix (e.g., "MYAPP")
+* @param schema - Zod schema to determine valid keys (optional, for filtering)
+* @returns Partial config object with mapped values
+*
+* @example
+* ```typescript
+* // With MYAPP_PORT=8080 and MYAPP_DB__HOST=localhost
+* const schema = z.object({
+*   port: z.coerce.number(),
+*   db: z.object({ host: z.string() }),
+* });
+*
+* const envConfig = mapEnvToConfig("MYAPP", schema);
+* // { port: "8080", db: { host: "localhost" } }
+*
+* const result = resolveConfig(schema, { env: envConfig });
+* ```
+*/
+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 };

package/dist/index.js

@@ -8069,7 +8069,7 @@ function getEnvBoolean(key) {
 // src/index.ts
 var import_json5 = __toESM(require_lib(), 1);
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import {
   NotFoundError,
   Result,
@@ -9070,6 +9070,11 @@ var ParseErrorBase = TaggedError("ParseError")();
 class ParseError extends ParseErrorBase {
   category = "validation";
 }
+var CircularExtendsErrorBase = TaggedError("CircularExtendsError")();
+
+class CircularExtendsError extends CircularExtendsErrorBase {
+  category = "validation";
+}
 function getConfigDir(appName) {
   const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
   const home = process.env["HOME"] ?? "";
@@ -9154,6 +9159,7 @@ function parseConfigFile(content, filename) {
         const parsed = JSON.parse(content);
         return Result.ok(parsed);
       }
+      case "jsonc":
       case "json5": {
         const parsed = import_json5.default.parse(content);
         return Result.ok(parsed);
@@ -9201,7 +9207,7 @@ function resolveConfig(schema, sources) {
   }
   return Result.ok(parseResult.data);
 }
-var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "json5"];
+var CONFIG_EXTENSIONS = ["toml", "yaml", "yml", "json", "jsonc", "json5"];
 function findConfigFile(dir) {
   for (const ext of CONFIG_EXTENSIONS) {
     const filePath = join(dir, `config.${ext}`);
@@ -9240,22 +9246,11 @@ function loadConfig(appName, schema, options) {
       resourceId: appName
     }));
   }
-  let content;
-  try {
-    content = readFileSync(configFilePath, "utf-8");
-  } catch {
-    return Result.err(new NotFoundError({
-      message: `Failed to read config file: ${configFilePath}`,
-      resourceType: "config",
-      resourceId: configFilePath
-    }));
-  }
-  const filename = configFilePath.split("/").pop() ?? "config";
-  const parseResult = parseConfigFile(content, filename);
-  if (parseResult.isErr()) {
-    return Result.err(parseResult.error);
+  const loadResult = loadConfigFileWithExtends(configFilePath);
+  if (loadResult.isErr()) {
+    return Result.err(loadResult.error);
   }
-  const parsed = parseResult.unwrap();
+  const parsed = loadResult.unwrap();
   const validateResult = schema.safeParse(parsed);
   if (!validateResult.success) {
     const issues = validateResult.error.issues;
@@ -9270,12 +9265,95 @@ function loadConfig(appName, schema, options) {
   }
   return Result.ok(validateResult.data);
 }
+function resolveExtendsPath(extendsValue, fromFile) {
+  if (isAbsolute(extendsValue)) {
+    return extendsValue;
+  }
+  return resolve(dirname(fromFile), extendsValue);
+}
+function loadConfigFileWithExtends(filePath, visited = new Set) {
+  const normalizedPath = resolve(filePath);
+  if (visited.has(normalizedPath)) {
+    return Result.err(new CircularExtendsError({
+      message: `Circular extends detected: ${[...visited, normalizedPath].join(" -> ")}`,
+      chain: [...visited, normalizedPath]
+    }));
+  }
+  if (!existsSync(filePath)) {
+    return Result.err(new NotFoundError({
+      message: `Config file not found: ${filePath}`,
+      resourceType: "config",
+      resourceId: filePath
+    }));
+  }
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    return Result.err(new NotFoundError({
+      message: `Failed to read config file: ${filePath}`,
+      resourceType: "config",
+      resourceId: filePath
+    }));
+  }
+  const filename = filePath.split("/").pop() ?? "config";
+  const parseResult = parseConfigFile(content, filename);
+  if (parseResult.isErr()) {
+    return Result.err(parseResult.error);
+  }
+  const parsed = parseResult.unwrap();
+  const extendsValue = parsed["extends"];
+  if (extendsValue === undefined) {
+    return Result.ok(parsed);
+  }
+  if (typeof extendsValue !== "string") {
+    return Result.err(new ParseError({
+      message: `Invalid "extends" value in ${filePath}: expected string, got ${typeof extendsValue}`,
+      filename: filePath
+    }));
+  }
+  visited.add(normalizedPath);
+  const extendsPath = resolveExtendsPath(extendsValue, filePath);
+  const baseResult = loadConfigFileWithExtends(extendsPath, visited);
+  if (baseResult.isErr()) {
+    return Result.err(baseResult.error);
+  }
+  const baseConfig = baseResult.unwrap();
+  const { extends: __, ...currentConfig } = parsed;
+  return Result.ok(deepMerge(baseConfig, currentConfig));
+}
+function mapEnvToConfig(prefix, _schema) {
+  const result = {};
+  const prefixWithUnderscore = `${prefix}_`;
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith(prefixWithUnderscore) || value === undefined) {
+      continue;
+    }
+    const configPath = key.slice(prefixWithUnderscore.length).toLowerCase().split("__");
+    let current = result;
+    for (let i = 0;i < configPath.length - 1; i++) {
+      const segment = configPath[i];
+      if (segment === undefined)
+        continue;
+      if (!(segment in current)) {
+        current[segment] = {};
+      }
+      current = current[segment];
+    }
+    const lastSegment = configPath.at(-1);
+    if (lastSegment !== undefined) {
+      current[lastSegment] = value;
+    }
+  }
+  return result;
+}
 export {
   resolveConfig,
   portSchema,
   parseEnv,
   parseConfigFile,
   optionalBooleanSchema,
+  mapEnvToConfig,
   loadConfig,
   getStateDir,
   getEnvBoolean,
@@ -9285,5 +9363,6 @@ export {
   env,
   deepMerge,
   booleanSchema,
-  ParseError
+  ParseError,
+  CircularExtendsError
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/config",
   "description": "XDG-compliant config loading with schema validation for Outfitter",
-  "version": "0.1.0-rc.3",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist"
@@ -27,8 +27,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.1.0-rc.2",
-    "@outfitter/types": "0.1.0-rc.3",
+    "@outfitter/contracts": "0.2.0",
+    "@outfitter/types": "0.2.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {