com-angel-authorization 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# com-angel-authorization
+
+框架无关的用户权限配置 npm 包，可在 **React** 与 **Vue 3** 项目中使用。
+
+## 特性
+
+- 核心层与 UI 框架解耦，也可直接在非前端环境使用
+- 支持权限码（permission）与角色（role）
+- `any` / `all` 匹配模式
+- 超级管理员旁路（`isSuperAdmin`）
+- React：`Provider` + Hooks + `<Can>`
+- Vue 3：Plugin + Composables + `v-permission` + `<Can>`
+
+## 安装
+
+```bash
+npm install com-angel-authorization
+# 或
+pnpm add com-angel-authorization
+```
+
+按需安装 peer 依赖：
+
+```bash
+# React 项目
+npm install react
+
+# Vue 项目
+npm install vue
+```
+
+## 包入口
+
+| 入口 | 用途 |
+|------|------|
+| `com-angel-authorization` | 框架无关核心 |
+| `com-angel-authorization/react` | React 适配 |
+| `com-angel-authorization/vue` | Vue 3 适配 |
+
+---
+
+## 核心 API（框架无关）
+
+```ts
+import { createPermissionStore } from 'com-angel-authorization';
+
+const store = createPermissionStore({
+  permissions: ['user:view', 'user:edit'],
+  roles: ['editor'],
+  isSuperAdmin: false,
+});
+
+store.hasPermission('user:edit'); // true
+store.hasPermission(['user:edit', 'user:delete'], { mode: 'all' }); // false
+store.hasRole('editor'); // true
+store.can('user:view'); // true（hasPermission 别名）
+
+// 登录后写入
+store.hydrate({
+  permissions: ['user:view', 'user:edit', 'user:delete'],
+  roles: ['admin'],
+});
+
+// 登出清空
+store.clear();
+```
+
+---
+
+## React 用法
+
+```tsx
+import {
+  PermissionProvider,
+  usePermission,
+  useHasPermission,
+  Can,
+} from 'com-angel-authorization/react';
+
+function App() {
+  return (
+    <PermissionProvider
+      initialState={{
+        permissions: ['user:view', 'user:edit'],
+        roles: ['editor'],
+      }}
+    >
+      <Dashboard />
+    </PermissionProvider>
+  );
+}
+
+function Dashboard() {
+  const { can, hydrate, clear } = usePermission();
+  const canEdit = useHasPermission('user:edit');
+
+  // 登录成功后
+  // hydrate({ permissions: data.perms, roles: data.roles });
+
+  // 登出
+  // clear();
+
+  return (
+    <div>
+      {canEdit && <button>编辑</button>}
+
+      <Can permission="user:delete" fallback={<span>无删除权限</span>}>
+        <button>删除</button>
+      </Can>
+
+      <Can permission={['user:edit', 'user:delete']} mode="all">
+        <AdminTools />
+      </Can>
+
+      <Can role="admin" permission="user:edit" combine="or">
+        <button>管理入口</button>
+      </Can>
+
+      {can('user:view') && <UserList />}
+    </div>
+  );
+}
+```
+
+也可传入外部 store，便于跨树或与路由守卫共享：
+
+```tsx
+import { createPermissionStore } from 'com-angel-authorization';
+import { PermissionProvider } from 'com-angel-authorization/react';
+
+export const permissionStore = createPermissionStore();
+
+<PermissionProvider store={permissionStore}>
+  <App />
+</PermissionProvider>
+```
+
+---
+
+## Vue 3 用法
+
+### 安装插件
+
+```ts
+import { createApp } from 'vue';
+import { createPermissionPlugin, Can } from 'com-angel-authorization/vue';
+import App from './App.vue';
+
+const permission = createPermissionPlugin({
+  initialState: {
+    permissions: ['user:view', 'user:edit'],
+    roles: ['editor'],
+  },
+});
+
+const app = createApp(App);
+app.use(permission);
+app.component('Can', Can); // 可选：全局注册
+app.mount('#app');
+
+// 需要时在模块外访问
+// permission.store.hydrate({ ... })
+```
+
+### Composition API
+
+```vue
+<script setup lang="ts">
+import { usePermission, useHasPermission, Can } from 'com-angel-authorization/vue';
+
+const { can, hydrate, clear } = usePermission();
+const canEdit = useHasPermission('user:edit');
+
+async function onLogin() {
+  const data = await fetchUserAuth();
+  hydrate({
+    permissions: data.permissions,
+    roles: data.roles,
+    isSuperAdmin: data.isSuperAdmin,
+  });
+}
+</script>
+
+<template>
+  <button v-if="canEdit">编辑</button>
+
+  <Can permission="user:delete">
+    <button>删除</button>
+    <template #fallback>无删除权限</template>
+  </Can>
+
+  <!-- 指令：无权限时隐藏元素 -->
+  <button v-permission="'user:edit'">编辑</button>
+  <button v-permission:all="['user:edit', 'user:delete']">危险操作</button>
+  <button v-permission:role="'admin'">管理员</button>
+  <button
+    v-permission="{
+      permission: 'user:edit',
+      role: 'admin',
+      combine: 'or',
+    }"
+  >
+    管理入口
+  </button>
+</template>
+```
+
+### 选项式 / 模板全局方法
+
+插件安装后可用：
+
+```vue
+<template>
+  <button v-if="$can('user:edit')">编辑</button>
+  <button v-if="$hasRole('admin')">管理</button>
+</template>
+```
+
+---
+
+## API 速查
+
+### PermissionStore
+
+| 方法 | 说明 |
+|------|------|
+| `hydrate(state)` | 一次性写入权限 / 角色 / 超管 |
+| `setPermissions(list)` | 设置权限码 |
+| `setRoles(list)` | 设置角色 |
+| `setSuperAdmin(bool)` | 设置超管 |
+| `clear()` | 清空 |
+| `hasPermission(codes, { mode })` | 校验权限，`mode`: `any` \| `all` |
+| `hasRole(codes, { mode })` | 校验角色 |
+| `can(codes, options)` | `hasPermission` 别名 |
+| `subscribe(listener)` | 订阅变更，返回取消函数 |
+| `getState()` | 获取当前快照 |
+
+### `<Can>` 组件（React / Vue）
+
+| Prop | 说明 |
+|------|------|
+| `permission` | 权限码或数组 |
+| `role` | 角色码或数组 |
+| `mode` | `any`（默认）/ `all` |
+| `combine` | 同时传 permission 与 role 时：`and`（默认）/ `or` |
+| `fallback` | React：无权限占位；Vue：使用 `#fallback` 插槽 |
+
+---
+
+## 典型接入流程
+
+1. 应用启动时创建 store / 安装 Provider 或 Plugin  
+2. 登录成功后调用 `hydrate` 写入后端返回的权限与角色  
+3. 页面用 `<Can>` / `v-permission` / `can()` 控制按钮与菜单  
+4. 路由守卫中直接读同一个 store 做页面级鉴权  
+5. 登出时调用 `clear()`
+
+```ts
+// 路由守卫示例（与框架无关）
+if (!permissionStore.hasPermission('order:view')) {
+  return next('/403');
+}
+```
+
+## 构建
+
+```bash
+npm install
+npm run build
+```
+
+产物在 `dist/`，支持 ESM / CJS 与类型声明。
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+// src/core/store.ts
+var DEFAULT_STATE = {
+  permissions: [],
+  roles: [],
+  isSuperAdmin: false
+};
+function toArray(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function matchCodes(owned, required, mode, isSuperAdmin) {
+  if (isSuperAdmin) return true;
+  if (required.length === 0) return true;
+  if (mode === "all") {
+    return required.every((code) => owned.has(code));
+  }
+  return required.some((code) => owned.has(code));
+}
+var PermissionStore = class {
+  constructor(initial) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.state = {
+      ...DEFAULT_STATE,
+      ...initial,
+      permissions: initial?.permissions ?? [],
+      roles: initial?.roles ?? []
+    };
+    this.permissionSet = new Set(this.state.permissions);
+    this.roleSet = new Set(this.state.roles);
+  }
+  getState() {
+    return {
+      permissions: [...this.state.permissions],
+      roles: [...this.state.roles],
+      isSuperAdmin: this.state.isSuperAdmin
+    };
+  }
+  setState(next) {
+    this.state = {
+      permissions: next.permissions ?? this.state.permissions,
+      roles: next.roles ?? this.state.roles,
+      isSuperAdmin: next.isSuperAdmin ?? this.state.isSuperAdmin
+    };
+    this.permissionSet = new Set(this.state.permissions);
+    this.roleSet = new Set(this.state.roles);
+    this.emit();
+  }
+  setPermissions(permissions) {
+    this.setState({ permissions });
+  }
+  setRoles(roles) {
+    this.setState({ roles });
+  }
+  setSuperAdmin(isSuperAdmin) {
+    this.setState({ isSuperAdmin });
+  }
+  /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+  hydrate(payload) {
+    this.setState({
+      permissions: payload.permissions ?? [],
+      roles: payload.roles ?? [],
+      isSuperAdmin: payload.isSuperAdmin ?? false
+    });
+  }
+  /** Clear all authz data (typical after logout). */
+  clear() {
+    this.hydrate({});
+  }
+  hasPermission(codes, options = {}) {
+    const mode = options.mode ?? "any";
+    return matchCodes(
+      this.permissionSet,
+      toArray(codes).filter(Boolean),
+      mode,
+      Boolean(this.state.isSuperAdmin)
+    );
+  }
+  hasRole(codes, options = {}) {
+    const mode = options.mode ?? "any";
+    return matchCodes(
+      this.roleSet,
+      toArray(codes).filter(Boolean),
+      mode,
+      Boolean(this.state.isSuperAdmin)
+    );
+  }
+  /** Alias of `hasPermission` for template-friendly APIs. */
+  can(codes, options) {
+    return this.hasPermission(codes, options);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit() {
+    const snapshot = this.getState();
+    this.listeners.forEach((listener) => listener(snapshot));
+  }
+};
+function createPermissionStore(initial) {
+  return new PermissionStore(initial);
+}
+
+exports.PermissionStore = PermissionStore;
+exports.createPermissionStore = createPermissionStore;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/store.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type {\n  CheckOptions,\n  MatchMode,\n  PermissionChecker,\n  PermissionCode,\n  PermissionListener,\n  PermissionState,\n  RoleCode,\n} from './types';\n\nconst DEFAULT_STATE: PermissionState = {\n  permissions: [],\n  roles: [],\n  isSuperAdmin: false,\n};\n\nfunction toArray<T>(value: T | T[]): T[] {\n  return Array.isArray(value) ? value : [value];\n}\n\nfunction matchCodes(\n  owned: Set<string>,\n  required: string[],\n  mode: MatchMode,\n  isSuperAdmin: boolean,\n): boolean {\n  if (isSuperAdmin) return true;\n  if (required.length === 0) return true;\n\n  if (mode === 'all') {\n    return required.every((code) => owned.has(code));\n  }\n\n  return required.some((code) => owned.has(code));\n}\n\n/**\n * Mutable permission store shared by React / Vue adapters.\n * Framework-agnostic — safe to use in Node, browser, or any UI lib.\n */\nexport class PermissionStore implements PermissionChecker {\n  private state: PermissionState;\n  private permissionSet: Set<string>;\n  private roleSet: Set<string>;\n  private listeners = new Set<PermissionListener>();\n\n  constructor(initial?: Partial<PermissionState>) {\n    this.state = {\n      ...DEFAULT_STATE,\n      ...initial,\n      permissions: initial?.permissions ?? [],\n      roles: initial?.roles ?? [],\n    };\n    this.permissionSet = new Set(this.state.permissions);\n    this.roleSet = new Set(this.state.roles);\n  }\n\n  getState(): PermissionState {\n    return {\n      permissions: [...this.state.permissions],\n      roles: [...this.state.roles],\n      isSuperAdmin: this.state.isSuperAdmin,\n    };\n  }\n\n  setState(next: Partial<PermissionState>): void {\n    this.state = {\n      permissions: next.permissions ?? this.state.permissions,\n      roles: next.roles ?? this.state.roles,\n      isSuperAdmin: next.isSuperAdmin ?? this.state.isSuperAdmin,\n    };\n    this.permissionSet = new Set(this.state.permissions);\n    this.roleSet = new Set(this.state.roles);\n    this.emit();\n  }\n\n  setPermissions(permissions: PermissionCode[]): void {\n    this.setState({ permissions });\n  }\n\n  setRoles(roles: RoleCode[]): void {\n    this.setState({ roles });\n  }\n\n  setSuperAdmin(isSuperAdmin: boolean): void {\n    this.setState({ isSuperAdmin });\n  }\n\n  /** Replace permissions, roles and super-admin flag in one shot (typical after login). */\n  hydrate(payload: Partial<PermissionState>): void {\n    this.setState({\n      permissions: payload.permissions ?? [],\n      roles: payload.roles ?? [],\n      isSuperAdmin: payload.isSuperAdmin ?? false,\n    });\n  }\n\n  /** Clear all authz data (typical after logout). */\n  clear(): void {\n    this.hydrate({});\n  }\n\n  hasPermission(\n    codes: PermissionCode | PermissionCode[],\n    options: CheckOptions = {},\n  ): boolean {\n    const mode = options.mode ?? 'any';\n    return matchCodes(\n      this.permissionSet,\n      toArray(codes).filter(Boolean),\n      mode,\n      Boolean(this.state.isSuperAdmin),\n    );\n  }\n\n  hasRole(codes: RoleCode | RoleCode[], options: CheckOptions = {}): boolean {\n    const mode = options.mode ?? 'any';\n    return matchCodes(\n      this.roleSet,\n      toArray(codes).filter(Boolean),\n      mode,\n      Boolean(this.state.isSuperAdmin),\n    );\n  }\n\n  /** Alias of `hasPermission` for template-friendly APIs. */\n  can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean {\n    return this.hasPermission(codes, options);\n  }\n\n  subscribe(listener: PermissionListener): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  private emit(): void {\n    const snapshot = this.getState();\n    this.listeners.forEach((listener) => listener(snapshot));\n  }\n}\n\nexport function createPermissionStore(\n  initial?: Partial<PermissionState>,\n): PermissionStore {\n  return new PermissionStore(initial);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+type PermissionCode = string;
+type RoleCode = string;
+interface PermissionState {
+    /** Permission codes owned by the current user */
+    permissions: PermissionCode[];
+    /** Roles owned by the current user */
+    roles: RoleCode[];
+    /** Super admin bypasses all checks when true */
+    isSuperAdmin?: boolean;
+}
+type MatchMode = 'all' | 'any';
+interface CheckOptions {
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: MatchMode;
+}
+type PermissionListener = (state: PermissionState) => void;
+interface PermissionChecker {
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    getState(): PermissionState;
+}
+
+/**
+ * Mutable permission store shared by React / Vue adapters.
+ * Framework-agnostic — safe to use in Node, browser, or any UI lib.
+ */
+declare class PermissionStore implements PermissionChecker {
+    private state;
+    private permissionSet;
+    private roleSet;
+    private listeners;
+    constructor(initial?: Partial<PermissionState>);
+    getState(): PermissionState;
+    setState(next: Partial<PermissionState>): void;
+    setPermissions(permissions: PermissionCode[]): void;
+    setRoles(roles: RoleCode[]): void;
+    setSuperAdmin(isSuperAdmin: boolean): void;
+    /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+    hydrate(payload: Partial<PermissionState>): void;
+    /** Clear all authz data (typical after logout). */
+    clear(): void;
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    /** Alias of `hasPermission` for template-friendly APIs. */
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    subscribe(listener: PermissionListener): () => void;
+    private emit;
+}
+declare function createPermissionStore(initial?: Partial<PermissionState>): PermissionStore;
+
+export { type CheckOptions, type MatchMode, type PermissionChecker, type PermissionCode, type PermissionListener, type PermissionState, PermissionStore, type RoleCode, createPermissionStore };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+type PermissionCode = string;
+type RoleCode = string;
+interface PermissionState {
+    /** Permission codes owned by the current user */
+    permissions: PermissionCode[];
+    /** Roles owned by the current user */
+    roles: RoleCode[];
+    /** Super admin bypasses all checks when true */
+    isSuperAdmin?: boolean;
+}
+type MatchMode = 'all' | 'any';
+interface CheckOptions {
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: MatchMode;
+}
+type PermissionListener = (state: PermissionState) => void;
+interface PermissionChecker {
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    getState(): PermissionState;
+}
+
+/**
+ * Mutable permission store shared by React / Vue adapters.
+ * Framework-agnostic — safe to use in Node, browser, or any UI lib.
+ */
+declare class PermissionStore implements PermissionChecker {
+    private state;
+    private permissionSet;
+    private roleSet;
+    private listeners;
+    constructor(initial?: Partial<PermissionState>);
+    getState(): PermissionState;
+    setState(next: Partial<PermissionState>): void;
+    setPermissions(permissions: PermissionCode[]): void;
+    setRoles(roles: RoleCode[]): void;
+    setSuperAdmin(isSuperAdmin: boolean): void;
+    /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+    hydrate(payload: Partial<PermissionState>): void;
+    /** Clear all authz data (typical after logout). */
+    clear(): void;
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    /** Alias of `hasPermission` for template-friendly APIs. */
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    subscribe(listener: PermissionListener): () => void;
+    private emit;
+}
+declare function createPermissionStore(initial?: Partial<PermissionState>): PermissionStore;
+
+export { type CheckOptions, type MatchMode, type PermissionChecker, type PermissionCode, type PermissionListener, type PermissionState, PermissionStore, type RoleCode, createPermissionStore };

package/dist/index.js

@@ -0,0 +1,107 @@
+// src/core/store.ts
+var DEFAULT_STATE = {
+  permissions: [],
+  roles: [],
+  isSuperAdmin: false
+};
+function toArray(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function matchCodes(owned, required, mode, isSuperAdmin) {
+  if (isSuperAdmin) return true;
+  if (required.length === 0) return true;
+  if (mode === "all") {
+    return required.every((code) => owned.has(code));
+  }
+  return required.some((code) => owned.has(code));
+}
+var PermissionStore = class {
+  constructor(initial) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.state = {
+      ...DEFAULT_STATE,
+      ...initial,
+      permissions: initial?.permissions ?? [],
+      roles: initial?.roles ?? []
+    };
+    this.permissionSet = new Set(this.state.permissions);
+    this.roleSet = new Set(this.state.roles);
+  }
+  getState() {
+    return {
+      permissions: [...this.state.permissions],
+      roles: [...this.state.roles],
+      isSuperAdmin: this.state.isSuperAdmin
+    };
+  }
+  setState(next) {
+    this.state = {
+      permissions: next.permissions ?? this.state.permissions,
+      roles: next.roles ?? this.state.roles,
+      isSuperAdmin: next.isSuperAdmin ?? this.state.isSuperAdmin
+    };
+    this.permissionSet = new Set(this.state.permissions);
+    this.roleSet = new Set(this.state.roles);
+    this.emit();
+  }
+  setPermissions(permissions) {
+    this.setState({ permissions });
+  }
+  setRoles(roles) {
+    this.setState({ roles });
+  }
+  setSuperAdmin(isSuperAdmin) {
+    this.setState({ isSuperAdmin });
+  }
+  /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+  hydrate(payload) {
+    this.setState({
+      permissions: payload.permissions ?? [],
+      roles: payload.roles ?? [],
+      isSuperAdmin: payload.isSuperAdmin ?? false
+    });
+  }
+  /** Clear all authz data (typical after logout). */
+  clear() {
+    this.hydrate({});
+  }
+  hasPermission(codes, options = {}) {
+    const mode = options.mode ?? "any";
+    return matchCodes(
+      this.permissionSet,
+      toArray(codes).filter(Boolean),
+      mode,
+      Boolean(this.state.isSuperAdmin)
+    );
+  }
+  hasRole(codes, options = {}) {
+    const mode = options.mode ?? "any";
+    return matchCodes(
+      this.roleSet,
+      toArray(codes).filter(Boolean),
+      mode,
+      Boolean(this.state.isSuperAdmin)
+    );
+  }
+  /** Alias of `hasPermission` for template-friendly APIs. */
+  can(codes, options) {
+    return this.hasPermission(codes, options);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit() {
+    const snapshot = this.getState();
+    this.listeners.forEach((listener) => listener(snapshot));
+  }
+};
+function createPermissionStore(initial) {
+  return new PermissionStore(initial);
+}
+
+export { PermissionStore, createPermissionStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/store.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n  CheckOptions,\n  MatchMode,\n  PermissionChecker,\n  PermissionCode,\n  PermissionListener,\n  PermissionState,\n  RoleCode,\n} from './types';\n\nconst DEFAULT_STATE: PermissionState = {\n  permissions: [],\n  roles: [],\n  isSuperAdmin: false,\n};\n\nfunction toArray<T>(value: T | T[]): T[] {\n  return Array.isArray(value) ? value : [value];\n}\n\nfunction matchCodes(\n  owned: Set<string>,\n  required: string[],\n  mode: MatchMode,\n  isSuperAdmin: boolean,\n): boolean {\n  if (isSuperAdmin) return true;\n  if (required.length === 0) return true;\n\n  if (mode === 'all') {\n    return required.every((code) => owned.has(code));\n  }\n\n  return required.some((code) => owned.has(code));\n}\n\n/**\n * Mutable permission store shared by React / Vue adapters.\n * Framework-agnostic — safe to use in Node, browser, or any UI lib.\n */\nexport class PermissionStore implements PermissionChecker {\n  private state: PermissionState;\n  private permissionSet: Set<string>;\n  private roleSet: Set<string>;\n  private listeners = new Set<PermissionListener>();\n\n  constructor(initial?: Partial<PermissionState>) {\n    this.state = {\n      ...DEFAULT_STATE,\n      ...initial,\n      permissions: initial?.permissions ?? [],\n      roles: initial?.roles ?? [],\n    };\n    this.permissionSet = new Set(this.state.permissions);\n    this.roleSet = new Set(this.state.roles);\n  }\n\n  getState(): PermissionState {\n    return {\n      permissions: [...this.state.permissions],\n      roles: [...this.state.roles],\n      isSuperAdmin: this.state.isSuperAdmin,\n    };\n  }\n\n  setState(next: Partial<PermissionState>): void {\n    this.state = {\n      permissions: next.permissions ?? this.state.permissions,\n      roles: next.roles ?? this.state.roles,\n      isSuperAdmin: next.isSuperAdmin ?? this.state.isSuperAdmin,\n    };\n    this.permissionSet = new Set(this.state.permissions);\n    this.roleSet = new Set(this.state.roles);\n    this.emit();\n  }\n\n  setPermissions(permissions: PermissionCode[]): void {\n    this.setState({ permissions });\n  }\n\n  setRoles(roles: RoleCode[]): void {\n    this.setState({ roles });\n  }\n\n  setSuperAdmin(isSuperAdmin: boolean): void {\n    this.setState({ isSuperAdmin });\n  }\n\n  /** Replace permissions, roles and super-admin flag in one shot (typical after login). */\n  hydrate(payload: Partial<PermissionState>): void {\n    this.setState({\n      permissions: payload.permissions ?? [],\n      roles: payload.roles ?? [],\n      isSuperAdmin: payload.isSuperAdmin ?? false,\n    });\n  }\n\n  /** Clear all authz data (typical after logout). */\n  clear(): void {\n    this.hydrate({});\n  }\n\n  hasPermission(\n    codes: PermissionCode | PermissionCode[],\n    options: CheckOptions = {},\n  ): boolean {\n    const mode = options.mode ?? 'any';\n    return matchCodes(\n      this.permissionSet,\n      toArray(codes).filter(Boolean),\n      mode,\n      Boolean(this.state.isSuperAdmin),\n    );\n  }\n\n  hasRole(codes: RoleCode | RoleCode[], options: CheckOptions = {}): boolean {\n    const mode = options.mode ?? 'any';\n    return matchCodes(\n      this.roleSet,\n      toArray(codes).filter(Boolean),\n      mode,\n      Boolean(this.state.isSuperAdmin),\n    );\n  }\n\n  /** Alias of `hasPermission` for template-friendly APIs. */\n  can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean {\n    return this.hasPermission(codes, options);\n  }\n\n  subscribe(listener: PermissionListener): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  private emit(): void {\n    const snapshot = this.getState();\n    this.listeners.forEach((listener) => listener(snapshot));\n  }\n}\n\nexport function createPermissionStore(\n  initial?: Partial<PermissionState>,\n): PermissionStore {\n  return new PermissionStore(initial);\n}\n"]}