@pyreon/permissions 0.5.0 → 0.7.0

package/lib/index.js

@@ -0,0 +1,132 @@
+import { computed, signal } from "@pyreon/reactivity";
+import { createContext, provide, useContext } from "@pyreon/core";
+
+//#region src/permissions.ts
+/**
+* Resolve a permission key against the map.
+* Resolution order: exact match → wildcard (e.g., 'posts.*') → global wildcard ('*') → false.
+*/
+function resolve(map, key, context) {
+	const exact = map.get(key);
+	if (exact !== void 0) return typeof exact === "function" ? exact(context) : exact;
+	const dotIndex = key.lastIndexOf(".");
+	if (dotIndex !== -1) {
+		const prefix = key.slice(0, dotIndex);
+		const wildcard = map.get(`${prefix}.*`);
+		if (wildcard !== void 0) return typeof wildcard === "function" ? wildcard(context) : wildcard;
+	}
+	const global = map.get("*");
+	if (global !== void 0) return typeof global === "function" ? global(context) : global;
+	return false;
+}
+/**
+* Create a reactive permissions instance.
+*
+* The returned `can` function checks permissions reactively —
+* reads update automatically when permissions change via `set()` or `patch()`.
+*
+* @param initial - Optional initial permission map
+* @returns A callable `Permissions` instance
+*
+* @example
+* ```tsx
+* const can = createPermissions({
+*   'posts.read': true,
+*   'posts.update': (post: Post) => post.authorId === userId(),
+*   'users.manage': false,
+* })
+*
+* // Check (reactive in effects/computeds/JSX)
+* can('posts.read')              // true
+* can('posts.update', myPost)    // evaluates predicate
+*
+* // JSX
+* {() => can('posts.delete') && <DeleteButton />}
+*
+* // Update
+* can.set({ 'posts.read': true, 'admin': true })
+* can.patch({ 'users.manage': true })
+* ```
+*/
+function createPermissions(initial) {
+	const store = signal(toMap(initial));
+	const version = signal(0);
+	function toMap(obj) {
+		if (!obj) return /* @__PURE__ */ new Map();
+		return new Map(Object.entries(obj));
+	}
+	function can(key, context) {
+		version();
+		return resolve(store.peek(), key, context);
+	}
+	can.not = (key, context) => {
+		return !can(key, context);
+	};
+	can.all = (...keys) => {
+		return keys.every((key) => can(key));
+	};
+	can.any = (...keys) => {
+		return keys.some((key) => can(key));
+	};
+	can.set = (permissions) => {
+		store.set(toMap(permissions));
+		version.update((v) => v + 1);
+	};
+	can.patch = (permissions) => {
+		const current = store.peek();
+		for (const [key, value] of Object.entries(permissions)) current.set(key, value);
+		store.set(current);
+		version.update((v) => v + 1);
+	};
+	can.granted = computed(() => {
+		version();
+		const keys = [];
+		for (const [key, value] of store.peek()) if (value === true || typeof value === "function") keys.push(key);
+		return keys;
+	});
+	can.entries = computed(() => {
+		version();
+		return [...store.peek().entries()];
+	});
+	return can;
+}
+
+//#endregion
+//#region src/context.ts
+const PermissionsContext = createContext(null);
+/**
+* Provide a permissions instance to descendant components.
+* Use this for SSR isolation or testing — each request/test gets its own instance.
+*
+* @example
+* ```tsx
+* const can = createPermissions({ ... })
+*
+* <PermissionsProvider instance={can}>
+*   <App />
+* </PermissionsProvider>
+* ```
+*/
+function PermissionsProvider(props) {
+	provide(PermissionsContext, props.instance);
+	return props.children ?? null;
+}
+/**
+* Access the nearest permissions instance from context.
+* Must be used within a `<PermissionsProvider>`.
+*
+* @example
+* ```tsx
+* const can = usePermissions()
+* {() => can('posts.read') && <PostList />}
+* ```
+*/
+function usePermissions() {
+	const instance = useContext(PermissionsContext);
+	if (!instance) throw new Error("[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>.");
+	return instance;
+}
+
+//#endregion
+export { PermissionsProvider, createPermissions, usePermissions };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/permissions.ts","../src/context.ts"],"sourcesContent":["import { computed, signal } from '@pyreon/reactivity'\nimport type { PermissionMap, PermissionValue, Permissions } from './types'\n\n/**\n * Resolve a permission key against the map.\n * Resolution order: exact match → wildcard (e.g., 'posts.*') → global wildcard ('*') → false.\n */\nfunction resolve(\n  map: Map<string, PermissionValue>,\n  key: string,\n  context?: unknown,\n): boolean {\n  // 1. Exact match\n  const exact = map.get(key)\n  if (exact !== undefined) {\n    return typeof exact === 'function' ? exact(context) : exact\n  }\n\n  // 2. Wildcard match — 'posts.read' matches 'posts.*'\n  const dotIndex = key.lastIndexOf('.')\n  if (dotIndex !== -1) {\n    const prefix = key.slice(0, dotIndex)\n    const wildcard = map.get(`${prefix}.*`)\n    if (wildcard !== undefined) {\n      return typeof wildcard === 'function' ? wildcard(context) : wildcard\n    }\n  }\n\n  // 3. Global wildcard\n  const global = map.get('*')\n  if (global !== undefined) {\n    return typeof global === 'function' ? global(context) : global\n  }\n\n  // 4. No match → denied\n  return false\n}\n\n/**\n * Create a reactive permissions instance.\n *\n * The returned `can` function checks permissions reactively —\n * reads update automatically when permissions change via `set()` or `patch()`.\n *\n * @param initial - Optional initial permission map\n * @returns A callable `Permissions` instance\n *\n * @example\n * ```tsx\n * const can = createPermissions({\n *   'posts.read': true,\n *   'posts.update': (post: Post) => post.authorId === userId(),\n *   'users.manage': false,\n * })\n *\n * // Check (reactive in effects/computeds/JSX)\n * can('posts.read')              // true\n * can('posts.update', myPost)    // evaluates predicate\n *\n * // JSX\n * {() => can('posts.delete') && <DeleteButton />}\n *\n * // Update\n * can.set({ 'posts.read': true, 'admin': true })\n * can.patch({ 'users.manage': true })\n * ```\n */\nexport function createPermissions(initial?: PermissionMap): Permissions {\n  // Internal reactive state — a signal holding the permission map\n  const store = signal(toMap(initial))\n  // Version counter — incremented on every set/patch to trigger reactive updates\n  const version = signal(0)\n\n  function toMap(obj?: PermissionMap): Map<string, PermissionValue> {\n    if (!obj) return new Map()\n    return new Map(Object.entries(obj))\n  }\n\n  // The main check function — reads `version` to subscribe in reactive contexts\n  function can(key: string, context?: unknown): boolean {\n    // Reading version subscribes this call to reactive updates\n    version()\n    return resolve(store.peek(), key, context)\n  }\n\n  can.not = (key: string, context?: unknown): boolean => {\n    return !can(key, context)\n  }\n\n  can.all = (...keys: string[]): boolean => {\n    return keys.every((key) => can(key))\n  }\n\n  can.any = (...keys: string[]): boolean => {\n    return keys.some((key) => can(key))\n  }\n\n  can.set = (permissions: PermissionMap): void => {\n    store.set(toMap(permissions))\n    version.update((v) => v + 1)\n  }\n\n  can.patch = (permissions: PermissionMap): void => {\n    const current = store.peek()\n    for (const [key, value] of Object.entries(permissions)) {\n      current.set(key, value)\n    }\n    store.set(current)\n    version.update((v) => v + 1)\n  }\n\n  can.granted = computed(() => {\n    version()\n    const keys: string[] = []\n    for (const [key, value] of store.peek()) {\n      // Static true or predicate (capability exists)\n      if (value === true || typeof value === 'function') {\n        keys.push(key)\n      }\n    }\n    return keys\n  })\n\n  can.entries = computed(() => {\n    version()\n    return [...store.peek().entries()]\n  })\n\n  return can as Permissions\n}\n","import { createContext, provide, useContext } from '@pyreon/core'\nimport type { VNodeChild } from '@pyreon/core'\nimport type { Permissions } from './types'\n\nconst PermissionsContext = createContext<Permissions | null>(null)\n\n/**\n * Provide a permissions instance to descendant components.\n * Use this for SSR isolation or testing — each request/test gets its own instance.\n *\n * @example\n * ```tsx\n * const can = createPermissions({ ... })\n *\n * <PermissionsProvider instance={can}>\n *   <App />\n * </PermissionsProvider>\n * ```\n */\nexport function PermissionsProvider(props: {\n  instance: Permissions\n  children?: VNodeChild\n}): VNodeChild {\n  provide(PermissionsContext, props.instance)\n\n  return props.children ?? null\n}\n\n/**\n * Access the nearest permissions instance from context.\n * Must be used within a `<PermissionsProvider>`.\n *\n * @example\n * ```tsx\n * const can = usePermissions()\n * {() => can('posts.read') && <PostList />}\n * ```\n */\nexport function usePermissions(): Permissions {\n  const instance = useContext(PermissionsContext)\n  if (!instance) {\n    throw new Error(\n      '[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>.',\n    )\n  }\n  return instance\n}\n"],"mappings":";;;;;;;;AAOA,SAAS,QACP,KACA,KACA,SACS;CAET,MAAM,QAAQ,IAAI,IAAI,IAAI;AAC1B,KAAI,UAAU,OACZ,QAAO,OAAO,UAAU,aAAa,MAAM,QAAQ,GAAG;CAIxD,MAAM,WAAW,IAAI,YAAY,IAAI;AACrC,KAAI,aAAa,IAAI;EACnB,MAAM,SAAS,IAAI,MAAM,GAAG,SAAS;EACrC,MAAM,WAAW,IAAI,IAAI,GAAG,OAAO,IAAI;AACvC,MAAI,aAAa,OACf,QAAO,OAAO,aAAa,aAAa,SAAS,QAAQ,GAAG;;CAKhE,MAAM,SAAS,IAAI,IAAI,IAAI;AAC3B,KAAI,WAAW,OACb,QAAO,OAAO,WAAW,aAAa,OAAO,QAAQ,GAAG;AAI1D,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCT,SAAgB,kBAAkB,SAAsC;CAEtE,MAAM,QAAQ,OAAO,MAAM,QAAQ,CAAC;CAEpC,MAAM,UAAU,OAAO,EAAE;CAEzB,SAAS,MAAM,KAAmD;AAChE,MAAI,CAAC,IAAK,wBAAO,IAAI,KAAK;AAC1B,SAAO,IAAI,IAAI,OAAO,QAAQ,IAAI,CAAC;;CAIrC,SAAS,IAAI,KAAa,SAA4B;AAEpD,WAAS;AACT,SAAO,QAAQ,MAAM,MAAM,EAAE,KAAK,QAAQ;;AAG5C,KAAI,OAAO,KAAa,YAA+B;AACrD,SAAO,CAAC,IAAI,KAAK,QAAQ;;AAG3B,KAAI,OAAO,GAAG,SAA4B;AACxC,SAAO,KAAK,OAAO,QAAQ,IAAI,IAAI,CAAC;;AAGtC,KAAI,OAAO,GAAG,SAA4B;AACxC,SAAO,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC;;AAGrC,KAAI,OAAO,gBAAqC;AAC9C,QAAM,IAAI,MAAM,YAAY,CAAC;AAC7B,UAAQ,QAAQ,MAAM,IAAI,EAAE;;AAG9B,KAAI,SAAS,gBAAqC;EAChD,MAAM,UAAU,MAAM,MAAM;AAC5B,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,YAAY,CACpD,SAAQ,IAAI,KAAK,MAAM;AAEzB,QAAM,IAAI,QAAQ;AAClB,UAAQ,QAAQ,MAAM,IAAI,EAAE;;AAG9B,KAAI,UAAU,eAAe;AAC3B,WAAS;EACT,MAAM,OAAiB,EAAE;AACzB,OAAK,MAAM,CAAC,KAAK,UAAU,MAAM,MAAM,CAErC,KAAI,UAAU,QAAQ,OAAO,UAAU,WACrC,MAAK,KAAK,IAAI;AAGlB,SAAO;GACP;AAEF,KAAI,UAAU,eAAe;AAC3B,WAAS;AACT,SAAO,CAAC,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC;GAClC;AAEF,QAAO;;;;;AC5HT,MAAM,qBAAqB,cAAkC,KAAK;;;;;;;;;;;;;;AAelE,SAAgB,oBAAoB,OAGrB;AACb,SAAQ,oBAAoB,MAAM,SAAS;AAE3C,QAAO,MAAM,YAAY;;;;;;;;;;;;AAa3B,SAAgB,iBAA8B;CAC5C,MAAM,WAAW,WAAW,mBAAmB;AAC/C,KAAI,CAAC,SACH,OAAM,IAAI,MACR,oFACD;AAEH,QAAO"}

package/lib/types/index.d.ts

@@ -0,0 +1,169 @@
+import { Computed } from "@pyreon/reactivity";
+import { VNodeChild } from "@pyreon/core";
+
+//#region src/types.d.ts
+/**
+ * A permission predicate — receives optional context and returns a boolean.
+ * Used for instance-level checks (e.g., "can update THIS post?").
+ */
+type PermissionPredicate<TContext = unknown> = (context?: TContext) => boolean;
+/**
+ * A permission value is either a static boolean or a predicate function.
+ * - `true` / `false` — static grant or denial
+ * - `(context?) => boolean` — dynamic, evaluated per-check
+ */
+type PermissionValue<TContext = unknown> = boolean | PermissionPredicate<TContext>;
+/**
+ * A map of permission keys to their values.
+ * Keys are dot-separated strings (e.g., 'posts.read', 'users.manage').
+ * Wildcards are supported: 'posts.*' matches any 'posts.X' key.
+ */
+type PermissionMap = Record<string, PermissionValue>;
+/**
+ * The permissions instance returned by `createPermissions()`.
+ * Callable — `can('posts.read')` returns a boolean, reactive in effects/computeds/JSX.
+ */
+interface Permissions {
+  /**
+   * Check if a permission is granted.
+   * Returns a boolean — reactive when read inside effects, computeds, or JSX `{() => ...}`.
+   *
+   * @param key - Permission key (e.g., 'posts.read')
+   * @param context - Optional context for predicate evaluation (e.g., a post instance)
+   *
+   * @example
+   * ```tsx
+   * can('posts.read')              // static check
+   * can('posts.update', post)      // instance check
+   * {() => can('posts.delete') && <DeleteButton />}
+   * ```
+   */
+  (key: string, context?: unknown): boolean;
+  /**
+   * Inverse check — returns true when the permission is denied.
+   *
+   * @example
+   * ```tsx
+   * can.not('billing.export')  // true if user cannot export
+   * ```
+   */
+  not: (key: string, context?: unknown) => boolean;
+  /**
+   * Check if ALL listed permissions are granted.
+   *
+   * @example
+   * ```tsx
+   * can.all('posts.read', 'posts.create')
+   * ```
+   */
+  all: (...keys: string[]) => boolean;
+  /**
+   * Check if ANY of the listed permissions is granted.
+   *
+   * @example
+   * ```tsx
+   * can.any('posts.update', 'posts.delete')
+   * ```
+   */
+  any: (...keys: string[]) => boolean;
+  /**
+   * Replace all permissions. All reactive reads update automatically.
+   *
+   * @example
+   * ```tsx
+   * can.set({ 'posts.read': true, 'users.manage': false })
+   * ```
+   */
+  set: (permissions: PermissionMap) => void;
+  /**
+   * Merge permissions into the current map.
+   * Existing keys are overwritten, new keys are added.
+   *
+   * @example
+   * ```tsx
+   * can.patch({ 'billing.export': true })
+   * ```
+   */
+  patch: (permissions: PermissionMap) => void;
+  /**
+   * All currently granted permission keys (static true + predicates that exist).
+   * Reactive signal — updates when permissions change.
+   *
+   * @example
+   * ```tsx
+   * // For help dialogs or admin dashboards
+   * can.granted()  // ['posts.read', 'posts.create', 'users.manage']
+   * ```
+   */
+  granted: Computed<string[]>;
+  /**
+   * All permission entries as [key, value] pairs.
+   * Reactive signal — updates when permissions change.
+   */
+  entries: Computed<[string, PermissionValue][]>;
+}
+//#endregion
+//#region src/permissions.d.ts
+/**
+ * Create a reactive permissions instance.
+ *
+ * The returned `can` function checks permissions reactively —
+ * reads update automatically when permissions change via `set()` or `patch()`.
+ *
+ * @param initial - Optional initial permission map
+ * @returns A callable `Permissions` instance
+ *
+ * @example
+ * ```tsx
+ * const can = createPermissions({
+ *   'posts.read': true,
+ *   'posts.update': (post: Post) => post.authorId === userId(),
+ *   'users.manage': false,
+ * })
+ *
+ * // Check (reactive in effects/computeds/JSX)
+ * can('posts.read')              // true
+ * can('posts.update', myPost)    // evaluates predicate
+ *
+ * // JSX
+ * {() => can('posts.delete') && <DeleteButton />}
+ *
+ * // Update
+ * can.set({ 'posts.read': true, 'admin': true })
+ * can.patch({ 'users.manage': true })
+ * ```
+ */
+declare function createPermissions(initial?: PermissionMap): Permissions;
+//#endregion
+//#region src/context.d.ts
+/**
+ * Provide a permissions instance to descendant components.
+ * Use this for SSR isolation or testing — each request/test gets its own instance.
+ *
+ * @example
+ * ```tsx
+ * const can = createPermissions({ ... })
+ *
+ * <PermissionsProvider instance={can}>
+ *   <App />
+ * </PermissionsProvider>
+ * ```
+ */
+declare function PermissionsProvider(props: {
+  instance: Permissions;
+  children?: VNodeChild;
+}): VNodeChild;
+/**
+ * Access the nearest permissions instance from context.
+ * Must be used within a `<PermissionsProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const can = usePermissions()
+ * {() => can('posts.read') && <PostList />}
+ * ```
+ */
+declare function usePermissions(): Permissions;
+//#endregion
+export { type PermissionMap, type PermissionPredicate, type PermissionValue, type Permissions, PermissionsProvider, createPermissions, usePermissions };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/permissions.ts","../../../src/context.ts"],"mappings":";;;;;;;AAQA;KAAY,mBAAA,wBACV,OAAA,GAAU,QAAA;;;;;;KAQA,eAAA,iCAER,mBAAA,CAAoB,QAAA;;AAFxB;;;;KAWY,aAAA,GAAgB,MAAA,SAAe,eAAA;;;;;UAQ1B,WAAA;EARQ;;;;AAQzB;;;;;;;;;;EARyB,CAuBtB,GAAA,UAAa,OAAA;EAAA;;;;;;;;EAUd,GAAA,GAAM,GAAA,UAAa,OAAA;EA8BA;;;;;;;;EApBnB,GAAA,MAAS,IAAA;EAiDkB;;;;;;ACrD7B;;EDcE,GAAA,MAAS,IAAA;ECd4D;;;;;;;;EDwBrE,GAAA,GAAM,WAAA,EAAa,aAAA;EExEL;;;;;;;;;EFmFd,KAAA,GAAQ,WAAA,EAAa,aAAA;EEjFrB;;;;;;AAiBF;;;;EF4EE,OAAA,EAAS,QAAA;;;;;EAMT,OAAA,EAAS,QAAA,UAAkB,eAAA;AAAA;;;;;;AAhH7B;;;;;;;;;AASA;;;;;;;;;AAWA;;;;;AAQA;;;iBC+BgB,iBAAA,CAAkB,OAAA,GAAU,aAAA,GAAgB,WAAA;;;;;AD3D5D;;;;;;;;;AASA;;iBEEgB,mBAAA,CAAoB,KAAA;EAClC,QAAA,EAAU,WAAA;EACV,QAAA,GAAW,UAAA;AAAA,IACT,UAAA;;;;AFMJ;;;;;AAQA;;iBEEgB,cAAA,CAAA,GAAkB,WAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/permissions",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Reactive permissions for Pyreon — type-safe, signal-driven, universal",
   "license": "MIT",
   "repository": {
@@ -42,11 +42,5 @@
   "peerDependencies": {
     "@pyreon/core": ">=0.5.0 <1.0.0",
     "@pyreon/reactivity": ">=0.5.0 <1.0.0"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^20.8.3",
-    "@pyreon/core": ">=0.5.0 <1.0.0",
-    "@pyreon/reactivity": ">=0.5.0 <1.0.0",
-    "@vitus-labs/tools-lint": "^1.11.0"
   }
 }

package/src/context.ts

@@ -1,10 +1,4 @@
-import {
-  createContext,
-  onUnmount,
-  popContext,
-  pushContext,
-  useContext,
-} from '@pyreon/core'
+import { createContext, provide, useContext } from '@pyreon/core'
 import type { VNodeChild } from '@pyreon/core'
 import type { Permissions } from './types'
 
@@ -27,11 +21,7 @@ export function PermissionsProvider(props: {
   instance: Permissions
   children?: VNodeChild
 }): VNodeChild {
-  const frame = new Map<symbol, unknown>([
-    [PermissionsContext.id, props.instance],
-  ])
-  pushContext(frame)
-  onUnmount(() => popContext())
+  provide(PermissionsContext, props.instance)
 
   return props.children ?? null
 }
@@ -50,7 +40,7 @@ export function usePermissions(): Permissions {
   const instance = useContext(PermissionsContext)
   if (!instance) {
     throw new Error(
-      '[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>',
+      '[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>.',
     )
   }
   return instance