@anjianshi/utils 2.1.3 → 2.1.5

package/env-node/env-reader.d.ts

@@ -1,19 +1,50 @@
+type EnvValue = string | number | boolean | unknown[] | Record<string, unknown>;
+type TypeDef = 'string' | 'number' | 'boolean' | unknown[] | Record<string, unknown>;
+type TypeFrom<D extends TypeDef> = D extends 'string' ? string : D extends 'number' ? number : D extends 'boolean' ? boolean : D;
+type ResultFrom<Defs extends Record<string, TypeDef>> = {
+    [K in keyof Defs]: TypeFrom<Defs[K]>;
+};
 /**
  * 读取 .env 文件，并获取格式化后的数据
  * 注意：依赖 dotenv 包
  */
 export declare class EnvReader {
-    readonly envFiles: string | string[];
-    envsFromFile: Record<string, string>;
-    constructor(envFiles: string | string[]);
+    protected loadedEnvs: Record<string, string>;
+    constructor(envFiles?: string | string[]);
     protected toNumber(raw: string): number | undefined;
     protected toBoolean(raw: string): boolean | undefined;
     getRaw(key: string): string | undefined;
+    /**
+     * 获取指定 env 的值，并转换成与 defaults 匹配的类型。
+     * 若值不存在，返回 defaults。
+     */
     get(key: string, defaults: string): string;
     get(key: string, defaults: number): number;
     get(key: string, defaults: boolean): boolean;
     get<T extends unknown[] | Record<string, unknown>>(key: string, defaults: T): T;
-    getNumber(key: string): number | undefined;
-    getBoolean(key: string): boolean | undefined;
-    getJSON<T>(key: string): T | undefined;
+    /**
+     * 获取指定 env 的值，并转换成指定类型，无需提供默认值。
+     * 值不存在或转换失败时，返回 undefined。
+     */
+    getByType(key: string, type?: 'string'): string;
+    getByType(key: string, type: 'number'): number;
+    getByType(key: string, type: 'boolean'): boolean;
+    getByType<T extends unknown[] | Record<string, unknown>>(key: string, type: 'json'): T;
+    /**
+     * 同 envReader.get()，只不过是通过对象指定各 env 的默认值来批量获取
+     * envReader.batchGet({ port: 8000, debug: false, mobiles: ['123', '456'] }
+     */
+    batchGet<Defs extends Record<string, EnvValue>>(definitions: Defs): Defs;
+    /**
+     * 同 envReader.getByType()，只不过是通过对象指定各 env 的类型来批量获取
+     *
+     * envReader.batchGetByType({
+     *   port: 'number',
+     *   debug: 'boolean',
+     *   mobiles: [] as string[],  // 用此格式定义内容是数组的 JSON 值
+     *   obj: {} as { a: number, b: string } // 用此格式定义内容是对象的 JSON 值
+     * }
+     */
+    batchGetByType<Defs extends Record<string, TypeDef>>(definitions: Defs): Partial<ResultFrom<Defs>>;
 }
+export {};

package/env-node/env-reader.js

@@ -5,13 +5,11 @@ import { safeParseJSON } from '../lang/string.js';
  * 注意：依赖 dotenv 包
  */
 export class EnvReader {
-    envFiles;
-    envsFromFile = {};
+    loadedEnvs = {};
     constructor(envFiles) {
-        this.envFiles = envFiles;
         dotenv.config({
-            path: this.envFiles,
-            processEnv: this.envsFromFile, // 把从 .env 文件读到的内容写入到此实例的属性，而不是 process.env
+            path: envFiles,
+            processEnv: this.loadedEnvs, // 把从 .env 文件读到的内容写入此变量，而不是 process.env，以避免污染 process.env。
         });
     }
     toNumber(raw) {
@@ -27,27 +25,60 @@ export class EnvReader {
         return undefined;
     }
     getRaw(key) {
-        return this.envsFromFile[key] ?? process.env[key];
+        return this.loadedEnvs[key] ?? process.env[key];
     }
     get(key, defaults) {
-        const value = this.getRaw(key);
-        if (value === undefined)
+        const raw = this.getRaw(key);
+        if (raw === undefined)
             return defaults;
         if (typeof defaults === 'number')
-            return this.toNumber(value) ?? defaults;
+            return this.toNumber(raw) ?? defaults;
         else if (typeof defaults === 'boolean')
-            return this.toBoolean(value) ?? defaults;
-        else if (Array.isArray(defaults) || typeof defaults === 'object')
-            return safeParseJSON(value) ?? defaults;
-        return value;
+            return this.toBoolean(raw) ?? defaults;
+        else if (Array.isArray(defaults) || typeof defaults === 'object') {
+            return safeParseJSON(raw) ?? defaults;
+        }
+        return raw;
     }
-    getNumber(key) {
-        return this.toNumber(this.getRaw(key) ?? '');
+    getByType(key, type = 'string') {
+        const raw = this.getRaw(key);
+        if (raw === undefined)
+            return raw;
+        if (type === 'number')
+            return this.toNumber(raw);
+        if (type === 'boolean')
+            return this.toBoolean(raw);
+        if (type === 'json')
+            return safeParseJSON(raw);
+        return raw;
     }
-    getBoolean(key) {
-        return this.toBoolean(this.getRaw(key) ?? '');
+    /**
+     * 同 envReader.get()，只不过是通过对象指定各 env 的默认值来批量获取
+     * envReader.batchGet({ port: 8000, debug: false, mobiles: ['123', '456'] }
+     */
+    batchGet(definitions) {
+        const result = {};
+        for (const [key, defaults] of Object.entries(definitions)) {
+            result[key] = this.get(key, defaults);
+        }
+        return result;
     }
-    getJSON(key) {
-        return safeParseJSON(this.getRaw(key) ?? '');
+    /**
+     * 同 envReader.getByType()，只不过是通过对象指定各 env 的类型来批量获取
+     *
+     * envReader.batchGetByType({
+     *   port: 'number',
+     *   debug: 'boolean',
+     *   mobiles: [] as string[],  // 用此格式定义内容是数组的 JSON 值
+     *   obj: {} as { a: number, b: string } // 用此格式定义内容是对象的 JSON 值
+     * }
+     */
+    batchGetByType(definitions) {
+        const result = {};
+        for (const [key, def] of Object.entries(definitions)) {
+            result[key] =
+                typeof def === 'string' ? this.getByType(key, def) : this.getByType(key, 'json');
+        }
+        return result;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjianshi/utils",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Common JavaScript Utils",
   "homepage": "https://github.com/anjianshi/js-packages/utils",
   "bugs": {