Fix support for array defaults using type().default() syntax

[Copilot]

Fixes the issue where using type("array[]").default(() => [...]) syntax was not accepted by createEnv due to overly restrictive type constraints.

Problem

The createEnv function had a type constraint that only accepted Record<string, string | undefined>, which prevented ArkType objects with default values from being used. This meant the following syntax from the ArkType documentation didn't work:

import arkenv, { type } from "arkenv";

const Thing = arkenv({
  array: type("number.integer[]").default(() => []),
});

This would result in a TypeScript error:

Type '[Type<...>, "=", () => never[]]' is not assignable to type 'string'.

Solution

Updated the type constraint to maintain string-keyed requirement while allowing flexible value types:

Before:

export function createEnv<const T extends Record<string, string | undefined>>(
  def: EnvSchema<T>,
  // ...

After:

export function createEnv<const T extends Record<string, any>>(
  def: EnvSchema<T>,
  // ...

This approach preserves the environment variable paradigm (string keys) while supporting ArkType objects with defaults. The EnvSchema<T> type provides proper validation through ArkType's type system.

What Now Works

✅ Array defaults with type function syntax:

const env = arkenv({
  ALLOWED_ORIGINS: type("string[]").default(() => ["localhost"]),
  FEATURE_FLAGS: type("string[]").default(() => []),
  PORTS: type("number[]").default(() => [3000, 8080]),
});

✅ Complex array types:

const env = arkenv({
  numbers: type("number.integer[]").default(() => [1, 2, 3]),
});

✅ Mixed schemas with both string-based and type-based defaults work together

Backward Compatibility

All existing functionality continues to work unchanged:

• String-based schemas: "string", "number.port", etc.
• String-based defaults: "'development' | 'production' = 'development'"
• Optional variables: "API_KEY?": "string"
• Built-in validators: "string.host", "number.port"

Testing

Added comprehensive test coverage including:

• Basic array default functionality
• Integration tests showing the exact syntax from the issue now works
• Mixed schema types to ensure no regressions
• All 94 existing tests continue to pass

Documentation

Updated the quickstart guide to include examples of array defaults, helping users discover this powerful feature.

Changeset

Added changeset for minor version bump reflecting the new functionality.

Fixes #163

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Provide a clear example of a default variable for an array</issue_title>
<issue_description>This doesn't work in ArkEnv (and ArkType):

Based on the docs we should use pipes:

https://arktype.io/docs/objects#properties-defaultable

But this is not clearly possible with ArkEnv (See #162)

Also, based on this, you would expect this to work:

import arkenv, { type } from "arkenv";

const Thing = arkenv({
	array: type("number.integer[]").default(() => []),
});

Instead, we are getting:

Type '[Type<number[], { string: Submodule<{ root: string; " arkInferred": string; trim: Submodule<$ & { " arkInferred": (In: string) => To<string>; }>; normalize: Submodule<$ & { " arkInferred": (In: string) => To<...>; }>; ... 19 more ...; host: string; }>; number: Submodule<...>; }>, "=", () => never[]]' is not assignable to type 'string'.ts(2322)

I think that createEnv is defined in a way that does not allow an internal type, and the issue is probably not in the type we export since this works:

import arkenv, { type } from "arkenv";

const Thing = type({
	array: type("number.integer[]").default(() => []),
});

More specifically the signature (i/o) of the createEnv function is probably insufficient.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #163

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

---

Note

Allow array defaults using type("...[]").default(() => [...]) by loosening createEnv input types; add tests, docs, and changeset.

• Core (arkenv)
  • Update createEnv signature to accept Record<string, any> (from Record<string, string | undefined>) enabling type("...[]").default(() => [...]) schemas.
• Tests
  • Add packages/arkenv/src/array-defaults-integration.test.ts covering array defaults, complex arrays, and env overrides.
  • Extend create-env.test.ts and type.test.ts to validate array defaults using type("...[]").default(() => [...]).
• Docs
  • Update apps/www/content/docs/quickstart.mdx to import { type } and demonstrate array defaults (ALLOWED_ORIGINS, FEATURE_FLAGS).
• Changeset
  • Add .changeset/array-defaults-support.md for a minor release.

^{Written by Cursor Bugbot for commit 77d51fb. This will update automatically on new commits. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
arkenv	Ready	Preview	Comment	Oct 6, 2025 2:27pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 3ff8f4c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
arkenv	Minor
@arkenv/vite-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[yamcodes]

@copilot Since this is an environment variable valiaditor, we should still constrain it to a string-keyed record, although your note that the type is too restrictive is taken. Maybe there is a middle ground where it's a record (string keyed, but the value can be unconstrained) or, we can just somehow "copy" the type from ArkType's type.object

Also, we need a changeset.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

---

Note

Free review on us!

CodeRabbit is offering free reviews until Wed Oct 08 2025 to showcase some of the refinements we've made.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/arkenv@199

npm i https://pkg.pr.new/@arkenv/vite-plugin@199

commit: 8db3377

[Copilot]

@copilot Since this is an environment variable valiaditor, we should still constrain it to a string-keyed record, although your note that the type is too restrictive is taken. Maybe there is a middle ...

Updated the constraint to Record<string, any> to maintain string-keyed requirement while allowing flexible value types. This preserves the environment variable constraint (string keys) while supporting ArkType objects with defaults. Also added the changeset as requested.

The fix is in commit 80a0b2e.