Skip to content

docs: add typedoc #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ThatsEmbarrassing merged 15 commits into from
Nov 4, 2025
Merged

docs: add typedoc #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
5f6277f
chore: fix typo in README
Nov 2, 2025
e501c83
tests: add unit tests
Nov 2, 2025
b285de0
fix(Flag): change checking flag presence order
Nov 2, 2025
7caf8de
fix(FlagRegistry): change combine's return type
Nov 2, 2025
e643db7
fix(IFlag): add alias property
Nov 2, 2025
4600b08
chore: upgrade to 1.0.1
Nov 2, 2025
b53758e
Merge branch 'develop' of https://github.com/ThatsEmbarrassing/bitwis…
Nov 2, 2025
2386fe8
feat(Flag): add bulk operations
Nov 2, 2025
47b2f64
feat(FlagRegistry): add parse method
Nov 3, 2025
9408321
chore: update README.md for 1.1.0
Nov 3, 2025
615f0fc
chore: set repository
Nov 3, 2025
d1ed4ec
chore: upgrade to 1.1.0
Nov 3, 2025
b260d25
style: add eslint
Nov 3, 2025
a61b0d8
chore: rebase develop to main
Nov 3, 2025
9e2d3ac
docs: add typedoc
Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 2 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ const fromHex = permissionRegistry.parse("3", 16); // READ + WRITE
const fromBinary = permissionRegistry.parse("101", 2); // READ + EXECUTE

// check for flags
const userPermissions = permissionsRegistry.combine("READ", "EXECUTE");
const userPermissions = permissionRegistry.combine("READ", "EXECUTE");

console.log(userPermissions.has("READ")); // true
console.log(userPermissions.has("WRITE")); // false
Expand All @@ -52,7 +52,7 @@ console.log(userPermissions.has("EXECUTE")); // true
Flag's instances are immutable. Thats means all operations return new instances. For example:

```ts
const readWrite = permissionsRegistry.combine("READ", "WRITE");
const readWrite = permissionRegistry.combine("READ", "WRITE");

// add execute flag
const fullPermissions = readWrite.add("EXECUTE");
Expand All @@ -64,70 +64,3 @@ const read = readWrite.remove("WRITE");
console.log(readWrite.has("WRITE")); // true
console.log(read.has("WRITE")); // false
```

## API Reference

### Class: `FlagsRegistry<TFlags extends string>`

Manages a collection of flag keys and their corresponding bitmask values. Use this to define and retrieve flag bit positions.

#### Static Methods

| Method | Description | Parameters | Returns | Throws |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------- | ------ |
| `FlagsRegistry.from(...flagKeys: TFlags[])` | Creates a new registry instance from an array of flag keys. Automatically deduplicates keys and assigns sequential bit positions (starting from bit 0). | `flagKeys`: Array of string keys. | `FlagsRegistry<TFlags>` | None. |

**Example:**

```typescript
const registry = FlagsRegistry.from("READ", "WRITE", "READ"); // Deduplicates 'READ'
```

#### Instance Methods

| Method | Description | Parameters | Returns | Throws |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------- |
| `keys()` | Returns an iterator over all flag keys. | None. | `MapIterator<TFlags>` | None. |
| `values()` | Returns an iterator over all bit values. | None. | `MapIterator<bigint>` | None. |
| `entries()` | Returns an iterator over key-bit pairs. | None. | `MapIterator<[TFlags, bigint]>` | None. |
| `get(flagName: TFlags)` | Retrieves the bitmask value for a specific flag key. | `flagName`: The flag key. | `bigint \| undefined` | None. |
| `empty()` | Creates an empty flag instance (value `0n`). | None. | `IFlag<TFlags>` | None. |
| `parse(value: string \| number \| bigint, radix?: string)` | Creates a flag from a value. If value is string, do **NOT** use prefixes like: `0x` or `0b`, like in JS. | `value` - source value; `radix` - base of value. Use if `value` is string. By default, equals to 10. | `IFlag<TFlags>` | `Error` if string value can't be parsed. |
| `combine(...flagKeys: TFlags[])` | Combines the specified flag keys into a new `Flag` instance by bitwise OR-ing their values. | `flagKeys`: Array of flag keys to combine. | `IFlag<TFlags>` | `Error` if any key is not registered. |

**Example:**

```typescript
const combined = registry.combine("READ", "WRITE"); // Value: 3n (0b11)
```

### Class: `Flag<TFlags extends string>`

Represents a bitwise combination of flags from a registry. All operations are immutable, returning new instances.

#### Properties

| Property | Description | Type |
| -------- | -------------------------------------------------------------- | -------- |
| `value` | The raw `BigInt` representing the combined bitmask. Read-only. | `bigint` |

#### Methods

| Method | Description | Parameters | Returns | Throws |
| -------------------------------- | ---------------------------------------------------------------------------- | --------------------------- | --------------- | ------------------------------------- |
| `isEmpty()` | Checks if no flags are set. | None. | `boolean` | None. |
| `has(flagName: TFlags)` | Tests if a specific flag is set in this combination. | `flagName`: The flag key. | `boolean` | None. |
| `add(...flagNames: TFlags[])` | Adds flags to the combination (idempotent if already set). Returns `IFlag`. | `flagNames`: The flag keys. | `IFlag<TFlags>` | `Error` if the key is not registered. |
| `remove(...flagNames: TFlags[])` | Removes flags from the combination (idempotent if not set). Returns `IFlag`. | `flagNames`: The flag keys. | `IFlag<TFlags>` | `Error` if the key is not registered. |
| `toString()` | Returns a string representation including the alias and raw value. | None. | `string` | None. |
| `alias` (getter) | Computed human-readable alias (e.g., `"[READ+WRITE]"` or `"EMPTY_FLAG"`) | None. | `string` | None. |

**Validation Note:** The constructor (internal) validates that the value only uses known bits from the registry and is non-negative. Unknown bits or negative values throw an `Error`.

**Example:**

```typescript
const flag = registry.combine("READ");
console.log(flag.has("READ")); // true
console.log(flag.add("WRITE").alias); // "[READ+WRITE]"
```
Loading