utf-8-validate

utf-8-validate is a small native Node.js addon that checks whether a Buffer contains valid UTF-8-encoded text. It exports a single function, isValidUTF8(buffer), backed by a C++ implementation (the vendored is_utf8 library) compiled via node-gyp-build, with prebuilt binaries shipped for common platforms so consumers avoid a local compile step. When no prebuilt binary is available for the current platform or architecture, it transparently falls back to a pure-JavaScript implementation so the package remains usable everywhere Node.js runs.

The library exists primarily to give the ws WebSocket library, and other real-time or binary-protocol code, a fast way to validate the UTF-8 payload of text frames per the WebSocket protocol (RFC 6455), which requires closing a connection when a text frame contains invalid UTF-8. Its narrow, single-purpose API and native-with-fallback design make it a common optional dependency wherever raw buffer-to-UTF-8 validation needs to be fast and reliable.

What You Get

• A single exported function isValidUTF8(buffer) with a boolean return value, no configuration or options to learn
• A native C++ addon (built on the vendored is_utf8 library) for maximum validation speed, loaded via node-gyp-build
• Prebuilt binaries for macOS, Linux, and Windows across x64/arm64/x86 and multiple Node.js versions, so installs skip local compilation
• A pure-JavaScript fallback (fallback.js) that activates automatically when no matching prebuilt binary exists for the host platform

Common Use Cases

• Validating the payload of WebSocket text frames before delivering them to application code, as required by RFC 6455
• Used as an optional dependency of the ws library to accelerate UTF-8 checks when the native binding is available
• Validating buffers of unknown or external origin (file uploads, network payloads) before treating them as UTF-8 text

Under The Hood

Architecture utf-8-validate is architected as a thin two-layer module: index.js attempts to load a native addon via node-gyp-build, and transparently falls back to a pure-JavaScript implementation in fallback.js if no matching prebuilt binary is found for the host platform or Node version. The native path (src/validation.cc) is a minimal N-API binding that marshals a single Buffer argument into the externally vendored is_utf8 C++ library (deps/is_utf8), returning a boolean. There is no internal layering beyond this native/fallback boundary; the entire surface area is one exported function, so there is little to break beyond the binding itself failing to load, which is exactly the case the fallback exists to handle.

Tech Stack The package targets Node.js >=6.14.2 and builds via node-gyp/binding.gyp against the N-API ABI (NAPI_VERSION 1) for cross-version binary compatibility, vendoring the is_utf8 C++ library as its actual validation implementation. Runtime dependencies are limited to node-gyp-build for locating the correct prebuilt binary at install time; devDependencies (prebuildify, prebuildify-cross, node-gyp, mocha) exist purely to produce and test those binaries. GitHub Actions CI builds and tests across a matrix of macOS/Linux/Windows, x64/arm64/x86, and multiple Node.js versions, then a separate release job runs prebuildify (including a musl/Alpine cross-build) and publishes tarballed prebuilt binaries to GitHub Releases on tag pushes.

Code Quality Testing uses mocha with a single parameterized test suite (test/test.js) that runs the same assertions against both the native binding and the fallback implementation, checking empty buffers, valid multi-byte UTF-8 (including autobahn test-suite fixtures), and known-invalid sequences such as overlong encodings and lone surrogates. CI runs this suite across every OS/arch/Node-version combination in the build matrix, giving strong confidence the native and fallback paths stay behaviorally identical. There is no linter or formatter configuration in the repository, and the codebase is plain JavaScript with no shipped type definitions, so there is no static type safety; error handling is minimal by design since the function performs no external I/O and needs none.

API Design The public API is about as minimal as a Node package can be: a single default export, isValidUTF8(buffer), taking one Buffer argument and returning a boolean, with no options object, no configuration, and no state. This makes onboarding trivial, the README’s one code sample is effectively the entire learning curve, and the optionalDependencies convention plus the automatic native/fallback swap means consumers get the performance benefit without needing any awareness of the native-binding mechanics. The README explicitly documents that the argument is not validated and correctness is the caller’s responsibility, trading input safety for raw throughput, an appropriate tradeoff for its intended use inside performance-sensitive libraries like ws.