diff --git a/.cursor/rules/coding-standards.mdc b/.cursor/rules/coding-standards.mdc new file mode 100644 index 00000000..e1b47f78 --- /dev/null +++ b/.cursor/rules/coding-standards.mdc @@ -0,0 +1,66 @@ +--- +globs: "*.js,*.ts,*.jsx,*.tsx" +description: JavaScript和TypeScript代码标准和最佳实践 +--- + +# 代码标准和最佳实践 + +本规则适用于JavaScript和TypeScript文件,定义了项目的编码规范和最佳实践。 + +## JavaScript/TypeScript 编码规范 + +### 命名约定 +- 使用camelCase命名变量和函数 +- 使用PascalCase命名类和构造函数 +- 使用UPPER_CASE命名常量 +- 使用描述性的变量名,避免缩写 +- 文件名使用kebab-case(如:binary-search.js) + +### 代码结构 +- 每个文件只导出一个主要的类或函数 +- 使用ES6模块语法(import/export) +- 保持函数简洁,遵循单一职责原则 +- 添加适当的注释说明复杂逻辑 +- 使用JSDoc格式的注释 + +### 数据结构实现规范 +- 所有数据结构都应该有基本的增删查改操作 +- 实现toString()方法用于调试和可视化 +- 提供clear()方法清空数据结构 +- 实现size()或length属性获取元素数量 +- 处理空数据结构的边界情况 +- 提供迭代器支持(Symbol.iterator) + +### 算法实现规范 +- 包含时间复杂度和空间复杂度注释 +- 提供多种实现方式(递归、迭代等) +- 添加输入验证和边界情况处理 +- 提供使用示例和测试用例 +- 实现通用的比较函数支持 + +### 测试要求 +- 每个实现都必须有对应的测试文件 +- 测试覆盖正常情况、边界情况和异常情况 +- 使用描述性的测试名称 +- 验证返回值和副作用 +- 确保100%的代码覆盖率 + +### TypeScript特殊要求 +- 使用严格的类型检查 +- 为所有公共API提供类型定义 +- 避免使用any类型 +- 使用泛型增强代码复用性 +- 利用接口定义复杂的数据结构 + +### 错误处理 +- 使用Error类或其子类抛出异常 +- 提供清晰的错误消息 +- 对无效输入进行验证 +- 文档化可能抛出的异常 + +## 性能优化建议 +- 避免不必要的循环和递归 +- 使用适当的数据结构来优化查找和插入操作 +- 考虑内存使用效率 +- 实现懒加载策略(当适用时) + diff --git a/.cursor/rules/project-structure.mdc b/.cursor/rules/project-structure.mdc new file mode 100644 index 00000000..dcd7fc05 --- /dev/null +++ b/.cursor/rules/project-structure.mdc @@ -0,0 +1,59 @@ +--- +alwaysApply: true +description: JavaScript数据结构和算法项目的结构指南 +--- + +# 项目结构指南 + +这是一个JavaScript数据结构和算法学习项目,包含JavaScript和TypeScript两个版本的实现。 + +## 主要目录结构 + +### 源代码目录 +- **src/js/**: JavaScript版本的源代码 + - `data-structures/`: 各种数据结构实现(栈、队列、链表、树、图等) + - `algorithms/`: 各种算法实现(排序、搜索、动态规划、图算法等) + - `others/`: 其他实用工具和辅助函数 + - [util.js](mdc:src/js/util.js): 通用工具函数和常量定义 + - [index.js](mdc:src/js/index.js): 主要入口文件,导出所有模块 + +- **src/ts/**: TypeScript版本的源代码(结构与js版本相同) + - 包含类型定义和更严格的类型检查 + - `models/`: 数据结构的模型定义和类型声明 + - [util.ts](mdc:src/ts/util.ts): TypeScript版本的工具函数 + - [index.ts](mdc:src/ts/index.ts): TypeScript主入口文件 + +### 测试目录 +- **test/**: 测试文件 + - `js/`: JavaScript版本的测试文件 + - `ts/`: TypeScript版本的测试文件 + - 每个实现都有对应的 `.spec.js` 或 `.spec.ts` 测试文件 + - 测试结构与源代码目录结构保持一致 + +### 示例和演示 +- **examples/**: 章节示例和演示代码 + - 按章节组织的学习示例(chapter01_02/, chapter03/, etc.) + - 包含HTML页面用于演示算法和数据结构的可视化效果 + - 每个章节包含相应的JavaScript和HTML文件 + +## 开发约定 + +- 每个数据结构和算法都有JavaScript和TypeScript两个版本 +- 所有实现都有相应的单元测试 +- 使用ES6+语法特性 +- TypeScript版本包含完整的类型定义 +- 测试使用Mocha和Chai框架 +- 支持Webpack打包和构建 + +## 配置文件 + +### 项目配置 +- [package.json](mdc:package.json): 项目依赖和脚本配置 +- [tsconfig.json](mdc:tsconfig.json): TypeScript编译配置 +- [webpack.config.js](mdc:webpack.config.js): Webpack打包配置 +- [.eslintrc.json](mdc:.eslintrc.json): ESLint代码规范配置 + +### 开发工具 +- [.gitignore](mdc:.gitignore): Git忽略文件配置 +- [.editorconfig](mdc:.editorconfig): 编辑器配置 +- [tslint.json](mdc:tslint.json): TypeScript代码检查配置 diff --git a/.cursor/rules/testing-guidelines.mdc b/.cursor/rules/testing-guidelines.mdc new file mode 100644 index 00000000..97dec464 --- /dev/null +++ b/.cursor/rules/testing-guidelines.mdc @@ -0,0 +1,127 @@ +--- +globs: "*.spec.js,*.spec.ts,*.test.js,*.test.ts" +description: 测试文件编写指导和最佳实践 +--- + +# 测试指导和最佳实践 + +本规则适用于所有测试文件,定义了测试编写的规范和最佳实践。 + +## 测试文件结构 + +### 文件命名 +- 测试文件使用 `.spec.js` 或 `.spec.ts` 后缀 +- 与被测试文件保持相同的基础名称 +- 例如:`binary-search.js` 对应 `binary-search.spec.js` + +### 测试框架 +- 使用 **Mocha** 作为测试运行器 +- 使用 **Chai** 作为断言库 +- 支持JavaScript和TypeScript测试 + +## 测试组织结构 + +### 基本模板 +```javascript +import 'mocha'; +import { expect } from 'chai'; +import { FunctionName } from '../../src/js/path/to/module'; + +describe('功能名称', () => { + // 测试用例 +}); +``` + +### 测试分组 +- 使用 `describe` 对相关测试进行分组 +- 每个类或函数都应该有自己的 `describe` 块 +- 使用中文描述测试组和测试用例 + +### 测试用例命名 +- 使用清晰、描述性的测试名称 +- 描述测试的预期行为 +- 例如:`it('应该在空数组中返回-1', () => {...})` + +## 数据结构测试标准 + +### 基本操作测试 +- 创建和初始化 +- 插入操作(push, enqueue, insert等) +- 删除操作(pop, dequeue, remove等) +- 查找操作(find, search, contains等) +- 大小获取(size, length, isEmpty等) +- 清空操作(clear) + +### 边界情况测试 +- 空数据结构操作 +- 单个元素操作 +- 最大容量操作(如果适用) +- 无效输入处理 + +### 状态验证 +- 验证数据结构的内部状态 +- 验证操作前后的状态变化 +- 使用 `toString()` 方法验证结构 + +## 算法测试标准 + +### 功能测试 +- 正常输入的正确性 +- 边界值测试 +- 异常输入处理 +- 性能基准测试(对于大数据集) + +### 排序算法测试 +- 空数组测试 +- 已排序数组测试 +- 逆序数组测试 +- 重复元素测试 +- 自定义比较函数测试 + +### 搜索算法测试 +- 找到目标元素 +- 未找到目标元素 +- 第一个和最后一个位置 +- 自定义相等比较函数 + +## 测试工具函数 + +### 通用测试函数 +- 为排序算法提供通用测试套件 +- 为搜索算法提供通用测试套件 +- 数据生成器函数 + +### 示例:排序算法测试 +```javascript +export function testSortAlgorithm(sortAlgorithm, algorithmName) { + describe(algorithmName, () => { + it('应该正确排序空数组', () => { + expect(sortAlgorithm([])).to.deep.equal([]); + }); + + it('应该正确排序非空数组', () => { + const array = [3, 1, 4, 1, 5, 9, 2, 6, 5]; + const sorted = [1, 1, 2, 3, 4, 5, 5, 6, 9]; + expect(sortAlgorithm(array)).to.deep.equal(sorted); + }); + }); +} +``` + +## 测试质量要求 + +### 覆盖率要求 +- 代码覆盖率应达到100% +- 分支覆盖率应达到100% +- 功能覆盖率应达到100% + +### 测试维护 +- 保持测试代码的清洁和可读性 +- 及时更新测试用例以反映代码变更 +- 删除无用的测试用例 + +### 性能测试 +- 对于算法实现,包含基本的性能测试 +- 验证时间复杂度符合预期 +- 测试大数据集的处理能力 + diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 00000000..84b53689 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,107 @@ +学习JavaScript数据结构与算法 +==================================== + +[![构建状态](https://travis-ci.org/loiane/javascript-datastructures-algorithms.svg?branch=master)](https://travis-ci.org/loiane/javascript-datastructures-algorithms) +[![代码覆盖率](https://codecov.io/gh/loiane/javascript-datastructures-algorithms/branch/master/graph/badge.svg)](https://codecov.io/gh/loiane/javascript-datastructures-algorithms) +[![开发依赖状态](https://david-dm.org/loiane/javascript-datastructures-algorithms/dev-status.svg)](https://david-dm.org/loiane/javascript-datastructures-algorithms?type=dev) +[![依赖状态](https://david-dm.org/loiane/javascript-datastructures-algorithms/status.svg)](https://david-dm.org/loiane/javascript-datastructures-algorithms) +[![Greenkeeper badge](https://badges.greenkeeper.io/loiane/javascript-datastructures-algorithms.svg)](https://greenkeeper.io/) + +《**学习JavaScript数据结构与算法**》第三版书籍源代码。 + +## 可用章节列表: + +* 01: [JavaScript 快速概览](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter01_02) +* 02: [ECMAScript 和 TypeScript 介绍](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter01_02) +* 03: [数组](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter03) +* 04: [栈](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter04) +* 05: [队列和双端队列](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter05) +* 06: [链表](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter06) +* 07: [集合](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter07) +* 08: [字典和散列表](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter08) +* 09: [递归](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter09) +* 10: [树](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter10) +* 11: [堆](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter11) +* 12: [图](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter12) +* 13: [排序和搜索算法](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter13) +* 14: [算法设计与技巧](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter14) +* 15: [算法复杂度](https://github.com/loiane/javascript-datastructures-algorithms/tree/third-edition/examples/chapter15) + +### 第三版更新内容 + +* 使用 ES2015+ (ES6+) 的算法实现 +* 新的数据结构和算法 +* 所有章节都经过重写和审查 +* 新增三 (3) 个章节 +* 创建了一个可在浏览器或 Node.js 中使用的数据结构和算法库 +* 使用 Mocha + Chai 测试算法(测试代码在 `test` 目录中) +* 包含源代码的 **TypeScript** 版本(包括库和测试) + +## 项目结构 + +`src/js/index.js` 文件包含按章节列出的所有数据结构和算法。 + +``` +|_examples (如何使用每个数据结构和算法,按章节组织) +|_src +|___js (源代码:JavaScript 版本) +|_____data-structures (数据结构) +|_______models (数据结构使用的类:Node、ValuePair 等) +|_____others (其他算法,如回文检查器、汉诺塔) +|___ts (源代码:TypeScript 版本) +|_____data-structures (数据结构) +|_______models (模型) +|_____others (其他算法) +|_test (使用 Mocha 和 Chai 对 src 进行单元测试) +|___js (JavaScript 代码测试) +|___ts (TypeScript 代码测试) +``` + +## 使用 Node.js 安装和运行书籍示例 + +* 安装 [Node](https://nodejs.org) +* 打开终端/命令提示符,切换到项目文件夹目录:`cd /Users/.../javascript-datastructures-algorithms` (Linux/Mac) 或 `cd C:/.../javascript-datastructures-algorithms` (Windows) +* 运行 `npm install` 安装所有依赖 +* 要查看示例,运行 `http-server html` 或 `npm run serve`。在浏览器中打开 `http:\\localhost:8080` 查看书籍示例 +* 或者 `cd html/chapter01` 并使用 node 运行每个 JavaScript 文件:`node 02-Variables` + +## 在浏览器中运行示例 + +* 右键点击您想要查看示例的 HTML 文件,右键选择 "使用 Chrome(或任何其他浏览器)打开" + +* 或者打开 `examples/index.html` 文件以轻松浏览所有示例: + +* 在线演示:[https://javascript-ds-algorithms-book.firebaseapp.com](https://javascript-ds-algorithms-book.firebaseapp.com) + + + +编程愉快! + +## 其他版本 + +| 第一版 | 第二版 | 第三版 | +| ------------- |:-------------:|:-------------:| +| ![第一版](https://images-na.ssl-images-amazon.com/images/I/51xXGv7QlBL._SX403_BO1,204,203,200_.jpg) | ![第二版](https://images-na.ssl-images-amazon.com/images/I/51PWJ%2BoKc2L._SX403_BO1,204,203,200_.jpg) | ![第三版](https://images-na.ssl-images-amazon.com/images/I/41oSXp3VztL._SX404_BO1,204,203,200_.jpg) | +| [书籍链接](http://amzn.to/1Y1OWPx)| [书籍链接](http://amzn.to/1TSkcA1)| [书籍链接](http://a.co/cbMlYmJ)| + +第一版书籍链接: + - [Packt](https://www.packtpub.com/application-development/learning-javascript-data-structures-and-algorithms) + - [Amazon](http://amzn.to/1Y1OWPx) + - [中文版](http://www.ituring.com.cn/book/1613) + - [韩文版](http://www.acornpub.co.kr/book/javascript-data-structure) + +第二版书籍链接: + - [Packt](https://www.packtpub.com/web-development/learning-javascript-data-structures-and-algorithms-second-edition) + - [Amazon](http://amzn.to/1TSkcA1) + - [中文版](http://www.ituring.com.cn/book/2029) + - [巴西葡萄牙语版](https://novatec.com.br/livros/estruturas-de-dados-algoritmos-em-javascript/) + +第三版书籍链接: + - [Packt](https://www.packtpub.com/en-us/product/learning-javascript-data-structures-and-algorithms-9781788624947) + - [Amazon](http://a.co/cbMlYmJ) + - [中文版](http://www.ituring.com.cn/book/2653) + - [巴西葡萄牙语版](https://novatec.com.br/livros/estruturas-de-dados-algoritmos-em-javascript-2ed/) + +### 发现问题或有疑问? + +请创建一个 [Issue](https://github.com/loiane/javascript-datastructures-algorithms/issues) 或 [Pull Request](https://github.com/loiane/javascript-datastructures-algorithms/pulls) \ No newline at end of file diff --git a/jsconfig.json b/jsconfig.json index 49805359..1a4b1a55 100644 --- a/jsconfig.json +++ b/jsconfig.json @@ -7,5 +7,5 @@ "strict": true }, "exclude": ["node_modules", "dist"], - "include": ["src/js/**/*","html/**"] + "include": ["src/js/**/*","html/**/*"] }