Array parsing

[yamcodes]

Add support for parsing arrays in environment variables.

Bonus points if we can control the "parsing type" (for lack of a better term): comma separated, space and comma separated, JSON stringified notation, etc.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Feature Request: Support Boolean Type Conversion for ArkEnv #87
• Coercion (string→number, string→boolean, etc.)  #228

👤 Suggested Assignees

• Cyb3rN8
• yamcodes

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add support for parsing environment variable strings into arrays with multiple parsing strategies. The primary use case is parsing comma-separated values (e.g., "item1,item2,item3") into typed arrays, with additional support for JSON-formatted arrays and other delimiters.

Observations

Codebase Summary

The arkenv package is built on ArkType and follows a modular architecture. Custom environment variable parsers are defined as "keywords" in packages/internal/keywords, organized into a type scope in packages/internal/types, and exposed through the main packages/arkenv package. The existing pattern includes custom types like string.host, number.port, and boolean that transform and validate string inputs. Array syntax ("string[]", "number[]") currently validates array objects but doesn't parse strings.

Assumptions

Assumption 1: Default array parsing strategy

Options Considered:

• Default comma-separated parsing for all array types when string input is provided
• Require explicit opt-in via special syntax (e.g., "string.array" vs "string[]"))

Chosen Option: Create explicit array parsing types using the module pattern ("string.array", "number.array") rather than modifying native array syntax.

Rationale: This provides clarity about when string-to-array parsing happens, maintains backwards compatibility with existing array validation, and follows the established pattern of explicit custom types like string.host and number.port. Users who want arrays to parse from strings use "string.array", while those validating pre-formed arrays continue using "string[]".

Assumption 2: Supported parsing formats

Options Considered:

• Only comma-separated (simplest, covers majority of use cases)
• Comma-separated + JSON parsing (covers both simple and complex cases)
• Comma-separated + JSON + space-separated + custom delimiter regex (maximum flexibility)

Chosen Option: Implement comma-separated parsing as the default and JSON parsing as a variant ("string.array.json").

Rationale: This covers the two most common environment variable patterns: simple comma-separated lists and complex JSON-serialized arrays. Other formats can be added later if demand emerges, or users can leverage the existing .pipe() transformation pattern for custom delimiters. This keeps the initial implementation focused while providing the flexibility mentioned in the ticket's "bonus points" section.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Array Parsing Keywords

Implement the core array parsing logic as custom ArkType keywords following the established transformation pattern used by existing keywords like port and boolean.

Task 1: Implement comma-separated array parsers

Create array parsing keywords for primitive types (string, number, boolean) in packages/internal/keywords/src/index.ts.

• Add string.array keyword that accepts string input (comma-separated) or array input (validated as-is)
• Use ArkType's union syntax "string | string[]" as input type, then transform via "=>" operator
• Split on comma, trim whitespace from each element, return string array
• Add number.array keyword that parses comma-separated numbers, validates each element is numeric, returns number array
• Add boolean.array keyword that parses comma-separated boolean values ("true", "false"), with appropriate error handling for invalid values
• Handle edge cases: empty strings (return empty array), single values (return array with one element), whitespace trimming

Task 2: Implement JSON array parser

Create a JSON-based array parser for complex scenarios in packages/internal/keywords/src/index.ts.

• Add string.array.json keyword that accepts string input and parses via JSON.parse()
• Validate the parsed result is an array using Array.isArray(), return error if not
• Catch JSON parsing errors and provide clear error messages via ArkType's context (ctx.mustBe())
• Support nested type validation by accepting the parsed JSON array and validating element types
• Consider adding similar .json variants for typed arrays (number.array.json, etc.) if type validation after parsing is needed

🤖 Prompt for AI agents

Implement array parsing keywords in `packages/internal/keywords/src/index.ts`
following the established transformation pattern.

Create comma-separated array parsers:
- Add `string.array` keyword accepting `"string | string[]"` input, transform by
splitting on comma and trimming whitespace
- Add `number.array` keyword parsing comma-separated numbers with validation
- Add `boolean.array` keyword parsing comma-separated boolean values with error
handling
- Handle edge cases: empty strings, single values, whitespace

Create JSON array parser:
- Add `string.array.json` keyword parsing via `JSON.parse()`
- Validate result with `Array.isArray()` and provide clear error messages
- Support nested type validation for array elements

Phase 2: Integrate into Type System

Integrate the new array parsing keywords into arkenv's type scope and make them available to users through the standard API.

Task 1: Add array types to scope

Update packages/internal/types/src/schema.ts to include the new array keywords in the module system.

• Add array parsing types to the scope definition using ArkType's module syntax
• Organize under appropriate modules: string.array, number.array, boolean.array, string.array.json
• Ensure type inference works correctly with type.infer for the new array types
• Export the extended scope so array types are available throughout arkenv

Task 2: Update TypeScript type definitions

Ensure TypeScript types correctly reflect the new array parsing capabilities in packages/internal/types/src/infer-type.ts and related type utilities.

• Verify that type.infer<"string.array"> correctly infers string[]
• Ensure type.infer<"number.array"> correctly infers number[]
• Validate that the union input type (string | T[]) doesn't leak into the inferred output type
• Test that nested array types and JSON arrays have correct inference

🤖 Prompt for AI agents

Integrate array parsing keywords into arkenv's type system.

Update `packages/internal/types/src/schema.ts`:
- Add array parsing types to scope using ArkType module syntax
- Organize as `string.array`, `number.array`, `boolean.array`,
`string.array.json`
- Ensure type inference works with `type.infer`
- Export extended scope

Update TypeScript definitions in `packages/internal/types/src/infer-type.ts`:
- Verify `type.infer<"string.array">` infers `string[]`
- Verify `type.infer<"number.array">` infers `number[]`
- Ensure union input types don't leak into output types
- Validate inference for nested and JSON arrays

Phase 3: Testing and Documentation

Add comprehensive tests for the new array parsing functionality and update documentation to demonstrate the new capabilities.

Task 1: Add unit and integration tests

Create tests in packages/arkenv/src/ covering array parsing behavior and edge cases.

• Add tests in a new array-parsing.integration.test.ts file demonstrating comma-separated parsing for each type
• Test JSON array parsing with valid and invalid JSON inputs
• Cover edge cases: empty strings, single values, whitespace handling, invalid element types
• Test that both string inputs and array inputs work correctly (union behavior)
• Update the existing TODO comment in array-defaults.integration.test.ts with working examples
• Add tests mixing array parsing with defaults (e.g., type("string.array").default(() => []))

Task 2: Update examples and documentation

Update examples to demonstrate array parsing and document the new types in README files.

• Add array parsing examples to examples/basic/index.ts showing simple comma-separated parsing
• Update examples/with-standard-schema/index.ts to compare ArkType's built-in array parsing with Zod's transform approach
• Add new example in examples/ directory demonstrating various array parsing strategies (comma, JSON, mixed types)
• Update the main README.md to document the new string.array, number.array, and .json types
• Add code examples showing how to migrate from .pipe() transforms to built-in array parsing

🤖 Prompt for AI agents

Add comprehensive testing and documentation for array parsing functionality.

Create tests in `packages/arkenv/src/`:
- Add `array-parsing.integration.test.ts` with comma-separated parsing tests for
all types
- Test JSON array parsing with valid/invalid inputs
- Cover edge cases: empty strings, single values, whitespace, invalid types
- Test union behavior with string and array inputs
- Update TODO in `array-defaults.integration.test.ts`
- Test array parsing with defaults

Update documentation:
- Add array parsing examples to `examples/basic/index.ts`
- Update `examples/with-standard-schema/index.ts` comparing with Zod
- Create new example demonstrating various parsing strategies
- Document new types in main `README.md`
- Add migration examples from `.pipe()` transforms

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement array parsing keywords in `packages/internal/keywords/src/index.ts`
following the established transformation pattern.

Create comma-separated array parsers:
- Add `string.array` keyword accepting `"string | string[]"` input, transform by
splitting on comma and trimming whitespace
- Add `number.array` keyword parsing comma-separated numbers with validation
- Add `boolean.array` keyword parsing comma-separated boolean values with error
handling
- Handle edge cases: empty strings, single values, whitespace

Create JSON array parser:
- Add `string.array.json` keyword parsing via `JSON.parse()`
- Validate result with `Array.isArray()` and provide clear error messages
- Support nested type validation for array elements
===============================================================================

Task: 2

Integrate array parsing keywords into arkenv's type system.

Update `packages/internal/types/src/schema.ts`:
- Add array parsing types to scope using ArkType module syntax
- Organize as `string.array`, `number.array`, `boolean.array`,
`string.array.json`
- Ensure type inference works with `type.infer`
- Export extended scope

Update TypeScript definitions in `packages/internal/types/src/infer-type.ts`:
- Verify `type.infer<"string.array">` infers `string[]`
- Verify `type.infer<"number.array">` infers `number[]`
- Ensure union input types don't leak into output types
- Validate inference for nested and JSON arrays
===============================================================================

Task: 3

Add comprehensive testing and documentation for array parsing functionality.

Create tests in `packages/arkenv/src/`:
- Add `array-parsing.integration.test.ts` with comma-separated parsing tests for
all types
- Test JSON array parsing with valid/invalid inputs
- Cover edge cases: empty strings, single values, whitespace, invalid types
- Test union behavior with string and array inputs
- Update TODO in `array-defaults.integration.test.ts`
- Test array parsing with defaults

Update documentation:
- Add array parsing examples to `examples/basic/index.ts`
- Update `examples/with-standard-schema/index.ts` comparing with Zod
- Create new example demonstrating various parsing strategies
- Document new types in main `README.md`
- Add migration examples from `.pipe()` transforms

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!