role-permission-engine 1.0.0

package/dist/utils.esm.js

@@ -0,0 +1,385 @@
+/**
+ * @fileoverview Core permission-checking utility functions.
+ *
+ * These are pure, framework-agnostic functions that form the heart of
+ * the role-permission-engine. They have zero side effects and can be
+ * used independently of any React component.
+ *
+ * @module utils/checkPermission
+ */
+
+// ─── Type Definitions ────────────────────────────────────────────────────────
+
+/**
+ * The logical operator used when evaluating multiple roles or permissions.
+ *
+ * - `"any"` – The user must satisfy **at least one** of the required items (OR logic).
+ * - `"all"` – The user must satisfy **every** required item (AND logic).
+ *
+ * @typedef {"any" | "all"} LogicOperator
+ */
+
+/**
+ * A single role string, e.g. `"admin"`, `"editor"`, `"viewer"`.
+ *
+ * @typedef {string} Role
+ */
+
+/**
+ * A single permission string, typically in `"action:resource"` format,
+ * e.g. `"read:users"`, `"write:posts"`, `"delete:*"`.
+ *
+ * @typedef {string} Permission
+ */
+
+/**
+ * The result returned by permission-check functions.
+ *
+ * @typedef {Object} PermissionResult
+ * @property {boolean} allowed  - Whether the user is allowed access.
+ * @property {string}  reason   - A human-readable explanation of the result.
+ */
+
+// ─── Role Checking ────────────────────────────────────────────────────────────
+
+/**
+ * Checks whether a user's roles satisfy the required roles using
+ * the specified logic operator.
+ *
+ * This is a **pure utility** — it accepts any string as a role.
+ * You define what roles mean in your own application. Examples:
+ * `"admin"`, `"manager"`, `"superuser"`, `"read-only"`, `"tenant-owner"`, etc.
+ *
+ * @param {string[]} userRoles
+ *   Array of role strings currently assigned to the user.
+ *   - Comparison is **case-insensitive** and **trims whitespace**.
+ *   - Example: `['Admin', ' editor ']` is treated as `['admin', 'editor']`.
+ *   - Pass an empty array `[]` when the user has no roles.
+ *
+ * @param {string[]} requiredRoles
+ *   Array of role strings required to pass this check.
+ *   - If this array is **empty** (`[]`) or not provided, the check
+ *     is skipped and `allowed: true` is returned immediately.
+ *   - Example: `['admin', 'superuser']`
+ *
+ * @param {"any" | "all"} [logic="any"]
+ *   Controls how multiple `requiredRoles` are evaluated.
+ *
+ *   | Value   | Alias | Behaviour                                           | Example                                      |
+ *   |---------|-------|-----------------------------------------------------|----------------------------------------------|
+ *   | `"any"` | OR    | User needs **at least one** of the required roles   | `required: ['admin','editor']` → admin **or** editor is enough |
+ *   | `"all"` | AND   | User needs **every single** required role           | `required: ['admin','editor']` → must have **both** |
+ *
+ *   **Default:** `"any"` (OR logic).
+ *
+ *   ```js
+ *   // Default — no third argument needed for OR logic
+ *   hasRole(['editor'], ['admin', 'editor']);
+ *   // same as:
+ *   hasRole(['editor'], ['admin', 'editor'], 'any');
+ *   ```
+ *
+ * @returns {PermissionResult}
+ *   `{ allowed: boolean, reason: string }`
+ *
+ * @example <caption>OR logic (default) — user has at least one required role</caption>
+ * hasRole(['editor'], ['admin', 'editor']);
+ * // => { allowed: true, reason: 'User has at least one required role.' }
+ *
+ * @example <caption>OR logic — user has none of the required roles</caption>
+ * hasRole(['viewer'], ['admin', 'editor'], 'any');
+ * // => { allowed: false, reason: 'User does not have any of the required roles: admin, editor' }
+ *
+ * @example <caption>AND logic — user must have every required role</caption>
+ * hasRole(['admin', 'editor'], ['admin', 'editor'], 'all');
+ * // => { allowed: true, reason: 'User has all required roles.' }
+ *
+ * @example <caption>AND logic — user is missing one role</caption>
+ * hasRole(['editor'], ['admin', 'editor'], 'all');
+ * // => { allowed: false, reason: 'User is missing required roles: admin' }
+ *
+ * @example <caption>Empty required roles — always allowed</caption>
+ * hasRole([], []);
+ * // => { allowed: true, reason: 'No roles required — access granted.' }
+ */
+function hasRole(userRoles, requiredRoles, logic = "any") {
+  if (!Array.isArray(requiredRoles) || requiredRoles.length === 0) {
+    return {
+      allowed: true,
+      reason: "No roles required — access granted."
+    };
+  }
+  if (!Array.isArray(userRoles) || userRoles.length === 0) {
+    return {
+      allowed: false,
+      reason: "User has no roles assigned."
+    };
+  }
+  const normalizedUser = userRoles.map(r => r.toLowerCase().trim());
+  const normalizedRequired = requiredRoles.map(r => r.toLowerCase().trim());
+  if (logic === "all") {
+    const missing = normalizedRequired.filter(r => !normalizedUser.includes(r));
+    if (missing.length > 0) {
+      return {
+        allowed: false,
+        reason: `User is missing required roles: ${missing.join(", ")}`
+      };
+    }
+    return {
+      allowed: true,
+      reason: "User has all required roles."
+    };
+  }
+
+  // Default: "any" (OR logic)
+  const matched = normalizedRequired.filter(r => normalizedUser.includes(r));
+  if (matched.length === 0) {
+    return {
+      allowed: false,
+      reason: `User does not have any of the required roles: ${normalizedRequired.join(", ")}`
+    };
+  }
+  return {
+    allowed: true,
+    reason: "User has at least one required role."
+  };
+}
+
+// ─── Permission Checking ──────────────────────────────────────────────────────
+
+/**
+ * Checks whether a user's permissions satisfy the required permissions
+ * using the specified logic operator. Supports wildcard `"*"` permissions.
+ *
+ * This is a **pure utility** — it accepts any string as a permission.
+ * You define what permissions mean in your own application. A common
+ * convention is `"action:resource"` format (e.g. `"read:invoices"`,
+ * `"export:reports"`, `"delete:accounts"`), but any string works.
+ *
+ * **Wildcard rules:**
+ * | User permission | Matches                                      |
+ * |-----------------|----------------------------------------------|
+ * | `"*"`           | Every possible permission — full super-access |
+ * | `"read:*"`      | Any permission starting with `"read:"`        |
+ * | `"write:posts"` | Only `"write:posts"` exactly                 |
+ *
+ * @param {string[]} userPermissions
+ *   Array of permission strings the user currently holds.
+ *   - Comparison is **case-insensitive** and **trims whitespace**.
+ *   - Pass `['*']` to grant superuser access to all checks.
+ *   - Pass an empty array `[]` when the user has no permissions.
+ *
+ * @param {string[]} requiredPermissions
+ *   Array of permission strings required to pass this check.
+ *   - If this array is **empty** (`[]`) or not provided, the check
+ *     is skipped and `allowed: true` is returned immediately.
+ *
+ * @param {"any" | "all"} [logic="any"]
+ *   Controls how multiple `requiredPermissions` are evaluated.
+ *
+ *   | Value   | Alias | Behaviour                                                 | Example                                              |
+ *   |---------|-------|-----------------------------------------------------------|------------------------------------------------------|
+ *   | `"any"` | OR    | User needs **at least one** of the required permissions   | `required: ['read:x','write:x']` → read **or** write is enough |
+ *   | `"all"` | AND   | User needs **every single** required permission           | `required: ['read:x','write:x']` → must have **both** |
+ *
+ *   **Default:** `"any"` (OR logic).
+ *
+ *   ```js
+ *   // Default — OR logic, no third argument needed
+ *   hasPermission(['read:reports'], ['read:reports', 'write:reports']);
+ *   // same as:
+ *   hasPermission(['read:reports'], ['read:reports', 'write:reports'], 'any');
+ *   ```
+ *
+ * @returns {PermissionResult}
+ *   `{ allowed: boolean, reason: string }`
+ *
+ * @example <caption>OR logic (default) — user has one of the required permissions</caption>
+ * hasPermission(['read:invoices'], ['read:invoices', 'write:invoices']);
+ * // => { allowed: true, reason: 'User has at least one required permission.' }
+ *
+ * @example <caption>OR logic — user has none</caption>
+ * hasPermission(['read:posts'], ['write:posts', 'delete:posts'], 'any');
+ * // => { allowed: false, reason: 'User does not have any of the required permissions: ...' }
+ *
+ * @example <caption>AND logic — must have all required permissions</caption>
+ * hasPermission(['read:users', 'write:users'], ['read:users', 'write:users'], 'all');
+ * // => { allowed: true, reason: 'User has all required permissions.' }
+ *
+ * @example <caption>Full wildcard — grants everything</caption>
+ * hasPermission(['*'], ['read:users', 'delete:posts'], 'all');
+ * // => { allowed: true, reason: 'User has wildcard permission (*) — full access granted.' }
+ *
+ * @example <caption>Namespace wildcard — "read:*" satisfies any "read:" permission</caption>
+ * hasPermission(['read:*'], ['read:invoices', 'read:reports'], 'all');
+ * // => { allowed: true, reason: 'User has all required permissions.' }
+ */
+function hasPermission(userPermissions, requiredPermissions, logic = "any") {
+  if (!Array.isArray(requiredPermissions) || requiredPermissions.length === 0) {
+    return {
+      allowed: true,
+      reason: 'No permissions required — access granted.'
+    };
+  }
+  if (!Array.isArray(userPermissions) || userPermissions.length === 0) {
+    return {
+      allowed: false,
+      reason: 'User has no permissions assigned.'
+    };
+  }
+  const normalizedUser = userPermissions.map(p => p.toLowerCase().trim());
+  const normalizedRequired = requiredPermissions.map(p => p.toLowerCase().trim());
+
+  // Full wildcard check
+  if (normalizedUser.includes("*")) {
+    return {
+      allowed: true,
+      reason: "User has wildcard permission (*) — full access granted."
+    };
+  }
+
+  /**
+   * Checks if a single required permission is satisfied by the user's permission set,
+   * including namespace wildcard matching (e.g. "read:*" matches "read:users").
+   *
+   * @param {string} required - The required permission to satisfy.
+   * @returns {boolean} Whether the user satisfies this specific permission.
+   */
+  function isSatisfied(required) {
+    if (normalizedUser.includes(required)) return true;
+
+    // Namespace wildcard: "read:*" should satisfy "read:users"
+    const [requiredNamespace] = required.split(":");
+    return normalizedUser.includes(`${requiredNamespace}:*`);
+  }
+  if (logic === "all") {
+    const missing = normalizedRequired.filter(p => !isSatisfied(p));
+    if (missing.length > 0) {
+      return {
+        allowed: false,
+        reason: `User is missing required permissions: ${missing.join(", ")}`
+      };
+    }
+    return {
+      allowed: true,
+      reason: "User has all required permissions."
+    };
+  }
+
+  // Default: "any" (OR logic)
+  const matched = normalizedRequired.filter(p => isSatisfied(p));
+  if (matched.length === 0) {
+    return {
+      allowed: false,
+      reason: `User does not have any of the required permissions: ${normalizedRequired.join(", ")}`
+    };
+  }
+  return {
+    allowed: true,
+    reason: "User has at least one required permission."
+  };
+}
+
+// ─── Combined Check ───────────────────────────────────────────────────────────
+
+/**
+ * Performs a **combined** role AND permission check in a single call.
+ *
+ * Both the role check and the permission check must independently pass
+ * for `allowed` to be `true`. If a constraint array is empty or not
+ * provided, that constraint is automatically satisfied (open access).
+ *
+ * @param {Object} options
+ *
+ * @param {string[]} [options.userRoles=[]]
+ *   The roles currently held by the user. Any strings are accepted;
+ *   you define what roles mean in your app.
+ *
+ * @param {string[]} [options.userPermissions=[]]
+ *   The permissions currently held by the user. Supports wildcards:
+ *   `"*"` (all access) and `"namespace:*"` (all in namespace).
+ *
+ * @param {string[]} [options.requiredRoles=[]]
+ *   Roles the user must have to pass the role check.
+ *   Pass `[]` (default) to skip the role check entirely.
+ *
+ * @param {string[]} [options.requiredPermissions=[]]
+ *   Permissions the user must have to pass the permission check.
+ *   Pass `[]` (default) to skip the permission check entirely.
+ *
+ * @param {"any" | "all"} [options.roleLogic="any"]
+ *   Controls how `requiredRoles` are evaluated.
+ *
+ *   | Value   | Behaviour                                        | Default? |
+ *   |---------|--------------------------------------------------|----------|
+ *   | `"any"` | User needs **at least one** required role (OR)   | ✅ Yes   |
+ *   | `"all"` | User needs **every** required role (AND)         | No       |
+ *
+ *   ```js
+ *   // 'any' is the default — no need to specify it explicitly for OR logic
+ *   checkAccess({ requiredRoles: ['admin', 'editor'], roleLogic: 'any' });
+ *   ```
+ *
+ * @param {"any" | "all"} [options.permissionLogic="any"]
+ *   Controls how `requiredPermissions` are evaluated.
+ *
+ *   | Value   | Behaviour                                             | Default? |
+ *   |---------|-------------------------------------------------------|----------|
+ *   | `"any"` | User needs **at least one** required permission (OR)  | ✅ Yes   |
+ *   | `"all"` | User needs **every** required permission (AND)        | No       |
+ *
+ *   ```js
+ *   // Require the user to have ALL listed permissions (AND logic)
+ *   checkAccess({
+ *     requiredPermissions: ['read:report', 'export:report'],
+ *     permissionLogic: 'all',
+ *   });
+ *   ```
+ *
+ * @returns {PermissionResult}
+ *   `{ allowed: boolean, reason: string }` — `allowed` is `true` only
+ *   when **both** role and permission checks pass.
+ *
+ * @example <caption>Combined check — OR role logic + OR permission logic (both defaults)</caption>
+ * checkAccess({
+ *   userRoles: ['editor'],
+ *   userPermissions: ['write:posts'],
+ *   requiredRoles: ['editor', 'admin'],      // editor OR admin
+ *   requiredPermissions: ['write:posts'],    // write:posts required
+ * });
+ * // => { allowed: true, reason: 'Access granted.' }
+ *
+ * @example <caption>AND logic for permissions — user must have ALL listed permissions</caption>
+ * checkAccess({
+ *   userRoles: ['manager'],
+ *   userPermissions: ['approve:leaves'],
+ *   requiredRoles: ['manager'],
+ *   requiredPermissions: ['approve:leaves', 'view:team'],
+ *   permissionLogic: 'all',   // must have BOTH permissions
+ * });
+ * // => { allowed: false, reason: 'User is missing required permissions: view:team' }
+ *
+ * @example <caption>No constraints — always allowed</caption>
+ * checkAccess({ userRoles: ['guest'], userPermissions: [] });
+ * // => { allowed: true, reason: 'Access granted.' }
+ */
+function checkAccess({
+  userRoles = [],
+  userPermissions = [],
+  requiredRoles = [],
+  requiredPermissions = [],
+  roleLogic = "any",
+  permissionLogic = "any"
+}) {
+  const roleResult = hasRole(userRoles, requiredRoles, roleLogic);
+  if (!roleResult.allowed) return roleResult;
+  const permResult = hasPermission(userPermissions, requiredPermissions, permissionLogic);
+  if (!permResult.allowed) return permResult;
+  return {
+    allowed: true,
+    reason: "Access granted."
+  };
+}
+
+export { checkAccess, hasPermission, hasRole };
+//# sourceMappingURL=utils.esm.js.map

package/dist/utils.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.esm.js","sources":["../src/utils/checkPermission.js"],"sourcesContent":["/**\n * @fileoverview Core permission-checking utility functions.\n *\n * These are pure, framework-agnostic functions that form the heart of\n * the role-permission-engine. They have zero side effects and can be\n * used independently of any React component.\n *\n * @module utils/checkPermission\n */\n\n// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * The logical operator used when evaluating multiple roles or permissions.\n *\n * - `\"any\"` – The user must satisfy **at least one** of the required items (OR logic).\n * - `\"all\"` – The user must satisfy **every** required item (AND logic).\n *\n * @typedef {\"any\" | \"all\"} LogicOperator\n */\n\n/**\n * A single role string, e.g. `\"admin\"`, `\"editor\"`, `\"viewer\"`.\n *\n * @typedef {string} Role\n */\n\n/**\n * A single permission string, typically in `\"action:resource\"` format,\n * e.g. `\"read:users\"`, `\"write:posts\"`, `\"delete:*\"`.\n *\n * @typedef {string} Permission\n */\n\n/**\n * The result returned by permission-check functions.\n *\n * @typedef {Object} PermissionResult\n * @property {boolean} allowed  - Whether the user is allowed access.\n * @property {string}  reason   - A human-readable explanation of the result.\n */\n\n// ─── Role Checking ────────────────────────────────────────────────────────────\n\n/**\n * Checks whether a user's roles satisfy the required roles using\n * the specified logic operator.\n *\n * This is a **pure utility** — it accepts any string as a role.\n * You define what roles mean in your own application. Examples:\n * `\"admin\"`, `\"manager\"`, `\"superuser\"`, `\"read-only\"`, `\"tenant-owner\"`, etc.\n *\n * @param {string[]} userRoles\n *   Array of role strings currently assigned to the user.\n *   - Comparison is **case-insensitive** and **trims whitespace**.\n *   - Example: `['Admin', ' editor ']` is treated as `['admin', 'editor']`.\n *   - Pass an empty array `[]` when the user has no roles.\n *\n * @param {string[]} requiredRoles\n *   Array of role strings required to pass this check.\n *   - If this array is **empty** (`[]`) or not provided, the check\n *     is skipped and `allowed: true` is returned immediately.\n *   - Example: `['admin', 'superuser']`\n *\n * @param {\"any\" | \"all\"} [logic=\"any\"]\n *   Controls how multiple `requiredRoles` are evaluated.\n *\n *   | Value   | Alias | Behaviour                                           | Example                                      |\n *   |---------|-------|-----------------------------------------------------|----------------------------------------------|\n *   | `\"any\"` | OR    | User needs **at least one** of the required roles   | `required: ['admin','editor']` → admin **or** editor is enough |\n *   | `\"all\"` | AND   | User needs **every single** required role           | `required: ['admin','editor']` → must have **both** |\n *\n *   **Default:** `\"any\"` (OR logic).\n *\n *   ```js\n *   // Default — no third argument needed for OR logic\n *   hasRole(['editor'], ['admin', 'editor']);\n *   // same as:\n *   hasRole(['editor'], ['admin', 'editor'], 'any');\n *   ```\n *\n * @returns {PermissionResult}\n *   `{ allowed: boolean, reason: string }`\n *\n * @example <caption>OR logic (default) — user has at least one required role</caption>\n * hasRole(['editor'], ['admin', 'editor']);\n * // => { allowed: true, reason: 'User has at least one required role.' }\n *\n * @example <caption>OR logic — user has none of the required roles</caption>\n * hasRole(['viewer'], ['admin', 'editor'], 'any');\n * // => { allowed: false, reason: 'User does not have any of the required roles: admin, editor' }\n *\n * @example <caption>AND logic — user must have every required role</caption>\n * hasRole(['admin', 'editor'], ['admin', 'editor'], 'all');\n * // => { allowed: true, reason: 'User has all required roles.' }\n *\n * @example <caption>AND logic — user is missing one role</caption>\n * hasRole(['editor'], ['admin', 'editor'], 'all');\n * // => { allowed: false, reason: 'User is missing required roles: admin' }\n *\n * @example <caption>Empty required roles — always allowed</caption>\n * hasRole([], []);\n * // => { allowed: true, reason: 'No roles required — access granted.' }\n */\nexport function hasRole(userRoles, requiredRoles, logic = \"any\") {\n  if (!Array.isArray(requiredRoles) || requiredRoles.length === 0) {\n    return { allowed: true, reason: \"No roles required — access granted.\" };\n  }\n\n  if (!Array.isArray(userRoles) || userRoles.length === 0) {\n    return { allowed: false, reason: \"User has no roles assigned.\" };\n  }\n\n  const normalizedUser = userRoles.map((r) => r.toLowerCase().trim());\n  const normalizedRequired = requiredRoles.map((r) => r.toLowerCase().trim());\n\n  if (logic === \"all\") {\n    const missing = normalizedRequired.filter(\n      (r) => !normalizedUser.includes(r),\n    );\n    if (missing.length > 0) {\n      return {\n        allowed: false,\n        reason: `User is missing required roles: ${missing.join(\", \")}`,\n      };\n    }\n    return { allowed: true, reason: \"User has all required roles.\" };\n  }\n\n  // Default: \"any\" (OR logic)\n  const matched = normalizedRequired.filter((r) => normalizedUser.includes(r));\n  if (matched.length === 0) {\n    return {\n      allowed: false,\n      reason: `User does not have any of the required roles: ${normalizedRequired.join(\", \")}`,\n    };\n  }\n  return { allowed: true, reason: \"User has at least one required role.\" };\n}\n\n// ─── Permission Checking ──────────────────────────────────────────────────────\n\n/**\n * Checks whether a user's permissions satisfy the required permissions\n * using the specified logic operator. Supports wildcard `\"*\"` permissions.\n *\n * This is a **pure utility** — it accepts any string as a permission.\n * You define what permissions mean in your own application. A common\n * convention is `\"action:resource\"` format (e.g. `\"read:invoices\"`,\n * `\"export:reports\"`, `\"delete:accounts\"`), but any string works.\n *\n * **Wildcard rules:**\n * | User permission | Matches                                      |\n * |-----------------|----------------------------------------------|\n * | `\"*\"`           | Every possible permission — full super-access |\n * | `\"read:*\"`      | Any permission starting with `\"read:\"`        |\n * | `\"write:posts\"` | Only `\"write:posts\"` exactly                 |\n *\n * @param {string[]} userPermissions\n *   Array of permission strings the user currently holds.\n *   - Comparison is **case-insensitive** and **trims whitespace**.\n *   - Pass `['*']` to grant superuser access to all checks.\n *   - Pass an empty array `[]` when the user has no permissions.\n *\n * @param {string[]} requiredPermissions\n *   Array of permission strings required to pass this check.\n *   - If this array is **empty** (`[]`) or not provided, the check\n *     is skipped and `allowed: true` is returned immediately.\n *\n * @param {\"any\" | \"all\"} [logic=\"any\"]\n *   Controls how multiple `requiredPermissions` are evaluated.\n *\n *   | Value   | Alias | Behaviour                                                 | Example                                              |\n *   |---------|-------|-----------------------------------------------------------|------------------------------------------------------|\n *   | `\"any\"` | OR    | User needs **at least one** of the required permissions   | `required: ['read:x','write:x']` → read **or** write is enough |\n *   | `\"all\"` | AND   | User needs **every single** required permission           | `required: ['read:x','write:x']` → must have **both** |\n *\n *   **Default:** `\"any\"` (OR logic).\n *\n *   ```js\n *   // Default — OR logic, no third argument needed\n *   hasPermission(['read:reports'], ['read:reports', 'write:reports']);\n *   // same as:\n *   hasPermission(['read:reports'], ['read:reports', 'write:reports'], 'any');\n *   ```\n *\n * @returns {PermissionResult}\n *   `{ allowed: boolean, reason: string }`\n *\n * @example <caption>OR logic (default) — user has one of the required permissions</caption>\n * hasPermission(['read:invoices'], ['read:invoices', 'write:invoices']);\n * // => { allowed: true, reason: 'User has at least one required permission.' }\n *\n * @example <caption>OR logic — user has none</caption>\n * hasPermission(['read:posts'], ['write:posts', 'delete:posts'], 'any');\n * // => { allowed: false, reason: 'User does not have any of the required permissions: ...' }\n *\n * @example <caption>AND logic — must have all required permissions</caption>\n * hasPermission(['read:users', 'write:users'], ['read:users', 'write:users'], 'all');\n * // => { allowed: true, reason: 'User has all required permissions.' }\n *\n * @example <caption>Full wildcard — grants everything</caption>\n * hasPermission(['*'], ['read:users', 'delete:posts'], 'all');\n * // => { allowed: true, reason: 'User has wildcard permission (*) — full access granted.' }\n *\n * @example <caption>Namespace wildcard — \"read:*\" satisfies any \"read:\" permission</caption>\n * hasPermission(['read:*'], ['read:invoices', 'read:reports'], 'all');\n * // => { allowed: true, reason: 'User has all required permissions.' }\n */\nexport function hasPermission(\n  userPermissions,\n  requiredPermissions,\n  logic = \"any\",\n) {\n  if (!Array.isArray(requiredPermissions) || requiredPermissions.length === 0) {\n    return {\n      allowed: true,\n      reason: 'No permissions required — access granted.',\n    };\n  }\n\n  if (!Array.isArray(userPermissions) || userPermissions.length === 0) {\n    return { allowed: false, reason: 'User has no permissions assigned.' };\n  }\n\n\n  const normalizedUser = userPermissions.map((p) => p.toLowerCase().trim());\n  const normalizedRequired = requiredPermissions.map((p) =>\n    p.toLowerCase().trim(),\n  );\n\n  // Full wildcard check\n  if (normalizedUser.includes(\"*\")) {\n    return {\n      allowed: true,\n      reason: \"User has wildcard permission (*) — full access granted.\",\n    };\n  }\n\n  /**\n   * Checks if a single required permission is satisfied by the user's permission set,\n   * including namespace wildcard matching (e.g. \"read:*\" matches \"read:users\").\n   *\n   * @param {string} required - The required permission to satisfy.\n   * @returns {boolean} Whether the user satisfies this specific permission.\n   */\n  function isSatisfied(required) {\n    if (normalizedUser.includes(required)) return true;\n\n    // Namespace wildcard: \"read:*\" should satisfy \"read:users\"\n    const [requiredNamespace] = required.split(\":\");\n    return normalizedUser.includes(`${requiredNamespace}:*`);\n  }\n\n  if (logic === \"all\") {\n    const missing = normalizedRequired.filter((p) => !isSatisfied(p));\n    if (missing.length > 0) {\n      return {\n        allowed: false,\n        reason: `User is missing required permissions: ${missing.join(\", \")}`,\n      };\n    }\n    return { allowed: true, reason: \"User has all required permissions.\" };\n  }\n\n  // Default: \"any\" (OR logic)\n  const matched = normalizedRequired.filter((p) => isSatisfied(p));\n  if (matched.length === 0) {\n    return {\n      allowed: false,\n      reason: `User does not have any of the required permissions: ${normalizedRequired.join(\", \")}`,\n    };\n  }\n  return {\n    allowed: true,\n    reason: \"User has at least one required permission.\",\n  };\n}\n\n// ─── Combined Check ───────────────────────────────────────────────────────────\n\n/**\n * Performs a **combined** role AND permission check in a single call.\n *\n * Both the role check and the permission check must independently pass\n * for `allowed` to be `true`. If a constraint array is empty or not\n * provided, that constraint is automatically satisfied (open access).\n *\n * @param {Object} options\n *\n * @param {string[]} [options.userRoles=[]]\n *   The roles currently held by the user. Any strings are accepted;\n *   you define what roles mean in your app.\n *\n * @param {string[]} [options.userPermissions=[]]\n *   The permissions currently held by the user. Supports wildcards:\n *   `\"*\"` (all access) and `\"namespace:*\"` (all in namespace).\n *\n * @param {string[]} [options.requiredRoles=[]]\n *   Roles the user must have to pass the role check.\n *   Pass `[]` (default) to skip the role check entirely.\n *\n * @param {string[]} [options.requiredPermissions=[]]\n *   Permissions the user must have to pass the permission check.\n *   Pass `[]` (default) to skip the permission check entirely.\n *\n * @param {\"any\" | \"all\"} [options.roleLogic=\"any\"]\n *   Controls how `requiredRoles` are evaluated.\n *\n *   | Value   | Behaviour                                        | Default? |\n *   |---------|--------------------------------------------------|----------|\n *   | `\"any\"` | User needs **at least one** required role (OR)   | ✅ Yes   |\n *   | `\"all\"` | User needs **every** required role (AND)         | No       |\n *\n *   ```js\n *   // 'any' is the default — no need to specify it explicitly for OR logic\n *   checkAccess({ requiredRoles: ['admin', 'editor'], roleLogic: 'any' });\n *   ```\n *\n * @param {\"any\" | \"all\"} [options.permissionLogic=\"any\"]\n *   Controls how `requiredPermissions` are evaluated.\n *\n *   | Value   | Behaviour                                             | Default? |\n *   |---------|-------------------------------------------------------|----------|\n *   | `\"any\"` | User needs **at least one** required permission (OR)  | ✅ Yes   |\n *   | `\"all\"` | User needs **every** required permission (AND)        | No       |\n *\n *   ```js\n *   // Require the user to have ALL listed permissions (AND logic)\n *   checkAccess({\n *     requiredPermissions: ['read:report', 'export:report'],\n *     permissionLogic: 'all',\n *   });\n *   ```\n *\n * @returns {PermissionResult}\n *   `{ allowed: boolean, reason: string }` — `allowed` is `true` only\n *   when **both** role and permission checks pass.\n *\n * @example <caption>Combined check — OR role logic + OR permission logic (both defaults)</caption>\n * checkAccess({\n *   userRoles: ['editor'],\n *   userPermissions: ['write:posts'],\n *   requiredRoles: ['editor', 'admin'],      // editor OR admin\n *   requiredPermissions: ['write:posts'],    // write:posts required\n * });\n * // => { allowed: true, reason: 'Access granted.' }\n *\n * @example <caption>AND logic for permissions — user must have ALL listed permissions</caption>\n * checkAccess({\n *   userRoles: ['manager'],\n *   userPermissions: ['approve:leaves'],\n *   requiredRoles: ['manager'],\n *   requiredPermissions: ['approve:leaves', 'view:team'],\n *   permissionLogic: 'all',   // must have BOTH permissions\n * });\n * // => { allowed: false, reason: 'User is missing required permissions: view:team' }\n *\n * @example <caption>No constraints — always allowed</caption>\n * checkAccess({ userRoles: ['guest'], userPermissions: [] });\n * // => { allowed: true, reason: 'Access granted.' }\n */\nexport function checkAccess({\n  userRoles = [],\n  userPermissions = [],\n  requiredRoles = [],\n  requiredPermissions = [],\n  roleLogic = \"any\",\n  permissionLogic = \"any\",\n}) {\n  const roleResult = hasRole(userRoles, requiredRoles, roleLogic);\n  if (!roleResult.allowed) return roleResult;\n\n  const permResult = hasPermission(\n    userPermissions,\n    requiredPermissions,\n    permissionLogic,\n  );\n  if (!permResult.allowed) return permResult;\n\n  return { allowed: true, reason: \"Access granted.\" };\n}\n"],"names":["hasRole","userRoles","requiredRoles","logic","Array","isArray","length","allowed","reason","normalizedUser","map","r","toLowerCase","trim","normalizedRequired","missing","filter","includes","join","matched","hasPermission","userPermissions","requiredPermissions","p","isSatisfied","required","requiredNamespace","split","checkAccess","roleLogic","permissionLogic","roleResult","permResult"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,OAAOA,CAACC,SAAS,EAAEC,aAAa,EAAEC,KAAK,GAAG,KAAK,EAAE;AAC/D,EAAA,IAAI,CAACC,KAAK,CAACC,OAAO,CAACH,aAAa,CAAC,IAAIA,aAAa,CAACI,MAAM,KAAK,CAAC,EAAE;IAC/D,OAAO;AAAEC,MAAAA,OAAO,EAAE,IAAI;AAAEC,MAAAA,MAAM,EAAE;KAAuC;AACzE,EAAA;AAEA,EAAA,IAAI,CAACJ,KAAK,CAACC,OAAO,CAACJ,SAAS,CAAC,IAAIA,SAAS,CAACK,MAAM,KAAK,CAAC,EAAE;IACvD,OAAO;AAAEC,MAAAA,OAAO,EAAE,KAAK;AAAEC,MAAAA,MAAM,EAAE;KAA+B;AAClE,EAAA;AAEA,EAAA,MAAMC,cAAc,GAAGR,SAAS,CAACS,GAAG,CAAEC,CAAC,IAAKA,CAAC,CAACC,WAAW,EAAE,CAACC,IAAI,EAAE,CAAC;AACnE,EAAA,MAAMC,kBAAkB,GAAGZ,aAAa,CAACQ,GAAG,CAAEC,CAAC,IAAKA,CAAC,CAACC,WAAW,EAAE,CAACC,IAAI,EAAE,CAAC;EAE3E,IAAIV,KAAK,KAAK,KAAK,EAAE;AACnB,IAAA,MAAMY,OAAO,GAAGD,kBAAkB,CAACE,MAAM,CACtCL,CAAC,IAAK,CAACF,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"}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "role-permission-engine",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A lightweight, flexible role and permission-based route guard and UI gate for React applications supporting React Router v5 and v6.",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs.js",
+      "import": "./dist/index.esm.js"
+    },
+    "./utils": {
+      "types": "./types/utils.d.ts",
+      "require": "./dist/utils.cjs.js",
+      "import": "./dist/utils.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "docs": "jsdoc -c jsdoc.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "react",
+    "role",
+    "permission",
+    "rbac",
+    "route-guard",
+    "authorization",
+    "access-control",
+    "react-router"
+  ],
+  "author": "Darshan Raghvani",
+  "license": "MIT",
+  "homepage": "https://role-permission-engine.pages.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DarshanR1406/role-permission-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DarshanR1406/role-permission-engine/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "react-router-dom": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.0",
+    "@babel/preset-env": "^7.23.0",
+    "@babel/preset-react": "^7.22.0",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@testing-library/jest-dom": "^6.1.4",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.5.1",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdoc": "^4.0.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.18.0",
+    "rollup": "^4.1.4"
+  },
+  "jest": {
+    "testEnvironment": "jsdom",
+    "setupFilesAfterEnv": ["./jest.setup.js"],
+    "transform": {
+      "^.+\\.(js|jsx)$": "babel-jest"
+    },
+    "moduleFileExtensions": [
+      "js",
+      "jsx"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.{js,jsx}",
+      "!src/index.js"
+    ]
+  }
+}