perf(fs): optimize bytesToHex encoding

[runyuan-wang]

Summary

Reduce the JavaScript CPU cost of the internal bytesToHex helper by replacing per-byte toString(16).padStart(2, "0") formatting with a module-private 256-entry lookup table and using an index loop.

This preserves the existing host-neutral Uint8Array implementation and keeps the call to intrinsicByteRange, including its defensive behavior for Node Buffer values and adversarial Uint8Array subclasses. The table is readonly in TypeScript but intentionally not frozen at runtime.

Tests

Added direct algorithms-suite coverage for:

• empty input;
• lowercase, zero-padded known bytes;
• every byte value from 0 through 255;
• Node Buffer input in the existing Node test environment;
• a Uint8Array subclass that overrides byteLength, byteOffset, buffer, subarray, and iteration;
• 128 deterministic randomized equivalence cases.

Local validation on the exact base below:

• pnpm build - pass
• direct bytesToHex test - pass
• pnpm test:m1 - pass (41/41)
• pnpm typecheck - pass
• changed-file Prettier and ESLint checks - pass
• git diff --check - pass
• pnpm validate:accepted - base-red, not claimed as a pass

validate:accepted stops in check:style on these two pre-existing files:

• tests/performance/artifacts-m3-final/A5-one-byte-edit.json
• tests/performance/artifacts/A5-one-byte-edit.json

The untouched exact-base control fails at the same step with the same two files. After replacing only the isolated worktree path, the candidate and base logs are byte-identical. Neither failing file is modified here.

Microbenchmark

Scope: JavaScript bytes-to-lowercase-hex encoding only, not end-to-end filesystem throughput.

Exact base:

• commit: 4bc1f8117a7fc210577a347d87b2acfa67ec81e7
• tree: 27977c20e82e6efcd7ba1d68191090ad1965673b

Local environment: Node v26.5.0, V8 14.6.202.34-node.24, Apple M1 Ultra, arm64 macOS 14.4.1. No distinct Node 22 or 24 runtime was locally available, and no alternate runtime was installed.

Protocol: 32-byte deterministic input; 200,000 warm-up iterations per variant; 2,000,000 measured iterations per variant in each of 7 deterministically shuffled repeats; 1,003 correctness vectors per variant; medians below.

Variant	Median
Existing for...of + per-byte formatting	1237.9 ms
Index loop + per-byte formatting	1241.6 ms
Mutable lookup + for...of	750.0 ms
Mutable lookup + index loop (this change)	506.6 ms
Frozen lookup + index loop (comparison only)	735.5 ms

On this machine, the combined candidate is 2.44x faster than the existing implementation. The decomposition shows that the lookup table supplies the main gain, while the index loop is an additional change and is not presented as the sole cause. Runtime-freezing the table was 45.2% slower than the mutable module-private table here, so this patch does not use Object.freeze.

These numbers are environment-specific microbenchmark evidence. The claim is limited to reduced JS hex-encoding CPU cost; no filesystem-throughput claim is made.

Telegram: @wangrunyuansecbot | Nickname: 一心

Powered by LingTai AI: https://github.com/Lingtai-AI/lingtai