Object parsing

[yamcodes]

Add the ability to define objects within environment variables, and for ArkEnv to be able to parse/coerce them into JavaScript objects.

[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

• Coercion (string→number, string→boolean, etc.)  #228
• Array parsing #574
• Support type definitions created with type() in addition to raw schema objects #381
• Feature Request: Support Boolean Type Conversion for ArkEnv #87
• feature request: support for default value #426

👤 Suggested Assignees

• yamcodes
• Cyb3rN8
• nurazon59

---

🧪 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 JSON-encoded objects from environment variables, allowing users to store structured data in environment variables and have ArkEnv automatically parse and validate them as JavaScript objects.

Observations

Codebase Summary

ArkEnv is a lightweight, type-safe environment variable parser built as a thin wrapper around ArkType. The architecture consists of a custom scope package (@repo/scope) that extends ArkType's built-in types with custom validators like string.host and number.port, which are defined in the @repo/keywords package. The main entry point (create-env.ts) delegates validation to ArkType's type system, which automatically handles type coercion. Custom types follow a consistent pattern: they are created using ArkType's transformation operator in @repo/keywords, then registered in the appropriate module (string, number, etc.) within @repo/scope.

Assumptions

Assumption 1: Which ArkType JSON parsing capabilities should be exposed to users?

Options Considered:

• Option A: Register string.json.parse as a simple keyword (e.g., string.json) that parses any valid JSON without validation
• Option B: Create a custom implementation that mirrors string.json.parse behavior within arkenv's custom keywords

Chosen Option: Option A: Register string.json.parse as a simple keyword (e.g., string.json) that parses any valid JSON without validation

Rationale: Register ArkType's built-in string.json.parse as string.json in the arkenv scope. This approach leverages ArkType's battle-tested implementation, aligns with the pattern of exposing ArkType's built-in types (like string.host), and maintains minimal code complexity. Users who need schema validation can combine it with .to() as shown in ArkType's documentation, which is already supported through arkenv's type() export.

Assumption 2: Should schema validation for parsed JSON be included in the basic implementation?

Options Considered:

• Option A: Basic implementation only - expose string.json for parsing any valid JSON, let users combine with .to() for validation
• Option B: Create a convenience wrapper that combines parsing and validation in a single type definition

Chosen Option: Option A: Basic implementation only - expose string.json for parsing any valid JSON, let users combine with .to() for validation

Rationale: Provide basic JSON parsing via string.json in the initial implementation. Users can already achieve schema validation using type("string.json").to({ schema }) through ArkType's existing .to() API, which arkenv already exposes. This keeps the implementation simple, avoids creating new abstractions, and follows the principle of building only what's needed. A convenience wrapper can be added later if user feedback indicates it would significantly improve ergonomics.

💡 User Tips

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

Implementation Steps

Phase 1: Expose ArkType's JSON Parsing Type

Enable JSON object parsing by registering ArkType's built-in string.json.parse type in arkenv's custom scope, making it available to users as string.json.

Register the JSON parsing type in the scope

Expose ArkType's string.json.parse as a string module keyword in the arkenv scope.

• Import type from arktype in packages/internal/scope/src/index.ts
• Create a reference to string.json.parse: const json = type("string.json.parse")
• Add json to the string module in the scope definition alongside host
• This makes string.json available as a type string in environment schemas (e.g., DATABASE_CONFIG: "string.json")

🤖 Prompt for AI agents

Register ArkType's built-in JSON parsing capability in arkenv's scope to enable
parsing JSON-encoded environment variables.

In `packages/internal/scope/src/index.ts`:
- Import `type` from arktype
- Create a reference to `string.json.parse`: `const json =
type("string.json.parse")`
- Add `json` to the string module in the scope definition alongside existing
types like `host`
- This exposes `string.json` as a usable type in environment schemas

Phase 2: Documentation and Testing

Validate the JSON parsing functionality works correctly and provide examples showing users how to use it.

Task 1: Add comprehensive tests for JSON parsing

Create test coverage following the existing testing patterns for type coercion and error handling.

• Add tests in packages/arkenv/src/type.test.ts for basic JSON parsing:

  • Valid JSON object string coercion (e.g., '{"key": "value"}' → {key: "value"})
  • Valid JSON array string coercion
  • Valid JSON primitive values
  • Invalid JSON string errors (malformed JSON)
  • Edge cases: empty objects, nested objects, null values

• Add integration tests in packages/arkenv/src/custom-types.integration.test.ts:

  • End-to-end validation through createEnv() with string.json in schema
  • Environment variable stubbing with JSON strings
  • Error propagation for invalid JSON in environment variables

Task 2: Create example demonstrating JSON object parsing

Add a practical example showing users how to parse JSON from environment variables.

• Create examples/with-json-config/ directory with basic example
• Demonstrate basic usage: DATABASE_CONFIG: "string.json" parsing a JSON object
• Show schema validation pattern using .to(): type("string.json").to({ host: "string", port: "number" })
• Include error handling example with malformed JSON
• Add README explaining the feature and common use cases (database configs, feature flags, API configurations)

Task 3: Update documentation

Document the new JSON parsing capability in the main package README.

• Add "Object/JSON Parsing" section to packages/arkenv/README.md after the existing type examples
• Show basic syntax: CONFIG: "string.json"
• Include schema validation example using type("string.json").to(schema)
• Mention common use cases: database configurations, complex feature flags, API endpoint configurations

🤖 Prompt for AI agents

Test and document the JSON parsing functionality to ensure it works correctly
and users understand how to use it.

Testing:
- Add unit tests in `packages/arkenv/src/type.test.ts` covering valid JSON
parsing (objects, arrays, primitives), invalid JSON errors, and edge cases
- Add integration tests in
`packages/arkenv/src/custom-types.integration.test.ts` for end-to-end validation
through `createEnv()`

Examples:
- Create `examples/with-json-config/` with basic usage and schema validation
patterns using `.to()`
- Show error handling for malformed JSON

Documentation:
- Add "Object/JSON Parsing" section to `packages/arkenv/README.md`
- Document basic syntax and schema validation patterns
- List common use cases

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Register ArkType's built-in JSON parsing capability in arkenv's scope to enable
parsing JSON-encoded environment variables.

In `packages/internal/scope/src/index.ts`:
- Import `type` from arktype
- Create a reference to `string.json.parse`: `const json =
type("string.json.parse")`
- Add `json` to the string module in the scope definition alongside existing
types like `host`
- This exposes `string.json` as a usable type in environment schemas
===============================================================================

Task: 2

Test and document the JSON parsing functionality to ensure it works correctly
and users understand how to use it.

Testing:
- Add unit tests in `packages/arkenv/src/type.test.ts` covering valid JSON
parsing (objects, arrays, primitives), invalid JSON errors, and edge cases
- Add integration tests in
`packages/arkenv/src/custom-types.integration.test.ts` for end-to-end validation
through `createEnv()`

Examples:
- Create `examples/with-json-config/` with basic usage and schema validation
patterns using `.to()`
- Show error handling for malformed JSON

Documentation:
- Add "Object/JSON Parsing" section to `packages/arkenv/README.md`
- Document basic syntax and schema validation patterns
- List common use cases

💡 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!