@helios-lang/effect 0.1.0

package/src/internal/Bits.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it } from "bun:test"
+import { Either } from "effect"
+import * as Bits from "./Bits.js"
+
+describe("Bits.Reader", () => {
+  describe("initialized with [255]", () => {
+    const bytes = [255]
+
+    it("returns 7 when reading the first 3 bits", () => {
+      const r = Bits.makeReader(bytes)
+      expect(r.readBits(3)).toBe(7)
+    })
+
+    it("is NOT at EOF when reading the first 7 bits", () => {
+      const r = Bits.makeReader(bytes)
+      r.readBits(7)
+      expect(r.isAtEnd()).toBe(false)
+    })
+
+    it("is at EOF when reading the first 8 bits", () => {
+      const r = Bits.makeReader(bytes)
+      r.readBits(8)
+      expect(r.isAtEnd()).toBe(true)
+    })
+
+    it("fails when reading 9 bits", () => {
+      const r = Bits.makeReader(bytes)
+      expect(() => r.readBits(9)).toThrow()
+    })
+  })
+
+  describe("initialized with an empty Uint8Array", () => {
+    it(`fails when reading a single bit`, () => {
+      const r = Bits.makeReader(new Uint8Array(0))
+      expect(() => r.readBits(1)).toThrow()
+    })
+
+    it(`fails when reading a single byte`, () => {
+      const r = Bits.makeReader(new Uint8Array(0))
+      expect(() => r.readByte()).toThrow()
+    })
+  })
+
+  describe("initialized with [255, 255] and truncate set to false", () => {
+    const bytes = [255, 255]
+
+    describe("discard 14 bits", () => {
+      it("returns 3 when reading 2 bits", () => {
+        const r = Bits.makeReader(bytes, false)
+        r.readBits(7)
+        r.readBits(7)
+        expect(r.readBits(2)).toBe(3)
+      })
+
+      it("returns 0b11000000 when reading 8 bits", () => {
+        const r = Bits.makeReader(bytes, false)
+        r.readBits(7)
+        r.readBits(7)
+        expect(r.readBits(8)).toBe(0b11000000)
+      })
+    })
+  })
+
+  describe("initialized with [0, 1, 2, ...] so that never at end", () => {
+    const bytes: number[] = []
+
+    for (let i = 0; i < 1000; i++) {
+      bytes.push(i % 256)
+    }
+
+    it("fails when reading more than 8 bits at a time", () => {
+      const r = Bits.makeReader(bytes)
+      expect(() => r.readBits(9)).toThrow()
+    })
+
+    it("after reading 8 bits and moving to byte boundary (which has no effect), returns 1 when reading a byte ", () => {
+      const r = Bits.makeReader(bytes)
+      r.readBits(8)
+      r.moveToByteBoundary()
+      expect(r.readByte()).toBe(1)
+    })
+
+    it("after reading 7 bits and moving to byte boundary, returns 1 when reading a byte", () => {
+      const r = Bits.makeReader(bytes)
+      r.readBits(7)
+      r.moveToByteBoundary()
+      expect(r.readByte()).toBe(1)
+    })
+
+    it("after forcing a move to byte boundary from start, returns 1 when reading a byte", () => {
+      const r = Bits.makeReader(bytes)
+      r.moveToByteBoundary(true)
+      expect(r.readByte()).toBe(1)
+    })
+  })
+})
+
+describe("Bits.Writer", () => {
+  describe("initialized without writing any bits", () => {
+    it("finalizes as []", () => {
+      expect(Bits.makeWriter().finalize(false)).toEqual([])
+    })
+
+    it("finalizes as [] after writing an empty bit-string", () => {
+      expect(Bits.makeWriter().writeBits("").finalize(false)).toEqual([])
+    })
+
+    it('fails when writing a bit-string not consisting of only "0"s and "1"s', () => {
+      const w = Bits.makeWriter()
+      expect(() => {
+        w.writeBits("2")
+      }).toThrow()
+    })
+
+    it("fails when writing -1 as a byte", () => {
+      const w = Bits.makeWriter()
+      expect(() => w.writeByte(-1)).toThrow()
+    })
+
+    it("fails when writing 256 as a byte", () => {
+      const w = Bits.makeWriter()
+      expect(() => w.writeByte(256)).toThrow()
+    })
+  })
+
+  describe('initialized by writing "0", "" (empty string), and then "1"', () => {
+    it("finalizes as [0b01000001]", () => {
+      expect(
+        Bits.makeWriter().writeBits("0").writeBits("1").finalize(false)
+      ).toEqual([0b01000001])
+    })
+
+    it("finalizes as [] after popping 2 bits", () => {
+      const w = Bits.makeWriter()
+      w.writeBits("0").writeBits("").writeBits("1").pop(2)
+      expect(w.finalize(false)).toEqual([])
+    })
+
+    it("fails when popping 3 bits", () => {
+      const w = Bits.makeWriter()
+      expect(() =>
+        w.writeBits("0").writeBits("").writeBits("1").pop(3)
+      ).toThrow()
+    })
+
+    it("finalizes as a bit-string with length divisible by 8", () => {
+      const w = Bits.makeWriter()
+      w.writeBits("0").writeBits("1").finalize(false)
+      expect(w.length % 8).toBe(0)
+    })
+  })
+
+  describe("initialized by writing 7 as a single byte", () => {
+    it("finalizes as [7]", () => {
+      const w = Bits.makeWriter()
+      expect(w.writeByte(7).finalize(false)).toEqual([7])
+    })
+
+    it("finalizes as [7, 1] if force is set to true", () => {
+      const w = Bits.makeWriter()
+      expect(w.writeByte(7).finalize(true)).toEqual([7, 1])
+    })
+
+    it('returns "111" when popping 3 bits', () => {
+      const w = Bits.makeWriter()
+      w.writeByte(7)
+      expect(w.pop(3)).toBe("111")
+    })
+
+    it("fails when popping a negative number of bits", () => {
+      const w = Bits.makeWriter()
+      w.writeByte(7)
+      expect(() => w.pop(-1)).toThrow()
+    })
+
+    it("returns an empty string when when popping 0 bits", () => {
+      const w = Bits.makeWriter()
+      w.writeByte(7)
+      expect(w.pop(0)).toBe("")
+    })
+
+    it("after popping 3 bits, finalizes as [1]", () => {
+      const w = Bits.makeWriter()
+      w.writeByte(7).pop(3)
+      expect(w.finalize(false)).toEqual([1])
+    })
+  })
+})
+
+describe("Bits.fromByte", () => {
+  describe("calling with 7 as the input byte", () => {
+    it('returns "0b00000111"', () => {
+      expect(Bits.fromByte(7)).toEqual(Either.right("0b00000111"))
+    })
+
+    it('returns "00000111" if prefix=false', () => {
+      expect(Bits.fromByte(7, 8, false)).toEqual(Either.right("00000111"))
+    })
+
+    it('returns "111" if n=3 and prefix=false', () => {
+      expect(Bits.fromByte(7, 3, false)).toEqual(Either.right("111"))
+    })
+
+    it("fails if n=2", () => {
+      expect(Bits.fromByte(7, 2)._tag).toBe("Left")
+    })
+  })
+
+  it("fails for 0 if n=0", () => {
+    expect(Bits.fromByte(0, 0, false)._tag).toBe("Left")
+  })
+
+  it("fails for a negative number", () => {
+    expect(Bits.fromByte(-1)._tag).toBe("Left")
+  })
+
+  it("fails for a non-whole number", () => {
+    expect(Bits.fromByte(3.14)._tag).toBe("Left")
+  })
+
+  it("fails for a number larger than 255", () => {
+    expect(Bits.fromByte(256)._tag).toBe("Left")
+  })
+})
+
+describe("Bits.getBit", () => {
+  it("get first bit of #00ff returns 0", () => {
+    expect(Bits.getBit([0x00, 0xff], 0)).toBe(0)
+  })
+
+  it("get last bit of #00ff returns 1", () => {
+    expect(Bits.getBit([0x00, 0xff], 15)).toBe(1)
+  })
+
+  it("returns 0 when getting indexing past bytes", () => {
+    expect(Bits.getBit([0x00, 0xff], 16)).toBe(0)
+  })
+
+  it("returns 0 when calling with negative index", () => {
+    expect(Bits.getBit([0x00, 0xff], -1)).toBe(0)
+  })
+})
+
+describe("Bits.mask", () => {
+  describe("calling with 0b11111111 as the input byte", () => {
+    it("returns 0b0111 if range=[1, 4)", () => {
+      expect(Bits.mask(0b11111111, 1, 4)).toBe(0b0111)
+    })
+
+    it("returns 0b11111111 if range=[0, 8)", () => {
+      const bits = 0b11111111
+      expect(Bits.mask(bits, 0, 8)).toBe(bits)
+    })
+
+    it("fails for range=[1, 1)", () => {
+      expect(() => Bits.mask(0b11111111, 1, 1)).toThrow()
+    })
+
+    it("fails for a range starting with a negative number", () => {
+      expect(() => Bits.mask(0b11111111, -1, 8)).toThrow()
+    })
+
+    it("fails for a range starting after 7", () => {
+      expect(() => Bits.mask(0b11111111, 8, 9)).toThrow()
+    })
+
+    it("fails for a range ending after 8", () => {
+      expect(() => Bits.mask(0b11111111, 0, 9)).toThrow()
+    })
+  })
+
+  it("fails for a negative input number", () => {
+    expect(() => Bits.mask(-1, 0, 8)).toThrow()
+  })
+
+  it("fails for an input number larger than 255", () => {
+    expect(() => Bits.mask(256, 0, 8)).toThrow()
+  })
+})
+
+describe("Bits.pad", () => {
+  describe('calling with "1111" as a bit-string', () => {
+    it('returns "00001111" if n=8', () => {
+      expect(Bits.pad("1111", 8)).toBe("00001111")
+    })
+
+    it('returns "001111" if n=3 (pads to next multiple of n if n is less than the number of bits)', () => {
+      expect(Bits.pad("1111", 3)).toBe("001111")
+    })
+
+    it('returns "1111" if n=4 (does nothing if n is equal to the input number of bits)', () => {
+      const bits = "1111"
+      expect(Bits.pad(bits, bits.length)).toBe(bits)
+    })
+
+    it("fails for negative n", () => {
+      expect(() => Bits.pad("1111", -1)).toThrow()
+    })
+  })
+})

package/src/internal/Bits.ts

@@ -0,0 +1,398 @@
+import { Either } from "effect"
+import * as Bytes from "./Bytes.js"
+
+/**
+ * Read non-byte aligned numbers
+ */
+export interface Reader {
+  isAtEnd(): boolean
+  moveToByteBoundary(force?: boolean): void
+  readBits(n: number): number
+  readByte(): number
+}
+
+/**
+ * @param bytes
+ * @param truncate defaults to true
+ * @returns {BitReader}
+ */
+export function makeReader(
+  bytes: string | number[] | Uint8Array,
+  truncate: boolean = true
+): Reader {
+  return new ReaderImpl(bytes, truncate ?? true)
+}
+
+class ReaderImpl implements Reader {
+  private readonly view: Uint8Array
+
+  /**
+   * bit position, not byte position
+   */
+  private pos: number
+
+  /**
+   * If true then read last bits as low part of number, if false pad with zero bits (only applies when trying to read more bits than there are left )
+   */
+  private readonly truncate: boolean
+
+  /**
+   * @param bytes
+   * @param truncate determines behavior when reading too many bits
+   */
+  constructor(bytes: string | number[] | Uint8Array, truncate: boolean = true) {
+    this.view = Bytes.toUint8Array(bytes)
+
+    this.pos = 0
+    this.truncate = truncate
+  }
+
+  isAtEnd(): boolean {
+    return Math.trunc(this.pos / 8) >= this.view.length
+  }
+
+  /**
+   * Moves position to next byte boundary
+   * @param force
+   * If true then move to next byte boundary if already at byte boundary
+   */
+  moveToByteBoundary(force: boolean = false): void {
+    if (this.pos % 8 != 0) {
+      const n = 8 - (this.pos % 8)
+
+      void this.readBits(n)
+    } else if (force) {
+      this.readBits(8)
+    }
+  }
+
+  /**
+   * Reads a number of bits (<= 8) and returns the result as an unsigned number
+   * @param n number of bits to read
+   * @returns
+   * @throws
+   * If at end
+   * @throws
+   * If n is larger than 8
+   */
+  readBits(n: number): number {
+    if (n > 8) {
+      throw new RangeError(
+        `Reading more than 1 byte (trying to read ${n} bits)`
+      )
+    }
+
+    let leftShift = 0
+    if (this.pos + n > this.view.length * 8) {
+      const newN = this.view.length * 8 - this.pos
+
+      if (!this.truncate) {
+        leftShift = n - newN
+      }
+
+      n = newN
+    }
+
+    if (n == 0) {
+      throw new Error("Bits.Reader is at end")
+    }
+
+    // it is assumed we don't need to be at the byte boundary
+
+    let res = 0
+    let i0 = this.pos
+
+    for (let i = this.pos + 1; i <= this.pos + n; i++) {
+      if (i % 8 == 0) {
+        const nPart = i - i0
+
+        res += mask(this.view[Math.trunc(i / 8) - 1], i0 % 8, 8) << (n - nPart)
+
+        i0 = i
+      } else if (i == this.pos + n) {
+        res += mask(this.view[Math.trunc(i / 8)], i0 % 8, i % 8)
+      }
+    }
+
+    this.pos += n
+    return res << leftShift
+  }
+
+  /**
+   * Reads 8 bits
+   * @returns
+   */
+  readByte(): number {
+    return this.readBits(8)
+  }
+}
+
+/**
+ * BitWriter turns a string of '0's and '1's into a list of bytes.
+ * Finalization pads the bits using '0*1' if not yet aligned with the byte boundary.
+ */
+export interface Writer {
+  readonly length: number
+  finalize(force?: boolean): number[]
+  padToByteBoundary(force?: boolean): void
+  pop(n: number): string
+  writeBits(bitChars: string): Writer
+  writeByte(byte: number): Writer
+}
+
+/**
+ * @returns
+ * Writer instance
+ */
+export function makeWriter() {
+  return new WriterImpl()
+}
+
+class WriterImpl implements Writer {
+  /**
+   * Concatenated and padded upon finalization
+   */
+  private readonly parts: string[]
+
+  /**
+   * Number of bits written so far
+   */
+  private n: number
+
+  constructor() {
+    this.parts = []
+    this.n = 0
+  }
+
+  get length(): number {
+    return this.n
+  }
+
+  /**
+   * Pads the Bits.Writer to align with the byte boundary and returns the resulting bytes.
+   * @param force force padding (will add one byte if already aligned)
+   * @returns
+   */
+  finalize(force: boolean = true): number[] {
+    this.padToByteBoundary(force)
+
+    const chars = this.parts.join("")
+
+    const bytes = []
+
+    for (let i = 0; i < chars.length; i += 8) {
+      const byteChars = chars.slice(i, i + 8)
+      const byte = parseInt(byteChars, 2)
+
+      bytes.push(byte)
+    }
+
+    return bytes
+  }
+
+  /**
+   * Add padding to the BitWriter in order to align with the byte boundary.
+   * @param force
+   * If 'force == true' then 8 bits are added if the Writer is already aligned.
+   */
+  padToByteBoundary(force: boolean = false): void {
+    let nPad = 0
+    if (this.n % 8 != 0) {
+      nPad = 8 - (this.n % 8)
+    } else if (force) {
+      nPad = 8
+    }
+
+    if (nPad != 0) {
+      const padding = new Array(nPad).fill("0")
+      padding[nPad - 1] = "1"
+
+      this.parts.push(padding.join(""))
+
+      this.n += nPad
+    }
+  }
+
+  /**
+   * Pop n bits of the end
+   * @param n
+   * @returns
+   */
+  pop(n: number): string {
+    if (n > this.n) {
+      throw new Error(
+        `Too many bits to pop, only have ${this.n} bits, but want n=${n}`
+      )
+    }
+
+    const n0 = n
+
+    const parts: string[] = []
+
+    while (n > 0) {
+      const last = this.parts.pop()
+
+      if (last !== undefined) {
+        if (last.length <= n) {
+          parts.unshift(last)
+          n -= last.length
+        } else {
+          parts.unshift(last.slice(last.length - n))
+          this.parts.push(last.slice(0, last.length - n))
+          n = 0
+        }
+      }
+    }
+
+    this.n -= n0
+
+    const bits = parts.join("")
+
+    if (bits.length != n0) {
+      throw new Error(
+        `Internal error: expected ${n0} bits popped, but popped ${bits.length}`
+      )
+    }
+
+    return bits
+  }
+
+  /**
+   * Write a string of '0's and '1's to the BitWriter.
+   * Returns the BitWriter to enable chaining
+   * @param bitChars
+   * @returns
+   * Self so these calls can be chain
+   */
+  writeBits(bitChars: string): Writer {
+    for (const c of bitChars) {
+      if (c != "0" && c != "1") {
+        throw new Error(`Bit string contains invalid chars: ${bitChars}`)
+      }
+    }
+
+    this.parts.push(bitChars)
+    this.n += bitChars.length
+
+    return this
+  }
+
+  /**
+   * Returns the BitWriter to enable chaining
+   * @param byte
+   * @returns
+   * Self so these calls can be chain
+   */
+  writeByte(byte: number): Writer {
+    if (byte < 0 || byte > 255) {
+      throw new Error(`Invalid byte: ${byte}`)
+    }
+
+    this.writeBits(pad(byte.toString(2), 8))
+
+    return this
+  }
+}
+
+/**
+ * Converts a 8 bit integer number into a bit string with an optional "0b" prefix.
+ * The result is padded with leading zeroes to become 'n' chars long ('2 + n' chars long if you count the "0b" prefix).
+ * @example
+ * byteToBits(7) == "0b00000111"
+ * @param {number} b
+ * @param {number} n
+ * @param {boolean} prefix
+ * @returns {string}
+ */
+export function fromByte(
+  b: number,
+  n: number = 8,
+  prefix: boolean = true
+): Either.Either<string, RangeError> {
+  if (b < 0 || b > 255) {
+    return Either.left(new RangeError(`Invalid byte: ${b}`))
+  }
+
+  const bits = b.toString(2)
+
+  if (n < bits.length) {
+    return Either.left(
+      new RangeError(
+        `n is smaller than the number of bits: ${n} < ${bits.length}`
+      )
+    )
+  }
+
+  const s = pad(bits, n)
+
+  if (prefix) {
+    return Either.right("0b" + s)
+  } else {
+    return Either.right(s)
+  }
+}
+
+/**
+ * @param bytes
+ * @param i
+ * bit index
+ * @returns
+ * 0 or 1
+ */
+export function getBit(bytes: number[], i: number): 0 | 1 {
+  return ((bytes[Math.floor(i / 8)] >> (i % 8)) & 1) as 0 | 1
+}
+
+const BIT_MASKS = [
+  0b11111111, 0b01111111, 0b00111111, 0b00011111, 0b00001111, 0b00000111,
+  0b00000011, 0b00000001
+]
+
+/**
+ * Masks bits of `b` by setting bits outside the range `[i0, i1)` to 0.
+ * `b` is an 8 bit integer (i.e. number between 0 and 255).
+ * The return value is also an 8 bit integer, shifted right by `i1`.
+ * @example
+ * maskBits(0b11111111, 1, 4) == 0b0111 // (i.e. 7)
+ * @param b
+ * @param i0
+ * @param i1
+ * @returns
+ */
+export function mask(b: number, i0: number, i1: number): number {
+  if (i0 >= i1 || i0 < 0 || i0 > 7 || i1 > 8 || b < 0 || b > 255) {
+    throw new RangeError(
+      `Invalid Bits.mask arguments: b=${b}, i0=${i0}, i1=${i1}`
+    )
+  }
+
+  return (b & BIT_MASKS[i0]) >> (8 - i1)
+}
+
+/**
+ * Prepends zeroes to a bit-string so that 'result.length == n'.
+ * If `n < nCurrent`, pad to next multiple of `n`.
+ * @example
+ * padBits("1111", 8) == "00001111"
+ * @param bits
+ * @param n
+ * @returns
+ * @throws
+ * If n is zero or negative
+ */
+export function pad(bits: string, n: number): string {
+  const nBits = bits.length
+
+  if (nBits == n) {
+    return bits
+  } else if (n <= 0) {
+    throw new RangeError(`Expected pad length n to be > 0, got n=${n}`)
+  } else if (nBits % n != 0) {
+    // padded to multiple of n
+    const nPad = n - (nBits % n)
+
+    bits = new Array(nPad).fill("0").join("") + bits
+  }
+
+  return bits
+}