v2.0.0

README.md

@@ -136,11 +136,11 @@ class Protocol {
 ### 🔍 Reading an ArrayBuffer into Objects
 
 ```typescript
-import { binread, BinaryReader } from 'binspector'
+import { binread } from 'binspector'
 
 const buf = new Uint8Array([0x02, 0x01, 0x02, 0x03, 0x04])
 
-binread(new BinaryReader(buf), Protocol)
+binread(buf, Protocol)
 // => { len: 2, coords: [{ x: 1, y: 2 }, { x: 3, y: 4 }] }
 ```
 
@@ -151,7 +151,7 @@ import { binwrite, BinaryWriter } from 'binspector'
 
 const obj = { len: 2, coords: [{ x: 1, y: 2 }, { x: 3, y: 4 }] }
 
-binwrite(new BinaryWriter(), Protocol, obj).buffer()
+binwrite(obj, Protocol)
 // => [0x02, 0x01, 0x02, 0x03, 0x04]
 ```
 

docs/Getting-Started-With-Binspector.md

@@ -93,7 +93,7 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 
 const data = fs.readFileSync(path.join(import.meta.dirname, 'file.bin'))
-const protocol = binread(new BinaryReader(data), Protocol)
+const protocol = binread(data, Protocol)
 ```
 
 From an high level point of view the `binread` function will first check
@@ -165,9 +165,9 @@ const obj = {
     bar: 0x01
 }
 
-const protocol = binwrite(new BinaryWriter(), obj, Protocol)
+const protocol = binwrite(obj, Protocol)
 
-const buf = protocol.buffer() // <= ArrayBuffer(...)
+const buf = protocol.buffer // <= ArrayBuffer(...)
 
 await fs.appendFile(path.join(__dirname, 'proto.bin'), new Uint8Array(buf));
 ```
@@ -196,3 +196,51 @@ flowchart TB
  end
  PostOperation -->  A@{ shape: framed-circle, label: "Stop" }
 ```
+
+### 🌐 Using Binspector in the browser
+
+Considering the following tag in the webpage.
+
+```html
+<!-- Input to pass the file to the browser -->
+<input type="file" id="file-input" />
+<!-- Button to download the file -->
+<button id="file-download" />
+```
+
+A file `input` that will read the content of the file when sent to the webpage
+and a `button` that will download a serialized version of the object sent to
+the webpage.
+
+The following code shows how to handle the content with Binspector.
+
+```typescript
+import { BinaryReader, binread } from 'binspector'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+let protocol = undefined
+
+const fileInput = document.getElementById("file-input")
+fileInput.addEventListener("change", handleFileInput)
+
+const fileDownload = document.getElementById("file-download")
+fileDownload.addEventListener("click", handleFileDownload)
+
+function handleFileInput(event) {
+  const file = event.target.files[0]
+  file.arraybuffer().then((arr) => {
+      protocol = binread(arr, Protocol)
+  })
+}
+
+function handleFileDownload(event) {
+    if (protocol !== undefined) {
+        const _protocol = binwrite(protocol, Protocol)
+
+        const blob = new Blob([_protocol.buffer])
+        const url = URL.createObjectURL(blob)
+        window.open(url)
+    }
+}
+```

example/bitmap/bmp.ts

@@ -1,4 +1,4 @@
-import { PrimitiveSymbol, Relation, Count, Enum, IfThen, Else, Choice, Matrix, Offset, Uint8, Uint16, Uint32, Ascii, Endian, BinaryCursorEndianness } from '../../src/index.ts'
+import { PrimitiveSymbol, Relation, Count, Enum, IfThen, Else, Choice, Matrix, Offset, Uint8, Uint16, Uint32, Ascii, LittleEndian } from '../../src/index.ts'
 import {
   OS22XBITMAPHEADER, BITMAPINFOHEADER, BITMAPV2INFOHEADER, BITMAPV3INFOHEADER, BITMAPV4INFOHEADER, BITMAPV5INFOHEADER,
 } from './header.ts'
@@ -50,7 +50,7 @@ class BitmapFileHeader {
   offset: number
 }
 
-@Endian(BinaryCursorEndianness.LittleEndian)
+@LittleEndian
 export class Bitmap {
   @Relation(BitmapFileHeader)
   file_header: BitmapFileHeader
@@ -80,7 +80,6 @@ export class Bitmap {
   color_table: RGBQ[]
 
   /* The gap size depend on the offset found in the BitmapFileHeader */
-  /* Just use the `@Pre` decorator to move the cursor to the correct place */
   @Offset('file_header.offset')
   @Matrix('bitmap_header.width', 'bitmap_header.height', 4)
   @Choice('bitmap_header.bits_per_pixels', {
@@ -112,3 +111,5 @@ export class Bitmap {
     console.log(lines.reverse().join('\n'))
   }
 }
+
+export default Bitmap

example/bson/bson.ts

@@ -1,4 +1,5 @@
-import { Count, Enum, Int32, Match, PrimitiveSymbol, Relation, Select, Size, Uint16, Uint32, Uint8, Utf8, LittleEndian, NullTerminated, BinaryReader, binread, jsonify, binwrite, BinaryWriter } from '../../src/index.ts'
+import { type BinspectorMetaClass } from '../../src/bindump.ts'
+import { Count, Enum, Int32, Match, PrimitiveSymbol, Relation, Select, Size, Uint16, Uint32, Uint8, Utf8, LittleEndian, NullTerminated, BinaryReader, binread, jsonify, binwrite, computeBinSize } from '../../src/index.ts'
 
 // When calling JSON.stringify on a BigInt an error will be raised by default
 // We need to define the serializer for this type.
@@ -10,6 +11,9 @@
 
 BigInt.prototype.toJSON = () => Number(this)
 
+type JSONPrimitive = string | number | boolean | JSONObject | null | undefined
+type JSONObject = { [key: string]: JSONPrimitive } | JSONPrimitive[]
+
 enum BSONType {
   EndOfObject = 0x00,
   NumberDouble = 0x01,
@@ -44,7 +48,7 @@
 
   @Match(0)
   @Uint8
-  terminator: number
+  terminator: number = 0
 
   toJson () {
     return this.name
@@ -161,7 +165,7 @@
   name: string
 
   @Select(_ => BSONTypeMap[_.bson_type]())
   data: any
 
   toJson () {
     switch (this.bson_type) {
@@ -192,6 +196,38 @@
         return { [this.name]: jsonify(this.data) }
     }
   }
+
+  static create (property: string, obj: JSONPrimitive | JSONObject) {
+    const res = new BsonElement()
+    res.name = property
+    if (Array.isArray(obj)) {
+      res.bson_type = BSONType.Array
+      res.data = Bson.fromObject(obj)
+    } else if (typeof obj === 'string') {
+      res.bson_type = BSONType.String
+      const str = new BsonString()
+      str.name = obj
+      str.size = (obj.length + 1)
+      res.data = str
+    } else if (typeof obj === 'number') {
+      res.bson_type = BSONType.NumberInt
+      res.data = obj
+    } else if (typeof obj === 'bigint') {
+      res.bson_type = BSONType.NumberLong
+      res.data = obj
+    } else if (typeof obj === 'boolean') {
+      res.bson_type = BSONType.Boolean
+      res.data = obj
+    } else if (obj === null || typeof obj === 'undefined') {
+      res.bson_type = BSONType.Null
+      res.data = undefined
+    } else if (typeof obj === 'object') {
+      res.bson_type = BSONType.Object
+      res.data = Bson.fromObject(obj)
+    }
+
+    return res
+  }
 }
 
 @LittleEndian
@@ -205,7 +241,7 @@
 
   @Match(0)
   @Uint8
-  terminator: number
+  terminator: number = 0
 
   toJson () {
     return this.fields.reduce((obj, curr) => ({
@@ -215,10 +251,22 @@
   }
 
   toBuffer () {
-    return binwrite(new BinaryWriter(), Bson, this).buffer()
+    return binwrite(this)
   }
 
-  static from (buf: ArrayBufferLike) {
-    return binread(new BinaryReader(buf), Bson)
+  static from (buf: ArrayBufferLike, meta: Partial<BinspectorMetaClass> = {}) {
+    return binread(new BinaryReader(buf), Bson, { meta })
+  }
+
+  static fromObject (obj: JSONObject) {
+    const bson = new Bson()
+    const fields = Object.entries(obj).map(([k, v]) => BsonElement.create(k, v))
+
+    bson.fields = fields
+    bson.size = (computeBinSize(fields) + 5)
+
+    return bson
   }
 }
+
+export default Bson

example/bson/index.test.ts

@@ -11,3 +11,27 @@ test('Testing BSON "nested.bson" read/write equality', () => {
   const filename = path.join(path.dirname(fileURLToPath(import.meta.url)), 'nested.bson')
   expect(filename).fileReadWriteEquality(Bson)
 })
+
+test('Testing Object Serialization', () => {
+  const obj = {
+    foo: undefined,
+    bar: {
+      first: [1, 2, 3],
+      second: 'hello'
+    }
+  }
+
+  const bson = Bson.fromObject(obj)
+  expect(bson.fields.length).toStrictEqual(2)
+  expect(bson.fields[0].name).toStrictEqual('foo')
+  expect(bson.fields[1].name).toStrictEqual('bar')
+  expect(bson.fields[0].data).toStrictEqual(undefined)
+  expect(bson.fields[1].data instanceof Bson).toStrictEqual(true)
+  expect(bson.fields[1].data.fields[0].name).toStrictEqual('first')
+  expect(bson.fields[1].data.fields[1].name).toStrictEqual('second')
+  expect(bson.fields[1].data.fields[0].data instanceof Bson).toStrictEqual(true)
+  expect(bson.fields[1].data.fields[0].data.fields.length).toStrictEqual(3)
+  expect(bson.fields[1].data.fields[1].data.name).toStrictEqual('hello')
+
+  expect(bson.toJson()).toMatchObject(obj)
+})

example/bson/index.ts

@@ -1,19 +1,60 @@
-import { promises as fs } from 'node:fs'
+import fs from 'node:fs'
 import path from 'node:path'
 import { Bson } from './bson.ts'
+import BinDump, { type MetaBinReadClass } from '../../src/bindump.ts'
 
 const USAGE = `
-Usage:
+Usage: deno run index.ts [options] <file>.bson
 
-> deno run index.ts <file>.bson
+Show the content of a BSON binary file as a JSON object using binspector.
+
+Arguments:
+  file                BSON file to read.
+
+Options:
+  -j, --to-json       Output the content as a JSON object.
+  -d, --dump          Dump the content of the BSON binary in bindump format.
+  -h, --help          Display this help.
 `
 
+function parseArgument (argv: string[]) {
+  const result = {
+    toJson: false,
+    dump: false,
+    help: false,
+    filename: '',
+  }
+
+  argv.forEach((arg) => {
+    if (arg === '-j' || arg === '--to-json') {
+      result.toJson = true
+    } else if (arg === '-d' || arg === '--dump') {
+      result.dump = true
+    } else if (arg === '-h' || arg === '--help') {
+      result.help = true
+    } else if ((arg = path.join(import.meta.dirname, arg)) && fs.existsSync(arg)) {
+      result.filename = arg
+    }
+  })
+
+  return result
+}
+
 if (process.argv[1] === import.meta.filename) {
   console.log(JSON.stringify(process.argv))
-  const argv = process.argv.slice(2)
-  if (argv.length == 1) {
-    const data = await fs.readFile(path.join(import.meta.dirname, argv[0]))
-    console.log(JSON.stringify(Bson.from(data.buffer).toJson(), null, 2))
+  const args = parseArgument(process.argv.slice(2))
+  if (args.filename.length) {
+    const data = fs.readFileSync(args.filename)
+
+    const meta = {}
+    const bson = Bson.from(data.buffer, meta)
+    if (args.help) {
+      console.log(USAGE)
+    } else if (args.dump) {
+      console.log(BinDump.dump(data, meta as MetaBinReadClass, bson))
+    } else {
+      console.log(JSON.stringify(bson.toJson(), null, 2))
+    }
   } else {
     console.log(USAGE)
   }

example/devicetree/devicetree.ts

@@ -1,4 +1,4 @@
-import { NullTerminatedString, Choice, Relation, Count, Match, While, Enum, Peek, Offset, Until, EOF, Uint8, Uint32, Uint64, Padding, Endian, BinaryCursorEndianness } from '../../src/index.ts'
+import { NullTerminatedString, Choice, Relation, Count, Match, While, Enum, Peek, Offset, Until, EOF, Uint8, Uint32, Uint64, Padding, BigEndian } from '../../src/index.ts'
 
 enum DTBStructureBlockToken {
   FDT_BEGIN_NODE = 0x1,
@@ -131,7 +131,7 @@
 }
 
 function asObjectDtb (structs: DTBStructBlock[]): object {
   function setObject (o: Record<string, any>, current: string[], key: string, value: any) {
     const currentObj = current.reduce((obj, k) => obj[k], o)
 
     currentObj[key] = value
@@ -168,7 +168,7 @@
   return result
 }
 
-@Endian(BinaryCursorEndianness.BigEndian)
+@BigEndian
 export class DTB {
   @Relation(DTBHeader)
   header: DTBHeader
@@ -188,7 +188,9 @@
   @NullTerminatedString()
   strings: string[]
 
   asObject (): Record<string, any> {
     return Reflect.get(asObjectDtb(this.structs), '')
   }
 }
+
+export default DTB

example/png/png.ts

@@ -1,4 +1,4 @@
-import { Relation, Count, Match, Validate, While, Enum, Choice, Uint8, Uint16, Uint32, Ascii, Endian, BinaryCursorEndianness } from '../../src/index.ts'
+import { Relation, Count, Match, Validate, While, Enum, Choice, Uint8, Uint16, Uint32, Ascii, BigEndian } from '../../src/index.ts'
 
 enum PNGTypes {
   IHDR = 'IHDR',
@@ -139,12 +139,11 @@ class PNGChunk {
   })
   data: PNGChunkIDAT | PNGChunkPLTE | PNGChunkbKGD | PNGChunkpHYs | PNGChunktIME | PNGChunkIHDR
 
-  // @Crc(u32)
   @Uint32
   crc: number
 }
 
-@Endian(BinaryCursorEndianness.BigEndian)
+@BigEndian
 export class PNG {
   @Match([137, 80, 78, 71, 13, 10, 26, 10])
   @Count(8)
@@ -156,3 +155,5 @@ export class PNG {
   @Relation(PNGChunk)
   chunks: PNGChunk[]
 }
+
+export default PNG