Add ability to read/write signed integers, and to choose Endianness. Bump library version to 0.0.4.

Author: goddtriffin

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "byte-transcoder"
-version = "0.0.3"
+version = "0.0.4"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Todd Everett Griffin <tgriffin115@gmail.com>"]
@@ -36,4 +36,4 @@ pedantic = { level = "deny", priority = -1 }
 cargo = { level = "deny", priority = -1 }
 
 [dependencies]
-uuid = "1.14.0"
+uuid = "1.16.0"

deno.jsonc

@@ -1,6 +1,6 @@
 {
   "name": "@todd/byte-transcoder",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "exports": {
     ".": "./src-ts/mod.ts"
   },

examples/transcode.rs

@@ -1,4 +1,4 @@
-use byte_transcoder::{reader::ByteReader, reader_error::ByteReaderResult};
+use byte_transcoder::{endian::Endian, reader::ByteReader, reader_error::ByteReaderResult};
 use uuid::Uuid;
 
 #[allow(dead_code)]
@@ -40,7 +40,7 @@ fn main() -> ByteReaderResult<()> {
         4, 84, 111, 100, 100,
     ];
 
-    let mut byte_reader: ByteReader = ByteReader::new(&bytes);
+    let mut byte_reader: ByteReader = ByteReader::new(&bytes, Endian::Little);
 
     let game_id: Uuid = byte_reader.read_uuid()?;
     let join_code: String = byte_reader.read_string()?;

src-ts/byte-reader.ts

@@ -1,18 +1,21 @@
 import { validate } from "@std/uuid";
+import { Endian } from "./endian.ts";
 
 /**
  * Reads bytes from a Uint8Array.
  */
-export default class ByteReader {
+export class ByteReader {
   private data: Uint8Array;
   private position: number;
+  private endian: Endian;
 
   /**
-   * Wraps a Uint8Array to read from.
+   * Reads bytes from a Uint8Array.
    */
-  constructor(data: Uint8Array) {
+  constructor(data: Uint8Array, endian: Endian) {
     this.data = data;
     this.position = 0;
+    this.endian = endian;
   }
 
   /**
@@ -27,18 +30,44 @@ export default class ByteReader {
   }
 
   /**
-   * Reads the next two bytes as a little-endian unsigned 16-bit integer.
+   * Reads the next byte as a signed 8-bit integer.
+   */
+  public readI8(): number {
+    if (this.position >= this.data.length) {
+      throw new Error("End of buffer");
+    }
+
+    const value = this.data[this.position++];
+    return value > 127 ? value - 256 : value;
+  }
+
+  /**
+   * Reads the next two bytes as an unsigned 16-bit integer.
    */
   public readU16(): number {
     if (this.position + 2 > this.data.length) {
       throw new Error("Not enough bytes to read u16");
     }
 
-    const value: number = this.data[this.position] | (this.data[this.position + 1] << 8);
+    const value = this.endian === Endian.Little
+      ? this.data[this.position] | (this.data[this.position + 1] << 8)
+      : (this.data[this.position] << 8) | this.data[this.position + 1];
     this.position += 2;
     return value;
   }
 
+  /**
+   * Reads the next two bytes as a signed 16-bit integer.
+   */
+  public readI16(): number {
+    if (this.position + 2 > this.data.length) {
+      throw new Error("Not enough bytes to read i16");
+    }
+
+    const value = this.readU16();
+    return value > 32767 ? value - 65536 : value;
+  }
+
   /**
    * Reads the next four bytes as an unsigned 32-bit integer.
    */
@@ -47,25 +76,54 @@ export default class ByteReader {
       throw new Error("Not enough bytes to read u32");
     }
 
-    const value: number = this.data[this.position] |
-      (this.data[this.position + 1] << 8) |
-      (this.data[this.position + 2] << 16) |
-      (this.data[this.position + 3] << 24);
+    const value = this.endian === Endian.Little
+      ? this.data[this.position] |
+        (this.data[this.position + 1] << 8) |
+        (this.data[this.position + 2] << 16) |
+        (this.data[this.position + 3] << 24)
+      : (this.data[this.position] << 24) |
+        (this.data[this.position + 1] << 16) |
+        (this.data[this.position + 2] << 8) |
+        this.data[this.position + 3];
     this.position += 4;
-    return value >>> 0; // Convert to unsigned 32-bit integer
+    return value >>> 0;
   }
 
   /**
-   * Reads the next eight bytes as a little-endian unsigned 64-bit integer.
+   * Reads the next four bytes as a signed 32-bit integer.
+   */
+  public readI32(): number {
+    if (this.position + 4 > this.data.length) {
+      throw new Error("Not enough bytes to read i32");
+    }
+
+    const value = this.readU32();
+    return value > 2147483647 ? value - 4294967296 : value;
+  }
+
+  /**
+   * Reads the next eight bytes as an unsigned 64-bit integer.
    */
   public readU64(): bigint {
     if (this.position + 8 > this.data.length) {
       throw new Error("Not enough bytes to read u64");
     }
 
-    const low: bigint = BigInt(this.readU32());
-    const high: bigint = BigInt(this.readU32());
-    return (high << 32n) | low;
+    const low = BigInt(this.readU32());
+    const high = BigInt(this.readU32());
+    return this.endian === Endian.Little ? (high << 32n) | low : (low << 32n) | high;
+  }
+
+  /**
+   * Reads the next eight bytes as a signed 64-bit integer.
+   */
+  public readI64(): bigint {
+    if (this.position + 8 > this.data.length) {
+      throw new Error("Not enough bytes to read i64");
+    }
+
+    const value = this.readU64();
+    return value > 9223372036854775807n ? value - 18446744073709551616n : value;
   }
 
   /**

src-ts/byte-writer.ts

@@ -1,13 +1,19 @@
 import { validate } from "@std/uuid";
+import { Endian } from "./endian.ts";
 
 /**
  * Writes bytes to a Uint8Array.
  */
-export default class ByteWriter {
+export class ByteWriter {
   private bytes: number[];
+  private endian: Endian;
 
-  constructor() {
+  /**
+   * Writes bytes to a Uint8Array.
+   */
+  constructor(endian: Endian) {
     this.bytes = [];
+    this.endian = endian;
   }
 
   /**
@@ -22,44 +28,99 @@ export default class ByteWriter {
   }
 
   /**
-   * Writes an unsigned 16-bit integer as little-endian.
+   * Writes a signed 8-bit integer.
+   */
+  public writeI8(value: number): void {
+    if (value < -128 || value > 127) {
+      throw new Error(`Invalid i8 value: '${value}'`);
+    }
+
+    this.bytes.push(value & 0xFF);
+  }
+
+  /**
+   * Writes an unsigned 16-bit integer.
    */
   public writeU16(value: number): void {
     if (value < 0 || value > 65535) {
       throw new Error(`Invalid u16 value: '${value}'`);
     }
 
-    this.bytes.push(value & 0xFF); // least significant byte
-    this.bytes.push((value >> 8) & 0xFF); // most significant byte
+    const bytes: number[] = [value & 0xFF, (value >> 8) & 0xFF];
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
+  }
+
+  /**
+   * Writes a signed 16-bit integer.
+   */
+  public writeI16(value: number): void {
+    if (value < -32768 || value > 32767) {
+      throw new Error(`Invalid i16 value: '${value}'`);
+    }
+
+    const bytes: number[] = [value & 0xFF, (value >> 8) & 0xFF];
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
   }
 
   /**
-   * Writes an unsigned 32-bit integer as little-endian.
+   * Writes an unsigned 32-bit integer.
    */
   public writeU32(value: number): void {
     if (value < 0 || value > 4294967295) {
       throw new Error(`Invalid u32 value: '${value}'`);
     }
 
-    this.bytes.push(value & 0xFF); // least significant byte
-    this.bytes.push((value >> 8) & 0xFF);
-    this.bytes.push((value >> 16) & 0xFF);
-    this.bytes.push((value >> 24) & 0xFF); // most significant byte
+    const bytes: number[] = [
+      value & 0xFF,
+      (value >> 8) & 0xFF,
+      (value >> 16) & 0xFF,
+      (value >> 24) & 0xFF,
+    ];
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
+  }
+
+  /**
+   * Writes a signed 32-bit integer.
+   */
+  public writeI32(value: number): void {
+    if (value < -2147483648 || value > 2147483647) {
+      throw new Error(`Invalid i32 value: '${value}'`);
+    }
+
+    const bytes: number[] = [
+      value & 0xFF,
+      (value >> 8) & 0xFF,
+      (value >> 16) & 0xFF,
+      (value >> 24) & 0xFF,
+    ];
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
   }
 
   /**
-   * Writes an unsigned 64-bit integer as little-endian.
+   * Writes an unsigned 64-bit integer.
    */
   public writeU64(value: bigint): void {
     if (value < 0n || value > 18446744073709551615n) {
       throw new Error(`Invalid u64 value: '${value}'`);
     }
 
-    const low: number = Number(value & 0xFFFFFFFFn); // least significant byte
-    const high: number = Number(value >> 32n); // most significant byte
+    const bytes: number[] = Array.from({ length: 8 }, (_, i) => Number((value >> BigInt(i * 8)) & 0xFFn));
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
+  }
+
+  /**
+   * Writes a signed 64-bit integer.
+   */
+  public writeI64(value: bigint): void {
+    if (value < -9223372036854775808n || value > 9223372036854775807n) {
+      throw new Error(`Invalid i64 value: '${value}'`);
+    }
 
-    this.writeU32(low);
-    this.writeU32(high);
+    const bytes: number[] = Array.from(
+      { length: 8 },
+      (_: unknown, i: number) => Number((value >> BigInt(i * 8)) & 0xFFn),
+    );
+    this.bytes.push(...(this.endian === Endian.Little ? bytes : bytes.reverse()));
   }
 
   /**

src-ts/endian.ts

@@ -0,0 +1,7 @@
+/**
+ * Denotes the endianness of a byte array.
+ */
+export enum Endian {
+  Little,
+  Big,
+}