https://github.com/starryinternet/fringe
Fast, lightweight, and extensible message framing over streams
https://github.com/starryinternet/fringe
buffer javascript message-framing stream streaming
Last synced: about 1 year ago
JSON representation
Fast, lightweight, and extensible message framing over streams
- Host: GitHub
- URL: https://github.com/starryinternet/fringe
- Owner: StarryInternet
- License: mit
- Created: 2017-05-26T13:11:34.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-09-28T22:27:37.000Z (over 2 years ago)
- Last Synced: 2025-04-10T11:34:51.373Z (about 1 year ago)
- Topics: buffer, javascript, message-framing, stream, streaming
- Language: JavaScript
- Size: 53.7 KB
- Stars: 6
- Watchers: 5
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Fringe
===
[](https://travis-ci.org/StarryInternet/fringe)
Fast, lightweight, and extensible message framing over streams.
### Installing
```
npm install --save fringe
```
### Usage
By default, `fringe` encodes your input buffer with the string `FRINGE`
plus the byte length of the input buffer encoded as `UInt32BE`.
#### Hello world:
```js
const { Encoder, Parser } = require('fringe');
const encoder = new Encoder();
const parser = new Parser();
encoder.pipe( parser );
parser.on( 'message', buffer => console.log( buffer.toString('utf8') ) );
encoder.write('hello');
encoder.write('world');
```
### Events
When a complete message is received, `Parser` will emit two events:
#### data
The standard Node.js `data` events for streams. The argument passed to your
callback will be a Buffer of the original message payload.
#### message
The argument passed to the `message` event will be the return value of the
`Parser` instance's `translate` method (see below).
By default, this value will be identical to the Buffer passed to the `data`
callback – but is useful for situations where `translate` may return a parsed
object.
### Configuration
`Encoder` and `Parser` each accept two arguments:
#### format
An object containing formatting options for the message
###### prefix
A string that will be prepended to each message (may be an empty string).
Defaults to `FRINGE`.
###### lengthFormat
The binary format that the payload length will be stored as. Options are
`UInt8`, `UInt16BE`, `UInt16LE`, `UInt32BE`, and `UInt32LE`. Defaults to
`UInt32BE`.
###### maxSize
The maximum acceptable payload length in bytes. Defaults to 100 MB
(1024 * 1024 * 100).
#### options
Options to be passed directly to the underlying `Transform` stream.
### Extending
`Encoder` and `Parser` may each be sub-classes with custom `translate` methods.
#### Encoder translate
Accepts any value and must return a string or Buffer.
An example `translate` function to accept an object and output a JSON string:
```js
translate( obj ) {
return JSON.stringify( obj );
}
```
#### Parser translate
Accepts a string or Buffer and may return any value.
An example `translate` function to accept a Buffer and output an object:
```js
translate( buffer ) {
return JSON.parse( buffer.toString('utf8') );
}
```