Instance
Learn how to create a new Permix instance
Overview
Instance is the main entry point for Permix that will check permissions in every returned method. To create an instance, you need to use the createPermix function.
TypeScript
Permix is built with TypeScript, providing type safety and validation. Using TypeScript enables autocompletion and compile-time checks for your permission definitions.
import { } from 'permix'
const = <{
: {
: 'create' | 'edit'
}
}>()Generic type
Permix instance accepts a generic type to define permissions.
action
Union type of all actions you want to check on the entity.
import { } from 'permix'
const = <{
: {
: 'create' | 'edit'
}
}>()dataType
Not required, but recommended.
To define a type of your entities, you can pass the dataType property to a generic type. This is useful if you want to check permissions on a specific entity otherwise the type will be unknown.
import { } from 'permix'
interface Post {
: string
: string
: string
}
const = <{
: {
: Post
: 'create' | 'edit'
}
}>()
.({
: {
: true,
: post => ?. === 'John Doe' }
})
const : Post = {
: '1',
: 'John Doe',
: 'Hello World'
}
const = .('post', 'edit') // false
const = .('post', 'edit', ) // truedataRequired
Not required, defaults to false.
By default, when you define a dataType, the data parameter in permission checks is optional. You can make it required by setting dataRequired: true. This ensures that permission checks for that entity must always include the data parameter.
import { } from 'permix'
interface Post {
: string
: string
: string
}
const = <{
: {
: Post
: true
: 'create' | 'edit'
}
}>()
.({
: {
: true,
: post => . === 'John Doe' }
})
const : Post = {
: '1',
: 'John Doe',
: 'Hello World'
}
const = .check('post', 'create')const = .('post', 'edit', ) // ✅ ValidWhen dataRequired is true, TypeScript will enforce that you must pass the data parameter when checking permissions for that entity. This is useful when your permission logic always depends on the entity data and you want to prevent accidental calls without the required data.
PermixDefinition
You can use PermixDefinition type to define your permissions separately from the instance.
import type { , } from 'permix'
import { } from 'permix'
type = <{
: {
: 'create' | 'edit'
}
}>
async function (): <<>> {
// get user or something like that
return {
: {
: true,
: false
}
}
}
const = <>()
.(await ())Return type
Each Permix instance provides a list of methods to manage and check permissions. These methods are documented in detail on their separate pages.
import { } from 'permix'
const = ()
.- check
- checkAsync
- dehydrate
- hook
- hookOnce
- hydrate
- isReady
- isReadyAsync
- setup
- template
JavaScript
Not using TypeScript? Permix works perfectly fine even with plain JavaScript.
const permix = createPermix()Initial Rules
You can provide initial rules when creating a Permix instance. This allows you to set up permissions immediately without calling setup separately.
import { } from 'permix'
const = <{
: {
: 'create' | 'edit'
}
}>({
: {
: true,
: false
}
})
// Permissions are immediately available
.(.('post', 'create')) // true
.(.()) // trueThis is equivalent to:
import { } from 'permix'
const = <{
: {
: 'create' | 'edit'
}
}>()
.({
: {
: true,
: false
}
})Initial rules are useful when you have permissions that are known at initialization time and don't need to be loaded asynchronously.
You still should pass generic type to createPermix even if you provide initial rules. Otherwise, Permix will not be able to validate your permissions.