@pyreon/permissions 0.11.3 → 0.11.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/permissions",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Reactive permissions for Pyreon — type-safe, signal-driven, universal",
   "license": "MIT",
   "repository": {
@@ -41,13 +41,13 @@
     "lint": "biome check ."
   },
   "peerDependencies": {
-    "@pyreon/core": "^0.11.3",
-    "@pyreon/reactivity": "^0.11.3"
+    "@pyreon/core": "^0.11.4",
+    "@pyreon/reactivity": "^0.11.4"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.3",
-    "@pyreon/core": "^0.11.3",
-    "@pyreon/reactivity": "^0.11.3",
+    "@pyreon/core": "^0.11.4",
+    "@pyreon/reactivity": "^0.11.4",
     "@vitus-labs/tools-lint": "^1.11.0"
   }
 }

package/src/tests/api.test.ts

@@ -0,0 +1,362 @@
+import { computed, effect } from "@pyreon/reactivity"
+import { describe, expect, it } from "vitest"
+import { createPermissions } from "../index"
+
+describe("createPermissions — can.all()", () => {
+  it("returns true when all permissions are granted", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.create": true,
+      "posts.update": true,
+    })
+    expect(can.all("posts.read", "posts.create", "posts.update")).toBe(true)
+  })
+
+  it("returns false when any permission is denied", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.create": true,
+      "posts.delete": false,
+    })
+    expect(can.all("posts.read", "posts.create", "posts.delete")).toBe(false)
+  })
+
+  it("returns false when any permission is undefined", () => {
+    const can = createPermissions({ "posts.read": true })
+    expect(can.all("posts.read", "posts.create")).toBe(false) // posts.create undefined
+  })
+
+  it("returns true for empty args (vacuous truth)", () => {
+    const can = createPermissions()
+    expect(can.all()).toBe(true)
+  })
+
+  it("works with wildcards", () => {
+    const can = createPermissions({ "posts.*": true })
+    expect(can.all("posts.read", "posts.create")).toBe(true)
+    expect(can.all("posts.read", "users.manage")).toBe(false)
+  })
+
+  it("is reactive in effects", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.create": true,
+    })
+    const results: boolean[] = []
+
+    effect(() => {
+      results.push(can.all("posts.read", "posts.create"))
+    })
+
+    can.patch({ "posts.create": false })
+    expect(results).toEqual([true, false])
+  })
+
+  it("is reactive in computed", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.create": true,
+    })
+    const allGranted = computed(() => can.all("posts.read", "posts.create"))
+    expect(allGranted()).toBe(true)
+
+    can.patch({ "posts.create": false })
+    expect(allGranted()).toBe(false)
+  })
+})
+
+describe("createPermissions — can.any()", () => {
+  it("returns true when at least one permission is granted", () => {
+    const can = createPermissions({
+      "posts.read": false,
+      "posts.create": true,
+    })
+    expect(can.any("posts.read", "posts.create")).toBe(true)
+  })
+
+  it("returns false when no permissions are granted", () => {
+    const can = createPermissions({
+      "posts.read": false,
+      "posts.create": false,
+    })
+    expect(can.any("posts.read", "posts.create")).toBe(false)
+  })
+
+  it("returns true when all are granted", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.create": true,
+    })
+    expect(can.any("posts.read", "posts.create")).toBe(true)
+  })
+
+  it("returns false for empty args", () => {
+    const can = createPermissions({ "posts.read": true })
+    expect(can.any()).toBe(false)
+  })
+
+  it("works with undefined permissions", () => {
+    const can = createPermissions({ "posts.read": true })
+    expect(can.any("posts.read", "nonexistent")).toBe(true)
+    expect(can.any("nonexistent", "also-nonexistent")).toBe(false)
+  })
+
+  it("works with wildcards", () => {
+    const can = createPermissions({ "posts.*": true })
+    expect(can.any("posts.read", "users.manage")).toBe(true)
+    expect(can.any("users.read", "users.manage")).toBe(false)
+  })
+
+  it("is reactive in effects", () => {
+    const can = createPermissions({
+      "posts.read": false,
+      "posts.create": true,
+    })
+    const results: boolean[] = []
+
+    effect(() => {
+      results.push(can.any("posts.read", "posts.create"))
+    })
+
+    can.patch({ "posts.create": false })
+    expect(results).toEqual([true, false])
+  })
+})
+
+describe("createPermissions — can.not()", () => {
+  it("returns inverse of can()", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.delete": false,
+    })
+    expect(can.not("posts.read")).toBe(false)
+    expect(can.not("posts.delete")).toBe(true)
+  })
+
+  it("returns true for undefined permissions", () => {
+    const can = createPermissions()
+    expect(can.not("anything")).toBe(true)
+  })
+
+  it("works with context for predicate permissions", () => {
+    const can = createPermissions({
+      "posts.update": (post: any) => post?.authorId === "me",
+    })
+    expect(can.not("posts.update", { authorId: "me" })).toBe(false)
+    expect(can.not("posts.update", { authorId: "other" })).toBe(true)
+  })
+
+  it("is reactive", () => {
+    const can = createPermissions({ "posts.read": true })
+    const results: boolean[] = []
+
+    effect(() => {
+      results.push(can.not("posts.read"))
+    })
+
+    can.set({ "posts.read": false })
+    expect(results).toEqual([false, true])
+  })
+})
+
+describe("createPermissions — can.set()", () => {
+  it("replaces all permissions entirely", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "users.manage": true,
+    })
+
+    can.set({ "posts.read": false })
+    expect(can("posts.read")).toBe(false)
+    expect(can("users.manage")).toBe(false) // was not in new set
+  })
+
+  it("triggers reactive updates", () => {
+    const can = createPermissions({ "posts.read": true })
+    const results: boolean[] = []
+
+    effect(() => {
+      results.push(can("posts.read"))
+    })
+
+    can.set({ "posts.read": false })
+    can.set({ "posts.read": true })
+    expect(results).toEqual([true, false, true])
+  })
+
+  it("set with empty object removes all permissions", () => {
+    const can = createPermissions({ "posts.read": true, "users.manage": true })
+    can.set({})
+    expect(can("posts.read")).toBe(false)
+    expect(can("users.manage")).toBe(false)
+  })
+
+  it("set with predicates", () => {
+    const can = createPermissions({})
+    can.set({
+      "posts.update": (post: any) => post?.authorId === "me",
+    })
+    expect(can("posts.update", { authorId: "me" })).toBe(true)
+    expect(can("posts.update", { authorId: "other" })).toBe(false)
+  })
+})
+
+describe("createPermissions — can.patch()", () => {
+  it("merges with existing permissions", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "users.manage": false,
+    })
+
+    can.patch({ "users.manage": true, "billing.view": true })
+    expect(can("posts.read")).toBe(true) // unchanged
+    expect(can("users.manage")).toBe(true) // updated
+    expect(can("billing.view")).toBe(true) // added
+  })
+
+  it("overwrites existing keys", () => {
+    const can = createPermissions({ "posts.read": true })
+    can.patch({ "posts.read": false })
+    expect(can("posts.read")).toBe(false)
+  })
+
+  it("adds new keys without removing existing", () => {
+    const can = createPermissions({ a: true })
+    can.patch({ b: true })
+    expect(can("a")).toBe(true)
+    expect(can("b")).toBe(true)
+  })
+
+  it("triggers reactive updates", () => {
+    const can = createPermissions({ "posts.read": false })
+    const results: boolean[] = []
+
+    effect(() => {
+      results.push(can("posts.read"))
+    })
+
+    can.patch({ "posts.read": true })
+    expect(results).toEqual([false, true])
+  })
+
+  it("patch with predicates", () => {
+    const can = createPermissions({ "posts.read": true })
+    can.patch({
+      "posts.update": (post: any) => post?.draft === true,
+    })
+    expect(can("posts.read")).toBe(true)
+    expect(can("posts.update", { draft: true })).toBe(true)
+    expect(can("posts.update", { draft: false })).toBe(false)
+  })
+})
+
+describe("createPermissions — can.granted()", () => {
+  it("returns keys with true values", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.delete": false,
+      "users.manage": true,
+    })
+    const granted = can.granted()
+    expect(granted).toContain("posts.read")
+    expect(granted).toContain("users.manage")
+    expect(granted).not.toContain("posts.delete")
+  })
+
+  it("includes predicate keys (capabilities exist)", () => {
+    const can = createPermissions({
+      "posts.update": (post: any) => post?.authorId === "me",
+    })
+    expect(can.granted()).toContain("posts.update")
+  })
+
+  it("returns empty array for no permissions", () => {
+    const can = createPermissions()
+    expect(can.granted()).toEqual([])
+  })
+
+  it("returns empty array when all denied", () => {
+    const can = createPermissions({ a: false, b: false })
+    expect(can.granted()).toEqual([])
+  })
+
+  it("is reactive — updates on set()", () => {
+    const can = createPermissions({ "posts.read": true })
+    const results: string[][] = []
+
+    effect(() => {
+      results.push([...can.granted()])
+    })
+
+    can.set({ "posts.read": true, "users.manage": true })
+    expect(results).toHaveLength(2)
+    expect(results[1]).toEqual(expect.arrayContaining(["posts.read", "users.manage"]))
+  })
+
+  it("is reactive — updates on patch()", () => {
+    const can = createPermissions({ "posts.read": true })
+    const results: string[][] = []
+
+    effect(() => {
+      results.push([...can.granted()])
+    })
+
+    can.patch({ "users.manage": true })
+    expect(results).toEqual([["posts.read"], ["posts.read", "users.manage"]])
+  })
+})
+
+describe("createPermissions — can.entries()", () => {
+  it("returns all entries as [key, value] pairs", () => {
+    const can = createPermissions({
+      "posts.read": true,
+      "posts.delete": false,
+    })
+    const entries = can.entries()
+    expect(entries).toHaveLength(2)
+    expect(entries).toEqual(
+      expect.arrayContaining([
+        ["posts.read", true],
+        ["posts.delete", false],
+      ]),
+    )
+  })
+
+  it("returns empty array for no permissions", () => {
+    const can = createPermissions()
+    expect(can.entries()).toEqual([])
+  })
+
+  it("includes predicate entries", () => {
+    const pred = (post: any) => post?.authorId === "me"
+    const can = createPermissions({
+      "posts.update": pred,
+    })
+    const entries = can.entries()
+    expect(entries).toHaveLength(1)
+    expect(entries[0]?.[0]).toBe("posts.update")
+    expect(entries[0]?.[1]).toBe(pred)
+  })
+
+  it("is reactive — updates on mutations", () => {
+    const can = createPermissions({ a: true })
+    const counts: number[] = []
+
+    effect(() => {
+      counts.push(can.entries().length)
+    })
+
+    can.patch({ b: true })
+    can.patch({ c: false })
+    expect(counts).toEqual([1, 2, 3])
+  })
+
+  it("reflects set() replacement", () => {
+    const can = createPermissions({ a: true, b: true, c: true })
+    expect(can.entries()).toHaveLength(3)
+
+    can.set({ x: true })
+    expect(can.entries()).toHaveLength(1)
+    expect(can.entries()[0]?.[0]).toBe("x")
+  })
+})

package/src/tests/context.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest"
+import { createPermissions, usePermissions } from "../index"
+
+describe("usePermissions", () => {
+  it("throws when called outside PermissionsProvider", () => {
+    expect(() => usePermissions()).toThrow(
+      "[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>.",
+    )
+  })
+})
+
+describe("createPermissions used directly (no context)", () => {
+  it("works standalone without any provider", () => {
+    const can = createPermissions({ "posts.read": true })
+    expect(can("posts.read")).toBe(true)
+  })
+
+  it("multiple independent instances do not interfere", () => {
+    const canA = createPermissions({ "posts.read": true })
+    const canB = createPermissions({ "posts.read": false })
+
+    expect(canA("posts.read")).toBe(true)
+    expect(canB("posts.read")).toBe(false)
+
+    canA.set({ "posts.read": false })
+    expect(canA("posts.read")).toBe(false)
+    expect(canB("posts.read")).toBe(false) // unchanged, already false
+  })
+
+  it("set() on one instance does not affect another", () => {
+    const canA = createPermissions({ a: true, b: true })
+    const canB = createPermissions({ a: true, b: true })
+
+    canA.set({ a: false })
+    expect(canA("a")).toBe(false)
+    expect(canA("b")).toBe(false) // cleared by set
+
+    expect(canB("a")).toBe(true) // unaffected
+    expect(canB("b")).toBe(true)
+  })
+
+  it("patch() on one instance does not affect another", () => {
+    const canA = createPermissions({ shared: true })
+    const canB = createPermissions({ shared: true })
+
+    canA.patch({ shared: false })
+    expect(canA("shared")).toBe(false)
+    expect(canB("shared")).toBe(true) // unaffected
+  })
+})

package/src/tests/predicates.test.ts

@@ -0,0 +1,149 @@
+import { signal } from "@pyreon/reactivity"
+import { describe, expect, it } from "vitest"
+import { createPermissions } from "../index"
+
+describe("createPermissions — predicate permissions", () => {
+  describe("basic predicate evaluation", () => {
+    it("evaluates predicate with context argument", () => {
+      const can = createPermissions({
+        "posts.update": (post: any) => post?.authorId === "user-1",
+      })
+      expect(can("posts.update", { authorId: "user-1" })).toBe(true)
+      expect(can("posts.update", { authorId: "user-2" })).toBe(false)
+    })
+
+    it("predicate called without context receives undefined", () => {
+      const can = createPermissions({
+        "posts.update": (post?: any) => post?.authorId === "user-1",
+      })
+      // No context — post is undefined
+      expect(can("posts.update")).toBe(false)
+    })
+
+    it("predicate that ignores context (always true)", () => {
+      const can = createPermissions({
+        "posts.create": () => true,
+      })
+      expect(can("posts.create")).toBe(true)
+      expect(can("posts.create", { anything: true })).toBe(true)
+    })
+
+    it("predicate that ignores context (always false)", () => {
+      const can = createPermissions({
+        "posts.create": () => false,
+      })
+      expect(can("posts.create")).toBe(false)
+    })
+  })
+
+  describe("complex predicate logic", () => {
+    it("ownership check", () => {
+      const currentUserId = "user-42"
+      const can = createPermissions({
+        "posts.update": (post: any) => post?.authorId === currentUserId,
+        "posts.delete": (post: any) => post?.authorId === currentUserId && post?.status === "draft",
+      })
+
+      const myDraft = { authorId: "user-42", status: "draft" }
+      const myPublished = { authorId: "user-42", status: "published" }
+      const otherPost = { authorId: "user-99", status: "draft" }
+
+      expect(can("posts.update", myDraft)).toBe(true)
+      expect(can("posts.update", myPublished)).toBe(true)
+      expect(can("posts.update", otherPost)).toBe(false)
+      expect(can("posts.delete", myDraft)).toBe(true)
+      expect(can("posts.delete", myPublished)).toBe(false)
+      expect(can("posts.delete", otherPost)).toBe(false)
+    })
+
+    it("predicate with multiple conditions", () => {
+      const can = createPermissions({
+        "orders.refund": (order: any) => {
+          if (!order) return false
+          const isRecent = Date.now() - order.createdAt < 86400000
+          const isSmall = order.amount < 100
+          return isRecent && isSmall
+        },
+      })
+
+      const recentSmall = { createdAt: Date.now() - 1000, amount: 50 }
+      const recentLarge = { createdAt: Date.now() - 1000, amount: 200 }
+      const oldSmall = { createdAt: Date.now() - 100_000_000, amount: 50 }
+
+      expect(can("orders.refund", recentSmall)).toBe(true)
+      expect(can("orders.refund", recentLarge)).toBe(false)
+      expect(can("orders.refund", oldSmall)).toBe(false)
+    })
+
+    it("predicate referencing reactive signal", () => {
+      const role = signal("admin")
+      const can = createPermissions({
+        "users.manage": () => role.peek() === "admin",
+      })
+
+      expect(can("users.manage")).toBe(true)
+
+      role.set("viewer")
+      // Need to trigger version update for reactive tracking,
+      // but predicate re-evaluation on read still reflects signal state
+      can.patch({ "users.manage": () => role.peek() === "admin" })
+      expect(can("users.manage")).toBe(false)
+    })
+  })
+
+  describe("predicate error handling", () => {
+    it("returns false when predicate throws", () => {
+      const can = createPermissions({
+        "posts.update": () => {
+          throw new Error("boom")
+        },
+      })
+      expect(can("posts.update")).toBe(false)
+    })
+
+    it("returns false when predicate throws with context", () => {
+      const can = createPermissions({
+        "posts.update": (_post: any) => {
+          throw new TypeError("property access failed")
+        },
+      })
+      expect(can("posts.update", { id: 1 })).toBe(false)
+    })
+
+    it("can.not returns true when predicate throws", () => {
+      const can = createPermissions({
+        "posts.update": () => {
+          throw new Error("error")
+        },
+      })
+      expect(can.not("posts.update")).toBe(true)
+    })
+
+    it("other permissions unaffected when one predicate throws", () => {
+      const can = createPermissions({
+        "posts.read": true,
+        "posts.update": () => {
+          throw new Error("boom")
+        },
+        "posts.create": () => true,
+      })
+      expect(can("posts.read")).toBe(true)
+      expect(can("posts.update")).toBe(false)
+      expect(can("posts.create")).toBe(true)
+    })
+  })
+
+  describe("predicates in granted()", () => {
+    it("predicates count as capabilities in granted()", () => {
+      const can = createPermissions({
+        "posts.read": true,
+        "posts.update": (post: any) => post?.authorId === "me",
+        "posts.delete": false,
+      })
+      const granted = can.granted()
+      expect(granted).toContain("posts.read")
+      expect(granted).toContain("posts.update") // predicate = capability exists
+      expect(granted).not.toContain("posts.delete")
+    })
+  })
+})

package/src/tests/wildcards.test.ts

@@ -0,0 +1,141 @@
+import { effect } from "@pyreon/reactivity"
+import { describe, expect, it } from "vitest"
+import { createPermissions } from "../index"
+
+describe("createPermissions — wildcard matching", () => {
+  describe("prefix wildcard (posts.*)", () => {
+    it("matches any sub-key under the prefix", () => {
+      const can = createPermissions({ "posts.*": true })
+      expect(can("posts.read")).toBe(true)
+      expect(can("posts.create")).toBe(true)
+      expect(can("posts.update")).toBe(true)
+      expect(can("posts.delete")).toBe(true)
+    })
+
+    it("does not match keys without a dot", () => {
+      const can = createPermissions({ "posts.*": true })
+      expect(can("posts")).toBe(false) // no dot, no wildcard match
+    })
+
+    it("does not match different prefix", () => {
+      const can = createPermissions({ "posts.*": true })
+      expect(can("users.read")).toBe(false)
+      expect(can("comments.read")).toBe(false)
+    })
+
+    it("does not match partial prefix overlap", () => {
+      const can = createPermissions({ "post.*": true })
+      expect(can("posts.read")).toBe(false) // 'posts' !== 'post'
+    })
+
+    it("exact match takes precedence over wildcard", () => {
+      const can = createPermissions({
+        "posts.*": true,
+        "posts.delete": false,
+      })
+      expect(can("posts.read")).toBe(true)
+      expect(can("posts.create")).toBe(true)
+      expect(can("posts.delete")).toBe(false) // exact overrides wildcard
+    })
+
+    it("wildcard with predicate function", () => {
+      const can = createPermissions({
+        "posts.*": (post: any) => post?.status !== "archived",
+      })
+      expect(can("posts.read", { status: "published" })).toBe(true)
+      expect(can("posts.update", { status: "archived" })).toBe(false)
+      expect(can("posts.delete", { status: "draft" })).toBe(true)
+    })
+
+    it("multiple prefix wildcards for different namespaces", () => {
+      const can = createPermissions({
+        "posts.*": true,
+        "users.*": false,
+      })
+      expect(can("posts.read")).toBe(true)
+      expect(can("users.read")).toBe(false)
+    })
+  })
+
+  describe("global wildcard (*)", () => {
+    it("matches any key", () => {
+      const can = createPermissions({ "*": true })
+      expect(can("posts.read")).toBe(true)
+      expect(can("users.manage")).toBe(true)
+      expect(can("anything.at.all")).toBe(true)
+      expect(can("simple-key")).toBe(true)
+    })
+
+    it("exact match takes precedence over global wildcard", () => {
+      const can = createPermissions({
+        "*": true,
+        "billing.export": false,
+      })
+      expect(can("posts.read")).toBe(true)
+      expect(can("billing.export")).toBe(false)
+    })
+
+    it("prefix wildcard takes precedence over global wildcard", () => {
+      const can = createPermissions({
+        "*": false,
+        "posts.*": true,
+      })
+      expect(can("posts.read")).toBe(true)
+      expect(can("posts.create")).toBe(true)
+      expect(can("users.manage")).toBe(false) // falls to global *
+    })
+
+    it("resolution order: exact > prefix wildcard > global wildcard", () => {
+      const can = createPermissions({
+        "*": false,
+        "posts.*": true,
+        "posts.delete": false,
+      })
+      expect(can("posts.read")).toBe(true) // matched by posts.*
+      expect(can("posts.delete")).toBe(false) // exact match
+      expect(can("users.manage")).toBe(false) // matched by *
+    })
+
+    it("global wildcard with predicate", () => {
+      const can = createPermissions({
+        "*": (ctx: any) => ctx?.role === "admin",
+      })
+      expect(can("posts.read", { role: "admin" })).toBe(true)
+      expect(can("posts.read", { role: "viewer" })).toBe(false)
+    })
+  })
+
+  describe("wildcard reactivity", () => {
+    it("wildcards are reactive after set()", () => {
+      const can = createPermissions({ "posts.*": false })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can("posts.read"))
+      })
+
+      can.set({ "posts.*": true })
+      expect(results).toEqual([false, true])
+    })
+
+    it("wildcards are reactive after patch()", () => {
+      const can = createPermissions({ "posts.*": true })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can("posts.read"))
+      })
+
+      can.patch({ "posts.read": false }) // exact override
+      expect(results).toEqual([true, false])
+    })
+
+    it("removing wildcard via set() removes its effect", () => {
+      const can = createPermissions({ "posts.*": true })
+      expect(can("posts.read")).toBe(true)
+
+      can.set({}) // remove all permissions
+      expect(can("posts.read")).toBe(false)
+    })
+  })
+})