feat!: migrate to Bun, publish ESM-only exports, add framework integrations (#30)

- Tooling: switch scripts/CI to Bun
- Packaging: ESM-only build, modern exports map + wildcard subpath exports for integrations (permask/<integration>)
- Integrations: express, fastify, h3, nitro, nestjs, hono, koa, itty-router, elysia (thin adapters)
- Core: add PermaskError, base64 helpers, portable packBitmasks/unpackBitmasks, add formatBitmask

  BREAKING CHANGE: package is ESM-only (CJS/UMD entry points removed)
  BREAKING CHANGE: unpackBitmasks now throws PermaskError on invalid input
  BREAKING CHANGE: createPermask().create now throws PermaskError for unknown groups

Author: dschewchenko

.github/workflows/release.yml

@@ -25,24 +25,35 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
+          bun-version: "1.3.1"
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+
+      - name: Use cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: pnpm install
+        run: bun install --frozen-lockfile
       - name: Build
-        run: pnpm build
+        run: bun run build
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm dlx semantic-release
+        run: npx semantic-release
 
   playground:
     name: Playground
@@ -52,26 +63,29 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
-      - name: Use Node.js
-        uses: actions/setup-node@v4
+          bun-version: "1.3.1"
+
+      - name: Use cache
+        uses: actions/cache@v4
         with:
-          node-version: 22
-          cache: 'pnpm'
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: |
-          cd playground/vue
-          pnpm install
+        run: bun install --frozen-lockfile
       - name: Build playground
-        run: |
-          cd playground/vue
-          pnpm build
+        working-directory: playground/vue
+        run: bun run build
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./playground/vue/dist
-

.github/workflows/test.yml

@@ -1,5 +1,9 @@
 name: Test
+
 on:
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main
@@ -8,9 +12,6 @@ jobs:
   test:
     name: Test
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [ 22 ]
 
     permissions:
       # Required to checkout the code
@@ -20,19 +21,27 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+          bun-version: "1.3.1"
+
+      - name: Use cache
+        uses: actions/cache@v4
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'pnpm'
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: pnpm install
+        run: bun install --frozen-lockfile
+
       - name: 'Test'
-        run: pnpm test:coverage
+        run: bun run test:coverage
       - name: 'Report Coverage'
         if: always() # Also generate the report if tests are failing
         uses:  davelosert/vitest-coverage-report-action@v2

AGENTS.md

@@ -0,0 +1,54 @@
+# Repository Guidelines
+
+## Project Structure
+
+- `src/`: main TypeScript source (utilities, constants, integrations).
+- `src/**/*.test.ts`: Vitest unit tests colocated with code.
+- `playground/vue/`: Vue playground for interactive/manual validation.
+- `dist/`: build output (generated; don’t edit by hand).
+- `.github/workflows/`: CI and release pipelines (Bun-based).
+
+## Build, Test, and Development Commands
+
+This repo uses **Bun** as the package manager and runtime.
+Use the version pinned in `package.json#packageManager` (CI matches it).
+
+```bash
+bun install                 # install deps (uses bun.lock)
+bun run build               # build library bundles + types into dist/
+bun run test                # run vitest (watch/default mode)
+bun run test:coverage       # run tests + V8 coverage summary
+bun run lint                # biome check for formatting + lint
+bun run lint:fix            # apply biome fixes where safe
+```
+
+Playground (from repo root):
+
+```bash
+bun --cwd=playground/vue run dev
+bun --cwd=playground/vue run build
+```
+
+## Coding Style & Naming Conventions
+
+- Language: TypeScript (ESM, `strict`).
+- Formatting/linting: **Biome** (`bunx biome check .`).
+- Indentation: 2 spaces; line width: 120.
+- File naming: `kebab-case.ts` for modules; tests as `*.test.ts`.
+
+## Testing Guidelines
+
+- Framework: **Vitest**.
+- Keep tests close to the code they validate (`src/**`).
+- Add/extend tests for new behavior and bug fixes; prefer deterministic tests.
+- Run locally before pushing: `bun run test:coverage`.
+
+## Commit & Pull Request Guidelines
+
+- This repo’s public changelog is generated by **semantic-release**, so commit messages must follow **Conventional Commits** (enforced by commitlint).
+- Prefer small, focused commits (one logical change per commit), because release notes are derived from them.
+- Use scopes to keep the changelog readable: `core`, `integrations`, `docs`, `playground`, `ci`, `build`.
+  - Examples: `feat(core): add formatBitmask utility`, `feat(integrations): add elysia adapter`, `fix(pack): throw on invalid base64`, `chore(ci): switch workflows to bun`.
+- Breaking changes: use `feat!:` / `fix!:` or add a `BREAKING CHANGE:` footer.
+- PRs should include: a short description, rationale, and any relevant usage notes.
+- Requirements: `bun run lint`, `bun run test:coverage`, and `bun run build` must pass; avoid committing generated `dist/` output.

README.md

@@ -17,7 +17,7 @@ For example in UNIX file systems, bitmasks are used to manage file permissions (
 - Fast: Bitwise operations (&, |) are faster than comparing strings.
 - Compact: Combine multiple permissions in a single integer (e.g., 0b1111 for read, create, update, delete).
   Just 4 bits for access control. For groups, you can use any number of bits,
-- Flexible: Easy to check, add, or remove permissions.
+- Flexible: Easy to check, add or remove permissions.
 
 Example of using bitmasks:
 
@@ -51,6 +51,8 @@ Group(1)  Permissions(read, create, update)
 Install `permask`:
 
 ```bash
+# bun
+bun add permask
 # npm
 npm install permask
 # pnpm
@@ -93,20 +95,18 @@ const permask = createPermask(PermissionGroup);
 
 - #### create a bitmask from an object:
 ```ts
-const bitmask2 = permask.create({
+console.log(permask.create({
   group: "LIKE",
   read: true,
   create: false,
   update: true,
   delete: false
-});
-console.log(bitmask2); // 53 (0b110101)
+})); // 53 (0b110101)
 ```
 
 - #### parse a bitmask to an object:
 ```ts
-const parsed = permask.parse(31); // 0b11111
-console.log(parsed);
+console.log(permask.parse(31)); // 0b11111
 // {
 //   group: 1,
 //   groupName: "POST",
@@ -120,36 +120,33 @@ console.log(parsed);
 - #### check if a bitmask has a specific group:
 
 ```ts
-const hasGroup = permask.hasGroup(23, "LIKE");
-console.log(hasGroup); // true
+console.log(permask.hasGroup(23, "LIKE")); // true
 // You can also use numeric group IDs
 const hasGroupById = permask.hasGroup(23, PermissionGroup.LIKE);
 ```
 
 - #### check if a bitmask has a specific permission:
 ```ts
-const canRead = permask.canRead(17);
-const canCreate = permask.canCreate(17);
-const canDelete = permask.canDelete(17);
-const canUpdate = permask.canUpdate(17);
-console.log(canRead, canCreate, canDelete, canUpdate); // true, false, false, false
+console.log(
+  permask.canRead(17),
+  permask.canCreate(17),
+  permask.canDelete(17),
+  permask.canUpdate(17)
+); // true, false, false, false
 ```
 
 - #### check if a bitmask has access to a specific group and permission:
 ```ts
 import { PermissionAccess } from "permask";
 
 // Check if bitmask has read access to LIKE group using string access
-const hasReadAccess = permask.hasAccess(53, "LIKE", "read");
-console.log(hasReadAccess); // true
+console.log(permask.hasAccess(53, "LIKE", "read")); // true
 
 // Check if bitmask has create access to LIKE group using string access
-const hasCreateAccess = permask.hasAccess(53, "LIKE", "create");
-console.log(hasCreateAccess); // false
+console.log(permask.hasAccess(53, "LIKE", "create")); // false
 
 // You can also use numeric group IDs with string access
-const hasAccessById = permask.hasAccess(53, PermissionGroup.LIKE, "update");
-console.log(hasAccessById); // true
+console.log(permask.hasAccess(53, PermissionGroup.LIKE, "update")); // true
 
 // You can use numeric access values (PermissionAccess) instead of strings
 const hasUpdateAccessNumeric = permask.hasAccess(53, PermissionGroup.LIKE, PermissionAccess.UPDATE);
@@ -158,10 +155,8 @@ console.log(hasUpdateAccessNumeric); // true
 
 - #### get group name from bitmask:
 ```ts
-const groupName = permask.getGroupName(23);
-console.log(groupName); // "LIKE"
-const groupName2 = permask.getGroupName(29);
-console.log(groupName2); // undefined
+console.log(permask.getGroupName(23)); // "LIKE"
+console.log(permask.getGroupName(29)); // undefined
 ```
 
 
@@ -173,25 +168,35 @@ You can use `permask` just with bitmask utility functions.
 
 ### Use bitmask utilities:
 
+#### `access` name vs `access` mask
+
+- **Access name**: `"read" | "create" | "update" | "delete"` (used in `createPermask().hasAccess(...)`).
+- **Access mask**: a number made from `PermissionAccess` flags (used in low-level utils), e.g. `PermissionAccess.READ | PermissionAccess.UPDATE`.
+
 **Functions:**
 - `createBitmask({ group: number, read: boolean, create: boolean, delete: boolean, update: boolean }): number` - creates a bitmask from an options.
 - `parseBitmask(bitmask: number): { group: number, read: boolean, create: boolean, delete: boolean, update: boolean }` - parses a bitmask and returns an object.
 - `getPermissionGroup(bitmask: number): number` - returns a group number from a bitmask.
-- `getPermissionAccess(bitmask: number): number` - returns an access number from a bitmask.
+- `getPermissionAccess(bitmask: number): number` - returns an access mask (4 bits) from a bitmask.
 - `hasPermissionGroup(bitmask: number, group: number): boolean` - checks if a bitmask has a specific group.
-- `hasPermissionAccess(bitmask: number, access: number): boolean` - checks if a bitmask has a specific access.
-- `hasRequiredPermission(bitmasks: number[], group: number, access: number): boolean` - checks if any bitmask in the array has the required permission for the specified group and access.
+- `hasPermissionAccess(bitmask: number, accessMask: number): boolean` - checks if a bitmask has **any** access flag from `accessMask`.
+- `hasAllPermissionAccess(bitmask: number, accessMask: number): boolean` - checks if a bitmask has **all** access flags from `accessMask`.
+- `hasRequiredPermission(bitmasks: number[], group: number, accessMask: number): boolean` - checks if any bitmask has the required group and **any** access flag from `accessMask`.
 
   useful functions:
   - `canRead(bitmask: number): boolean`
   - `canCreate(bitmask: number): boolean`
   - `canDelete(bitmask: number): boolean`
   - `canUpdate(bitmask: number): boolean`
 - `setPermissionGroup(bitmask: number, group: number): number` - sets a group in a bitmask (will overwrite the previous group).
-- `setPermissionAccess(bitmask: number, access: number): number` - sets access in a bitmask (will overwrite the previous access).
-- `getPermissionBitmask(group: number, access: number): number` - creates a bitmask from a group and access.
-- `packBitbasks(bitmasks: number[], urlSafe?: boolean): string` - packs bitmasks to base64 string. (more compact than JSON.stringify)
-- `unpackBitmasks(base64: string, urlSafe?: boolean): number[]` - unpacks bitmasks from a base64 string.
+- `setPermissionAccess(bitmask: number, accessMask: number): number` - sets access mask (will overwrite the previous access).
+- `removePermissionAccess(bitmask: number, accessMask: number): number` - removes access flags from a bitmask.
+- `togglePermissionAccess(bitmask: number, accessMask: number): number` - toggles access flags in a bitmask.
+- `clearPermissionAccess(bitmask: number): number` - clears all access flags in a bitmask.
+- `getPermissionBitmask(group: number, accessMask: number): number` - creates a bitmask from a group and an access mask.
+- `packBitmasks(bitmasks: number[], urlSafe?: boolean): string` - packs bitmasks to base64 string (more compact than JSON.stringify).
+- `unpackBitmasks(packed: string, urlSafe?: boolean): number[]` - unpacks bitmasks from a packed string (throws `PermaskError` on invalid input).
+- `formatBitmask(bitmask: number, groups?: Record<string, number>): string` - formats a bitmask into a readable string for logging/debugging.
 
 **Constants:**
 - `PermissionAccess` - an enum-like object with access types.
@@ -212,8 +217,19 @@ You can use `permask` just with bitmask utility functions.
   } as const;
   ```
 
+## Integrations
+
+Framework integrations are published as subpath exports (ESM-only). See [src/integrations/README.md](src/integrations/README.md).
 
-## [Integration with frameworks](https://github.com/dschewchenko/permask/blob/main/integrations/README.md)
+- Express: `import { permaskExpress } from "permask/express";`
+- Fastify: `import { permaskFastify } from "permask/fastify";`
+- H3: `import { permaskH3 } from "permask/h3";`
+- Nitro: `import { permaskNitro } from "permask/nitro";`
+- NestJS: `import { permaskNestjs } from "permask/nestjs";`
+- Hono: `import { permaskHono } from "permask/hono";`
+- Koa: `import { permaskKoa } from "permask/koa";`
+- itty-router: `import { permaskIttyRouter } from "permask/itty-router";`
+- Elysia: `import { permaskElysia } from "permask/elysia";`
 
 ## How I'm using it?
 
@@ -236,15 +252,16 @@ If you have any questions or suggestions, feel free to open an issue or pull req
 - [x] Create a library
 - [x] Add tests
 - [x] Add documentation
-- [ ] Add easy-to-use integration with frameworks
-  - [x] Express
-  - [ ] Fastify
-  - [ ] H3
-  - [ ] Nitro
-  - [ ] NestJS
-  - [ ] Hono
-  - [ ] Koa
-  - [ ] itty-router
+- [x] Add easy-to-use integration with frameworks (subpath exports, ESM-only)
+  - [x] Express (`permask/express`) — Express middleware
+  - [x] Fastify (`permask/fastify`) — `preHandler` hook (works well with `@fastify/auth`)
+  - [x] H3 (`permask/h3`) — `requirePermask(event, ...)` + middleware
+  - [x] Nitro (`permask/nitro`) — H3-based helpers + handler wrapper
+  - [x] NestJS (`permask/nestjs`) — Decorator + Guard
+  - [x] Hono (`permask/hono`) — middleware (context-based)
+  - [x] Koa (`permask/koa`) — async middleware (typically via `ctx.state`)
+  - [x] itty-router (`permask/itty-router`) — handler / `before` middleware returning `Response`
+  - [x] Elysia (`permask/elysia`) — `beforeHandle` helper (usable inside `guard`)
 
 
 ## License