simple-rule
React library for simple permissions map creation and policy checking. Simple rule is an authorization library which restricts what resources a given user is allowed to access.
Why
Quite often, in any application, becomes necessary to allow or deny certain actions with objects, depending on the access rights of the current user. This library allows you to simplify the process of initializing the rules and their checks.
Install
npm install --save simple-rule
Quick start
This example explain simplest possible usage:
Wrap your component by SimpleRulesProvider and create rulesSchema
import React from 'react'
import { SimpleRulesProvider } from 'simple-rule'
const rulesSchema = {
post: {
show: ({ currentUser, record }) => !record.owner_id || record.owner_id === currentUser.id,
},
}
function Example({ currentUser }) {
return (
<SimpleRulesProvider rulesSchema={rulesSchema} currentUser={currentUser}>
<PostsList />
</SimpleRulesProvider>
)
}
Use rules in your components
import React from 'react'
import { useRules } from 'simple-rule'
const posts = [
{ id: 1, content: "Post visible for user with id = 1", owner_id: 1 },
{ id: 2, content: "Post visible for user with id = 2", owner_id: 2 },
{ id: 3, content: "Post visible for all users", owner_id: null },
]
function PostsList() {
const postRules = useRules('post')
return (
posts.map((post) => (
postRules.show(post) && (
<div key={post.id}>
{ `${post.id}. ${post.content}` }
</div>
)
))
)
}
Components
The following components are available as named imports from simple-rule.
SimpleRulesProvider
The SimpleRulesProvider
component is used for wrapping your React App so an instance of coniditions check will be made available within your React tree.
const rulesSchema = {
post: {
show: ({ currentUser, record }) => !record.owner_id || record.owner_id === currentUser.id,
},
}
const userRolesSchema = {
admin: (currentUser) => currentUser.role === 'admin',
}
function Example({ currentUser }) {
return (
<SimpleRulesProvider
rulesSchema={rulesSchema}
userRolesSchema={userRolesSchema}
currentUser={currentUser}
>
<PostsList />
</SimpleRulesProvider>
)
}
Props
currentUser
User object with any needed for you params:
const currentUser = { id: 1, role: 'admin', ... }
rulesSchema
Object with keys equal entity names (example: post
, user
) or entity usage place (example: settings/post
).
Each entity value equal object with keys - action names
and values - condition functions
.
Condition function
must return a boolean value of the condition result.
Condition function params:
currentUser
- passed to SimpleRulesProvider
user.
record
- passed to action check record.
roles
- passed to userRolesSchema
currentUser roles checks.
const rulesSchema = {
post: {
show: ({ currentUser, record, roles }) => (
!record.owner_id || record.owner_id === currentUser.id
),
destroy: ({ currentUser, record, roles }) => (
roles.admin(currentUser) && record.owner_id === currentUser.id
),
},
}
userRolesSchema
Object with keys - role names and values - role condition functions
.
Role condition function
must return a boolean value of the condition result.
Role condition function params:
currentUser
- passed to SimpleRulesProvider
user.
const userRolesSchema = {
admin: (currentUser) => currentUser.role === 'admin',
client: (currentUser) => currentUser.role === 'client'
}
Hooks
useRules hook
The useRules
hook is used to connect with entity rule conditions checks by available in rulesSchema condition functions. Condition function parameter is entity instance.
Hook parameter is entity name from rulesSchema.
const rulesSchema = {
post: {
show: ({ currentUser, record }) => !record.owner_id || record.owner_id === currentUser.id,
},
}
...
function ExampleComponent({ post }) {
const postRules = useRules('post')
if (!postRules.show(post)) {
return 'Post is invisible!'
}
return post.content
}
usePermissions hook
The usePermissions
hook can be used for connecting entity rule condition with some UI block.
Hook return wrapper that renders children when connected rule condition check is true.
Hook parameter is entity name from rulesSchema.
Wrapper props is entity instance record
and rule name rule
.
const rulesSchema = {
post: {
show: ({ currentUser, record }) => !record.owner_id || record.owner_id === currentUser.id,
},
}
...
function ExampleComponent({ post }) {
const PostPermission = usePermissions('post')
return (
<PostPermission action="destroy" record={post}>
{ post.content }
</PostPermission>
)
}
License
MIT © gl-pv