@ubean/shared 0.6.3 → 0.6.5

package/dist/index.d.ts

@@ -380,22 +380,121 @@ export declare function isUbeanError(err: unknown): err is UbeanError;
 export declare function errorToResponse(c: unknown, err?: unknown): Response;
 //#endregion
 //#region src/env.d.ts
-export type EnvSchema = Record<string, StandardSchemaV1 | GenericSchema | {
+export type EnvSchema = Record<string, EnvFieldDef>;
+/**
+ * 环境变量的**归属维度**（借用 Astro `astro:env` 的模型，见 docs/contracts/env-v1.md）。
+ *
+ * - `context`: 值在哪一侧可用。`client` → 构建期内联进客户端产物（服务端同样可读）；
+ *   `server` → 只在服务端运行时读取。
+ * - `access`: 值是否敏感。`secret` 永不进客户端产物；`public` 可以（但 `client` 侧的
+ *   public 才会被内联）。
+ *
+ * 合法组合只有三种：`client+public`、`server+public`、`server+secret`。
+ * `client+secret` 在建 schema 时直接抛错 —— 这是 Astro 的硬约束，也是本设计里唯一
+ * 「配置期就失败」的规则。
+ */
+export type EnvContext = 'client' | 'server';
+export type EnvAccess = 'public' | 'secret';
+export interface EnvFieldMeta<T = unknown> {
+  /** 判别标记：把 `envField.*()` 的产物与 legacy 三形态区分开。 */
+  readonly __ubeanEnvField: true;
+  readonly type: 'string' | 'number' | 'boolean' | 'enum';
+  readonly context: EnvContext;
+  readonly access: EnvAccess;
+  /** 仅 `type: 'enum'` 有值。 */
+  readonly values?: readonly string[];
+  readonly optional?: boolean;
+  readonly default?: T;
+  /** 纯类型标记(运行时不写),让 `InferEnvOutput` 能推出字面量联合。 */
+  readonly _output?: T;
+}
+/**
+ * 一个 schema 字段：新形态（`envField.*()`）或 legacy 形态。
+ *
+ * legacy 形态保留是为了不破坏既有 `defineEnv({ server, public })` 调用 —— 现有仓库
+ * 与示例都在用，`0.6.x` 内不能变语义。
+ */
+export type EnvFieldDef = StandardSchemaV1 | GenericSchema | EnvFieldMeta | {
   type: StringConstructor | NumberConstructor | BooleanConstructor;
   default?: unknown;
   required?: boolean;
-}>;
-export type InferEnvOutput<S extends EnvSchema> = { [K in keyof S]: S[K] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S[K]> : S[K] extends GenericSchema<infer O> ? O : S[K] extends {
+};
+interface EnvFieldBase {
+  context: EnvContext;
+  access: EnvAccess;
+  optional?: boolean;
+}
+export interface EnvStringFieldOptions extends EnvFieldBase {
+  default?: string;
+}
+export interface EnvNumberFieldOptions extends EnvFieldBase {
+  default?: number;
+}
+export interface EnvBooleanFieldOptions extends EnvFieldBase {
+  default?: boolean;
+}
+export interface EnvEnumFieldOptions<V extends readonly string[]> extends EnvFieldBase {
+  values: V;
+  default?: V[number];
+}
+/**
+ * 声明一个环境变量字段（Astro `envField` 的等价物）。
+ *
+ * @example
+ * ```ts
+ * // ubean.config.ts
+ * export default defineConfig({
+ *   env: {
+ *     schema: {
+ *       PUBLIC_API_BASE: envField.string({ context: 'client', access: 'public', default: '/api' }),
+ *       DATABASE_URL: envField.string({ context: 'server', access: 'secret', optional: true }),
+ *       PORT: envField.number({ context: 'server', access: 'public', default: 9527 })
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const envField: {
+  string(options: EnvStringFieldOptions): EnvFieldMeta<string>;
+  number(options: EnvNumberFieldOptions): EnvFieldMeta<number>;
+  boolean(options: EnvBooleanFieldOptions): EnvFieldMeta<boolean>;
+  enum<const V extends readonly string[]>(options: EnvEnumFieldOptions<V>): EnvFieldMeta<V[number]>;
+};
+export declare function isEnvFieldMeta(value: unknown): value is EnvFieldMeta;
+export type InferEnvOutput<S extends EnvSchema> = { [K in keyof S]: S[K] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S[K]> : S[K] extends GenericSchema<infer O> ? O : S[K] extends EnvFieldMeta<infer O> ? O : S[K] extends {
   type: StringConstructor;
 } ? string : S[K] extends {
   type: NumberConstructor;
 } ? number : S[K] extends {
   type: BooleanConstructor;
 } ? boolean : string; };
+/**
+ * 规范化后的字段：把 legacy 的 `server:` / `public:` 分组糖与显式 `context`/`access`
+ * 统一成同一形状。codegen 与虚拟模块都只消费这个形状。
+ */
+export interface NormalizedEnvField {
+  key: string;
+  context: EnvContext;
+  access: EnvAccess;
+  def: EnvFieldDef;
+}
 export interface EnvConfig<S extends EnvSchema = EnvSchema> {
-  /** Server-only env variables (not exposed to client) */
+  /**
+   * 扁平 schema —— 每个字段自带 `context` / `access`（`envField.*()` 声明）。
+   * 这是新写法，也是 `ubean.config.ts` 的 `env.schema` 直通入口。
+   */
+  schema?: S;
+  /**
+   * @deprecated 用 `schema` + `envField.*()` 代替。
+   *
+   * 分组糖：组内字段默认 `context: 'server', access: 'secret'`。
+   */
   server?: S;
-  /** Public env variables (exposed to client via import.meta.env) */
+  /**
+   * @deprecated 用 `schema` + `envField.*()` 代替。
+   *
+   * 分组糖：组内字段默认 `context: 'client', access: 'public'`。
+   */
   public?: S;
   /** Validation mode - 'warn' logs errors, 'throw' throws on validation failure */
   mode?: 'warn' | 'throw';
@@ -413,6 +512,24 @@ export interface EnvValidationError {
   message: string;
   value: unknown;
 }
+/**
+ * 把用户 schema（含 legacy 分组糖）摊平成 `NormalizedEnvField[]`。
+ *
+ * 字段自带的 `context`/`access` 优先于分组默认值 —— 这样用户可以在 legacy 的
+ * `server:` 组里单独把一个字段标成 `public`，不必整体重写。
+ */
+export declare function normalizeEnvSchema(schema: EnvSchema | EnvConfig): NormalizedEnvField[];
+/**
+ * 服务端运行时校验：按规范化字段读 `source`（默认 `process.env`），产出强类型对象。
+ *
+ * 与 `defineEnv()` 的区别：这里只处理「已经归好维度」的字段，不碰 legacy 分组糖 ——
+ * 虚拟模块 `ubean:env/server` 的运行时校验走它。
+ */
+export declare function resolveEnvSchema(schema: EnvSchema | EnvConfig, source?: Record<string, string | undefined>): {
+  success: boolean;
+  errors: EnvValidationError[];
+  data: Record<string, unknown>;
+};
 export declare function defineEnv<S extends EnvSchema>(config: EnvConfig<S>): DefineEnvResult<S>;
 export declare function setRuntimeEnv(env: Record<string, unknown>): void;
 export declare function useRuntimeEnv<T = string>(key: string, defaultValue?: T): T;
@@ -475,4 +592,5 @@ export declare function matchAnyGlob(route: string, patterns: string[]): boolean
  * 将字符串首字母大写。
  */
 export declare function capitalize(str: string): string;
-//#endregion
+//#endregion
+export {};

package/dist/index.js

@@ -113,11 +113,86 @@ function errorToResponse(c, err) {
 }
 //#endregion
 //#region src/env.ts
+function assertEnvFieldCombo(options) {
+	if (options.context === "client" && options.access === "secret") throw new Error("Invalid env field: context 'client' cannot be combined with access 'secret'. Secrets are never sent to the client; use `{ context: 'server', access: 'secret' }`.");
+}
+/**
+* 声明一个环境变量字段（Astro `envField` 的等价物）。
+*
+* @example
+* ```ts
+* // ubean.config.ts
+* export default defineConfig({
+*   env: {
+*     schema: {
+*       PUBLIC_API_BASE: envField.string({ context: 'client', access: 'public', default: '/api' }),
+*       DATABASE_URL: envField.string({ context: 'server', access: 'secret', optional: true }),
+*       PORT: envField.number({ context: 'server', access: 'public', default: 9527 })
+*     }
+*   }
+* });
+* ```
+*/
+const envField = {
+	string(options) {
+		assertEnvFieldCombo(options);
+		return {
+			__ubeanEnvField: true,
+			type: "string",
+			...options
+		};
+	},
+	number(options) {
+		assertEnvFieldCombo(options);
+		return {
+			__ubeanEnvField: true,
+			type: "number",
+			...options
+		};
+	},
+	boolean(options) {
+		assertEnvFieldCombo(options);
+		return {
+			__ubeanEnvField: true,
+			type: "boolean",
+			...options
+		};
+	},
+	enum(options) {
+		assertEnvFieldCombo(options);
+		return {
+			__ubeanEnvField: true,
+			type: "enum",
+			...options
+		};
+	}
+};
+function isEnvFieldMeta(value) {
+	return typeof value === "object" && value !== null && value.__ubeanEnvField === true;
+}
+/**
+* legacy 分组 → 维度映射。
+*
+* `server:` 组历史语义是「只在服务端读」→ `server + secret`。
+* `public:` 组历史语义是「不敏感、客户端也能拿」→ `client + public`（`client` 侧在服务端
+* 同样可读，所以 examples 里在 API handler 中读 `env.API_BASE_URL` 的行为不变）。
+*/
+const LEGACY_GROUP_DIMENSIONS = {
+	server: {
+		context: "server",
+		access: "secret"
+	},
+	public: {
+		context: "client",
+		access: "public"
+	}
+};
 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"
@@ -203,6 +278,135 @@ function parseSchemaValue(schema, rawValue, key) {
 		value: rawValue
 	};
 }
+/** 缺失判定用内联比较而非 `isMissing()` 谓词函数 —— 后者是 boolean 返回，
+* TypeScript 不会据此收窄 `string | undefined`，下游的 `values.includes()` 就会报错。 */
+/**
+* 解析 `envField.*()` 声明的字段。
+*
+* 三种类型各自的行为与 legacy 形态保持一致（缺失 → `default` → `optional` 放行 → 报错），
+* 多出来的是 `enum` 的成员校验：值不在 `values` 里直接失败，不做静默回落 ——
+* 枚举变量的拼写错误在启动期暴露比在运行期暴露便宜得多。
+*/
+function parseEnvFieldValue(meta, rawValue, key) {
+	if (rawValue === void 0 || rawValue === "") {
+		if (meta.default !== void 0) return {
+			ok: true,
+			value: meta.default
+		};
+		if (meta.optional === true) return {
+			ok: true,
+			value: void 0
+		};
+		return {
+			ok: false,
+			error: `Missing required env: ${key}`
+		};
+	}
+	if (meta.type === "string") return {
+		ok: true,
+		value: rawValue
+	};
+	if (meta.type === "number") {
+		const n = Number(rawValue);
+		if (Number.isNaN(n)) return {
+			ok: false,
+			error: `Env ${key} must be a number, got ${rawValue}`
+		};
+		return {
+			ok: true,
+			value: n
+		};
+	}
+	if (meta.type === "boolean") return {
+		ok: true,
+		value: rawValue === "true" || rawValue === "1"
+	};
+	const values = meta.values ?? [];
+	if (!values.includes(rawValue)) return {
+		ok: false,
+		error: `Env ${key} must be one of ${values.join(" | ")}, got ${rawValue}`
+	};
+	return {
+		ok: true,
+		value: rawValue
+	};
+}
+/**
+* 把用户 schema（含 legacy 分组糖）摊平成 `NormalizedEnvField[]`。
+*
+* 字段自带的 `context`/`access` 优先于分组默认值 —— 这样用户可以在 legacy 的
+* `server:` 组里单独把一个字段标成 `public`，不必整体重写。
+*/
+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'.`);
+		fields.push({
+			key,
+			context: dimensions.context,
+			access: dimensions.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` 的运行时校验走它。
+*/
+function resolveEnvSchema(schema, source) {
+	const fields = normalizeEnvSchema(schema);
+	const resolvedSource = source ?? readProcessEnv();
+	const errors = [];
+	const data = {};
+	for (const field of fields) {
+		const rawValue = resolvedSource[field.key];
+		const result = parseEnvFieldOrLegacy(field.def, rawValue, field.key);
+		if (!result.ok) errors.push({
+			key: field.key,
+			message: result.error || "invalid",
+			value: rawValue
+		});
+		else data[field.key] = result.value;
+	}
+	return {
+		success: errors.length === 0,
+		errors,
+		data
+	};
+}
+function parseEnvFieldOrLegacy(def, rawValue, key) {
+	return parseSchemaValue(def, rawValue, key);
+}
+function readProcessEnv() {
+	if (typeof process !== "undefined" && process.env) return process.env;
+	return globalThis.process?.env || {};
+}
 function validateSchemaSync(schema, source) {
 	const errors = [];
 	const data = {};
@@ -223,10 +427,11 @@ function validateSchemaSync(schema, source) {
 	};
 }
 function defineEnv(config) {
-	const serverSource = typeof process !== "undefined" ? process.env : globalThis.process?.env || {};
+	const serverSource = readProcessEnv();
 	const mergedSchema = {
 		...config.public,
-		...config.server
+		...config.server,
+		...config.schema
 	};
 	const initial = validateSchemaSync(mergedSchema, serverSource);
 	if (!initial.success && config.mode === "throw") {
@@ -351,4 +556,4 @@ function matchAnyGlob(route, patterns) {
 	return patterns.some((p) => matchGlob(route, p));
 }
 //#endregion
-export { ACTION_BRAND, ActionError, UbeanError, capitalize, createError, defineEnv, errorToResponse, fail, getBasename, getDirname, getExtension, getStem, isActionFailure, isNodeRuntime, isServerAction, isUbeanError, matchAnyGlob, matchGlob, normalizePath, pathToTitle, setRuntimeEnv, useRuntimeEnv };
+export { ACTION_BRAND, ActionError, UbeanError, capitalize, createError, defineEnv, envField, errorToResponse, fail, getBasename, getDirname, getExtension, getStem, isActionFailure, isEnvFieldMeta, isNodeRuntime, isServerAction, isUbeanError, matchAnyGlob, matchGlob, normalizeEnvSchema, normalizePath, pathToTitle, resolveEnvSchema, setRuntimeEnv, useRuntimeEnv };

package/package.json

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