{"_id":"@canxjs/dominion","name":"@canxjs/dominion","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@canxjs/dominion","version":"1.0.0","type":"module","description":"CanxJS Dominion - Advanced Roles and Permissions","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc"},"keywords":["canxjs","auth","permission","roles","rbac","spatie"],"author":{"name":"CanxJS Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/chandafa/canxjs.git","directory":"packages/dominion"},"publishConfig":{"access":"public"},"peerDependencies":{"canxjs":">=1.0.0"},"devDependencies":{"typescript":"^5.0.0","canxjs":"^1.6.1"},"_id":"@canxjs/dominion@1.0.0","bugs":{"url":"https://github.com/chandafa/canxjs/issues"},"homepage":"https://github.com/chandafa/canxjs#readme","_nodeVersion":"22.13.1","_npmVersion":"11.7.0","dist":{"integrity":"sha512-0JcO7+ucytgIT55ZddWb43xfYLi614X3Y3ckGuyqdPKhVvj/8H2Ml8QuvubeA3a4RxUyEzX4pWnXpYK6r8iF1A==","shasum":"bbdb95de34352b69072c756064ab26c945557eba","tarball":"https://registry.npmjs.org/@canxjs/dominion/-/dominion-1.0.0.tgz","fileCount":234,"unpackedSize":969744,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDHQHk/QqbOk1nygBVakdyJtr2SdhbIUBlj7ZiIoVnitgIgKnwlJea5oo8Pr2EP/RKAs3+12qH2eMy14WZBYVq1bT8="}]},"_npmUser":{"name":"chandafa","email":"chankirana722@gmail.com"},"directories":{},"maintainers":[{"name":"chandafa","email":"chankirana722@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dominion_1.0.0_1769930705825_0.1763604713906215"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-01T07:25:05.742Z","1.0.0":"2026-02-01T07:25:05.977Z","modified":"2026-02-01T07:25:06.180Z"},"maintainers":[{"name":"chandafa","email":"chankirana722@gmail.com"}],"description":"CanxJS Dominion - Advanced Roles and Permissions","homepage":"https://github.com/chandafa/canxjs#readme","keywords":["canxjs","auth","permission","roles","rbac","spatie"],"repository":{"type":"git","url":"git+https://github.com/chandafa/canxjs.git","directory":"packages/dominion"},"author":{"name":"CanxJS Team"},"bugs":{"url":"https://github.com/chandafa/canxjs/issues"},"license":"MIT","readme":"# @canxjs/dominion\r\n\r\n<p align=\"center\">\r\n  <strong>Advanced Roles and Permissions for CanxJS</strong>\r\n</p>\r\n\r\n<p align=\"center\">\r\n  A powerful role-based access control (RBAC) system with direct permissions support.\r\n  <br />\r\n  Inspired by Spatie Laravel Permission.\r\n</p>\r\n\r\n---\r\n\r\n## ✨ Features\r\n\r\n- 👥 **Role Management** - Assign multiple roles to users\r\n- 🔑 **Direct Permissions** - Grant permissions directly to users\r\n- 🎭 **Role Permissions** - Assign permissions to roles\r\n- 🔄 **Sync Operations** - Easily sync roles and permissions\r\n- 🛡️ **Guard Support** - Multiple authentication guards\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @canxjs/dominion\r\n# or\r\nbun add @canxjs/dominion\r\n```\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Register the Service Provider\r\n\r\n```typescript\r\n// src/providers.ts\r\nimport { DominionServiceProvider } from \"@canxjs/dominion\";\r\n\r\nexport const providers = [\r\n  // ... other providers\r\n  DominionServiceProvider,\r\n];\r\n```\r\n\r\n### 2. Run the Install Command\r\n\r\n```bash\r\nnode canx dominion:install\r\nnode canx migrate\r\n```\r\n\r\n### 3. Add Mixin to User Model\r\n\r\n```typescript\r\nimport { Model } from \"canxjs\";\r\nimport { HasRoles } from \"@canxjs/dominion\";\r\n\r\nclass User extends HasRoles(Model) {\r\n  static tableName = \"users\";\r\n\r\n  id!: number;\r\n  email!: string;\r\n  // ... other fields\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📖 Usage\r\n\r\n### Creating Roles & Permissions\r\n\r\n```typescript\r\nimport { Role, Permission } from \"@canxjs/dominion\";\r\n\r\n// Create permissions\r\nawait Permission.create({ name: \"create posts\", guard_name: \"web\" });\r\nawait Permission.create({ name: \"edit posts\", guard_name: \"web\" });\r\nawait Permission.create({ name: \"delete posts\", guard_name: \"web\" });\r\n\r\n// Create a role\r\nconst writerRole = await Role.create({ name: \"writer\", guard_name: \"web\" });\r\n\r\n// Assign permissions to role\r\nawait writerRole.permissions().attach([1, 2]); // attach by IDs\r\n```\r\n\r\n### Assigning Roles to Users\r\n\r\n```typescript\r\nconst user = await User.find(1);\r\n\r\n// Assign a single role\r\nawait user.assignRole(\"writer\");\r\n\r\n// Assign multiple roles\r\nawait user.assignRole(\"writer\", \"editor\");\r\n\r\n// Assign by Role instance\r\nconst adminRole = await Role.where(\"name\", \"admin\").first();\r\nawait user.assignRole(adminRole);\r\n```\r\n\r\n### Checking Roles\r\n\r\n```typescript\r\n// Check if user has a role\r\nif (await user.hasRole(\"writer\")) {\r\n  // User is a writer\r\n}\r\n\r\n// Get all user roles\r\nconst roles = await user.roles().get();\r\n```\r\n\r\n### Direct Permissions\r\n\r\n```typescript\r\n// Give permissions directly to user (bypassing roles)\r\nawait user.givePermissionTo(\"publish posts\");\r\n\r\n// Revoke a permission\r\nawait user.revokePermissionTo(\"publish posts\");\r\n\r\n// Get all direct permissions\r\nconst permissions = await user.permissions().get();\r\n```\r\n\r\n### Checking Permissions\r\n\r\n```typescript\r\n// Check permission (checks both direct AND role-based)\r\nif (await user.hasPermissionTo(\"edit posts\")) {\r\n  // User can edit posts\r\n}\r\n\r\n// This works with permission names or Permission instances\r\nconst editPerm = await Permission.where(\"name\", \"edit posts\").first();\r\nif (await user.hasPermissionTo(editPerm)) {\r\n  // User can edit posts\r\n}\r\n```\r\n\r\n### Syncing Roles\r\n\r\n```typescript\r\n// Replace all current roles with new ones\r\nawait user.syncRoles(\"admin\", \"manager\");\r\n\r\n// Remove a role\r\nawait user.removeRole(\"writer\");\r\n```\r\n\r\n---\r\n\r\n## 🔧 How It Works\r\n\r\n### Database Schema\r\n\r\nDominion creates the following tables:\r\n\r\n**`roles`**\r\n| Column | Type | Description |\r\n|--------|------|-------------|\r\n| `id` | integer | Primary key |\r\n| `name` | string | Role name (e.g., \"admin\") |\r\n| `guard_name` | string | Auth guard (default: \"web\") |\r\n\r\n**`permissions`**\r\n| Column | Type | Description |\r\n|--------|------|-------------|\r\n| `id` | integer | Primary key |\r\n| `name` | string | Permission name (e.g., \"edit posts\") |\r\n| `guard_name` | string | Auth guard (default: \"web\") |\r\n\r\n**`role_has_permissions`** (pivot)\r\n| Column | Type | Description |\r\n|--------|------|-------------|\r\n| `role_id` | integer | Foreign key to roles |\r\n| `permission_id` | integer | Foreign key to permissions |\r\n\r\n**`model_has_roles`** (pivot)\r\n| Column | Type | Description |\r\n|--------|------|-------------|\r\n| `role_id` | integer | Foreign key to roles |\r\n| `model_type` | string | Model class name |\r\n| `model_id` | integer | Model primary key |\r\n\r\n**`model_has_permissions`** (pivot)\r\n| Column | Type | Description |\r\n|--------|------|-------------|\r\n| `permission_id` | integer | Foreign key to permissions |\r\n| `model_type` | string | Model class name |\r\n| `model_id` | integer | Model primary key |\r\n\r\n### Permission Resolution\r\n\r\nWhen checking `hasPermissionTo()`:\r\n\r\n1. First, check **direct permissions** on the user\r\n2. Then, check permissions through **each assigned role**\r\n3. Returns `true` if found in either\r\n\r\n```\r\nUser\r\n├── Direct Permissions (model_has_permissions)\r\n│   └── \"publish posts\"\r\n└── Roles (model_has_roles)\r\n    ├── \"writer\" → Permissions: [\"create posts\", \"edit posts\"]\r\n    └── \"editor\" → Permissions: [\"edit posts\", \"delete posts\"]\r\n```\r\n\r\n---\r\n\r\n## 📚 API Reference\r\n\r\n### `HasRoles` Mixin\r\n\r\n| Method                         | Description                         |\r\n| ------------------------------ | ----------------------------------- |\r\n| `assignRole(...roles)`         | Assign one or more roles            |\r\n| `removeRole(...roles)`         | Remove one or more roles            |\r\n| `syncRoles(...roles)`          | Replace all roles                   |\r\n| `hasRole(role)`                | Check if user has a role            |\r\n| `roles()`                      | Get roles relationship              |\r\n| `givePermissionTo(...perms)`   | Grant direct permissions            |\r\n| `revokePermissionTo(...perms)` | Revoke direct permissions           |\r\n| `hasPermissionTo(perm)`        | Check if user has permission        |\r\n| `permissions()`                | Get direct permissions relationship |\r\n\r\n### `Role` Model\r\n\r\n| Method          | Description                         |\r\n| --------------- | ----------------------------------- |\r\n| `permissions()` | Get role's permissions relationship |\r\n\r\n### `Permission` Model\r\n\r\nStandard Eloquent model with `name` and `guard_name` fields.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT © CanxJS Team\r\n","readmeFilename":"README.md","_rev":"1-d283b0e48d8fa5f59737eaa3fe6e5d12"}