Coercion through preprocessing PoC

apps/playgrounds/bun-react/bin/build.ts

@@ -3,7 +3,6 @@ import arkenv from "@arkenv/bun-plugin";
 const result = await Bun.build({
 	entrypoints: ["./src/index.html"],
 	outdir: "./dist",
-	sourcemap: true,
 	target: "browser",
 	minify: true,
 	plugins: [arkenv],

apps/playgrounds/node/index.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 
 const env = arkenv({
 	HOST: "string.host",
+	MY_STRING_AS_NUMBER: type("string").pipe((value) => Number(value)),
 	PORT: "number.port",
 	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
 	ALLOWED_ORIGINS: type("string[]").default(() => []),
@@ -24,6 +25,7 @@ console.log({
 	nodeEnv,
 	allowedOrigins,
 	debug,
+	myString: env.MY_STRING_AS_NUMBER,
 	zedEnv,
 });
 

examples/basic/index.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 
 const env = arkenv({
 	HOST: "string.host",
+	MY_STRING_AS_NUMBER: type("string").pipe((value) => Number(value)),
 	PORT: "number.port",
 	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
 	ALLOWED_ORIGINS: type("string[]").default(() => []),
@@ -24,6 +25,7 @@ console.log({
 	nodeEnv,
 	allowedOrigins,
 	debug,
+	myString: env.MY_STRING_AS_NUMBER,
 	zedEnv,
 });
 

examples/with-bun-react/bin/build.ts

@@ -3,7 +3,6 @@ import arkenv from "@arkenv/bun-plugin";
 const result = await Bun.build({
 	entrypoints: ["./src/index.html"],
 	outdir: "./dist",
-	sourcemap: true,
 	target: "browser",
 	minify: true,
 	plugins: [arkenv],

openspec/changes/add-coercion/design.md

@@ -0,0 +1,66 @@
+# Design: Coercion
+
+## Architecture
+The coercion logic will be implemented as a preprocessing step within the `createEnv` function.
+
+### Flow
+1.  **Input**: `createEnv` receives a schema definition (`def`) and an environment object (`env`).
+2.  **Inspection**: We inspect `def` to identify keys that expect primitive types (number, boolean) but will receive strings from `env`.
+    *   This inspection primarily targets schema definitions provided as plain objects with string values (e.g., `{ PORT: "number" }`).
+    *   Complex ArkType definitions (already compiled types) may be skipped or require advanced introspection (out of scope for initial implementation).
+3.  **Coercion**:
+    *   For each identified key, we check the corresponding value in `env`.
+    *   If the target type is `number` (or subtypes like `number.port`, `number.epoch`), we attempt to convert the string to a number using `Number()` or `parseFloat()`.
+    *   If the target type is `boolean`, we convert "true" to `true` and "false" to `false`.
+4.  **Validation**: The modified `env` object (with coerced values) is passed to the ArkType schema for validation.
+
+## Decisions
+
+### Decision: Use Preprocessing for Coercion
+We decided to implement coercion as a preprocessing step that runs *before* ArkType validation, rather than using ArkType's native "morphs" or scope-level overrides.
+
+**Rationale:**
+1.  **Scope Limitations**: As confirmed by the ArkType creator, there is no mechanism to apply a morph to an entire scope (e.g., "all numbers"). We would have to manually override `number` and every subtype (`number.port`, `number.epoch`, etc.), which is brittle and unscalable.
+2.  **Separation of Concerns**: Coercion (parsing a string into a primitive) is distinct from Validation (checking if that primitive meets criteria). Keeping coercion separate allows `arkenv` to handle the "environment variable boundary" explicitly, ensuring that `number` in the schema always validates a real JavaScript number.
+3.  **Complexity**: Implementing type-level mapping for global coercion would introduce significant complexity to the types, whereas a runtime preprocessor is straightforward and easier to maintain.
+
+**Alternatives Considered:**
+*   **ArkType Morphs**: We considered using `type("string").pipe(...)` or overriding keywords in the scope. This was rejected because it requires manual per-type configuration or complex scope manipulation that doesn't propagate to sub-keywords.
+*   **Manual Parsing**: Continuing with the current state where users manually pipe string types. This was rejected as it degrades developer experience.
+
+## Risks / Trade-offs
+*   **String Definitions**: This approach relies on inspecting the schema definition. It works best when users provide string definitions (e.g., `{ PORT: "number" }`). If a user provides a pre-compiled `type("number")`, we cannot easily inspect it to apply coercion, meaning those values might remain strings and fail validation. We will document this limitation.
+
+## Implementation Details
+
+### `coerce` Utility
+We will create a utility function `coerce(def: Record<string, unknown>, env: Record<string, string | undefined>)` that returns a new environment object.
+
+```typescript
+function coerce(def: Record<string, unknown>, env: Record<string, string | undefined>) {
+  const coerced = { ...env };
+  for (const key in def) {
+    const typeDef = def[key];
+    if (typeof typeDef === "string") {
+      if (typeDef.startsWith("number")) {
+        // Coerce to number
+      } else if (typeDef === "boolean") {
+        // Coerce to boolean
+      }
+    }
+  }
+  return coerced;
+}
+```
+
+### Integration
+In `createEnv`:
+
+```typescript
+export function createEnv(def, env = process.env) {
+  // ...
+  const coercedEnv = isPlainObject(def) ? coerce(def, env) : env;
+  const validatedEnv = schema(coercedEnv);
+  // ...
+}
+```

openspec/changes/add-coercion/proposal.md

@@ -0,0 +1,28 @@
+# Coercion
+
+## Problem
+Environment variables are always strings at runtime, but users want to treat them as typed primitives without manual conversion.
+
+**Current state:**
+```typescript
+// Manual conversion required
+const env = arkenv({
+  PORT: type("string").pipe(str => Number.parseInt(str, 10)),
+  DEBUG: type("string").pipe(str => str === "true")
+});
+```
+
+**Desired state:**
+```typescript
+// Coercion
+const env = arkenv({
+  PORT: "number",           // "3000" → 3000
+  DEBUG: "boolean",        // "true" → true  
+  TIMESTAMP: "number.epoch" // "1640995200000" → 1640995200000
+});
+```
+
+## Solution
+Implement an automatic coercion layer in `arkenv` that runs before ArkType validation. This layer will inspect the provided schema definition and, where possible, convert string environment variables into their target primitive types (number, boolean) so that ArkType can validate them as such.
+
+This approach allows `arkenv` to support "native" feeling environment variables while leveraging ArkType's powerful validation for the final values.

openspec/changes/add-coercion/specs/coercion/spec.md

@@ -0,0 +1,42 @@
+# Spec: Coercion
+
+## ADDED Requirements
+
+### Requirement: Coerce numeric strings to numbers
+The system MUST coerce environment variable strings to numbers when the schema definition specifies `number` or a `number.*` subtype.
+
+#### Scenario: Basic number coercion
+Given a schema `{ PORT: "number" }`
+And an environment `{ PORT: "3000" }`
+When `arkenv` parses the environment
+Then the result should contain `PORT` as the number `3000`
+
+#### Scenario: Number subtype coercion
+Given a schema `{ TIMESTAMP: "number.epoch" }`
+And an environment `{ TIMESTAMP: "1640995200000" }`
+When `arkenv` parses the environment
+Then the result should contain `TIMESTAMP` as the number `1640995200000`
+
+### Requirement: Coerce boolean strings to booleans
+The system MUST coerce environment variable strings "true" and "false" to boolean values when the schema definition specifies `boolean`.
+
+#### Scenario: Boolean true coercion
+Given a schema `{ DEBUG: "boolean" }`
+And an environment `{ DEBUG: "true" }`
+When `arkenv` parses the environment
+Then the result should contain `DEBUG` as the boolean `true`
+
+#### Scenario: Boolean false coercion
+Given a schema `{ DEBUG: "boolean" }`
+And an environment `{ DEBUG: "false" }`
+When `arkenv` parses the environment
+Then the result should contain `DEBUG` as the boolean `false`
+
+### Requirement: Pass through non-coercible values
+The system MUST pass through values unchanged if they do not match a coercible type definition or if coercion fails (letting ArkType handle the validation error).
+
+#### Scenario: String pass-through
+Given a schema `{ API_KEY: "string" }`
+And an environment `{ API_KEY: "12345" }`
+When `arkenv` parses the environment
+Then the result should contain `API_KEY` as the string `"12345"`