@knotx/utils 0.4.12 → 0.4.13

package/README.en.md

@@ -0,0 +1,346 @@
+# @knotx/utils
+
+A utility library for Knotx, providing a collection of useful utility functions including BEM naming conventions, ID generation, data operation handling, and symbol utilities.
+
+## Installation
+
+```bash
+npm install @knotx/utils
+```
+
+```bash
+yarn add @knotx/utils
+```
+
+```bash
+pnpm add @knotx/utils
+```
+
+## Overview
+
+`@knotx/utils` is a core utility library in the Knotx ecosystem, providing the following main features:
+
+- **BEM Naming Convention Tools**: Helps generate CSS class names that follow BEM specifications
+- **ID Generation Tools**: Generate unique identifiers
+- **Data Operation Tools**: Provide utility functions for data operation handling
+- **Symbol Tools**: Create and manage symbol identifiers
+
+## API Documentation
+
+### BEM Utility Functions
+
+#### `bem(block, element?, modifier?, prefix?)`
+
+Generates CSS class names according to BEM naming conventions.
+
+**Parameters:**
+- `block` (string): Block name
+- `element` (string, optional): Element name
+- `modifier` (string, optional): Modifier name
+- `prefix` (string, optional): Prefix, defaults to `'knotx-'`
+
+**Returns:**
+- `string`: Generated CSS class name
+
+**Examples:**
+
+```javascript
+import { bem } from '@knotx/utils'
+
+// Basic block
+bem('button')
+// Output: 'knotx-button'
+
+// Block + Element
+bem('button', 'text')
+// Output: 'knotx-button__text'
+
+// Block + Modifier
+bem('button', undefined, 'primary')
+// Output: 'knotx-button--primary'
+
+// Block + Element + Modifier
+bem('button', 'text', 'large')
+// Output: 'knotx-button__text--large'
+
+// Custom prefix
+bem('button', undefined, 'primary', 'my-')
+// Output: 'my-button--primary'
+```
+
+#### `addBemModifier(className, modifier)`
+
+Adds a modifier to an existing CSS class name.
+
+**Parameters:**
+- `className` (string): Existing class name
+- `modifier` (string): Modifier to add
+
+**Returns:**
+- `string`: Class name with modifier added
+
+**Examples:**
+
+```javascript
+import { addBemModifier } from '@knotx/utils'
+
+// Add modifier to class name
+addBemModifier('knotx-button', 'primary')
+// Output: 'knotx-button--primary'
+
+addBemModifier('knotx-button__text', 'large')
+// Output: 'knotx-button__text--large'
+```
+
+### ID Generation Tools
+
+#### `generateId()`
+
+Generates a unique random ID string.
+
+**Returns:**
+- `string`: Generated unique ID
+
+**Examples:**
+
+```javascript
+import { generateId } from '@knotx/utils'
+
+// Generate unique ID
+const id1 = generateId()
+// Output: 'k7j2m5n8p1r3t6'
+
+const id2 = generateId()
+// Output: 'x9z4v2b7m1k5q8'
+
+// Each call generates a different ID
+console.log(id1 === id2) // false
+```
+
+### Data Operation Tools
+
+#### `isInitOperation(operation)`
+
+Checks if an operation is an initialization batch operation.
+
+**Parameters:**
+- `operation` (DataOperation<T>): Data operation to check
+
+**Returns:**
+- `boolean`: Returns true if it's an initialization operation
+
+**Examples:**
+
+```javascript
+import { isInitOperation } from '@knotx/utils'
+
+const initOp = { type: 'batch', operations: [], isInit: true }
+const normalOp = { type: 'add', data: { id: '1' } }
+
+isInitOperation(initOp) // true
+isInitOperation(normalOp) // false
+```
+
+#### `isDraftOperation(operation)`
+
+Checks if an operation is a draft operation.
+
+**Parameters:**
+- `operation` (DataOperation<T>): Data operation to check
+
+**Returns:**
+- `boolean`: Returns true if it's a draft operation
+
+**Examples:**
+
+```javascript
+import { isDraftOperation } from '@knotx/utils'
+
+const draftOp = { type: 'draftOperation', draftId: 'draft1', operation: { type: 'add', data: { id: '1' } } }
+const normalOp = { type: 'add', data: { id: '1' } }
+
+isDraftOperation(draftOp) // true
+isDraftOperation(normalOp) // false
+```
+
+#### `isEmptyBatchOperation(operation)`
+
+Checks if a batch operation is empty.
+
+**Parameters:**
+- `operation` (DataOperation<T>): Data operation to check
+
+**Returns:**
+- `boolean`: Returns true if it's an empty batch operation
+
+**Examples:**
+
+```javascript
+import { isEmptyBatchOperation } from '@knotx/utils'
+
+const emptyBatch = { type: 'batch', operations: [] }
+const nonEmptyBatch = { type: 'batch', operations: [{ type: 'add', data: { id: '1' } }] }
+
+isEmptyBatchOperation(emptyBatch) // true
+isEmptyBatchOperation(nonEmptyBatch) // false
+```
+
+#### `flattenOperations(operations)`
+
+Flattens nested batch operations into a single-level array of operations.
+
+**Parameters:**
+- `operations` (DataOperation<T>[]): Array of operations to flatten
+
+**Returns:**
+- `DataOperation<T>[]`: Flattened array of operations
+
+**Examples:**
+
+```javascript
+import { flattenOperations } from '@knotx/utils'
+
+const nestedOps = [
+  { type: 'add', data: { id: '1' } },
+  {
+    type: 'batch',
+    operations: [
+      { type: 'add', data: { id: '2' } },
+      { type: 'remove', id: '3' }
+    ]
+  }
+]
+
+const flatOps = flattenOperations(nestedOps)
+// Output: [
+//   { type: 'add', data: { id: '1' } },
+//   { type: 'add', data: { id: '2' } },
+//   { type: 'remove', id: '3' }
+// ]
+```
+
+#### `emptyOperation()`
+
+Creates an empty batch operation.
+
+**Returns:**
+- `DataEmptyBatchOperation<T>`: Empty batch operation
+
+**Examples:**
+
+```javascript
+import { emptyOperation } from '@knotx/utils'
+
+const empty = emptyOperation()
+// Output: { type: 'batch', operations: [] }
+```
+
+#### `buildDiffOperation(previousDataMap, dataMap, compare?)`
+
+Builds a diff operation between two data maps.
+
+**Parameters:**
+- `previousDataMap` (Map<string, T>): Previous data map
+- `dataMap` (Map<string, T>): Current data map
+- `compare` (function, optional): Comparison function, defaults to `Object.is`
+
+**Returns:**
+- `DataBatchOperation<T>`: Batch operation containing diff operations
+
+**Examples:**
+
+```javascript
+import { buildDiffOperation } from '@knotx/utils'
+
+const prevData = new Map([
+  ['1', { id: '1', name: 'Alice' }],
+  ['2', { id: '2', name: 'Bob' }]
+])
+
+const currentData = new Map([
+  ['1', { id: '1', name: 'Alice Updated' }],
+  ['3', { id: '3', name: 'Charlie' }]
+])
+
+const diffOp = buildDiffOperation(prevData, currentData)
+// Output: {
+//   type: 'batch',
+//   operations: [
+//     { type: 'remove', id: '2' },
+//     { type: 'add', data: { id: '3', name: 'Charlie' } },
+//     { type: 'update', id: '1', data: { id: '1', name: 'Alice Updated' } }
+//   ],
+//   isInit: false
+// }
+```
+
+### Symbol Tools
+
+#### `getSymbol(name)`
+
+Gets or creates a symbol with a name identifier.
+
+**Parameters:**
+- `name` (string): Symbol name
+
+**Returns:**
+- `symbol`: Symbol with name identifier
+
+**Examples:**
+
+```javascript
+import { getSymbol } from '@knotx/utils'
+
+// Get symbol
+const sym1 = getSymbol('mySymbol')
+const sym2 = getSymbol('mySymbol')
+
+console.log(sym1 === sym2) // true - same name returns same symbol
+console.log(sym1.toString()) // 'Symbol(knotx:mySymbol)'
+
+// Different names return different symbols
+const sym3 = getSymbol('anotherSymbol')
+console.log(sym1 === sym3) // false
+```
+
+## Project Structure
+
+```
+packages/utils/
+├── src/
+│   ├── index.ts        # Main entry file, exports all utility functions
+│   ├── bem.ts          # BEM naming convention tools
+│   ├── id.ts           # ID generation tools
+│   ├── operation.ts    # Data operation tools
+│   └── symbol.ts       # Symbol tools
+├── dist/               # Build output directory
+├── package.json        # Package configuration
+├── tsconfig.json       # TypeScript configuration
+├── build.config.ts     # Build configuration
+└── README.en.md       # English documentation
+```
+
+## Type Definitions
+
+This package provides complete TypeScript type definitions, including:
+
+- `DataInitBatchOperation<T>`: Initialization batch operation type
+- `DataEmptyBatchOperation<T>`: Empty batch operation type
+- All function parameter and return value types
+
+## Dependencies
+
+- `@knotx/data`: Data operation related type definitions
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and Pull Requests are welcome to improve this package.
+
+## More Information
+
+- [GitHub Repository](https://github.com/boenfu/knotx)
+- [Official Website](https://github.com/boenfu/knotx#readme)

package/README.md

@@ -0,0 +1,346 @@
+# @knotx/utils
+
+Knotx 工具函数库，提供一系列实用工具函数，包括 BEM 命名约定、ID 生成、数据操作处理以及符号工具等。
+
+## 安装
+
+```bash
+npm install @knotx/utils
+```
+
+```bash
+yarn add @knotx/utils
+```
+
+```bash
+pnpm add @knotx/utils
+```
+
+## 概述
+
+`@knotx/utils` 是 Knotx 生态系统中的核心工具函数库，提供了以下主要功能：
+
+- **BEM 命名约定工具**：帮助生成符合 BEM 规范的 CSS 类名
+- **ID 生成工具**：生成唯一标识符
+- **数据操作工具**：提供数据操作相关的工具函数
+- **符号工具**：创建和管理符号标识符
+
+## API 文档
+
+### BEM 工具函数
+
+#### `bem(block, element?, modifier?, prefix?)`
+
+根据 BEM 命名约定生成 CSS 类名。
+
+**参数：**
+- `block` (string): 块名
+- `element` (string, 可选): 元素名
+- `modifier` (string, 可选): 修饰符名
+- `prefix` (string, 可选): 前缀，默认为 `'knotx-'`
+
+**返回值：**
+- `string`: 生成的 CSS 类名
+
+**示例：**
+
+```javascript
+import { bem } from '@knotx/utils'
+
+// 基础块
+bem('button')
+// 输出: 'knotx-button'
+
+// 块 + 元素
+bem('button', 'text')
+// 输出: 'knotx-button__text'
+
+// 块 + 修饰符
+bem('button', undefined, 'primary')
+// 输出: 'knotx-button--primary'
+
+// 块 + 元素 + 修饰符
+bem('button', 'text', 'large')
+// 输出: 'knotx-button__text--large'
+
+// 自定义前缀
+bem('button', undefined, 'primary', 'my-')
+// 输出: 'my-button--primary'
+```
+
+#### `addBemModifier(className, modifier)`
+
+为已有的 CSS 类名添加修饰符。
+
+**参数：**
+- `className` (string): 现有的类名
+- `modifier` (string): 要添加的修饰符
+
+**返回值：**
+- `string`: 添加修饰符后的类名
+
+**示例：**
+
+```javascript
+import { addBemModifier } from '@knotx/utils'
+
+// 为类名添加修饰符
+addBemModifier('knotx-button', 'primary')
+// 输出: 'knotx-button--primary'
+
+addBemModifier('knotx-button__text', 'large')
+// 输出: 'knotx-button__text--large'
+```
+
+### ID 生成工具
+
+#### `generateId()`
+
+生成唯一的随机 ID 字符串。
+
+**返回值：**
+- `string`: 生成的唯一 ID
+
+**示例：**
+
+```javascript
+import { generateId } from '@knotx/utils'
+
+// 生成唯一 ID
+const id1 = generateId()
+// 输出: 'k7j2m5n8p1r3t6'
+
+const id2 = generateId()
+// 输出: 'x9z4v2b7m1k5q8'
+
+// 每次调用都会生成不同的 ID
+console.log(id1 === id2) // false
+```
+
+### 数据操作工具
+
+#### `isInitOperation(operation)`
+
+检查操作是否为初始化批处理操作。
+
+**参数：**
+- `operation` (DataOperation<T>): 要检查的数据操作
+
+**返回值：**
+- `boolean`: 如果是初始化操作则返回 true
+
+**示例：**
+
+```javascript
+import { isInitOperation } from '@knotx/utils'
+
+const initOp = { type: 'batch', operations: [], isInit: true }
+const normalOp = { type: 'add', data: { id: '1' } }
+
+isInitOperation(initOp) // true
+isInitOperation(normalOp) // false
+```
+
+#### `isDraftOperation(operation)`
+
+检查操作是否为草稿操作。
+
+**参数：**
+- `operation` (DataOperation<T>): 要检查的数据操作
+
+**返回值：**
+- `boolean`: 如果是草稿操作则返回 true
+
+**示例：**
+
+```javascript
+import { isDraftOperation } from '@knotx/utils'
+
+const draftOp = { type: 'draftOperation', draftId: 'draft1', operation: { type: 'add', data: { id: '1' } } }
+const normalOp = { type: 'add', data: { id: '1' } }
+
+isDraftOperation(draftOp) // true
+isDraftOperation(normalOp) // false
+```
+
+#### `isEmptyBatchOperation(operation)`
+
+检查批处理操作是否为空。
+
+**参数：**
+- `operation` (DataOperation<T>): 要检查的数据操作
+
+**返回值：**
+- `boolean`: 如果是空批处理操作则返回 true
+
+**示例：**
+
+```javascript
+import { isEmptyBatchOperation } from '@knotx/utils'
+
+const emptyBatch = { type: 'batch', operations: [] }
+const nonEmptyBatch = { type: 'batch', operations: [{ type: 'add', data: { id: '1' } }] }
+
+isEmptyBatchOperation(emptyBatch) // true
+isEmptyBatchOperation(nonEmptyBatch) // false
+```
+
+#### `flattenOperations(operations)`
+
+将嵌套的批处理操作展平为单级操作数组。
+
+**参数：**
+- `operations` (DataOperation<T>[]): 要展平的操作数组
+
+**返回值：**
+- `DataOperation<T>[]`: 展平后的操作数组
+
+**示例：**
+
+```javascript
+import { flattenOperations } from '@knotx/utils'
+
+const nestedOps = [
+  { type: 'add', data: { id: '1' } },
+  {
+    type: 'batch',
+    operations: [
+      { type: 'add', data: { id: '2' } },
+      { type: 'remove', id: '3' }
+    ]
+  }
+]
+
+const flatOps = flattenOperations(nestedOps)
+// 输出: [
+//   { type: 'add', data: { id: '1' } },
+//   { type: 'add', data: { id: '2' } },
+//   { type: 'remove', id: '3' }
+// ]
+```
+
+#### `emptyOperation()`
+
+创建一个空的批处理操作。
+
+**返回值：**
+- `DataEmptyBatchOperation<T>`: 空的批处理操作
+
+**示例：**
+
+```javascript
+import { emptyOperation } from '@knotx/utils'
+
+const empty = emptyOperation()
+// 输出: { type: 'batch', operations: [] }
+```
+
+#### `buildDiffOperation(previousDataMap, dataMap, compare?)`
+
+构建两个数据映射之间的差异操作。
+
+**参数：**
+- `previousDataMap` (Map<string, T>): 之前的数据映射
+- `dataMap` (Map<string, T>): 当前的数据映射
+- `compare` (function, 可选): 比较函数，默认为 `Object.is`
+
+**返回值：**
+- `DataBatchOperation<T>`: 包含差异操作的批处理操作
+
+**示例：**
+
+```javascript
+import { buildDiffOperation } from '@knotx/utils'
+
+const prevData = new Map([
+  ['1', { id: '1', name: 'Alice' }],
+  ['2', { id: '2', name: 'Bob' }]
+])
+
+const currentData = new Map([
+  ['1', { id: '1', name: 'Alice Updated' }],
+  ['3', { id: '3', name: 'Charlie' }]
+])
+
+const diffOp = buildDiffOperation(prevData, currentData)
+// 输出: {
+//   type: 'batch',
+//   operations: [
+//     { type: 'remove', id: '2' },
+//     { type: 'add', data: { id: '3', name: 'Charlie' } },
+//     { type: 'update', id: '1', data: { id: '1', name: 'Alice Updated' } }
+//   ],
+//   isInit: false
+// }
+```
+
+### 符号工具
+
+#### `getSymbol(name)`
+
+获取或创建一个带有名称标识的符号。
+
+**参数：**
+- `name` (string): 符号名称
+
+**返回值：**
+- `symbol`: 带有名称标识的符号
+
+**示例：**
+
+```javascript
+import { getSymbol } from '@knotx/utils'
+
+// 获取符号
+const sym1 = getSymbol('mySymbol')
+const sym2 = getSymbol('mySymbol')
+
+console.log(sym1 === sym2) // true - 相同名称返回相同符号
+console.log(sym1.toString()) // 'Symbol(knotx:mySymbol)'
+
+// 不同名称返回不同符号
+const sym3 = getSymbol('anotherSymbol')
+console.log(sym1 === sym3) // false
+```
+
+## 项目结构
+
+```
+packages/utils/
+├── src/
+│   ├── index.ts        # 主入口文件，导出所有工具函数
+│   ├── bem.ts          # BEM 命名约定工具
+│   ├── id.ts           # ID 生成工具
+│   ├── operation.ts    # 数据操作工具
+│   └── symbol.ts       # 符号工具
+├── dist/               # 编译输出目录
+├── package.json        # 包配置文件
+├── tsconfig.json       # TypeScript 配置
+├── build.config.ts     # 构建配置
+└── README.md          # 中文文档
+```
+
+## 类型定义
+
+本包提供了完整的 TypeScript 类型定义，包括：
+
+- `DataInitBatchOperation<T>`: 初始化批处理操作类型
+- `DataEmptyBatchOperation<T>`: 空批处理操作类型
+- 以及所有函数的参数和返回值类型
+
+## 依赖
+
+- `@knotx/data`: 数据操作相关类型定义
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交 Issues 和 Pull Requests 来改进这个包。
+
+## 更多信息
+
+- [GitHub 仓库](https://github.com/boenfu/knotx)
+- [官方网站](https://github.com/boenfu/knotx#readme)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knotx/utils",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Utils for Knotx",
   "author": "boenfu",
   "license": "MIT",
@@ -28,12 +28,12 @@
     "dist"
   ],
   "dependencies": {
-    "@knotx/data": "0.4.12"
+    "@knotx/data": "0.4.13"
   },
   "devDependencies": {
-    "@knotx/build-config": "0.4.12",
-    "@knotx/eslint-config": "0.4.12",
-    "@knotx/typescript-config": "0.4.12"
+    "@knotx/build-config": "0.4.13",
+    "@knotx/eslint-config": "0.4.13",
+    "@knotx/typescript-config": "0.4.13"
   },
   "scripts": {
     "build": "unbuild",