@zh-moody/safe-env 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# safe-env 🔒
+
+**告别 `undefined`！在应用启动的第一行，拦截所有错误配置。**
+
+无论你在写 Vue、React 还是 Node.js，环境变量配置永远是 Bug 的温床。`safe-env` 通过强类型 Schema 校验，确保你的应用在拥有正确配置的前提下才启动。
+
+---
+
+### 🚀 核心特性
+
+- **类型安全**：自动推断配置对象类型，拥有完美的 IDE 补全。
+- **链式校验**：内置 `min`, `max`, `validate`, `enum` 等校验逻辑。
+- **自动前缀**：支持 `VITE_` 或 `REACT_APP_` 自动补全，代码里用 `PORT`，配置里用 `VITE_PORT`。
+- **跨端兼容**：自动识别 Node/浏览器环境，支持双端“防御性退出”。
+- **极致轻量**：Minified 体积约 **2.6 KB**，Gzip 后仅 **1.3 KB**，零运行时依赖。
+
+---
+
+### 🚀 快速上手
+
+#### 🔹 [Vite / React / Vue] 端使用
+在前端，环境变量由构建工具（如 Vite）注入到 `import.meta.env` 中。
+
+**1. 准备 `.env` 文件：**
+```bash
+VITE_API_URL=https://api.com
+VITE_PORT=3000
+```
+
+**2. 定义配置 (`src/env.ts`)：**
+```typescript
+import { safeEnv, s } from 'safe-env';
+
+export const config = safeEnv({
+  apiUrl: s.string().from('VITE_API_URL'), // 别名映射
+  port: s.number(3000).from('VITE_PORT'),
+}, { 
+  source: import.meta.env // ⚠️ 浏览器端必须手动传入数据源
+});
+```
+
+---
+
+#### 🔸 [Node.js / 服务端] 端使用
+在后端，库会自动寻找并解析磁盘上的 `.env` 文件。
+
+**1. 准备 `.env` 文件：**
+```bash
+DB_HOST=localhost
+DB_PORT=5432
+```
+
+**2. 定义配置 (`src/db.ts`)：**
+```typescript
+import { safeEnv, s } from 'safe-env';
+
+const dbConfig = safeEnv({
+  DB_HOST: s.string('localhost'),
+  DB_PORT: s.number(5432)
+}); // ⚠️ Node 端无需传 source，会自动读取文件
+
+export default dbConfig;
+```
+
+---
+
+### 📂 核心对比：Schema 与 .env 对应关系
+
+| Schema 定义 | .env 中的写法 | 结果 |
+| :--- | :--- | :--- |
+| `s.string()` | `KEY=val` | ✅ 通过 |
+| `s.string()` | *(未填写)* | ❌ **报错并拦截启动** |
+| `s.string('App')` | `KEY=` (留空) | ✅ 自动降级为 `'App'` |
+| `s.number()` | `KEY=abc` | ❌ **报错：Invalid number** |
+
+---
+
+### 🛠️ API 详解
+
+#### 1. 定义字段 (`s.xxx`)
+- `s.string(default?)`: 字符串。若无默认值则必填。
+- `s.number(default?)`: 数字。自动将字符串转为 `number`。
+- `s.boolean(default?)`: 布尔。将 `"true"` 解析为 `true`。
+- `s.enum(options, default?)`: 枚举。值必须在数组中。
+  - 示例：`s.enum(['dev', 'prod'], 'dev')`
+
+#### 2. 增强校验 (链式调用)
+每个通过 `s` 定义的字段都可以调用以下方法进行增强：
+
+- **`.from(key)`**: 指定环境变量名。
+  ```typescript
+  // 即使变量叫 VITE_PATH，代码里也可以叫 port
+  port: s.number().from('VITE_PATH')
+  ```
+
+- **`.min(n)` / `.max(n)`**: 限制数字取值范围。
+  ```typescript
+  // 端口必须在 1-65535 之间
+  PORT: s.number().min(1).max(65535)
+  ```
+
+- **`.validate(fn, msg?)`**: 自定义校验（如：邮箱、URL 格式）。
+  ```typescript
+  // 必须是安全地址
+  API: s.string().validate(v => v.startsWith('https'), 'Must be HTTPS')
+  ```
+
+#### 3. 加载选项 (`SafeEnvOptions`)
+
+| 选项 | 适用环境 | 说明 |
+| :--- | :--- | :--- |
+| `source` | **[Vite/浏览器]** | **必填**。传入 `import.meta.env` 或 `process.env`。 |
+| `prefix` | **通用** | **可选**。自动补全前缀，如 `prefix: 'VITE_'`。 |
+| `mode` | **[Node.js]** | **可选**。指定模式（dev/prod）以加载对应的 `.env.prod` 等文件。 |
+| `loadProcessEnv` | **[Node.js]** | **可选**。是否加载系统环境变量，默认 `true`。 |
+
+---
+
+### 🎨 错误报告：长什么样？
+
+当校验失败时，`safe-env` 会在控制台打印一个显眼的表格，告诉你哪个字段错了、原因是什么以及当前的值。在浏览器中这会抛出一个 Error 阻止应用启动，在 Node.js 中会直接 `process.exit(1)`。
+
+---
+
+### 📦 跨平台支持
+- **前端**: Vite (Vue/React/Vanilla)。
+- **后端**: Node.js (ESM/CJS)。

package/dist/chunk-5ZP5OWCL.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }var _fs = require('fs'); var _fs2 = _interopRequireDefault(_fs);var _path = require('path'); var _path2 = _interopRequireDefault(_path);function s(i){let r={},c=i.split(/\r?\n/);for(let f of c){let n=f.trim();if(!n||n.startsWith("#"))continue;let e=n.indexOf("=");if(e==-1)continue;let l=n.slice(0,e).trim(),t=n.slice(e+1).trim();(t.startsWith('"')&&t.endsWith('"')||t.startsWith("'")&&t.endsWith("'"))&&(t=t.slice(1,-1)),r[l]=t}return r}function a(i=".env"){try{let r=_path2.default.resolve(process.cwd(),i);if(_fs2.default.existsSync(r))return s(_fs2.default.readFileSync(r,"utf-8"))}catch (e2){}return{}}exports.a = s; exports.b = a;

package/dist/chunk-BEFKPDEA.js

@@ -0,0 +1 @@
+import o from"fs";import d from"path";function s(i){let r={},c=i.split(/\r?\n/);for(let f of c){let n=f.trim();if(!n||n.startsWith("#"))continue;let e=n.indexOf("=");if(e==-1)continue;let l=n.slice(0,e).trim(),t=n.slice(e+1).trim();(t.startsWith('"')&&t.endsWith('"')||t.startsWith("'")&&t.endsWith("'"))&&(t=t.slice(1,-1)),r[l]=t}return r}function a(i=".env"){try{let r=d.resolve(process.cwd(),i);if(o.existsSync(r))return s(o.readFileSync(r,"utf-8"))}catch{}return{}}export{s as a,a as b};

package/dist/fs-browser.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});function t(n=".env"){return{}}exports.loadDotEnv = t;

package/dist/fs-browser.d.cts

@@ -0,0 +1,6 @@
+/**
+ * 浏览器端不需要读取文件，所以返回空对象
+ */
+declare function loadDotEnv(_filePath?: string): Record<string, string>;
+
+export { loadDotEnv };

package/dist/fs-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 浏览器端不需要读取文件，所以返回空对象
+ */
+declare function loadDotEnv(_filePath?: string): Record<string, string>;
+
+export { loadDotEnv };

package/dist/fs-browser.js

@@ -0,0 +1 @@
+function t(n=".env"){return{}}export{t as loadDotEnv};

package/dist/fs-node.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk5ZP5OWCLcjs = require('./chunk-5ZP5OWCL.cjs');exports.loadDotEnv = _chunk5ZP5OWCLcjs.b;

package/dist/fs-node.d.cts

@@ -0,0 +1,3 @@
+declare function loadDotEnv(filePath?: string): Record<string, string>;
+
+export { loadDotEnv };

package/dist/fs-node.d.ts

@@ -0,0 +1,3 @@
+declare function loadDotEnv(filePath?: string): Record<string, string>;
+
+export { loadDotEnv };

package/dist/fs-node.js

@@ -0,0 +1 @@
+import{b as a}from"./chunk-BEFKPDEA.js";export{a as loadDotEnv};

package/dist/index.cjs

@@ -0,0 +1,5 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk5ZP5OWCLcjs = require('./chunk-5ZP5OWCL.cjs');function u(r,e,n,s=[]){return{type:r,default:e,required:e===void 0,parse:n,metadata:s.length?{options:s}:{},from(o){return this.sourceKey=o,this},validate(o,m="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:o,message:m}},this},min(o){return this.metadata={...this.metadata,min:o},this},max(o){return this.metadata={...this.metadata,max:o},this}}}var x={string:r=>u("string",r,e=>String(e)),number:r=>u("number",r,e=>{let n=Number(e);if(isNaN(n))throw new Error(`Invalid number: ${e}`);return n}),boolean:r=>u("boolean",r,e=>e==="true"||e===!0),enum:(r,e)=>u("enum",e,n=>{if(!r.includes(n))throw new Error(`Value "${n}" is not one of: ${r.join(", ")}`);return n},r)};function h(r){let e={r:"\x1B[31m",g:"\x1B[32m",y:"\x1B[33m",b:"\x1B[1m",res:"\x1B[0m",d:"\x1B[2m"};console.error(`
+${e.r}${e.b}\u274C SafeEnv Error${e.res}
+${e.d}${"".padEnd(40,"-")}${e.res}`),r.forEach(n=>{let s=n.value===void 0?"undefined":`"${n.value}"`;console.error(`${e.y}${n.key}${e.res} ${e.r}${n.error}${e.res} ${e.d}${s}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
+${e.g}\u{1F4A1} Check your .env files.${e.res}
+`)}function D(r,e={}){let{loadProcessEnv:n=!0,source:s,prefix:l=""}=e,o;if(s)o=s;else{let i=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),a=[".env",".env.local",`.env.${i}`,`.env.${i}.local`],f={};for(let d of a)f={...f,..._chunk5ZP5OWCLcjs.b.call(void 0, d)};o={...f,...n&&typeof process<"u"?process.env:{}}}let m={},c=[];for(let i in r){let a=r[i],f=a.sourceKey||(o[l+i]!==void 0?l+i:i),d=o[f];try{let t;if(d===void 0||d===""&&a.default!==void 0){if(a.required&&d===void 0)throw new Error("Required field missing");t=a.default}else t=a.parse(d);if(t!==void 0&&a.metadata){let{min:p,max:E,validate:v}=a.metadata;if(typeof t=="number"){if(p!==void 0&&t<p)throw new Error(`Below min ${p}`);if(E!==void 0&&t>E)throw new Error(`Above max ${E}`)}if(v&&!v.fn(t))throw new Error(v.message)}m[i]=t}catch(t){c.push({key:f,error:t.message,value:d})}}if(c.length>0)if(h(c),typeof process<"u"&&!!process.exit&&!s)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.");return m}exports.loadDotEnv = _chunk5ZP5OWCLcjs.b; exports.parseDotEnv = _chunk5ZP5OWCLcjs.a; exports.reportErrors = h; exports.s = x; exports.safeEnv = D;

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+export { loadDotEnv } from './fs-node.cjs';
+
+type BaseType = "string" | "number" | "boolean" | "enum";
+interface FieldDefinition<T = any> {
+    type: BaseType;
+    default?: T;
+    required: boolean;
+    sourceKey?: string;
+    metadata?: {
+        min?: number;
+        max?: number;
+        options?: T[];
+        validate?: {
+            fn: (val: T) => boolean;
+            message: string;
+        };
+    };
+    parse: (val: any) => T;
+    from: (key: string) => FieldDefinition<T>;
+    validate: (fn: (val: T) => boolean, message?: string) => FieldDefinition<T>;
+    min: (val: number) => FieldDefinition<T>;
+    max: (val: number) => FieldDefinition<T>;
+}
+type Schema = Record<string, FieldDefinition>;
+interface EnvError {
+    key: string;
+    error: string;
+    value: any;
+}
+type InferSchema<T> = {
+    [K in keyof T]: T[K] extends FieldDefinition<infer U> ? U : never;
+};
+
+declare const s: {
+    string: (defaultValue?: string) => FieldDefinition<string>;
+    number: (defaultValue?: number) => FieldDefinition<number>;
+    boolean: (defaultValue?: boolean) => FieldDefinition<boolean>;
+    enum: <T extends string>(options: T[], defaultValue?: T) => FieldDefinition<T>;
+};
+
+interface SafeEnvOptions {
+    mode?: string;
+    loadProcessEnv?: boolean;
+    source?: Record<string, any>;
+    prefix?: string;
+}
+declare function safeEnv<T extends Schema>(schema: T, options?: SafeEnvOptions): InferSchema<T>;
+
+/***
+ *  将 .env 内容字符串解析为对象
+ * */
+declare function parseDotEnv(content: string): Record<string, string>;
+
+declare function reportErrors(errors: EnvError[]): void;
+
+export { type BaseType, type EnvError, type FieldDefinition, type InferSchema, type Schema, parseDotEnv, reportErrors, s, safeEnv };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export { loadDotEnv } from './fs-node.js';
+
+type BaseType = "string" | "number" | "boolean" | "enum";
+interface FieldDefinition<T = any> {
+    type: BaseType;
+    default?: T;
+    required: boolean;
+    sourceKey?: string;
+    metadata?: {
+        min?: number;
+        max?: number;
+        options?: T[];
+        validate?: {
+            fn: (val: T) => boolean;
+            message: string;
+        };
+    };
+    parse: (val: any) => T;
+    from: (key: string) => FieldDefinition<T>;
+    validate: (fn: (val: T) => boolean, message?: string) => FieldDefinition<T>;
+    min: (val: number) => FieldDefinition<T>;
+    max: (val: number) => FieldDefinition<T>;
+}
+type Schema = Record<string, FieldDefinition>;
+interface EnvError {
+    key: string;
+    error: string;
+    value: any;
+}
+type InferSchema<T> = {
+    [K in keyof T]: T[K] extends FieldDefinition<infer U> ? U : never;
+};
+
+declare const s: {
+    string: (defaultValue?: string) => FieldDefinition<string>;
+    number: (defaultValue?: number) => FieldDefinition<number>;
+    boolean: (defaultValue?: boolean) => FieldDefinition<boolean>;
+    enum: <T extends string>(options: T[], defaultValue?: T) => FieldDefinition<T>;
+};
+
+interface SafeEnvOptions {
+    mode?: string;
+    loadProcessEnv?: boolean;
+    source?: Record<string, any>;
+    prefix?: string;
+}
+declare function safeEnv<T extends Schema>(schema: T, options?: SafeEnvOptions): InferSchema<T>;
+
+/***
+ *  将 .env 内容字符串解析为对象
+ * */
+declare function parseDotEnv(content: string): Record<string, string>;
+
+declare function reportErrors(errors: EnvError[]): void;
+
+export { type BaseType, type EnvError, type FieldDefinition, type InferSchema, type Schema, parseDotEnv, reportErrors, s, safeEnv };

package/dist/index.js

@@ -0,0 +1,5 @@
+import{a as b,b as $}from"./chunk-BEFKPDEA.js";function u(r,e,n,s=[]){return{type:r,default:e,required:e===void 0,parse:n,metadata:s.length?{options:s}:{},from(o){return this.sourceKey=o,this},validate(o,m="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:o,message:m}},this},min(o){return this.metadata={...this.metadata,min:o},this},max(o){return this.metadata={...this.metadata,max:o},this}}}var x={string:r=>u("string",r,e=>String(e)),number:r=>u("number",r,e=>{let n=Number(e);if(isNaN(n))throw new Error(`Invalid number: ${e}`);return n}),boolean:r=>u("boolean",r,e=>e==="true"||e===!0),enum:(r,e)=>u("enum",e,n=>{if(!r.includes(n))throw new Error(`Value "${n}" is not one of: ${r.join(", ")}`);return n},r)};function h(r){let e={r:"\x1B[31m",g:"\x1B[32m",y:"\x1B[33m",b:"\x1B[1m",res:"\x1B[0m",d:"\x1B[2m"};console.error(`
+${e.r}${e.b}\u274C SafeEnv Error${e.res}
+${e.d}${"".padEnd(40,"-")}${e.res}`),r.forEach(n=>{let s=n.value===void 0?"undefined":`"${n.value}"`;console.error(`${e.y}${n.key}${e.res} ${e.r}${n.error}${e.res} ${e.d}${s}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
+${e.g}\u{1F4A1} Check your .env files.${e.res}
+`)}function D(r,e={}){let{loadProcessEnv:n=!0,source:s,prefix:l=""}=e,o;if(s)o=s;else{let i=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),a=[".env",".env.local",`.env.${i}`,`.env.${i}.local`],f={};for(let d of a)f={...f,...$(d)};o={...f,...n&&typeof process<"u"?process.env:{}}}let m={},c=[];for(let i in r){let a=r[i],f=a.sourceKey||(o[l+i]!==void 0?l+i:i),d=o[f];try{let t;if(d===void 0||d===""&&a.default!==void 0){if(a.required&&d===void 0)throw new Error("Required field missing");t=a.default}else t=a.parse(d);if(t!==void 0&&a.metadata){let{min:p,max:E,validate:v}=a.metadata;if(typeof t=="number"){if(p!==void 0&&t<p)throw new Error(`Below min ${p}`);if(E!==void 0&&t>E)throw new Error(`Above max ${E}`)}if(v&&!v.fn(t))throw new Error(v.message)}m[i]=t}catch(t){c.push({key:f,error:t.message,value:d})}}if(c.length>0)if(h(c),typeof process<"u"&&!!process.exit&&!s)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.");return m}export{$ as loadDotEnv,b as parseDotEnv,h as reportErrors,x as s,D as safeEnv};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zh-moody/safe-env",
+  "version": "0.1.0",
+  "description": "",
+  "author": "Moody",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "browser": {
+    "./dist/fs-node.js": "./dist/fs-browser.js",
+    "./dist/fs-node.cjs": "./dist/fs-browser.js"
+  },
+  "scripts": {
+    "dev": "tsup src/index.ts src/fs-node.ts src/fs-browser.ts --watch",
+    "build": "tsup src/index.ts src/fs-node.ts src/fs-browser.ts --format cjs,esm --dts --minify --clean --splitting",
+    "test": "vitest run"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "keywords": [],
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  }
+}