Coercion

.changeset/cuddly-ears-wink.md

@@ -0,0 +1,21 @@
+---
+"@arkenv/vite-plugin": minor
+---
+
+### Breaking Change: `createEnv` API Update
+
+The underlying `arkenv` package has updated its `createEnv` API. This affects users who manually call `arkenv` (or `createEnv`) within their `vite.config.ts` to Type-Safe environment variables during config loading.
+
+If you are using this pattern:
+
+```ts
+const env = arkenv(Env, loadEnv(mode, process.cwd(), ""));
+```
+
+You must update it to:
+
+```ts
+const env = arkenv(Env, { env: loadEnv(mode, process.cwd(), "") });
+```
+
+The plugin usage itself (`plugins: [arkenv(Env)]`) remains unchanged.

.changeset/cyan-loops-hear.md

@@ -0,0 +1,22 @@
+---
+"arkenv": minor
+---
+
+### Coercion
+
+Introduced **Schema-Directed Coercion**: now, environment variables defined as `number` or `boolean` in your schema are automatically parsed to their correct types.
+
+If you want to opt-out of this feature, pass `config.coerce: false` to `createEnv()` (`arkenv()`). Example:
+
+```ts
+arkenv(schema, { coerce: false });
+```
+
+To learn more about the new coercion system, read [the docs](https://arkenv.js.org/docs/arkenv/coercion).
+
+### ⚠️ Breaking Changes
+
+* **`createEnv` API**: The `createEnv` function signature has changed to support a configuration object.
+  Instead of `createEnv(schema, env)`, use `createEnv(schema, config)` where `config` includes `env` and the newly added `coerce` option (`true` by default).
+* **`boolean` keyword**: The custom `boolean` morph has been removed. Use `arktype`'s standard `boolean` instead, which will be coerced when used within `createEnv` / `arkenv`.
+* **`port` keyword**: Now a strict numeric refinement (0-65535). It no longer parses strings automatically outside of `createEnv` / `arkenv`.

.changeset/humble-lizards-judge.md

@@ -0,0 +1,9 @@
+---
+"@repo/keywords": minor
+---
+
+#### Simplify keywords for central coercion
+
+* **BREAKING**: The `boolean` keyword has been removed. Universal boolean coercion is now handled by the `arkenv` package.
+* **BREAKING**: The `port` keyword has been changed from a `string -> number` morph to a pure `number` refinement. Numeric coercion is now handled centrally.
+* Added `maybeParsedNumber` and `maybeParsedBoolean` internal morphs to support central coercion (including specific "NaN" support).

.changeset/open-spiders-tan.md

@@ -0,0 +1,8 @@
+---
+"@repo/scope": minor
+---
+
+#### Align scope with central coercion
+
+* **BREAKING**: Removed the custom `boolean` keyword from the root scope. ArkEnv now uses the standard ArkType `boolean` primitive combined with global coercion.
+* Updated `number.port` to use the new strict numeric refinement, as string parsing is now handled by global coercion.

.github/copilot-instructions.md

@@ -281,7 +281,7 @@ These examples demonstrate real-world usage and can serve as templates for new i
 - **Avoid breaking changes** to the public API without explicit approval and a major version changeset
 - **Don't modify generated files** like `pnpm-lock.yaml` directly - use `pnpm install` instead
 - **Don't skip changesets** for published packages - always run `pnpm changeset` for version bumps
-- **Avoid adding new dependencies** without considering bundle size impact (aspirational goal: <1kB gzipped, enforced limit: 2kB gzipped)
+- **Avoid adding new dependencies** without considering bundle size impact (aspirational goal: <2kB gzipped, enforced limit: 2kB gzipped)
 
 ### Security Considerations
 - Always validate user input in examples and documentation

apps/playgrounds/bun-react/src/env.ts

@@ -1,6 +1,6 @@
 import { type } from "arkenv";
 
 export default type({
-	BUN_PUBLIC_API_URL: "string",
+	BUN_PUBLIC_API_URL: "string.url",
 	BUN_PUBLIC_DEBUG: "boolean",
 });

apps/playgrounds/bun/index.ts

@@ -8,10 +8,6 @@ const env = arkenv({
 
 // Automatically validate and parse process.env
 // TypeScript knows the ✨exact✨ types!
-const host = env.HOST;
-const port = env.PORT;
-const nodeEnv = env.NODE_ENV;
-
-console.log({ host, port, nodeEnv });
+console.log({ host: env.HOST, port: env.PORT, nodeEnv: env.NODE_ENV });
 
 export default env;

apps/playgrounds/node/.env.example

@@ -1,5 +1,2 @@
 HOST=localhost
 PORT=3000
-NODE_ENV=development
-DEBUG=true
-ZED_ENV=development

apps/playgrounds/node/index.ts

@@ -1,30 +1,19 @@
-import arkenv, { type } from "arkenv";
-import * as z from "zod";
+import arkenv from "arkenv";
 
 const env = arkenv({
-	HOST: "string.host",
-	PORT: "number.port",
+	HOST: "string.ip | 'localhost'",
+	PORT: "0 <= number.integer <= 65535",
 	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
-	ALLOWED_ORIGINS: type("string[]").default(() => []),
-	DEBUG: "boolean = true",
-	ZED_ENV: z.string(),
+	DEBUGGING: "boolean = false",
 });
 
 // Automatically validate and parse process.env
 // TypeScript knows the ✨exact✨ types!
-const host = env.HOST;
-const port = env.PORT;
-const nodeEnv = env.NODE_ENV;
-const allowedOrigins = env.ALLOWED_ORIGINS;
-const debug = env.DEBUG;
-const zedEnv = env.ZED_ENV;
 console.log({
-	host,
-	port,
-	nodeEnv,
-	allowedOrigins,
-	debug,
-	zedEnv,
+	host: env.HOST,
+	port: env.PORT,
+	nodeEnv: env.NODE_ENV,
+	debugging: env.DEBUGGING,
 });
 
 export default env;

apps/playgrounds/standard-schema/index.ts

@@ -9,7 +9,7 @@ const env = arkenv({
 	DEBUG: "boolean = false",
 
 	// Zod validators (great for complex validation and transformations)
-	DATABASE_URL: z.string().url(),
+	DATABASE_URL: z.url(),
 	API_KEY: z
 		.string()
 		.min(32)
@@ -23,35 +23,24 @@ const env = arkenv({
 	ALLOWED_ORIGINS: z
 		.string()
 		.transform((str: string) => str.split(","))
-		.pipe(z.array(z.string().url())),
+		.pipe(z.array(z.url())),
 
 	// Array defaults with ArkType
 	FEATURE_FLAGS: type("string[]").default(() => []),
 });
 
 // All validators work together seamlessly with full type inference
-const host: string = env.HOST;
-const port: number = env.PORT;
-const nodeEnv: "development" | "production" | "test" = env.NODE_ENV;
-const debug: boolean = env.DEBUG;
-const databaseUrl: string = env.DATABASE_URL;
-const apiKey: string = env.API_KEY;
-const maxRetries: number = env.MAX_RETRIES;
-const timeoutMs: number = env.TIMEOUT_MS;
-const allowedOrigins: string[] = env.ALLOWED_ORIGINS;
-const featureFlags: string[] = env.FEATURE_FLAGS;
-
 console.log({
-	host,
-	port,
-	nodeEnv,
-	debug,
-	databaseUrl,
-	apiKey: `${apiKey.substring(0, 8)}...`, // Don't log full API key
-	maxRetries,
-	timeoutMs,
-	allowedOrigins,
-	featureFlags,
+	host: env.HOST,
+	port: env.PORT,
+	nodeEnv: env.NODE_ENV,
+	debug: env.DEBUG,
+	databaseUrl: env.DATABASE_URL,
+	apiKey: `${env.API_KEY.substring(0, 8)}...`, // Don't log full API key
+	maxRetries: env.MAX_RETRIES,
+	timeoutMs: env.TIMEOUT_MS,
+	allowedOrigins: env.ALLOWED_ORIGINS,
+	featureFlags: env.FEATURE_FLAGS,
 });
 
 export default env;

apps/playgrounds/vite-legacy/vite.config.ts

@@ -10,14 +10,14 @@ import tsconfigPaths from "vite-tsconfig-paths";
 // 2. Validating VITE_* variables via the plugin
 export const Env = type({
 	PORT: "number.port",
-	VITE_MY_VAR: "string",
-	VITE_MY_NUMBER: type("string").pipe((str) => Number.parseInt(str, 10)),
-	VITE_MY_BOOLEAN: type("string").pipe((str) => str === "true"),
+	VITE_MY_VAR: "unknown",
+	VITE_MY_NUMBER: "number",
+	VITE_MY_BOOLEAN: "boolean",
 });
 
 // https://vite.dev/config/
 export default defineConfig(({ mode }) => {
-	const env = arkenv(Env, loadEnv(mode, process.cwd(), ""));
+	const env = arkenv(Env, { env: loadEnv(mode, process.cwd(), "") });
 
 	console.log(`${env.VITE_MY_NUMBER} ${typeof env.VITE_MY_NUMBER}`);
 	return {

apps/playgrounds/vite/README.md

@@ -18,24 +18,24 @@ import { defineConfig, loadEnv } from "vite";
 
 // Define the schema once
 export const Env = type({
-	PORT: "number.port",              // Server-only (used in vite.config)
-	VITE_MY_VAR: "string",            // Client-exposed
-	VITE_MY_NUMBER: type("string").pipe((str) => Number.parseInt(str, 10)),
-	VITE_MY_BOOLEAN: type("string").pipe((str) => str === "true"),
+  PORT: "number.port", // Server-only (used in vite.config)
+  VITE_MY_VAR: "string", // Client-exposed
+  VITE_MY_NUMBER: "number",
+  VITE_MY_BOOLEAN: "boolean",
 });
 
 export default defineConfig(({ mode }) => {
-	// Validate server-side variables (PORT) using loadEnv
-	const env = arkenv(Env, loadEnv(mode, process.cwd(), ""));
-
-	return {
-		plugins: [
-			arkenvVitePlugin(Env), // Validates VITE_* variables
-		],
-		server: {
-			port: env.PORT, // Use validated PORT
-		},
-	};
+  // Validate server-side variables (PORT) using loadEnv
+  const env = arkenv(Env, { env: loadEnv(mode, process.cwd(), "") });
+
+  return {
+    plugins: [
+      arkenvVitePlugin(Env), // Validates VITE_* variables
+    ],
+    server: {
+      port: env.PORT, // Use validated PORT
+    },
+  };
 });
 ```
 
@@ -47,12 +47,12 @@ The playground includes type augmentation for `import.meta.env`:
 /// <reference types="vite/client" />
 
 type ImportMetaEnvAugmented =
-	import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
-		typeof import("../vite.config").Env
-	>;
+  import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
+    typeof import("../vite.config").Env
+  >;
 
 interface ViteTypeOptions {
-	strictImportMetaEnv: unknown;
+  strictImportMetaEnv: unknown;
 }
 
 interface ImportMetaEnv extends ImportMetaEnvAugmented {}
@@ -62,10 +62,10 @@ This makes `import.meta.env` fully typesafe in your React components:
 
 ```tsx title="src/app.tsx"
 // All of these are typesafe!
-const myVar = import.meta.env.VITE_MY_VAR;        // ✅ string
-const myNumber = import.meta.env.VITE_MY_NUMBER;  // ✅ number
+const myVar = import.meta.env.VITE_MY_VAR; // ✅ string
+const myNumber = import.meta.env.VITE_MY_NUMBER; // ✅ number
 const myBoolean = import.meta.env.VITE_MY_BOOLEAN; // ✅ boolean
-const port = import.meta.env.PORT;                // ❌ Error: PORT is server-only
+const port = import.meta.env.PORT; // ❌ Error: PORT is server-only
 ```
 
 ## Environment Variables
@@ -80,6 +80,7 @@ VITE_MY_BOOLEAN=true
 ```
 
 The plugin automatically:
+
 - Validates all variables at build-time
 - Filters to only expose `VITE_*` variables to the client
 - Excludes server-only variables (like `PORT`) from the client bundle

apps/playgrounds/vite/vite.config.ts

@@ -10,14 +10,14 @@ import tsconfigPaths from "vite-tsconfig-paths";
 // 2. Validating VITE_* variables via the plugin
 export const Env = type({
 	PORT: "number.port",
-	VITE_MY_VAR: "string",
-	VITE_MY_NUMBER: type("string").pipe((str) => Number.parseInt(str, 10)),
-	VITE_MY_BOOLEAN: type("string").pipe((str) => str === "true"),
+	VITE_MY_VAR: "unknown",
+	VITE_MY_NUMBER: "number",
+	VITE_MY_BOOLEAN: "boolean",
 });
 
 // https://vite.dev/config/
 export default defineConfig(({ mode }) => {
-	const env = arkenv(Env, loadEnv(mode, process.cwd(), ""));
+	const env = arkenv(Env, { env: loadEnv(mode, process.cwd(), "") });
 
 	console.log(`${env.VITE_MY_NUMBER} ${typeof env.VITE_MY_NUMBER}`);
 	return {

apps/www/components/banner.tsx

@@ -8,12 +8,11 @@ export function Banner() {
 	return (
 		<FumadocsBanner
 			variant="rainbow"
-			id="standard-schema-support-banner"
-			onClick={() => router.push("/docs/integrations/standard-schema")}
+			id="coercion-banner"
+			onClick={() => router.push("/docs/arkenv/coercion")}
 			className="cursor-pointer"
 		>
-			🎉 Standard Schema support is here: Use ArkEnv with Zod, Valibot, and
-			more!
+			🎉 Coercion is here: Auto convert strings to numbers, booleans, etc.
 		</FumadocsBanner>
 	);
 }