Coercion

Traditionally, environment variables are always strings by default. ArkEnv coerces these strings into their target types based on your schema, so you only have to think about the types you want.

Numbers

Any field defined as a number or a numeric subtype (like number.integer or number.port) will be automatically parsed.

// All are numbers! (hover `env` to see)
const env = arkenv({
  PORT: "number.port",
  RETRY_COUNT: "number.integer = 3",
  AGE: "0 <= number.integer <= 120"
});

Booleans

The boolean type handles strings like "true" and "false".

// DEBUG is true if process.env.DEBUG is "true"
const env = arkenv({
  DEBUG: "boolean = false"
});

Arrays

ArkEnv can parse strings into arrays. By default, it splits the string by commas and trims each value.

const env = arkenv({
  TAGS: "string[]",
  PORTS: "number[]"
}, {
  env: {
    TAGS: "web, app, api",
    PORTS: "3000, 8080"
  }
});

Array format

If your environment variables use JSON format instead of commas, you can change the arrayFormat option:

const env = arkenv(
  { TAGS: "string[]" },
  {
    arrayFormat: "json",
    env: { TAGS: '["web", "app"]' }
  }
);

Objects

ArkEnv can parse JSON strings into objects. This is useful for grouping related configuration into a single environment variable.

import arkenv from "arkenv";

const env = arkenv({
  DATABASE: {
    HOST: "string",
    PORT: "number"
  }
}, {
  env: {
    DATABASE: '{"HOST": "localhost", "PORT": "5432"}'
  }
});

Coercion works recursively: even variables inside a JSON object are coerced to their correct types (like PORT becoming a number above).

How it works

ArkEnv introspects your schema to identify fields that should be numbers, booleans, and other non-string types you define. When you call createEnv() (or arkenv()), it pre-processes your environment variables to perform these conversions before validation.

Performance

Coercion is highly optimized: ArkEnv performs a one-time introspection of your schema to map out exactly which paths need conversion. At runtime, it only touches the variables that actually need coercion, keeping your startup time virtually identical to manually parsing process.env.

Disabling coercion

You can opt-out of this behavior by setting coerce to false.

// ⚠️ This will throw an error!
// "3000" (string) is not a number.
const env = arkenv(
  {
    PORT: "number.port",
  },
  {
    coerce: false, // < -- Disable coercion
    env: {
      PORT: "3000",
    },
  }
);

When coercion is disabled, environment variables are validated exactly as they are. Since environment variables are strings, this means validation will fail for number or boolean fields unless you morph them yourself.