(v1) Unify error normalization and formatting

.changeset/unified-error-normalization.md

@@ -0,0 +1,13 @@
+---
+"arkenv": minor
+---
+
+#### Refactor error system to use normalized `EnvIssue` and add `safeCreateEnv` API
+
+**BREAKING CHANGE**: Unify validation error formatting across all validation engines (ArkType and Standard Schema). The exact text format of the `message` property on thrown `ArkEnvError` instances has changed. Check and update any test suites or CI/CD pipelines that assert on the exact error message text.
+
+- Implement `EnvIssue` type and attach the full list of errors to `ArkEnvError.issues` for programmatic access.
+- Add `safeCreateEnv` API to both `arkenv` and `arkenv/standard` entries for non-throwing validation in Server Actions or Next.js components.
+- Standardize Standard Schema validation errors to look and act like ArkType validation errors, resolving received values and flattening paths.
+- Redact credentials and sensitive environment variables by default in stringified error reports.
+- Support `debugSecrets` configuration and `process.env.ARKENV_DEBUG_SECRETS=true` to temporarily bypass redaction.

packages/arkenv/package.json

@@ -89,7 +89,7 @@
 		{
 			"name": "arkenv",
 			"path": "dist/index.mjs",
-			"limit": "2.1 kB",
+			"limit": "2.3 kB",
 			"import": "*",
 			"ignore": [
 				"arktype"

packages/arkenv/src/arkenv.ts

@@ -6,7 +6,8 @@ import type {
 	SchemaShape,
 } from "@repo/types";
 import type { type as at, distill } from "arktype";
-import { parse } from "./arktype";
+import { parse } from "./arktype/index.ts";
+import { ArkEnvError, type EnvIssue } from "./core.ts";
 
 /**
  * Declarative environment schema definition accepted by ArkEnv.
@@ -80,6 +81,12 @@ export type ArkEnvConfig = {
 	 */
 	arrayFormat?: "comma" | "json";
 
+	/**
+	 * Whether to bypass secret redaction and print raw sensitive values during debugging.
+	 * Defaults to checking `process.env.ARKENV_DEBUG_SECRETS === "true"` or `"1"`.
+	 */
+	debugSecrets?: boolean;
+
 	/**
 	 * Whether to treat empty strings (`""`) as `undefined` before validation.
 	 *
@@ -93,10 +100,11 @@ export type ArkEnvConfig = {
 };
 
 /**
- * TODO: `SchemaShape` is basically `Record<string, unknown>`.
- * If possible, find a better type than "const T extends Record<string, unknown>",
- * and be as close as possible to the type accepted by ArkType's `type`.
+ * The result structure returned by safeCreateEnv.
  */
+export type SafeCreateEnvResult<T> =
+	| { success: true; data: T }
+	| { success: false; error: string; issues: EnvIssue[] };
 
 /**
  * Utility to parse environment variables using ArkType or Standard Schema
@@ -124,3 +132,38 @@ export function arkenv<const T extends SchemaShape>(
 	// biome-ignore lint/suspicious/noExplicitAny: parse handles both EnvSchema<T> and CompiledEnvSchema at runtime
 	return parse(def as any, config);
 }
+
+/**
+ * Non-throwing utility to parse environment variables using ArkType or Standard Schema.
+ * Returns a serializable result object containing either the validated data or error issues.
+ *
+ * @param def - The schema definition
+ * @param config - The evaluation configuration
+ * @returns The SafeCreateEnvResult containing the data or plain error issues
+ */
+export function safeCreateEnv<const T extends SchemaShape>(
+	def: EnvSchema<T>,
+	config?: ArkEnvConfig,
+): SafeCreateEnvResult<distill.Out<at.infer<T, $>>>;
+export function safeCreateEnv<T extends CompiledEnvSchema>(
+	def: T,
+	config?: ArkEnvConfig,
+): SafeCreateEnvResult<InferType<T>>;
+export function safeCreateEnv<const T extends SchemaShape>(
+	def: EnvSchema<T> | CompiledEnvSchema,
+	config?: ArkEnvConfig,
+): SafeCreateEnvResult<distill.Out<at.infer<T, $>> | InferType<typeof def>>;
+export function safeCreateEnv<const T extends SchemaShape>(
+	def: EnvSchema<T> | CompiledEnvSchema,
+	config: ArkEnvConfig = {},
+): SafeCreateEnvResult<distill.Out<at.infer<T, $>> | InferType<typeof def>> {
+	try {
+		const data = arkenv(def as any, config);
+		return { success: true, data };
+	} catch (error) {
+		if (error instanceof ArkEnvError) {
+			return { success: false, error: error.message, issues: error.issues };
+		}
+		throw error;
+	}
+}

packages/arkenv/src/arktype/index.ts

@@ -2,14 +2,20 @@ import { $ } from "@repo/scope";
 import type { SchemaShape } from "@repo/types";
 import type { distill } from "arktype";
 import { ArkErrors } from "arktype";
-import type { ArkEnvConfig, EnvSchema } from "@/arkenv";
+import type { ArkEnvConfig, EnvSchema } from "../arkenv.ts";
 import {
 	applyCoercion,
 	findCoercionPaths,
 	stripEmptyStrings,
-} from "@/coercion";
-import { ArkEnvError, type ValidationIssue } from "@/core";
-import { styleText } from "@/utils/style-text";
+} from "../coercion/index.ts";
+import {
+	ArkEnvError,
+	type EnvIssue,
+	type EnvIssueCode,
+	type EnvIssueMeta,
+} from "../core.ts";
+import { shouldRedact } from "../utils/redact.ts";
+import { styleText } from "../utils/style-text.ts";
 
 /**
  * Re-export of ArkType's `distill` utilities.
@@ -23,17 +29,20 @@ import { styleText } from "@/utils/style-text";
 export type { distill };
 
 /**
- * Converts ArkType's `ArkErrors` (keyed by path) into a flat `ValidationIssue[]`
+ * Converts ArkType's `ArkErrors` (keyed by path) into a flat `EnvIssue[]`
  * suitable for `ArkEnvError`. Strips leading path references from messages to
- * avoid duplication when `formatInternalErrors` prepends the styled path, and
+ * avoid duplication when `formatIssues` prepends the styled path, and
  * applies cyan styling to inline "(was …)" values.
  *
  * @param errors The ArkType errors object to convert
  * @returns An array of flattened validation issues
  *
  * @internal
  */
-function arkErrorsToIssues(errors: ArkErrors): ValidationIssue[] {
+function arkErrorsToIssues(
+	errors: ArkErrors,
+	config?: ArkEnvConfig,
+): EnvIssue[] {
 	return Object.entries(errors.byPath).map(([path, error]) => {
 		let message = error.message;
 
@@ -50,19 +59,71 @@ function arkErrorsToIssues(errors: ArkErrors): ValidationIssue[] {
 			message = rest.trimStart();
 		}
 
+		// Check for redaction
+		const debugSecrets =
+			config?.debugSecrets ??
+			(typeof process !== "undefined" &&
+				(process.env.ARKENV_DEBUG_SECRETS === "true" ||
+					process.env.ARKENV_DEBUG_SECRETS === "1"));
+		const isSensitive = shouldRedact(path);
+
 		// Style (was ...) inline values
 		const valueMatch = message.match(/\(was (.*)\)/);
 		if (valueMatch?.[1]) {
 			const value = valueMatch[1];
-			if (!value.includes("\x1b[")) {
+			const displayedValue =
+				!debugSecrets && isSensitive ? "[REDACTED]" : value;
+			if (!displayedValue.includes("\x1b[")) {
 				message = message.replace(
 					`(was ${value})`,
-					`(was ${styleText("cyan", value)})`,
+					`(was ${styleText("cyan", displayedValue)})`,
 				);
 			}
 		}
 
-		return { path, message };
+		// Map code
+		let code: EnvIssueCode = "INVALID_TYPE";
+		if (error.code === "required") {
+			code = "MISSING_VARIABLE";
+		} else if (error.code === "pattern") {
+			code = "PATTERN_MISMATCH";
+		} else if (["min", "minLength"].includes(error.code)) {
+			code = "VALUE_TOO_SMALL";
+		} else if (["max", "maxLength"].includes(error.code)) {
+			code = "VALUE_TOO_LARGE";
+		} else if (
+			["divisor", "index", "sequence", "intersection", "union"].includes(
+				error.code,
+			)
+		) {
+			code = "INVALID_TYPE";
+		} else {
+			code = "INVALID_FORMAT";
+		}
+
+		// Safe meta extraction
+		const meta: EnvIssueMeta = {
+			engine: "arktype",
+			engineCode: error.code,
+		};
+		const errObj = error as any;
+		if (errObj.min !== undefined && typeof errObj.min === "number") {
+			meta.min = errObj.min;
+		} else if (errObj.rule !== undefined && typeof errObj.rule === "number") {
+			meta.min = errObj.rule;
+		}
+		if (errObj.max !== undefined && typeof errObj.max === "number") {
+			meta.max = errObj.max;
+		}
+
+		return {
+			path,
+			message,
+			code,
+			expected: error.expected,
+			received: error.code === "required" ? undefined : error.data,
+			meta,
+		};
 	});
 }
 
@@ -130,7 +191,7 @@ export function parse<const T extends SchemaShape>(
 
 	// In ArkType 2.x, calling a type as a function returns the validated data or ArkErrors
 	if (validatedEnv instanceof ArkErrors) {
-		throw new ArkEnvError(arkErrorsToIssues(validatedEnv));
+		throw new ArkEnvError(arkErrorsToIssues(validatedEnv, config));
 	}
 
 	return validatedEnv;

packages/arkenv/src/core.ts

@@ -1,22 +1,63 @@
 import { indent } from "./utils/indent";
 import { styleText } from "./utils/style-text";
 
-/**
- * A single validation issue produced during environment variable parsing.
- * Used by {@link ArkEnvError} to report which key failed and why.
- */
-export type ValidationIssue = {
+export type EnvIssueCode =
+	| "MISSING_VARIABLE"
+	| "INVALID_TYPE"
+	| "VALUE_TOO_SMALL"
+	| "VALUE_TOO_LARGE"
+	| "PATTERN_MISMATCH"
+	| "INVALID_FORMAT"
+	| "UNDECLARED_KEY"
+	| "INVALID_SCHEMA"
+	| "CUSTOM";
+
+export type EnvIssueMeta = {
+	min?: number;
+	max?: number;
+	validation?: string;
+	constraint?: string;
+	engineCode?: string;
+	engine: "arktype" | "zod" | "valibot" | "unknown";
+	traversalError?: string;
+};
+
+export type EnvIssue = {
 	path: string;
 	message: string;
+	code: EnvIssueCode;
+	expected?: string;
+	received?: unknown;
+	meta?: EnvIssueMeta;
 };
 
-export const formatInternalErrors = (errors: ValidationIssue[]): string =>
-	errors
-		.map(
-			(error) =>
-				`${styleText("yellow", error.path)} ${error.message.trimStart()}`,
-		)
+/**
+ * @deprecated Use EnvIssue instead
+ */
+export type ValidationIssue = EnvIssue;
+
+export function formatIssues(issues: EnvIssue[]): string {
+	return issues
+		.map((issue) => {
+			const pathStr = styleText("yellow", issue.path);
+			const messageStr = issue.message.trimStart();
+			return `${pathStr} ${messageStr}`;
+		})
 		.join("\n");
+}
+
+export function formatError(error: ArkEnvError | EnvIssue[]): string {
+	if (Array.isArray(error)) {
+		return formatIssues(error);
+	}
+	return formatIssues(error.issues);
+}
+
+/**
+ * @deprecated Use formatIssues instead
+ */
+export const formatInternalErrors = (errors: ValidationIssue[]): string =>
+	formatIssues(errors);
 
 /**
  * Error thrown when environment variable validation fails.
@@ -42,13 +83,16 @@ export const formatInternalErrors = (errors: ValidationIssue[]): string =>
  * ```
  */
 export class ArkEnvError extends Error {
+	readonly issues: EnvIssue[];
+
 	constructor(
-		errors: ValidationIssue[],
+		issues: EnvIssue[],
 		message = "Errors found while validating environment variables",
 	) {
-		const formattedErrors = formatInternalErrors(errors);
+		const formattedErrors = formatIssues(issues);
 		super(`${styleText("red", message)}\n${indent(formattedErrors)}\n`);
 		this.name = "ArkEnvError";
+		this.issues = issues;
 	}
 }