InternetMessage.js
![NPM version][npm-badge]
[npm-badge]: https://badge.fury.io/js/internet-message.png
InternetMessage.js is a small JavaScript library for parsing messages and
stringifying objects to the syntax of RFC 733 (ARPA Network Text
Message) , RFC 822 (ARPA Internet Text Messages) and RFC 2822
(Internet Message Format) . You've probably seen the format in e-mail
messages or in HTTP. It's basically a format for headers and a body . You can
use it to send both text or binary data .
InternetMessage.js isn't meant to be an e-mail or HTTP parser, but more of
a useful small library for sending standard formatted messages over any
channel that doesn't have built-in structured data. Comes in handy with message
queues (like ZeroMQ ), event sockets (WebSockets and
Server-Sent Events ) and such. Where the medium just gives you a single
blob without structure, use InternetMessage.js and RFC 822 to not have
to invent a custom format.
Example
Message-Id: fc00fc02a215412780bf09a7dcd5e33c
Content-Type: application/json
{"type":"created", "uri": "/models/1"} copy
Installing
npm install internet-message copy
InternetMessage.js follows semantic versioning , so feel
free to depend on its major version with something like >= 1.0.0 < 2
(a.k.a ^1.0.0).
Using
Create an instance of InternetMessage by giving it an object of headers and
any text for the body.
var InternetMessage = require ( "internet-message" )
var msg = new InternetMessage ({
"Content-Type" : "application/json" ,
"Location" : "http://example.com/models/1"
}, JSON. stringify ({name: "John" })) copy
Calling msg.toString() will then return the message as a string:
Content-Type: application/json
Location: http://example.com/models/1
{"name":"John"} copy
As the standard requires, lines will end with CRLF (carriage return and line
feed).
You can also use InternetMessage.stringify directly without creating an
intermediate InternetMessage instance:
InternetMessage. stringify (headers, body) copy
Parsing
Giving the message below to InternetMessage.parse will give you an instance of
InternetMessage:
Content-Type: application/json
Location: http://example.com/models/1
{"name":"John"} copy
The message will have headers as enumerable properties and a body property
with the body, if it has one. All header names are in lower-case for easier
access.
var msg = InternetMessage. parse (TEXT)
msg[ "content-type" ] // => "application/json"
msg[ "location" ] // => "http://example.com/models/1"
msg.body // => "{\"name\":\"John\"}" copy
Customizing end-of-line or start-of-body
If you wish to customize the end-of-line and start-of-body characters the header
uses, pass them as strings of any length to InternetMessage.prototype.toString
or InternetMessage.stringify.
msg. toString ({eol: " \n " })
msg. toString ({eol: " \x1e " , sob: " \x02 " })
InternetMessage. stringify (msg, {eol: " \n " }) copy
Remember to pass the same options later to InternetMessage.parse.
If you've just changed the eol option to \n, then don't bother.
InternetMessage.parse supports both \r\n and \n as the end-of-line out of
the box.
API
For extended documentation on all functions, please see the InternetMessage.js
API Documentation .
header
body
parse (message, [options])
stringify (message, [body], [options])
toJSON ()
License
InternetMessage.js is released under a Lesser GNU Affero General Public
License , which in summary means:
You can use this program for no cost .
You can use this program for both personal and commercial reasons .
You do not have to share your own program's code which uses this program.
You have to share modifications (e.g. bug-fixes) you've made to this
program.
For more convoluted language, see the LICENSE file.
About
Andri Möll typed this and the code.
Monday Calendar supported the engineering work.
If you find InternetMessage.js needs improving, please don't hesitate to type to
me now at andri@dot.ee or create an issue online .