zod-envkit 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] – 2026-01-26
+
+### Added
+- Initial release of **zod-envkit**
+- Type-safe environment variable validation using Zod
+- `loadEnv` helper for safe runtime parsing of `process.env`
+- `formatZodError` for human-readable error output
+- CLI tool to generate:
+  - `.env.example`
+  - `ENV.md` documentation
+- Automatic type inference for validated environment variables
+- Support for ESM and CommonJS builds
+- TypeScript declaration files (`.d.ts`) included
+- Basic test suite using Vitest
+- Clear and documented API surface
+- MIT license
+
+### Design Decisions
+- Explicit configuration over magic
+- No automatic schema introspection for documentation generation
+- Environment variables treated as an explicit runtime contract
+- Small, framework-agnostic core
+
+---
+
+[1.0.0]: https://www.npmjs.com/package/zod-envkit/v/1.0.0
+
+
+## [1.0.1] – 2026-01-26
+
+### Changed
+- Documentation and packaging improvements
+- Minor CLI/docs adjustments
+
+[1.0.1]: https://www.npmjs.com/package/zod-envkit/v/1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nxtxe
+
+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

@@ -1,3 +1,18 @@
+<div align="center">
+	<br />
+	<p>
+		<img src="./zod-envkit.svg" width="546" alt="zod-envkit" /><
+	</p>
+	<br />
+	<p>
+		<a href="https://www.npmjs.com/package/zod-envkit"><img src="https://img.shields.io/npm/v/zod-envkit.svg?maxAge=100" alt="npm version" /></a>
+		<a href="https://www.npmjs.com/package/zod-envkit"><img src="https://img.shields.io/npm/dt/zod-envkit.svg?maxAge=100" alt="npm downloads" /></a>
+	</p>
+  <p align="center">
+    <b> A framework for developing bots based using discord.js. </b>
+  </p>
+</div>
+
 Type-safe environment variable validation and documentation using Zod.
 
 `zod-envkit` is a small library and CLI tool that helps you:

package/package.json

@@ -1,13 +1,11 @@
 {
   "name": "zod-envkit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Validate environment variables with Zod and generate .env.example",
   "type": "module",
-
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,28 +13,43 @@
       "require": "./dist/index.cjs"
     }
   },
-
   "bin": {
     "zod-envkit": "dist/cli.js"
   },
-
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxtxe/zod-envkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nxtxe/zod-envkit/issues"
+  },
+  "homepage": "https://github.com/nxtxe/zod-envkit#readme",
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts src/cli.ts --watch --dts",
     "test": "vitest run",
     "prepublishOnly": "npm run test && npm run build"
   },
-
-  "keywords": ["env", "dotenv", "zod", "validation", "cli"],
+  "keywords": [
+    "env",
+    "dotenv",
+    "zod",
+    "validation",
+    "cli"
+  ],
   "author": "",
   "license": "MIT",
-
   "dependencies": {
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",
     "zod": "^4.3.6"
   },
-
   "devDependencies": {
     "@types/node": "^25.0.10",
     "eslint": "^9.39.2",

package/.env.example

@@ -1,8 +0,0 @@
-# Runtime mode
-NODE_ENV=development
-
-# HTTP port
-PORT=3000
-
-# Postgres connection string
-DATABASE_URL=postgresql://user:pass@localhost:5432/db

package/ENV.md

@@ -1,7 +0,0 @@
-# Environment variables
-
-|      Key       |  Required  |                  Example                   |         Description          |
-| :------------: | :--------: | :----------------------------------------: | :--------------------------: |
-|    NODE_ENV    |    yes     |                development                 |         Runtime mode         |
-|      PORT      |    yes     |                    3000                    |          HTTP port           |
-|  DATABASE_URL  |    yes     |  postgresql://user:pass@localhost:5432/db  |  Postgres connection string  |

package/env.meta.json

@@ -1,5 +0,0 @@
-{
-  "NODE_ENV": { "description": "Runtime mode", "example": "development" },
-  "PORT": { "description": "HTTP port", "example": "3000" },
-  "DATABASE_URL": { "description": "Postgres connection string", "example": "postgresql://user:pass@localhost:5432/db" }
-}

package/src/cli.ts

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { Command } from "commander";
-import { generateEnvDocs, generateEnvExample, type EnvMeta } from "./generate.js";
-
-const program = new Command();
-
-program
-  .name("zod-envkit")
-  .description("Generate .env.example and ENV.md from env.meta.json")
-  .option("-c, --config <file>", "Path to env meta json", "env.meta.json")
-  .option("--out-example <file>", "Output file for .env.example", ".env.example")
-  .option("--out-docs <file>", "Output file for docs", "ENV.md")
-  .action((opts) => {
-    const configPath = path.resolve(process.cwd(), opts.config);
-    const raw = fs.readFileSync(configPath, "utf8");
-    const meta: EnvMeta = JSON.parse(raw);
-
-    fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
-    fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
-
-    console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
-  });
-
-program.parse();

package/src/generate.ts

@@ -1,130 +0,0 @@
-// src/generate.ts
-
-export type EnvMeta = Record<
-  string,
-  {
-    description?: string;
-    example?: string;
-    required?: boolean; // default: true
-  }
->;
-
-function strLen(s: string): number {
-  return s.length;
-}
-
-function padCenter(text: string, width: number): string {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
-
-  const left = Math.floor(diff / 2);
-  const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
-}
-
-function padRight(text: string, width: number): string {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
-  return t + " ".repeat(diff);
-}
-
-function makeDivider(width: number, align: "left" | "center" | "right"): string {
-  // Markdown alignment:
-  // left   : --- 
-  // center : :---:
-  // right  : ---:
-  if (width < 3) width = 3;
-
-  if (align === "center") return ":" + "-".repeat(width - 2) + ":";
-  if (align === "right") return "-".repeat(width - 1) + ":";
-  return "-".repeat(width);
-}
-
-/**
- * Генерит .env.example красиво:
- * - комментарий с description
- * - KEY=example
- */
-export function generateEnvExample(meta: EnvMeta): string {
-  const lines: string[] = [];
-
-  for (const [key, m] of Object.entries(meta)) {
-    if (m.description) lines.push(`# ${m.description}`);
-    lines.push(`${key}=${m.example ?? ""}`);
-    lines.push("");
-  }
-
-  return lines.join("\n").trim() + "\n";
-}
-
-/**
- * Генерит ENV.md как ровную таблицу:
- * - вычисляет ширины колонок по максимальной длине
- * - паддит значения пробелами
- * - ставит выравнивание :---: чтобы центрировалось в Markdown
- */
-export function generateEnvDocs(meta: EnvMeta): string {
-  const headers = ["Key", "Required", "Example", "Description"] as const;
-
-  const rows = Object.entries(meta).map(([key, m]) => {
-    const req = m.required === false ? "no" : "yes";
-    return {
-      Key: key,
-      Required: req,
-      Example: m.example ?? "",
-      Description: m.description ?? "",
-    };
-  });
-
-  const widths = {
-    Key: headers[0].length,
-    Required: headers[1].length,
-    Example: headers[2].length,
-    Description: headers[3].length,
-  };
-
-  for (const r of rows) {
-    widths.Key = Math.max(widths.Key, strLen(r.Key));
-    widths.Required = Math.max(widths.Required, strLen(r.Required));
-    widths.Example = Math.max(widths.Example, strLen(r.Example));
-    widths.Description = Math.max(widths.Description, strLen(r.Description));
-  }
-
-  widths.Key += 2;
-  widths.Required += 2;
-  widths.Example += 2;
-  widths.Description += 2;
-
-  const headerLine =
-    `| ${padCenter(headers[0], widths.Key)} ` +
-    `| ${padCenter(headers[1], widths.Required)} ` +
-    `| ${padCenter(headers[2], widths.Example)} ` +
-    `| ${padCenter(headers[3], widths.Description)} |`;
-
-  const dividerLine =
-    `| ${makeDivider(widths.Key, "center")} ` +
-    `| ${makeDivider(widths.Required, "center")} ` +
-    `| ${makeDivider(widths.Example, "center")} ` +
-    `| ${makeDivider(widths.Description, "center")} |`;
-
-  const bodyLines = rows.map((r) => {
-    return (
-      `| ${padCenter(r.Key, widths.Key)} ` +
-      `| ${padCenter(r.Required, widths.Required)} ` +
-      `| ${padCenter(r.Example, widths.Example)} ` +
-      `| ${padCenter(r.Description, widths.Description)} |`
-    );
-  });
-
-
-  return [
-    `# Environment variables`,
-    ``,
-    headerLine,
-    dividerLine,
-    ...bodyLines,
-    ``,
-  ].join("\n");
-}

package/src/index.ts

@@ -1,23 +0,0 @@
-import { z } from "zod";
-
-export type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
-
-export function loadEnv<T extends z.ZodTypeAny>(
-  schema: T,
-  opts?: { throwOnError?: boolean }
-):
-  | { ok: true; env: z.infer<T> }
-  | { ok: false; error: z.ZodError } {
-  const parsed = schema.safeParse(process.env);
-
-  if (parsed.success) return { ok: true, env: parsed.data };
-
-  if (opts?.throwOnError) throw parsed.error;
-  return { ok: false, error: parsed.error };
-}
-
-export function formatZodError(err: z.ZodError): string {
-  return err.issues
-    .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`)
-    .join("\n");
-}

package/test/basic.test.ts

@@ -1,15 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { z } from "zod";
-import { loadEnv } from "../src/index";
-
-describe("loadEnv", () => {
-  it("parses valid env", () => {
-    process.env.PORT = "3000";
-    const schema = z.object({ PORT: z.coerce.number() });
-
-    const res = loadEnv(schema);
-    expect(res.ok).toBe(true);
-
-    if (res.ok) expect(res.env.PORT).toBe(3000);
-  });
-});

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "declaration": true,
-    "skipLibCheck": true
-  }
-}