@chancedickson/framebuffer

A library for handling length-prefixed frames.

Usage no npm install needed!

<script type="module">
  import chancedicksonFramebuffer from 'https://cdn.skypack.dev/@chancedickson/framebuffer';
</script>

README

@chancedickson/framebuffer

A library for consuming length-prefixed frames.

Usage

import { FrameBuffer, FrameBufferTransform } from "@chancedickson/framebuffer";

/**
 * Build a frame buffer with a callback for when a frame is received, the
 * number of bytes for the length prefix (between 1 and 6, default is 4),
 * and a function for reading the length prefix (default is
 * Buffer.prototype.readUIntBE, but can be Buffer.prototype.readUIntLE,
 * Buffer.prototype.readIntBE, or Buffer.prototype.readIntLE).
 *
 * FrameBuffer returns a function that you call prividing the length-prefixed
 * data as an argument. The data given to this function should be a buffer and
 * can be a partial frame, a single frame, or many frames. FrameBuffer does the
 * buffering for you, so just send it all your data and it will call the
 * provided callback with a frame's data when it receives a full frame.
 */
const frameBuffer = FrameBuffer(
  /**
   * Frame callback. Will be called when a frame is received with the frame's
   * data without the length prefix.
   */
  onFrame,

  /**
   * Number of bytes in length-prefix (optional, defaults to 4).
   */
  4,

  /**
   * Read function (optional, defaults to Buffer.prototype.readUIntBE).
   */
  Buffer.prototype.readUIntBE
);

/**
 * This is our callback that will be called when frameBuffer receives a full
 * frame. It's argument is the frame's data as a buffer without the
 * length prefix.
 */
function onFrame(frameData) {
  // Do something with frameData.
}

/**
 * Just call the returned frameBuffer when you receive data. Can be passed a
 * full frame, partial frame, or multiple frames.
 */
frameBuffer(receivedData);

/**
 * FrameBufferTransform can be used to buffer data coming in from a stream. Its
 * arguments are similar to FrameBuffer's, however it does not take a callback.
 */
const frameBufferTransform = FrameBufferTransform(
  /**
   * Number of bytes in length-prefix (optional, defaults to 4).
   */
  4,

  /**
   * Read function (optional, defaults to Buffer.prototype.readUIntBE).
   */
  Buffer.prototype.readUIntBE
);

/**
 * someReadableStream can push full frames, partial frames, or multiple
 * frames in one push. frameBufferTransform pushes the data of the full
 * frames it receives without the length prefix.
 */
someReadableStream.pipe(frameBufferTransform).pipe(someWritableStream);