@kasoa/env 0.0.3 → 0.0.6

package/README.md

@@ -1 +1,69 @@
-# `@kasoa/env`
+# @kasoa/env
+
+Type-safe environment variable validation using [Standard Schema](https://standardschema.dev/).
+
+## Installation
+
+```bash
+pnpm add @kasoa/env valibot
+```
+
+## Usage
+
+```ts
+import { defineEnv } from "@kasoa/env";
+import * as v from "valibot";
+
+const env = defineEnv(
+  v.object({
+    DATABASE_URL: v.pipe(v.string(), v.url()),
+    PORT: v.pipe(v.string(), v.transform(Number)),
+    NODE_ENV: v.optional(
+      v.picklist(["development", "production"]),
+      "development",
+    ),
+  }),
+);
+
+// env is fully typed:
+// { DATABASE_URL: string; PORT: number; NODE_ENV: "development" | "production" }
+```
+
+## Features
+
+- Works with any [Standard Schema](https://standardschema.dev/) compatible library (Valibot, Zod, ArkType, etc.)
+- Treats empty strings as missing values
+- Throws with formatted error messages listing all invalid variables
+- Full TypeScript inference
+
+## API
+
+### `defineEnv(schema, env?)`
+
+Validates environment variables against the provided schema.
+
+- `schema` - A Standard Schema compatible schema
+- `env` - Optional env object (defaults to `process.env`)
+
+Returns the validated and typed environment object.
+
+Throws an `Error` if validation fails:
+
+```
+Environment validation failed:
+
+  DATABASE_URL: Invalid URL
+  PORT: Required
+```
+
+### `InferEnv<T>`
+
+Type helper to infer the output type of a schema:
+
+```ts
+import type { InferEnv } from "@kasoa/env";
+
+const schema = v.object({ PORT: v.string() });
+type Env = InferEnv<typeof schema>;
+// { PORT: string }
+```

package/dist/define-env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define-env.test.d.ts.map

package/dist/define-env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-env.test.d.ts","sourceRoot":"","sources":["../src/define-env.test.ts"],"names":[],"mappings":""}

package/dist/define-env.test.js

@@ -0,0 +1,82 @@
+import * as v from "valibot";
+import { describe, expect, it } from "vitest";
+import { defineEnv } from "./index.js";
+describe("defineEnv()", () => {
+    it("returns validated env object", () => {
+        expect.assertions(1);
+        const schema = v.object({
+            DATABASE_URL: v.string(),
+            PORT: v.pipe(v.string(), v.toNumber()),
+        });
+        const env = defineEnv(schema, {
+            DATABASE_URL: "postgres://localhost",
+            PORT: "3000",
+        });
+        expect(env).toStrictEqual({
+            DATABASE_URL: "postgres://localhost",
+            PORT: 3000,
+        });
+    });
+    it("throws on missing required variable", () => {
+        expect.assertions(2);
+        const schema = v.object({
+            DATABASE_URL: v.string(),
+        });
+        expect(() => defineEnv(schema, {})).toThrowError("Environment validation failed");
+        expect(() => defineEnv(schema, {})).toThrowError("DATABASE_URL");
+    });
+    it("treats empty string as undefined", () => {
+        expect.assertions(1);
+        const schema = v.object({
+            API_KEY: v.string(),
+        });
+        expect(() => defineEnv(schema, { API_KEY: "" })).toThrowError("Environment validation failed");
+    });
+    it("supports optional variables with defaults", () => {
+        expect.assertions(1);
+        const schema = v.object({
+            PORT: v.optional(v.string(), "3000"),
+        });
+        const env = defineEnv(schema, {});
+        expect(env.PORT).toBe("3000");
+    });
+    it("validates nested paths correctly", () => {
+        expect.assertions(1);
+        const schema = v.object({
+            DATABASE_URL: v.pipe(v.string(), v.url()),
+        });
+        expect(() => defineEnv(schema, { DATABASE_URL: "not-a-url" })).toThrowError("DATABASE_URL");
+    });
+    it("throws TypeError for async schemas", () => {
+        expect.assertions(2);
+        const asyncSchema = {
+            "~standard": {
+                version: 1,
+                vendor: "test",
+                validate: () => Promise.resolve({ value: {} }),
+            },
+        };
+        expect(() => defineEnv(asyncSchema, {})).toThrowError(TypeError);
+        expect(() => defineEnv(asyncSchema, {})).toThrowError("Async schema validation is not supported");
+    });
+    it("uses process.env by default", () => {
+        expect.assertions(1);
+        const originalEnv = process.env.TEST_VAR;
+        process.env.TEST_VAR = "test-value";
+        try {
+            const schema = v.object({
+                TEST_VAR: v.string(),
+            });
+            const env = defineEnv(schema);
+            expect(env.TEST_VAR).toBe("test-value");
+        }
+        finally {
+            if (originalEnv === undefined) {
+                delete process.env.TEST_VAR;
+            }
+            else {
+                process.env.TEST_VAR = originalEnv;
+            }
+        }
+    });
+});

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export * from "./define-env.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type InferEnv<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+export declare function defineEnv<T extends StandardSchemaV1>(schema: T, env?: Record<string, string | undefined>): InferEnv<T>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,gBAAgB,IAC7C,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAElC,wBAAgB,SAAS,CAAC,CAAC,SAAS,gBAAgB,EAClD,MAAM,EAAE,CAAC,EACT,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,QAAQ,CAAC,CAAC,CAAC,CAab"}

package/dist/index.js

@@ -1 +1,31 @@
-export * from "./define-env.js";
+export function defineEnv(schema, env = process.env) {
+    const normalizedEnv = normalizeEnv(env);
+    const result = schema["~standard"].validate(normalizedEnv);
+    if (result instanceof Promise) {
+        throw new TypeError("Async schema validation is not supported");
+    }
+    if (result.issues) {
+        throw new Error(formatIssues(result.issues));
+    }
+    return result.value;
+}
+function normalizeEnv(env) {
+    const normalizedEnv = {};
+    for (const key of Object.keys(env)) {
+        const value = env[key];
+        normalizedEnv[key] = value === "" ? undefined : value;
+    }
+    return normalizedEnv;
+}
+function formatIssues(issues) {
+    const lines = issues.map((issue) => {
+        const key = issue.path ? getPathString(issue.path) : "root";
+        return `  ${key}: ${issue.message}`;
+    });
+    return `Environment validation failed:\n\n${lines.join("\n")}`;
+}
+function getPathString(path) {
+    return path
+        .map((segment) => (typeof segment === "object" ? segment.key : segment))
+        .join(".");
+}

package/package.json

@@ -1,59 +1,62 @@
 {
   "name": "@kasoa/env",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "type": "module",
-  "sideEffects": false,
   "license": "MIT",
-  "description": "Manage environment variables, simply",
+  "description": "Type-safe environment variable validation using Standard Schema",
   "keywords": [
-    "kasoa",
     "env",
     "environment",
-    "variables",
-    "valibot",
-    "zod",
-    "arktype"
+    "validation",
+    "standard-schema",
+    "kasoa"
   ],
   "author": {
     "name": "Emmanuel Chucks",
+    "email": "hi@emmanuelchucks.com",
     "url": "https://emmanuelchucks.com"
   },
-  "homepage": "https://github.com/emmanuelchucks/kasoa/tree/main/packages/package-env",
+  "homepage": "https://github.com/emmanuelchucks/kasoa/tree/main/packages/env",
   "repository": {
     "type": "git",
-    "url": "https://github.com/emmanuelchucks/kasoa.git",
-    "directory": "packages/package-env"
+    "url": "git+https://github.com/emmanuelchucks/kasoa.git",
+    "directory": "packages/env"
   },
   "bugs": {
     "url": "https://github.com/emmanuelchucks/kasoa/issues"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
+    "src",
     "dist"
   ],
   "exports": {
     ".": "./dist/index.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@standard-schema/spec": "1.0.0-rc.0"
+    "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.7",
-    "arktype": "2.0.0",
-    "typescript": "^5.7.3",
-    "valibot": "^1.0.0-beta.12",
-    "zod": "^3.24.1",
-    "@kasoa/config-biome": "0.0.0",
-    "@kasoa/config-typescript": "0.0.0"
+    "@types/node": "^25.0.3",
+    "@typescript/native-preview": "^7.0.0-dev.20251216.1",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "valibot": "^1.2.0",
+    "vitest": "^4.0.16",
+    "@kasoa/eslint-config": "0.0.7",
+    "@kasoa/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=24"
   },
   "scripts": {
-    "dev": "tsc --watch",
-    "build": "tsc",
-    "test": "node --test --experimental-strip-types tests/*.test.ts",
-    "check": "biome check --write",
-    "format": "biome format --write",
-    "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "dev": "tsgo --watch",
+    "build": "tsgo",
+    "lint": "eslint --fix --cache .",
+    "format": "prettier --write --cache .",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
   }
 }

package/src/define-env.test.ts

@@ -0,0 +1,113 @@
+import * as v from "valibot";
+import { describe, expect, it } from "vitest";
+import { defineEnv } from "./index.js";
+
+describe("defineEnv()", () => {
+  it("returns validated env object", () => {
+    expect.assertions(1);
+
+    const schema = v.object({
+      DATABASE_URL: v.string(),
+      PORT: v.pipe(v.string(), v.toNumber()),
+    });
+
+    const env = defineEnv(schema, {
+      DATABASE_URL: "postgres://localhost",
+      PORT: "3000",
+    });
+
+    expect(env).toStrictEqual({
+      DATABASE_URL: "postgres://localhost",
+      PORT: 3000,
+    });
+  });
+
+  it("throws on missing required variable", () => {
+    expect.assertions(2);
+
+    const schema = v.object({
+      DATABASE_URL: v.string(),
+    });
+
+    expect(() => defineEnv(schema, {})).toThrowError(
+      "Environment validation failed",
+    );
+    expect(() => defineEnv(schema, {})).toThrowError("DATABASE_URL");
+  });
+
+  it("treats empty string as undefined", () => {
+    expect.assertions(1);
+
+    const schema = v.object({
+      API_KEY: v.string(),
+    });
+
+    expect(() => defineEnv(schema, { API_KEY: "" })).toThrowError(
+      "Environment validation failed",
+    );
+  });
+
+  it("supports optional variables with defaults", () => {
+    expect.assertions(1);
+
+    const schema = v.object({
+      PORT: v.optional(v.string(), "3000"),
+    });
+
+    const env = defineEnv(schema, {});
+
+    expect(env.PORT).toBe("3000");
+  });
+
+  it("validates nested paths correctly", () => {
+    expect.assertions(1);
+
+    const schema = v.object({
+      DATABASE_URL: v.pipe(v.string(), v.url()),
+    });
+
+    expect(() => defineEnv(schema, { DATABASE_URL: "not-a-url" })).toThrowError(
+      "DATABASE_URL",
+    );
+  });
+
+  it("throws TypeError for async schemas", () => {
+    expect.assertions(2);
+
+    const asyncSchema = {
+      "~standard": {
+        version: 1 as const,
+        vendor: "test",
+        validate: () => Promise.resolve({ value: {} }),
+      },
+    };
+
+    expect(() => defineEnv(asyncSchema, {})).toThrowError(TypeError);
+    expect(() => defineEnv(asyncSchema, {})).toThrowError(
+      "Async schema validation is not supported",
+    );
+  });
+
+  it("uses process.env by default", () => {
+    expect.assertions(1);
+
+    const originalEnv = process.env.TEST_VAR;
+    process.env.TEST_VAR = "test-value";
+
+    try {
+      const schema = v.object({
+        TEST_VAR: v.string(),
+      });
+
+      const env = defineEnv(schema);
+
+      expect(env.TEST_VAR).toBe("test-value");
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.TEST_VAR;
+      } else {
+        process.env.TEST_VAR = originalEnv;
+      }
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,50 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type InferEnv<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+export function defineEnv<T extends StandardSchemaV1>(
+  schema: T,
+  env: Record<string, string | undefined> = process.env,
+): InferEnv<T> {
+  const normalizedEnv = normalizeEnv(env);
+  const result = schema["~standard"].validate(normalizedEnv);
+
+  if (result instanceof Promise) {
+    throw new TypeError("Async schema validation is not supported");
+  }
+
+  if (result.issues) {
+    throw new Error(formatIssues(result.issues));
+  }
+
+  return result.value as InferEnv<T>;
+}
+
+function normalizeEnv(
+  env: Record<string, string | undefined>,
+): Record<string, string | undefined> {
+  const normalizedEnv: Record<string, string | undefined> = {};
+  for (const key of Object.keys(env)) {
+    const value = env[key];
+    normalizedEnv[key] = value === "" ? undefined : value;
+  }
+  return normalizedEnv;
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  const lines = issues.map((issue) => {
+    const key = issue.path ? getPathString(issue.path) : "root";
+    return `  ${key}: ${issue.message}`;
+  });
+
+  return `Environment validation failed:\n\n${lines.join("\n")}`;
+}
+
+function getPathString(
+  path: readonly (PropertyKey | StandardSchemaV1.PathSegment)[],
+): string {
+  return path
+    .map((segment) => (typeof segment === "object" ? segment.key : segment))
+    .join(".");
+}

package/dist/define-env.d.ts

@@ -1,3 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-export declare function defineEnv<TSchema extends StandardSchemaV1>(schema: TSchema): (env: unknown) => StandardSchemaV1.InferOutput<TSchema>;
-//# sourceMappingURL=define-env.d.ts.map

package/dist/define-env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"define-env.d.ts","sourceRoot":"","sources":["../src/define-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,wBAAgB,SAAS,CAAC,OAAO,SAAS,gBAAgB,EACzD,MAAM,EAAE,OAAO,GACb,CAAC,GAAG,EAAE,OAAO,KAAK,gBAAgB,CAAC,WAAW,CAAC,OAAO,CAAC,CA2BzD"}

package/dist/define-env.js

@@ -1,22 +0,0 @@
-import { styleText } from "node:util";
-export function defineEnv(schema) {
-    return (env) => {
-        const result = schema["~standard"].validate(env);
-        if (result instanceof Promise) {
-            throw new TypeError("Schema validation must be synchronous");
-        }
-        if (result.issues) {
-            const issues = result.issues.flatMap((issue) => (issue.path ?? []).map((item) => {
-                const key = typeof item === "object" ? item.key : item;
-                const message = issue.message;
-                return `${String(key)}: ${message}`;
-            }));
-            const error = [
-                `${styleText("red", "Invalid environment variables")}`,
-                ...issues,
-            ].join("\n");
-            throw new Error(error);
-        }
-        return result.value;
-    };
-}