refactor: replace safeArkEnv utility with a safe option in the arkenv function

Author: yamcodes

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

@@ -166,14 +166,14 @@ console.log(`Connecting to ${dbConfig.host}:${dbConfig.port}...`);
 
 ## Safe parsing (Non-throwing)
 
-By default, calling `arkenv()` will throw an `ArkEnvError` if validation fails. If you prefer to handle validation issues without catching thrown exceptions, you can use the non-throwing `safeArkEnv()` function instead. It returns a result object containing either the successfully parsed data or an array of validation issues.
+By default, calling `arkenv()` will throw an `ArkEnvError` if validation fails. If you prefer to handle validation issues without catching thrown exceptions, you can pass the `{ safe: true }` option instead. It returns a result object containing either the successfully parsed data or an array of validation issues.
 
 ```ts title="env.ts" twoslash
-import { safeArkEnv } from 'arkenv';
+import { arkenv } from 'arkenv';
 
-const result = safeArkEnv({
+const result = arkenv({
   PORT: "number = 3000",
-});
+}, { safe: true });
 
 if (result.success) {
   console.log("Validated config:", result.data);

packages/arkenv/src/arkenv.ts

@@ -98,6 +98,15 @@ 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 };
@@ -123,49 +132,38 @@ export type ArkenvOutput<T extends SchemaShape, D> =
  */
 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): ArkenvOutput<T, D>;
-export function arkenv<
-	const T extends SchemaShape,
-	const D extends EnvSchema<T> | CompiledEnvSchema,
->(def: D, config: ArkEnvConfig = {}): ArkenvOutput<T, D> {
-	// 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 SafeArkEnvResult containing the data or the validation error object
- */
-export function safeArkEnv<const T extends SchemaShape>(
+>(def: D, config?: ArkEnvConfig & { safe?: false }): ArkenvOutput<T, D>;
+export function arkenv<const T extends SchemaShape>(
 	def: EnvSchema<T>,
-	config?: ArkEnvConfig,
+	config: ArkEnvConfig & { safe: true },
 ): SafeArkEnvResult<distill.Out<at.infer<T, $>>>;
-export function safeArkEnv<T extends CompiledEnvSchema>(
+export function arkenv<T extends CompiledEnvSchema>(
 	def: T,
-	config?: ArkEnvConfig,
+	config: ArkEnvConfig & { safe: true },
 ): SafeArkEnvResult<InferType<T>>;
-export function safeArkEnv<
+export function arkenv<
 	const T extends SchemaShape,
 	const D extends EnvSchema<T> | CompiledEnvSchema,
->(def: D, config?: ArkEnvConfig): SafeArkEnvResult<ArkenvOutput<T, D>>;
-export function safeArkEnv<
+>(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 = {}): SafeArkEnvResult<ArkenvOutput<T, D>> {
-	// Cast to any is required here because 'def' is a union type (EnvSchema | CompiledEnvSchema)
-	// which TypeScript's overload resolution cannot resolve statically. It is safely resolved at runtime.
-	return executeSafe(() => arkenv(def as any, config));
+>(
+	def: D,
+	config: ArkEnvConfig = {},
+): ArkenvOutput<T, D> | SafeArkEnvResult<ArkenvOutput<T, D>> {
+	if (config.safe) {
+		return executeSafe(() => 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);
 }

packages/arkenv/src/errors.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { safeStringify, shouldRedact } from "@/utils/redact";
-import { safeArkEnv } from "./arkenv";
+import { arkenv } from "./arkenv";
 import { ArkEnvError, type EnvIssue, formatError, formatIssues } from "./core";
 
 describe("shouldRedact", () => {
@@ -101,7 +101,7 @@ describe("formatIssues & formatError", () => {
 	});
 });
 
-describe("ArkEnvError & safeArkEnv", () => {
+describe("ArkEnvError & arkenv safe mode", () => {
 	it("should create error and store issues", () => {
 		const issues: EnvIssue[] = [
 			{
@@ -117,16 +117,16 @@ describe("ArkEnvError & safeArkEnv", () => {
 		expect(error.name).toBe("ArkEnvError");
 	});
 
-	it("should run safeArkEnv successfully", () => {
-		const result = safeArkEnv({ PORT: "number" }, { env: { PORT: "3000" } });
+	it("should run arkenv safely", () => {
+		const result = arkenv({ PORT: "number" }, { safe: true, env: { PORT: "3000" } });
 		expect(result.success).toBe(true);
 		if (result.success) {
 			expect(result.data).toEqual({ PORT: 3000 });
 		}
 	});
 
-	it("should return failure for safeArkEnv with invalid input", () => {
-		const result = safeArkEnv({ PORT: "number" }, { env: { PORT: "abc" } });
+	it("should return failure for arkenv safe mode with invalid input", () => {
+		const result = arkenv({ PORT: "number" }, { safe: true, env: { PORT: "abc" } });
 		expect(result.success).toBe(false);
 		if (!result.success) {
 			expect(result.issues).toBeDefined();

packages/arkenv/src/index.ts

@@ -1,8 +1,8 @@
 import { $ } from "@repo/scope";
-import { arkenv, safeArkEnv } from "./arkenv";
+import { arkenv } from "./arkenv";
 import { getSchemaKeys } from "./schema";
 
-export { arkenv, getSchemaKeys, safeArkEnv };
+export { arkenv, getSchemaKeys };
 /**
  * Like ArkType's `type`, but with ArkEnv's extra keywords, such as:
  *

packages/arkenv/src/parse-standard.ts

@@ -89,6 +89,15 @@ export type ParseStandardConfig = {
 	 * @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;
 };
 
 /**

packages/arkenv/src/standard-mode.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, expectTypeOf, it, vi } from "vitest";
 import { ArkEnvError } from "./core";
-import { arkenv, safeArkEnv } from "./standard";
+import { arkenv } from "./standard";
 
 // Mock Standard Schema validators for testing
 const createMockStandardSchema = <TOutput>(outputValue: TOutput) => ({
@@ -488,7 +488,7 @@ describe("Standard Mode emptyAsUndefined", () => {
 		}
 	});
 
-	it("should support safeArkEnv standard mode API", () => {
+	it("should support arkenv({ safe: true }) standard mode API", () => {
 		const mockZodValidator = {
 			"~standard": {
 				version: 1 as const,
@@ -511,22 +511,22 @@ describe("Standard Mode emptyAsUndefined", () => {
 			},
 		};
 
-		const resultSuccess = safeArkEnv(
+		const resultSuccess = arkenv(
 			{
 				PORT: mockZodValidator,
 			},
-			{ env: { PORT: "3000" } },
+			{ safe: true, env: { PORT: "3000" } },
 		);
 		expect(resultSuccess.success).toBe(true);
 		if (resultSuccess.success) {
 			expect(resultSuccess.data).toEqual({ PORT: "3000" });
 		}
 
-		const resultFail = safeArkEnv(
+		const resultFail = arkenv(
 			{
 				PORT: mockZodValidator,
 			},
-			{ env: {} },
+			{ safe: true, env: {} },
 		);
 		expect(resultFail.success).toBe(false);
 		if (!resultFail.success) {

packages/arkenv/src/standard.ts

@@ -37,8 +37,18 @@ export type StandardEnvConfig = ParseStandardConfig;
  */
 export function arkenv<const T extends Record<string, StandardSchemaV1>>(
 	def: T,
-	config?: StandardEnvConfig,
-): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> } {
+	config?: StandardEnvConfig & { safe?: false },
+): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> };
+export function arkenv<const T extends Record<string, StandardSchemaV1>>(
+	def: T,
+	config: StandardEnvConfig & { safe: true },
+): SafeArkEnvResult<{ [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }>;
+export function arkenv<const T extends Record<string, StandardSchemaV1>>(
+	def: T,
+	config: StandardEnvConfig = {},
+):
+	| { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }
+	| SafeArkEnvResult<{ [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }> {
 	assertStandardSchemaMap(def);
 
 	for (const key in def) {
@@ -47,26 +57,20 @@ export function arkenv<const T extends Record<string, StandardSchemaV1>>(
 		assertStandardSchema(key, validator);
 	}
 
-	return parseStandard(def as Record<string, unknown>, config ?? {}) as {
+	if (config.safe) {
+		return executeSafe(
+			() =>
+				parseStandard(def as Record<string, unknown>, config) as {
+					[K in keyof T]: StandardSchemaV1.InferOutput<T[K]>;
+				},
+		);
+	}
+
+	return parseStandard(def as Record<string, unknown>, config) as {
 		[K in keyof T]: StandardSchemaV1.InferOutput<T[K]>;
 	};
 }
 
-/**
- * Non-throwing standard mode utility to parse and validate environment variables using Standard Schema 1.0 validators.
- * Returns a serializable result object containing either the validated data or error issues.
- *
- * @param def - An object mapping variable names to Standard Schema validators
- * @param config - Optional configuration
- * @returns The SafeArkEnvResult containing the data or the validation error object
- */
-export function safeArkEnv<const T extends Record<string, StandardSchemaV1>>(
-	def: T,
-	config?: StandardEnvConfig,
-): SafeArkEnvResult<{ [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }> {
-	return executeSafe(() => arkenv(def, config));
-}
-
 /**
  * ArkEnv's Standard Schema export
  *