@arkenv/core 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/index.d.cts

@@ -5937,43 +5937,110 @@ interface MorphableIntersection<piped extends boolean> extends Hkt<[unknown, unk
 }
 type intersectObjects<l, r, piped extends boolean> = l extends array ? r extends array ? intersectArrays<l, r, MorphableIntersection<piped>> : // for an intersection with exactly one array operand like { name: string } & string[],
 l & r : r extends array ? l & r : keyof l & keyof r extends never ? show<l & r> : show<{ [k in keyof l]: k extends keyof r ? _inferIntersection<l[k], r[k], piped> : l[k] } & { [k in keyof r]: k extends keyof l ? _inferIntersection<l[k], r[k], piped> : r[k] }>; //#endregion
-//#region src/coercion/environment.d.ts
+//#region ../types/dist/standard-schema.d.ts
 /**
- * Prepare an environment record by optionally stripping empty strings and applying coercion.
+ * @see https://github.com/standard-schema/standard-schema/tree/3130ce43fdd848d9ab49dbb0458d04f18459961c/packages/spec
  *
- * @param env The raw environment variables
- * @param emptyAsUndefined Whether to strip empty string values before processing
- * @param arrayFormat The format to use for array coercion
- * @param getSchema Optional callback that returns a JSON Schema and whether it exists,
- *        used to determine coercion targets. When omitted, no coercion is performed.
- * @returns The processed environment, the coerced environment, and any missing schema keys
+ * Copied from standard-schema (MIT License)
+ * Copyright (c) 2024 Colin McDannell
+ */
+/**
+ * The Standard Typed interface. This is a base type extended by other specs.
  */
 //#endregion
 //#region src/core.d.ts
 /**
  * Machine-readable classification codes for environment validation issues.
- * Serves as the Source of Truth (SoT) for error categorization in ArkEnv.
  */
-type EnvIssueCode = /** The environment variable is required but was not provided, and has no default value. */"MISSING_VARIABLE" /** The variable value failed a type assertion (e.g., expected a number or boolean but received a string). */ | "INVALID_TYPE" /** The variable value falls below the minimum allowed numeric limit or string/array length constraint. */ | "VALUE_TOO_SMALL" /** The variable value exceeds the maximum allowed numeric limit or string/array length constraint. */ | "VALUE_TOO_LARGE" /** The variable value did not match the specified regular expression (regex) pattern constraint. */ | "PATTERN_MISMATCH" /** The variable value is not in a valid format (e.g., failed email or UUID format validation). */ | "INVALID_FORMAT" /** An undeclared key was found in the environment, and the schema config is set to reject undeclared keys. */ | "UNDECLARED_KEY" /** The provided validation schema definition itself is malformed or invalid. */ | "INVALID_SCHEMA" /** A validation error was triggered by a custom validator function or inline pipe logic. */ | "CUSTOM";
+type EnvIssueCode =
+/**
+ * The environment variable is required but was not provided, and has no default value.
+ */
+"MISSING_VARIABLE"
+/**
+ * The variable value failed a type assertion (e.g., expected a number or boolean but received a string).
+ */
+| "INVALID_TYPE"
+/**
+ * The variable value falls below the minimum allowed numeric limit or string/array length constraint.
+ */
+| "VALUE_TOO_SMALL"
+/**
+ * The variable value exceeds the maximum allowed numeric limit or string/array length constraint.
+ */
+| "VALUE_TOO_LARGE"
+/**
+ * The variable value did not match the specified regular expression (regex) pattern constraint.
+ */
+| "PATTERN_MISMATCH"
+/**
+ * The variable value is not in a valid format (e.g., failed email or UUID format validation).
+ */
+| "INVALID_FORMAT"
+/**
+ * An undeclared key was found in the environment, and the schema config is set to reject undeclared keys.
+ */
+| "UNDECLARED_KEY"
+/**
+ * The provided validation schema definition itself is malformed or invalid.
+ */
+| "INVALID_SCHEMA"
+/**
+ * A validation error was triggered by a custom validator function or inline pipe logic.
+ */
+| "CUSTOM";
 /**
  * Metadata associated with an environment validation issue.
  */
 type EnvIssueMeta = {
-  /** The minimum expected boundary for numeric/string length constraints */min?: number; /** The maximum expected boundary for numeric/string length constraints */
-  max?: number; /** Additional validation pattern/specifier details */
-  validation?: string; /** Any custom constraint descriptions */
-  constraint?: string; /** Traversal error occurred during JSON-parsing of the environment variable */
+  /**
+   * The minimum expected boundary for numeric/string length constraints
+   */
+  min?: number;
+  /**
+   * The maximum expected boundary for numeric/string length constraints
+   */
+  max?: number;
+  /**
+   * Additional validation pattern/specifier details
+   */
+  validation?: string;
+  /**
+   * Any custom constraint descriptions
+   */
+  constraint?: string;
+  /**
+   * Traversal error occurred during JSON-parsing of the environment variable
+   */
   traversalError?: string;
 };
 /**
  * Normalized validation issue representing a failure on a specific environment variable.
  */
 type EnvIssue = {
-  /** The dot-separated property path/name of the environment variable */path: string; /** The descriptive, user-friendly error message */
-  message: string; /** The normalized classification code for the issue */
-  code: EnvIssueCode; /** The expected type or value shape description */
-  expected?: string; /** The raw value received (redacted in string formatting if sensitive) */
-  received?: unknown; /** Additional validation metadata */
+  /**
+   * The dot-separated property path/name of the environment variable
+   */
+  path: string;
+  /**
+   * The descriptive, user-friendly error message
+   */
+  message: string;
+  /**
+   * The normalized classification code for the issue
+   */
+  code: EnvIssueCode;
+  /**
+   * The expected type or value shape description
+   */
+  expected?: string;
+  /**
+   * The raw value received (redacted in string formatting if sensitive)
+   */
+  received?: unknown;
+  /**
+   * Additional validation metadata
+   */
   meta?: EnvIssueMeta;
 };
 /**
@@ -5991,9 +6058,6 @@ declare function formatIssues(issues: EnvIssue[]): string;
  *
  * @example
  * ```ts
- * import arkenv from 'arkenv';
- * import { ArkEnvError } from 'arkenv/core';
- *
  * try {
  *   const env = arkenv({
  *     PORT: 'number.port',
@@ -6007,7 +6071,9 @@ declare function formatIssues(issues: EnvIssue[]): string;
  * ```
  */
 declare class ArkEnvError extends Error {
-  /** The list of normalized issues that caused the validation failure */
+  /**
+   * The list of normalized issues that caused the validation failure
+   */
   readonly issues: EnvIssue[];
   constructor(issues: EnvIssue[], message?: string);
 }
@@ -6029,23 +6095,19 @@ type SafeArkEnvResult<T> = {
 //#endregion
 //#region src/schema.d.ts
 /**
- * Extract the keys from a schema definition dynamically.
+ * Extract the keys from a schema definition.
  * 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/utils/errors.d.ts
+//#region src/schema-capture.d.ts
 /**
- * Map a Standard Schema validation issue to a normalized EnvIssueCode.
+ * Start recording `arkenv()` schema arguments instead of validating the environment.
  *
- * @param engineCode The raw issue code from the Standard Schema engine
- * @param message The error message associated with the issue
- * @param receivedVal The raw value received by the validator
- * @returns The normalized EnvIssueCode classification
- * @internal
+ * CLI-supporting API: tools such as the ArkEnv CLI use this to inspect a user's
+ * schema module without requiring `process.env` to be populated.
  */
 //#endregion
 //#region ../internal/scope/dist/index.d.ts
@@ -6138,79 +6200,139 @@ type Dict<T> = Record<string, T | undefined>;
  * Copied from standard-schema (MIT License)
  * Copyright (c) 2024 Colin McDannell
  */
-/** The Standard Typed interface. This is a base type extended by other specs. */
+/**
+ * The Standard Typed interface. This is a base type extended by other specs.
+ */
 interface StandardTypedV1<Input = unknown, Output = Input> {
-  /** The Standard properties. */
+  /**
+   * The Standard properties.
+   */
   readonly "~standard": StandardTypedV1.Props<Input, Output>;
 }
 declare namespace StandardTypedV1 {
-  /** The Standard Typed properties interface. */
+  /**
+   * The Standard Typed properties interface.
+   */
   interface Props<Input = unknown, Output = Input> {
-    /** The version number of the standard. */
+    /**
+     * The version number of the standard.
+     */
     readonly version: 1;
-    /** The vendor name of the schema library. */
+    /**
+     * The vendor name of the schema library.
+     */
     readonly vendor: string;
-    /** Inferred types associated with the schema. */
+    /**
+     * Inferred types associated with the schema.
+     */
     readonly types?: Types<Input, Output> | undefined;
   }
-  /** The Standard Typed types interface. */
+  /**
+   * The Standard Typed types interface.
+   */
   interface Types<Input = unknown, Output = Input> {
-    /** The input type of the schema. */
+    /**
+     * The input type of the schema.
+     */
     readonly input: Input;
-    /** The output type of the schema. */
+    /**
+     * The output type of the schema.
+     */
     readonly output: Output;
   }
-  /** Infers the input type of a Standard Typed. */
+  /**
+   * Infers the input type of a Standard Typed.
+   */
   type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
-  /** Infers the output type of a Standard Typed. */
+  /**
+   * Infers the output type of a Standard Typed.
+   */
   type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
 }
-/** The Standard Schema interface. */
+/**
+ * The Standard Schema interface.
+ */
 interface StandardSchemaV1<Input = unknown, Output = Input> {
-  /** The Standard Schema properties. */
+  /**
+   * The Standard Schema properties.
+   */
   readonly "~standard": StandardSchemaV1.Props<Input, Output>;
 }
 declare namespace StandardSchemaV1 {
-  /** The Standard Schema properties interface. */
+  /**
+   * The Standard Schema properties interface.
+   */
   interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
-    /** Validates unknown input values. */
+    /**
+     * Validates unknown input values.
+     */
     readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
   }
-  /** The result interface of the validate function. */
+  /**
+   * The result interface of the validate function.
+   */
   type Result<Output> = SuccessResult<Output> | FailureResult;
-  /** The result interface if validation succeeds. */
+  /**
+   * The result interface if validation succeeds.
+   */
   interface SuccessResult<Output> {
-    /** The typed output value. */
+    /**
+     * The typed output value.
+     */
     readonly value: Output;
-    /** A falsy value for `issues` indicates success. */
+    /**
+     * A falsy value for `issues` indicates success.
+     */
     readonly issues?: undefined;
   }
   interface Options {
-    /** Explicit support for additional vendor-specific parameters, if needed. */
+    /**
+     * Explicit support for additional vendor-specific parameters, if needed.
+     */
     readonly libraryOptions?: Record<string, unknown> | undefined;
   }
-  /** The result interface if validation fails. */
+  /**
+   * The result interface if validation fails.
+   */
   interface FailureResult {
-    /** The issues of failed validation. */
+    /**
+     * The issues of failed validation.
+     */
     readonly issues: ReadonlyArray<Issue>;
   }
-  /** The issue interface of the failure output. */
+  /**
+   * The issue interface of the failure output.
+   */
   interface Issue {
-    /** The error message of the issue. */
+    /**
+     * The error message of the issue.
+     */
     readonly message: string;
-    /** The path of the issue, if any. */
+    /**
+     * The path of the issue, if any.
+     */
     readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
   }
-  /** The path segment interface of the issue. */
+  /**
+   * The path segment interface of the issue.
+   */
   interface PathSegment {
-    /** The key representing a path segment. */
+    /**
+     * The key representing a path segment.
+     */
     readonly key: PropertyKey;
   }
-  /** The Standard types interface. */
+  /**
+   * The Standard types interface.
+   */
   interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
-  /** Infers the input type of a Standard. */
+  /**
+   * Infers the input type of a Standard.
+   */
   type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
-  /** Infers the output type of a Standard. */
+  /**
+   * Infers the output type of a Standard.
+   */
   type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
 }
 //#endregion
@@ -6248,14 +6370,8 @@ type CompiledEnvSchema = Type<SchemaShape, $$1>;
 /**
  * Declarative environment schema definition accepted by ArkEnv.
  *
- * Represents a declarative schema object mapping environment
- * variable names to schema definitions (e.g. ArkType DSL strings
- * or Standard Schema validators).
- *
- * This type is used to validate that a schema object is compatible with
- * ArkEnv’s validator scope before being compiled or parsed.
- *
- * Most users will provide schemas in this form.
+ * Maps environment variable names to schema definitions (e.g. ArkType DSL
+ * strings or Standard Schema validators).
  *
  * @template def - The schema shape object
  */
@@ -6286,12 +6402,10 @@ type ArkEnvConfig = {
   /**
    * Control how ArkEnv handles environment variables that are not defined in your schema.
    *
-   * Defaults to `'delete'` to ensure your output object only contains
-   * keys you've explicitly declared. This differs from ArkType's standard behavior, which
-   * mirrors TypeScript by defaulting to `'ignore'`.
+   * Defaults to `'delete'` so the output object only contains keys you've declared.
    *
-   * - `delete` (ArkEnv default): Undeclared keys are allowed on input but stripped from the output.
-   * - `ignore` (ArkType default): Undeclared keys are allowed and preserved in the output.
+   * - `delete` (default): Undeclared keys are allowed on input but stripped from the output.
+   * - `ignore`: Undeclared keys are allowed and preserved in the output.
    * - `reject`: Undeclared keys will cause validation to fail.
    *
    * @default "delete"
@@ -6332,19 +6446,15 @@ type ArkEnvConfig = {
   safe?: boolean;
 };
 /**
- * Helper type to represent the output of parsing either an EnvSchema or CompiledEnvSchema.
+ * Parsed environment object inferred from an EnvSchema or CompiledEnvSchema.
  */
 type ArkenvOutput<T extends SchemaShape, D> = distill.Out<type$1.infer<T, $$1>> | InferType<D>;
 /**
- * Utility to parse environment variables using ArkType or Standard Schema
- *
- * 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`).
+ * Parse and validate environment variables using ArkType or Standard Schema.
  *
  * @param def The schema definition
  * @param config The evaluation configuration
- * @returns The parsed environment variables, or a SafeArkEnvResult if `{ safe: true }` is configured
+ * @returns The parsed environment variables, a SafeArkEnvResult if `{ safe: true }` is configured, or a value-less stub when schema capture is active
  * @throws An {@link ArkEnvError | error} if the environment variables are invalid and `safe` is not enabled
  */
 declare function arkenv<const T extends SchemaShape>(def: EnvSchema<T>, config?: ArkEnvConfig & {