bit-sequence 1.0.0 → 1.2.0

package/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'daily'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+    cooldown:
+      default-days: 5
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'daily'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+    cooldown:
+      default-days: 5
+  - package-ecosystem: 'gomod'
+    directory: '/go'
+    schedule:
+      interval: 'daily'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+    cooldown:
+      default-days: 5

package/.github/workflows/go.yml

@@ -0,0 +1,47 @@
+name: Go CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        working-directory: go
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.25'
+          cache-dependency-path: go/go.mod
+      - name: Run tests
+        run: go test -v ./...
+      - name: Vet
+        run: go vet ./...
+      - name: Check formatting
+        if: runner.os != 'Windows'
+        run: |
+          test -z "$(gofmt -l .)" || (gofmt -d . && exit 1)
+
+  staticcheck:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: go
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.25'
+          cache-dependency-path: go/go.mod
+      - name: Install staticcheck
+        run: go install honnef.co/go/tools/cmd/staticcheck@latest
+      - name: Run staticcheck
+        run: staticcheck ./...

package/.github/workflows/test-and-release.yml

@@ -0,0 +1,56 @@
+name: Test & Maybe Release
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [lts/*, current]
+        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install Dependencies
+        run: npm install --no-progress
+      - name: Check build is up to date
+        run: |
+          npm run build
+          git diff --exit-code || (echo "::error::Build artifacts not committed. Run 'npm run build' and commit the changes." && exit 1)
+      - name: Run tests
+        run: npm test
+
+  release:
+    name: Release
+    needs: [test]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm install --no-progress --no-package-lock --no-save
+      - name: Build
+        run: npm run build
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+        run: npx semantic-release

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [1.2.0](https://github.com/rvagg/bit-sequence/compare/v1.1.0...v1.2.0) (2026-02-16)
+
+### Features
+
+* dep & CI updates & minor modernisation ([d37d229](https://github.com/rvagg/bit-sequence/commit/d37d229fea152b35e0329af0304bf9abb502abd7))
+
+### Trivial Changes
+
+* **deps:** bump actions/setup-go from 5 to 6 ([#3](https://github.com/rvagg/bit-sequence/issues/3)) ([8786d6d](https://github.com/rvagg/bit-sequence/commit/8786d6d92408d6ffe069eae6b5cd8bb00c4d2919))

package/README.md

@@ -1,25 +1,37 @@
 # bit-sequence
 
-**Turn an arbitrary sequence of bits from a byte array and turn it into an integer**
+[![NPM](https://nodei.co/npm/bit-sequence.svg?style=flat&data=n,v&color=blue)](https://nodei.co/npm/bit-sequence/)
 
-[![NPM](https://nodei.co/npm/bit-sequence.svg)](https://nodei.co/npm/bit-sequence/)
+**Turn an arbitrary sequence of bits from a byte array into an integer**
+
+* [JavaScript](#javascript)
+  * [Example](#example)
+  * [API](#api)
+* [Go](#go)
+* [License and Copyright](#license-and-copyright)
+
+## Requirements
+
+Node.js >= 20
+
+## JavaScript
 
 Given an `Array`-like containing bytes (unsigned 8-bit integers), extract an arbitrary sequence of the underlying bits and convert them into an unsigned integer value.
 
 Useful for cases where a sub-sequence of bits within a longer byte sequence is used to form an index, such as in a [hash array mapped trie](https://en.wikipedia.org/wiki/Hash_array_mapped_trie) where an index at each level of the tree structure is formed by incremental chunks of a key's hash.
 
-## Example
+### Example
 
 ```js
-const bitSequence = require('bit-sequence')
-const assert = require('assert')
+import bitSequence from 'bit-sequence'
+import assert from 'node:assert'
 const bytes = new Uint8Array([ 0b00010101, 0b10101000, 0b00000000, 0b00000000 ])
 //               extract bits from here ^         to here ^
 const int = bitSequence(bytes, 7, 11)
 assert.strictEqual(int, 0b11010100000) // or `1696`
 ```
 
-## API
+### API
 
 **`bitSequence(bytes, start, length)`**
 
@@ -33,6 +45,21 @@ As per the example above, the assumption is that we are extracting bytes where t
 
 JavaScript's crazy numbers allows us to extract potentially very large bit sequences, but the usual caveats apply at 32-bits and beyond [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).
 
+## Go
+
+`github.com/rvagg/bit-sequence/go`
+
+### API
+
+Exports `BitSequence(bytes []byte, bitStart uint32, bitLength uint32) (uint32, error)` where:
+
+* `bytes` is a simple byte array of arbitrary length
+* `bitStart` is a _bit_ index to start extraction (not a _byte_ index).
+* `bitLength` is the number of bits to extract from the `bytes` array. This value can only be a maximum of `32`, higher values will be adjusted down.
+
+Returns an unsigned integer version of the bit sequence. The most significant bit is not interpreted for a two's compliment representation.
+Returns an error if `bitLength` exceeds 32 or the requested sequence overflows the bytes boundary.
+
 ## License and Copyright
 
 Copyright 2019 Rod Vagg

package/go/bitsequence.go

@@ -0,0 +1,58 @@
+package bitsequence
+
+import "fmt"
+
+// BitSequence turns an arbitrary sequence of bits from a byte array into an integer.
+//
+// - `bytes` is a simple byte array of arbitrary length
+//
+// - `bitStart` is a _bit_ index to start extraction (not a _byte_ index).
+//
+// - `bitLength` is the number of bits to extract from the `bytes` array. This value can only be a maximum of `32`, higher values will be adjusted down.
+//
+// Returns an unsigned integer version of the bit sequence. The most significant bit is not interpreted for a two's compliment representation.
+// Returns an error if `bitLength` exceeds 32 or the requested sequence overflows the bytes boundary.
+func BitSequence(bytes []byte, bitStart uint32, bitLength uint32) (uint32, error) {
+	if bitLength > 32 {
+		return 0, fmt.Errorf("maximum bits that can be read is 32")
+	}
+	startOffset := bitStart % 8
+	byteCount := (7 + startOffset + bitLength) / 8
+	byteStart := bitStart / 8
+	endOffset := byteCount*8 - bitLength - startOffset
+
+	if int(byteStart+byteCount) > len(bytes) {
+		return 0, fmt.Errorf("cannot read past end of bytes array")
+	}
+
+	var result uint32
+
+	var i uint32
+	for i = 0; i < byteCount; i++ {
+		local := bytes[byteStart+i]
+		var shift uint32
+		var localBitLength uint32 = 8 // how many bits of this byte we are extracting
+
+		if i == 0 {
+			localBitLength -= startOffset
+		}
+
+		if i == byteCount-1 {
+			localBitLength -= endOffset
+			shift = endOffset
+			local = local >> shift // take off the trailing bits
+		}
+
+		if localBitLength < 8 {
+			mask := uint8((1 << localBitLength) - 1)
+			local = local & mask // mask off the leading bits
+		}
+
+		if shift < 8 {
+			result = result << (8 - shift)
+		}
+		result = result | uint32(local)
+	}
+
+	return result, nil
+}

package/go/bitsequence_test.go

@@ -0,0 +1,111 @@
+package bitsequence
+
+import (
+	"bufio"
+	"encoding/hex"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const FixturesFile = "../test-fixture.csv"
+
+type TestCase struct {
+	bytes                   []byte
+	start, length, expected uint32
+}
+
+func TestFixtures(t *testing.T) {
+	testCases, err := readTestCases(FixturesFile)
+	if err != nil {
+		panic(err)
+	}
+
+	for _, testCase := range testCases {
+		actual, err := BitSequence(testCase.bytes, testCase.start, testCase.length)
+		if err != nil {
+			t.Errorf("Bytes [%s] start=%d length=%d returned an error reading",
+				hex.EncodeToString(testCase.bytes),
+				testCase.start,
+				testCase.length,
+			)
+		}
+		if actual != testCase.expected {
+			t.Errorf("Bytes [%s] start=%d length=%d expected %d but got %d",
+				hex.EncodeToString(testCase.bytes),
+				testCase.start,
+				testCase.length,
+				testCase.expected,
+				actual)
+		} /* else {
+			fmt.Printf("Bytes [%s] start=%d length=%d expected %d and got %d\n",
+				hex.EncodeToString(testCase.bytes),
+				testCase.start,
+				testCase.length,
+				testCase.expected,
+				actual)
+		} */
+	}
+}
+
+func TestReadPastEndErrors(t *testing.T) {
+	bytes, err := hex.DecodeString("ff")
+	if err != nil {
+		panic(err)
+	}
+	_, err = BitSequence(bytes, 16, 1)
+	if err == nil {
+		t.Errorf("Should not have allowed reading past end of byte array but did")
+	}
+	_, err = BitSequence(bytes, 14, 6)
+	if err == nil {
+		t.Errorf("Should not have allowed reading past end of byte array but did")
+	}
+}
+
+func readTestCases(path string) ([]TestCase, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	scanner.Split(bufio.ScanLines)
+
+	var testCases []TestCase
+	for scanner.Scan() {
+		line := scanner.Text()
+		s := strings.Split(line, ",")
+
+		testCase := TestCase{}
+		var err error
+		var ii int
+
+		testCase.bytes, err = hex.DecodeString(s[0])
+		if err != nil {
+			return nil, err
+		}
+		ii, err = strconv.Atoi(s[1])
+		if err != nil {
+			return nil, err
+		}
+		testCase.start = uint32(ii)
+		ii, err = strconv.Atoi(s[2])
+		if err != nil {
+			return nil, err
+		}
+		testCase.length = uint32(ii)
+		ii, err = strconv.Atoi(s[3])
+		if err != nil {
+			return nil, err
+		}
+		testCase.expected = uint32(ii)
+
+		testCases = append(testCases, testCase)
+	}
+
+	return testCases, nil
+}

package/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/rvagg/bit-sequence/go
+
+go 1.25

package/js/bit-sequence.js

@@ -1,4 +1,10 @@
-function bitSequence (bytes, bitStart, bitLength) {
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} bitStart
+ * @param {number} bitLength
+ * @returns {number}
+ */
+export default function bitSequence (bytes, bitStart, bitLength) {
   // making an assumption that bytes is an Array-like that will give us one
   // byte per element, so either an Array full of 8-bit integers or a
   // Uint8Array or a Node.js Buffer, or something like that
@@ -48,5 +54,3 @@ function bitSequence (bytes, bitStart, bitLength) {
 
   return result
 }
-
-module.exports = bitSequence

package/js/test.js

@@ -1,5 +1,6 @@
-const assert = require('assert')
-const bitSequence = require('./bit-sequence.js')
+import { test } from 'node:test'
+import assert from 'node:assert'
+import bitSequence from './bit-sequence.js'
 
 function binaryStringToBytes (s) {
   const byteLength = Math.ceil(s.length / 8)
@@ -11,82 +12,92 @@ function binaryStringToBytes (s) {
   return bytes
 }
 
-// sanity check binaryStringToBytes
-;[
-  '00000001:01',
-  '10000000:80',
-  '11111111:ff',
-  '11000000:c0',
-  '11110000:f0',
-  '1111111111111111:ffff',
-  '0000000000000001:0001',
-  '000000000000000000000001:000001',
-  '111111111111111111111111:ffffff',
-  '100000001000000010000000:808080',
-  '10000000100000001000000010000000:80808080',
-  '10000000111111111000000011111111:80ff80ff',
-  '001:01',
-  '111:07',
-  '1111:0f',
-  '01111:0f',
-  '001111:0f',
-  '0000001111:000f',
-  '10000000000001111:01000f'
-].forEach((s) => {
-  const [ binary, hex ] = s.split(':')
-  const bytesHex = Array.prototype.map.call(
-    binaryStringToBytes(binary),
-    (b) => b.toString(16).padStart(2, '0')
-  ).join('')
-  // console.log(binary, '=>', binaryStringToBytes(binary).toString('hex'), '<>', hex, '?', parseInt(binary, 2).toString(16))
-  assert.strictEqual(bytesHex, hex)
-  // sanity check the sanity check by reading the binary
-  assert.strictEqual(bytesHex.replace(/^0+/, ''), parseInt(binary, 2).toString(16))
+test('binaryStringToBytes sanity check', () => {
+  ;[
+    '00000001:01',
+    '10000000:80',
+    '11111111:ff',
+    '11000000:c0',
+    '11110000:f0',
+    '1111111111111111:ffff',
+    '0000000000000001:0001',
+    '000000000000000000000001:000001',
+    '111111111111111111111111:ffffff',
+    '100000001000000010000000:808080',
+    '10000000100000001000000010000000:80808080',
+    '10000000111111111000000011111111:80ff80ff',
+    '001:01',
+    '111:07',
+    '1111:0f',
+    '01111:0f',
+    '001111:0f',
+    '0000001111:000f',
+    '10000000000001111:01000f'
+  ].forEach((s) => {
+    const [binary, hex] = s.split(':')
+    const bytesHex = Array.prototype.map.call(
+      binaryStringToBytes(binary),
+      (b) => b.toString(16).padStart(2, '0')
+    ).join('')
+    assert.strictEqual(bytesHex, hex)
+    assert.strictEqual(bytesHex.replace(/^0+/, ''), parseInt(binary, 2).toString(16))
+  })
 })
 
-let asserts = 0
-;[
-  '00000001',
-  '11111111',
-  '01010101',
-  '10001000',
-  '0000000000000001',
-  '0000000100000001',
-  '1111111111111111',
-  '1010101010101010',
-  '0101010101010101',
-  '1001001001001001',
-  '0100100100100100',
-  '1000100010001000',
-  '0100010001000100',
-  '1111111100000000',
-  '0000000011111111',
-  '0000111111110000',
-  '000000000000000000000001',
-  '111111111111111111111111',
-  '001001100100110010011111',
-  '00000000000000000000000000000001',
-  '11111111111111111111111111111111',
-  '10000000000000000000000000000001',
-  '10001100010110011110001010111010',
-  '1111111111111111111111111111111111111111111111111111111111111111',
-  '0000000000000000000000000000000000000000000000000000000000000001',
-  '1000000000000000000000000000000000000000000000000000000000000001',
-  '1010110100111110101110101001010001000000001101011101110010011111',
-  '11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111'
-].forEach((s) => {
-  const bytes = binaryStringToBytes(s)
+test('bitSequence extracts correct bit sequences', () => {
+  const testCases = [
+    '00000001',
+    '11111111',
+    '01010101',
+    '10001000',
+    '0000000000000001',
+    '0000000100000001',
+    '1111111111111111',
+    '1010101010101010',
+    '0101010101010101',
+    '1001001001001001',
+    '0100100100100100',
+    '1000100010001000',
+    '0100010001000100',
+    '1111111100000000',
+    '0000000011111111',
+    '0000111111110000',
+    '000000000000000000000001',
+    '111111111111111111111111',
+    '001001100100110010011111',
+    '00000000000000000000000000000001',
+    '11111111111111111111111111111111',
+    '10000000000000000000000000000001',
+    '10001100010110011110001010111010',
+    '1111111111111111111111111111111111111111111111111111111111111111',
+    '0000000000000000000000000000000000000000000000000000000000000001',
+    '1000000000000000000000000000000000000000000000000000000000000001',
+    '1010110100111110101110101001010001000000001101011101110010011111',
+    '11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111',
+    '1111101000010110000011111100000101110000010110111001100000000000',
+    '10010101000110001000101011111111101000010110000011111100000101110000010110111001111000011001000000001000111101010010101001110000'
+  ]
 
-  for (let start = 0; start < bytes.length * 8; start++) {
-    for (let length = 1; length <= bytes.length * 8 - start; length++) {
-      const expected = parseInt(s.substring(start, start + length), 2)
-      const actual = bitSequence(bytes, start, length)
-      // console.log(`[${s}] start=${start} length=${length} ${actual} <> ${expected}`)
-      asserts++
-      assert.strictEqual(actual, expected, `[${s}] start=${start} length=${length} ${actual} <> ${expected}`)
-      assert.ok(actual >= 0, 'sanity check that we\'re only dealing with unsigned integers')
+  let asserts = 0
+  let tooBig = 0
+  testCases.forEach((s) => {
+    const bytes = binaryStringToBytes(s)
+
+    for (let start = 0; start < bytes.length * 8; start++) {
+      for (let length = 1; length <= bytes.length * 8 - start; length++) {
+        const expected = parseInt(s.substring(start, start + length), 2)
+        const actual = bitSequence(bytes, start, length)
+        if (actual !== expected && actual > Number.MAX_SAFE_INTEGER) {
+          tooBig++
+          continue
+        }
+        asserts++
+        assert.strictEqual(actual, expected, `[${s}] start=${start} length=${length} ${actual} <> ${expected}`)
+        assert.ok(actual >= 0, 'sanity check that we\'re only dealing with unsigned integers')
+      }
     }
-  }
-})
+  })
 
-assert.ok(asserts > 10000, 'did a lot of asserts')
+  assert.ok(asserts > 10000, 'did a lot of asserts')
+  assert.ok(tooBig < 200, 'not too many non-matches beyond MAX_SAFE_INTEGER')
+})