Merge pull request #1157 from yamcodes/709-unify-error-normalization-and-formatting

(v1) Unify error normalization and formatting

Author: yamcodes

.changeset/unified-error-normalization.md

@@ -0,0 +1,18 @@
+---
+"arkenv": major
+---
+
+#### Refactor error system to use normalized `EnvIssue` and add `{ safe: true }` API
+
+Introduce a unified `EnvIssue` type for programmatic access to validation issues via `ArkEnvError.issues`, and add the non-throwing `{ safe: true }` configuration option to `arkenv`.
+
+Error messages now use ANSI colors instead of a bullet-point prefix:
+
+```diff
+- - [PORT] must be a valid port number (was "invalid-port")
++ PORT must be a valid port number (was "invalid-port")
+```
+
+Note: Header (red), variable path (yellow), and received value (cyan) are now styled with ANSI escape codes. Update any test suites asserting on exact error text.
+
+**BREAKING CHANGE**: `ValidationIssue` and `formatInternalErrors` removed. Use `EnvIssue` and `formatIssues` instead.

.gitignore

@@ -89,3 +89,4 @@ gha-creds-*.json
 skills/*-workspace/
 skills/create-skill/scripts/__pycache__/
 tooling/
+job_logs.txt

apps/www/bin/twoslash-mdx.ts

@@ -1,7 +1,7 @@
 // biome-ignore-all lint/suspicious/noConsole: This is a CLI debugging script
 import fs from "node:fs";
 import { createTwoslasher } from "twoslash";
-import { arktypeTwoslashOptions } from "../lib/twoslash-options";
+import { arktypeTwoslashOptions } from "~/lib/twoslash-options";
 
 const mdxPath = process.argv[2];
 if (!mdxPath) {

apps/www/components/page/compatibility-rails.tsx

@@ -9,13 +9,13 @@ import {
 } from "@icons-pack/react-simple-icons";
 import { Square } from "lucide-react";
 import type { JSX } from "react";
+import { ArkTypeIcon } from "~/components/icons/arktype-icon";
+import { JoiIcon } from "~/components/icons/joi-icon";
+import { SolidStartIcon } from "~/components/icons/solid-start-icon";
+import { TypiaIcon } from "~/components/icons/typia-icon";
+import { ValibotIcon } from "~/components/icons/valibot-icon";
+import { VinxiIcon } from "~/components/icons/vinxi-icon";
 import { cn } from "~/lib/utils";
-import { ArkTypeIcon } from "../icons/arktype-icon";
-import { JoiIcon } from "../icons/joi-icon";
-import { SolidStartIcon } from "../icons/solid-start-icon";
-import { TypiaIcon } from "../icons/typia-icon";
-import { ValibotIcon } from "../icons/valibot-icon";
-import { VinxiIcon } from "../icons/vinxi-icon";
 
 type RailItem = {
 	name: string;

apps/www/components/ui/popover.tsx

@@ -1,7 +1,7 @@
 "use client";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import * as React from "react";
-import { cn } from "../../lib/cn";
+import { cn } from "~/lib/cn";
 
 const Popover = PopoverPrimitive.Root;
 

apps/www/content/docs/arkenv/options.mdx

@@ -87,3 +87,32 @@ const env = arkenv(
 // env.PORT  → 3000 (default applied)
 // env.DEBUG → false (default applied)
 ```
+
+## `safe`
+
+Whether to return a safe result object instead of throwing an error on validation failure. Defaults to `false`.
+
+When enabled, the function returns an object with `{ success: true, data }` or `{ success: false, issues }`.
+
+```ts twoslash
+import arkenv from "arkenv";
+// ---cut---
+const result = arkenv(
+  { PORT: "number" },
+  { safe: true, env: { PORT: "invalid" } }
+);
+
+if (!result.success) {
+  console.error("Validation failed:", result.issues);
+} else {
+  console.log("Port is:", result.data.PORT);
+}
+```
+
+:::warn Not supported in Integrations
+The `safe: true` option is purposefully omitted from the configuration options of framework integrations (like `@arkenv/vite-plugin`, `@arkenv/nextjs`, etc.).
+
+Framework integrations rely on injecting the raw, validated environment variables into the build process. If `safe: true` were enabled, a validation failure would result in the plugin silently injecting the `{ success: false, issues }` wrapper object into your application bundle instead of crashing the build, leading to broken downstream behavior.
+
+If you need to handle validation failures programmatically without failing the build, you should invoke `arkenv()` manually rather than using an automated bundler plugin.
+:::

docs/CONTEXT.md

@@ -176,6 +176,15 @@ pnpm run test:e2e                     # E2E tests
 - Run `pnpm release` after merging PRs to publish packages
 - Only packages in `packages/` are published to npm
 
+## Design Decisions
+
+**Split Parsing Engines (ArkType vs Standard Schema):**
+
+- ArkEnv maintains two distinct parsing engines: `src/arktype/index.ts` and `src/parse-standard.ts`.
+- Despite visual similarities, they are strictly isolated to guarantee the `arkenv/standard` module boundary remains "ArkType-free".
+- Unifying them would force bundlers to trace static imports and drag ArkType into the dependency tree of Standard Schema users, violating the zero-dependency goal.
+- We prioritize optimal tree-shaking, bundle size isolation, and decoupling over dogmatic DRYness.
+
 ## Domain context
 
 **Environment Variable Validation:**
@@ -225,8 +234,12 @@ pnpm run test:e2e                     # E2E tests
 - Leverages ArkType's `type.infer` and `type.validate` utilities
 - Typesafe environment object returned from `arkenv`
 
-**Error Handling:**
+**Error Handling & Vocabulary:**
 
+- **Issue vs. Error Distinction**: ArkEnv strictly differentiates between an "Issue" and an "Error".
+  - **Issue (`EnvIssue`)**: A single, isolated validation failure on a specific environment variable.
+  - **Error (`ArkEnvError`)**: The overarching runtime exception that is thrown when validation fails. It contains an array of `EnvIssue`s.
+- Functions dealing with individual failures should use "Issue" (e.g., `formatIssues`), while functions dealing with the final halting exception should use "Error" (e.g., `ArkEnvError`).
 - `ArkEnvError` extends `Error` and formats ArkType validation errors
 - Errors include variable names and expected types
 - Fail-fast approach: app won't start if validation fails

docs/adr/0010-bundle-isolation-over-dryness.md

@@ -0,0 +1,27 @@
+# 10. Bundle Isolation trumps DRYness
+
+Date: 2026-06-21
+
+## Status
+
+Accepted
+
+## Context
+
+ArkEnv operates as a zero-dependency environment variable parser. It uses ArkType as its primary validation engine (`arkenv`), while also offering a completely separate entry point (`arkenv/standard`) that leverages Standard Schema 1.0 (for users preferring Zod, Valibot, etc.).
+
+During the refactoring to a single core repository with multiple internal exports, a code review raised concerns about code duplication between `src/arktype/index.ts` and `src/parse-standard.ts`. Both files implement similar logic for parsing objects, extracting issue metadata, and formatting validation results. The suggestion was to "aggressively unify or codeshare" these implementations to abide by the DRY (Don't Repeat Yourself) principle.
+
+However, sharing utilities across the core ArkType engine and the Standard Schema engine introduces hidden module graph entanglements. Bundlers like Webpack, Rollup, and esbuild often rely on static imports for tree-shaking. A single shared `utils.ts` file imported by both entry points can easily trick the bundler's heuristics into statically tracing the dependency tree back to `arktype`. This would drag the entire 50kb+ ArkType AST engine into the production bundle of users who only wanted to use `arkenv/standard` with Zod.
+
+## Decision
+
+We intentionally duplicate parsing, formatting, and issue-mapping logic across the `arktype` and `standard` engine implementations to maintain an airtight module boundary. **Bundle isolation strictly trumps DRYness across core/standard boundaries.**
+
+We will not create shared abstractions or utility files that bridge these two domains. The small maintenance cost of duplicated internal logic is a worthwhile trade-off to guarantee that `arkenv/standard` users never incur a bundle size penalty from ArkType.
+
+## Consequences
+
+- The footprint of `@arkenv/standard` remains strictly minimal and fully decoupled from ArkType.
+- Contributors must be aware that fixing a bug in the error extraction logic for ArkType may require a mirrored fix in the Standard Schema logic.
+- Future code reviews raising concerns about DRYness between these files should be directed to this ADR.

packages/arkenv/package.json

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

packages/arkenv/src/arkenv.ts

@@ -7,6 +7,8 @@ import type {
 } from "@repo/types";
 import type { type as at, distill } from "arktype";
 import { parse } from "./arktype";
+import { ArkEnvError, type SafeArkEnvResult } from "./core";
+import { safeExecute } from "./utils/errors";
 
 /**
  * Declarative environment schema definition accepted by ArkEnv.
@@ -35,7 +37,7 @@ export type Infer<T> = T extends SchemaShape
 	: InferType<T>;
 
 /**
- * The environment variables passed to `createEnv`.
+ * The environment variables passed to `arkenv`.
  * Uses `Dict<string>` to enforce
  * compile-time safety: all input environment variables must be strings
  * (or undefined), matching `process.env` semantics.
@@ -80,6 +82,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.
 	 *
@@ -90,37 +98,75 @@ export type ArkEnvConfig = {
 	 * @default false
 	 */
 	emptyAsUndefined?: boolean;
+
+	/**
+	 * Whether to return a safe result object instead of throwing an error on validation failure.
+	 *
+	 * When enabled, the function returns an object with `{ success: true, data }` or `{ success: false, issues }`.
+	 *
+	 * @default false
+	 */
+	safe?: boolean;
 };
 
+export type { SafeArkEnvResult };
+
 /**
- * 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`.
+ * Helper type to represent the output of parsing either an EnvSchema or CompiledEnvSchema.
  */
+export type ArkenvOutput<T extends SchemaShape, D> =
+	| distill.Out<at.infer<T, $>>
+	| InferType<D>;
 
 /**
  * Utility to parse environment variables using ArkType or Standard Schema
- * @param def - The schema definition
- * @param config - The evaluation configuration
- * @returns The parsed environment variables
- * @throws An {@link ArkEnvError | error} if the environment variables are invalid.
+ *
+ * Naming convention: the main function is lowercase (`arkenv`) following the
+ * JavaScript convention for functions (e.g. `zod`, `joi`). Classes and types
+ * use PascalCase with the full product name (`ArkEnvError`, `SafeArkEnvResult`).
+ *
+ * @param def The schema definition
+ * @param config The evaluation configuration
+ * @returns The parsed environment variables, or a SafeArkEnvResult if `{ safe: true }` is configured
+ * @throws An {@link ArkEnvError | error} if the environment variables are invalid and `safe` is not enabled
  */
 export function arkenv<const T extends SchemaShape>(
 	def: EnvSchema<T>,
-	config?: ArkEnvConfig,
+	config?: ArkEnvConfig & { safe?: false },
 ): distill.Out<at.infer<T, $>>;
 export function arkenv<T extends CompiledEnvSchema>(
 	def: T,
-	config?: ArkEnvConfig,
+	config?: ArkEnvConfig & { safe?: false },
 ): InferType<T>;
+export function arkenv<
+	const T extends SchemaShape,
+	const D extends EnvSchema<T> | CompiledEnvSchema,
+>(def: D, config?: ArkEnvConfig & { safe?: false }): ArkenvOutput<T, D>;
 export function arkenv<const T extends SchemaShape>(
-	def: EnvSchema<T> | CompiledEnvSchema,
-	config?: ArkEnvConfig,
-): distill.Out<at.infer<T, $>> | InferType<typeof def>;
-export function arkenv<const T extends SchemaShape>(
-	def: EnvSchema<T> | CompiledEnvSchema,
+	def: EnvSchema<T>,
+	config: ArkEnvConfig & { safe: true },
+): SafeArkEnvResult<distill.Out<at.infer<T, $>>>;
+export function arkenv<T extends CompiledEnvSchema>(
+	def: T,
+	config: ArkEnvConfig & { safe: true },
+): SafeArkEnvResult<InferType<T>>;
+export function arkenv<
+	const T extends SchemaShape,
+	const D extends EnvSchema<T> | CompiledEnvSchema,
+>(
+	def: D,
+	config: ArkEnvConfig & { safe: true },
+): SafeArkEnvResult<ArkenvOutput<T, D>>;
+export function arkenv<
+	const T extends SchemaShape,
+	const D extends EnvSchema<T> | CompiledEnvSchema,
+>(
+	def: D,
 	config: ArkEnvConfig = {},
-): distill.Out<at.infer<T, $>> | InferType<typeof def> {
+): ArkenvOutput<T, D> | SafeArkEnvResult<ArkenvOutput<T, D>> {
+	if (config.safe) {
+		return safeExecute(() => parse(def as any, config));
+	}
 	// biome-ignore lint/suspicious/noExplicitAny: parse handles both EnvSchema<T> and CompiledEnvSchema at runtime
 	return parse(def as any, config);
 }