@arkenv/standard 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/bind-arkenv-D5X_ukEU.js

@@ -0,0 +1 @@
+import{t as e}from"./src-CJWeQijZ.js";function t(t){function n(n,r){return e(n,{...r,toJsonSchema:r?.toJsonSchema??t})}return n}export{t};

package/dist/{bind-arkenv-F4i-iDsA.cjs → bind-arkenv-DCVPKJ39.cjs}

@@ -1 +1 @@
-const e=require(`./src-BZoXXFsx.cjs`);function t(t){function n(n,r){return e.t(n,{...r,toJsonSchema:r?.toJsonSchema??t})}return n}Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return t}});
+const e=require(`./src-DTEO2b2p.cjs`);function t(t){function n(n,r){return e.t(n,{...r,toJsonSchema:r?.toJsonSchema??t})}return n}Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return t}});

package/dist/index-ByAIZ0F1.d.ts

@@ -0,0 +1,622 @@
+//#region ../internal/types/dist/standard-schema.d.ts
+/**
+ * @see https://github.com/standard-schema/standard-schema/tree/3130ce43fdd848d9ab49dbb0458d04f18459961c/packages/spec
+ *
+ * Copied from standard-schema (MIT License)
+ * Copyright (c) 2024 Colin McDannell
+ */
+/**
+ * The Standard Typed interface. This is a base type extended by other specs.
+ */
+interface StandardTypedV1$1<Input = unknown, Output = Input> {
+  /**
+   * The Standard properties.
+   */
+  readonly "~standard": StandardTypedV1$1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1$1 {
+  /**
+   * The Standard Typed properties interface.
+   */
+  interface Props<Input = unknown, Output = Input> {
+    /**
+     * The version number of the standard.
+     */
+    readonly version: 1;
+    /**
+     * The vendor name of the schema library.
+     */
+    readonly vendor: string;
+    /**
+     * Inferred types associated with the schema.
+     */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /**
+   * The Standard Typed types interface.
+   */
+  interface Types<Input = unknown, Output = Input> {
+    /**
+     * The input type of the schema.
+     */
+    readonly input: Input;
+    /**
+     * The output type of the schema.
+     */
+    readonly output: Output;
+  }
+  /**
+   * Infers the input type of a Standard Typed.
+   */
+  type InferInput<Schema extends StandardTypedV1$1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /**
+   * Infers the output type of a Standard Typed.
+   */
+  type InferOutput<Schema extends StandardTypedV1$1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/**
+ * The Standard Schema interface.
+ */
+interface StandardSchemaV1$1<Input = unknown, Output = Input> {
+  /**
+   * The Standard Schema properties.
+   */
+  readonly "~standard": StandardSchemaV1$1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1$1 {
+  /**
+   * The Standard Schema properties interface.
+   */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1$1.Props<Input, Output> {
+    /**
+     * Validates unknown input values.
+     */
+    readonly validate: (value: unknown, options?: StandardSchemaV1$1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /**
+   * The result interface of the validate function.
+   */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /**
+   * The result interface if validation succeeds.
+   */
+  interface SuccessResult<Output> {
+    /**
+     * The typed output value.
+     */
+    readonly value: Output;
+    /**
+     * A falsy value for `issues` indicates success.
+     */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /**
+     * Explicit support for additional vendor-specific parameters, if needed.
+     */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /**
+   * The result interface if validation fails.
+   */
+  interface FailureResult {
+    /**
+     * The issues of failed validation.
+     */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /**
+   * The issue interface of the failure output.
+   */
+  interface Issue {
+    /**
+     * The error message of the issue.
+     */
+    readonly message: string;
+    /**
+     * The path of the issue, if any.
+     */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /**
+   * The path segment interface of the issue.
+   */
+  interface PathSegment {
+    /**
+     * The key representing a path segment.
+     */
+    readonly key: PropertyKey;
+  }
+  /**
+   * The Standard types interface.
+   */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1$1.Types<Input, Output> {}
+  /**
+   * Infers the input type of a Standard.
+   */
+  type InferInput<Schema extends StandardTypedV1$1> = StandardTypedV1$1.InferInput<Schema>;
+  /**
+   * Infers the output type of a Standard.
+   */
+  type InferOutput<Schema extends StandardTypedV1$1> = StandardTypedV1$1.InferOutput<Schema>;
+}
+//#endregion
+//#region ../internal/utils/dist/index.d.ts
+//#endregion
+//#region ../types/dist/standard-schema.d.ts
+/**
+ * @see https://github.com/standard-schema/standard-schema/tree/3130ce43fdd848d9ab49dbb0458d04f18459961c/packages/spec
+ *
+ * Copied from standard-schema (MIT License)
+ * Copyright (c) 2024 Colin McDannell
+ */
+/**
+ * The Standard Typed interface. This is a base type extended by other specs.
+ */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /**
+   * The Standard properties.
+   */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /**
+   * The Standard Typed properties interface.
+   */
+  interface Props<Input = unknown, Output = Input> {
+    /**
+     * The version number of the standard.
+     */
+    readonly version: 1;
+    /**
+     * The vendor name of the schema library.
+     */
+    readonly vendor: string;
+    /**
+     * Inferred types associated with the schema.
+     */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /**
+   * The Standard Typed types interface.
+   */
+  interface Types<Input = unknown, Output = Input> {
+    /**
+     * The input type of the schema.
+     */
+    readonly input: Input;
+    /**
+     * The output type of the schema.
+     */
+    readonly output: Output;
+  }
+  /**
+   * 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.
+   */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/**
+ * The Standard Schema interface.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /**
+   * The Standard Schema properties.
+   */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /**
+   * The Standard Schema properties interface.
+   */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /**
+     * Validates unknown input values.
+     */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /**
+   * The result interface of the validate function.
+   */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /**
+   * The result interface if validation succeeds.
+   */
+  interface SuccessResult<Output> {
+    /**
+     * The typed output value.
+     */
+    readonly value: Output;
+    /**
+     * A falsy value for `issues` indicates success.
+     */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /**
+     * Explicit support for additional vendor-specific parameters, if needed.
+     */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /**
+   * The result interface if validation fails.
+   */
+  interface FailureResult {
+    /**
+     * The issues of failed validation.
+     */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /**
+   * The issue interface of the failure output.
+   */
+  interface Issue {
+    /**
+     * The error message of the issue.
+     */
+    readonly message: string;
+    /**
+     * The path of the issue, if any.
+     */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /**
+   * The path segment interface of the issue.
+   */
+  interface PathSegment {
+    /**
+     * The key representing a path segment.
+     */
+    readonly key: PropertyKey;
+  }
+  /**
+   * The Standard types interface.
+   */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /**
+   * Infers the input type of a Standard.
+   */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /**
+   * Infers the output type of a Standard.
+   */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+} //#endregion
+//#region src/coercion/environment.d.ts
+/**
+ * Prepare an environment record by optionally stripping empty strings and applying coercion.
+ *
+ * @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
+ */
+//#endregion
+//#region src/core.d.ts
+/**
+ * Machine-readable classification codes for environment validation issues.
+ */
+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
+   */
+  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
+   */
+  meta?: EnvIssueMeta;
+};
+/**
+ * Format a list of normalized environment issues into a single styled string.
+ *
+ * @param issues - The array of normalized issues to format
+ * @returns The formatted and styled error report string
+ */
+declare function formatIssues(issues: EnvIssue[]): string;
+/**
+ * Error thrown when environment variable validation fails.
+ *
+ * This error extends the native `Error` class and provides formatted error messages
+ * that clearly indicate which environment variables are invalid and why.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const env = arkenv({
+ *     PORT: 'number.port',
+ *     HOST: 'string.host',
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ArkEnvError) {
+ *     console.error('Environment validation failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class ArkEnvError extends Error {
+  /**
+   * The list of normalized issues that caused the validation failure
+   */
+  readonly issues: EnvIssue[];
+  constructor(issues: EnvIssue[], message?: string);
+}
+/**
+ * Result of a non-throwing arkenv parse operation.
+ */
+type SafeArkEnvResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  issues: readonly EnvIssue[];
+}; //#endregion
+//#region src/guards.d.ts
+/**
+ * Throws if the given value is a string (ArkType DSL) in standard mode.
+ * @internal
+ */
+//#endregion
+//#region src/parse-standard.d.ts
+/**
+ * Configuration options for {@link parseStandard}.
+ */
+type ParseStandardConfig = {
+  /**
+   * The environment variables to parse. Defaults to `process.env`.
+   *
+   * All values must be strings (or `undefined`) to match `process.env` semantics.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Control how ArkEnv handles environment variables that are not defined in your schema.
+   *
+   * Defaults to `'delete'` so the output object only contains keys you've declared.
+   *
+   * - `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"
+   */
+  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 prefers validators that expose Standard JSON Schema on the value
+   * itself (e.g. Zod). For converters that live outside the schema (e.g. Valibot
+   * via `@valibot/to-json-schema`, Zod Mini via `z.toJSONSchema`, or Zod v3 via
+   * `zod-to-json-schema`), pass {@link toJsonSchema}.
+   *
+   * @see https://standard-schema.dev
+   * @default true
+   */
+  coerce?: boolean;
+  /**
+   * Optional fallback that converts a Standard Schema validator to JSON Schema
+   * for ArkEnv pre-coercion when a key has no Standard JSON Schema on the value.
+   *
+   * Called per key only in that case. Not called when omitted, when `coerce` is
+   * `false`, or when JSON Schema was already read from the value.
+   *
+   * - Return a plain object to use as that key's JSON Schema.
+   * - Return `undefined` to skip coercion for that key only.
+   * - Throwing or returning a non-plain object fails the parse with
+   *   {@link ArkEnvError} for that key (`INVALID_SCHEMA`).
+   *
+   * Typed as {@link StandardSchemaV1}. Host converters (Valibot, Zod Mini,
+   * Zod v3 via `zod-to-json-schema`) do not accept that type — assert at the
+   * converter call (`as v.GenericSchema`, `as z.ZodMiniType`,
+   * `as z.ZodTypeAny`). Same assertion for a single-library map and a hybrid
+   * with classic Zod (Zod never reaches this callback at runtime).
+   *
+   * @example Valibot wiring
+   * ```ts
+   * import { toJsonSchema } from "@valibot/to-json-schema";
+   * import * as v from "valibot";
+   *
+   * arkenv(
+   *   { PORT: v.number() },
+   *   {
+   *     toJsonSchema: (schema) =>
+   *       toJsonSchema(schema as v.GenericSchema, {
+   *         typeMode: "input",
+   *         target: "draft-07",
+   *       }),
+   *   },
+   * );
+   * ```
+   *
+   * @example Zod v3 wiring
+   * ```ts
+   * import { z } from "zod/v3";
+   * import { zodToJsonSchema } from "zod-to-json-schema";
+   *
+   * arkenv(
+   *   { PORT: z.number() },
+   *   {
+   *     toJsonSchema: (schema) =>
+   *       zodToJsonSchema(schema as z.ZodTypeAny, {
+   *         $refStrategy: "none",
+   *       }),
+   *   },
+   * );
+   * ```
+   */
+  toJsonSchema?: (schema: StandardSchemaV1) => object | undefined;
+  /**
+   * The format to use for array parsing when coercion is enabled.
+   *
+   * - `comma` (default): Strings are split by comma and trimmed.
+   * - `json`: Strings are parsed as JSON.
+   *
+   * @default "comma"
+   */
+  arrayFormat?: "comma" | "json";
+  /**
+   * Whether to treat empty strings (`""`) as `undefined` before validation.
+   *
+   * When enabled, an environment variable set to an empty value (e.g. `PORT=`)
+   * will be treated as if it were missing, allowing defaults to apply and
+   * preventing validation errors for numeric or boolean types.
+   *
+   * @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;
+};
+/**
+ * Parse and validate environment variables using Standard Schema 1.0 validators.
+ *
+ * @param def An object mapping environment variable keys to Standard Schema 1.0 validators
+ * @param config Parsing options, including environment source, undeclared key handling, and coercion config
+ * @returns The parsed and validated environment variables
+ * @throws An ArkEnvError if validation fails
+ */
+//#endregion
+//#region src/schema.d.ts
+/**
+ * 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
+ */
+declare function getSchemaKeys(schema: any): string[]; //#endregion
+//#region src/schema-capture.d.ts
+/**
+ * Start recording `arkenv()` schema arguments instead of validating the environment.
+ *
+ * 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 src/index.d.ts
+/**
+ * Configuration options for `arkenv` from `@arkenv/standard`.
+ */
+type StandardEnvConfig = ParseStandardConfig;
+type StandardEnvOutput<T extends Record<string, StandardSchemaV1$1>> = { [K in keyof T]: StandardSchemaV1$1.InferOutput<T[K]> };
+/**
+ * Parse and validate environment variables using Standard Schema 1.0 validators (e.g. Zod, Valibot).
+ *
+ * This entry is ArkType-free - ArkType is never imported, even transitively.
+ * Use this when your project must not depend on ArkType.
+ *
+ * @param def An object mapping variable names to Standard Schema validators
+ * @param config Optional configuration
+ * @returns The validated environment variables, a SafeArkEnvResult if `{ safe: true }` is configured, or a value-less stub when schema capture is active
+ * @throws An {@link ArkEnvError} if validation fails and `safe` is not enabled
+ *
+ * @example
+ * ```ts
+ * import arkenv from "@arkenv/standard";
+ * import * as z from "zod";
+ *
+ * const env = arkenv({
+ *   PORT: z.number(),
+ *   HOST: z.string(),
+ * });
+ * ```
+ */
+declare function arkenv<const T extends Record<string, StandardSchemaV1$1>, const Safe extends boolean | undefined = undefined>(def: T, config?: Omit<StandardEnvConfig, "safe"> & {
+  safe?: Safe;
+}): [Safe] extends [true] ? SafeArkEnvResult<StandardEnvOutput<T>> : StandardEnvOutput<T>;
+//#endregion
+export { SafeArkEnvResult as a, EnvIssue as i, arkenv as n, formatIssues as o, ArkEnvError as r, getSchemaKeys as s, StandardEnvConfig as t };