ph-utils 0.17.2 → 0.19.0

package/lib/src/logger.d.ts

@@ -0,0 +1,62 @@
+type LoggerLevel = "debug" | "info" | "warn" | "error" | "fatal";
+/** 日志消息类型 */
+type MessageIntf = number | string | boolean | object | any[] | Error;
+/** 日志消息选项 */
+type MessageOption = {
+    /** 日志名称 */
+    name?: string;
+    /** 日志级别 */
+    level?: LoggerLevel;
+    /** 日志消息 */
+    message: MessageIntf;
+    /** 当前消息是否美化输出 */
+    pretty?: boolean;
+    /** 如果消息是 JSON 格式, 转换为字符串时, 是否格式化 JSON */
+    jsonSpace?: number;
+};
+type LoggerOption = {
+    /** 记录的日志名称, 通常用于表明哪个页面 */
+    name?: string;
+    /** 记录日志级别, 通常上线时 error 或者禁用日志, 默认: debug */
+    level?: LoggerLevel;
+    /** 是否需要美化输出, 默认: true */
+    pretty?: boolean;
+};
+/**
+ * 日志记录器
+ */
+export declare class Logger {
+    /** 日志级别 */
+    levels: string[];
+    colors: {
+        debug: string;
+        info: string;
+        warn: string;
+        error: string;
+    };
+    option: LoggerOption & {
+        levelNum: number;
+    };
+    /** 构造日志记录器 */
+    constructor(option?: LoggerOption);
+    setOption(option: LoggerOption): void;
+    log(message: MessageIntf | MessageOption): void;
+    info(message: MessageIntf | MessageOption): void;
+    debug(message: MessageIntf | MessageOption): void;
+    warn(message: MessageIntf | MessageOption): void;
+    error(message: MessageIntf | MessageOption): void;
+    fatal(message: MessageIntf | MessageOption): void;
+    getLevel(): string;
+    getName(): string | undefined;
+    getOption(): LoggerOption & {
+        levelNum: number;
+    };
+    private generateLog;
+    /** 格式化显示 */
+    private formatShow;
+}
+/** 默认日志记录器 */
+export declare const logger: Logger;
+/** 获取新的日志记录器, 属性采用之前的 */
+export declare const getLogger: (option?: LoggerOption) => Logger;
+export {};

package/lib/src/logger.js

@@ -0,0 +1,122 @@
+import { format } from "./date.js";
+/**
+ * 日志记录器
+ */
+export class Logger {
+    /** 构造日志记录器 */
+    constructor(option) {
+        /** 日志级别 */
+        this.levels = ["debug", "info", "warn", "error", "fatal"];
+        this.colors = {
+            debug: "#909399",
+            info: "#1677ff",
+            warn: "#fadb14",
+            error: "#eb2f96",
+        };
+        this.setOption(option || {});
+    }
+    setOption(option) {
+        let opts = { level: "debug", levelNum: 0, pretty: true, ...option };
+        opts.levelNum = this.levels.indexOf(opts.level);
+        this.option = opts;
+    }
+    log(message) {
+        let msgInfo = {
+            name: this.option.name,
+            level: "info",
+            time: format(null, "yyyy-mm-dd HH:MM:ss.S"),
+            pretty: this.option.pretty,
+            jsonSpace: 0,
+        };
+        let msgContent = message;
+        if (typeof message === "object") {
+            if (message instanceof Error) {
+                msgInfo.level = "error";
+                msgContent = msgContent.stack;
+            }
+            else if (message.message != null) {
+                msgContent = message.message;
+                msgInfo = { ...msgInfo, ...message };
+            }
+        }
+        if (typeof msgContent === "object") {
+            try {
+                msgInfo.message = JSON.stringify(msgContent, null, msgInfo.jsonSpace);
+            }
+            catch (error) {
+                msgInfo.message = msgContent.toString();
+            }
+        }
+        else {
+            msgInfo.message = msgContent;
+        }
+        if (msgInfo.pretty == null) {
+            msgInfo.pretty = this.option.pretty;
+        }
+        let levelIndex = this.levels.indexOf(msgInfo.level);
+        if (levelIndex >= this.option.levelNum) {
+            this.formatShow(msgInfo);
+        }
+    }
+    info(message) {
+        this.log(this.generateLog(message, "info"));
+    }
+    debug(message) {
+        this.log(this.generateLog(message, "debug"));
+    }
+    warn(message) {
+        this.log(this.generateLog(message, "warn"));
+    }
+    error(message) {
+        this.log(this.generateLog(message, "error"));
+    }
+    fatal(message) {
+        this.log(this.generateLog(message, "fatal"));
+    }
+    getLevel() {
+        return this.levels[this.option.levelNum];
+    }
+    getName() {
+        return this.option.name;
+    }
+    getOption() {
+        return this.option;
+    }
+    generateLog(message, level = "info") {
+        let msgInfo = {
+            message: message,
+        };
+        if (typeof message === "object") {
+            if (message.message != null) {
+                msgInfo = message;
+            }
+        }
+        msgInfo["level"] = level;
+        return msgInfo;
+    }
+    /** 格式化显示 */
+    formatShow(msg) {
+        if (msg.level === "fatal") {
+            msg.level = "error";
+        }
+        const res = [`[${msg.time}]`];
+        if (msg.name != null) {
+            res.push(`[${msg.name}]`);
+        }
+        res.push(`- ${msg.message}`);
+        if (!msg.pretty) {
+            res.splice(1, 0, `${msg.level.toUpperCase()}`);
+            console[msg.level](res.join(" "));
+        }
+        else {
+            const color = this.colors[msg.level];
+            console.log(`%c ${`${msg.level.toUpperCase()}`} %c ${res.join(" ")} %c`, `background:${color};border:1px solid ${color}; padding: 1px; border-radius: 2px 0 0 2px; color: #fff;`, `border:1px solid ${color}; padding: 1px; border-radius: 0 2px 2px 0; color: ${color};`, "background:transparent");
+        }
+    }
+}
+/** 默认日志记录器 */
+export const logger = new Logger({ name: "APP" });
+/** 获取新的日志记录器, 属性采用之前的 */
+export const getLogger = (option) => {
+    return new Logger({ ...logger.getOption(), ...option });
+};

package/lib/src/server.d.ts

@@ -0,0 +1,33 @@
+import type { SpawnOptionsWithoutStdio } from "node:child_process";
+/**
+ * 执行命令
+ * @param command 待执行的命令
+ * @param args    命令参数
+ */
+export declare function exec(command: string, args?: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function exec(command: string, options?: SpawnOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function exec(command: string, args?: string[], options?: SpawnOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+type SpawnOptions = SpawnOptionsWithoutStdio & {
+    shell?: 'powershell';
+};
+/**
+ * 执行命令并返回执行结果的Promise
+ * @param command 要执行的命令
+ * @param args 命令参数数组
+ * @param options 执行选项，支持指定shell类型
+ * @returns Promise对象，成功时resolve包含stdout和stderr的对象，失败时reject包含错误信息
+ */
+export declare function spawn(command: string, args?: string[], options?: SpawnOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export {};

package/lib/src/server.js

@@ -0,0 +1,65 @@
+import { execFile, spawn as spawnOri } from "node:child_process";
+import { promisify } from "node:util";
+const execFilePromise = promisify(execFile);
+/**
+ * 执行命令
+ * @param cmd 执行的命令
+ * @returns
+ */
+export function exec(command, ...params) {
+    let argvs = [];
+    const commandItems = command.split(" ");
+    const cmd = commandItems.shift();
+    if (commandItems.length > 0) {
+        argvs = commandItems;
+    }
+    let opts = { shell: true };
+    if (params[0] != null) {
+        if (params[0] instanceof Array) {
+            argvs.push(...params[0]);
+            if (params[1] != null) {
+                opts = params[1];
+            }
+        }
+        else {
+            opts = params[0];
+        }
+    }
+    return execFilePromise(cmd, argvs, opts);
+}
+/**
+ * 执行命令并返回执行结果的Promise
+ * @param command 要执行的命令
+ * @param args 命令参数数组
+ * @param options 执行选项，支持指定shell类型
+ * @returns Promise对象，成功时resolve包含stdout和stderr的对象，失败时reject包含错误信息
+ */
+export function spawn(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        let execArgs = [];
+        let cmd;
+        // 根据是否指定powershell shell来设置实际执行的命令和参数
+        if (options.shell === 'powershell') {
+            cmd = 'powershell.exe';
+            execArgs = ['-NoProfile', '-Command', command, ...(args || [])];
+        }
+        else {
+            cmd = command;
+            execArgs = args || [];
+        }
+        delete options.shell;
+        const child = spawnOri(cmd, execArgs, options);
+        let stdout = '', stderr = '';
+        child.stdout.on('data', d => stdout += d);
+        child.stderr.on('data', d => stderr += d);
+        // 监听子进程关闭事件，根据退出码决定resolve或reject
+        child.on('close', code => {
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(`spawn failed (${code}): ${stderr}`));
+        });
+        // 监听子进程错误事件，发生错误时直接reject
+        child.on('error', reject);
+    });
+}

package/lib/src/storage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 缓存相关
+ */
+type StorageType = "session" | "local";
+interface StorageSetOption {
+    storage?: StorageType;
+    /** 数据有效期, 单位秒, 默认: -1 - 永久存储 */
+    expire?: number;
+}
+/**
+ * 存储值到 Storage 中
+ * @param key 设置的 key
+ * @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;
+/**
+ * 清空所有的缓存内容
+ * @param storage 待清空的缓存对象
+ */
+export declare function clear(storage?: StorageType): void;
+/**
+ * 删除存储到 Storage 中的数据
+ * @param key
+ * @param storage
+ */
+export declare function remove(key: string, storage?: StorageType): void;
+/** 从 Storage 中获取数据时的配置 */
+interface StorageQueryOption {
+    /** 数据是否持久化, 默认为: false, 设置为 true 则会在每一次取出数据后删除 */
+    delete?: boolean;
+    /** 存储对象, session、local */
+    storage?: StorageType;
+}
+/**
+ * 从 Storage 中取出数据
+ * @param key 保存时的 key
+ * @param defaultValue 没有数据时的默认值
+ * @param [option.delete] 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param [option.storage] 使用的 Storage ，可以是 localStorage、sessionStorage, 默认: localStorage、sessionStorage
+ * @returns Storage 中 key 对应的数据
+ */
+export declare function get<T>(key: string, defaultValue?: T, option?: StorageQueryOption): T;
+export {};

package/lib/src/storage.js

@@ -0,0 +1,73 @@
+function getStorage(storage = "session") {
+    return storage === "session" ? sessionStorage : localStorage;
+}
+/**
+ * 存储值到 Storage 中
+ * @param key 设置的 key
+ * @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 = {
+        expire: -1,
+        storage: "session",
+        ...option,
+    };
+    const saveData = JSON.stringify({
+        value,
+        time: Date.now(),
+        expire: opts.expire === -1 ? -1 : Math.floor(Date.now() / 1000) + opts.expire,
+    });
+    getStorage(opts.storage).setItem(key, saveData);
+}
+/**
+ * 清空所有的缓存内容
+ * @param storage 待清空的缓存对象
+ */
+export function clear(storage) {
+    getStorage(storage).clear();
+}
+/**
+ * 删除存储到 Storage 中的数据
+ * @param key
+ * @param storage
+ */
+export function remove(key, storage) {
+    getStorage(storage).removeItem(key);
+}
+/**
+ * 从 Storage 中取出数据
+ * @param key 保存时的 key
+ * @param defaultValue 没有数据时的默认值
+ * @param [option.delete] 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param [option.storage] 使用的 Storage ，可以是 localStorage、sessionStorage, 默认: localStorage、sessionStorage
+ * @returns Storage 中 key 对应的数据
+ */
+export function get(key, defaultValue, option) {
+    const opts = (option || { delete: false });
+    const storage = getStorage(opts.storage);
+    let data = storage.getItem(key);
+    if (data == null) {
+        return defaultValue || null;
+    }
+    data = JSON.parse(data);
+    let d = data.value;
+    if (data.expire !== -1) {
+        // 数据过期
+        if (Math.floor(Date.now() / 1000) > data.expire) {
+            d = null;
+            storage.removeItem(key);
+        }
+    }
+    if (opts.delete) {
+        storage.removeItem(key);
+    }
+    return d || defaultValue;
+}

package/lib/src/theme.d.ts

@@ -0,0 +1,44 @@
+/** 获取当前系统的主题 */
+export declare function getSystemTheme(): "light" | "dark" | "auto";
+/**
+ * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
+ * @returns 当前应用的主题
+ */
+export declare function initTheme(): Promise<"light" | "dark" | "auto">;
+/**
+ * 切换主题, 通常用于预览
+ * @param theme 切换的主题
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 切换后的主题
+ */
+export declare function toggleTheme(theme?: "light" | "dark" | "auto", transition?: boolean): Promise<"light" | "dark" | "auto">;
+/** 获取当前主题 */
+export declare function getTheme(): string;
+/**
+ * 应用主题
+ * @param theme 待应用的主题
+ * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 应用的主题
+ */
+export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean, transition?: boolean): Promise<"light" | "dark" | "auto">;
+/** 获取当前主题色 */
+export declare function getColorTheme(defaultValue?: string): string | undefined;
+/**
+ * 初始化主题色, 让网页能够适应系统主题色, 同时根据缓存的主题色切换主题色
+ * @returns 当前应用的主题色
+ */
+export declare function initColorTheme(): Promise<string> | null;
+/**
+ * 切换主题色, 通常用于预览
+ * @param color 待切换的主题色
+ * @returns 切换后的主题色
+ */
+export declare function toggleColorTheme(color: string): Promise<string>;
+/**
+ * 应用主题色
+ * @param color 主题色
+ * @param cache 是否缓存主题色, 让应用下一次启动的时候, 可以应用主题色, 默认: true
+ * @returns 切换后的主题色
+ */
+export declare function applyColorTheme(color: string, cache?: boolean): Promise<string>;

package/lib/src/theme.js

@@ -0,0 +1,156 @@
+import { adjust } from "./color.js";
+/** 获取当前系统的主题 */
+export function getSystemTheme() {
+    if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+        return "dark";
+    }
+    else if (window.matchMedia("(prefers-color-scheme: light)").matches) {
+        return "light";
+    }
+    return "auto";
+}
+/**
+ * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
+ * @returns 当前应用的主题
+ */
+export async function initTheme() {
+    // 让网页能够适应系统主题
+    let $themeStyle = document.getElementById("theme-style");
+    if ($themeStyle == null) {
+        $themeStyle = document.createElement("style");
+        $themeStyle.id = "theme-style";
+        $themeStyle.innerHTML =
+            ":root{color-scheme:light dark;}html.light{color-scheme: light;}html.dark {color-scheme: dark;}";
+        document.head.appendChild($themeStyle);
+    }
+    // 获取已经应用的主题设置
+    const cacheTheme = localStorage.getItem("web-theme-appearance");
+    return toggleTheme(cacheTheme);
+}
+/**
+ * 切换主题, 通常用于预览
+ * @param theme 切换的主题
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 切换后的主题
+ */
+export async function toggleTheme(theme, transition = true) {
+    return new Promise((resolve) => {
+        const classList = document.documentElement.classList;
+        if (theme == null) {
+            theme = getSystemTheme();
+        }
+        function updateThemeClass() {
+            if (theme === "light") {
+                classList.add("light");
+                classList.remove("dark");
+            }
+            else if (theme === "dark") {
+                classList.add("dark");
+                classList.remove("light");
+            }
+            else {
+                classList.remove("light", "dark");
+            }
+        }
+        // @ts-ignore
+        if (transition && document.startViewTransition) {
+            // @ts-ignore
+            document.startViewTransition(() => {
+                updateThemeClass();
+                resolve(theme);
+            });
+        }
+        else {
+            updateThemeClass();
+            resolve(theme);
+        }
+    });
+}
+/** 获取当前主题 */
+export function getTheme() {
+    // 1. 从根节点获取
+    let theme = document.documentElement.className.match(/light|dark/);
+    if (theme != null) {
+        theme = theme[0];
+    }
+    if (theme == null) {
+        theme = localStorage.getItem("web-theme-appearance");
+    }
+    if (theme == null) {
+        theme = getSystemTheme();
+    }
+    return theme;
+}
+/**
+ * 应用主题
+ * @param theme 待应用的主题
+ * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 应用的主题
+ */
+export async function applyTheme(theme, cache = true, transition = true) {
+    if (cache === true) {
+        localStorage.setItem("web-theme-appearance", theme == null ? "auto" : theme);
+    }
+    return toggleTheme(theme, transition);
+}
+/** 获取当前主题色 */
+export function getColorTheme(defaultValue) {
+    const root = document.documentElement;
+    const match = root.className.match(/color-([0-9a-fA-F]{6})/);
+    if (match == null) {
+        // 获取 --nt-primary-color 的值
+        let color = getComputedStyle(root).getPropertyValue("--l-primary-color");
+        if (color === "") {
+            color = localStorage.getItem("web-theme-color");
+        }
+        return color ? color : defaultValue;
+    }
+    return `#${match[1]}`;
+}
+/**
+ * 初始化主题色, 让网页能够适应系统主题色, 同时根据缓存的主题色切换主题色
+ * @returns 当前应用的主题色
+ */
+export function initColorTheme() {
+    // 获取缓存主题色
+    const color = localStorage.getItem("web-theme-color");
+    if (color != null) {
+        return toggleColorTheme(color);
+    }
+    return color;
+}
+/**
+ * 切换主题色, 通常用于预览
+ * @param color 待切换的主题色
+ * @returns 切换后的主题色
+ */
+export async function toggleColorTheme(color) {
+    const vars = [
+        `--l-primary-color: ${color};`,
+        `--l-primary-color-dark1: ${adjust(color, 1, false)};`,
+    ];
+    for (let i = 1; i <= 5; i++) {
+        vars.push(`--l-primary-color-light${i}: ${adjust(color, i)};`);
+    }
+    let $style = document.getElementById("color-theme-style");
+    if ($style == null) {
+        $style = document.createElement("style");
+        $style.id = "color-theme-style";
+        document.head.appendChild($style);
+    }
+    $style.innerHTML = `:root{${vars.join("")}}`;
+    return color;
+}
+/**
+ * 应用主题色
+ * @param color 主题色
+ * @param cache 是否缓存主题色, 让应用下一次启动的时候, 可以应用主题色, 默认: true
+ * @returns 切换后的主题色
+ */
+export function applyColorTheme(color, cache = true) {
+    if (cache === true) {
+        localStorage.setItem("web-theme-color", color);
+    }
+    return toggleColorTheme(color);
+}

package/lib/src/validator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 数据验证器
+ */
+interface RuleItem {
+    rule: RegExp | ((v: any) => boolean) | "required";
+    message: string;
+    sameKey?: string;
+}
+export type RuleType = string | RegExp | ((v: any) => boolean) | (RegExp | string | ((v: any) => boolean) | {
+    rule: string | RegExp | ((v: any) => boolean);
+    message?: string;
+});
+export interface SchemaType {
+    /** 数据字段 */
+    key: string;
+    /** 是否必须 */
+    required?: boolean;
+    /** 验证规则列表 */
+    rules?: RuleType[];
+    /** 错误信息 */
+    message?: string;
+}
+/**
+ * 数据验证器
+ */
+declare class Validator {
+    rules: {
+        [index: string]: RuleItem[];
+    };
+    /**
+     * 构造数据验证转换器
+     *
+     * 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[]);
+    addSchemas(schemas: SchemaType[]): void;
+    addSchema(schema: SchemaType): void;
+    /**
+     * 进行数据验证
+     * @param data 待验证的数据
+     * @param all 是否全部验证, false - 只要验证错误一个则停止验证
+     * @returns
+     */
+    validate(data: any, all?: boolean): Promise<boolean>;
+    /**
+     * 只验证指定 key 的数据格式
+     * @param key   指定待验证的 key
+     * @param value 待验证的数据
+     * @param data 原始数据，当验证确认密码时需要使用
+     */
+    validateKey(key: string, value: any, data?: any): Promise<{
+        key: string;
+        value: any;
+    }>;
+    private _validateRule;
+    private _parseSchemaRules;
+    private _parseStringRule;
+}
+export default Validator;