sculp-js 1.17.1 → 1.17.3

package/README.md

@@ -1,150 +1,136 @@
-[![Node.js CI](https://github.com/chandq/sculp-js/actions/workflows/node.js.yml/badge.svg)](https://github.com/chandq/sculp-js/actions/workflows/node.js.yml)
-[![sculp-js](https://img.shields.io/github/package-json/v/chandq/sculp-js?style=flat-square)](https://www.npmjs.com/package/sculp-js)
-
-[![license:MIT](https://img.shields.io/npm/l/vue.svg?sanitize=true)](https://github.com/chandq/sculp-js/blob/main/LICENSE.md)
-[![Downloads:?](https://img.shields.io/npm/dm/sculp-js.svg?sanitize=true)](https://npmcharts.com/compare/sculp-js?minimal=true)
-[![codecov](https://codecov.io/gh/chandq/sculp-js/graph/badge.svg?token=VZ6TERPGI9)](https://codecov.io/gh/chandq/sculp-js)
+<div align="center">
 
 # sculp-js
 
-[API Doc](https://chandq.github.io/sculp-js/)
-
-> TS + Rollup, native implementation, without relying on any third-party libraries, outputs products of three module modes: ESM, CJS, and UMD. sculp-js only used to Web environment, @sculp/core can be used to Web、Node.js、Mini Program.
-
-## Quickstart
+**A Modern JavaScript Utility Library for Web**
 
-- Via CDN: `<script src="https://unpkg.com/sculp-js"></script>`
-- Via npm:
-
-  ```js
-  npm i sculp-js
-  ```
-
-## Features
-
-- Type
-
-  - isString
-  - isBoolean
-  - isNumber
-  - isUndefined
-  - isNull
-  - isNullish
-  - isPrimitive
-  - isFunction
-  - isObject
-  - isArray
-  - typeIs
-  - isJsonString
-  - isEmpty
+[![Node.js CI](https://github.com/chandq/sculp-js/actions/workflows/node.js.yml/badge.svg)](https://github.com/chandq/sculp-js/actions/workflows/node.js.yml)
+[![sculp-js](https://img.shields.io/github/package-json/v/chandq/sculp-js?style=flat-square)](https://www.npmjs.com/package/sculp-js)
+[![license:MIT](https://img.shields.io/npm/l/vue.svg?sanitize=true)](https://github.com/chandq/sculp-js/blob/main/LICENSE.md)
+[![codecov](https://codecov.io/gh/chandq/sculp-js/graph/badge.svg?token=VZ6TERPGI9)](https://codecov.io/gh/chandq/sculp-js)
 
-- encode/decode
+</div>
 
-  - weAtob
-  - weBtoa
+<br/>
 
-- Array
+> A lightweight utility library written in TypeScript with zero dependencies, supporting ESM, CJS, and UMD formats.
 
-  - arrayEach
-  - arrayEachAsync
+**[API Documentation](https://chandq.github.io/sculp-js/)** • **[Getting Started](#usage)** • **[Features](#features)**
 
-- Tree
+## ✨ Features
 
-  - forEachDeep
-  - mapDeep
-  - findDeep
-  - filterDeep
-  - searchTreeById
-  - formatTree
-  - flatTree
-  - fuzzySearchTree
+- **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- **Zero Dependencies**: Pure native implementation, no external libraries
+- **Tree Shaking**: Supports selective imports for smaller bundle sizes
+- **Multi-Format**: ESM, CJS, and UMD builds available
+- **Web Focused**: Optimized for modern web environments
 
-- Object
+### Core Utilities
 
-  - isPlainObject
-  - objectHas
-  - objectAssign
-  - objectEach
-  - objectEachAsync
-  - objectGet
-  - cloneDeep
+<details>
+<summary><strong>Type Checking</strong></summary>
 
-- Number
+- `isString`, `isNumber`, `isBoolean`, `isFunction`, `isObject`, `isArray`
+- `isDate`, `isRegExp`, `isUndefined`, `isNull`, `isError`, `isNaN`
+- `isPrimitive`, `isSymbol`, `isBigInt`, `isPlainObject`
+- `isEmpty`, `isNodeList`, `isValidDate`, `typeIs`
 
-  - formatNumber
+</details>
 
-- String
+<details>
+<summary><strong>Data Structures</strong></summary>
 
-  - stringCamelCase
-  - stringKebabCase
-  - parseQueryParams
+- **Array**: `arrayEach`, `arrayEachAsync`, `arrayInsertBefore`, `arrayRemove`
+- **Tree**: `forEachDeep`, `mapDeep`, `findDeep`, `filterDeep`, `searchTreeById`, `flatTree`, `fuzzySearchTree`
+- **Object**: `objectAssign`, `objectGet`, `objectHas`, `cloneDeep`, `objectPick`, `objectOmit`
 
-- Unique
+</details>
 
-  - uniqueString
-  - uniqueNumber
+<details>
+<summary><strong>Web APIs</strong></summary>
 
-- Date
+- **DOM**: `addClass`, `hasClass`, `removeClass`, `getStyle`, `setStyle`
+- **File**: `chooseLocalFile`, `compressImg`
+- **Clipboard**: `copyText`, `fallbackCopyText`
+- **Download**: `downloadBlob`, `downloadURL`, `downloadData`
+- **Watermark**: `genCanvasWM`
 
-  - formatDate
-  - dateToStart
-  - dateToEnd
-  - calculateDate
-  - calculateDateTime
+</details>
 
-- Download (web)
+<details>
+<summary><strong>Encoding & Validation</strong></summary>
 
-  - downloadURL
-  - downloadHref
-  - downloadBlob
-  - downloadData
+- **Encode/Decode**: `weBtoa`, `weAtob`, `b64encode`, `b64decode`
+- **Validation**: `isEmail`, `isPhone`, `isUrl`, `isIDNO`, `isIPv4`, `isIPv6`
 
-- File (web)
+</details>
 
-  - chooseLocalFile
-  - compressImg
+<details>
+<summary><strong>Additional Utils</strong></summary>
 
-- Dom （web）
+- **Date**: `formatDate`, `calculateDate`, `dateToStart`, `dateToEnd`
+- **String**: `stringCamelCase`, `stringKebabCase`, `parseQueryParams`, `stringEscapeHTML`
+- **Math**: `add`, `subtract`, `multiply`, `divide`, `numberAbbr`
+- **Functional**: `debounce`, `throttle`, `once`, `wait`
 
-  - hasClass
-  - addClass
-  - removeClass
-  - setStyle
-  - getStyle
-  - getComputedCssVal
-  - getStrWidthPx
+</details>
 
-- Watermark (web)
+## 🚀 Installation
 
-  - genCanvasWM
+### npm
 
-- Clipboard (web)
-  - copyText
+```bash
+npm install sculp-js
+```
 
-## Install
+### CDN
 
-```js
-npm i sculp-js
+```html
+<script src="https://unpkg.com/sculp-js"></script>
 ```
 
-## Usage
+## 💡 Usage
 
 ```js
-import { forEachDeep } from 'sculp-js';
+import { forEachDeep, cloneDeep } from 'sculp-js';
 
+// Deep traversal of tree structures
 const tree = [
-  { id: 1, name: 'row1' },
   {
-    id: 2,
-    name: 'row2',
-    children: [{ id: 21, name: 'row2-1' }]
+    id: 1,
+    name: 'Parent 1',
+    children: [
+      { id: 11, name: 'Child 1' },
+      { id: 12, name: 'Child 2', children: [{ id: 121, name: 'Grandchild 1' }] }
+    ]
   },
-  { id: 3, name: 'row3' }
+  { id: 2, name: 'Parent 2' }
 ];
 
-const arr = [];
-forEachDeep(tree, ({ id, name }) => {
-  arr.push(name);
+const names = [];
+forEachDeep(tree, item => {
+  names.push(item.name);
 });
-// arr will be: ['row1', 'row2', 'row2-1', 'row3'];
+// names = ['Parent 1', 'Child 1', 'Child 2', 'Grandchild 1', 'Parent 2']
+
+// Deep cloning of objects
+const original = { a: 1, b: { c: 2 } };
+const cloned = cloneDeep(original);
 ```
+
+## 📦 Module Formats
+
+```js
+// ES Modules (recommended)
+import { cloneDeep } from 'sculp-js';
+
+// Individual module imports
+import cloneDeep from 'sculp-js/cloneDeep';
+
+// CommonJS
+const { cloneDeep } = require('sculp-js');
+```
+
+## 📄 License
+
+MIT License © 2023-present, [chandq](https://github.com/chandq)

package/dist/cjs/array.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -98,7 +98,7 @@ function arrayRemove(array, expect) {
   return array;
 }
 /**
- * Compare source array and target array, return diff result (add / delete).
+ * Compare source array and target array, return diff result (added / removed).
  *
  * - If `getKey` is not provided:
  *   - Primitive values (string | number | symbol) will be used as keys directly.
@@ -115,13 +115,13 @@ function arrayRemove(array, expect) {
  * @example
  * ```ts
  * diffArray([1, 2, 3], [2, 3, 4])
- * // => { add: [4], delete: [1] }
+ * // => { added: [4], removed: [1] }
  * ```
  *
  * @example
  * ```ts
  * diffArray(['a', 'b'], ['b', 'c'])
- * // => { add: ['c'], delete: ['a'] }
+ * // => { added: ['c'], removed: ['a'] }
  * ```
  *
  * @example
@@ -131,7 +131,7 @@ function arrayRemove(array, expect) {
  *   [{ id: 2 }, { id: 3 }],
  *   item => item.id
  * )
- * // => { add: [{ id: 3 }], delete: [{ id: 1 }] }
+ * // => { added: [{ id: 3 }], removed: [{ id: 1 }] }
  * ```
  */
 function diffArray(source, target, getKey) {
@@ -150,11 +150,11 @@ function diffArray(source, target, getKey) {
   for (const item of target) {
     targetMap.set(resolveKey(item), item);
   }
-  const add = [];
+  const added = [];
   const del = [];
   for (const [key, item] of targetMap) {
     if (!sourceMap.has(key)) {
-      add.push(item);
+      added.push(item);
     }
   }
   for (const [key, item] of sourceMap) {
@@ -162,7 +162,7 @@ function diffArray(source, target, getKey) {
       del.push(item);
     }
   }
-  return { add, delete: del };
+  return { added, removed: del };
 }
 
 exports.arrayEach = arrayEach;

package/dist/cjs/async.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/base64.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/clipboard.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/cloneDeep.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/cookie.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/date.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/dom.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/download.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/file.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/func.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/index.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/isEqual.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/math.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/number.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/object.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/path.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/qs.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/random.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/string.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/tooltip.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/tree.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/type.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/unique.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/url.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/validator.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/variable.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/watermark.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/array.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -96,7 +96,7 @@ function arrayRemove(array, expect) {
   return array;
 }
 /**
- * Compare source array and target array, return diff result (add / delete).
+ * Compare source array and target array, return diff result (added / removed).
  *
  * - If `getKey` is not provided:
  *   - Primitive values (string | number | symbol) will be used as keys directly.
@@ -113,13 +113,13 @@ function arrayRemove(array, expect) {
  * @example
  * ```ts
  * diffArray([1, 2, 3], [2, 3, 4])
- * // => { add: [4], delete: [1] }
+ * // => { added: [4], removed: [1] }
  * ```
  *
  * @example
  * ```ts
  * diffArray(['a', 'b'], ['b', 'c'])
- * // => { add: ['c'], delete: ['a'] }
+ * // => { added: ['c'], removed: ['a'] }
  * ```
  *
  * @example
@@ -129,7 +129,7 @@ function arrayRemove(array, expect) {
  *   [{ id: 2 }, { id: 3 }],
  *   item => item.id
  * )
- * // => { add: [{ id: 3 }], delete: [{ id: 1 }] }
+ * // => { added: [{ id: 3 }], removed: [{ id: 1 }] }
  * ```
  */
 function diffArray(source, target, getKey) {
@@ -148,11 +148,11 @@ function diffArray(source, target, getKey) {
   for (const item of target) {
     targetMap.set(resolveKey(item), item);
   }
-  const add = [];
+  const added = [];
   const del = [];
   for (const [key, item] of targetMap) {
     if (!sourceMap.has(key)) {
-      add.push(item);
+      added.push(item);
     }
   }
   for (const [key, item] of sourceMap) {
@@ -160,7 +160,7 @@ function diffArray(source, target, getKey) {
       del.push(item);
     }
   }
-  return { add, delete: del };
+  return { added, removed: del };
 }
 
 export { arrayEach, arrayEachAsync, arrayInsertBefore, arrayRemove, diffArray };

package/dist/esm/async.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/base64.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/clipboard.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/cloneDeep.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/cookie.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/date.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/dom.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/download.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/file.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.17.1
+ * sculp-js v1.17.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */