@wtasnorg/node-lib 0.0.11 → 0.0.12

package/readme.txt

@@ -15,6 +15,7 @@ A library project for nodejs. #nodejs #typescript #library
 6. `encode58` / `decode58` for Base58 encoding/decoding with charset variants (`bitcoin`, `flickr`, `ripple`).
 7. `encode85` / `decode85` for Base85 encoding/decoding with charset variants (`ascii85`, `z85`, `rfc1924`).
 8. `encode32` / `decode32` for Base32 encoding/decoding with charset variants (`rfc4648`, `hex`, `crockford`).
+9. `popcount32`, `popcount64`, `countOnes`, `countZeroesWithWidth`, `countZeroes` for integer bit counting helpers.
 
 ## Develop
 
@@ -33,23 +34,36 @@ We are using `node --test` for testing.
 npm install @wtasnorg/node-lib
 ```
 
-```typescript
-# check if you can run code
-import {hello} from "@wtasnorg/node-lib";
+**Recommended:** Use subpath imports for maximum efficiency (enables tree shaking):
 
-await hello();
-// "hello from @wtasnorg/node-lib"
+```typescript
+import { encode, decode } from "@wtasnorg/node-lib/base64";
+import { encode58 } from "@wtasnorg/node-lib/base58";
+import { encode32 } from "@wtasnorg/node-lib/base32";
+import { parseUserAgent } from "@wtasnorg/node-lib/user-agent";
+import { popcount32, countZeroes } from "@wtasnorg/node-lib/bits";
 ```
 
-## Tree Shaking
-
-Import only what you need for smaller bundles:
+Alternatively, import from the main entry point (includes all modules):
 
 ```typescript
-import { encode58 } from "@wtasnorg/node-lib/base58";
-import { encode32 } from "@wtasnorg/node-lib/base32";
+import { hello, encode, encode58 } from "@wtasnorg/node-lib";
 ```
 
+## Available Subpath Imports
+
+| Module | Import Path |
+|--------|-------------|
+| Base64 | `@wtasnorg/node-lib/base64` |
+| Base58 | `@wtasnorg/node-lib/base58` |
+| Base85 | `@wtasnorg/node-lib/base85` |
+| Base32 | `@wtasnorg/node-lib/base32` |
+| User-Agent | `@wtasnorg/node-lib/user-agent` |
+| Find | `@wtasnorg/node-lib/find` |
+| POJO | `@wtasnorg/node-lib/pojo` |
+| Hello | `@wtasnorg/node-lib/hello` |
+| Bits | `@wtasnorg/node-lib/bits` |
+
 ## License: MIT
 
 [MIT License file](LICENSE)

package/src/bits.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Count set bits in an unsigned 32-bit representation of a number.
+ *
+ * @param {number} value - Number interpreted as uint32.
+ * @returns {number} Number of set bits (0-32).
+ */
+declare function popcount32(value: number): number;
+/**
+ * Count set bits in the low 64 bits of a number or bigint.
+ *
+ * @param {number | bigint} value - Input value. For `number`, it must be a non-negative safe integer.
+ * @returns {number} Number of set bits (0-64).
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function popcount64(value: number | bigint): number;
+/**
+ * Count set bits in a non-negative integer.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function countOnes(value: number | bigint): number;
+/**
+ * Count zero bits within a fixed width, considering only low-order `width` bits.
+ *
+ * @param {number | bigint} value - Input value.
+ * @param {number} width - Bit width to inspect.
+ * @returns {number} Number of zero bits in the selected width.
+ * @throws {RangeError} If `value` is negative/unsafe or `width` is negative/unsafe.
+ */
+declare function countZeroesWithWidth(value: number | bigint, width: number): number;
+/**
+ * Count zero bits from LSB up to and including the highest set bit.
+ * For zero input, returns 0.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Zero count up to the left-most set bit.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function countZeroes(value: number | bigint): number;
+export { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
+//# sourceMappingURL=bits.d.ts.map

package/src/bits.js

@@ -0,0 +1,117 @@
+const UINT64_MASK = (1n << 64n) - 1n;
+/**
+ *
+ * @param {number | bigint} value
+ * @param {string} fnName
+ * @returns {bigint}
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ * @example
+ * toNonNegativeBigInt(42, "exampleFunction"); // returns 42n
+ * toNonNegativeBigInt(-1, "exampleFunction"); // throws RangeError
+ */
+function toNonNegativeBigInt(value, fnName) {
+    if (typeof value === "bigint") {
+        if (value < 0n) {
+            throw new RangeError(`${fnName}: value must be non-negative`);
+        }
+        return value;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${fnName}: value must be a non-negative safe integer`);
+    }
+    return BigInt(value);
+}
+/**
+ * Count set bits in a bigint.
+ *
+ * @param {bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @example
+ * popcountBigInt(0b1011n); // returns 3
+ */
+function popcountBigInt(value) {
+    let count = 0;
+    let bits = value;
+    while (bits !== 0n) {
+        bits &= bits - 1n;
+        count += 1;
+    }
+    return count;
+}
+/**
+ * Count set bits in an unsigned 32-bit representation of a number.
+ *
+ * @param {number} value - Number interpreted as uint32.
+ * @returns {number} Number of set bits (0-32).
+ */
+function popcount32(value) {
+    let bits = value >>> 0;
+    bits -= (bits >>> 1) & 0x55555555;
+    bits = (bits & 0x33333333) + ((bits >>> 2) & 0x33333333);
+    bits = (bits + (bits >>> 4)) & 0x0f0f0f0f;
+    bits += bits >>> 8;
+    bits += bits >>> 16;
+    return bits & 0x3f;
+}
+/**
+ * Count set bits in the low 64 bits of a number or bigint.
+ *
+ * @param {number | bigint} value - Input value. For `number`, it must be a non-negative safe integer.
+ * @returns {number} Number of set bits (0-64).
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function popcount64(value) {
+    const bits64 = toNonNegativeBigInt(value, "popcount64") & UINT64_MASK;
+    return popcountBigInt(bits64);
+}
+/**
+ * Count set bits in a non-negative integer.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countOnes(value) {
+    const bits = toNonNegativeBigInt(value, "countOnes");
+    return popcountBigInt(bits);
+}
+/**
+ * Count zero bits within a fixed width, considering only low-order `width` bits.
+ *
+ * @param {number | bigint} value - Input value.
+ * @param {number} width - Bit width to inspect.
+ * @returns {number} Number of zero bits in the selected width.
+ * @throws {RangeError} If `value` is negative/unsafe or `width` is negative/unsafe.
+ */
+function countZeroesWithWidth(value, width) {
+    if (!Number.isSafeInteger(width) || width < 0) {
+        throw new RangeError("countZeroesWithWidth: width must be a non-negative safe integer");
+    }
+    if (width === 0) {
+        return 0;
+    }
+    const bits = toNonNegativeBigInt(value, "countZeroesWithWidth");
+    const widthBigInt = BigInt(width);
+    const mask = (1n << widthBigInt) - 1n;
+    const ones = popcountBigInt(bits & mask);
+    return width - ones;
+}
+/**
+ * Count zero bits from LSB up to and including the highest set bit.
+ * For zero input, returns 0.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Zero count up to the left-most set bit.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countZeroes(value) {
+    const bits = toNonNegativeBigInt(value, "countZeroes");
+    if (bits === 0n) {
+        return 0;
+    }
+    const width = bits.toString(2).length;
+    const ones = popcountBigInt(bits);
+    return width - ones;
+}
+export { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
+//# sourceMappingURL=bits.js.map

package/src/bits.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bits.test.d.ts.map

package/src/bits.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes } from "./bits.js";
+describe("popcount32", () => {
+    it("counts set bits for simple values", () => {
+        strictEqual(popcount32(0), 0);
+        strictEqual(popcount32(1), 1);
+        strictEqual(popcount32(0b10110100), 4);
+    });
+    it("uses uint32 semantics", () => {
+        strictEqual(popcount32(-1), 32);
+        strictEqual(popcount32(0xffffffff), 32);
+    });
+});
+describe("popcount64", () => {
+    it("counts set bits for bigint values", () => {
+        strictEqual(popcount64(0n), 0);
+        strictEqual(popcount64((1n << 64n) - 1n), 64);
+        strictEqual(popcount64(41n), 3);
+    });
+    it("counts only low 64 bits", () => {
+        const value = (1n << 65n) | 1n;
+        strictEqual(popcount64(value), 1);
+    });
+    it("throws for invalid number input", () => {
+        throws(() => popcount64(-1), /must be a non-negative safe integer/);
+        throws(() => popcount64(Number.MAX_SAFE_INTEGER + 1), /must be a non-negative safe integer/);
+    });
+});
+describe("countOnes", () => {
+    it("counts set bits for number and bigint", () => {
+        strictEqual(countOnes(0), 0);
+        strictEqual(countOnes(255), 8);
+        strictEqual(countOnes(65537n), 2);
+    });
+});
+describe("countZeroesWithWidth", () => {
+    it("counts zero bits for a chosen width", () => {
+        strictEqual(countZeroesWithWidth(0b10100, 5), 3);
+        strictEqual(countZeroesWithWidth(0b10100, 8), 6);
+        strictEqual(countZeroesWithWidth(0, 8), 8);
+        strictEqual(countZeroesWithWidth(123, 0), 0);
+    });
+    it("throws for invalid width", () => {
+        throws(() => countZeroesWithWidth(1, -1), /width must be a non-negative safe integer/);
+        throws(() => countZeroesWithWidth(1, Number.MAX_SAFE_INTEGER + 1), /width must be a non-negative safe integer/);
+    });
+});
+describe("countZeroes", () => {
+    it("counts zero bits only up to highest set bit", () => {
+        strictEqual(countZeroes(0), 0);
+        strictEqual(countZeroes(1), 0);
+        strictEqual(countZeroes(0b10100), 3);
+        strictEqual(countZeroes(0b1000), 3);
+        strictEqual(countZeroes(0b1111), 0);
+    });
+    it("throws for invalid inputs", () => {
+        throws(() => countZeroes(-1), /must be a non-negative safe integer/);
+        throws(() => countOnes(-1n), /must be non-negative/);
+    });
+});
+//# sourceMappingURL=bits.test.js.map

package/src/bits.test.ts

@@ -0,0 +1,77 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import {
+    popcount32,
+    popcount64,
+    countOnes,
+    countZeroesWithWidth,
+    countZeroes
+} from "./bits.js";
+
+describe("popcount32", () => {
+    it("counts set bits for simple values", () => {
+        strictEqual(popcount32(0), 0);
+        strictEqual(popcount32(1), 1);
+        strictEqual(popcount32(0b10110100), 4);
+    });
+
+    it("uses uint32 semantics", () => {
+        strictEqual(popcount32(-1), 32);
+        strictEqual(popcount32(0xffffffff), 32);
+    });
+});
+
+describe("popcount64", () => {
+    it("counts set bits for bigint values", () => {
+        strictEqual(popcount64(0n), 0);
+        strictEqual(popcount64((1n << 64n) - 1n), 64);
+        strictEqual(popcount64(0b101001n), 3);
+    });
+
+    it("counts only low 64 bits", () => {
+        const value = (1n << 65n) | 1n;
+        strictEqual(popcount64(value), 1);
+    });
+
+    it("throws for invalid number input", () => {
+        throws(() => popcount64(-1), /must be a non-negative safe integer/);
+        throws(() => popcount64(Number.MAX_SAFE_INTEGER + 1), /must be a non-negative safe integer/);
+    });
+});
+
+describe("countOnes", () => {
+    it("counts set bits for number and bigint", () => {
+        strictEqual(countOnes(0), 0);
+        strictEqual(countOnes(255), 8);
+        strictEqual(countOnes(0b10000000000000001n), 2);
+    });
+});
+
+describe("countZeroesWithWidth", () => {
+    it("counts zero bits for a chosen width", () => {
+        strictEqual(countZeroesWithWidth(0b10100, 5), 3);
+        strictEqual(countZeroesWithWidth(0b10100, 8), 6);
+        strictEqual(countZeroesWithWidth(0, 8), 8);
+        strictEqual(countZeroesWithWidth(123, 0), 0);
+    });
+
+    it("throws for invalid width", () => {
+        throws(() => countZeroesWithWidth(1, -1), /width must be a non-negative safe integer/);
+        throws(() => countZeroesWithWidth(1, Number.MAX_SAFE_INTEGER + 1), /width must be a non-negative safe integer/);
+    });
+});
+
+describe("countZeroes", () => {
+    it("counts zero bits only up to highest set bit", () => {
+        strictEqual(countZeroes(0), 0);
+        strictEqual(countZeroes(1), 0);
+        strictEqual(countZeroes(0b10100), 3);
+        strictEqual(countZeroes(0b1000), 3);
+        strictEqual(countZeroes(0b1111), 0);
+    });
+
+    it("throws for invalid inputs", () => {
+        throws(() => countZeroes(-1), /must be a non-negative safe integer/);
+        throws(() => countOnes(-1n), /must be non-negative/);
+    });
+});

package/src/bits.ts

@@ -0,0 +1,135 @@
+const UINT64_MASK = (1n << 64n) - 1n;
+
+/**
+ *
+ * @param {number | bigint} value
+ * @param {string} fnName
+ * @returns {bigint}
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ * @example
+ * toNonNegativeBigInt(42, "exampleFunction"); // returns 42n
+ * toNonNegativeBigInt(-1, "exampleFunction"); // throws RangeError
+ */
+function toNonNegativeBigInt(value: number | bigint, fnName: string): bigint {
+    if (typeof value === "bigint") {
+        if (value < 0n) {
+            throw new RangeError(`${fnName}: value must be non-negative`);
+        }
+        return value;
+    }
+
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${fnName}: value must be a non-negative safe integer`);
+    }
+
+    return BigInt(value);
+}
+
+/**
+ * Count set bits in a bigint.
+ *
+ * @param {bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @example
+ * popcountBigInt(0b1011n); // returns 3
+ */
+function popcountBigInt(value: bigint): number {
+    let count = 0;
+    let bits = value;
+    while (bits !== 0n) {
+        bits &= bits - 1n;
+        count += 1;
+    }
+    return count;
+}
+
+/**
+ * Count set bits in an unsigned 32-bit representation of a number.
+ *
+ * @param {number} value - Number interpreted as uint32.
+ * @returns {number} Number of set bits (0-32).
+ */
+function popcount32(value: number): number {
+    let bits = value >>> 0;
+    bits -= (bits >>> 1) & 0x55555555;
+    bits = (bits & 0x33333333) + ((bits >>> 2) & 0x33333333);
+    bits = (bits + (bits >>> 4)) & 0x0f0f0f0f;
+    bits += bits >>> 8;
+    bits += bits >>> 16;
+    return bits & 0x3f;
+}
+
+/**
+ * Count set bits in the low 64 bits of a number or bigint.
+ *
+ * @param {number | bigint} value - Input value. For `number`, it must be a non-negative safe integer.
+ * @returns {number} Number of set bits (0-64).
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function popcount64(value: number | bigint): number {
+    const bits64 = toNonNegativeBigInt(value, "popcount64") & UINT64_MASK;
+    return popcountBigInt(bits64);
+}
+
+/**
+ * Count set bits in a non-negative integer.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countOnes(value: number | bigint): number {
+    const bits = toNonNegativeBigInt(value, "countOnes");
+    return popcountBigInt(bits);
+}
+
+/**
+ * Count zero bits within a fixed width, considering only low-order `width` bits.
+ *
+ * @param {number | bigint} value - Input value.
+ * @param {number} width - Bit width to inspect.
+ * @returns {number} Number of zero bits in the selected width.
+ * @throws {RangeError} If `value` is negative/unsafe or `width` is negative/unsafe.
+ */
+function countZeroesWithWidth(value: number | bigint, width: number): number {
+    if (!Number.isSafeInteger(width) || width < 0) {
+        throw new RangeError("countZeroesWithWidth: width must be a non-negative safe integer");
+    }
+
+    if (width === 0) {
+        return 0;
+    }
+
+    const bits = toNonNegativeBigInt(value, "countZeroesWithWidth");
+    const widthBigInt = BigInt(width);
+    const mask = (1n << widthBigInt) - 1n;
+    const ones = popcountBigInt(bits & mask);
+    return width - ones;
+}
+
+/**
+ * Count zero bits from LSB up to and including the highest set bit.
+ * For zero input, returns 0.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Zero count up to the left-most set bit.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countZeroes(value: number | bigint): number {
+    const bits = toNonNegativeBigInt(value, "countZeroes");
+    if (bits === 0n) {
+        return 0;
+    }
+
+    const width = bits.toString(2).length;
+    const ones = popcountBigInt(bits);
+    return width - ones;
+}
+
+export {
+    popcount32,
+    popcount64,
+    countOnes,
+    countZeroesWithWidth,
+    countZeroes
+};

package/src/index.d.ts

@@ -12,6 +12,7 @@ import type { Base85CharsetType } from "./base85.js";
 import { encode85, decode85, Base85Charset } from "./base85.js";
 import type { Base32CharsetType } from "./base32.js";
 import { encode32, decode32, Base32Charset } from "./base32.js";
-export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset, encode58, decode58, Base58Charset, encode85, decode85, Base85Charset, encode32, decode32, Base32Charset };
+import { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes } from "./bits.js";
+export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset, encode58, decode58, Base58Charset, encode85, decode85, Base85Charset, encode32, decode32, Base32Charset, popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
 export type { FindDirectoriesOptions, FileSystemDependencies, UserAgentInfo, Base64CharsetType, Base58CharsetType, Base85CharsetType, Base32CharsetType };
 //# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -6,5 +6,6 @@ import { encode, decode, Base64Charset } from "./base64.js";
 import { encode58, decode58, Base58Charset } from "./base58.js";
 import { encode85, decode85, Base85Charset } from "./base85.js";
 import { encode32, decode32, Base32Charset } from "./base32.js";
-export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset, encode58, decode58, Base58Charset, encode85, decode85, Base85Charset, encode32, decode32, Base32Charset };
+import { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes } from "./bits.js";
+export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset, encode58, decode58, Base58Charset, encode85, decode85, Base85Charset, encode32, decode32, Base32Charset, popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
 //# sourceMappingURL=index.js.map

package/src/index.ts

@@ -12,6 +12,7 @@ import type { Base85CharsetType } from "./base85.js";
 import { encode85, decode85, Base85Charset } from "./base85.js";
 import type { Base32CharsetType } from "./base32.js";
 import { encode32, decode32, Base32Charset } from "./base32.js";
+import { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes } from "./bits.js";
 
 export {
     hello,
@@ -29,7 +30,12 @@ export {
     Base85Charset,
     encode32,
     decode32,
-    Base32Charset
+    Base32Charset,
+    popcount32,
+    popcount64,
+    countOnes,
+    countZeroesWithWidth,
+    countZeroes
 };
 
 export type {

package/.github/workflows/npm-publish.yml

@@ -1,36 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm clean-install
-      - run: npm run build
-      - run: npm run test
-      - run: npm run docs
-      - run: npm run docs:json
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm clean-install
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/npm-test-on-pr.yml

@@ -1,30 +0,0 @@
-name: Run tests on pull request
-
-on:
-  pull_request:
-    types: [opened, reopened, synchronize]
-
-permissions:
-  contents: read
-
-jobs:
-  run-tests:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test