@helios-lang/effect 0.1.5 → 0.1.7

package/src/internal/Bits.test.ts

@@ -1,300 +0,0 @@
-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

@@ -1,398 +0,0 @@
-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
-}