Skip to content

README.md

Latest commit

 

History

History
124 lines (90 loc) · 3.84 KB

README.md

File metadata and controls

124 lines (90 loc) · 3.84 KB

J2735 Codec - Node.js Bindings

This package provides high-performance Node.js bindings for the SAE J2735 (202409) V2X codec. By leveraging WebAssembly (WASM), it enables seamless, type-safe conversion between JSON (JER) and Packed Encoding Rules (UPER) directly in JavaScript and TypeScript environments.

📥 Installation

Runtime Requirements

  • Node.js: v22.16.0 (LTS) or higher.
  • Environment: Supports both CommonJS and ES Modules.

Installation via GitHub Release

The fastest way to install the bindings is to use the pre-built packages from the Releases page.

# Example: Replace v1.0.0 with the latest version tag
npm install https://github.com/verizon/j2735codec/releases/download/v1.0.0/j2735codec-1.0.0.tgz

🚀 Quick Start

The codec initialization is asynchronous to allow for non-blocking WebAssembly compilation.

import { createV2XCodec, EncodingRules, PDUTypes } from 'j2735codec';

async function main() {
  // 1. Initialize the codec (loads and compiles WASM)
  const codec = await createV2XCodec();

  const jsonContent = JSON.stringify({
    messageFrame: {
      messageId: 20,
      value: { /* ... J2735 payload ... */ }
    }
  });

  // 2. Transcode: JSON (JER) -> Packed (UPER)
  const uperBytes = codec.transcode(
    EncodingRules.JER,
    EncodingRules.UNALIGNED_BASIC_PER,
    PDUTypes.MessageFrame,
    jsonContent
  );

  console.log('Encoded UPER (Hex):', Buffer.from(uperBytes).toString('hex').toUpperCase());

  // 3. Transcode: Packed (UPER) -> JSON (JER)
  const decodedJsonRaw = codec.transcode(
    EncodingRules.UNALIGNED_BASIC_PER,
    EncodingRules.JER,
    PDUTypes.MessageFrame,
    uperBytes
  );

  const decodedJson = new TextDecoder().decode(decodedJsonRaw);
  console.log('Decoded JSON:', JSON.parse(decodedJson));
}

main().catch(console.error);

🛠 Local Development & Build Artifacts

The recommended way of installing and building is through the root Makefile. If you wish to work on the bindings directly though, here are some tips to help.

1. Build the WASM Core

Ensure you have the Prerequisites installed:

  • Emscripten
  • CMake
  • UV or Pip
# From the project root
make wasm

This command compiles the C++ core and populates src/generated/ with the required .wasm binary and metadata.

2. Build the Package and Tarball

The build process generates a flattened distribution and packages it into a compressed tarball.

cd bindings/node
npm install
npm run build

3. The Output Tarball (.tgz)

When you run make build-js (or npm pack within the node binding folder), the build system generates a distribution tarball at the project root:

  • File: node-j2735codec-<version>.tgz
  • Purpose: This file contains the compiled JavaScript, type definitions, and the bundled WASM assets.
  • Local Testing: You can test the package locally in another project by running: 
    npm install /path/to/node-j2735codec-1.0.0.tgz

4. Running Tests

We use Vitest for low-latency testing of the bindings.

npm test

📂 Internal Structure

This package uses a flattened dist/ structure to simplify asset resolution:

  • dist/: Contains compiled JS, .d.ts files, and the bundled wasm/ assets.
  • Asset Resolution: Internal path resolution is identical in development and production, ensuring the WASM binary is always locatable by the runtime.

🔢 Versioning Policy

This package follows Unified Versioning. The package.json version must stay in sync with the root VERSION file and CMakeLists.txt.

Warning: Do not bump versions manually in package.json. Use make sync-version from the root.

⚖️ License

Licensed under the Apache License 2.0. See the LICENSE file for details.