Features

Migrations

NetPress Permissions ships a single migration helper that creates the five tables the package needs. The published migration delegates to the helper so you can customise columns without forking the package.

The Helper

import {
  createPermissionTables,
  dropPermissionTables,
} from '@admicaa/netpress-permissions';

Both functions accept either a Knex instance or a NetPress migration schema context. Under the hood they normalize the schema operations into the same hasTable, createTable, dropTableIfExists interface, so the migration runs identically on SQL or Mongo connections.

The Published Migration

import {
  createPermissionTables,
  dropPermissionTables,
} from '@admicaa/netpress-permissions';

const permissionsConfig = {
  driver: 'mongo',
  connection: 'mongo',
  pivotConnection: 'mongo',
};

export async function up(schema) {
  await createPermissionTables(schema.connection('mongo'), permissionsConfig);
}

export async function down(schema) {
  await dropPermissionTables(schema.connection('mongo'), permissionsConfig);
}

The up function is idempotent — existing tables are skipped rather than rebuilt. Use down to tear the schema back down in tests or rollbacks.

Tables Created

roles — id, name (unique), description
permissions — id, name (unique), group (nullable, indexed), description
role_has_permissions — roleId + permissionId unique composite, indexed both ways
model_has_roles — modelType + modelId + roleId unique, indexed
model_has_permissions — modelType + modelId + permissionId unique, indexed

The column names come from config.columns. The polymorphic type column is built from config.morphName (default 'model'), yielding modelType.

Overriding Column Names

createPermissionTables(target, overrides) accepts an overrides object:

await createPermissionTables(knex, {
  tables: { roles: 'acl_roles' },
  columns: { rolePivot: 'role_id' },
});

The helper merges overrides on top of the current runtime config — perfect for tests that create an isolated schema.

Running Migrations

npm run migrate           # applies pending migrations
npm run migrate -- --step # one migration at a time
npm run migrate -- :rollback

The published permissions migration participates in your app's normal migration flow. Running it twice is safe because of the hasTable checks.

Seeding Default Roles

Create a seeder that inserts a baseline so new environments bootstrap with useful data:

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

export default async function seedRoles() {
  const admin = await Role.findOrCreate('admin', { description: 'Full access' });
  const editor = await Role.findOrCreate('editor', { description: 'Content access' });

  const publish = await Permission.findOrCreate('posts.publish', { group: 'posts' });
  const archive = await Permission.findOrCreate('posts.archive', { group: 'posts' });

  await admin.syncPermissions(publish, archive);
  await editor.syncPermissions(publish);
}

Run it with npm run seed after your migrations.