Nimoy Prospers Mystically

    decoder-ring

    4.0.0 • Public • Published

    node-decoder-ring

    Build Status

    Decoder Ring allows you to use a Javascript object as a specification to decode Node.js Buffers into a Javascript object.

    Installation

    npm install decoder-ring
    

    Usage

    Javascript Object Specification

    The Javascript object specification is used to specify endianness and a description of the fields present in the buffer.

    {
        bigEndian: true,
        fields: [
            {name: "field1", start: 0,  type: 'int8'  },
            {name: "field2", start: 1,  type: 'uint8' },
            {name: "field3", start: 2,  type: 'int16' },
            {name: "field4", start: 4,  type: 'uint16'},
            {name: "field5", start: 6,  type: 'float' },
            {name: "field6", start: 10, type: 'double'},
            {name: "field7", start: 18, type: 'ascii', length: 10 },
            {name: "field8", start: 28, type: 'utf8',  length: 9  },
            {name: "field9", start: 37, type: 'bit', position: 7},
            {name: "field10", start: 37, type: 'bit', position: 6},
            {name: "field11", start: 37, type: 'bit', position: 0},
            {name: "field12", start: 38, type: 'uint32'},
            {name: "field13", start: 42, type: 'int32'}
            {name: "field14", start: 46, type: 'int8', default: 42 }
            {name: "field15", start: 50, type: 'buffer', length: 4 }
        ]
    }
     
     

    All fields must have a name, a starting byte, and a type. The name is used for assigning the property in the resulting javascript object. Additionally, fields can have a default value which is used when encoding an object's properties that have null or undefined values.

    Types

    • buffer - Raw buffer

    • int8 - Signed 8-bit integer

    • uint8 - Unsigned 8-bit integer

    • int16 - Signed 16-bit integer

    • uint16 - Unsigned 16-bit integer

    • int32 - Signed 32-bit integer

    • uint32 - Unsigned 32-bit integer

    • float - 4-bit floating point number

    • double - 8-bit double precision floating point number

    • ascii - 8-bit per character ASCII encoded text

      This field type must also have a length property which is a count of the number of characters.

    • utf8 - 8-bit per character UTF8 encoded text

      This field type must also have a length property which is a count of the number of characters.

    • bit - true/false values

      Bit fields are pieces of a 1-byte unsigned integer. Given a big endian, unsigned integer of 129, it will appear as the following when broken down into bits:

      128(2^7) 64(2^6) 32(2^5) 16(2^4) 8(2^3) 4(2^2) 2(2^1) 1(2^0)
      1 0 0 0 0 0 0 1

      Bit fields must have a position property which is used to check if a specific bit is on or off in the 1-byte unsigned integer. The position of the bit of interest, is defined as which power of two the bit falls in the integer. For the bit in the 128th's place, the position would be 7, for the bit in the 1's place the position would be 0.

    API

    decode: (buffer, spec, { noAssert = false })

    • set noAssert to true to ignore validation of offsets

    encode: (obj, spec, { noAssert = false, padding = null })

    • set padding to a character to right pad ascii and utf8 strings instead of using null termination
    • set noAssert to true to ignore validation of written values and offsets

    Example

    var DecoderRing = require("decoder-ring");
    var decoderRing = new DecoderRing();
     
    var bufferBE = Buffer.alloc(51);
    bufferBE.writeInt8(-127, 0);
    bufferBE.writeUInt8(254, 1);
    bufferBE.writeInt16BE(5327, 2);
    bufferBE.writeUInt16BE(5328, 4);
    bufferBE.writeFloatBE(-15.33, 6);
    bufferBE.writeDoubleBE(-1534.98, 10);
    bufferBE.write("ascii", 18, 10,'ascii');
    bufferBE.write("utf8 text", 28, 9, 'utf8');
    bufferBE.writeUInt8(129, 37);
    bufferBE.writeUInt32BE(79001, 38);
    bufferBE.writeInt32BE(-79001, 42);
    bufferBE.writeInt8(1, 46);
     
    var testBuffer = new Buffer("test");
    testBuffer.copy(bufferBE, 47, 0, 4);
     
    var spec = {
      bigEndian: true,
      fields: [
        { name: "field1", start: 0,   type: 'int8'  },
        { name: "field2", start: 1,   type: 'uint8' },
        { name: "field3", start: 2,   type: 'int16' },
        { name: "field4", start: 4,   type: 'uint16'},
        { name: "field5", start: 6,   type: 'float' },
        { name: "field6", start: 10,  type: 'double'},
        { name: "field7", start: 18,  type: 'ascii', length: 10 },
        { name: "field8", start: 28,  type: 'utf8', length: 9  },
        { name: "field9", start: 37,  type: 'bit', position: 7 },
        { name: "field10", start: 37, type: 'bit', position: 6 },
        { name: "field11", start: 37, type: 'bit', position: 0 },
        { name: "field12", start: 38, type: 'uint32' },
        { name: "field13", start: 42, type: 'int32' },
        { name: "field14", start: 46, type: 'int8', default: 42 },
        { name: "field15", start: 47, type: 'buffer', length: 4 }
      ]
    };
     
    // Decode the buffer into a javascript object
    var result = decoderRing.decode(bufferBE, spec);
    console.log(result);
     
    // Assign field14 to undefined to test default value on encoding
    result.field14 = undefined;
     
    // Encode the object to a buffer
    var buffer = decoderRing.encode(result, spec);
    console.log(buffer);
     
    // Decode buffer to object and check field14 for default value
    var resultWithDefaultValue = decoderRing.decode(buffer, spec);
    console.log("Field14 default value: " + resultWithDefaultValue.field14);

    Result of the above example

    { 
      field1: -127,
      field2: 254,
      field3: 5327,
      field4: 5328,
      field5: -15.329999923706055,
      field6: -1534.98,
      field7: 'ascii\u0000\u0000\u0000\u0000\u0000',
      field8: 'utf8 text',
      field9: true,
      field10: false,
      field11: true,
      field12: 79001,
      field13: -79001,
      field14: 1,
      field15: <Buffer 74 65 73 74> 
    }
     
    <Buffer 81 fe 14 cf 14 d0 c1 75 47 ae c0 97 fb eb 85 1e b8 52 61 73 63 69 69 20 20 20 20 20 75 74 66 38 20 74 65 78 74 81 00 01 34 99 ff fe cb 67 2a>
     
    Field14 42

    Development

    Running tests

    npm test
    

    Testing the package locally

    npm pack
    npm install decoder-ring-0.4.0.tgz
    node example.js
    

    Install

    npm i decoder-ring

    DownloadsWeekly Downloads

    1

    Version

    4.0.0

    License

    MIT

    Last publish

    Collaborators

    • josephdickens87
    • nevans54
    • rrglomsk
    • jakesjews
    • eflex
    • asbaker2