@zh-moody/safe-env 0.2.0 → 0.3.0

package/README.md

@@ -10,82 +10,69 @@
 
 ---
 
-### 🔗 链接 (Links)
-
-- **GitHub Repository**: [https://github.com/zhMoody/safe-env](https://github.com/zhMoody/safe-env)
-- **NPM Package**: [https://www.npmjs.com/package/@zh-moody/safe-env](https://www.npmjs.com/package/@zh-moody/safe-env)
-
----
-
 ### 🚀 核心特性
 
+- **构建时预校验**：提供 Vite 插件，在 `npm run dev` 或 `build` 的瞬间拦截错误，无需打开浏览器。
+- **IDE 增强**：支持 `.description()` 字段，直接在代码中通过悬停查看变量用途。
+- **更强的数据转换**：内置 `s.array()`, `s.boolean()` 增强转换，支持 `.transform()` 链式 Pipe 处理。
+- **内置常用规则**：提供 `.url()`, `.email()`, `.regex()` 等高频校验，无需依赖 zod。
 - **类型安全**：自动推断配置对象类型，拥有完美的 IDE 补全。
-- **链式校验**：内置 `min`, `max`, `validate`, `enum` 等校验逻辑。
-- **自动前缀**：支持 `VITE_` 或 `REACT_APP_` 自动补全，代码里用 `PORT`，配置里用 `VITE_PORT`。
-- **跨端兼容**：自动识别 Node/浏览器环境，支持双端“防御性退出”。
-- **极致轻量**：Minified 体积约 **2.6 KB**，Gzip 后仅 **1.3 KB**，零运行时依赖。
+- **极致轻量**：Minified 体积约 **2KB**，零运行时依赖。
 
 ---
 
 ### 🚀 快速上手
 
-#### 🔹 [Vite / React / Vue] 端使用
-在前端，环境变量由构建工具（如 Vite）注入到 `import.meta.env` 中。
+#### 🔹 [Vite / React / Vue] 使用
+在前端，建议配合 Vite 插件实现**构建时校验**。
 
-**1. 准备 `.env` 文件：**
-```bash
-VITE_API_URL=https://api.com
-VITE_PORT=3000
+**1. 配置 Vite 插件 (`vite.config.ts`)：**
+```typescript
+import { viteSafeEnv } from '@zh-moody/safe-env/vite';
+import { schema } from './src/env'; // 建议将 schema 提取到独立文件
+
+export default {
+  plugins: [
+    viteSafeEnv(schema) // 构建时校验，配置错误直接停止构建
+  ]
+}
 ```
 
-**2. 定义配置 (`src/env.ts`)：**
+**2. 定义配置并导出 (`src/env.ts`)：**
 ```typescript
 import { safeEnv, s } from '@zh-moody/safe-env';
 
-export const config = safeEnv({
-  apiUrl: s.string().from('VITE_API_URL'), // 别名映射
-  port: s.number(3000).from('VITE_PORT'),
-}, { 
-  source: import.meta.env // ⚠️ 浏览器端必须手动传入数据源
+export const schema = {
+  VITE_API_URL: s.string().url().description("后端 API 地址"),
+  VITE_PORT: s.number(3000).description("服务端口"),
+  VITE_FEATURES: s.array().description("启用的特性列表")
+};
+
+export const env = safeEnv(schema, { 
+  source: import.meta.env 
 });
 ```
 
 ---
 
-#### 🔸 [Node.js / 服务端] 端使用
+#### 🔸 [Node.js / 服务端] 使用
 在后端，库会自动寻找并解析磁盘上的 `.env` 文件。
 
-**1. 准备 `.env` 文件：**
-```bash
-DB_HOST=localhost
-DB_PORT=5432
-```
-
-**2. 定义配置 (`src/db.ts`)：**
+**1. 定义配置 (`src/config.ts`)：**
 ```typescript
 import { safeEnv, s } from '@zh-moody/safe-env';
 
-const dbConfig = safeEnv({
-  DB_HOST: s.string('localhost'),
-  DB_PORT: s.number(5432)
-}); // ⚠️ Node 端无需传 source，会自动读取文件
+const config = safeEnv({
+  DB_HOST: s.string('localhost').description("数据库主机"),
+  DB_PORT: s.number(5432).min(1).max(65535),
+  ADMIN_EMAIL: s.string().email()
+});
 
-export default dbConfig;
+export default config;
 ```
 
 ---
 
-### 📂 核心对比：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`)
@@ -93,63 +80,65 @@ export default dbConfig;
 - `s.number(default?)`: 数字。自动将字符串转为 `number`。
 - `s.boolean(default?)`: 布尔型。支持将 `"true"`, `"1"`, `"yes"`, `"on"` 解析为 `true`（大小写无关）。
 - `s.array(default?, separator?)`: 数组型。支持将字符串按分隔符（默认 `,`）拆分为数组。
-  - 示例：`s.array([], '|')`
 - `s.enum(options, default?)`: 枚举。值必须在数组中。
-  - 示例：`s.enum(['dev', 'prod'], 'dev')`
 
-#### 2. 数据处理与增强 (链式调用)
-每个通过 `s` 定义的字段都可以调用以下方法进行增强：
+#### 2. 校验与增强 (链式调用)
+
+每个字段都可以通过链式调用进行深度定制：
 
-- **`.transform(fn)`**: **[New]** 自定义数据转换，支持链式调用。
+- **`.url()`**: 校验是否为合法 URL 格式。
+  ```typescript
+  API_URL: s.string().url()
+  ```
+- **`.email()`**: 校验是否为合法邮箱格式。
   ```typescript
-  // 示例 1: 将字符串转大写
-  KEY: s.string().transform(v => v.toUpperCase())
+  CONTACT: s.string().email()
+  ```
+- **`.regex(pattern, msg?)`**: 自定义正则校验。
+  ```typescript
+  VERSION: s.string().regex(/^v\d+\.\d+\.\d+$/, "版本号必须以 v 开头")
+  ```
+- **`.description(text)`**: 添加变量描述。该描述会映射到 IDE 的悬停提示中。
+  ```typescript
+  PORT: s.number(3000).description("本地服务器端口")
+  ```
+- **`.transform(fn)`**: 自定义数据转换，支持多级链式 Pipe。
+  ```typescript
+  // 示例 1: 拿到字符串 -> 去空格 -> 转大写
+  NAME: s.string().transform(v => v.trim()).transform(v => v.toUpperCase())
 
   // 示例 2: 将逗号分隔的数字字符串转为数字数组
   SCORES: s.array().transform(arr => arr.map(Number))
   ```
-
-- **`.from(key)`**: 指定环境变量名。
+- **`.from(key)`**: 映射环境变量名（别名）。
   ```typescript
-  // 即使变量叫 VITE_PATH，代码里也可以叫 port
-  port: s.number().from('VITE_PATH')
+  // 即使环境变量叫 VITE_SERVER_PORT，代码里也可以叫 port
+  port: s.number().from('VITE_SERVER_PORT')
   ```
-
 - **`.min(n)` / `.max(n)`**: 限制数字取值范围。
   ```typescript
-  // 端口必须在 1-65535 之间
-  PORT: s.number().min(1).max(65535)
+  // 端口必须在 1024-65535 之间
+  PORT: s.number().min(1024).max(65535)
   ```
-
-- **`.validate(fn, msg?)`**: 自定义校验（如：邮箱、URL 格式）。
+- **`.validate(fn, msg?)`**: 完全自定义的校验逻辑。
   ```typescript
-  // 必须是安全地址
-  API: s.string().validate(v => v.startsWith('https'), 'Must be HTTPS')
+  // 必须是特定的内部域名
+  INTERNAL_URL: s.string().validate(v => v.endsWith('.internal.com'), 'Must be an internal URL')
   ```
 
-#### 3. 加载选项 (`SafeEnvOptions`)
-
-| 选项 | 适用环境 | 说明 |
-| :--- | :--- | :--- |
-| `source` | **[Vite/浏览器]** | **必填**。传入 `import.meta.env` 或 `process.env`。 |
-| `prefix` | **通用** | **可选**。自动补全前缀，如 `prefix: 'VITE_'`。 |
-| `mode` | **[Node.js]** | **可选**。指定模式（dev/prod）以加载对应的 `.env.prod` 等文件。 |
-| `loadProcessEnv` | **[Node.js]** | **可选**。是否加载系统环境变量，默认 `true`。 |
+#### 3. 加载规则 (Env Priority)
+`safe-env` 遵循标准的优先级顺序（从低到高）：
+1. `.env` (基础配置)
+2. `.env.[mode]` (环境配置，如 `.env.development`)
+3. `.env.local` (本地覆盖)
+4. `.env.[mode].local` (环境特定的本地覆盖)
 
 ---
 
-### 🎨 错误报告：长什么样？
-
-当校验失败时，`safe-env` 会在控制台打印一个显眼的表格，告诉你哪个字段错了、原因是什么以及当前的值。在浏览器中这会抛出一个 Error 阻止应用启动，在 Node.js 中会直接 `process.exit(1)`。
-
----
-
-### 📦 跨平台支持
-- **前端**: Vite (Vue/React/Vanilla)。
-- **后端**: Node.js (ESM/CJS)。
+### 🎨 错误报告
+当校验失败时，`safe-env` 会在控制台打印精美的表格，清晰展示：**Key / 错误原因 / 当前值**。
 
 ---
 
 ### 📄 开源协议 (License)
-
-[MIT License](./LICENSE) - Copyright (c) 2025 Moody.
+[MIT License](./LICENSE) - Copyright (c) 2026 Moody.

package/dist/{chunk-5ZP5OWCL.cjs → chunk-FH2DFX4J.cjs}

@@ -1 +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;
+"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 h(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 = h;

package/dist/{chunk-BEFKPDEA.js → chunk-POVTEBYN.js}

@@ -1 +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};
+import o from"fs";import a 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 h(i=".env"){try{let r=a.resolve(process.cwd(),i);if(o.existsSync(r))return s(o.readFileSync(r,"utf-8"))}catch{}return{}}export{s as a,h as b};

package/dist/chunk-YZVFZGPW.js

@@ -0,0 +1,5 @@
+import{b as v}from"./chunk-POVTEBYN.js";function $(f){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}`),f.forEach(t=>{let d=t.value===void 0?"undefined":`"${t.value}"`;console.error(`${e.y}${t.key}${e.res} ${e.r}${t.error}${e.res} ${e.d}${d}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
+${e.g}\u{1F4A1} Check your .env files.${e.res}
+`)}function h(f,e={}){let{loadProcessEnv:t=!0,source:d,prefix:p=""}=e,a;if(d!==void 0)a=d||{};else{let n=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),r=[".env",`.env.${n}`,".env.local",`.env.${n}.local`],i={};for(let s of r)i={...i,...v(s)};a={...i,...t&&typeof process<"u"?process.env:{}}}let E={},c=[];for(let n in f){let r=f[n],i=r.sourceKey||(a[p+n]!==void 0?p+n:n),s=a[i];try{let o;if(s===void 0||s===""&&r.default!==void 0){if(r.required&&s===void 0)throw new Error("Required field missing");o=r.default}else o=r.parse(s);if(o!==void 0&&r.metadata){let{min:l,max:u,validate:m}=r.metadata;if(typeof o=="number"){if(l!==void 0&&o<l)throw new Error(`Below min ${l}`);if(u!==void 0&&o>u)throw new Error(`Above max ${u}`)}if(m&&!m.fn(o))throw new Error(m.message)}E[n]=o}catch(o){c.push({key:i,error:o.message,value:s})}}if(c.length>0){$(c);let n=typeof process<"u"&&!!process.exit,r=typeof process<"u"&&process.env.NODE_ENV==="test";if(n&&!d&&!r)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.")}return E}export{$ as a,h as b};

package/dist/chunk-ZMFWDJAZ.cjs

@@ -0,0 +1,5 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkFH2DFX4Jcjs = require('./chunk-FH2DFX4J.cjs');function $(f){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}`),f.forEach(t=>{let d=t.value===void 0?"undefined":`"${t.value}"`;console.error(`${e.y}${t.key}${e.res} ${e.r}${t.error}${e.res} ${e.d}${d}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
+${e.g}\u{1F4A1} Check your .env files.${e.res}
+`)}function h(f,e={}){let{loadProcessEnv:t=!0,source:d,prefix:p=""}=e,a;if(d!==void 0)a=d||{};else{let n=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),r=[".env",`.env.${n}`,".env.local",`.env.${n}.local`],i={};for(let s of r)i={...i,..._chunkFH2DFX4Jcjs.b.call(void 0, s)};a={...i,...t&&typeof process<"u"?process.env:{}}}let E={},c=[];for(let n in f){let r=f[n],i=r.sourceKey||(a[p+n]!==void 0?p+n:n),s=a[i];try{let o;if(s===void 0||s===""&&r.default!==void 0){if(r.required&&s===void 0)throw new Error("Required field missing");o=r.default}else o=r.parse(s);if(o!==void 0&&r.metadata){let{min:l,max:u,validate:m}=r.metadata;if(typeof o=="number"){if(l!==void 0&&o<l)throw new Error(`Below min ${l}`);if(u!==void 0&&o>u)throw new Error(`Above max ${u}`)}if(m&&!m.fn(o))throw new Error(m.message)}E[n]=o}catch(o){c.push({key:i,error:o.message,value:s})}}if(c.length>0){$(c);let n=typeof process<"u"&&!!process.exit,r=typeof process<"u"&&process.env.NODE_ENV==="test";if(n&&!d&&!r)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.")}return E}exports.a = $; exports.b = h;

package/dist/fs-node.cjs

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

package/dist/fs-node.js

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

package/dist/index.cjs

@@ -1,5 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk5ZP5OWCLcjs = require('./chunk-5ZP5OWCL.cjs');function m(n,e,r,i=[]){return{type:n,default:e,required:e===void 0,parse:r,metadata:i.length?{options:i}:{},from(o){return this.sourceKey=o,this},validate(o,f="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:o,message:f}},this},min(o){return this.metadata={...this.metadata,min:o},this},max(o){return this.metadata={...this.metadata,max:o},this},transform(o){let f=this.parse;return this.parse=u=>o(f(u)),this}}}var g={string:n=>m("string",n,e=>String(e)),number:n=>m("number",n,e=>{let r=Number(e);if(isNaN(r))throw new Error(`Invalid number: ${e}`);return r}),boolean:n=>m("boolean",n,e=>{if(typeof e=="boolean")return e;let r=String(e).toLowerCase();return r==="true"||r==="1"||r==="yes"||r==="on"}),enum:(n,e)=>m("enum",e,r=>{if(!n.includes(r))throw new Error(`Value "${r}" is not one of: ${n.join(", ")}`);return r},n),array:(n,e=",")=>m("array",n,r=>Array.isArray(r)?r:typeof r!="string"?[]:r.split(e).map(i=>i.trim()).filter(Boolean))};function $(n){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}`),n.forEach(r=>{let i=r.value===void 0?"undefined":`"${r.value}"`;console.error(`${e.y}${r.key}${e.res} ${e.r}${r.error}${e.res} ${e.d}${i}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
-${e.g}\u{1F4A1} Check your .env files.${e.res}
-`)}function D(n,e={}){let{loadProcessEnv:r=!0,source:i,prefix:c=""}=e,o;if(i)o=i;else{let a=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),s=[".env",".env.local",`.env.${a}`,`.env.${a}.local`],l={};for(let d of s)l={...l,..._chunk5ZP5OWCLcjs.b.call(void 0, d)};o={...l,...r&&typeof process<"u"?process.env:{}}}let f={},u=[];for(let a in n){let s=n[a],l=s.sourceKey||(o[c+a]!==void 0?c+a:a),d=o[l];try{let t;if(d===void 0||d===""&&s.default!==void 0){if(s.required&&d===void 0)throw new Error("Required field missing");t=s.default}else t=s.parse(d);if(t!==void 0&&s.metadata){let{min:p,max:y,validate:E}=s.metadata;if(typeof t=="number"){if(p!==void 0&&t<p)throw new Error(`Below min ${p}`);if(y!==void 0&&t>y)throw new Error(`Above max ${y}`)}if(E&&!E.fn(t))throw new Error(E.message)}f[a]=t}catch(t){u.push({key:l,error:t.message,value:d})}}if(u.length>0)if($(u),typeof process<"u"&&!!process.exit&&!i)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.");return f}exports.loadDotEnv = _chunk5ZP5OWCLcjs.b; exports.parseDotEnv = _chunk5ZP5OWCLcjs.a; exports.reportErrors = $; exports.s = g; exports.safeEnv = D;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkZMFWDJAZcjs = require('./chunk-ZMFWDJAZ.cjs');var _chunkFH2DFX4Jcjs = require('./chunk-FH2DFX4J.cjs');function a(n,i,e,o=[]){return{type:n,default:i,required:i===void 0,parse:e,metadata:o.length?{options:o}:{},from(t){return this.sourceKey=t,this},validate(t,r="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:t,message:r}},this},min(t){return this.metadata={...this.metadata,min:t},this},max(t){return this.metadata={...this.metadata,max:t},this},transform(t){let r=this.parse;return this.parse=s=>t(r(s)),this},url(){return this.validate(t=>{try{return new URL(String(t)),!0}catch (e2){return!1}},"Invalid URL format")},email(){let t=/^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/;return this.validate(r=>t.test(String(r)),"Invalid email format")},regex(t,r="Value does not match pattern"){return this.validate(s=>t.test(String(s)),r)},description(t){return this.metadata={...this.metadata,description:t},this}}}var f={string:n=>a("string",n,i=>String(i)),number:n=>a("number",n,i=>{let e=Number(i);if(isNaN(e))throw new Error(`Invalid number: ${i}`);return e}),boolean:n=>a("boolean",n,i=>{if(typeof i=="boolean")return i;let e=String(i).toLowerCase();return e==="true"||e==="1"||e==="yes"||e==="on"}),enum:(n,i)=>a("enum",i,e=>{if(!n.includes(e))throw new Error(`Value "${e}" is not one of: ${n.join(", ")}`);return e},n),array:(n,i=",")=>a("array",n,e=>Array.isArray(e)?e:typeof e!="string"?[]:e.split(i).map(o=>o.trim()).filter(Boolean))};exports.parseDotEnv = _chunkFH2DFX4Jcjs.a; exports.reportErrors = _chunkZMFWDJAZcjs.a; exports.s = f; exports.safeEnv = _chunkZMFWDJAZcjs.b;

package/dist/index.d.cts

@@ -1,36 +1,5 @@
-export { loadDotEnv } from './fs-node.cjs';
-
-type BaseType = "string" | "number" | "boolean" | "enum" | "array";
-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>;
-    transform: <U>(fn: (val: T) => U) => FieldDefinition<U>;
-}
-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;
-};
+import { F as FieldDefinition, S as Schema, I as InferSchema, E as EnvError } from './types-B59cqDDx.cjs';
+export { B as BaseType } from './types-B59cqDDx.cjs';
 
 declare const s: {
     string: (defaultValue?: string) => FieldDefinition<string>;
@@ -55,4 +24,4 @@ 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 };
+export { EnvError, FieldDefinition, InferSchema, Schema, parseDotEnv, reportErrors, s, safeEnv };

package/dist/index.d.ts

@@ -1,36 +1,5 @@
-export { loadDotEnv } from './fs-node.js';
-
-type BaseType = "string" | "number" | "boolean" | "enum" | "array";
-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>;
-    transform: <U>(fn: (val: T) => U) => FieldDefinition<U>;
-}
-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;
-};
+import { F as FieldDefinition, S as Schema, I as InferSchema, E as EnvError } from './types-B59cqDDx.js';
+export { B as BaseType } from './types-B59cqDDx.js';
 
 declare const s: {
     string: (defaultValue?: string) => FieldDefinition<string>;
@@ -55,4 +24,4 @@ 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 };
+export { EnvError, FieldDefinition, InferSchema, Schema, parseDotEnv, reportErrors, s, safeEnv };

package/dist/index.js

@@ -1,5 +1 @@
-import{a as b,b as h}from"./chunk-BEFKPDEA.js";function m(n,e,r,i=[]){return{type:n,default:e,required:e===void 0,parse:r,metadata:i.length?{options:i}:{},from(o){return this.sourceKey=o,this},validate(o,f="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:o,message:f}},this},min(o){return this.metadata={...this.metadata,min:o},this},max(o){return this.metadata={...this.metadata,max:o},this},transform(o){let f=this.parse;return this.parse=u=>o(f(u)),this}}}var g={string:n=>m("string",n,e=>String(e)),number:n=>m("number",n,e=>{let r=Number(e);if(isNaN(r))throw new Error(`Invalid number: ${e}`);return r}),boolean:n=>m("boolean",n,e=>{if(typeof e=="boolean")return e;let r=String(e).toLowerCase();return r==="true"||r==="1"||r==="yes"||r==="on"}),enum:(n,e)=>m("enum",e,r=>{if(!n.includes(r))throw new Error(`Value "${r}" is not one of: ${n.join(", ")}`);return r},n),array:(n,e=",")=>m("array",n,r=>Array.isArray(r)?r:typeof r!="string"?[]:r.split(e).map(i=>i.trim()).filter(Boolean))};function $(n){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}`),n.forEach(r=>{let i=r.value===void 0?"undefined":`"${r.value}"`;console.error(`${e.y}${r.key}${e.res} ${e.r}${r.error}${e.res} ${e.d}${i}${e.res}`)}),console.error(`${e.d}${"".padEnd(40,"-")}${e.res}
-${e.g}\u{1F4A1} Check your .env files.${e.res}
-`)}function D(n,e={}){let{loadProcessEnv:r=!0,source:i,prefix:c=""}=e,o;if(i)o=i;else{let a=e.mode||(typeof process<"u"?process.env.NODE_ENV:"development"),s=[".env",".env.local",`.env.${a}`,`.env.${a}.local`],l={};for(let d of s)l={...l,...h(d)};o={...l,...r&&typeof process<"u"?process.env:{}}}let f={},u=[];for(let a in n){let s=n[a],l=s.sourceKey||(o[c+a]!==void 0?c+a:a),d=o[l];try{let t;if(d===void 0||d===""&&s.default!==void 0){if(s.required&&d===void 0)throw new Error("Required field missing");t=s.default}else t=s.parse(d);if(t!==void 0&&s.metadata){let{min:p,max:y,validate:E}=s.metadata;if(typeof t=="number"){if(p!==void 0&&t<p)throw new Error(`Below min ${p}`);if(y!==void 0&&t>y)throw new Error(`Above max ${y}`)}if(E&&!E.fn(t))throw new Error(E.message)}f[a]=t}catch(t){u.push({key:l,error:t.message,value:d})}}if(u.length>0)if($(u),typeof process<"u"&&!!process.exit&&!i)process.exit(1);else throw new Error("SafeEnv: Configuration validation failed.");return f}export{h as loadDotEnv,b as parseDotEnv,$ as reportErrors,g as s,D as safeEnv};
+import{a as u,b as m}from"./chunk-YZVFZGPW.js";import{a as l}from"./chunk-POVTEBYN.js";function a(n,i,e,o=[]){return{type:n,default:i,required:i===void 0,parse:e,metadata:o.length?{options:o}:{},from(t){return this.sourceKey=t,this},validate(t,r="Custom validation failed"){return this.metadata={...this.metadata,validate:{fn:t,message:r}},this},min(t){return this.metadata={...this.metadata,min:t},this},max(t){return this.metadata={...this.metadata,max:t},this},transform(t){let r=this.parse;return this.parse=s=>t(r(s)),this},url(){return this.validate(t=>{try{return new URL(String(t)),!0}catch{return!1}},"Invalid URL format")},email(){let t=/^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/;return this.validate(r=>t.test(String(r)),"Invalid email format")},regex(t,r="Value does not match pattern"){return this.validate(s=>t.test(String(s)),r)},description(t){return this.metadata={...this.metadata,description:t},this}}}var f={string:n=>a("string",n,i=>String(i)),number:n=>a("number",n,i=>{let e=Number(i);if(isNaN(e))throw new Error(`Invalid number: ${i}`);return e}),boolean:n=>a("boolean",n,i=>{if(typeof i=="boolean")return i;let e=String(i).toLowerCase();return e==="true"||e==="1"||e==="yes"||e==="on"}),enum:(n,i)=>a("enum",i,e=>{if(!n.includes(e))throw new Error(`Value "${e}" is not one of: ${n.join(", ")}`);return e},n),array:(n,i=",")=>a("array",n,e=>Array.isArray(e)?e:typeof e!="string"?[]:e.split(i).map(o=>o.trim()).filter(Boolean))};export{l as parseDotEnv,u as reportErrors,f as s,m as safeEnv};

package/dist/types-B59cqDDx.d.cts

@@ -0,0 +1,40 @@
+type BaseType = "string" | "number" | "boolean" | "enum" | "array";
+interface FieldDefinition<T = any, D extends string = string> {
+    type: BaseType;
+    default?: T;
+    required: boolean;
+    sourceKey?: string;
+    metadata?: {
+        min?: number;
+        max?: number;
+        options?: T[];
+        description?: string;
+        validate?: {
+            fn: (val: T) => boolean;
+            message: string;
+        };
+    };
+    parse: (val: any) => T;
+    from: (key: string) => FieldDefinition<T, D>;
+    validate: (fn: (val: T) => boolean, message?: string) => FieldDefinition<T, D>;
+    min: (val: number) => FieldDefinition<T, D>;
+    max: (val: number) => FieldDefinition<T, D>;
+    transform: <U>(fn: (val: T) => U) => FieldDefinition<U, D>;
+    url: () => FieldDefinition<T, D>;
+    email: () => FieldDefinition<T, D>;
+    regex: (pattern: RegExp, message?: string) => FieldDefinition<T, D>;
+    description: <NewD extends string>(text: NewD) => FieldDefinition<T, NewD>;
+}
+type Schema = Record<string, FieldDefinition<any, any>>;
+interface EnvError {
+    key: string;
+    error: string;
+    value: any;
+}
+type InferSchema<T> = {
+    [K in keyof T]: T[K] extends FieldDefinition<infer U, infer D> ? string extends D ? U : U & {
+        readonly __description?: D;
+    } : never;
+};
+
+export type { BaseType as B, EnvError as E, FieldDefinition as F, InferSchema as I, Schema as S };

package/dist/types-B59cqDDx.d.ts

@@ -0,0 +1,40 @@
+type BaseType = "string" | "number" | "boolean" | "enum" | "array";
+interface FieldDefinition<T = any, D extends string = string> {
+    type: BaseType;
+    default?: T;
+    required: boolean;
+    sourceKey?: string;
+    metadata?: {
+        min?: number;
+        max?: number;
+        options?: T[];
+        description?: string;
+        validate?: {
+            fn: (val: T) => boolean;
+            message: string;
+        };
+    };
+    parse: (val: any) => T;
+    from: (key: string) => FieldDefinition<T, D>;
+    validate: (fn: (val: T) => boolean, message?: string) => FieldDefinition<T, D>;
+    min: (val: number) => FieldDefinition<T, D>;
+    max: (val: number) => FieldDefinition<T, D>;
+    transform: <U>(fn: (val: T) => U) => FieldDefinition<U, D>;
+    url: () => FieldDefinition<T, D>;
+    email: () => FieldDefinition<T, D>;
+    regex: (pattern: RegExp, message?: string) => FieldDefinition<T, D>;
+    description: <NewD extends string>(text: NewD) => FieldDefinition<T, NewD>;
+}
+type Schema = Record<string, FieldDefinition<any, any>>;
+interface EnvError {
+    key: string;
+    error: string;
+    value: any;
+}
+type InferSchema<T> = {
+    [K in keyof T]: T[K] extends FieldDefinition<infer U, infer D> ? string extends D ? U : U & {
+        readonly __description?: D;
+    } : never;
+};
+
+export type { BaseType as B, EnvError as E, FieldDefinition as F, InferSchema as I, Schema as S };

package/dist/vite.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkZMFWDJAZcjs = require('./chunk-ZMFWDJAZ.cjs');require('./chunk-FH2DFX4J.cjs');var _vite = require('vite');function m(t,r={}){return{name:"vite-plugin-safe-env",configResolved(e){let{envDir:i=e.root,prefix:o=e.envPrefix||"VITE_"}=r,s=e.mode,v=_vite.loadEnv.call(void 0, s,i,o);try{_chunkZMFWDJAZcjs.b.call(void 0, t,{source:v,loadProcessEnv:!1})}catch (e2){process.exit(1)}}}}exports.viteSafeEnv = m;

package/dist/vite.d.cts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+import { S as Schema } from './types-B59cqDDx.cjs';
+
+interface ViteSafeEnvOptions {
+    /**
+     * 环境变量目录，默认为项目根目录
+     */
+    envDir?: string;
+    /**
+     * 环境变量前缀，默认是 VITE_
+     */
+    prefix?: string | string[];
+}
+/**
+ * Vite 插件：在构建或开发启动时校验环境变量
+ */
+declare function viteSafeEnv(schema: Schema, options?: ViteSafeEnvOptions): Plugin;
+
+export { viteSafeEnv };

package/dist/vite.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+import { S as Schema } from './types-B59cqDDx.js';
+
+interface ViteSafeEnvOptions {
+    /**
+     * 环境变量目录，默认为项目根目录
+     */
+    envDir?: string;
+    /**
+     * 环境变量前缀，默认是 VITE_
+     */
+    prefix?: string | string[];
+}
+/**
+ * Vite 插件：在构建或开发启动时校验环境变量
+ */
+declare function viteSafeEnv(schema: Schema, options?: ViteSafeEnvOptions): Plugin;
+
+export { viteSafeEnv };

package/dist/vite.js

@@ -0,0 +1 @@
+import{b as n}from"./chunk-YZVFZGPW.js";import"./chunk-POVTEBYN.js";import{loadEnv as a}from"vite";function m(t,r={}){return{name:"vite-plugin-safe-env",configResolved(e){let{envDir:i=e.root,prefix:o=e.envPrefix||"VITE_"}=r,s=e.mode,v=a(s,i,o);try{n(t,{source:v,loadProcessEnv:!1})}catch{process.exit(1)}}}}export{m as viteSafeEnv};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zh-moody/safe-env",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Type-safe environment variables for Node.js and Browser with schema validation.",
   "author": "Moody",
   "license": "MIT",
@@ -26,8 +26,8 @@
     "./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",
+    "dev": "tsup src/index.ts src/vite.ts src/fs-node.ts src/fs-browser.ts --watch",
+    "build": "tsup src/index.ts src/vite.ts src/fs-node.ts src/fs-browser.ts --format cjs,esm --dts --minify --clean --splitting",
     "test": "vitest run"
   },
   "exports": {
@@ -35,6 +35,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "require": "./dist/vite.cjs"
     }
   },
   "keywords": [
@@ -49,10 +54,14 @@
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "vite": ">=3.0.0"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "vite": "^6.2.0",
     "vitest": "^4.1.2"
   }
 }