@outfitter/config 0.1.0-rc.2 → 0.1.0

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.
 *
@@ -465,5 +478,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"] ?? "";
@@ -9240,22 +9245,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 +9264,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 +9362,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.2",
+  "version": "0.1.0",
   "type": "module",
   "files": [
     "dist"
@@ -27,8 +27,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@outfitter/contracts": "workspace:*",
-    "@outfitter/types": "workspace:*",
+    "@outfitter/contracts": "0.1.0",
+    "@outfitter/types": "0.1.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {