Object coercion

.changeset/curvy-heads-grow.md

@@ -0,0 +1,19 @@
+---
+"@repo/keywords": patch
+---
+
+#### Add `maybeJson` keyword
+
+JSDoc:
+
+```ts
+/**
+ * A loose JSON morph.
+ *
+ * **In**: `unknown`
+ *
+ * **Out**: A parsed JSON object if the input is a valid JSON string; otherwise the original input.
+ *
+ * Useful for coercion in unions where failing on non-JSON strings would block other branches.
+ */
+```

.changeset/moody-humans-knock.md

@@ -0,0 +1,25 @@
+---
+"arkenv": patch
+---
+
+#### Object coercion
+
+ArkEnv now coerces objects when the `coerce` option is enabled (true by default).
+Objects are parsed from JSON strings, allowing for nested typesafe configuration.
+
+Example:
+
+```dotenv
+DATABASE={"HOST": "localhost", "PORT": "5432"}
+```
+
+```ts
+const env = arkenv({
+  DATABASE: {
+    HOST: "string",
+    PORT: "number"
+  }
+});
+
+console.log(env.DATABASE.PORT); // 5432 (number)
+```

.vscode/tasks.json

@@ -17,6 +17,13 @@
 			},
 			"label": "build",
 			"detail": "turbo run build"
+		},
+		{
+			"type": "npm",
+			"script": "changeset",
+			"problemMatcher": [],
+			"label": "changeset",
+			"detail": "changeset"
 		}
 	]
 }

apps/www/app/(home)/page.tsx

@@ -25,8 +25,8 @@ export default function HomePage() {
 			<div className="flex flex-col lg:flex-row items-center justify-center px-4 sm:px-6 lg:pl-12 lg:pr-6 max-w-screen-2xl mx-auto w-full gap-4 md:gap-8 lg:gap-12 lg:mt-20">
 				<div className="flex flex-col items-center lg:items-start text-center lg:text-left lg:flex-[1.4] relative z-20 mt-12 w-full max-w-full">
 					<div className="lg:mb-6 mb-0">
-						<AnnouncementBadge new href="docs/arkenv/coercion#arrays">
-							Array coercion
+						<AnnouncementBadge new href="docs/arkenv/coercion#objects">
+							Object & Array coercion
 						</AnnouncementBadge>
 					</div>
 					<h1 className="mb-4 mt-6 lg:mt-0 w-full max-w-2xl">

apps/www/content/docs/arkenv/coercion.mdx

@@ -68,6 +68,30 @@ const env = arkenv(
 );
 ```
 
+## Objects
+
+ArkEnv can parse JSON strings into objects. This is useful for grouping related configuration into a single environment variable.
+
+```ts title="index.ts" twoslash
+import arkenv from "arkenv";
+
+const env = arkenv({
+  DATABASE: {
+    HOST: "string",
+    PORT: "number"
+  }
+}, {
+  env: {
+    DATABASE: '{"HOST": "localhost", "PORT": "5432"}'
+  }
+});
+
+// env.DATABASE.HOST is "localhost"
+// env.DATABASE.PORT is 5432 (number!)
+```
+
+Coercion works recursively: even variables inside a JSON object are coerced to their correct types (like `PORT` becoming a `number` above).
+
 ## How it works
 
 ArkEnv introspects your schema to identify fields that should be numbers, booleans, and other non-string types you define. When you call `createEnv()` (or `arkenv()`), it pre-processes your environment variables to perform these conversions *before* validation.

packages/arkenv/src/create-env.test.ts

@@ -571,4 +571,61 @@ describe("createEnv", () => {
 			expect(env.TAGS).toEqual([]);
 		});
 	});
+
+	describe("object coercion", () => {
+		it("should parse an object from a JSON string", () => {
+			const env = createEnv(
+				{ DATABASE: { HOST: "string", PORT: "number" } },
+				{
+					env: {
+						DATABASE: '{"HOST": "localhost", "PORT": "5432"}',
+					},
+				},
+			);
+			expect(env.DATABASE).toEqual({ HOST: "localhost", PORT: 5432 });
+			expect(env.DATABASE.HOST).toBe("localhost");
+			expect(env.DATABASE.PORT).toBe(5432);
+		});
+
+		it("should handle nested object coercion", () => {
+			const env = createEnv(
+				{ CONFIG: { DB: { PORT: "number" }, APP: { NAME: "string" } } },
+				{
+					env: {
+						CONFIG: '{"DB": {"PORT": "8080"}, "APP": {"NAME": "myapp"}}',
+					},
+				},
+			);
+			expect(env.CONFIG).toEqual({
+				DB: { PORT: 8080 },
+				APP: { NAME: "myapp" },
+			});
+		});
+
+		it("should fail validation if object is not valid JSON", () => {
+			expect(() => {
+				createEnv(
+					{ DATABASE: { HOST: "string" } },
+					{ env: { DATABASE: '{"HOST": "localhost"' } }, // Missing closing brace
+				);
+			}).toThrow("must be an object");
+		});
+
+		it("should parse objects within arrays", () => {
+			const env = createEnv(
+				{ SERVICES: type({ NAME: "string", PORT: "number" }).array() },
+				{
+					env: {
+						SERVICES:
+							'[{"NAME": "web", "PORT": "80"}, {"NAME": "api", "PORT": "3000"}]',
+					},
+					arrayFormat: "json",
+				},
+			);
+			expect(env.SERVICES).toEqual([
+				{ NAME: "web", PORT: 80 },
+				{ NAME: "api", PORT: 3000 },
+			]);
+		});
+	});
 });