@ubean/shared 0.6.8 → 0.7.0

package/README.md

@@ -73,18 +73,21 @@ isNodeRuntime(); // false on Cloudflare Workers
 
 ## Environment Variables
 
-`defineEnv(config)` validates a constructor-based schema and returns `{ env, validate }`. `server` keys are never exposed to the client; `public` keys are exposed via `import.meta.env`.
+`defineEnv(config)` validates a schema and returns `{ env, validate }`. Every field declares its own `context` (`client` | `server`) and `access` (`public` | `secret`) via `envField.*()` — the same shape `ubean.config.ts` accepts under `env.schema`.
 
 ```ts
-import { defineEnv } from '@ubean/shared';
+import { defineEnv, envField } from '@ubean/shared';
 
 export const { env, validate } = defineEnv({
-  server: {
-    DATABASE_URL: { type: String, required: true },
-    PORT: { type: Number, default: 9527 }
-  },
-  public: {
-    APP_NAME: { type: String, default: 'ubean-app' }
+  schema: {
+    DATABASE_URL: envField.string({ context: 'server', access: 'secret', optional: true }),
+    PORT: envField.number({ context: 'server', access: 'public', default: 9527 }),
+    APP_NAME: envField.string({
+      context: 'client',
+      access: 'public',
+      default: 'ubean-app',
+      description: 'Shown in the header'
+    })
   },
   mode: 'warn' // 'warn' logs; 'throw' rethrows on validation failure
 });
@@ -93,6 +96,10 @@ env.PORT; // number
 validate(); // { success, errors, data }
 ```
 
+Every builder also accepts `description`, emitted as JSDoc in the generated `.ubean/env.d.ts`. Grouped `server:` / `public:` schemas are gone: dimensions live on the field, so nothing silently changes meaning when an entry moves between groups. `client` + `secret` throws at declaration time. The constructor shape (`{ type: String }`) still parses under `schema`, but it has no dimension to read from, so it is treated as `server + secret` (the conservative choice).
+
+For zod / valibot-grade validation, `defineEnv()` also accepts Standard Schema and `safeParse` shapes — it shares a process with the validator, unlike the generated env modules. Validation must be synchronous.
+
 | API                                              | Description                                                                           |
 | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
 | `defineEnv(config)`                              | Validate a schema and return `{ env, validate }` (`DefineEnvResult<S>`)               |

package/README.zh-CN.md

@@ -73,18 +73,21 @@ isNodeRuntime(); // Cloudflare Workers 上为 false
 
 ## 环境变量
 
-`defineEnv(config)` 校验基于构造函数的 schema，返回 `{ env, validate }`。`server` 键永不暴露给客户端；`public` 键通过 `import.meta.env` 暴露。
+`defineEnv(config)` 校验 schema 并返回 `{ env, validate }`。每个字段用 `envField.*()` 自带 `context`（`client` | `server`）与 `access`（`public` | `secret`）—— 与 `ubean.config.ts` 的 `env.schema` 完全同形。
 
 ```ts
-import { defineEnv } from '@ubean/shared';
+import { defineEnv, envField } from '@ubean/shared';
 
 export const { env, validate } = defineEnv({
-  server: {
-    DATABASE_URL: { type: String, required: true },
-    PORT: { type: Number, default: 9527 }
-  },
-  public: {
-    APP_NAME: { type: String, default: 'ubean-app' }
+  schema: {
+    DATABASE_URL: envField.string({ context: 'server', access: 'secret', optional: true }),
+    PORT: envField.number({ context: 'server', access: 'public', default: 9527 }),
+    APP_NAME: envField.string({
+      context: 'client',
+      access: 'public',
+      default: 'ubean-app',
+      description: '页头展示的名称'
+    })
   },
   mode: 'warn' // 'warn' 记录日志；'throw' 在校验失败时抛出
 });
@@ -93,6 +96,10 @@ env.PORT; // number
 validate(); // { success, errors, data }
 ```
 
+每个 builder 还接受 `description`，它会以 JSDoc 形式写进生成的 `.ubean/env.d.ts`。分组糖（`server:` / `public:`）已删除：维度写在字段上，同一个字段挪位置不会静默换语义。`client` + `secret` 在声明时直接抛错。构造函数形态（`{ type: String }`）仍可在 `schema` 下解析，但它没有维度可读，按 `server + secret` 处理（最保守的取舍）。
+
+需要 zod / valibot 级校验时，`defineEnv()` 也接受 Standard Schema 与 `safeParse` 形态——它与校验器同进程，而生成的 env 模块装不下函数。校验必须同步。
+
 | API                                              | 说明                                                                                  |
 | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
 | `defineEnv(config)`                              | 校验 schema 并返回 `{ env, validate }`（`DefineEnvResult<S>`）                        |

package/dist/index.d.ts

@@ -396,7 +396,7 @@ export type EnvSchema = Record<string, EnvFieldDef>;
 export type EnvContext = 'client' | 'server';
 export type EnvAccess = 'public' | 'secret';
 export interface EnvFieldMeta<T = unknown> {
-  /** 判别标记：把 `envField.*()` 的产物与 legacy 三形态区分开。 */
+  /** 判别标记：把 `envField.*()` 的产物与构造函数形态区分开。 */
   readonly __ubeanEnvField: true;
   readonly type: 'string' | 'number' | 'boolean' | 'enum';
   readonly context: EnvContext;
@@ -405,14 +405,18 @@ export interface EnvFieldMeta<T = unknown> {
   readonly values?: readonly string[];
   readonly optional?: boolean;
   readonly default?: T;
+  /**
+   * 字段说明。写进 `.ubean/env.d.ts` 的 JSDoc，编辑器里 hover 具名导入时直接可见 ——
+   * 这是唯一能跟着变量走到消费端的地方（`.env.example` 里的注释不会）。
+   */
+  readonly description?: string;
   /** 纯类型标记(运行时不写),让 `InferEnvOutput` 能推出字面量联合。 */
   readonly _output?: T;
 }
 /**
- * 一个 schema 字段：新形态（`envField.*()`）或 legacy 形态。
+ * 一个 schema 字段：`envField.*()` 产物、运行期 schema，或构造函数形态（`{ type: String }`）。
  *
- * legacy 形态保留是为了不破坏既有 `defineEnv({ server, public })` 调用 —— 现有仓库
- * 与示例都在用，`0.6.x` 内不能变语义。
+ * 构造函数形态没有维度信息，按 `server + secret` 处理（见 `DEFAULT_FIELD_DIMENSIONS`）。
  */
 export type EnvFieldDef = StandardSchemaV1 | GenericSchema | EnvFieldMeta | {
   type: StringConstructor | NumberConstructor | BooleanConstructor;
@@ -423,6 +427,13 @@ interface EnvFieldBase {
   context: EnvContext;
   access: EnvAccess;
   optional?: boolean;
+  /**
+   * 字段说明，会作为 JSDoc 出现在生成的 `.ubean/env.d.ts` 里。
+   *
+   * 与 `.env.example` 的注释分工：那边是给运维看「这个值填什么」，这里是给写代码的人
+   * 看「这个变量是什么」—— 且会跟着类型走到每一处 import。
+   */
+  description?: string;
 }
 export interface EnvStringFieldOptions extends EnvFieldBase {
   default?: string;
@@ -469,8 +480,8 @@ export type InferEnvOutput<S extends EnvSchema> = { [K in keyof S]: S[K] extends
   type: BooleanConstructor;
 } ? boolean : string; };
 /**
- * 规范化后的字段：把 legacy 的 `server:` / `public:` 分组糖与显式 `context`/`access`
- * 统一成同一形状。codegen 与虚拟模块都只消费这个形状。
+ * 规范化后的字段：每个都带着确定的 `context` / `access`。codegen 与虚拟模块都只
+ * 消费这个形状。
  */
 export interface NormalizedEnvField {
   key: string;
@@ -480,22 +491,14 @@ export interface NormalizedEnvField {
 }
 export interface EnvConfig<S extends EnvSchema = EnvSchema> {
   /**
-   * 扁平 schema —— 每个字段自带 `context` / `access`（`envField.*()` 声明）。
-   * 这是新写法，也是 `ubean.config.ts` 的 `env.schema` 直通入口。
-   */
-  schema?: S;
-  /**
-   * @deprecated 用 `schema` + `envField.*()` 代替。
-   *
-   * 分组糖：组内字段默认 `context: 'server', access: 'secret'`。
-   */
-  server?: S;
-  /**
-   * @deprecated 用 `schema` + `envField.*()` 代替。
+   * 扁平 schema —— 每个字段自带 `context` / `access`（用 `envField.*()` 声明）。
+   * `ubean.config.ts` 的 `env.schema` 与 `defineEnv({ schema })` 都是这个形状。
    *
-   * 分组糖：组内字段默认 `context: 'client', access: 'public'`。
+   * 分组糖（`server:` / `public:`）已删除：维度**必须**写在字段上。旧写法靠组名
+   * 隐式决定 `context`/`access`，同一个字段换个位置就换了语义，且 `client+secret`
+   * 这类非法组合只能靠组合规则兜。
    */
-  public?: S;
+  schema?: S;
   /** Validation mode - 'warn' logs errors, 'throw' throws on validation failure */
   mode?: 'warn' | 'throw';
 }
@@ -513,17 +516,22 @@ export interface EnvValidationError {
   value: unknown;
 }
 /**
- * 把用户 schema（含 legacy 分组糖）摊平成 `NormalizedEnvField[]`。
+ * 把用户 schema 摊平成 `NormalizedEnvField[]`。
+ *
+ * 字段自带 `context`/`access`（`envField.*()`）时用它；构造函数形态（`{ type: String }`）
+ * 没有维度信息，按「最保守」处理 —— 当 `server + secret`，绝不进客户端产物。要跳侧可见
+ * 就显式用 `envField.*()`。
  *
- * 字段自带的 `context`/`access` 优先于分组默认值 —— 这样用户可以在 legacy 的
- * `server:` 组里单独把一个字段标成 `public`，不必整体重写。
+ * 分组糖（`server:` / `public:`）已删除：维度必须写在字段上。旧写法靠组名隐式决定
+ * `context`/`access`，同一字段换个位置就换了语义，而混用（分组里再放 envField）只能靠
+ * 优先级规则解释。现在传入分组语法会直接抛错。
  */
 export declare function normalizeEnvSchema(schema: EnvSchema | EnvConfig): NormalizedEnvField[];
 /**
  * 服务端运行时校验：按规范化字段读 `source`（默认 `process.env`），产出强类型对象。
  *
- * 与 `defineEnv()` 的区别：这里只处理「已经归好维度」的字段，不碰 legacy 分组糖 ——
- * 虚拟模块 `ubean:env/server` 的运行时校验走它。
+ * 与 `defineEnv()` 的区别：这里只做「已归好维度」的字段到运行时值的解析 —— 虚拟模块
+ * `ubean:env/server` 的运行时校验走它。
  */
 export declare function resolveEnvSchema(schema: EnvSchema | EnvConfig, source?: Record<string, string | undefined>): {
   success: boolean;

package/dist/index.js

@@ -171,32 +171,69 @@ function isEnvFieldMeta(value) {
 	return typeof value === "object" && value !== null && value.__ubeanEnvField === true;
 }
 /**
-* legacy 分组 → 维度映射。
+* 构造函数形态（无维度信息）的默认维度：按「最保守」处理 —— 当服务端 secret，
+* 绝不进客户端产物。要跳侧可见就显式用 `envField.*()`。
+*/
+const DEFAULT_FIELD_DIMENSIONS = {
+	context: "server",
+	access: "secret"
+};
+/**
+* 判断一个值是否符合 Standard Schema 接口（zod / valibot / arktype 等）。
 *
-* `server:` 组历史语义是「只在服务端读」→ `server + secret`。
-* `public:` 组历史语义是「不敏感、客户端也能拿」→ `client + public`（`client` 侧在服务端
-* 同样可读，所以 examples 里在 API handler 中读 `env.API_BASE_URL` 的行为不变）。
+* 只看 `~standard.validate` 是不是函数，不看 `vendor` / `version` —— 各家实现这几个字段
+* 的值不一致（valibot 是 `vendor: 'valibot'`），但**调用面**统一。
 */
-const LEGACY_GROUP_DIMENSIONS = {
-	server: {
-		context: "server",
-		access: "secret"
-	},
-	public: {
-		context: "client",
-		access: "public"
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const standard = value["~standard"];
+	return typeof standard === "object" && standard !== null && typeof standard.validate === "function";
+}
+/**
+* 用 Standard Schema 校验一个环境变量。
+*
+* **`~standard.validate()` 必须同步返回。** 大多数 schema 都是同步的（zod 的 `.min()`
+* 一类、valibot 的 `v.pipe()`），但 zod 的 `.refine(async …)` 会返回 Promise：那种 schema
+* 在环境变量上无法支持 —— 生成的 server 模块在模块顶层同步执行，而
+* `loadUbeanConfigSync()` 又把配置编译成 CJS（顶层 await 在那里是语法错误），
+* 两边都没有 await 的位置。
+*
+* 早先这里写的是「看到 `~standard` 就判失败」并提示「请用 validate()」—— 可它从未
+* 调用过 `validate()`，于是**任何**标准 schema 都必定校验失败，而且报错指向一个同样会
+* 失败的方向。现在真的调用它了。
+*/
+function parseStandardSchemaValue(schema, rawValue, key) {
+	const input = rawValue === "" ? void 0 : rawValue;
+	let result;
+	try {
+		result = schema["~standard"].validate(input);
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
 	}
-};
+	if (typeof result?.then === "function") return {
+		ok: false,
+		error: `Env ${key}: async Standard Schema validation is not supported (env validation must be synchronous)`
+	};
+	const settled = result;
+	if (settled.issues && settled.issues.length > 0) return {
+		ok: false,
+		error: settled.issues[0]?.message ?? `Env ${key} is invalid`
+	};
+	return {
+		ok: true,
+		value: settled.value
+	};
+}
 function parseSchemaValue(schema, rawValue, key) {
 	if (!schema) return {
 		ok: true,
 		value: rawValue
 	};
 	if (isEnvFieldMeta(schema)) return parseEnvFieldValue(schema, rawValue, key);
-	if ("~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"]) return {
-		ok: false,
-		error: "Standard schema validation requires async validate, use validate() instead"
-	};
+	if (isStandardSchema(schema)) return parseStandardSchemaValue(schema, rawValue, key);
 	if (typeof schema.safeParse === "function") {
 		const result = schema.safeParse(rawValue);
 		if (!result.success) return {
@@ -283,7 +320,7 @@ function parseSchemaValue(schema, rawValue, key) {
 /**
 * 解析 `envField.*()` 声明的字段。
 *
-* 三种类型各自的行为与 legacy 形态保持一致（缺失 → `default` → `optional` 放行 → 报错），
+* 三种类型的行为与构造函数形态一致（缺失 → `default` → `optional` 放行 → 报错），
 * 多出来的是 `enum` 的成员校验：值不在 `values` 里直接失败，不做静默回落 ——
 * 枚举变量的拼写错误在启动期暴露比在运行期暴露便宜得多。
 */
@@ -332,52 +369,47 @@ function parseEnvFieldValue(meta, rawValue, key) {
 	};
 }
 /**
-* 把用户 schema（含 legacy 分组糖）摊平成 `NormalizedEnvField[]`。
+* 把用户 schema 摊平成 `NormalizedEnvField[]`。
+*
+* 字段自带 `context`/`access`（`envField.*()`）时用它；构造函数形态（`{ type: String }`）
+* 没有维度信息，按「最保守」处理 —— 当 `server + secret`，绝不进客户端产物。要跳侧可见
+* 就显式用 `envField.*()`。
 *
-* 字段自带的 `context`/`access` 优先于分组默认值 —— 这样用户可以在 legacy 的
-* `server:` 组里单独把一个字段标成 `public`，不必整体重写。
+* 分组糖（`server:` / `public:`）已删除：维度必须写在字段上。旧写法靠组名隐式决定
+* `context`/`access`，同一字段换个位置就换了语义，而混用（分组里再放 envField）只能靠
+* 优先级规则解释。现在传入分组语法会直接抛错。
 */
 function normalizeEnvSchema(schema) {
 	const fields = [];
-	const push = (key, def, fallback) => {
-		const dimensions = (isEnvFieldMeta(def) ? {
-			context: def.context,
-			access: def.access
-		} : null) ?? fallback;
-		if (dimensions.context === "client" && dimensions.access === "secret") throw new Error(`Invalid env field "${key}": context 'client' cannot be combined with access 'secret'.`);
+	const config = schema;
+	for (const groupKey of ["server", "public"]) if (groupKey in schema) throw new Error(`Invalid env config: grouped \`${groupKey}:\` schemas were removed.\nDeclare every field under \`schema:\` with explicit dimensions, e.g. \`${groupKey.toUpperCase()}_KEY: envField.string({ context: '${groupKey}', access: 'public' })\`.`);
+	const raw = config.schema ?? schema;
+	if (!raw || typeof raw !== "object") return fields;
+	for (const [key, def] of Object.entries(raw)) {
+		if (def === void 0 || def === null) continue;
+		if (!isEnvFieldMeta(def)) {
+			fields.push({
+				key,
+				...DEFAULT_FIELD_DIMENSIONS,
+				def
+			});
+			continue;
+		}
+		if (def.context === "client" && def.access === "secret") throw new Error(`Invalid env field "${key}": context 'client' cannot be combined with access 'secret'.`);
 		fields.push({
 			key,
-			context: dimensions.context,
-			access: dimensions.access,
+			context: def.context,
+			access: def.access,
 			def
 		});
-	};
-	const record = schema;
-	if (!("server" in record) && !("public" in record)) {
-		const flat = "schema" in record ? record.schema : record;
-		if (!flat || typeof flat !== "object") return fields;
-		for (const [key, def] of Object.entries(flat)) {
-			if (!isEnvFieldMeta(def)) {
-				push(key, def, LEGACY_GROUP_DIMENSIONS.server);
-				continue;
-			}
-			push(key, def, {
-				context: def.context,
-				access: def.access
-			});
-		}
-		return fields;
 	}
-	const grouped = schema;
-	for (const [key, def] of Object.entries(grouped.server ?? {})) push(key, def, LEGACY_GROUP_DIMENSIONS.server);
-	for (const [key, def] of Object.entries(grouped.public ?? {})) push(key, def, LEGACY_GROUP_DIMENSIONS.public);
 	return fields;
 }
 /**
 * 服务端运行时校验：按规范化字段读 `source`（默认 `process.env`），产出强类型对象。
 *
-* 与 `defineEnv()` 的区别：这里只处理「已经归好维度」的字段，不碰 legacy 分组糖 ——
-* 虚拟模块 `ubean:env/server` 的运行时校验走它。
+* 与 `defineEnv()` 的区别：这里只做「已归好维度」的字段到运行时值的解析 —— 虚拟模块
+* `ubean:env/server` 的运行时校验走它。
 */
 function resolveEnvSchema(schema, source) {
 	const fields = normalizeEnvSchema(schema);
@@ -428,11 +460,7 @@ function validateSchemaSync(schema, source) {
 }
 function defineEnv(config) {
 	const serverSource = readProcessEnv();
-	const mergedSchema = {
-		...config.public,
-		...config.server,
-		...config.schema
-	};
+	const mergedSchema = config.schema ?? {};
 	const initial = validateSchemaSync(mergedSchema, serverSource);
 	if (!initial.success && config.mode === "throw") {
 		const messages = initial.errors.map((e) => `  - ${e.key}: ${e.message}`).join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/shared",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Shared protocol types, errors, env and universal utilities for ubean",
   "files": [
     "dist"