Add Material for MkDocs documentation (#56)

* Add Material for MkDocs documentation

* Add GitHub Pages deployment workflow

Author: phellipeandrade

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

docs/basic-usage.md

@@ -0,0 +1,131 @@
+# Basic Usage
+
+This section shows how to configure RBAC, model permissions, and integrate the library into common application layers.
+
+## Configure RBAC
+
+Create an instance by passing configuration and a role map. Configuration accepts a custom logger and a `enableLogger` flag to turn logging on or off.
+
+```ts
+import RBAC from '@rbac/rbac';
+
+const rbac = RBAC({ enableLogger: true })({
+  guest: { can: ['products:find'] }
+});
+```
+
+## Define roles and permissions
+
+A role definition accepts:
+
+- `can`: An array of strings or objects with a `name` and optional `when` guard. Strings match directly, and patterns can use glob wildcards or regular expressions.
+- `inherits`: An optional array of roles to pull permissions from.
+
+```ts
+const rbac = RBAC()({
+  user: { can: ['products:find'] },
+  supervisor: {
+    can: [
+      { name: 'products:edit', when: () => true },
+      { name: 'products:*' } // wildcard
+    ],
+    inherits: ['user']
+  }
+});
+```
+
+`when` guards can be synchronous, async, a returned Promise, or a callback. They receive the `params` object passed to `can`.
+
+```ts
+const rbac = RBAC()({
+  auditor: {
+    can: [
+      { name: 'products:audit:callback', when: (_params, done) => done(null, true) },
+      { name: 'products:audit:async', when: async () => true },
+      { name: 'products:audit:promise', when: Promise.resolve(true) }
+    ]
+  }
+});
+```
+
+## Check permissions
+
+The `can` helper resolves inheritance, matches exact operations, globs, or regexes, and evaluates conditional guards when present:
+
+```ts
+await rbac.can('supervisor', 'products:find');
+await rbac.can('supervisor', 'products:create');
+await rbac.can('auditor', /products:audit/);
+await rbac.can('auditor', 'products:audit:async', { requestId: '42' });
+```
+
+## Update roles at runtime
+
+Add or merge role definitions without rebuilding your application:
+
+```ts
+rbac.addRole('editor', { can: ['products:update'], inherits: ['user'] });
+rbac.updateRoles({
+  user: { can: ['products:find', 'products:share'] }
+});
+```
+
+## Persist and load roles with adapters
+
+Use the optional adapters to store roles in your database. Each adapter supports a customizable table/collection schema and an optional `tenantId` for multi-tenancy.
+
+```ts
+import { MongoRoleAdapter, MySQLRoleAdapter, PostgresRoleAdapter } from '@rbac/rbac/adapters';
+
+const mongoAdapter = new MongoRoleAdapter({
+  uri: 'mongodb://localhost:27017',
+  dbName: 'mydb',
+  collection: 'roles'
+});
+
+const mysqlAdapter = new MySQLRoleAdapter({
+  uri: 'mysql://user:pass@localhost:3306/app',
+  table: 'roles'
+});
+
+const pgAdapter = new PostgresRoleAdapter({
+  connectionString: 'postgres://user:pass@localhost:5432/app',
+  table: 'roles'
+});
+```
+
+Adapters expose `getRoles`, `addRole`, and `updateRoles` to manage definitions in storage.
+
+## Multi-tenant RBAC
+
+Scope RBAC to a specific tenant by loading role definitions with a `tenantId`:
+
+```ts
+import { createTenantRBAC, MongoRoleAdapter } from '@rbac/rbac';
+
+const adapter = new MongoRoleAdapter({
+  uri: 'mongodb://localhost:27017',
+  dbName: 'mydb',
+  collection: 'roles'
+});
+
+const rbacTenantA = await createTenantRBAC(adapter, 'tenant-a');
+await rbacTenantA.can('user', 'products:find');
+```
+
+## Web framework middleware
+
+Guard routes using the built-in middleware factories for Express, NestJS, and Fastify. Each factory accepts optional callbacks to extract the role and params or to override the default denied response.
+
+```ts
+import RBAC, { createExpressMiddleware } from '@rbac/rbac';
+
+const rbac = RBAC({ enableLogger: false })({
+  user: { can: ['products:find'] }
+});
+
+const canFindProducts = createExpressMiddleware(rbac)('products:find');
+app.get('/products', canFindProducts, handler);
+```
+
+Swap `createExpressMiddleware` for `createNestMiddleware` or `createFastifyMiddleware` to integrate with other frameworks.

docs/comparison.md

@@ -0,0 +1,30 @@
+# Comparison
+
+RBAC focuses on performance and flexibility while keeping the API small. This page highlights how it differs from other access-control approaches and how to measure those differences with the built-in benchmarks.
+
+## Where this library stands out
+
+- **Operation-oriented permissions:** Operations are plain strings that can also be matched with globs or regular expressions, enabling granular checks without designing a resource matrix.
+- **Hierarchical roles:** Roles can inherit from one another to avoid duplicating permission lists.
+- **Conditional guards:** Permissions can be gated by callbacks, async functions, or promises so that runtime context influences the decision.
+- **Runtime mutability:** `addRole` and `updateRoles` let you change the role map without restarting your app.
+- **Adapter support:** Optional MongoDB, MySQL, and PostgreSQL adapters make it straightforward to persist and share definitions across services.
+- **Multi-tenant aware:** A `tenantId` can be provided to adapters and the `createTenantRBAC` helper to isolate role definitions by tenant.
+
+## Benchmarks
+
+The repository includes a benchmark suite that compares RBAC against popular alternatives such as `accesscontrol`, `rbac`, `easy-rbac`, and `fast-rbac` across direct checks, inherited roles, and conditional permissions.
+
+Run the suite with:
+
+```bash
+yarn bench
+```
+
+The script builds large permission sets, executes identical operations against each library, and prints timing results to the console.
+
+## Choosing the right model
+
+- Pick this library when you need fast checks on string-based operations, optional glob/regex matching, and minimal setup.
+- Use conditional guards when permissions depend on runtime data such as ownership or tenant membership.
+- Pair the adapters with the multi-tenant helper if your platform isolates permissions per customer or workspace.

docs/get-started.md

@@ -0,0 +1,79 @@
+# Get Started
+
+Follow this guide to install the library, define your first role map, and perform permission checks.
+
+## 1) Install the package
+
+```bash
+npm install @rbac/rbac
+# or
+yarn add @rbac/rbac
+```
+
+The package ships with TypeScript types and works in JavaScript and TypeScript projects.
+
+## 2) Create a role map
+
+`RBAC` is a curried factory. First pass configuration, then the role definitions:
+
+```ts
+import RBAC from '@rbac/rbac';
+
+const rbac = RBAC({ enableLogger: false })({
+  reader: { can: ['articles:find'] },
+  editor: { can: ['articles:update'], inherits: ['reader'] },
+  admin: { can: ['articles:*'] }
+});
+```
+
+- `can` is an array of operation strings or objects with a `when` guard.
+- `inherits` lets a role reuse permissions from other roles.
+
+## 3) Check permissions
+
+Use the `can` function returned by the factory to verify operations. Operations accept strings, glob-style wildcards, or regular expressions:
+
+```ts
+await rbac.can('reader', 'articles:find'); // true
+await rbac.can('editor', 'articles:find'); // true via inheritance
+await rbac.can('editor', 'articles:delete'); // false
+await rbac.can('admin', /articles:/); // true through regex
+```
+
+## 4) Add conditions
+
+Attach synchronous, asynchronous, Promise-based, or callback guards to permissions to enforce contextual rules:
+
+```ts
+interface Params {
+  ownerId: string;
+  currentUserId: string;
+}
+
+const rbac = RBAC()({
+  author: {
+    can: [{
+      name: 'articles:update',
+      when: ({ ownerId, currentUserId }) => ownerId === currentUserId
+    }]
+  }
+});
+
+await rbac.can('author', 'articles:update', {
+  ownerId: '123',
+  currentUserId: '123'
+}); // true
+```
+
+## 5) Keep iterating
+
+Roles can evolve at runtime without rebuilding your application:
+
+```ts
+rbac.addRole('support', { can: ['tickets:find'] });
+rbac.updateRoles({
+  reader: { can: ['articles:find', 'articles:share'] }
+});
+```
+
+Head to **Basic Usage** for more end-to-end examples that include adapters and web framework middleware.

docs/index.md

@@ -0,0 +1,27 @@
+# RBAC
+
+Hierarchical Role-Based Access Control (RBAC) for Node.js and TypeScript. The library is curried for flexible setup, keeps dependencies to a minimum, and ships with first-class TypeScript types.
+
+## Highlights
+
+- **Operation-first design:** Define operations as strings, globs, or regular expressions, and check them with a simple `can` helper.
+- **Hierarchical roles:** Reuse permissions with inheritance and update definitions at runtime without rebuilding your app.
+- **Runtime conditions:** Attach synchronous, async, promise-based, or callback-based guards to any permission.
+- **Adapters and middleware:** Load or persist role definitions through MongoDB, MySQL, or PostgreSQL adapters and guard routes with Express, NestJS, or Fastify helpers.
+- **Multi-tenant ready:** Scope role definitions to tenants using the optional adapter utilities.
+
+## Quick tour
+
+```ts
+import RBAC from '@rbac/rbac';
+
+const rbac = RBAC({ enableLogger: false })({
+  user: { can: ['products:find'] },
+  admin: { can: ['products:*'], inherits: ['user'] }
+});
+
+await rbac.can('user', 'products:find'); // true
+await rbac.can('admin', 'products:delete'); // true via inheritance and wildcard
+```
+
+Use the navigation to explore setup instructions, conceptual guides, feature comparisons, and practical usage recipes.

docs/installation.md

@@ -0,0 +1,40 @@
+# Installation
+
+## Library
+
+Install the package from npm using your preferred package manager:
+
+```bash
+npm install @rbac/rbac
+# or
+yarn add @rbac/rbac
+```
+
+The published bundle ships with its TypeScript declaration files so IDEs and build pipelines pick up types automatically.
+
+## Optional database drivers
+
+Role adapters are lazy-loaded and expect their respective drivers to be available in your project. Add the dependency for the adapter you plan to use:
+
+- MongoDB adapter → `npm install mongodb`
+- MySQL adapter → `npm install mysql2`
+- PostgreSQL adapter → `npm install pg`
+
+Each adapter accepts custom column names and a tenant identifier; see **Basic Usage** for concrete examples.
+
+## Documentation site
+
+This repository includes a ready-to-use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) configuration. To preview the docs locally:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
+The site will be available at `http://127.0.0.1:8000/` by default. To publish to GitHub Pages, run:
+
+```bash
+mkdocs gh-deploy
+```
+
+The command builds the static site and pushes it to the `gh-pages` branch, which GitHub Pages can serve directly.

docs/le-introduction.md

@@ -0,0 +1,21 @@
+# Library Essentials (LE) Introduction
+
+This library centers on an **operation-first** approach to authorization. Instead of tying permissions to resources, you describe the exact operations your application exposes and map roles to those operations.
+
+## How RBAC is structured
+
+- **Curried factory:** `RBAC(config)(roles)` returns an object with the `can`, `addRole`, and `updateRoles` helpers. Configuration accepts a custom logger and a switch to enable or disable logging.
+- **Operations:** Any string can be an operation. Use exact matches, glob-style patterns (e.g., `products:*`), or regular expressions to express permissions at the granularity you need.
+- **Roles:** Each role lists operations under `can` and can optionally `inherit` other roles, creating a hierarchy without repeating permissions.
+- **Conditions:** Every permission can define a `when` guard as a boolean, promise, async function, or callback. The guard receives the `params` object you pass to `can` and returns a truthy or falsy value.
+- **Caching:** Permission checks are cached per role to speed up repeated lookups, including glob and regex evaluations.
+
+## What happens during a `can` check
+
+1. Resolve the role and expand inherited permissions.
+2. Try direct matches (`operation` string) first.
+3. Evaluate glob or regex matches, caching results per role and pattern.
+4. If the permission has a `when` guard, normalize it to an async function and evaluate it with the provided params.
+5. Log the outcome when logging is enabled.
+
+Understanding these steps makes it easier to choose between exact operations, patterns, or conditional checks for your own system.

mkdocs.yml

@@ -0,0 +1,35 @@
+site_name: RBAC
+site_description: Hierarchical, curried RBAC utilities for Node.js and TypeScript
+site_url: https://github.com/phellipeandrade/rbac
+repo_url: https://github.com/phellipeandrade/rbac
+repo_name: phellipeandrade/rbac
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - toc.integrate
+    - content.code.copy
+    - content.tabs.link
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+markdown_extensions:
+  - admonition
+  - codehilite
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+nav:
+  - Home: index.md
+  - Get Started: get-started.md
+  - LE Introduction: le-introduction.md
+  - Installation: installation.md
+  - Basic Usage: basic-usage.md
+  - Comparison: comparison.md
+  - Migrating from v1 to v2: migrating-v1-to-v2.md