ph-utils 0.9.3 → 0.9.5

package/lib/file.d.ts

@@ -8,7 +8,7 @@
  * @param defaultValue 文件不存在时默认值, 不传则抛异常, 如果传递的是对象形式则会将结果转换为 JSON
  * @returns 文件内容
  */
-export declare function read<T>(filepath: string, defaultValue?: T): Promise<any>;
+export declare function read<T>(filepath: string, defaultValue?: T): Promise<T>;
 /**
  * 写入 JSON 格式的数据到文件
  * @param file 待写入的文件

package/lib/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * 验证字符串是否为空
- * @param str               待验证的字符串
- * @param ignoreWhitespace  是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
+ * 验证参数是否为空
+ * @param str               待验证的参数
+ * @param ignoreWhitespace  如果是字符串是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
  */
-export declare function isBlank(str?: string | null, ignoreWhitespace?: boolean): boolean;
+export declare function isBlank(str?: any, ignoreWhitespace?: boolean): boolean;
 /**
  * 屏蔽手机号，中间部分用 * 展示
  * @param mobile 待屏蔽的手机号
@@ -122,4 +122,8 @@ export declare function snakeCaseStyle(name: string, connector?: string): string
  * @returns 返回经过指定方式舍入后的数字
  */
 export declare function round(num: number, precision?: number, roundType?: 0 | 1 | 2): number;
+/**
+ * 反转字符串
+ */
+export declare function reverseStr(str: string): string;
 export {};

package/lib/index.js

@@ -6,15 +6,17 @@ const RANDOM_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz012345
 /** 只包含字母的随机数字符 */
 const NUMBER_RANDOM_CHARTS = "0123456789";
 /**
- * 验证字符串是否为空
- * @param str               待验证的字符串
- * @param ignoreWhitespace  是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
+ * 验证参数是否为空
+ * @param str               待验证的参数
+ * @param ignoreWhitespace  如果是字符串是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
  */
 export function isBlank(str, ignoreWhitespace = true) {
     if (str == null) {
         return true;
     }
-    return (ignoreWhitespace ? str.trim().length : str.length) === 0;
+    return ((ignoreWhitespace && typeof str === "string"
+        ? str.trim().length
+        : str.length) === 0);
 }
 /**
  * 屏蔽手机号，中间部分用 * 展示
@@ -86,11 +88,6 @@ export function random(opts) {
  * 带有错误名称标记的错误类型
  */
 export class BaseError extends Error {
-    /**
-     * 错误名称，类似于 Java 中的不同的 Exception[NullPointerException]；
-     * 增加 name 字段，表明不同的错误，当需要根据不同的错误执行不同的处理的时候，会很有用
-     */
-    name;
     constructor() {
         if (arguments.length === 1) {
             super(arguments[0]);
@@ -170,3 +167,9 @@ export function round(num, precision = 2, roundType = 0) {
             return num;
     }
 }
+/**
+ * 反转字符串
+ */
+export function reverseStr(str) {
+    return str.split("").reverse().join("");
+}

package/lib/logger.js

@@ -3,17 +3,16 @@ import { format } from "./date";
  * 日志记录器
  */
 export class Logger {
-    /** 日志级别 */
-    levels = ["debug", "info", "warn", "error", "fatal"];
-    colors = {
-        debug: "#909399",
-        info: "#1677ff",
-        warn: "#fadb14",
-        error: "#eb2f96",
-    };
-    option;
     /** 构造日志记录器 */
     constructor(option) {
+        /** 日志级别 */
+        this.levels = ["debug", "info", "warn", "error", "fatal"];
+        this.colors = {
+            debug: "#909399",
+            info: "#1677ff",
+            warn: "#fadb14",
+            error: "#eb2f96",
+        };
         this.setOption(option || {});
     }
     setOption(option) {

package/lib/server.d.ts

@@ -8,3 +8,23 @@ import type { SpawnOptions } from "node:child_process";
 export declare function exec(command: string, args?: string[]): Promise<string>;
 export declare function exec(command: string, options?: SpawnOptions): Promise<string>;
 export declare function exec(command: string, args?: string[], options?: SpawnOptions): Promise<string>;
+/**
+ * 解析环境变量;
+ * 同时读取多个环境变量文件: .env, .env.local, .env.[development|test|production];
+ * 根据运行环境变量 `NODE_ENV` 读取不同的环境变量文件;
+ * 同时支持手动通过运行命令指定 `NODE_ENV` 值, 不指定默认为: production
+ *
+ * ```bash
+ * node test.js --NODE_ENV development
+ * // or
+ * node test.js -n development
+ * ```
+ *
+ * ```js
+ * // test.js
+ * await parseEnvs();
+ * ```
+ *
+ * @returns
+ */
+export declare function parseEnvs(): Promise<Record<string, string>>;

package/lib/server.js

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { parseEnv, parseArgs } from "node:util";
+import { read } from "./file.js";
 /**
  * 执行命令
  * @param cmd 执行的命令
@@ -36,7 +38,7 @@ export function exec(command, ...params) {
         prs.on("error", (err) => {
             error = err;
         });
-        prs.on("close", (code, signal) => {
+        prs.on("close", (code, _signal) => {
             if (code === 0) {
                 resolve(msg.join("\n"));
             }
@@ -50,3 +52,56 @@ export function exec(command, ...params) {
         });
     });
 }
+/**
+ * 解析环境变量;
+ * 同时读取多个环境变量文件: .env, .env.local, .env.[development|test|production];
+ * 根据运行环境变量 `NODE_ENV` 读取不同的环境变量文件;
+ * 同时支持手动通过运行命令指定 `NODE_ENV` 值, 不指定默认为: production
+ *
+ * ```bash
+ * node test.js --NODE_ENV development
+ * // or
+ * node test.js -n development
+ * ```
+ *
+ * ```js
+ * // test.js
+ * await parseEnvs();
+ * ```
+ *
+ * @returns
+ */
+export async function parseEnvs() {
+    // development, test, production
+    const files = [".env", ".env.local"];
+    let nodeEnv = process.env.NODE_ENV;
+    const { values } = parseArgs({
+        options: {
+            NODE_ENV: {
+                type: "string",
+                short: "n",
+            },
+        },
+    });
+    if (values.NODE_ENV != null) {
+        nodeEnv = values.NODE_ENV;
+    }
+    else {
+        nodeEnv = "production";
+    }
+    process.env.NODE_ENV = nodeEnv;
+    files.push(`.env.${values.NODE_ENV}`);
+    let envParsed = {};
+    for (let i = 0, len = files.length; i < len; i++) {
+        const file = files[i];
+        const envContent = await read(file, "");
+        if (envContent !== "") {
+            const envValue = parseEnv(envContent);
+            envParsed = { ...envParsed, ...envValue };
+        }
+    }
+    for (const key in envParsed) {
+        process.env[key] = envParsed[key];
+    }
+    return envParsed;
+}

package/lib/storage.d.ts

@@ -13,6 +13,12 @@ interface StorageSetOption {
  * @param value 设置的值
  * @param [option.storage] session 或 local, 默认: session
  * @param [option.expire] 数据有效期, 单位秒, 默认: -1 - 永久存储
+ *
+ * @example <caption>1. 存储到 SessionStorage</caption>
+ * set("key", "value");
+ *
+ * @example <caption>2. 存储到 LocalStorage</caption>
+ * set("key", "value", { storage: "local" });
  */
 export declare function set(key: string, value: any, option?: StorageSetOption): void;
 /**

package/lib/storage.js

@@ -7,6 +7,12 @@ function getStorage(storage = "session") {
  * @param value 设置的值
  * @param [option.storage] session 或 local, 默认: session
  * @param [option.expire] 数据有效期, 单位秒, 默认: -1 - 永久存储
+ *
+ * @example <caption>1. 存储到 SessionStorage</caption>
+ * set("key", "value");
+ *
+ * @example <caption>2. 存储到 LocalStorage</caption>
+ * set("key", "value", { storage: "local" });
  */
 export function set(key, value, option) {
     const opts = {

package/lib/theme.d.ts

@@ -4,13 +4,13 @@ export declare function getSystemTheme(): "dark" | "light" | "auto";
  * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
  * @returns 当前应用的主题
  */
-export declare function initTheme(): Promise<"dark" | "light" | "auto" | undefined>;
+export declare function initTheme(): Promise<"dark" | "light" | "auto">;
 /**
  * 切换主题, 通常用于预览
  * @param theme 切换的主题
  * @returns 切换后的主题
  */
-export declare function toggleTheme(theme?: "light" | "dark" | "auto"): Promise<"dark" | "light" | "auto" | undefined>;
+export declare function toggleTheme(theme?: "light" | "dark" | "auto"): Promise<"dark" | "light" | "auto">;
 /** 获取当前主题 */
 export declare function getTheme(): string;
 /**
@@ -19,7 +19,7 @@ export declare function getTheme(): string;
  * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
  * @returns 应用的主题
  */
-export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean): Promise<"dark" | "light" | "auto" | undefined>;
+export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean): Promise<"dark" | "light" | "auto">;
 /** 获取当前主题色 */
 export declare function getColorTheme(defaultValue?: string): string | undefined;
 /**

package/lib/theme.js

@@ -37,6 +37,9 @@ export async function initTheme() {
  */
 export async function toggleTheme(theme) {
     const classList = document.documentElement.classList;
+    if (theme == null) {
+        theme = getSystemTheme();
+    }
     if (theme === "light") {
         classList.add("light");
         classList.remove("dark");

package/lib/validator.d.ts

@@ -26,7 +26,20 @@ declare class Validator {
     };
     /**
      * 构造数据验证转换器
+     *
+     * See {@link https://gitee.com/towardly/ph/wikis/utils/validator|Validator文档}.
+     *
      * @param schemas 配置验证转换规则
+     *
+     * @example
+     *
+     * const validator = new Validator([
+     *  { key: 'mobile', rules: ['required', 'mobile'] },
+     *  { key: 'code': rules: /^\d{6}$/, message: '请输入正确的验证码' },
+     *  { key: 'confirmPassword', rules: ['required', 'same:password'] }
+     * ])
+     * // 验证某一个字段
+     * validator.validateKey().then(res => {})
      */
     constructor(schemas: SchemaType[]);
     /**

package/lib/validator.js

@@ -32,8 +32,6 @@ const ruleFns = {
     },
 };
 class ValidateError extends Error {
-    name;
-    key;
     constructor(key, msg) {
         super(msg);
         this.name = "ValidateError";
@@ -44,10 +42,22 @@ class ValidateError extends Error {
  * 数据验证器
  */
 class Validator {
-    rules;
     /**
      * 构造数据验证转换器
+     *
+     * See {@link https://gitee.com/towardly/ph/wikis/utils/validator|Validator文档}.
+     *
      * @param schemas 配置验证转换规则
+     *
+     * @example
+     *
+     * const validator = new Validator([
+     *  { key: 'mobile', rules: ['required', 'mobile'] },
+     *  { key: 'code': rules: /^\d{6}$/, message: '请输入正确的验证码' },
+     *  { key: 'confirmPassword', rules: ['required', 'same:password'] }
+     * ])
+     * // 验证某一个字段
+     * validator.validateKey().then(res => {})
      */
     constructor(schemas) {
         let parsedRules = {};

package/package.json

@@ -64,7 +64,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.9.3",
+  "version": "0.9.5",
   "type": "module",
   "repository": {
     "type": "git",