Refactor BinaryWriter and BinaryReader APIs with performance improvements

.github/workflows/test.yml

@@ -7,6 +7,9 @@ on:
     branches: [ main, develop ]
   workflow_dispatch:
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}
@@ -53,3 +56,59 @@ jobs:
         with:
           file: ./coverage/lcov.info
           fail_ci_if_error: false
+
+  benchmark:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: Install dependencies
+        run: dart pub get
+
+      - name: Run Benchmarks (JIT)
+        run: |
+          echo "### 🚀 JIT Benchmarks (Dart VM)" >> $GITHUB_STEP_SUMMARY
+          echo '```text' >> $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor jit --target test/performance/serialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor jit --target test/performance/deserialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor jit --target test/performance/strings_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor jit --target test/performance/pool_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+      - name: Run Benchmarks (AOT)
+        run: |
+          echo "### ⚡ AOT Benchmarks (Native)" >> $GITHUB_STEP_SUMMARY
+          echo '```text' >> $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor aot --target test/performance/serialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor aot --target test/performance/deserialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor aot --target test/performance/strings_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor aot --target test/performance/pool_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+      - name: Run Benchmarks (JS)
+        run: |
+          echo "### 🌐 JS Benchmarks (V8)" >> $GITHUB_STEP_SUMMARY
+          echo '```text' >> $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor js --target test/performance/serialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor js --target test/performance/deserialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor js --target test/performance/strings_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor js --target test/performance/pool_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+      - name: Run Benchmarks (WASM)
+        run: |
+          echo "### ⚙️ WASM Benchmarks" >> $GITHUB_STEP_SUMMARY
+          echo '```text' >> $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor wasm --target test/performance/serialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor wasm --target test/performance/deserialization_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor wasm --target test/performance/strings_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          dart run benchmark_harness:bench --flavor wasm --target test/performance/pool_bench.dart | tee -a $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

CHANGELOG.md

@@ -1,3 +1,21 @@
+## 3.1.0
+
+- **feat**: Added `BinaryWriterPool.withWriter()` for safer and more concise object pool usage.
+- **feat**: Added modern API features for a more idiomatic experience:
+  - `BinaryReader`: Added `operator []` for absolute byte access (e.g., `reader[0]`).
+  - `BinaryReader`: Added `call()` method for shorthand byte reading (e.g., `reader(10)`).
+  - `BinaryWriter`: Added `call()` method for shorthand byte writing (e.g., `writer([1, 2, 3])`).
+- **performance**: Optimized `writeVarString` with a high-performance one-pass "optimistic shift" algorithm (~30% faster).
+- **performance**: Unrolled `readVarUint` loop for the first 3 bytes, resulting in ~25% speedup in AOT mode.
+- **performance**: Applied Fast Path / Slow Path optimization to buffer expansion logic for better inlining.
+- **improvement**: Enhanced `BinaryWriterPool.clear()` with explicit buffer reference discarding to assist GC.
+- **fix**: Added missing `ensureSize` check in `BinaryWriterPool.acquire` to guarantee buffer capacity when reusing writers.
+- **improvement**: Updated lint rules to `pro_lints/recommended.yaml` and resolved related lint issues.
+- **deps**: Updated `pro_lints`, `test`, and `meta` dependencies to latest versions.
+- **test**: Refactored pool benchmarks for better accuracy and reliability.
+- **docs**: Fixed minor typos and improved documentation for `BinaryWriterPool`.
+- **docs**: Complete README overhaul with a focus on recipes and technical clarity.
+
 ## 3.0.0
 
 **Improvements:**