@mr-aftab-ahmad-khan/envy 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] — 2026-05-15
+
+### Added
+
+- Zod-validated `createEnv({ server, client, clientPrefix, runtimeEnv })` with read-only proxy and client/server isolation.
+- Framework adapters: `envy/next`, `envy/vite`, `envy/astro`.
+- CLI: `envy validate` and `envy generate-example` for `.env.example` scaffolding.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 envy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,532 @@
+# envy
+
+[![npm version](https://img.shields.io/npm/v/%40mr-aftab-ahmad-khan%2Fenvy.svg)](https://www.npmjs.com/package/@mr-aftab-ahmad-khan/envy)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/%40mr-aftab-ahmad-khan%2Fenvy)](https://bundlephobia.com/package/envy)
+[![license](https://img.shields.io/npm/l/%40mr-aftab-ahmad-khan%2Fenvy.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue.svg)](https://www.typescriptlang.org/)
+
+**Type-safe environment variables for any JavaScript runtime.** `envy` is a framework-agnostic, Zod-powered loader that turns `process.env` into a strongly-typed, validated object at boot. `env.PORT` is a `number`. `env.DATABASE_URL` is a non-empty URL string. Defaults flow into the inferred type. Missing or malformed variables are reported all-at-once before your app starts.
+
+Unlike `dotenv` (which gives you `string | undefined` everywhere) or `t3-env` (which is glued to Next.js + React), `envy` is a tiny zero-runtime-dependency core with optional adapters for **Next.js**, **Vite**, and **Astro**, a CLI for CI validation and `.env.example` generation, and a strict server/client boundary that throws at runtime if you ever try to read a secret in the browser.
+
+---
+
+## Installation
+
+```bash
+npm install @mr-aftab-ahmad-khan/envy zod
+# or
+pnpm add @mr-aftab-ahmad-khan/envy zod
+# or
+yarn add @mr-aftab-ahmad-khan/envy zod
+```
+
+`zod` is a peer dependency — `envy` itself has no runtime dependencies.
+
+---
+
+## Quick Start
+
+```ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    PORT: z.coerce.number().default(3000),
+  },
+});
+
+console.log(env.DATABASE_URL); // string
+console.log(env.PORT);         // number
+```
+
+If `DATABASE_URL` is missing, the process exits with a clear error listing every problem at once.
+
+---
+
+## Core Usage Examples
+
+### 1. Basic server-only env
+
+```ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    PORT: z.coerce.number(),
+    DEBUG: z.coerce.boolean(),
+    API_BASE: z.string().url(),
+  },
+});
+
+env.DATABASE_URL; // string
+env.PORT;         // number
+env.DEBUG;        // boolean
+env.API_BASE;     // string
+```
+
+### 2. Defaults and coercion
+
+```ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    PORT: z.coerce.number().default(3000),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    FEATURE_X_ENABLED: z.coerce.boolean().default(false),
+  },
+});
+
+env.PORT;              // number (3000 if PORT is missing)
+env.LOG_LEVEL;         // "debug" | "info" | "warn" | "error"
+env.FEATURE_X_ENABLED; // boolean
+```
+
+### 3. Custom onValidationError hook
+
+```ts
+import { createEnv, EnvValidationError } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: { DATABASE_URL: z.string().url() },
+  onValidationError: (err: EnvValidationError) => {
+    console.error("envy: cannot start, missing required env");
+    for (const v of err.invalid) {
+      console.error(`  - ${v.name}`);
+    }
+    process.exit(1);
+  },
+});
+```
+
+### 4. skipValidation in Vitest setup
+
+```ts
+// vitest.setup.ts
+import { beforeAll } from "vitest";
+
+beforeAll(() => {
+  process.env.DATABASE_URL = "postgres://localhost/test";
+  process.env.SKIP_ENV_VALIDATION = "1";
+});
+
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: { DATABASE_URL: z.string().url() },
+  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+});
+```
+
+### 5. Shared env in a utility module
+
+```ts
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy/next";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: { DATABASE_URL: z.string().url() },
+  client: { NEXT_PUBLIC_APP_URL: z.string().url() },
+});
+
+// src/lib/api.ts (imported by both server and client code)
+import { env } from "../env";
+
+export function getApiBase() {
+  return env.NEXT_PUBLIC_APP_URL; // safe everywhere
+}
+```
+
+### 6. Combining multiple env files via runtimeEnv
+
+```ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+const stage = process.env.NODE_ENV ?? "development";
+const overlay = stage === "production" ? process.env : { ...process.env, DEBUG: "true" };
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    DEBUG: z.coerce.boolean().default(false),
+  },
+  runtimeEnv: overlay,
+});
+```
+
+---
+
+## Framework Integration Examples
+
+### Next.js App Router
+
+```ts
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy/next";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    NEXTAUTH_SECRET: z.string().min(32),
+    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  },
+  client: {
+    NEXT_PUBLIC_APP_URL: z.string().url(),
+    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+  },
+});
+```
+
+```tsx
+// app/page.tsx (Server Component)
+import { env } from "@/env";
+
+export default function Page() {
+  const url = process.env.NODE_ENV === "production"
+    ? env.NEXT_PUBLIC_APP_URL
+    : "http://localhost:3000";
+  return <main>{url}</main>;
+}
+```
+
+```tsx
+// app/components/StripeButton.tsx
+"use client";
+import { env } from "@/env";
+
+export function StripeButton() {
+  return <button data-key={env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY}>Pay</button>;
+}
+```
+
+### Vite + React
+
+```ts
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy/vite";
+import { z } from "zod";
+
+export const env = createEnv({
+  client: {
+    VITE_API_BASE: z.string().url(),
+    VITE_SENTRY_DSN: z.string().url().optional(),
+  },
+  runtimeEnv: import.meta.env,
+});
+```
+
+```tsx
+// src/App.tsx
+import { env } from "./env";
+
+export function App() {
+  return <pre>{env.VITE_API_BASE}</pre>;
+}
+```
+
+### Plain Express
+
+```ts
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    PORT: z.coerce.number().default(3000),
+    DATABASE_URL: z.string().url(),
+  },
+});
+
+// src/server.ts
+import express from "express";
+import { env } from "./env";
+
+const app = express();
+app.listen(env.PORT, () => console.log(`listening on ${env.PORT}`));
+```
+
+---
+
+## Configuration Reference
+
+| Option                   | Type                                   | Default            | Description                                                                 |
+| ------------------------ | -------------------------------------- | ------------------ | --------------------------------------------------------------------------- |
+| `server`                 | `Record<string, ZodTypeAny>`           | `{}`               | Server-only schemas. Never accessible on the client.                        |
+| `client`                 | `Record<string, ZodTypeAny>`           | `{}`               | Client-exposed schemas. Must match `clientPrefix` (when set by an adapter). |
+| `runtimeEnv`             | `Record<string, string \| undefined>`  | `process.env`      | Source of raw values.                                                       |
+| `clientPrefix`           | `string`                               | `undefined`        | Prefix required on every `client` key. Set by adapters.                     |
+| `skipValidation`         | `boolean`                              | `false`            | Bypass Zod parsing; values returned as-is.                                  |
+| `onValidationError`      | `(err: EnvValidationError) => void`    | `undefined`        | Called instead of throwing.                                                 |
+| `isServer`               | `boolean`                              | `typeof window === "undefined"` | Controls whether server vars can be read.                  |
+| `emptyStringAsUndefined` | `boolean`                              | `true`             | Coerce `""` to `undefined` so defaults fire.                                |
+
+---
+
+## Error Handling
+
+When validation fails, `envy` throws an `EnvValidationError`:
+
+```
+Invalid environment variables (2 issues):
+  - DATABASE_URL: Invalid url (received: "not-a-url")
+  - PORT: Expected number, received string (received: "abc")
+```
+
+Catch it programmatically:
+
+```ts
+import { createEnv, EnvValidationError } from "@mr-aftab-ahmad-khan/envy";
+
+try {
+  const env = createEnv({ /* ... */ });
+} catch (err) {
+  if (err instanceof EnvValidationError) {
+    for (const v of err.invalid) {
+      console.error(v.name, v.received, v.issues);
+    }
+  }
+  process.exit(1);
+}
+```
+
+`EnvValidationError` shape:
+
+```ts
+class EnvValidationError extends Error {
+  readonly invalid: ReadonlyArray<{
+    name: string;
+    received: unknown;
+    issues: ReadonlyArray<ZodIssue>;
+  }>;
+}
+```
+
+---
+
+## TypeScript Types
+
+```ts
+import type {
+  CreateEnvOptions,
+  Env,
+  InferEnv,
+  InvalidVar,
+  ZodRecord,
+} from "@mr-aftab-ahmad-khan/envy";
+
+const env = createEnv({ server: { PORT: z.coerce.number() } });
+
+type MyEnv = InferEnv<typeof env>;
+// { readonly PORT: number }
+```
+
+---
+
+## CLI Reference
+
+### `envy validate`
+
+Validates the current environment against your schema. Exits with code `1` on failure — perfect for CI.
+
+```bash
+envy validate
+envy validate --schema src/env.ts --env .env.production
+```
+
+| Flag           | Default     | Description                                |
+| -------------- | ----------- | ------------------------------------------ |
+| `--schema, -s` | `src/env.ts`| Path to schema module (must export `schema = { server, client }`) |
+| `--env, -e`    | `.env`      | Path to `.env` file                        |
+
+### `envy generate-example`
+
+Generates a `.env.example` from the schema, using `.default()` values or sensible placeholders.
+
+```bash
+envy generate-example
+envy generate-example --out .env.example.local
+```
+
+| Flag        | Default        | Description                |
+| ----------- | -------------- | -------------------------- |
+| `--out, -o` | `.env.example` | Output path                |
+
+Schemas must be exported as:
+
+```ts
+// src/env.ts
+import { z } from "zod";
+
+export const schema = {
+  server: { DATABASE_URL: z.string().url() },
+  client: { NEXT_PUBLIC_URL: z.string().url() },
+};
+```
+
+---
+
+## Real-World Recipe — Full Next.js Production Setup
+
+```ts
+// src/env.ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy/next";
+import { z } from "zod";
+
+export const schema = {
+  server: {
+    DATABASE_URL: z.string().url().describe("postgres://..."),
+    NEXTAUTH_SECRET: z.string().min(32),
+    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  },
+  client: {
+    NEXT_PUBLIC_APP_URL: z.string().url(),
+    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+  },
+};
+
+export const env = createEnv(schema);
+```
+
+```bash
+# .env.local
+DATABASE_URL=postgres://app:pass@localhost:5432/app
+NEXTAUTH_SECRET=ab92e7da6c0f4d39b1c6a8a2f0b1c4e3
+STRIPE_SECRET_KEY=sk_test_abc123
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123
+```
+
+```bash
+# .env.example  (generated by `envy generate-example`)
+# --- server-only ---
+DATABASE_URL=postgres://...
+NEXTAUTH_SECRET=your-value-here
+STRIPE_SECRET_KEY=your-value-here
+
+# --- exposed to client ---
+NEXT_PUBLIC_APP_URL=https://example.com
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-value-here
+```
+
+```json
+// package.json
+{
+  "scripts": {
+    "build": "envy validate && next build",
+    "start": "next start"
+  }
+}
+```
+
+```tsx
+// app/page.tsx (Server Component)
+import { env } from "@/env";
+import Stripe from "stripe";
+
+const stripe = new Stripe(env.STRIPE_SECRET_KEY);
+
+export default async function Page() {
+  const balance = await stripe.balance.retrieve();
+  return <pre>{JSON.stringify(balance, null, 2)}</pre>;
+}
+```
+
+```tsx
+// app/checkout/CheckoutButton.tsx
+"use client";
+import { env } from "@/env";
+
+export function CheckoutButton() {
+  return <button data-pk={env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY}>Pay</button>;
+}
+```
+
+```yaml
+# .github/workflows/deploy.yml
+name: deploy
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npx envy validate
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
+          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+          NEXT_PUBLIC_APP_URL: ${{ vars.NEXT_PUBLIC_APP_URL }}
+          NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: ${{ vars.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY }}
+      - run: npm run build
+```
+
+---
+
+## Migration Guide from dotenv
+
+**Before — `dotenv`:**
+
+```ts
+import "dotenv/config";
+
+const port = parseInt(process.env.PORT ?? "3000", 10);
+const dbUrl = process.env.DATABASE_URL;
+if (!dbUrl) throw new Error("DATABASE_URL missing");
+
+app.listen(port);
+```
+
+**After — `envy`:**
+
+```ts
+import { createEnv } from "@mr-aftab-ahmad-khan/envy";
+import { z } from "zod";
+
+const env = createEnv({
+  server: {
+    PORT: z.coerce.number().default(3000),
+    DATABASE_URL: z.string().url(),
+  },
+});
+
+app.listen(env.PORT);
+```
+
+- `process.env.PORT` (`string | undefined`) → `env.PORT` (`number`).
+- Missing `DATABASE_URL` fails before listen with every error printed at once.
+
+---
+
+## Comparison Table
+
+| Feature                 | dotenv | t3-env | **envy** |
+| ----------------------- | :----: | :----: | :------: |
+| TypeScript types        |   ❌   |   ✅   |    ✅    |
+| Framework agnostic      |   ✅   |   ❌   |    ✅    |
+| Zod validation          |   ❌   |   ✅   |    ✅    |
+| CLI tooling             |   ❌   |   ❌   |    ✅    |
+| Client/server boundary  |   ❌   |   ✅   |    ✅    |
+| Bundle size             | 6 KB   | 14 KB  |  **3 KB** |
+| Custom error handler    |   ❌   |   ❌   |    ✅    |
+
+---
+
+## License
+
+MIT

package/dist/astro.cjs

@@ -0,0 +1,153 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/astro.ts
+var astro_exports = {};
+__export(astro_exports, {
+  EnvValidationError: () => EnvValidationError,
+  InvalidAccessError: () => InvalidAccessError,
+  createEnv: () => createEnv2
+});
+module.exports = __toCommonJS(astro_exports);
+
+// src/errors.ts
+var EnvValidationError = class _EnvValidationError extends Error {
+  invalid;
+  constructor(invalid) {
+    super(_EnvValidationError.formatMessage(invalid));
+    this.name = "EnvValidationError";
+    this.invalid = invalid;
+    Object.setPrototypeOf(this, _EnvValidationError.prototype);
+  }
+  static formatMessage(invalid) {
+    const lines = [
+      `Invalid environment variables (${invalid.length} issue${invalid.length === 1 ? "" : "s"}):`
+    ];
+    for (const v of invalid) {
+      const received = v.received === void 0 ? "<missing>" : JSON.stringify(v.received);
+      for (const issue of v.issues) {
+        lines.push(`  - ${v.name}: ${issue.message} (received: ${received})`);
+      }
+    }
+    return lines.join("\n");
+  }
+};
+var InvalidAccessError = class _InvalidAccessError extends Error {
+  constructor(varName) {
+    super(
+      `Attempted to access server-only env var "${varName}" on the client. Move it to the "server" object only if access is required server-side.`
+    );
+    this.name = "InvalidAccessError";
+    Object.setPrototypeOf(this, _InvalidAccessError.prototype);
+  }
+};
+
+// src/core.ts
+var DEFAULT_RUNTIME_ENV = typeof process !== "undefined" && process.env ? process.env : {};
+function isServerDefault() {
+  return typeof window === "undefined";
+}
+function createEnv(opts) {
+  const {
+    server = {},
+    client = {},
+    runtimeEnv = DEFAULT_RUNTIME_ENV,
+    clientPrefix,
+    skipValidation = false,
+    onValidationError,
+    isServer = isServerDefault(),
+    emptyStringAsUndefined = true
+  } = opts;
+  if (clientPrefix) {
+    for (const key of Object.keys(client)) {
+      if (!key.startsWith(clientPrefix)) {
+        throw new Error(
+          `Client variable "${key}" must start with prefix "${clientPrefix}".`
+        );
+      }
+    }
+    for (const key of Object.keys(server)) {
+      if (key.startsWith(clientPrefix)) {
+        throw new Error(
+          `Server variable "${key}" must NOT start with the client prefix "${clientPrefix}".`
+        );
+      }
+    }
+  }
+  const parsed = {};
+  const invalid = [];
+  const validate = (name, schema) => {
+    let raw = runtimeEnv[name];
+    if (emptyStringAsUndefined && raw === "") raw = void 0;
+    const result = schema.safeParse(raw);
+    if (result.success) {
+      parsed[name] = result.data;
+    } else {
+      invalid.push({ name, received: raw, issues: result.error.issues });
+    }
+  };
+  if (!skipValidation) {
+    for (const [name, schema] of Object.entries(server)) validate(name, schema);
+    for (const [name, schema] of Object.entries(client)) validate(name, schema);
+    if (invalid.length > 0) {
+      const err = new EnvValidationError(invalid);
+      if (onValidationError) {
+        onValidationError(err);
+        return parsed;
+      }
+      throw err;
+    }
+  } else {
+    for (const name of Object.keys(server)) parsed[name] = runtimeEnv[name];
+    for (const name of Object.keys(client)) parsed[name] = runtimeEnv[name];
+  }
+  const serverKeys = new Set(Object.keys(server));
+  const proxy = new Proxy(parsed, {
+    get(target, prop) {
+      if (typeof prop !== "string") return Reflect.get(target, prop);
+      if (!isServer && serverKeys.has(prop)) {
+        throw new InvalidAccessError(prop);
+      }
+      return target[prop];
+    },
+    set() {
+      throw new Error("Env is read-only");
+    },
+    deleteProperty() {
+      throw new Error("Env is read-only");
+    }
+  });
+  return proxy;
+}
+
+// src/adapters/astro.ts
+function createEnv2(opts) {
+  return createEnv({
+    ...opts,
+    clientPrefix: "PUBLIC_",
+    isServer: typeof window === "undefined"
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EnvValidationError,
+  InvalidAccessError,
+  createEnv
+});
+//# sourceMappingURL=astro.cjs.map