Stop Over-Parsing Streams: The New ODAC.JS WebSockets

Handling real-time communication at enterprise scale requires extreme precision.
When building high-throughput services like collaborative whiteboards, multiplayer gaming, or financial tickers, developers cannot afford to have their raw data silently mutated by the web framework.
Yet, many modern Node.js tools fall into the trap of over-processing incoming socket data, attempting to parse everything as structured objects.
This over-convenience introduces hidden performance penalties and subtle bugs.

The latest release of ODAC.JS addresses this key developer pain point by introducing critical upgrades to the ODAC.WEBSOCKET layer.
We have rebuilt the payload routing pipeline to guarantee binary integrity, while giving developers explicit control over how text streams are decoded.
No more silent decoding errors, and no more unexpected type coercion.

Show Me The Code

Here is how simple it is to handle zero-copy, zero-mangle real-time streams with the new ODAC.JS WebSocket API.
Simply pass the parseJson: false option to secure pristine data delivery.

// route/websocket.js
const { READY_STATE } = require('odac');

Odac.Route.ws('/stream', Odac => {
  Odac.ws.on('message', data => {
    if (Buffer.isBuffer(data)) {
      // Process binary Buffer safely with no structural changes
      console.log('Binary frame size:', data.length);
    } else {
      // Process raw text string safely without auto-parsing side effects
      console.log('Received raw text:', data);
    }
  });
}, { parseJson: false });

The Danger of Over-Parsing Real-Time Payloads

To appreciate why this change is essential, we must examine the request lifecycle.
Traditionally, when a WebSocket text frame arrived, frameworks would automatically route the payload through JSON.parse().
While this is convenient for quick JSON API prototypes, it introduces severe friction for mixed or raw data streams.

For instance, consider a plain text message containing just the string "1" or "true".
An over-eager JSON parser will automatically coerce these into the integer 1 or the boolean true respectively.
This coercion breaks text-only stream semantics, forcing developers to write defensive code to re-stringify values.

Even worse, binary frames (like Buffers or TypedArrays) were often inadvertently converted to strings before parsing.
This resulted in silent data corruption, payload bloating, or random exceptions that crashed worker processes under high load.

Pristine Binary Buffers and Raw Text Streams

With this release, ODAC.JS introduces a hardened separation of concerns.
Incoming binary frames (Opcode 0x2) now bypass the JSON parser entirely.
They are delivered straight to your message handlers as raw Node.js Buffer objects, preserving every single byte.

Furthermore, we introduced the parseJson: false option for route definitions.
Setting this to false instructs ODAC.JS to skip JSON auto-parsing for incoming text streams.
Your application receives the untouched, raw text exactly as transmitted by the client.

This design gives developers absolute control over payload deserialization.
You get to decide when, where, and how to parse incoming data, maximizing efficiency and eliminating runtime surprises.

Step-by-Step Implementation Scenario

Implementing this new capability in your ODAC.JS application takes just a few steps.

1. Define the Route: Open your WebSocket routing file (typically located at route/websocket.js) and define a route using Odac.Route.ws(). Pass { parseJson: false } inside the options block.
2. Access the Connection: Within the route handler, the active WebSocket client is fully exposed via Odac.ws.
3. Listen for Messages: Register an event listener for incoming messages using Odac.ws.on('message', data => { ... }).
4. Handle and Process: Write your custom logic to check if data is a binary Buffer or a raw string, and proceed to parse it manually if needed.

Here is a full example illustrating manual JSON parsing for mixed text streams:

// route/websocket.js
Odac.Route.ws('/mixed-stream', Odac => {
  Odac.ws.on('message', data => {
    if (Buffer.isBuffer(data)) {
      // Handle binary payload
      return;
    }

    try {
      const parsed = JSON.parse(data);
      console.log('Successfully parsed custom JSON object:', parsed);
    } catch {
      console.log('Safely fallback to raw string stream:', data);
    }
  });
}, { parseJson: false });

Important Gotchas and Best Practices

While turning off auto-parsing is incredibly powerful, there are a few architectural trade-offs to keep in mind.

First, setting parseJson: false turns off the default parsing convenience for all text frames on that route.
If your frontend sends a mixture of JSON objects and raw string commands, you must handle JSON.parse() manually inside your event listener.
Always wrap your manual parser calls inside a try/catch block to protect your connection from malformed JSON payloads.

Second, remember that binary messages are never auto-parsed, regardless of your route settings.
They always arrive as a Buffer, ensuring that your media streams, WebAssembly payloads, and custom binary protocols remain completely untouched.