ph-utils 0.6.0 → 0.6.1

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/clipboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 复制数据, 可以从多种类型的数据
+ *    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

@@ -0,0 +1,101 @@
+/**
+ * 创建一个临时节点缓存待复制数据
+ * @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);
+}

package/lib/date.d.ts

@@ -12,9 +12,9 @@ export declare function format(date?: Date | string | number | null, pattern?: s
 export declare function parse(date?: Date | string | number | null): Date;
 /**
  * 设置日期的开始或者结束的点
- * @param {Object} date 日期，能够被 parse 解析的日期
- * @param {String} unit 单位，Date|date, 默认为 Date
- * @param {Boolean} isEnd true则为 endOf
+ * @param date 日期，能够被 parse 解析的日期
+ * @param unit 单位，Date|date, 默认为 Date
+ * @param isEnd true则为 endOf
  */
 export declare function dateOf(date?: Date | string | number, unit?: string, isEnd?: boolean): Date;
 /**
@@ -45,6 +45,10 @@ export declare function timeStamp(ctime?: Date | string | number, pre?: "s" | "m
  * @param unit 需要添加的单位，date、month、year、hours、minute、second
  *
  * 查阅文档: {@link https://gitee.com/towardly/ph/wikis/utils/date ph-utils}
+ *
+ * @example <caption>1. 分钟加1并格式化显示时间</caption>
+ *
+ * add(new Date(), 1, 'minute', 'HHMMss')
  */
 export declare function add(date: Date | string | number | null, num: number, unit: string): Date;
 /**

package/lib/date.js

@@ -131,9 +131,9 @@ export function parse(date) {
 }
 /**
  * 设置日期的开始或者结束的点
- * @param {Object} date 日期，能够被 parse 解析的日期
- * @param {String} unit 单位，Date|date, 默认为 Date
- * @param {Boolean} isEnd true则为 endOf
+ * @param date 日期，能够被 parse 解析的日期
+ * @param unit 单位，Date|date, 默认为 Date
+ * @param isEnd true则为 endOf
  */
 export function dateOf(date, unit, isEnd = false) {
     /* 如果是设置某一天的开始时刻, 就需要将时、分、秒、毫秒设置为0，依次类推设置 */

package/lib/file.d.ts

@@ -1,14 +1,14 @@
 /**
- * 读取文件内容为JSON格式
- * @param filepath 读取的文件路径
- * @param defaultValue 读取失败时，提供默认值, 如果不提供传参数则[抛出异常]
- *
- * @example <caption>1. 文件不存在时, 默认为: null</caption>
- * await readJSON("./not-exists.json", true);
- *
- * @returns Promise<unknown>
+ * 读取文件内容
+ * @example <caption>1. 读取JSON文件, 内容为字符串列表</caption>
+ * read<string[]>('a.json', []);
+ * @example <caption>2. 读取JSON文件, 内容为对象</caption>
+ * read<{ name: string }>('b.json', {});
+ * @param filepath     文件路径
+ * @param defaultValue 文件不存在时默认值, 不传则抛异常, 如果传递的是对象形式则会将结果转换为 JSON
+ * @returns 文件内容
  */
-export declare function readJSON<T>(filepath: string, defaultValue?: T): Promise<T>;
+export declare function read<T>(filepath: string, defaultValue?: T): Promise<any>;
 /**
  * 写入 JSON 格式的数据到文件
  * @param file 待写入的文件
@@ -20,7 +20,7 @@ export declare function readJSON<T>(filepath: string, defaultValue?: T): Promise
 export declare function write(file: string, data: any, opts?: {
     json: boolean;
     format: boolean;
-}): Promise<unknown>;
+}): Promise<void>;
 /**
  * 根据文件的 stat 获取文件的 etag
  * @param filePath 文件地址

package/lib/file.js

@@ -1,32 +1,30 @@
 /** nodejs 文件操作工具类 */
 import path from "node:path";
-import fs from "node:fs";
+import fs from "node:fs/promises";
 /**
- * 读取文件内容为JSON格式
- * @param filepath 读取的文件路径
- * @param defaultValue 读取失败时，提供默认值, 如果不提供传参数则[抛出异常]
- *
- * @example <caption>1. 文件不存在时, 默认为: null</caption>
- * await readJSON("./not-exists.json", true);
- *
- * @returns Promise<unknown>
+ * 读取文件内容
+ * @example <caption>1. 读取JSON文件, 内容为字符串列表</caption>
+ * read<string[]>('a.json', []);
+ * @example <caption>2. 读取JSON文件, 内容为对象</caption>
+ * read<{ name: string }>('b.json', {});
+ * @param filepath     文件路径
+ * @param defaultValue 文件不存在时默认值, 不传则抛异常, 如果传递的是对象形式则会将结果转换为 JSON
+ * @returns 文件内容
  */
-export function readJSON(filepath, defaultValue) {
-    return new Promise((resolve, reject) => {
-        fs.readFile(path.resolve(filepath), "utf-8", (err, data) => {
-            if (err) {
-                if (defaultValue !== undefined) {
-                    resolve(defaultValue);
-                }
-                else {
-                    reject(err);
-                }
-            }
-            else {
-                resolve(JSON.parse(data));
-            }
-        });
-    });
+export async function read(filepath, defaultValue) {
+    let content;
+    try {
+        content = await fs.readFile(filepath, "utf8");
+        if (defaultValue != null && typeof defaultValue === "object") {
+            return JSON.parse(content);
+        }
+    }
+    catch (error) {
+        if (defaultValue === undefined) {
+            throw error;
+        }
+        return defaultValue;
+    }
 }
 /**
  * 写入 JSON 格式的数据到文件
@@ -36,22 +34,13 @@ export function readJSON(filepath, defaultValue) {
  * @property opts.json 是否写入 JSON 格式的数据，写入数据时对数据进行 JSON 格式化，默认为：true
  * @property opts.format 是否在写入 json 数据时，将 JSON 数据格式化2个空格写入, 默认为 true
  */
-export function write(file, data, opts) {
-    return new Promise((resolve, reject) => {
-        let writeData = data.toString();
-        opts = { json: true, format: true, ...opts };
-        if (opts.json === true && typeof data === "object") {
-            writeData = JSON.stringify(data, null, opts.format === true ? 2 : 0);
-        }
-        fs.writeFile(path.resolve(file), writeData, (err) => {
-            if (err) {
-                reject(err);
-            }
-            else {
-                resolve(0);
-            }
-        });
-    });
+export async function write(file, data, opts) {
+    let writeData = data.toString();
+    opts = { json: true, format: true, ...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);
 }
 /**
  * 根据文件的 stat 获取文件的 etag
@@ -59,6 +48,6 @@ export function write(file, data, opts) {
  * @returns file stat etag
  */
 export async function statTag(filePath) {
-    let stat = await fs.promises.stat(filePath);
+    let stat = await fs.stat(filePath);
     return `${stat.size.toString(16)}-${stat.mtimeMs.toString(16)}`;
 }

package/package.json

@@ -52,7 +52,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -80,9 +80,6 @@
     "dom",
     "file"
   ],
-  "dependencies": {
-    "@ctrl/tinycolor": "^4.1.0"
-  },
   "scripts": {
     "build": "node scripts/build.js"
   }