🧩 @trap_stevo/rolestack

Seamless dynamic role and permission management, unifying access with precision and speed. Unify access logic across your applications with a single, elegant stack for roles. Define, query, and evolve roles on the fly.

🚀 Features

• 🔑 Simple API Surface – Register, update, remove, and query roles with a few lines of code
• 🧭 Nested Field Access – Get/set deeply nested properties with dot-paths ("meta.tier")
• ⚡ Upserts & Patches – Create or update roles dynamically with merge/patch semantics
• 🧩 Flexible Queries – Find roles by equality, deep comparison, or custom predicates
• 🔄 Import/Export – Serialize roles to JSON and hydrate back instantly
• 🛡 Silent Skips – Empty or invalid names are safely ignored, never crash your app
• 🧪 Validator Hook – Optionally enforce schema or invariants before persisting

🧠 Use Cases

• Application user role & permission systems
• Feature flagging by role tier or group
• Multi-tenant SaaS role definitions
• Game server character roles, classes, or abilities
• CMS/editorial workflows with granular control
• Any app that needs hierarchies, access control, or flexible identity metadata

⚙️ System Requirements

| Requirement | Version | | ----------- | --------------------- | | Node.js | ≥ 18.x | | npm | ≥ 9.x (recommended) | | OS | Windows, macOS, Linux |

🔍 API Specifications

🔧 Methods

| Method | Signature | Returns | Description | | ----------------------------- | ------------------------------------------------------------ | --------------------------------------- | ------------------------------------------------------------------- | | register(name, data) | (name: string, data: any) | object \| null | Registers a new role, errors if already exists (skips empty names). | | set(name, data) | (name: string, data: any) | object \| null | Sets/replaces a role, overwriting if present. | | upsert(name, patch, opts?) | (name: string, patch: object \| fn, opts?: { merge?: fn }) | object \| null | Creates or updates a role. Supports merge or function patching. | | get(name) | (name: string) | object \| null | Retrieves a role or null if not found. | | remove(name) | (name: string) | void | Removes a role. | | contains(name) | (name: string) | boolean | Checks if a role exists. | | list() | () | Array<{ name: string, data: object }> | Returns all roles. | | toJSON() | () | Array<{ name: string, data: object }> | Serializes all roles to JSON. | | fromJSON(data, opts?) | (data: RoleData[], opts?) | RoleStack | Creates a new RoleStack from JSON. | | getField(name, path) | (name: string, path: string) | any | Reads a nested property with dot-notation. | | setField(name, path, value) | (name: string, path: string, value: any) | object \| null | Updates a nested property. | | query(path, value, opts?) | (path: string, value: any, opts?: { equals?: fn }) | Array<{ name, data }> | Finds roles where a field matches. | | queryWhere(path, predicate) | (path: string, fn) | Array<{ name, data }> | Filters roles by custom logic. |

📦 Installation

npm install @trap_stevo/rolestack

🛠️ Usage

✨ Basic Setup

const { RoleStack } = require("@trap_stevo/rolestack");

const rs = new RoleStack();

// Register roles
rs.register("Admin", { permissions: ["*"], meta: { tier: 3 } });
rs.register("Editor", { permissions: ["write"], meta: { tier: 2 } });

// Upsert (merge)
rs.upsert("Editor", { meta: { dept: "Content" } });

// Get role
console.log(rs.get("Admin"));
// → { permissions: [ '*' ], meta: { tier: 3 } }

🎯 Nested Fields

// Get a nested field
console.log(rs.getField("Admin", "meta.tier")); 
// → 3

// Set a nested field
rs.setField("Editor", "profile.email", "[email protected]");

console.log(rs.get("Editor"));
/*
{
  permissions: [ 'write' ],
  meta: { tier: 2, dept: 'Content' },
  profile: { email: '[email protected]' }
}
*/

🔎 Queries

// Exact match query
console.log(rs.query("meta.tier", 2));
/*
[
  { name: 'editor', data: { permissions: [...], meta: { tier: 2, dept: 'Content' } } }
]
*/

// Predicate query
console.log(rs.queryWhere("permissions", v => Array.isArray(v) && v.includes("*")));
/*
[
  { name: 'admin', data: { permissions: [ '*' ], meta: { tier: 3 } } }
]
*/

📦 Import / Export

const snapshot = rs.toJSON();
console.log(snapshot);

const restored = RoleStack.fromJSON(snapshot);
console.log(restored.list());

📜 License

See License in LICENSE.md

🧩 RoleStack — Build Seamless Role Management Into Your Stack. From simple permissions to complex hierarchies, RoleStack keeps your access logic elegant, flexible, and future-proof.