@trap_stevo/rolestack/README.md

Unify access logic across your applications with a single, elegant stack for roles. Define, query, and evolve roles on the fly.

# 🧩 @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

```bash
npm install @trap_stevo/rolestack
```

---


## 🛠️ Usage

### ✨ Basic Setup

```js
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

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

// Set a nested field
rs.setField("Editor", "profile.email", "editor@example.com");

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

---


### 🔎 Queries

```js
// 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

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

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

---


## 📜 License

See License in [LICENSE.md](./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.