@iamjs/react

@iamjs/react

This package contains the react hook for iamjs a library for easy role and permissions management for your application.

Installation

npm install @iamjs/core @iamjs/react
# or
yarn add @iamjs/core @iamjs/react
# or
pnpm add @iamjs/core @iamjs/react
# or
bun add @iamjs/core @iamjs/react

Usage

Basic usage

This example demonstrates the usage of the @iamjs/core and @iamjs/react packages for role-based authorization.

• Import the necessary components and functions from the packages:

import { Role } from '@iamjs/core';
import { createSchema, useAuthorization } from '@iamjs/react';

• Create a schema using the createSchema function:

const schema = createSchema({
  user: new Role({
    name: 'user',
    description: 'User role',
    meta: {
      name: 'user'
    },
    config: {
      books: {
        base: 'crudl',
        custom: {
          upgrade: true,
          downgrade: false,
          sort: true
        }
      }
    }
  })
});

In this example, the schema is created with a single role named 'user'. The role has a description, meta data, and configuration for the 'books' resource. The 'books' resource has 'crudl' scopes (create, read, update, delete, list), and additional custom permissions such as 'upgrade', 'downgrade', and 'sort'.

• Use the useAuthorization hook to access the authorization methods:

const { can } = useAuthorization(schema);

The useAuthorization hook takes the schema as a parameter and returns an object that includes the can method to check permissions.

• Use the can method to check if the user has permission:

const canDo = can('user', 'books', 'create').toString(); // 'true'

The can method is called with the role name ('user'), the resource name ('books'), and the action ('create'). It returns a boolean value indicating whether the user with the 'user' role has permission to create books.

In summary, this example demonstrates how to create a schema with a role and its permissions using the @iamjs/core package. Then, the @iamjs/react package is used to access the useAuthorization hook and check permissions using the can method.

Build a role from its permissions

This example also demonstrates the usage of the build function for permissions based authorization.

import { Role } from "@iamjs/core";
import { createSchema, useAuthorization } from "@iamjs/react";
import { useEffect, useState } from "react";

// Create the initial schema with a default roles
const schema = createSchema({
  user: new Role({
    name: "user",
    description: "User role",
    meta: {
      name: "user",
    },
    config: {
      books: {
        base: "crudl",
        custom: {
          upgrade: true,
          downgrade: false,
          sort: true,
        },
      },
    },
  }),
});

// Custom hook to fetch user permissions and build the role
const useUser = () => {
  const { build } = useAuthorization(schema);
  const [userRole, setUserRole] = useState(null);

  useEffect(() => {
    // Call the API endpoint to fetch user permissions
    fetch("/permssions")
      .then((response) => response.json())
      .then((data) => {
        // Build the role based on the received permissions
        const builtRole = build(data);
        setUserRole(builtRole);
      })
      .catch((error) => {
        console.error("Error fetching user permissions:", error);
      });
  }, []);

  return userRole;
};

const Component = () => {
  const userRole = useUser();

  if (!userRole) {
    return <div>Loading...</div>;
  }

  const { can, Show } = userRole;

  return (
    <div>
      <div>{can("books", "create").toString()}</div>
      <Show resources="books" actions="create">
        <div>Rendered if user has 'create' permission for 'books'</div>
      </Show>
    </div>
  );
};

Show component based on permission

This example also demonstrates the usage of the Show component for conditional rendering based on the user's permssions.

• Import the necessary components and functions from the packages:

import { Role } from '@iamjs/core';
import { createSchema, useAuthorization } from '@iamjs/react';

• Create a schema using the createSchema function:

const schema = createSchema({
  user: new Role({
    name: 'user',
    description: 'User role',
    meta: {
      name: 'user'
    },
    config: {
      books: {
        base: 'crudl',
        custom: {
          upgrade: true,
          downgrade: false,
          sort: true
        }
      }
    }
  })
});

The schema is created in the same way as in the previous example, with a role named 'user' and its permissions for the 'books' resource.

• Use the useAuthorization hook to access the authorization components:

const { Show } = useAuthorization(schema);

The useAuthorization hook is used to access the authorization components. In this example, only the Show component is extracted from the returned object.

• Render the Show component with the appropriate props:

<Show role="user" resources="books" actions="create">
  <div>can show</div>
</Show>

The Show component is used to conditionally render the child components based on the user's role and permissions. It takes props specifying the role, resources, and actions, and renders the child components if the user has permission.

In summary, this example demonstrates how to use the Show component from the @iamjs/react package to conditionally render components based on the user's role and permissions. The component is rendered within the Show component's block if the user has the specified role, resources, and actions.