arkenv 1.0.0-alpha.0 → 1.0.0-alpha.2

package/dist/index.d.cts

@@ -1,11 +1,12 @@
-import { a as Dict, n as SchemaShape, o as $, r as InferType, t as CompiledEnvSchema } from "./index-CzNfOanV.cjs";
+import { a as SafeArkEnvResult } from "./core-7-JO-N-w.cjs";
+import { a as Dict, n as SchemaShape, o as $, r as InferType, t as CompiledEnvSchema } from "./index-Do-2CL1V.cjs";
 import * as _$arktype_internal_keywords_string_ts0 from "arktype/internal/keywords/string.ts";
 import * as _$arktype_internal_attributes_ts0 from "arktype/internal/attributes.ts";
 import * as _$arktype from "arktype";
 import { distill, type as type$1 } from "arktype";
 import * as _$arktype_internal_type_ts0 from "arktype/internal/type.ts";
 
-//#region src/create-env.d.ts
+//#region src/arkenv.d.ts
 /**
  * Declarative environment schema definition accepted by ArkEnv.
  *
@@ -28,9 +29,15 @@ type EnvSchema<def> = type$1.validate<def, $>;
  * @template T - The schema type
  */
 type Infer<T> = T extends SchemaShape ? distill.Out<type$1.infer<T, $>> : InferType<T>;
+/**
+ * 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.
+ */
 type RuntimeEnvironment = Dict<string>;
 /**
- * Configuration options for `createEnv`
+ * Configuration options for `arkenv`
  */
 type ArkEnvConfig = {
   /**
@@ -65,6 +72,11 @@ type ArkEnvConfig = {
    * @default "comma"
    */
   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.
    *
@@ -75,22 +87,60 @@ 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;
 };
 /**
- * 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.
  */
+type ArkenvOutput<T extends SchemaShape, D> = distill.Out<type$1.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
  */
-declare function createEnv<const T extends SchemaShape>(def: EnvSchema<T>, config?: ArkEnvConfig): distill.Out<type$1.infer<T, $>>;
-declare function createEnv<T extends CompiledEnvSchema>(def: T, config?: ArkEnvConfig): InferType<T>;
-declare function createEnv<const T extends SchemaShape>(def: EnvSchema<T> | CompiledEnvSchema, config?: ArkEnvConfig): distill.Out<type$1.infer<T, $>> | InferType<typeof def>;
+declare function arkenv<const T extends SchemaShape>(def: EnvSchema<T>, config?: ArkEnvConfig & {
+  safe?: false;
+}): distill.Out<type$1.infer<T, $>>;
+declare function arkenv<T extends CompiledEnvSchema>(def: T, config?: ArkEnvConfig & {
+  safe?: false;
+}): InferType<T>;
+declare function arkenv<const T extends SchemaShape, const D extends EnvSchema<T> | CompiledEnvSchema>(def: D, config?: ArkEnvConfig & {
+  safe?: false;
+}): ArkenvOutput<T, D>;
+declare function arkenv<const T extends SchemaShape>(def: EnvSchema<T>, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<distill.Out<type$1.infer<T, $>>>;
+declare function arkenv<T extends CompiledEnvSchema>(def: T, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<InferType<T>>;
+declare function arkenv<const T extends SchemaShape, const D extends EnvSchema<T> | CompiledEnvSchema>(def: D, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<ArkenvOutput<T, D>>;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * Extract the keys from a schema definition dynamically.
+ * Supports plain objects, ArkType schemas, and Standard Schema validators.
+ *
+ * @param schema The schema definition to extract keys from
+ * @returns An array of extracted key names
+ * @internal
+ */
+declare function getSchemaKeys(schema: any): string[];
 //#endregion
 //#region src/index.d.ts
 /**
@@ -173,14 +223,8 @@ declare const type: _$arktype_internal_type_ts0.TypeParser<{
     port: number;
   }>;
 }>;
-/**
- * ArkEnv's main export, an alias for {@link createEnv}
- *
- * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
- */
-declare const arkenv: typeof createEnv;
 //#endregion
-export { type ArkEnvConfig, type EnvSchema, type Infer, createEnv, arkenv as default, type };
+export { type ArkEnvConfig, type EnvSchema, type Infer, type SafeArkEnvResult, arkenv, arkenv as default, getSchemaKeys, type };
 
 // CJS Interop Shim
 if (module.exports && module.exports.default) {

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/create-env.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;KAAY,SAAA,QAAiB,MAAA,CAAG,QAAA,CAAS,GAAA,EAAK,CAAA;;;;;;AAQ9C;KAAY,KAAA,MAAW,CAAA,SAAU,WAAA,GAC9B,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;AAAA,KAER,kBAAA,GAAqB,IAAA;;;;KAKd,YAAA;EARG;;;EAYd,GAAA,GAAM,kBAAA;EAXK;;;EAeX,MAAA;EAjBgC;;;;;;;;;;;AAEjB;;;EA8Bf,eAAA;EA5B6B;AAK9B;;;;;;;EAiCC,WAAA;EAAA;;;;AA2BD;;;;;EAhBC,gBAAA;AAAA;;;;;;;;;;;;;iBAgBe,SAAA,iBAA0B,WAAA,CAAA,CACzC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,GAAS,YAAA,GACP,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBACX,SAAA,WAAoB,iBAAA,CAAA,CACnC,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,YAAA,GACP,SAAA,CAAU,CAAA;AAAA,iBACG,SAAA,iBAA0B,WAAA,CAAA,CACzC,GAAA,EAAK,SAAA,CAAU,CAAA,IAAK,iBAAA,EACpB,MAAA,GAAS,YAAA,GACP,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KAAM,SAAA,QAAiB,GAAA;;;;;;;;;AAxFlD;;;cCZa,IAAA,8BAAI,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAQX,MAAA,SAAM,SAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/arkenv.ts","../src/schema.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;;AA0BA;;;;;;;;;KAAY,SAAA,QAAiB,MAAA,CAAG,QAAA,CAAS,GAAA,EAAK,CAAA;;;;;;AAQ9C;KAAY,KAAA,MAAW,CAAA,SAAU,WAAA,GAC9B,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;;;;;;;KAQR,kBAAA,GAAqB,IAAA;;;;KAKd,YAAA;EAfM;;;EAmBjB,GAAA,GAAM,kBAAA;EAlBI;;;EAsBV,MAAA;EAtB0B;;;;;AACX;;;;;AAahB;;;;EAuBC,eAAA;EAnBM;;;;;;;;EA6BN,WAAA;EAkCW;;;;EA5BX,YAAA;EA6B0B;;;;;;;;;EAlB1B,gBAAA;EAkBE;;;;;;;EATF,IAAA;AAAA;AAwBD;;;AAAA,KAhBY,YAAA,WAAuB,WAAA,OAChC,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;;;;;;;;;;;;;iBAcG,MAAA,iBAAuB,WAAA,CAAA,CACtC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IACxB,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBACX,MAAA,WAAiB,iBAAA,CAAA,CAChC,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IACxB,SAAA,CAAU,CAAA;AAAA,iBACG,MAAA,iBACC,WAAA,kBACA,SAAA,CAAU,CAAA,IAAK,iBAAA,CAAA,CAC9B,GAAA,EAAK,CAAA,EAAG,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IAAiB,YAAA,CAAa,CAAA,EAAG,CAAA;AAAA,iBACrD,MAAA,iBAAuB,WAAA,CAAA,CACtC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBAC5B,MAAA,WAAiB,iBAAA,CAAA,CAChC,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,SAAA,CAAU,CAAA;AAAA,iBACd,MAAA,iBACC,WAAA,kBACA,SAAA,CAAU,CAAA,IAAK,iBAAA,CAAA,CAE/B,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,YAAA,CAAa,CAAA,EAAG,CAAA;;;;;;;;;;;iBCrJpB,aAAA,CAAc,MAAA;;;;;;;;;ADiB9B;;;cEZa,IAAA,8BAAI,UAAA"}

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import { a as Dict, n as SchemaShape, o as $, r as InferType, t as CompiledEnvSchema } from "./index-Br22fqkz.mjs";
+import { a as SafeArkEnvResult } from "./core-BaGd9k2K.mjs";
+import { a as Dict, n as SchemaShape, o as $, r as InferType, t as CompiledEnvSchema } from "./index-NbQAnciD.mjs";
 import * as _$arktype from "arktype";
 import { distill, type as type$1 } from "arktype";
 import * as _$arktype_internal_keywords_string_ts0 from "arktype/internal/keywords/string.ts";
 import * as _$arktype_internal_attributes_ts0 from "arktype/internal/attributes.ts";
 import * as _$arktype_internal_type_ts0 from "arktype/internal/type.ts";
 
-//#region src/create-env.d.ts
+//#region src/arkenv.d.ts
 /**
  * Declarative environment schema definition accepted by ArkEnv.
  *
@@ -28,9 +29,15 @@ type EnvSchema<def> = type$1.validate<def, $>;
  * @template T - The schema type
  */
 type Infer<T> = T extends SchemaShape ? distill.Out<type$1.infer<T, $>> : InferType<T>;
+/**
+ * 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.
+ */
 type RuntimeEnvironment = Dict<string>;
 /**
- * Configuration options for `createEnv`
+ * Configuration options for `arkenv`
  */
 type ArkEnvConfig = {
   /**
@@ -65,6 +72,11 @@ type ArkEnvConfig = {
    * @default "comma"
    */
   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.
    *
@@ -75,22 +87,60 @@ 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;
 };
 /**
- * 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.
  */
+type ArkenvOutput<T extends SchemaShape, D> = distill.Out<type$1.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
  */
-declare function createEnv<const T extends SchemaShape>(def: EnvSchema<T>, config?: ArkEnvConfig): distill.Out<type$1.infer<T, $>>;
-declare function createEnv<T extends CompiledEnvSchema>(def: T, config?: ArkEnvConfig): InferType<T>;
-declare function createEnv<const T extends SchemaShape>(def: EnvSchema<T> | CompiledEnvSchema, config?: ArkEnvConfig): distill.Out<type$1.infer<T, $>> | InferType<typeof def>;
+declare function arkenv<const T extends SchemaShape>(def: EnvSchema<T>, config?: ArkEnvConfig & {
+  safe?: false;
+}): distill.Out<type$1.infer<T, $>>;
+declare function arkenv<T extends CompiledEnvSchema>(def: T, config?: ArkEnvConfig & {
+  safe?: false;
+}): InferType<T>;
+declare function arkenv<const T extends SchemaShape, const D extends EnvSchema<T> | CompiledEnvSchema>(def: D, config?: ArkEnvConfig & {
+  safe?: false;
+}): ArkenvOutput<T, D>;
+declare function arkenv<const T extends SchemaShape>(def: EnvSchema<T>, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<distill.Out<type$1.infer<T, $>>>;
+declare function arkenv<T extends CompiledEnvSchema>(def: T, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<InferType<T>>;
+declare function arkenv<const T extends SchemaShape, const D extends EnvSchema<T> | CompiledEnvSchema>(def: D, config: ArkEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<ArkenvOutput<T, D>>;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * Extract the keys from a schema definition dynamically.
+ * Supports plain objects, ArkType schemas, and Standard Schema validators.
+ *
+ * @param schema The schema definition to extract keys from
+ * @returns An array of extracted key names
+ * @internal
+ */
+declare function getSchemaKeys(schema: any): string[];
 //#endregion
 //#region src/index.d.ts
 /**
@@ -173,13 +223,7 @@ declare const type: _$arktype_internal_type_ts0.TypeParser<{
     port: number;
   }>;
 }>;
-/**
- * ArkEnv's main export, an alias for {@link createEnv}
- *
- * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
- */
-declare const arkenv: typeof createEnv;
 //#endregion
-export { type ArkEnvConfig, type EnvSchema, type Infer, createEnv, arkenv as default, type };
+export { type ArkEnvConfig, type EnvSchema, type Infer, type SafeArkEnvResult, arkenv, arkenv as default, getSchemaKeys, type };
 
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/create-env.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;KAAY,SAAA,QAAiB,MAAA,CAAG,QAAA,CAAS,GAAA,EAAK,CAAA;;;;;;AAQ9C;KAAY,KAAA,MAAW,CAAA,SAAU,WAAA,GAC9B,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;AAAA,KAER,kBAAA,GAAqB,IAAA;;;;KAKd,YAAA;EARG;;;EAYd,GAAA,GAAM,kBAAA;EAXK;;;EAeX,MAAA;EAjBgC;;;;;;;;;;;AAEjB;;;EA8Bf,eAAA;EA5B6B;AAK9B;;;;;;;EAiCC,WAAA;EAAA;;;;AA2BD;;;;;EAhBC,gBAAA;AAAA;;;;;;;;;;;;;iBAgBe,SAAA,iBAA0B,WAAA,CAAA,CACzC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,GAAS,YAAA,GACP,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBACX,SAAA,WAAoB,iBAAA,CAAA,CACnC,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,YAAA,GACP,SAAA,CAAU,CAAA;AAAA,iBACG,SAAA,iBAA0B,WAAA,CAAA,CACzC,GAAA,EAAK,SAAA,CAAU,CAAA,IAAK,iBAAA,EACpB,MAAA,GAAS,YAAA,GACP,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KAAM,SAAA,QAAiB,GAAA;;;;;;;;;AAxFlD;;;cCZa,IAAA,8BAAI,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAQX,MAAA,SAAM,SAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/arkenv.ts","../src/schema.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;;AA0BA;;;;;;;;;KAAY,SAAA,QAAiB,MAAA,CAAG,QAAA,CAAS,GAAA,EAAK,CAAA;;;;;;AAQ9C;KAAY,KAAA,MAAW,CAAA,SAAU,WAAA,GAC9B,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;;;;;;;KAQR,kBAAA,GAAqB,IAAA;;;;KAKd,YAAA;EAfM;;;EAmBjB,GAAA,GAAM,kBAAA;EAlBI;;;EAsBV,MAAA;EAtB0B;;;;;AACX;;;;;AAahB;;;;EAuBC,eAAA;EAnBM;;;;;;;;EA6BN,WAAA;EAkCW;;;;EA5BX,YAAA;EA6B0B;;;;;;;;;EAlB1B,gBAAA;EAkBE;;;;;;;EATF,IAAA;AAAA;AAwBD;;;AAAA,KAhBY,YAAA,WAAuB,WAAA,OAChC,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA,KACxB,SAAA,CAAU,CAAA;;;;;;;;;;;;;iBAcG,MAAA,iBAAuB,WAAA,CAAA,CACtC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IACxB,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBACX,MAAA,WAAiB,iBAAA,CAAA,CAChC,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IACxB,SAAA,CAAU,CAAA;AAAA,iBACG,MAAA,iBACC,WAAA,kBACA,SAAA,CAAU,CAAA,IAAK,iBAAA,CAAA,CAC9B,GAAA,EAAK,CAAA,EAAG,MAAA,GAAS,YAAA;EAAiB,IAAA;AAAA,IAAiB,YAAA,CAAa,CAAA,EAAG,CAAA;AAAA,iBACrD,MAAA,iBAAuB,WAAA,CAAA,CACtC,GAAA,EAAK,SAAA,CAAU,CAAA,GACf,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAG,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,iBAC5B,MAAA,WAAiB,iBAAA,CAAA,CAChC,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,SAAA,CAAU,CAAA;AAAA,iBACd,MAAA,iBACC,WAAA,kBACA,SAAA,CAAU,CAAA,IAAK,iBAAA,CAAA,CAE/B,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,YAAA;EAAiB,IAAA;AAAA,IACvB,gBAAA,CAAiB,YAAA,CAAa,CAAA,EAAG,CAAA;;;;;;;;;;;iBCrJpB,aAAA,CAAc,MAAA;;;;;;;;;ADiB9B;;;cEZa,IAAA,8BAAI,UAAA"}

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import{n as e,r as t,t as n}from"./shared-B7lIFzfk.mjs";import{r,t as i}from"./core-B0IkKRzg.mjs";import{ArkErrors as a,scope as o,type as s}from"arktype";const c=s(`0 <= number.integer <= 65535`),l=s(`string.ip | 'localhost'`),u=o({string:s.module({...s.keywords.string,host:l}),number:s.module({...s.keywords.number,port:c})});function d(e){return Object.entries(e.byPath).map(([e,t])=>{let n=t.message,i=n.trimStart();if(i.length>0&&`:.-`.includes(i[0])&&(i=i.slice(1).trimStart()),i.toLowerCase().startsWith(e.toLowerCase())){let t=i.slice(e.length).trimStart();t.length>0&&`:.-`.includes(t[0])&&(t=t.slice(1)),n=t.trimStart()}let a=n.match(/\(was (.*)\)/);if(a?.[1]){let e=a[1];e.includes(`\x1B[`)||(n=n.replace(`(was ${e})`,`(was ${r(`cyan`,e)})`))}return{path:e,message:n}})}function f(r,o){let{env:s=process.env,coerce:c=!0,onUndeclaredKey:l=`delete`,arrayFormat:f=`comma`,emptyAsUndefined:p=!1}=o,m=(typeof r==`function`&&`assert`in r?r:u.type.raw(r)).onUndeclaredKey(l),h={...p?t(s):s};if(c){let t=e(m.in.toJsonSchema({fallback:e=>e.base}));t.length>0&&(h=n(h,t,{arrayFormat:f}))}let g=m(h);if(g instanceof a)throw new i(d(g));return g}function p(e,t={}){return f(e,t)}const m=u.type,h=p;export{p as createEnv,h as default,m as type};
+import{a as e,c as t,l as n,r,s as i,t as a}from"./errors-C_uh86xh.mjs";import{t as o}from"./core-A65KioHX.mjs";import{ArkErrors as s,scope as c,type as l}from"arktype";const u=l(`0 <= number.integer <= 65535`),d=l(`string.ip | 'localhost'`),f=c({string:l.module({...l.keywords.string,host:d}),number:l.module({...l.keywords.number,port:u})});function p(t,n){return Object.entries(t.byPath).map(([t,o])=>{let s=o.message,c=s.trimStart();if(c.length>0&&`:.-`.includes(c[0])&&(c=c.slice(1).trimStart()),c.toLowerCase().startsWith(t.toLowerCase())){let e=c.slice(t.length).trimStart();e.length>0&&`:.-`.includes(e[0])&&(e=e.slice(1)),s=e.trimStart()}s=i(s,t,n?.debugSecrets);let l=e(o.code),u={...r(o)};return a(t,s,l,u,o.expected,o.code===`required`?void 0:o.data)})}function m(e,t){let{env:r=process.env,coerce:i=!0,onUndeclaredKey:a=`delete`,arrayFormat:c=`comma`,emptyAsUndefined:l=!1}=t,u=(typeof e==`function`&&`assert`in e?e:f.type.raw(e)).onUndeclaredKey(a),{coercedEnv:d}=n(r,l,c,i?()=>({schema:u.in.toJsonSchema({fallback:e=>e.base}),hasSchema:!0}):void 0),m=u(d);if(m instanceof s)throw new o(p(m,t));return m}function h(e,n={}){return n.safe?t(()=>m(e,n)):m(e,n)}function g(e){if(!e||typeof e!=`object`&&typeof e!=`function`)return[];if(e.json&&typeof e.json==`object`&&e.json.domain===`object`){let t=[];if(Array.isArray(e.json.required))for(let n of e.json.required)n&&typeof n==`object`&&`key`in n&&t.push(n.key);if(Array.isArray(e.json.optional))for(let n of e.json.optional)n&&typeof n==`object`&&`key`in n&&t.push(n.key);return t}let t=e[`~standard`],n=typeof t?.jsonSchema?.input==`function`&&t.jsonSchema.input||typeof e.jsonSchema?.input==`function`&&e.jsonSchema.input;if(n)try{let e=n({target:`draft-07`});if(e&&typeof e==`object`&&e.properties)return Object.keys(e.properties)}catch{}if(typeof e.toJSONSchema==`function`)try{let t=e.toJSONSchema();if(t&&typeof t==`object`&&t.properties)return Object.keys(t.properties)}catch{}if(typeof e.toStandardJSONSchema?.v1==`function`)try{let t=e.toStandardJSONSchema.v1();if(t&&typeof t==`object`&&t.properties)return Object.keys(t.properties)}catch{}return Object.keys(e)}const _=f.type;var v=h;export{h as arkenv,v as default,g as getSchemaKeys,_ as type};
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["t","e","$","$"],"sources":["../../internal/scope/dist/index.js","../src/arktype/index.ts","../src/create-env.ts","../src/index.ts"],"sourcesContent":["import{scope as e,type as t}from\"arktype\";const n=t(`0 <= number.integer <= 65535`),r=t(`string.ip | 'localhost'`),i=e({string:t.module({...t.keywords.string,host:r}),number:t.module({...t.keywords.number,port:n})});export{i as $};\n//# sourceMappingURL=index.js.map","import { $ } from \"@repo/scope\";\nimport type { SchemaShape } from \"@repo/types\";\nimport type { distill } from \"arktype\";\nimport { ArkErrors } from \"arktype\";\nimport {\n\tapplyCoercion,\n\tfindCoercionPaths,\n\tstripEmptyStrings,\n} from \"@/coercion\";\nimport { ArkEnvError, type ValidationIssue } from \"@/core\";\nimport type { ArkEnvConfig, EnvSchema } from \"@/create-env\";\nimport { styleText } from \"@/utils/style-text\";\n\n/**\n * Re-export of ArkType's `distill` utilities.\n *\n * Exposed for internal use cases and type-level integrations.\n * ArkEnv does not add behavior or guarantees beyond what ArkType provides.\n *\n * @internal\n * @see https://github.com/arktypeio/arktype\n */\nexport type { distill };\n\n/**\n * Converts ArkType's `ArkErrors` (keyed by path) into a flat `ValidationIssue[]`\n * suitable for `ArkEnvError`. Strips leading path references from messages to\n * avoid duplication when `formatInternalErrors` prepends the styled path, and\n * applies cyan styling to inline \"(was …)\" values.\n *\n * @param errors The ArkType errors object to convert\n * @returns An array of flattened validation issues\n *\n * @internal\n */\nfunction arkErrorsToIssues(errors: ArkErrors): ValidationIssue[] {\n\treturn Object.entries(errors.byPath).map(([path, error]) => {\n\t\tlet message = error.message;\n\n\t\t// Strip leading path reference if ArkType included it in the message\n\t\tlet trimmed = message.trimStart();\n\t\tif (trimmed.length > 0 && \":.-\".includes(trimmed[0])) {\n\t\t\ttrimmed = trimmed.slice(1).trimStart();\n\t\t}\n\t\tif (trimmed.toLowerCase().startsWith(path.toLowerCase())) {\n\t\t\tlet rest = trimmed.slice(path.length).trimStart();\n\t\t\tif (rest.length > 0 && \":.-\".includes(rest[0])) {\n\t\t\t\trest = rest.slice(1);\n\t\t\t}\n\t\t\tmessage = rest.trimStart();\n\t\t}\n\n\t\t// Style (was ...) inline values\n\t\tconst valueMatch = message.match(/\\(was (.*)\\)/);\n\t\tif (valueMatch?.[1]) {\n\t\t\tconst value = valueMatch[1];\n\t\t\tif (!value.includes(\"\\x1b[\")) {\n\t\t\t\tmessage = message.replace(\n\t\t\t\t\t`(was ${value})`,\n\t\t\t\t\t`(was ${styleText(\"cyan\", value)})`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn { path, message };\n\t});\n}\n\n/**\n * Parse and validate environment variables using ArkEnv's schema rules.\n *\n * This applies:\n * - schema validation\n * - optional coercion (strings → numbers, booleans, arrays)\n * - undeclared key handling\n *\n * On success, returns the validated environment object.\n * On failure, throws an {@link ArkEnvError}.\n *\n * This is a low-level utility used internally by ArkEnv.\n * Most users should prefer the default `arkenv()` export.\n *\n * @param def The ArkType schema definition to validate against\n * @param config The configuration object for parsing and coercion\n * @returns The parsed and validated environment variables\n * @throws {@link ArkEnvError} if validation fails\n *\n * @internal\n */\nexport function parse<const T extends SchemaShape>(\n\tdef: EnvSchema<T>,\n\tconfig: ArkEnvConfig,\n) {\n\tconst {\n\t\tenv = process.env,\n\t\tcoerce: shouldCoerce = true,\n\t\tonUndeclaredKey = \"delete\",\n\t\tarrayFormat = \"comma\",\n\t\temptyAsUndefined = false,\n\t} = config;\n\n\t// If def is a type definition (has assert method), use it directly\n\t// Otherwise, use raw() to convert the schema definition\n\tconst isCompiledType = typeof def === \"function\" && \"assert\" in def;\n\tconst schema = (isCompiledType ? def : $.type.raw(def)) as any;\n\n\t// Apply the `onUndeclaredKey` option\n\tconst schemaWithKeys = schema.onUndeclaredKey(onUndeclaredKey);\n\n\t// Optionally treat empty strings as undefined\n\tconst processedEnv = emptyAsUndefined\n\t\t? stripEmptyStrings(env as Record<string, string | undefined>)\n\t\t: env;\n\n\tlet coercedEnv = { ...processedEnv } as Record<string, unknown>;\n\n\t// Apply coercion transformation to allow strings to be parsed as numbers/booleans\n\tif (shouldCoerce) {\n\t\tconst json = schemaWithKeys.in.toJsonSchema({\n\t\t\tfallback: (ctx: { base: unknown }) => ctx.base,\n\t\t});\n\t\tconst targets = findCoercionPaths(json);\n\t\tif (targets.length > 0) {\n\t\t\tcoercedEnv = applyCoercion(coercedEnv, targets, {\n\t\t\t\tarrayFormat,\n\t\t\t});\n\t\t}\n\t}\n\n\t// Validate the environment variables\n\tconst validatedEnv = schemaWithKeys(coercedEnv);\n\n\t// In ArkType 2.x, calling a type as a function returns the validated data or ArkErrors\n\tif (validatedEnv instanceof ArkErrors) {\n\t\tthrow new ArkEnvError(arkErrorsToIssues(validatedEnv));\n\t}\n\n\treturn validatedEnv;\n}\n","import type { $ } from \"@repo/scope\";\nimport type {\n\tCompiledEnvSchema,\n\tDict,\n\tInferType,\n\tSchemaShape,\n} from \"@repo/types\";\nimport type { type as at, distill } from \"arktype\";\nimport { parse } from \"./arktype\";\nimport type { ArkEnvError } from \"./core\";\n\n/**\n * Declarative environment schema definition accepted by ArkEnv.\n *\n * Represents a declarative schema object mapping environment\n * variable names to schema definitions (e.g. ArkType DSL strings\n * or Standard Schema validators).\n *\n * This type is used to validate that a schema object is compatible with\n * ArkEnv’s validator scope before being compiled or parsed.\n *\n * Most users will provide schemas in this form.\n *\n * @template def - The schema shape object\n */\nexport type EnvSchema<def> = at.validate<def, $>;\n\n/**\n * Infer the validated and coerced environment object type from a schema.\n * Supports declarative schema shapes, compiled ArkType schemas, and Standard Schema validators.\n *\n * @template T - The schema type\n */\nexport type Infer<T> = T extends SchemaShape\n\t? distill.Out<at.infer<T, $>>\n\t: InferType<T>;\n\ntype RuntimeEnvironment = Dict<string>;\n\n/**\n * Configuration options for `createEnv`\n */\nexport type ArkEnvConfig = {\n\t/**\n\t * The environment variables to parse. Defaults to `process.env`\n\t */\n\tenv?: RuntimeEnvironment;\n\t/**\n\t * Whether to coerce environment variables to their defined types. Defaults to `true`\n\t */\n\tcoerce?: boolean;\n\t/**\n\t * Control how ArkEnv handles environment variables that are not defined in your schema.\n\t *\n\t * Defaults to `'delete'` to ensure your output object only contains\n\t * keys you've explicitly declared. This differs from ArkType's standard behavior, which\n\t * mirrors TypeScript by defaulting to `'ignore'`.\n\t *\n\t * - `delete` (ArkEnv default): Undeclared keys are allowed on input but stripped from the output.\n\t * - `ignore` (ArkType default): Undeclared keys are allowed and preserved in the output.\n\t * - `reject`: Undeclared keys will cause validation to fail.\n\t *\n\t * @default \"delete\"\n\t * @see https://arktype.io/docs/configuration#onundeclaredkey\n\t */\n\tonUndeclaredKey?: \"ignore\" | \"delete\" | \"reject\";\n\n\t/**\n\t * The format to use for array parsing when coercion is enabled.\n\t *\n\t * - `comma` (default): Strings are split by comma and trimmed.\n\t * - `json`: Strings are parsed as JSON.\n\t *\n\t * @default \"comma\"\n\t */\n\tarrayFormat?: \"comma\" | \"json\";\n\n\t/**\n\t * Whether to treat empty strings (`\"\"`) as `undefined` before validation.\n\t *\n\t * When enabled, an environment variable set to an empty value (e.g. `PORT=`)\n\t * will be treated as if it were missing, allowing defaults to apply and\n\t * preventing validation errors for numeric or boolean types.\n\t *\n\t * @default false\n\t */\n\temptyAsUndefined?: boolean;\n};\n\n/**\n * TODO: `SchemaShape` is basically `Record<string, unknown>`.\n * If possible, find a better type than \"const T extends Record<string, unknown>\",\n * and be as close as possible to the type accepted by ArkType's `type`.\n */\n\n/**\n * Utility to parse environment variables using ArkType or Standard Schema\n * @param def - The schema definition\n * @param config - The evaluation configuration\n * @returns The parsed environment variables\n * @throws An {@link ArkEnvError | error} if the environment variables are invalid.\n */\nexport function createEnv<const T extends SchemaShape>(\n\tdef: EnvSchema<T>,\n\tconfig?: ArkEnvConfig,\n): distill.Out<at.infer<T, $>>;\nexport function createEnv<T extends CompiledEnvSchema>(\n\tdef: T,\n\tconfig?: ArkEnvConfig,\n): InferType<T>;\nexport function createEnv<const T extends SchemaShape>(\n\tdef: EnvSchema<T> | CompiledEnvSchema,\n\tconfig?: ArkEnvConfig,\n): distill.Out<at.infer<T, $>> | InferType<typeof def>;\nexport function createEnv<const T extends SchemaShape>(\n\tdef: EnvSchema<T> | CompiledEnvSchema,\n\tconfig: ArkEnvConfig = {},\n): distill.Out<at.infer<T, $>> | InferType<typeof def> {\n\t// biome-ignore lint/suspicious/noExplicitAny: parse handles both EnvSchema<T> and CompiledEnvSchema at runtime\n\treturn parse(def as any, config);\n}\n","import { $ } from \"@repo/scope\";\nimport { createEnv } from \"./create-env\";\n\nexport { createEnv };\n/**\n * Like ArkType's `type`, but with ArkEnv's extra keywords, such as:\n *\n * - `string.host` – a hostname (e.g. `\"localhost\"`, `\"127.0.0.1\"`)\n * - `number.port` – a port number (e.g. `8080`)\n *\n * See ArkType's docs for the full API:\n * https://arktype.io/docs/type-api\n */\nexport const type = $.type;\nexport type { ArkEnvConfig, EnvSchema, Infer } from \"./create-env\";\n\n/**\n * ArkEnv's main export, an alias for {@link createEnv}\n *\n * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.\n */\nconst arkenv = createEnv;\nexport default arkenv;\n"],"mappings":"2JAA0C,MAAM,EAAEA,EAAE,+BAA+B,CAAC,EAAEA,EAAE,0BAA0B,CAAC,EAAEC,EAAE,CAAC,OAAOD,EAAE,OAAO,CAAC,GAAGA,EAAE,SAAS,OAAO,KAAK,EAAE,CAAC,CAAC,OAAOA,EAAE,OAAO,CAAC,GAAGA,EAAE,SAAS,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CCmCvN,SAAS,EAAkB,EAAsC,CAChE,OAAO,OAAO,QAAQ,EAAO,OAAO,CAAC,KAAK,CAAC,EAAM,KAAW,CAC3D,IAAI,EAAU,EAAM,QAGhB,EAAU,EAAQ,WAAW,CAIjC,GAHI,EAAQ,OAAS,GAAK,MAAM,SAAS,EAAQ,GAAG,GACnD,EAAU,EAAQ,MAAM,EAAE,CAAC,WAAW,EAEnC,EAAQ,aAAa,CAAC,WAAW,EAAK,aAAa,CAAC,CAAE,CACzD,IAAI,EAAO,EAAQ,MAAM,EAAK,OAAO,CAAC,WAAW,CAC7C,EAAK,OAAS,GAAK,MAAM,SAAS,EAAK,GAAG,GAC7C,EAAO,EAAK,MAAM,EAAE,EAErB,EAAU,EAAK,WAAW,CAI3B,IAAM,EAAa,EAAQ,MAAM,eAAe,CAChD,GAAI,IAAa,GAAI,CACpB,IAAM,EAAQ,EAAW,GACpB,EAAM,SAAS,QAAQ,GAC3B,EAAU,EAAQ,QACjB,QAAQ,EAAM,GACd,QAAQ,EAAU,OAAQ,EAAM,CAAC,GACjC,EAIH,MAAO,CAAE,OAAM,UAAS,EACvB,CAwBH,SAAgB,EACf,EACA,EACC,CACD,GAAM,CACL,MAAM,QAAQ,IACd,OAAQ,EAAe,GACvB,kBAAkB,SAClB,cAAc,QACd,mBAAmB,IAChB,EAQE,GAJiB,OAAO,GAAQ,YAAc,WAAY,EAC/B,EAAME,EAAE,KAAK,IAAI,EAAI,EAGxB,gBAAgB,EAAgB,CAO1D,EAAa,CAAE,GAJE,EAClB,EAAkB,EAA0C,CAC5D,EAEiC,CAGpC,GAAI,EAAc,CAIjB,IAAM,EAAU,EAHH,EAAe,GAAG,aAAa,CAC3C,SAAW,GAA2B,EAAI,KAC1C,CACqC,CAAC,CACnC,EAAQ,OAAS,IACpB,EAAa,EAAc,EAAY,EAAS,CAC/C,cACA,CAAC,EAKJ,IAAM,EAAe,EAAe,EAAW,CAG/C,GAAI,aAAwB,EAC3B,MAAM,IAAI,EAAY,EAAkB,EAAa,CAAC,CAGvD,OAAO,ECvBR,SAAgB,EACf,EACA,EAAuB,EAAE,CAC6B,CAEtD,OAAO,EAAM,EAAY,EAAO,CC1GjC,MAAa,EAAOC,EAAE,KAQhB,EAAS"}
+{"version":3,"file":"index.mjs","names":["t","e","$","$"],"sources":["../../internal/scope/dist/index.js","../src/arktype/index.ts","../src/arkenv.ts","../src/schema.ts","../src/index.ts"],"sourcesContent":["import{scope as e,type as t}from\"arktype\";const n=t(`0 <= number.integer <= 65535`),r=t(`string.ip | 'localhost'`),i=e({string:t.module({...t.keywords.string,host:r}),number:t.module({...t.keywords.number,port:n})});export{i as $};\n//# sourceMappingURL=index.js.map","import { $ } from \"@repo/scope\";\nimport type { SchemaShape } from \"@repo/types\";\nimport type { distill } from \"arktype\";\nimport { ArkErrors } from \"arktype\";\nimport type { ArkEnvConfig, EnvSchema } from \"@/arkenv\";\nimport { coerceEnvironment } from \"@/coercion\";\nimport { ArkEnvError, type EnvIssue, type EnvIssueMeta } from \"@/core\";\nimport {\n\tbuildEnvIssue,\n\tgetArkTypeMeta,\n\tmapArkTypeCode,\n\tredactMessageWasValue,\n} from \"@/utils/errors\";\n\n/**\n * Re-export of ArkType's `distill` utilities.\n *\n * Exposed for internal use cases and type-level integrations.\n * ArkEnv does not add behavior or guarantees beyond what ArkType provides.\n *\n * @internal\n * @see https://github.com/arktypeio/arktype\n */\nexport type { distill };\n\n/**\n * Convert ArkType's `ArkErrors` (keyed by path) into a flat `EnvIssue[]`\n * suitable for `ArkEnvError`.\n *\n * @param errors The ArkType errors object to convert\n * @param config Optional ArkEnvConfig to read debugSecrets options\n * @returns An array of flattened validation issues\n *\n * @internal\n */\nfunction arkErrorsToIssues(\n\terrors: ArkErrors,\n\tconfig?: ArkEnvConfig,\n): EnvIssue[] {\n\treturn Object.entries(errors.byPath).map(([path, error]) => {\n\t\tlet message = error.message;\n\n\t\t// Strip leading path reference if ArkType included it in the message\n\t\tlet trimmed = message.trimStart();\n\t\tif (trimmed.length > 0 && \":.-\".includes(trimmed[0])) {\n\t\t\ttrimmed = trimmed.slice(1).trimStart();\n\t\t}\n\t\tif (trimmed.toLowerCase().startsWith(path.toLowerCase())) {\n\t\t\tlet rest = trimmed.slice(path.length).trimStart();\n\t\t\tif (rest.length > 0 && \":.-\".includes(rest[0])) {\n\t\t\t\trest = rest.slice(1);\n\t\t\t}\n\t\t\tmessage = rest.trimStart();\n\t\t}\n\n\t\t// Redact and style (was ...) inline values\n\t\tmessage = redactMessageWasValue(message, path, config?.debugSecrets);\n\n\t\t// Map code and metadata using centralized helpers\n\t\tconst code = mapArkTypeCode(error.code);\n\t\tconst bounds = getArkTypeMeta(error);\n\t\tconst meta: EnvIssueMeta = {\n\t\t\t...bounds,\n\t\t};\n\n\t\treturn buildEnvIssue(\n\t\t\tpath,\n\t\t\tmessage,\n\t\t\tcode,\n\t\t\tmeta,\n\t\t\terror.expected,\n\t\t\terror.code === \"required\" ? undefined : error.data,\n\t\t);\n\t});\n}\n\n/**\n * Parse and validate environment variables using ArkEnv's schema rules.\n *\n * This applies:\n * - schema validation\n * - optional coercion (strings → numbers, booleans, arrays)\n * - undeclared key handling\n *\n * On success, returns the validated environment object.\n * On failure, throws an {@link ArkEnvError}.\n *\n * This is a low-level utility used internally by ArkEnv.\n * Most users should prefer the default `arkenv()` export.\n *\n * @param def The ArkType schema definition to validate against\n * @param config The configuration object for parsing and coercion\n * @returns The parsed and validated environment variables\n * @throws {@link ArkEnvError} if validation fails\n *\n * @internal\n */\nexport function parse<const T extends SchemaShape>(\n\tdef: EnvSchema<T>,\n\tconfig: ArkEnvConfig,\n) {\n\tconst {\n\t\tenv = process.env,\n\t\tcoerce: shouldCoerce = true,\n\t\tonUndeclaredKey = \"delete\",\n\t\tarrayFormat = \"comma\",\n\t\temptyAsUndefined = false,\n\t} = config;\n\n\t// If def is a type definition (has assert method), use it directly\n\t// Otherwise, use raw() to convert the schema definition\n\tconst isCompiledType = typeof def === \"function\" && \"assert\" in def;\n\tconst schema = (isCompiledType ? def : $.type.raw(def)) as any;\n\n\t// Apply the `onUndeclaredKey` option\n\tconst schemaWithKeys = schema.onUndeclaredKey(onUndeclaredKey);\n\n\t// Optionally strip empty strings and apply coercion\n\tconst { coercedEnv } = coerceEnvironment(\n\t\tenv,\n\t\temptyAsUndefined,\n\t\tarrayFormat,\n\t\tshouldCoerce\n\t\t\t? () => {\n\t\t\t\t\tconst json = schemaWithKeys.in.toJsonSchema({\n\t\t\t\t\t\tfallback: (ctx: { base: unknown }) => ctx.base,\n\t\t\t\t\t});\n\t\t\t\t\treturn { schema: json, hasSchema: true };\n\t\t\t\t}\n\t\t\t: undefined,\n\t);\n\n\t// Validate the environment variables\n\tconst validatedEnv = schemaWithKeys(coercedEnv);\n\n\t// In ArkType 2.x, calling a type as a function returns the validated data or ArkErrors\n\tif (validatedEnv instanceof ArkErrors) {\n\t\tthrow new ArkEnvError(arkErrorsToIssues(validatedEnv, config));\n\t}\n\n\treturn validatedEnv;\n}\n","import type { $ } from \"@repo/scope\";\nimport type {\n\tCompiledEnvSchema,\n\tDict,\n\tInferType,\n\tSchemaShape,\n} from \"@repo/types\";\nimport type { type as at, distill } from \"arktype\";\nimport { parse } from \"./arktype\";\nimport { ArkEnvError, type SafeArkEnvResult } from \"./core\";\nimport { safeExecute } from \"./utils/errors\";\n\n/**\n * Declarative environment schema definition accepted by ArkEnv.\n *\n * Represents a declarative schema object mapping environment\n * variable names to schema definitions (e.g. ArkType DSL strings\n * or Standard Schema validators).\n *\n * This type is used to validate that a schema object is compatible with\n * ArkEnv’s validator scope before being compiled or parsed.\n *\n * Most users will provide schemas in this form.\n *\n * @template def - The schema shape object\n */\nexport type EnvSchema<def> = at.validate<def, $>;\n\n/**\n * Infer the validated and coerced environment object type from a schema.\n * Supports declarative schema shapes, compiled ArkType schemas, and Standard Schema validators.\n *\n * @template T - The schema type\n */\nexport type Infer<T> = T extends SchemaShape\n\t? distill.Out<at.infer<T, $>>\n\t: InferType<T>;\n\n/**\n * The environment variables passed to `arkenv`.\n * Uses `Dict<string>` to enforce\n * compile-time safety: all input environment variables must be strings\n * (or undefined), matching `process.env` semantics.\n */\ntype RuntimeEnvironment = Dict<string>;\n\n/**\n * Configuration options for `arkenv`\n */\nexport type ArkEnvConfig = {\n\t/**\n\t * The environment variables to parse. Defaults to `process.env`\n\t */\n\tenv?: RuntimeEnvironment;\n\t/**\n\t * Whether to coerce environment variables to their defined types. Defaults to `true`\n\t */\n\tcoerce?: boolean;\n\t/**\n\t * Control how ArkEnv handles environment variables that are not defined in your schema.\n\t *\n\t * Defaults to `'delete'` to ensure your output object only contains\n\t * keys you've explicitly declared. This differs from ArkType's standard behavior, which\n\t * mirrors TypeScript by defaulting to `'ignore'`.\n\t *\n\t * - `delete` (ArkEnv default): Undeclared keys are allowed on input but stripped from the output.\n\t * - `ignore` (ArkType default): Undeclared keys are allowed and preserved in the output.\n\t * - `reject`: Undeclared keys will cause validation to fail.\n\t *\n\t * @default \"delete\"\n\t * @see https://arktype.io/docs/configuration#onundeclaredkey\n\t */\n\tonUndeclaredKey?: \"ignore\" | \"delete\" | \"reject\";\n\n\t/**\n\t * The format to use for array parsing when coercion is enabled.\n\t *\n\t * - `comma` (default): Strings are split by comma and trimmed.\n\t * - `json`: Strings are parsed as JSON.\n\t *\n\t * @default \"comma\"\n\t */\n\tarrayFormat?: \"comma\" | \"json\";\n\n\t/**\n\t * Whether to bypass secret redaction and print raw sensitive values during debugging.\n\t * Defaults to checking `process.env.ARKENV_DEBUG_SECRETS === \"true\"` or `\"1\"`.\n\t */\n\tdebugSecrets?: boolean;\n\n\t/**\n\t * Whether to treat empty strings (`\"\"`) as `undefined` before validation.\n\t *\n\t * When enabled, an environment variable set to an empty value (e.g. `PORT=`)\n\t * will be treated as if it were missing, allowing defaults to apply and\n\t * preventing validation errors for numeric or boolean types.\n\t *\n\t * @default false\n\t */\n\temptyAsUndefined?: boolean;\n\n\t/**\n\t * Whether to return a safe result object instead of throwing an error on validation failure.\n\t *\n\t * When enabled, the function returns an object with `{ success: true, data }` or `{ success: false, issues }`.\n\t *\n\t * @default false\n\t */\n\tsafe?: boolean;\n};\n\nexport type { SafeArkEnvResult };\n\n/**\n * Helper type to represent the output of parsing either an EnvSchema or CompiledEnvSchema.\n */\nexport type ArkenvOutput<T extends SchemaShape, D> =\n\t| distill.Out<at.infer<T, $>>\n\t| InferType<D>;\n\n/**\n * Utility to parse environment variables using ArkType or Standard Schema\n *\n * Naming convention: the main function is lowercase (`arkenv`) following the\n * JavaScript convention for functions (e.g. `zod`, `joi`). Classes and types\n * use PascalCase with the full product name (`ArkEnvError`, `SafeArkEnvResult`).\n *\n * @param def The schema definition\n * @param config The evaluation configuration\n * @returns The parsed environment variables, or a SafeArkEnvResult if `{ safe: true }` is configured\n * @throws An {@link ArkEnvError | error} if the environment variables are invalid and `safe` is not enabled\n */\nexport function arkenv<const T extends SchemaShape>(\n\tdef: EnvSchema<T>,\n\tconfig?: ArkEnvConfig & { safe?: false },\n): distill.Out<at.infer<T, $>>;\nexport function arkenv<T extends CompiledEnvSchema>(\n\tdef: T,\n\tconfig?: ArkEnvConfig & { safe?: false },\n): InferType<T>;\nexport function arkenv<\n\tconst T extends SchemaShape,\n\tconst D extends EnvSchema<T> | CompiledEnvSchema,\n>(def: D, config?: ArkEnvConfig & { safe?: false }): ArkenvOutput<T, D>;\nexport function arkenv<const T extends SchemaShape>(\n\tdef: EnvSchema<T>,\n\tconfig: ArkEnvConfig & { safe: true },\n): SafeArkEnvResult<distill.Out<at.infer<T, $>>>;\nexport function arkenv<T extends CompiledEnvSchema>(\n\tdef: T,\n\tconfig: ArkEnvConfig & { safe: true },\n): SafeArkEnvResult<InferType<T>>;\nexport function arkenv<\n\tconst T extends SchemaShape,\n\tconst D extends EnvSchema<T> | CompiledEnvSchema,\n>(\n\tdef: D,\n\tconfig: ArkEnvConfig & { safe: true },\n): SafeArkEnvResult<ArkenvOutput<T, D>>;\nexport function arkenv<\n\tconst T extends SchemaShape,\n\tconst D extends EnvSchema<T> | CompiledEnvSchema,\n>(\n\tdef: D,\n\tconfig: ArkEnvConfig = {},\n): ArkenvOutput<T, D> | SafeArkEnvResult<ArkenvOutput<T, D>> {\n\tif (config.safe) {\n\t\treturn safeExecute(() => parse(def as any, config));\n\t}\n\t// biome-ignore lint/suspicious/noExplicitAny: parse handles both EnvSchema<T> and CompiledEnvSchema at runtime\n\treturn parse(def as any, config);\n}\n","/**\n * Extract the keys from a schema definition dynamically.\n * Supports plain objects, ArkType schemas, and Standard Schema validators.\n *\n * @param schema The schema definition to extract keys from\n * @returns An array of extracted key names\n * @internal\n */\n// biome-ignore lint/suspicious/noExplicitAny: Need to handle various schema formats\nexport function getSchemaKeys(schema: any): string[] {\n\tif (!schema || (typeof schema !== \"object\" && typeof schema !== \"function\")) {\n\t\treturn [];\n\t}\n\n\t// ArkType Type\n\tif (\n\t\tschema.json &&\n\t\ttypeof schema.json === \"object\" &&\n\t\tschema.json.domain === \"object\"\n\t) {\n\t\tconst keys: string[] = [];\n\t\tif (Array.isArray(schema.json.required)) {\n\t\t\tfor (const r of schema.json.required) {\n\t\t\t\tif (r && typeof r === \"object\" && \"key\" in r) {\n\t\t\t\t\tkeys.push(r.key);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif (Array.isArray(schema.json.optional)) {\n\t\t\tfor (const o of schema.json.optional) {\n\t\t\t\tif (o && typeof o === \"object\" && \"key\" in o) {\n\t\t\t\t\tkeys.push(o.key);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn keys;\n\t}\n\n\t// Standard Schema / JSON Schema fallback\n\tconst std = schema[\"~standard\"];\n\tconst jsonSchemaInput =\n\t\t(typeof std?.jsonSchema?.input === \"function\" && std.jsonSchema.input) ||\n\t\t(typeof schema.jsonSchema?.input === \"function\" && schema.jsonSchema.input);\n\n\tif (jsonSchemaInput) {\n\t\ttry {\n\t\t\tconst json = jsonSchemaInput({ target: \"draft-07\" });\n\t\t\tif (json && typeof json === \"object\" && json.properties) {\n\t\t\t\treturn Object.keys(json.properties);\n\t\t\t}\n\t\t} catch {}\n\t}\n\n\tif (typeof schema.toJSONSchema === \"function\") {\n\t\ttry {\n\t\t\tconst json = schema.toJSONSchema();\n\t\t\tif (json && typeof json === \"object\" && json.properties) {\n\t\t\t\treturn Object.keys(json.properties);\n\t\t\t}\n\t\t} catch {}\n\t}\n\n\tif (typeof schema.toStandardJSONSchema?.v1 === \"function\") {\n\t\ttry {\n\t\t\tconst json = schema.toStandardJSONSchema.v1();\n\t\t\tif (json && typeof json === \"object\" && json.properties) {\n\t\t\t\treturn Object.keys(json.properties);\n\t\t\t}\n\t\t} catch {}\n\t}\n\n\t// Plain object schema\n\treturn Object.keys(schema);\n}\n","import { $ } from \"@repo/scope\";\nimport { arkenv } from \"./arkenv\";\nimport { getSchemaKeys } from \"./schema\";\n\nexport { arkenv, getSchemaKeys };\n/**\n * Like ArkType's `type`, but with ArkEnv's extra keywords, such as:\n *\n * - `string.host` – a hostname (e.g. `\"localhost\"`, `\"127.0.0.1\"`)\n * - `number.port` – a port number (e.g. `8080`)\n *\n * See ArkType's docs for the full API:\n * https://arktype.io/docs/type-api\n */\nexport const type = $.type;\nexport type {\n\tArkEnvConfig,\n\tEnvSchema,\n\tInfer,\n\tSafeArkEnvResult,\n} from \"./arkenv\";\n\n/**\n * ArkEnv's main export, an alias for {@link arkenv}\n *\n * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.\n */\nexport default arkenv;\n"],"mappings":"yKAA0C,MAAM,EAAEA,EAAE,+BAA+B,CAAC,EAAEA,EAAE,0BAA0B,CAAC,EAAEC,EAAE,CAAC,OAAOD,EAAE,OAAO,CAAC,GAAGA,EAAE,SAAS,OAAO,KAAK,EAAE,CAAC,CAAC,OAAOA,EAAE,OAAO,CAAC,GAAGA,EAAE,SAAS,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CCmCvN,SAAS,EACR,EACA,EACa,CACb,OAAO,OAAO,QAAQ,EAAO,OAAO,CAAC,KAAK,CAAC,EAAM,KAAW,CAC3D,IAAI,EAAU,EAAM,QAGhB,EAAU,EAAQ,WAAW,CAIjC,GAHI,EAAQ,OAAS,GAAK,MAAM,SAAS,EAAQ,GAAG,GACnD,EAAU,EAAQ,MAAM,EAAE,CAAC,WAAW,EAEnC,EAAQ,aAAa,CAAC,WAAW,EAAK,aAAa,CAAC,CAAE,CACzD,IAAI,EAAO,EAAQ,MAAM,EAAK,OAAO,CAAC,WAAW,CAC7C,EAAK,OAAS,GAAK,MAAM,SAAS,EAAK,GAAG,GAC7C,EAAO,EAAK,MAAM,EAAE,EAErB,EAAU,EAAK,WAAW,CAI3B,EAAU,EAAsB,EAAS,EAAM,GAAQ,aAAa,CAGpE,IAAM,EAAO,EAAe,EAAM,KAAK,CAEjC,EAAqB,CAC1B,GAFc,EAAe,EAEpB,CACT,CAED,OAAO,EACN,EACA,EACA,EACA,EACA,EAAM,SACN,EAAM,OAAS,WAAa,IAAA,GAAY,EAAM,KAC9C,EACA,CAwBH,SAAgB,EACf,EACA,EACC,CACD,GAAM,CACL,MAAM,QAAQ,IACd,OAAQ,EAAe,GACvB,kBAAkB,SAClB,cAAc,QACd,mBAAmB,IAChB,EAQE,GAJiB,OAAO,GAAQ,YAAc,WAAY,EAC/B,EAAME,EAAE,KAAK,IAAI,EAAI,EAGxB,gBAAgB,EAAgB,CAGxD,CAAE,cAAe,EACtB,EACA,EACA,EACA,OAKU,CAAE,OAHI,EAAe,GAAG,aAAa,CAC3C,SAAW,GAA2B,EAAI,KAC1C,CACoB,CAAE,UAAW,GAAM,EAExC,IAAA,GACH,CAGK,EAAe,EAAe,EAAW,CAG/C,GAAI,aAAwB,EAC3B,MAAM,IAAI,EAAY,EAAkB,EAAc,EAAO,CAAC,CAG/D,OAAO,ECmBR,SAAgB,EAIf,EACA,EAAuB,EAAE,CACmC,CAK5D,OAJI,EAAO,KACH,MAAkB,EAAM,EAAY,EAAO,CAAC,CAG7C,EAAM,EAAY,EAAO,CCjKjC,SAAgB,EAAc,EAAuB,CACpD,GAAI,CAAC,GAAW,OAAO,GAAW,UAAY,OAAO,GAAW,WAC/D,MAAO,EAAE,CAIV,GACC,EAAO,MACP,OAAO,EAAO,MAAS,UACvB,EAAO,KAAK,SAAW,SACtB,CACD,IAAM,EAAiB,EAAE,CACzB,GAAI,MAAM,QAAQ,EAAO,KAAK,SAAS,KACjC,IAAM,KAAK,EAAO,KAAK,SACvB,GAAK,OAAO,GAAM,UAAY,QAAS,GAC1C,EAAK,KAAK,EAAE,IAAI,CAInB,GAAI,MAAM,QAAQ,EAAO,KAAK,SAAS,KACjC,IAAM,KAAK,EAAO,KAAK,SACvB,GAAK,OAAO,GAAM,UAAY,QAAS,GAC1C,EAAK,KAAK,EAAE,IAAI,CAInB,OAAO,EAIR,IAAM,EAAM,EAAO,aACb,EACJ,OAAO,GAAK,YAAY,OAAU,YAAc,EAAI,WAAW,OAC/D,OAAO,EAAO,YAAY,OAAU,YAAc,EAAO,WAAW,MAEtE,GAAI,EACH,GAAI,CACH,IAAM,EAAO,EAAgB,CAAE,OAAQ,WAAY,CAAC,CACpD,GAAI,GAAQ,OAAO,GAAS,UAAY,EAAK,WAC5C,OAAO,OAAO,KAAK,EAAK,WAAW,MAE7B,EAGT,GAAI,OAAO,EAAO,cAAiB,WAClC,GAAI,CACH,IAAM,EAAO,EAAO,cAAc,CAClC,GAAI,GAAQ,OAAO,GAAS,UAAY,EAAK,WAC5C,OAAO,OAAO,KAAK,EAAK,WAAW,MAE7B,EAGT,GAAI,OAAO,EAAO,sBAAsB,IAAO,WAC9C,GAAI,CACH,IAAM,EAAO,EAAO,qBAAqB,IAAI,CAC7C,GAAI,GAAQ,OAAO,GAAS,UAAY,EAAK,WAC5C,OAAO,OAAO,KAAK,EAAK,WAAW,MAE7B,EAIT,OAAO,OAAO,KAAK,EAAO,CC1D3B,MAAa,EAAOC,EAAE,KAatB,IAAA,EAAe"}

package/dist/standard.cjs

@@ -1,4 +1,4 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require(`./shared-Bx3sbEJf.cjs`),t=require(`./core-BftJnV8f.cjs`);function n(e,n){if(typeof n==`string`)throw new t.t([{path:e,message:`ArkType DSL strings are not supported in "standard" mode. Use a Standard Schema validator (e.g., Zod, Valibot) or import from "arkenv" for ArkType schemas.`}])}function r(e,n){let r=n&&typeof n==`object`&&`~standard`in n&&n[`~standard`];if(!r||typeof r!=`object`||!(`validate`in r)||typeof r.validate!=`function`)throw new t.t([{path:e,message:`Invalid validator: expected a Standard Schema 1.0 validator (must have "~standard" property). Import from "arkenv" to use ArkType schemas.`}])}function i(e){if(!e||typeof e!=`object`||Array.isArray(e))throw new t.t([{path:``,message:`Invalid schema: expected an object mapping in "standard" mode.`}])}function a(e,t){let n={type:`object`,properties:{}},r=!1;for(let i in e){let a=e[i];if(!a){t.push(i);continue}let o=a[`~standard`];if(typeof o?.jsonSchema?.input==`function`)try{let e=o.jsonSchema.input({target:`draft-07`});if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.jsonSchema?.input==`function`)try{let e=a.jsonSchema.input({target:`draft-07`});if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.toJSONSchema==`function`)try{let e=a.toJSONSchema();if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.toStandardJSONSchema?.v1==`function`)try{let e=a.toStandardJSONSchema.v1();if(e){n.properties[i]=e,r=!0;continue}}catch{}t.push(i)}return{jsonSchema:n,hasJsonSchema:r}}function o(e,t){return!t||t.length===0?e:[e,...t.map(e=>typeof e==`object`&&e&&`key`in e?String(e.key):String(e))].join(`.`)}function s(n,r){let{env:i=process.env,onUndeclaredKey:s=`delete`,coerce:c=!0,arrayFormat:l=`comma`,emptyAsUndefined:u=!1}=r,d={},f=[],p=u?e.r(i):i,m=new Set(Object.keys(p)),h={...p},g=[];if(c){let{jsonSchema:t,hasJsonSchema:r}=a(n,g);r&&(h=e.t(h,e.n(t),{arrayFormat:l}))}for(let e in n){let r=n[e],i=h[e];if(!r||typeof r!=`object`||!(`~standard`in r))throw new t.t([{path:e,message:`Invalid schema: expected a Standard Schema 1.0 validator (e.g. Zod, Valibot) in 'standard' mode.`}]);let a=r[`~standard`].validate(i);if(a instanceof Promise)throw new t.t([{path:e,message:`Async validation is not supported. ArkEnv is synchronous.`}]);if(a.issues)for(let t of a.issues){let n=o(e,t.path),r=t.message;c&&g.includes(e)&&(r+=` (Hint: coercion is enabled by default, but the validator for '${e}' lacks Standard JSON Schema support.)`),f.push({path:n,message:r})}else d[e]=a.value;m.delete(e)}if(s!==`delete`)for(let e of m)s===`reject`?f.push({path:e,message:`Undeclared key`}):s===`ignore`&&(d[e]=h[e]);if(f.length>0)throw new t.t(f);return d}function c(e,t){i(e);for(let t in e){let i=e[t];n(t,i),r(t,i)}return s(e,t??{})}const l=c;exports.createEnv=c,exports.default=l;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require(`./errors-Dn6WQ2pP.cjs`),t=require(`./core-CA13n2Iu.cjs`);function n(e,n){if(typeof n==`string`)throw new t.t([{path:e,message:`ArkType DSL strings are not supported in "standard" mode. Use a Standard Schema validator (e.g., Zod, Valibot) or import from "arkenv" for ArkType schemas.`,code:`INVALID_SCHEMA`}])}function r(e,n){let r=n&&typeof n==`object`&&`~standard`in n&&n[`~standard`];if(!r||typeof r!=`object`||!(`validate`in r)||typeof r.validate!=`function`)throw new t.t([{path:e,message:`Invalid validator: expected a Standard Schema 1.0 validator (must have "~standard" property). Import from "arkenv" to use ArkType schemas.`,code:`INVALID_SCHEMA`}])}function i(e){if(!e||typeof e!=`object`||Array.isArray(e))throw new t.t([{path:``,message:`Invalid schema: expected an object mapping in "standard" mode.`,code:`INVALID_SCHEMA`}])}function a(e){let t={type:`object`,properties:{}},n=!1,r=[];for(let i in e){let a=e[i];if(!a){r.push(i);continue}let o=a[`~standard`];if(typeof o?.jsonSchema?.input==`function`)try{let e=o.jsonSchema.input({target:`draft-07`});if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.jsonSchema?.input==`function`)try{let e=a.jsonSchema.input({target:`draft-07`});if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.toJSONSchema==`function`)try{let e=a.toJSONSchema();if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.toStandardJSONSchema?.v1==`function`)try{let e=a.toStandardJSONSchema.v1();if(e){t.properties[i]=e,n=!0;continue}}catch{}r.push(i)}return{jsonSchema:t,hasJsonSchema:n,missingKeys:r}}function o(e){return typeof e==`object`&&e&&`key`in e?String(e.key):String(e)}function s(e,t){return!t||t.length===0?e:[e,...t.map(o)].join(`.`)}function c(e,t){let n=e,r;try{let i=e,a=e.trim();if(a[0]===`{`||a[0]===`[`)try{i=JSON.parse(e)}catch(e){r=`[Unparseable JSON: ${e.message}]`}if(!r){for(let e of t)i=i?.[o(e)];n=i}}catch(e){r=`[Traversal error: ${e.message}]`}return{receivedVal:n,traversalError:r}}function l(n,r){let{env:i=process.env,onUndeclaredKey:o=`delete`,coerce:l=!0,arrayFormat:u=`comma`,emptyAsUndefined:d=!1}=r,f={},p=[],{processedEnv:m,coercedEnv:h,missingKeys:g}=e.l(i,d,u,l?()=>{let{jsonSchema:e,hasJsonSchema:t,missingKeys:r}=a(n);return{schema:e,hasSchema:t,missingKeys:r}}:void 0),_=new Set(Object.keys(m));for(let i in n){let a=n[i],o=h[i];if(!a||typeof a!=`object`||!(`~standard`in a))throw new t.t([e.t(i,`Invalid schema: expected a Standard Schema 1.0 validator (e.g. Zod, Valibot) in 'standard' mode.`,`INVALID_SCHEMA`)]);let u=a[`~standard`].validate(o);if(u instanceof Promise)throw new t.t([e.t(i,`Async validation is not supported. ArkEnv is synchronous.`,`INVALID_SCHEMA`)]);if(u.issues)for(let t of u.issues){let n=s(i,t.path),a,o;if(i in m){let e=m[i];if(typeof e==`string`&&t.path?.length){let n=c(e,t.path);a=n.receivedVal,o=n.traversalError}else a=e}else a=t.received;let u=e.o(t.code||`invalid_type`,t.message||``,a),d=t.expected||void 0,f={...e.i(t)},h=t;h.validation!==void 0&&(f.validation=h.validation),o!==void 0&&(f.traversalError=o);let _=e.n(t.message||``,u,d,a,n,r);l&&g.includes(i)&&(_+=` (Hint: coercion is enabled by default, but the validator for '${i}' lacks Standard JSON Schema support.)`),p.push(e.t(n,_,u,f,d,a))}else f[i]=u.value;_.delete(i)}if(o!==`delete`)for(let t of _)o===`reject`?p.push(e.t(t,`Undeclared key`,`UNDECLARED_KEY`)):o===`ignore`&&(f[t]=h[t]);if(p.length>0)throw new t.t(p);return f}function u(t,a={}){i(t);for(let e in t){let i=t[e];n(e,i),r(e,i)}return a.safe?e.c(()=>l(t,a)):l(t,a)}exports.arkenv=u,exports.default=u;
 
 // CJS Interop Shim
 if (module.exports && module.exports.default) {

package/dist/standard.d.cts

@@ -1,4 +1,5 @@
-import { i as StandardSchemaV1 } from "./index-CzNfOanV.cjs";
+import { a as SafeArkEnvResult } from "./core-7-JO-N-w.cjs";
+import { a as Dict, i as StandardSchemaV1 } from "./index-Do-2CL1V.cjs";
 
 //#region src/parse-standard.d.ts
 /**
@@ -8,7 +9,7 @@ type ParseStandardConfig = {
   /**
    * The environment variables to parse. Defaults to `process.env`
    */
-  env?: Record<string, string | undefined>;
+  env?: Dict<string>;
   /**
    * Control how ArkEnv handles environment variables that are not defined in your schema.
    *
@@ -22,6 +23,11 @@ type ParseStandardConfig = {
    * @default "delete"
    */
   onUndeclaredKey?: "ignore" | "delete" | "reject";
+  /**
+   * 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 perform best-effort coercion on the environment variables.
    * Coercion requires validators that implement the StandardJSONSchemaV1 spec
@@ -50,11 +56,19 @@ 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;
 };
 //#endregion
 //#region src/standard.d.ts
 /**
- * Configuration options for the `arkenv/standard` entry's `createEnv`.
+ * Configuration options for the `arkenv/standard` entry's `arkenv`.
  */
 type StandardEnvConfig = ParseStandardConfig;
 /**
@@ -65,8 +79,8 @@ type StandardEnvConfig = ParseStandardConfig;
  *
  * @param def An object mapping variable names to Standard Schema validators
  * @param config Optional configuration
- * @returns The validated environment variables
- * @throws An {@link ArkEnvError} if validation fails
+ * @returns The validated environment variables, or a SafeArkEnvResult if `{ safe: true }` is configured
+ * @throws An {@link ArkEnvError} if validation fails and `safe` is not enabled
  *
  * @example
  * ```ts
@@ -79,15 +93,14 @@ type StandardEnvConfig = ParseStandardConfig;
  * });
  * ```
  */
-declare function createEnv<const T extends Record<string, StandardSchemaV1>>(def: T, config?: StandardEnvConfig): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> };
-/**
- * ArkEnv's Standard Schema export, an alias for {@link createEnv}
- *
- * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
- */
-declare const arkenv: typeof createEnv;
+declare function arkenv<const T extends Record<string, StandardSchemaV1>>(def: T, config?: StandardEnvConfig & {
+  safe?: false;
+}): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> };
+declare function arkenv<const T extends Record<string, StandardSchemaV1>>(def: T, config: StandardEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<{ [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }>;
 //#endregion
-export { StandardEnvConfig, createEnv, arkenv as default };
+export { StandardEnvConfig, arkenv, arkenv as default };
 
 // CJS Interop Shim
 if (module.exports && module.exports.default) {

package/dist/standard.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"standard.d.cts","names":[],"sources":["../src/parse-standard.ts","../src/standard.ts"],"mappings":";;;;;;KAWY,mBAAA;EAAmB;;;EAI9B,GAAA,GAAM,MAAA;EAAA;;;;;;;;;;ACJP;;EDiBC,eAAA;ECjB+B;;AAwBhC;;;;;;EDEC,MAAA;ECCgB;;;;;;;;EDQhB,WAAA;ECVK;;;;;;;;;EDqBL,gBAAA;AAAA;;;;AA9CD;;KCAY,iBAAA,GAAoB,mBAAA;;;;;;;;;;;;;AAAhC;;;;;AAwBA;;;;;iBAAgB,SAAA,iBAA0B,MAAA,SAAe,gBAAA,EAAA,CACxD,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,iBAAA,iBACO,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA;;;;;;cAmB9C,MAAA,SAAM,SAAA"}
+{"version":3,"file":"standard.d.cts","names":[],"sources":["../src/parse-standard.ts","../src/standard.ts"],"mappings":";;;;;;;KAqCY,mBAAA;EAAmB;;;EAI9B,GAAA,GAAM,IAAA;EAAA;;;;;;;;;;;;EAaN,eAAA;ECzC4B;;;;ED8C5B,YAAA;ECtBqB;;;;;;;;EDgCrB,MAAA;EC7BoB;;;;;;;;EDuCpB,WAAA;ECxC+B;;;;;;;;;EDmD/B,gBAAA;ECjDe;;;;;;;ED0Df,IAAA;AAAA;;;;AA9DD;;KCxBY,iBAAA,GAAoB,mBAAA;;;;;;;;;;;;;;;AAAhC;;;;;AAwBA;;;iBAAgB,MAAA,iBAAuB,MAAA,SAAe,gBAAA,EAAA,CACrD,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,iBAAA;EAAsB,IAAA;AAAA,kBACf,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA;AAAA,iBACpC,MAAA,iBAAuB,MAAA,SAAe,gBAAA,EAAA,CACrD,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,iBAAA;EAAsB,IAAA;AAAA,IAC5B,gBAAA,eAA+B,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA"}

package/dist/standard.d.mts

@@ -1,4 +1,5 @@
-import { i as StandardSchemaV1 } from "./index-Br22fqkz.mjs";
+import { a as SafeArkEnvResult } from "./core-BaGd9k2K.mjs";
+import { a as Dict, i as StandardSchemaV1 } from "./index-NbQAnciD.mjs";
 
 //#region src/parse-standard.d.ts
 /**
@@ -8,7 +9,7 @@ type ParseStandardConfig = {
   /**
    * The environment variables to parse. Defaults to `process.env`
    */
-  env?: Record<string, string | undefined>;
+  env?: Dict<string>;
   /**
    * Control how ArkEnv handles environment variables that are not defined in your schema.
    *
@@ -22,6 +23,11 @@ type ParseStandardConfig = {
    * @default "delete"
    */
   onUndeclaredKey?: "ignore" | "delete" | "reject";
+  /**
+   * 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 perform best-effort coercion on the environment variables.
    * Coercion requires validators that implement the StandardJSONSchemaV1 spec
@@ -50,11 +56,19 @@ 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;
 };
 //#endregion
 //#region src/standard.d.ts
 /**
- * Configuration options for the `arkenv/standard` entry's `createEnv`.
+ * Configuration options for the `arkenv/standard` entry's `arkenv`.
  */
 type StandardEnvConfig = ParseStandardConfig;
 /**
@@ -65,8 +79,8 @@ type StandardEnvConfig = ParseStandardConfig;
  *
  * @param def An object mapping variable names to Standard Schema validators
  * @param config Optional configuration
- * @returns The validated environment variables
- * @throws An {@link ArkEnvError} if validation fails
+ * @returns The validated environment variables, or a SafeArkEnvResult if `{ safe: true }` is configured
+ * @throws An {@link ArkEnvError} if validation fails and `safe` is not enabled
  *
  * @example
  * ```ts
@@ -79,14 +93,13 @@ type StandardEnvConfig = ParseStandardConfig;
  * });
  * ```
  */
-declare function createEnv<const T extends Record<string, StandardSchemaV1>>(def: T, config?: StandardEnvConfig): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> };
-/**
- * ArkEnv's Standard Schema export, an alias for {@link createEnv}
- *
- * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
- */
-declare const arkenv: typeof createEnv;
+declare function arkenv<const T extends Record<string, StandardSchemaV1>>(def: T, config?: StandardEnvConfig & {
+  safe?: false;
+}): { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> };
+declare function arkenv<const T extends Record<string, StandardSchemaV1>>(def: T, config: StandardEnvConfig & {
+  safe: true;
+}): SafeArkEnvResult<{ [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }>;
 //#endregion
-export { StandardEnvConfig, createEnv, arkenv as default };
+export { StandardEnvConfig, arkenv, arkenv as default };
 
 //# sourceMappingURL=standard.d.mts.map

package/dist/standard.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"standard.d.mts","names":[],"sources":["../src/parse-standard.ts","../src/standard.ts"],"mappings":";;;;;;KAWY,mBAAA;EAAmB;;;EAI9B,GAAA,GAAM,MAAA;EAAA;;;;;;;;;;ACJP;;EDiBC,eAAA;ECjB+B;;AAwBhC;;;;;;EDEC,MAAA;ECCgB;;;;;;;;EDQhB,WAAA;ECVK;;;;;;;;;EDqBL,gBAAA;AAAA;;;;AA9CD;;KCAY,iBAAA,GAAoB,mBAAA;;;;;;;;;;;;;AAAhC;;;;;AAwBA;;;;;iBAAgB,SAAA,iBAA0B,MAAA,SAAe,gBAAA,EAAA,CACxD,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,iBAAA,iBACO,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA;;;;;;cAmB9C,MAAA,SAAM,SAAA"}
+{"version":3,"file":"standard.d.mts","names":[],"sources":["../src/parse-standard.ts","../src/standard.ts"],"mappings":";;;;;;;KAqCY,mBAAA;EAAmB;;;EAI9B,GAAA,GAAM,IAAA;EAAA;;;;;;;;;;;;EAaN,eAAA;ECzC4B;;;;ED8C5B,YAAA;ECtBqB;;;;;;;;EDgCrB,MAAA;EC7BoB;;;;;;;;EDuCpB,WAAA;ECxC+B;;;;;;;;;EDmD/B,gBAAA;ECjDe;;;;;;;ED0Df,IAAA;AAAA;;;;AA9DD;;KCxBY,iBAAA,GAAoB,mBAAA;;;;;;;;;;;;;;;AAAhC;;;;;AAwBA;;;iBAAgB,MAAA,iBAAuB,MAAA,SAAe,gBAAA,EAAA,CACrD,GAAA,EAAK,CAAA,EACL,MAAA,GAAS,iBAAA;EAAsB,IAAA;AAAA,kBACf,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA;AAAA,iBACpC,MAAA,iBAAuB,MAAA,SAAe,gBAAA,EAAA,CACrD,GAAA,EAAK,CAAA,EACL,MAAA,EAAQ,iBAAA;EAAsB,IAAA;AAAA,IAC5B,gBAAA,eAA+B,CAAA,GAAI,gBAAA,CAAiB,WAAA,CAAY,CAAA,CAAE,CAAA"}

package/dist/standard.mjs

@@ -1,3 +1,3 @@
-import{n as e,r as t,t as n}from"./shared-B7lIFzfk.mjs";import{t as r}from"./core-B0IkKRzg.mjs";function i(e,t){if(typeof t==`string`)throw new r([{path:e,message:`ArkType DSL strings are not supported in "standard" mode. Use a Standard Schema validator (e.g., Zod, Valibot) or import from "arkenv" for ArkType schemas.`}])}function a(e,t){let n=t&&typeof t==`object`&&`~standard`in t&&t[`~standard`];if(!n||typeof n!=`object`||!(`validate`in n)||typeof n.validate!=`function`)throw new r([{path:e,message:`Invalid validator: expected a Standard Schema 1.0 validator (must have "~standard" property). Import from "arkenv" to use ArkType schemas.`}])}function o(e){if(!e||typeof e!=`object`||Array.isArray(e))throw new r([{path:``,message:`Invalid schema: expected an object mapping in "standard" mode.`}])}function s(e,t){let n={type:`object`,properties:{}},r=!1;for(let i in e){let a=e[i];if(!a){t.push(i);continue}let o=a[`~standard`];if(typeof o?.jsonSchema?.input==`function`)try{let e=o.jsonSchema.input({target:`draft-07`});if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.jsonSchema?.input==`function`)try{let e=a.jsonSchema.input({target:`draft-07`});if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.toJSONSchema==`function`)try{let e=a.toJSONSchema();if(e){n.properties[i]=e,r=!0;continue}}catch{}if(typeof a.toStandardJSONSchema?.v1==`function`)try{let e=a.toStandardJSONSchema.v1();if(e){n.properties[i]=e,r=!0;continue}}catch{}t.push(i)}return{jsonSchema:n,hasJsonSchema:r}}function c(e,t){return!t||t.length===0?e:[e,...t.map(e=>typeof e==`object`&&e&&`key`in e?String(e.key):String(e))].join(`.`)}function l(i,a){let{env:o=process.env,onUndeclaredKey:l=`delete`,coerce:u=!0,arrayFormat:d=`comma`,emptyAsUndefined:f=!1}=a,p={},m=[],h=f?t(o):o,g=new Set(Object.keys(h)),_={...h},v=[];if(u){let{jsonSchema:t,hasJsonSchema:r}=s(i,v);r&&(_=n(_,e(t),{arrayFormat:d}))}for(let e in i){let t=i[e],n=_[e];if(!t||typeof t!=`object`||!(`~standard`in t))throw new r([{path:e,message:`Invalid schema: expected a Standard Schema 1.0 validator (e.g. Zod, Valibot) in 'standard' mode.`}]);let a=t[`~standard`].validate(n);if(a instanceof Promise)throw new r([{path:e,message:`Async validation is not supported. ArkEnv is synchronous.`}]);if(a.issues)for(let t of a.issues){let n=c(e,t.path),r=t.message;u&&v.includes(e)&&(r+=` (Hint: coercion is enabled by default, but the validator for '${e}' lacks Standard JSON Schema support.)`),m.push({path:n,message:r})}else p[e]=a.value;g.delete(e)}if(l!==`delete`)for(let e of g)l===`reject`?m.push({path:e,message:`Undeclared key`}):l===`ignore`&&(p[e]=_[e]);if(m.length>0)throw new r(m);return p}function u(e,t){o(e);for(let t in e){let n=e[t];i(t,n),a(t,n)}return l(e,t??{})}const d=u;export{u as createEnv,d as default};
+import{c as e,i as t,l as n,n as r,o as i,t as a}from"./errors-C_uh86xh.mjs";import{t as o}from"./core-A65KioHX.mjs";function s(e,t){if(typeof t==`string`)throw new o([{path:e,message:`ArkType DSL strings are not supported in "standard" mode. Use a Standard Schema validator (e.g., Zod, Valibot) or import from "arkenv" for ArkType schemas.`,code:`INVALID_SCHEMA`}])}function c(e,t){let n=t&&typeof t==`object`&&`~standard`in t&&t[`~standard`];if(!n||typeof n!=`object`||!(`validate`in n)||typeof n.validate!=`function`)throw new o([{path:e,message:`Invalid validator: expected a Standard Schema 1.0 validator (must have "~standard" property). Import from "arkenv" to use ArkType schemas.`,code:`INVALID_SCHEMA`}])}function l(e){if(!e||typeof e!=`object`||Array.isArray(e))throw new o([{path:``,message:`Invalid schema: expected an object mapping in "standard" mode.`,code:`INVALID_SCHEMA`}])}function u(e){let t={type:`object`,properties:{}},n=!1,r=[];for(let i in e){let a=e[i];if(!a){r.push(i);continue}let o=a[`~standard`];if(typeof o?.jsonSchema?.input==`function`)try{let e=o.jsonSchema.input({target:`draft-07`});if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.jsonSchema?.input==`function`)try{let e=a.jsonSchema.input({target:`draft-07`});if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.toJSONSchema==`function`)try{let e=a.toJSONSchema();if(e){t.properties[i]=e,n=!0;continue}}catch{}if(typeof a.toStandardJSONSchema?.v1==`function`)try{let e=a.toStandardJSONSchema.v1();if(e){t.properties[i]=e,n=!0;continue}}catch{}r.push(i)}return{jsonSchema:t,hasJsonSchema:n,missingKeys:r}}function d(e){return typeof e==`object`&&e&&`key`in e?String(e.key):String(e)}function f(e,t){return!t||t.length===0?e:[e,...t.map(d)].join(`.`)}function p(e,t){let n=e,r;try{let i=e,a=e.trim();if(a[0]===`{`||a[0]===`[`)try{i=JSON.parse(e)}catch(e){r=`[Unparseable JSON: ${e.message}]`}if(!r){for(let e of t)i=i?.[d(e)];n=i}}catch(e){r=`[Traversal error: ${e.message}]`}return{receivedVal:n,traversalError:r}}function m(e,s){let{env:c=process.env,onUndeclaredKey:l=`delete`,coerce:d=!0,arrayFormat:m=`comma`,emptyAsUndefined:h=!1}=s,g={},_=[],{processedEnv:v,coercedEnv:y,missingKeys:b}=n(c,h,m,d?()=>{let{jsonSchema:t,hasJsonSchema:n,missingKeys:r}=u(e);return{schema:t,hasSchema:n,missingKeys:r}}:void 0),x=new Set(Object.keys(v));for(let n in e){let c=e[n],l=y[n];if(!c||typeof c!=`object`||!(`~standard`in c))throw new o([a(n,`Invalid schema: expected a Standard Schema 1.0 validator (e.g. Zod, Valibot) in 'standard' mode.`,`INVALID_SCHEMA`)]);let u=c[`~standard`].validate(l);if(u instanceof Promise)throw new o([a(n,`Async validation is not supported. ArkEnv is synchronous.`,`INVALID_SCHEMA`)]);if(u.issues)for(let e of u.issues){let o=f(n,e.path),c,l;if(n in v){let t=v[n];if(typeof t==`string`&&e.path?.length){let n=p(t,e.path);c=n.receivedVal,l=n.traversalError}else c=t}else c=e.received;let u=i(e.code||`invalid_type`,e.message||``,c),m=e.expected||void 0,h={...t(e)},g=e;g.validation!==void 0&&(h.validation=g.validation),l!==void 0&&(h.traversalError=l);let y=r(e.message||``,u,m,c,o,s);d&&b.includes(n)&&(y+=` (Hint: coercion is enabled by default, but the validator for '${n}' lacks Standard JSON Schema support.)`),_.push(a(o,y,u,h,m,c))}else g[n]=u.value;x.delete(n)}if(l!==`delete`)for(let e of x)l===`reject`?_.push(a(e,`Undeclared key`,`UNDECLARED_KEY`)):l===`ignore`&&(g[e]=y[e]);if(_.length>0)throw new o(_);return g}function h(t,n={}){l(t);for(let e in t){let n=t[e];s(e,n),c(e,n)}return n.safe?e(()=>m(t,n)):m(t,n)}export{h as arkenv,h as default};
 
 //# sourceMappingURL=standard.mjs.map