ph-utils 0.16.3 → 0.16.4

package/README.md

@@ -1,7 +1,7 @@
-## ph-utils
-
-整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
-
-### 包含如下工具文件
-
-`index` 基础工具类、`date` 跟日期相关的工具类、`file` 文件操作相关工具类[**服务端**]、`server` 服务端工具类、`validator` 数据验证、`dom` 浏览器节点操作相关[**前端**]、`web` 一些只适用于前端相关的工具、`color` 颜色相关工具
+## ph-utils
+
+整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
+
+### 包含如下工具文件
+
+`index` 基础工具类、`date` 跟日期相关的工具类、`file` 文件操作相关工具类[**服务端**]、`server` 服务端工具类、`validator` 数据验证、`dom` 浏览器节点操作相关[**前端**]、`web` 一些只适用于前端相关的工具、`color` 颜色相关工具

package/lib/crypto.js

@@ -193,7 +193,7 @@ export async function aesEncrypt(message, key, encode = "hex", iv = null) {
     else if (typeof iv === "string") {
         iv = hexToBuffer(iv);
     }
-    const encodeData = await encrypt({ ...algorithm, iv }, cryptoKey, message, encode);
+    const encodeData = await encrypt({ ...algorithm, iv: iv }, cryptoKey, message, encode);
     ciphertext = encodeData;
     resIv = bufferToHex(iv);
     return { ciphertext, iv: resIv, key };

package/lib/dom.d.ts

@@ -10,14 +10,14 @@
 type FormatStyleParam = (string | undefined | null)[] | Record<string, boolean | string | undefined | null> | string;
 type FormatClassParam = (string | undefined | null | boolean)[] | Record<string, boolean | string | undefined | null | boolean> | string;
 type DocumentContext = HTMLElement | ShadowRoot | Document;
-export declare function elem(selector: string | HTMLElement, dom?: DocumentContext): NodeListOf<HTMLElement> | HTMLElement[];
+export declare function elem(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
 /**
  * 根据选择器获取 DOM 元素。
  * @param selector - 选择器字符串或 HTMLElement 实例。
  * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
  * @returns 返回匹配到的 HTMLElement 实例。
  */
-export declare function $(selector: string | HTMLElement, dom?: DocumentContext): NodeListOf<HTMLElement> | HTMLElement[];
+export declare function $(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
 /**
  * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
  * @param tag - 元素标签名或 HTML 字符串。
@@ -46,7 +46,7 @@ export declare function $$(tag: string, option?: {
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
  * @param dom - 可选的父级 DOM 元素，默认为当前文档。
- * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
+ * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 null。
  */
 export declare function $one(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement | null;
 /**
@@ -80,8 +80,8 @@ type EventHandler = EventListenerOrEventListenerObject | ((e: CustomEvent) => vo
  * 为节点添加事件处理
  * @param {HTMLElement} element   添加事件的节点
  * @param {string}      listener  事件名称
- * @param {function}    event     事件处理函数
- * @param {boolean}     onceOrConfig  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
+ * @param {function}    fn     事件处理函数
+ * @param {boolean}     option  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
  */
 export declare function on(element: HTMLElement | ShadowRoot | Document | HTMLCollection | NodeListOf<HTMLElement> | HTMLElement[], listener: string, fn: EventHandler, option?: boolean | (AddEventListenerOptions & {
     eventFlag?: string;
@@ -119,7 +119,7 @@ export declare function html(element: HTMLElement, htmlstr?: string): string | u
  * @param textstr 可选，如果传递该参数，则表示设置；否则表示获取
  * @returns
  */
-export declare function text(element: HTMLElement, textstr?: string): string | null | undefined;
+export declare function text(element: HTMLElement, textstr?: string): string | undefined;
 export declare function iterate<T>(elems: T[], fn: (el: T, index: number) => any): void;
 export declare function iterate(elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>, fn: (el: HTMLElement, index: number) => any): void;
 /**

package/lib/dom.js

@@ -75,7 +75,7 @@ export function $$(tag, option = {}, ctx) {
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
  * @param dom - 可选的父级 DOM 元素，默认为当前文档。
- * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
+ * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 null。
  */
 export function $one(selector, dom) {
     if (typeof selector === "string") {
@@ -126,8 +126,8 @@ export function toggleClass(el, clazz) {
  * 为节点添加事件处理
  * @param {HTMLElement} element   添加事件的节点
  * @param {string}      listener  事件名称
- * @param {function}    event     事件处理函数
- * @param {boolean}     onceOrConfig  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
+ * @param {function}    fn     事件处理函数
+ * @param {boolean}     option  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
  */
 export function on(element, listener, fn, option) {
     if (element.length != null) {
@@ -527,7 +527,7 @@ export function transition(el, nameOrProperties, dir = "enter", finish) {
             });
         }
     }
-    el.addEventListener("transitionend", (_e) => {
+    el.addEventListener("transitionend", () => {
         if (status === 0) {
             status = 1;
             if (nameClass) {

package/lib/file.js

@@ -41,7 +41,7 @@ export async function write(file, data, opts) {
     if (opts.json === true && typeof data === "object") {
         writeData = JSON.stringify(data, null, opts.format === true ? 2 : 0);
     }
-    return await fs.writeFile(path.resolve(file), writeData);
+    await fs.writeFile(path.resolve(file), writeData);
 }
 /**
  * 根据文件的 stat 获取文件的 etag

package/lib/id.d.ts

@@ -1,3 +1,12 @@
+type SnowflakeIDInfo = {
+    value: string;
+    timeOffset: bigint;
+    timestamp: number;
+    machineId: bigint;
+    sequence: bigint;
+    epoch: number;
+    version: string | undefined;
+};
 /** 雪花ID, 推荐在全局构造一个对象用于生成id */
 export declare class SnowflakeID {
     /** 机器码, 默认为: 1 */
@@ -24,15 +33,7 @@ export declare class SnowflakeID {
      * @throws 如果时钟回退，抛出错误
      */
     generate(): string;
-    parse(snowflakeID: string, epoch?: number, includeVersion?: boolean): {
-        value: string;
-        timeOffset: bigint;
-        timestamp: number;
-        machineId: bigint;
-        sequence: bigint;
-        epoch: number;
-        version: string | undefined;
-    };
+    parse(snowflakeID: string, epoch?: number, includeVersion?: boolean): SnowflakeIDInfo;
 }
 /** 将uuid转换为更简单的唯一标记id */
 export declare class ShortUUID {
@@ -64,3 +65,4 @@ export declare class ShortUUID {
     private _uuidHexToInt;
     private _uuidIntToHex;
 }
+export {};

package/lib/id.js

@@ -76,7 +76,7 @@ export class SnowflakeID {
             machineId: machineId,
             sequence: sequence,
             epoch: epochTime,
-            version,
+            version: version,
         };
     }
 }

package/lib/logger.js

@@ -1,4 +1,4 @@
-import { format } from "./date";
+import { format } from "./date.js";
 /**
  * 日志记录器
  */

package/lib/server.d.ts

@@ -1,4 +1,4 @@
-import type { SpawnOptions } from "node:child_process";
+import type { SpawnOptionsWithoutStdio } from "node:child_process";
 /**
  * 执行命令
  * @param command 待执行的命令
@@ -16,3 +16,18 @@ export declare function exec(command: string, args?: string[], options?: SpawnOp
     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/server.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn as spawnOri } from "node:child_process";
 import { promisify } from "node:util";
 const execFilePromise = promisify(execFile);
 /**
@@ -27,3 +27,39 @@ export function exec(command, ...params) {
     }
     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/theme.d.ts

@@ -1,17 +1,17 @@
 /** 获取当前系统的主题 */
-export declare function getSystemTheme(): "dark" | "light" | "auto";
+export declare function getSystemTheme(): "light" | "dark" | "auto";
 /**
  * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
  * @returns 当前应用的主题
  */
-export declare function initTheme(): Promise<unknown>;
+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<unknown>;
+export declare function toggleTheme(theme?: "light" | "dark" | "auto", transition?: boolean): Promise<"light" | "dark" | "auto">;
 /** 获取当前主题 */
 export declare function getTheme(): string;
 /**
@@ -21,7 +21,7 @@ export declare function getTheme(): string;
  * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
  * @returns 应用的主题
  */
-export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean, transition?: boolean): Promise<unknown>;
+export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean, transition?: boolean): Promise<"light" | "dark" | "auto">;
 /** 获取当前主题色 */
 export declare function getColorTheme(defaultValue?: string): string | undefined;
 /**

package/package.json

@@ -68,7 +68,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.16.3",
+  "version": "0.16.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -95,8 +95,5 @@
     "date",
     "dom",
     "file"
-  ],
-  "scripts": {
-    "build": "node scripts/build.js"
-  }
+  ]
 }

package/lib/clipboard.d.ts

@@ -1,11 +0,0 @@
-/**
- * 复制数据, 可以从多种类型的数据
- *    1. 直接复制文本: await copy("待复制的文本")
- *    2. 复制节点上的 data-copy-text:
- *      <button data-copy-text="这是待复制的文本">复制</button>
- *      await copy(e.target) // or await copy("#a") or await copy(document.querySelector('#a'))
- *    3. 直接复制节点本身数据: await copy('#a')
- * @param {string | HTMLElement} source 复制源, 从中解析待复制的数据
- * @returns {Promise<boolean>} 是否复制成功
- */
-export declare function copy(source: string | HTMLElement): Promise<boolean>;

package/lib/clipboard.js

@@ -1,101 +0,0 @@
-/**
- * 创建一个临时节点缓存待复制数据
- * @param {String} value - 待复制文本
- * @return {HTMLElement}
- */
-function createFakeElement(value) {
-    const fakeElement = document.createElement("textarea");
-    fakeElement.style.border = "0";
-    fakeElement.style.padding = "0";
-    fakeElement.style.margin = "0";
-    fakeElement.style.position = "absolute";
-    fakeElement.style.left = "-9999px";
-    fakeElement.style.top = "-9999";
-    fakeElement.setAttribute("readonly", "");
-    fakeElement.value = value;
-    return fakeElement;
-}
-/** 通过执行 execCommand 来执行复制 */
-function copyFromCommand(text) {
-    // 添加节点
-    const fakeEl = createFakeElement(text);
-    document.body.append(fakeEl);
-    fakeEl.focus();
-    fakeEl.select();
-    // 执行复制
-    const res = document.execCommand("copy");
-    fakeEl.remove(); // 删除节点
-    return Promise.resolve(res);
-}
-/** 使用 navigator.clipboard 复制 */
-function copyFromClipboard(text) {
-    const theClipboard = navigator.clipboard;
-    if (theClipboard != null) {
-        return theClipboard
-            .writeText(text)
-            .then(() => {
-            Promise.resolve(true);
-        })
-            .catch(() => Promise.resolve(false));
-    }
-    return Promise.resolve(false);
-}
-/** 解析待复制的文本 */
-function parseCopyText(source) {
-    let copyText = null; // 待复制文本
-    let sourceEl = null;
-    // 获取待复制数据
-    if (typeof source === "string") {
-        // 从节点拿数据
-        if (source.startsWith("#") || source.startsWith(".")) {
-            sourceEl = document.querySelector(source);
-            if (sourceEl == null) {
-                copyText = source;
-            }
-        }
-        else {
-            copyText = source;
-        }
-    }
-    if (source instanceof HTMLElement) {
-        sourceEl = source;
-    }
-    // 从节点获取待复制数据
-    if (sourceEl != null) {
-        if (sourceEl.hasAttribute("data-copy-text")) {
-            copyText = sourceEl.getAttribute("data-copy-text");
-        }
-        else {
-            const tagName = sourceEl.tagName;
-            if (tagName === "INPUT" || tagName === "TEXTAREA") {
-                copyText = sourceEl.value;
-            }
-            else {
-                copyText = sourceEl.textContent;
-            }
-        }
-    }
-    return copyText;
-}
-/**
- * 复制数据, 可以从多种类型的数据
- *    1. 直接复制文本: await copy("待复制的文本")
- *    2. 复制节点上的 data-copy-text:
- *      <button data-copy-text="这是待复制的文本">复制</button>
- *      await copy(e.target) // or await copy("#a") or await copy(document.querySelector('#a'))
- *    3. 直接复制节点本身数据: await copy('#a')
- * @param {string | HTMLElement} source 复制源, 从中解析待复制的数据
- * @returns {Promise<boolean>} 是否复制成功
- */
-export async function copy(source) {
-    // 待复制文本
-    const copyText = parseCopyText(source);
-    if (copyText == null) {
-        return Promise.resolve(false);
-    }
-    const v = await copyFromClipboard(copyText);
-    if (v === false) {
-        return copyFromCommand(copyText);
-    }
-    return Promise.resolve(true);
-}