refactor: 优化 js 端状态管理， 重构项目为 ts，优化单测, build.sh 新增快速构建 (#1)

* refactor: 项目重构为 ts, 优化 js 侧状态管理,新增队列对实例状态更新进行处理, 优化 build 脚本

* fix: build.sh 支持 macos

* fix: 单测优化

* cd: Bump version from 1.0.5 to 1.1.0

* feat: 单测重构为ts, 使用 vitest, 解决队列中的竞态问题

* fix: filename typo

Author: JimmyDaddy

.gitignore

@@ -216,3 +216,8 @@ coverage.*.html
 *.gcda
 *.gcno
 *.gcov
+
+### TypeScript ###
+dist/
+*.tsbuildinfo
+*.test.js.map

CMakeLists.txt

@@ -36,7 +36,7 @@ else()
     set(ROCKETMQ_LIB ${CMAKE_CURRENT_SOURCE_DIR}/deps/rocketmq/bin/librocketmq.a)
 endif()
 
-file(GLOB SOURCE_FILES "src/*.cpp")
+file(GLOB SOURCE_FILES "lib/*.cpp")
 add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES})
 set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
 set_target_properties(${PROJECT_NAME}
@@ -46,8 +46,8 @@ set_target_properties(${PROJECT_NAME}
         ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/build")
 target_link_libraries(${PROJECT_NAME} ${ROCKETMQ_LIB})
 
-set(CMAKE_DEPENDS_USE_COMPILER FALSE)
-set(CMAKE_SKIP_DEPENDENCY_TRACKING TRUE)
+# Keep CMake dependency tracking enabled to avoid missing compiler_depend.ts with newer CMake
+# versions when using Makefile generators.
 
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -std=c++11")

TESTING.md

@@ -0,0 +1,144 @@
+# 测试指南
+
+本项目现在使用 **Vitest** 作为测试框架，并完全支持 **TypeScript**。
+
+## 🎯 测试设置
+
+### 测试框架
+- **Vitest**: 现代、快速的测试框架
+- **TypeScript**: 所有测试文件使用 `.ts` 扩展名
+- **原生绑定支持**: 完全兼容 C++ 原生模块
+
+### 文件结构
+```
+test/
+├── consumer.test.ts      # Consumer 功能测试
+├── consumer_ack.test.ts  # Consumer ACK 测试
+├── producer.test.ts      # Producer 功能测试
+├── rocketmq_init.test.ts # 初始化测试
+└── helpers/
+    └── binding.ts        # 测试辅助工具
+```
+
+## 🚀 运行测试
+
+### 基本命令
+
+```bash
+# 完整测试（推荐）- 编译原生模块 + TypeScript + 运行测试
+npm test
+
+# 快速测试 - 只编译 TypeScript + 运行测试（需要原生模块已编译）
+npm run test:dryrun
+
+# 开发模式测试 - 带内存优化
+npm run test:dev
+
+# 覆盖率测试
+npm run test:coverage
+
+# 监视模式 - 文件变化时自动重新运行
+npm run test:watch
+```
+
+### 单独运行 Vitest
+
+```bash
+# 直接运行 Vitest
+npm run vitest
+
+# 带覆盖率
+npm run vitest:coverage
+```
+
+## 📝 编写测试
+
+### TypeScript 测试示例
+
+```typescript
+import { describe, test, expect } from 'vitest';
+import { RocketMQProducer } from '../dist/producer';
+
+describe('Producer tests', () => {
+  test('should create producer instance', () => {
+    const producer = new RocketMQProducer('test-group');
+    expect(producer).toBeTruthy();
+    expect(producer.status).toBe(0);
+  });
+
+  test('should handle async operations', async () => {
+    const producer = new RocketMQProducer('test-group');
+    await producer.start();
+    expect(producer.status).toBe(1);
+    await producer.shutdown();
+  });
+});
+```
+
+### 重要注意事项
+
+1. **导入路径**: 测试文件从 `../dist/` 导入编译后的代码，以确保原生绑定兼容性
+2. **类型安全**: 所有测试代码都有完整的 TypeScript 类型检查
+3. **异步测试**: 使用 `async/await` 处理异步操作
+4. **环境变量**: 测试会自动设置必要的环境变量
+
+## 🔧 配置
+
+### Vitest 配置 (`vitest.config.mjs`)
+
+- **环境**: Node.js 环境，适合原生绑定
+- **TypeScript**: 通过 esbuild 自动编译
+- **超时**: 原生操作设置 30 秒超时
+- **并发**: 限制为单进程以避免原生绑定冲突
+- **覆盖率**: 使用 v8 提供商，包含源码覆盖率
+
+### 覆盖率阈值
+
+- 行覆盖率: 80%
+- 函数覆盖率: 80%
+- 分支覆盖率: 70%
+- 语句覆盖率: 80%
+
+## 🐛 调试
+
+### 常见问题
+
+1. **原生绑定加载失败**
+   ```bash
+   # 确保原生模块已编译
+   npm run build:native:test
+   ```
+
+2. **TypeScript 编译错误**
+   ```bash
+   # 清理并重新编译
+   npm run clean:ts
+   npm run build:ts
+   ```
+
+3. **测试超时**
+   - 原生操作测试超时设置为 30 秒
+   - 如需调整，修改 `vitest.config.mjs` 中的 `testTimeout`
+
+### 调试模式
+
+```bash
+# 使用 Node.js 调试器
+node --inspect-brk node_modules/.bin/vitest run
+
+# 详细输出
+npm run vitest -- --reporter=verbose
+```
+
+## 📊 测试覆盖率
+
+生成详细的覆盖率报告：
+
+```bash
+npm run test:coverage
+```
+
+报告将生成在 `coverage/` 目录中，包括：
+- HTML 报告: `coverage/index.html`
+- JSON 数据: `coverage/coverage-final.json`
+- 文本摘要: 控制台输出

build.sh

@@ -163,6 +163,70 @@ build_all_linux() {
     build_linux_emulated
 }
 
+# 本地直接构建当前架构（不依赖 act/docker），用于快速调试
+build_local_host() {
+    info "=== 本地快速构建当前架构（无容器） ==="
+    local log_file="$LOG_DIR/local-${HOST_OS}-${HOST_ARCH}.log"
+    local artifact_name=""
+
+    if [[ "$HOST_OS" == "linux" ]]; then
+        if [[ "$HOST_ARCH" == "amd64" ]]; then
+            artifact_name="linux-x86_64-gnu-rocketmq.node"
+        elif [[ "$HOST_ARCH" == "arm64" ]]; then
+            artifact_name="linux-aarch64-gnu-rocketmq.node"
+        else
+            error "当前 Linux 架构不支持快速构建: $HOST_ARCH"
+            return 1
+        fi
+
+        (
+            rm -rf build/
+            npm install --no-audit --prefer-offline
+            ./deps/rocketmq/build.sh
+            npx cmake-js compile --CDCMAKE_BUILD_TYPE=Release
+            strip -s build/rocketmq.node 2>/dev/null || true
+            cp build/rocketmq.node "$RELEASE_DIR/$artifact_name"
+        ) 2>&1 | tee "$log_file"
+
+    elif [[ "$HOST_OS" == "macos" ]]; then
+        local osx_arch=""
+        if [[ "$HOST_ARCH" == "amd64" ]]; then
+            osx_arch="x86_64"
+            artifact_name="darwin-x86_64-rocketmq.node"
+        elif [[ "$HOST_ARCH" == "arm64" ]]; then
+            osx_arch="arm64"
+            artifact_name="darwin-arm64-rocketmq.node"
+        else
+            error "当前 macOS 架构不支持快速构建: $HOST_ARCH"
+            return 1
+        fi
+
+        (
+            rm -rf build/
+            npm install --no-audit --prefer-offline
+            ./deps/rocketmq/build.sh
+            npx cmake-js compile --CDCMAKE_BUILD_TYPE=Release \
+                --CDCMAKE_OSX_ARCHITECTURES="$osx_arch" \
+                --CDCMAKE_OSX_DEPLOYMENT_TARGET=11 \
+                --CDCMAKE_SKIP_DEPENDENCY_TRACKING=ON
+            strip -S -x build/rocketmq.node 2>/dev/null || true
+            cp build/rocketmq.node "$RELEASE_DIR/$artifact_name"
+        ) 2>&1 | tee "$log_file"
+
+    else
+        error "快速构建仅支持 macOS 或 Linux 主机"
+        return 1
+    fi
+
+    if [[ -f "$RELEASE_DIR/$artifact_name" ]]; then
+        success "本地快速构建完成: $artifact_name"
+        return 0
+    fi
+
+    error "本地快速构建失败，查看日志: $log_file"
+    return 1
+}
+
 # =============================================================================
 # 主逻辑
 # =============================================================================
@@ -172,24 +236,26 @@ show_help() {
 用法: $0 [选项]
 
 选项:
-  all           构建所有平台 (默认)
-  linux         构建所有 Linux 目标
-  linux-native  仅构建当前架构的 Linux 目标 (快)
-  linux-cross   仅构建交叉架构的 Linux 目标 (慢)
-  macos         构建 macOS Universal
+    all           构建所有平台 (默认)
+    linux         构建所有 Linux 目标
+    linux-native  仅构建当前架构的 Linux 目标 (快)
+    linux-cross   仅构建交叉架构的 Linux 目标 (慢)
+    macos         构建 macOS Universal
+    local         本地快速构建当前主机架构（macOS/Linux，无 act/docker）
 
-  linux-gnu-x64     单独构建 linux-gnu-x64
-  linux-gnu-arm64   单独构建 linux-gnu-arm64
-  linux-musl-x64    单独构建 linux-musl-x64
-  linux-musl-arm64  单独构建 linux-musl-arm64
+    linux-gnu-x64     单独构建 linux-gnu-x64
+    linux-gnu-arm64   单独构建 linux-gnu-arm64
+    linux-musl-x64    单独构建 linux-musl-x64
+    linux-musl-arm64  单独构建 linux-musl-arm64
 
-  -h, --help    显示帮助信息
+    -h, --help    显示帮助信息
 
 示例:
-  $0                    # 构建所有
-  $0 linux-native       # 仅构建当前架构
-  $0 linux-gnu-x64      # 仅构建指定目标
-  $0 macos              # 仅构建 macOS
+    $0                    # 构建所有
+    $0 linux-native       # 仅构建当前架构
+    $0 linux-gnu-x64      # 仅构建指定目标
+    $0 macos              # 仅构建 macOS
+    $0 local              # 本地快速构建当前架构
 EOF
 }
 
@@ -220,6 +286,10 @@ main() {
             info "=== 构建交叉架构 Linux 目标 ==="
             build_linux_emulated
             ;;
+        local)
+            info "=== 本地快速构建（当前主机架构） ==="
+            build_local_host
+            ;;
         macos)
             if [[ "$HOST_OS" != "macos" ]]; then
                 error "macOS 构建只能在 macOS 上运行"

example/status_behavior.js

@@ -0,0 +1,50 @@
+const { RocketMQProducer } = require('../src/producer');
+const { Status } = require('../src/constants');
+
+async function demonstrateStatusBehavior() {
+  const producer = new RocketMQProducer('demo-group');
+  
+  console.log('=== 新的状态行为演示 ===');
+  console.log('初始状态:', getStatusName(producer.status)); // STOPPED
+  
+  console.log('\n1. 调用 start() 后状态不会立即改变');
+  const startPromise = producer.start();
+  console.log('调用 start() 后立即检查状态:', getStatusName(producer.status)); // 可能还是 STOPPED
+  
+  await startPromise;
+  console.log('start() 完成后状态:', getStatusName(producer.status)); // STARTED
+  
+  console.log('\n2. 并发调用会被正确处理');
+  const promise1 = producer.start(); // 应该失败
+  const promise2 = producer.start(); // 应该失败
+  
+  try {
+    await promise1;
+    console.log('第一个 start() 调用成功');
+  } catch (err) {
+    console.log('第一个 start() 调用失败:', err.message);
+  }
+  
+  try {
+    await promise2;
+    console.log('第二个 start() 调用成功');
+  } catch (err) {
+    console.log('第二个 start() 调用失败:', err.message);
+  }
+  
+  console.log('\n3. 清理');
+  await producer.shutdown();
+  console.log('最终状态:', getStatusName(producer.status)); // STOPPED
+}
+
+function getStatusName(status) {
+  switch (status) {
+    case Status.STOPPED: return 'STOPPED';
+    case Status.STARTED: return 'STARTED';
+    case Status.STARTING: return 'STARTING';
+    case Status.STOPPING: return 'STOPPING';
+    default: return 'UNKNOWN';
+  }
+}
+
+demonstrateStatusBehavior().catch(console.error);