access-permission-control

v0.0.8

Published

10 days ago

The **Access Permission Control** package is a lightweight Role-Based Access Control (RBAC) and Permission-Based Authorization solution written in TypeScript. It is designed to work seamlessly with React applications as well as backend systems (NestJS). T

0High
0Medium
0Low

krishnanrs

Access Permission Control Library Documentation

1. Introduction

The Access Permission Control package is a lightweight Role-Based Access Control (RBAC) and Permission-Based Authorization solution written in TypeScript. It is designed to work seamlessly with React applications as well as backend systems (NestJS). This library helps developers manage user roles, permissions, and access protections in a clean, scalable way.

This documentation covers:

Features
Architecture
File structure
Explanation of core concepts
How to install and use the package
React usage guide
API reference
Examples (roles, permissions, route guarding)

2. Key Features

2.1 Role Management

Assign roles to users (e.g., Admin, Staff, Manager).
Check user role via hasRole().

2.2 Permission-Based Access Control

Assign permissions such as VIEW DASHBOARD, EDIT USER, etc.
Check permissions using hasPermission().

2.3 React Support

Comes with a built-in AccessControlProvider.
Provides useAccessControl() custom hook.
Can be used to protect components, pages, or routes.

2.4 TypeScript Support

Full type definitions included.

2.5 NestJS Support (Optional)

Works with backend permission validation.

3. Installation

Install from npm:

npm install access-permission-control

4. Package Structure

access-permission-control/
│
├── src/
│   ├── react/
│   │   ├── AccessControlProvider.tsx
│   │   ├── RouteGuard.tsx
│   │   └── index.ts
│   │
│   ├── nestjs/
│   │   └── decorators, guards, utils...
│   │
│   ├── index.react.ts
│   ├── index.nestjs.ts
│
├── dist/
│   ├── react/* (bundled files)
│   └── nestjs/* (bundled files)
│
└── package.json

5. Core Concepts

5.1 Roles

Roles are high‑level groups like:

Admin
Manager
User

Example:

roles: ["Admin"]

5.2 Permissions

Permissions define exactly what a user can do:

permissions: ["VIEW DASHBOARD", "EDIT DOCUMENT"]

5.3 AccessControlProvider

A React context provider that exposes:

roles
permissions
hasRole(role)
hasPermission(permission)

5.4 useAccessControl() Hook

Allows any component to ask:

Does user have a role?
Does user have a permission?

6. How to Use (React)

6.1 Wrap Your App with Permission Provider

'use client';
import PermissionProvide from './PermissionProvide';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <PermissionProvide>{children}</PermissionProvide>
      </body>
    </html>
  );
}

7. PermissionProvide Component

This component loads user data from localStorage and passes it to the RBAC system.

Example Implementation

'use client';

import { ReactNode, useEffect, useState } from 'react';
import { AccessControlProvider } from 'access-permission-control/dist/index.react';

export default function PermissionProvide({ children }) {
  const [roles, setRoles] = useState([]);
  const [permissions, setPermissions] = useState([]);
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    const userString = localStorage.getItem('currentUser');
    if (userString) {
      const currentUser = JSON.parse(userString);
      setRoles([currentUser.role]);
      setPermissions(currentUser.permissions);
    }
    setIsReady(true);
  }, []);

  if (!isReady) return null;

  return (
    <AccessControlProvider roles={roles} permissions={permissions}>
      {children}
    </AccessControlProvider>
  );
}

8. Using the `useAccessControl` Hook

Example inside a React component:

'use client';
import { useAccessControl } from 'access-permission-control/dist/index.react';

export default function DashboardPage() {
  const { hasRole, hasPermission } = useAccessControl();

  return (
    <>
      {hasRole('Admin') && <h1>Welcome Admin</h1>}
      {hasPermission('VIEW DASHBOARD') ? <p>You can view dashboard</p> : <p>Access denied</p>}
    </>
  );
}

9. Using RouteGuard

import { RouteGuard } from 'access-permission-control/dist/index.react';

<RouteGuard requiredRoles={["Admin"]}>
  <AdminSettingsPage />
</RouteGuard>

10. How to Store User After Login

localStorage.setItem(
  'currentUser',
  JSON.stringify({
    role: 'Admin',
    permissions: ['VIEW DASHBOARD', 'MANAGE USERS'],
  })
);

11. Backend / NestJS Support

The nestjs build includes decorators and guards for role/permission enforcement.