Wondering what’s next for npm?Check out our public roadmap! »

    internet-message

    1.0.0 • Public • Published

    InternetMessage.js

    NPM version

    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"}
    

    Installing

    npm install internet-message

    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"}))

    Calling msg.toString() will then return the message as a string:

    Content-Type: application/json
    Location: http://example.com/models/1
    
    {"name":"John"}
    

    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)

    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"}
    

    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\"}"

    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"})

    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.

    InternetMessage

    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.

    Install

    npm i internet-message

    DownloadsWeekly Downloads

    8

    Version

    1.0.0

    License

    none

    Last publish

    Collaborators

    • avatar