Core Concepts

Models

The package ships two Eloquent-style models that extend BaseModel from @admicaa/netpress. They are fully queryable like any other NetPress model, and their tables and columns come from the configuration you set up in Configuration.

Role

import { Role } from '@admicaa/netpress-permissions';

Fillable

name — required, unique
description — optional display-only copy

Relations

permissions() — belongsToMany Permission via role_has_permissions
assignees(ModelClass) — morphedByMany subjects via model_has_roles

Methods

await role.getPermissions();
await role.givePermissionTo(permission);
await role.revokePermissionTo(permission);
await role.syncPermissions(permission1, permission2);
await role.hasPermissionTo('posts.publish');

Role.findByName('editor');
Role.findOrCreate('editor');

Permission

import { Permission } from '@admicaa/netpress-permissions';

Fillable

name — required, unique
description — optional display-only copy
group — optional grouping key for UI rendering (see Permission Groups)

Relations

roles() — belongsToMany Role via role_has_permissions
holders(ModelClass) — morphedByMany subjects via model_has_permissions

Methods

Permission.findByName('posts.publish');
Permission.findOrCreate('posts.publish', { group: 'posts' });

Permission.findByGroup('posts');  // Permission[] with group === 'posts'
Permission.groupedBy();           // { posts: [...], users: [...], ... }

Custom Models

Two ways to extend:

1. Subclass And Re-Register

import { Role as PackageRole } from '@admicaa/netpress-permissions';

export default class Role extends PackageRole {
  async getHumanLabel() {
    return this.description || this.name;
  }
}

Subclassing keeps connection, table, and fillable attributes inherited while giving you a place to hang domain logic.

2. Override The Table Name

You rarely need to subclass just to rename a table. Update config.tables or config.columns in your config/permissions.js instead — the default models read through the config on every query.

Primary Keys

Both models use id as the primary key by default. If your app uses uuid primary keys, set columns.id in config and also add an override to the models themselves:

export default class Role extends PackageRole {
  static primaryKey = 'uuid';
}

Permission resolution in entities.js calls ModelClass.primaryKey || 'id' so this flows through to resolveEntityIds.