varstruct / varstruct Goto Github PK

Why not

vstruct({
  x: vstruct.DoubleBE,
  y: vstruct.DoubleBE,
  z: vstruct.DoubleBE
})

This module isn't compliant at the moment, might submit a PR if/when I have the time

Often there are times where you have a fixed size structure, but multiples of it.

Say you wanted to encode 100, 10 byte structures.
You could just send 1000 bytes, and the underlying transport protocol captures the length without needing to also provide it with the application layer; which would just be able to see 1000 bytes / 10 is 100 structures.

Thoughts on this?
Worth adding?

As found in #20, our type related error messages now:

'value must be an Array instance'
'expected value as object, got ' + value
'value must be a Buffer instance'
'value must be a string'

Why did we do + value in https://github.com/varstruct/varstruct/blob/master/lib/object.js#L23 ?

Do we want to make it consistent?

Thoughts on whether this is a bug?

v.UInt8.decode('h')
> 'h'

It'd be great if you could do something like:

vstruct([
  { type: vstruct.value(0xdeadbeef) },
  { name: 'data', type: vstruct.Buffer(32) }
])

You'd need to encode the type though I suppose, so maybe:

vstruct([
  { type: vstruct.UInt32, value: 0xdeadbeef },
  { name: 'data', type: vstruct.Buffer(32) }
])

varstruct.DoubleLE.encode('oh no a string')
// <Buffer 00 00 00 00 00 00 f8 7f>

varstruct.UInt32BE.encode(function () {})
// <Buffer 00 00 00 00>

I guess I shouldn't have expected otherwise... but maybe worth noting?

I think overall the potential for confusion is high here because there is an expectation of safety due to the explicit typing specified for the codec.

For reference, what my solution was.

Neat idea for a module! This might help simplify my module bittorrent-tracker. In order to talk to a UDP tracker, you have to produce some packed binary data (like a C struct) and I'm doing it by hand now. See: https://github.com/feross/bittorrent-tracker/blob/master/index.js#L261

When I implement UDP tracker servers (which I haven't done yet) I might give varstruct a try and see how it goes since that will involve a lot of unpacking.

@dcousens I would like to add you as collaborator.

Also, I think the time has come to move this to an org,
the essential thing about an org is that I can add others as "owners" and the owners are then able to add more collaborators, if it's under a user name, that user is the bottleneck for adding collaborators.

It took me a long while to realize that adding others was essential (because it turned out to be someone other than me which got the most use from the module) but they can't pass that on if they do not have the ability to add collaborators

Is there any interest in adding support for a Boolean type? If you think this fits, I can PR it.

I implemented it like this:

function encode (value, buffer, offset) {
  if (typeof value !== 'boolean') throw new TypeError('value must be a boolean')
  if (!buffer) buffer = Buffer.allocUnsafe(1)
  if (!offset) offset = 0
  buffer.writeUInt8(Number(value), offset)
  return buffer
}

function decode (buffer, offset, end) {
  if (!offset) offset = 0
  if (!end) return Boolean(buffer.readUInt8(offset))
  return Boolean(buffer.slice(offset, end).readUInt8(0))
}

function encodingLength () {
  return 1
}

encode.bytes = decode.bytes = 1

export const VBoolean = {
  encode,
  decode,
  encodingLength
}

It'd be much easier to just move all the test data to a JSON file and pipe each type through a consistent testing framework that tests each branch properly.

I don't want to hold back #30 from publish just because the coverage decreased a small amount, so I'll get to doing this ASAP.

If a Buffer is to be returned in decode, we return a copy.

Why?

I think users would assume Buffer is only copied when necessary, and if they intend to mutate, they would copy it prior.

Can we remove the extra Buffer.froms?
Is this a breaking change seeing as it isn't documented?

Usage

console.log(vstruct.Empty.encode())
// => Buffer < >

console.log(vstruct.Empty.decode(Buffer.alloc(0)))
// => Buffer < >

console.log(vstruct.Empty.decode(Buffer.alloc(1000)))
// => Buffer < >

No parameters, returns empty buffer.

Why?

Several layers deep in an abstraction, and this solves the problem more elegantly than handling a null type all the way down... I suppose?

Thoughts?

varstruct uses for-in loops, but order of enumerating the properties is not deterministic. ecma-262 sec. 12.6.4
I think that array of object will be good:

var vector = vstruct([
  { name: 'x', codec: vstruct.DoubleBE },
  { name: 'y', codec: vstruct.DoubleBE },
  { name: 'z', codec: vstruct.DoubleBE }
])

Do you accept PR with this changes?

Should a fixed-length encoding throw if given a Buffer that is not the expected length?

Would be cool if you could set a default value.
So if you dont provide it at encode, it will use that value.

e.g:

const Header = VStruct([
  [ 'keyIndex', VStruct.UInt8 ],
  [ 'unkn', VStruct.UInt8, 0 ],
  [ 'packetSize', VStruct.UInt16LE ],
  [ 'encrypted', VStruct.UInt8 ]
])

let buf = Header.encode({
  keyIndex: 5,
  packetSize: 7,
  encrypted: 0
})

In short form the 3rd value is default, and in normal form there could be a key called "default"

VarMap(lengthCodec, keyCodec, valueCodec)

vstruct([
   ['items', vstruct.VarMap(vstruct.UInt16, vstruct.VarString(vstruct.UInt8), vstruct.UInt32LE)]
])

You could then pass an arbitrary JS object (mapping to vstruct.UInt32LE values, or some other codec) and have an optimal encoding format for that object.

I'm thinking it would just turn into equivalent of vsturct.VarArray, but it would unpack the key/value pairs for you.