@moon7/bits
Version:
Type-safe bitwise operations for JavaScript and TypeScript with named bit collections
282 lines (210 loc) • 10.5 kB
Markdown
[](https://www.npmjs.com/package/@moon7/bits)
[](https://opensource.org/licenses/MIT)
A lightweight, type-safe utility library for bitwise operations in JavaScript and TypeScript applications.
- 🧩 **Modular API** - Simple, focused functions for specific bitwise operations
- 📝 **Named bit collections** - Create organized, readable constants for bit flags and enums
- 🔄 **Bit masking utilities** - Easily work with multiple bits at once using masks
- 🔍 **Debug helpers** - Convert bits to readable binary strings for debugging
```bash
npm install @moon7/bits
yarn add @moon7/bits
pnpm add @moon7/bits
```
```typescript
import {
getBit, setBit, setBitOn, setBitOff, toggleBit,
bitMask, ALL, NONE
} from '@moon7/bits';
// Check if a specific bit is set
const hasBit = getBit(0b1010, 1);
// true (bit at position 1 is set)
// Set a bit to a specific value
const withBit = setBit(0b1010, 0, true);
// 0b1011 (set bit 0 to 1)
const withoutBit = setBit(0b1010, 1, false);
// 0b1000 (set bit 1 to 0)
// Turn a specific bit on
const bitsOn = setBitOn(0b1010, 2);
// 0b1110 (turn on bit 2)
// Turn a specific bit off
const bitsOff = setBitOff(0b1010, 1);
// 0b1000 (turn off bit 1)
// Toggle a specific bit
const toggled = toggleBit(0b1010, 1);
// 0b1000 (toggle bit 1 from 1 to 0)
const toggled2 = toggleBit(0b1010, 0);
// 0b1011 (toggle bit 0 from 0 to 1)
// Get a bitmask for a specific position
const mask = bitMask(3);
// 0b1000 (a mask with bit 3 set)
// ALL contains a bitfield with all bits set to 1
// NONE contains a bitfield with all bits set to 0
```
```typescript
import {
checkMask, applyMask, clearMask, toggleMask
} from '@moon7/bits';
// Check if any of the specified bits are set
const hasAnyBit = checkMask(0b1010, 0b1100);
// true (at least one bit overlaps)
// Set multiple bits at once
const withBits = applyMask(0b1010, 0b0101);
// 0b1111 (apply mask to set bits)
// Clear multiple bits at once
const clearedBits = clearMask(0b1111, 0b1010);
// 0b0101 (clear bits specified by mask)
// Toggle multiple bits at once
const toggledBits = toggleMask(0b1010, 0b1111);
// 0b0101 (toggle all bits in the mask)
```
```typescript
import { defineBitFlags, defineBitEnum } from '@moon7/bits';
// Define named bit flags with explicit positions
const Permissions = defineBitFlags({
READ: 0, // bit 0
WRITE: 1, // bit 1
DELETE: 2, // bit 2
ADMIN: 5 // bit 5 (can skip positions)
});
// Positions are preserved exactly as defined
console.log(Permissions.READ);
// 0
console.log(Permissions.ADMIN);
// 5
// Get bitmasks using the mask function
console.log(Permissions.mask("READ"));
// 1 (0b0001)
console.log(Permissions.mask("ADMIN"));
// 32 (0b100000)
// Define sequentially numbered bit positions
const Features = defineBitEnum(
"DARK_MODE", // bit 0
"NOTIFICATIONS", // bit 1
"AUTO_SAVE", // bit 2
"SYNC" // bit 3
);
// Positions are assigned sequentially
console.log(Features.DARK_MODE);
// 0
console.log(Features.NOTIFICATIONS);
// 1
// Get bitmasks the same way
console.log(Features.mask("AUTO_SAVE"));
// 4 (0b100)
```
```typescript
import { defineBitFlags } from '@moon7/bits';
// Define user permissions
const Permissions = defineBitFlags({
READ: 0,
WRITE: 1,
DELETE: 2,
ADMIN: 3
});
// Create a user with READ and WRITE permissions
let userPermissions = 0;
// Set READ bit
userPermissions |= Permissions.mask("READ");
// Set WRITE bit
userPermissions |= Permissions.mask("WRITE");
// Check if user has specific permissions
function hasPermission(permissions, permission) {
return (permissions & Permissions.mask(permission)) !== 0;
}
console.log(hasPermission(userPermissions, "READ"));
// true
console.log(hasPermission(userPermissions, "ADMIN"));
// false
// Add ADMIN permission
userPermissions |= Permissions.mask("ADMIN");
console.log(hasPermission(userPermissions, "ADMIN"));
// true
// Remove WRITE permission
userPermissions &= ~Permissions.mask("WRITE");
console.log(hasPermission(userPermissions, "WRITE"));
// false
```
```typescript
import { toBinaryString, toFormattedBinaryString } from '@moon7/bits';
// Convert a number to binary string
console.log(toBinaryString(42));
// "00000000000000000000000000101010"
// Convert with custom length
console.log(toBinaryString(42, 8));
// "00101010"
// Get a nicely formatted binary string with grouping
console.log(toFormattedBinaryString(42));
// "0000 0000 - 0000 0000 - 0000 0000 - 0010 1010"
console.log(toFormattedBinaryString(42, 16));
// "0000 0000 - 0010 1010"
```
```typescript
import { countBits, isSingleBit } from '@moon7/bits';
// Count the number of set bits
console.log(countBits(0b10101));
// 3 (bits 0, 2, and 4 are set)
console.log(countBits(0));
// 0 (no bits set)
console.log(countBits(0xFF));
// 8 (all 8 bits are set)
// Check if exactly one bit is set
console.log(isSingleBit(0b1000));
// true (only bit 3 is set)
console.log(isSingleBit(0b1010));
// false (multiple bits are set)
console.log(isSingleBit(0));
// false (no bits are set)
```
| API | Description |
| --------------------------------------- | ----------------------------------------------------------- |
| **🧮 Constants** | |
| `ALL` | Constant with all bits set to 1 |
| `NONE` | Constant with all bits set to 0 |
| **🧩 Core Functions** | |
| `bitMask(index)` | Gets a mask with a single bit set at the specified position |
| **🎭 Multiple Bit Operations** | |
| `checkMask(bits, mask)` | Checks if any bits specified by the mask are set |
| `applyMask(bits, mask)` | Sets (turns on) bits specified by the mask |
| `clearMask(bits, mask)` | Clears (turns off) bits specified by the mask |
| `toggleMask(bits, mask)` | Toggles bits specified by the mask |
| **👆 Single Bit Operations** | |
| `getBit(bits, index)` | Gets the boolean value of a bit at a specific position |
| `setBit(bits, index, value)` | Sets a bit at a specific position to a boolean value |
| `setBitOn(bits, index)` | Sets (turns on) a bit at a specific position |
| `setBitOff(bits, index)` | Clears (turns off) a bit at a specific position |
| `toggleBit(bits, index)` | Toggles a bit at a specific position |
| **📝 Named Bit Collections** | |
| `defineBitFlags(definition)` | Creates a named collection with explicit bit positions |
| `defineBitEnum(...names)` | Creates a named collection with sequential bit positions |
| **🔍 Utility Functions** | |
| `toBinaryString(bits, length)` | Converts bits to a binary string representation |
| `toFormattedBinaryString(bits, length)` | Converts bits to a formatted binary string with grouping |
| `countBits(bits)` | Counts the number of bits set to 1 |
| `isSingleBit(bits)` | Checks if exactly one bit is set |
| Library | Description | npm |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [@moon7/async](https://github.com/moon7-io/moon7-async) | Asynchronous utilities for managing promises, concurrent operations, and timing | [](https://www.npmjs.com/package/@moon7/async) |
| [@moon7/inspect](https://github.com/moon7-io/moon7-inspect) | Runtime type checking with powerful, composable type inspectors | [](https://www.npmjs.com/package/@moon7/inspect) |
| [@moon7/result](https://github.com/moon7-io/moon7-result) | Functional error handling with Result and Maybe types | [](https://www.npmjs.com/package/@moon7/result) |
| [@moon7/signals](https://github.com/moon7-io/moon7-signals) | Reactive programming with Signals, Sources, and Streams | [](https://www.npmjs.com/package/@moon7/signals) |
We welcome contributions from everyone! See our [contributing guide](https://github.com/moon7-io/.github/blob/main/CONTRIBUTING.md) for more details on how to get involved. Please feel free to submit a Pull Request.
This project is released under the MIT License. See the [LICENSE](https://github.com/moon7-io/moon7-bits/blob/main/LICENSE) file for details.
Created and maintained by [Munir Hussin](https://github.com/profound7).