@zap-studio/permit 0.3.3 → 1.0.0

package/CHANGELOG.md

@@ -1,98 +1,112 @@
-## @zap-studio/permit@0.3.3
+# Changelog
 
-### Migrate to ultracite lint/format
+All notable changes to this project will be documented in this file.
 
-Internal formatting and lint cleanup only. No public API or behavior change.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-# @zap-studio/permit
+## [1.0.0]
 
-## 0.3.2
+### Changed
 
-### Dependencies
+- Clarified tree-shakeable design in the package description and README (no code change).
 
-- Updated dependency `@zap-studio/validation` to `0.3.4`.
+### Removed
 
-## 0.3.1
+`assertNever` is no longer exported — it had no internal consumers and existed only as a generic exhaustiveness-check convenience. Use your own `never`-typed helper if you relied on it.
 
 ### Fixed
 
-- d10d8c4: Removed the TanStack Intent-specific authoring helper from the package surface.
-- d9ba7d1: Reworked the packaged permit skill content.
+Neither merge strategy short-circuits anymore. All policies now run concurrently via `Promise.allSettled`, and every policy is invoked regardless of outcome, for both `mergePoliciesSome` (allow) and `mergePoliciesEvery` (deny). A rejecting policy no longer sinks the whole check — it's treated as a deny (`false`) and logged with `console.warn`, consistent with how `createPolicy` handles internal validation/evaluation errors.
+
+## [0.3.4]
+
+### Added
+
+The package root now re-exports the full public API, so everything can be imported from `@zap-studio/permit` directly, including `PolicyError`, `assertNever`, and all public types. All exports are side-effect free and tree-shakeable; granular subpath imports keep working.
+
+- The implementation moved out of the entrypoint into two new subpaths: `./conditions` (`allow`, `deny`, `when`, `and`, `or`, `not`, `has`, `hasRole`, `collectInheritedRoles`) and `./policy` (`createPolicy`, `mergePolicies`, `mergePoliciesAny`).
+
+## [0.3.3]
+
+### Changed
+
+Internal formatting and lint cleanup only. No public API or behavior change.
+
+## [0.3.2]
+
+### Changed
+
+- Updated dependency `@zap-studio/validation` to `0.3.4`.
+
+## [0.3.1]
 
 ### Changed
 
 - 5fa58b1: Reduced policy evaluation complexity by extracting permission parsing and merge strategy helpers without changing the `policy.can(...)` API.
 - abfda4b: Cleaned up public option typings by removing redundant `| undefined` unions from package types.
 - 9f31f87: Switched the package build to ESNext-aligned output and updated package tooling and publish metadata.
+- d9ba7d1: Reworked the packaged permit skill content.
+- Updated dependency `@zap-studio/validation` to `0.3.3`.
 
-### Dependencies
+### Removed
 
-- Updated dependency `@zap-studio/validation` to `0.3.3`.
+- d10d8c4: Removed the TanStack Intent-specific authoring helper from the package surface.
 
-## 0.3.0
+## [0.3.0]
 
-### Minor Changes
+### Changed
 
-- fe60f55: Change `policy.can()` to use a single permission string plus the resource object.
+- fe60f55: **Breaking:** Changed `policy.can()` to use a single permission string plus the resource object.
 
   `policy.can(ctx, "read", "post", post)` is replaced by `policy.can(ctx, "post:read", post)`.
 
   This is a breaking API change in the `0.x` line. Docs and examples now use the new permission-string format consistently.
 
-## 0.2.2
+## [0.2.2]
 
-### Patch Changes
+### Changed
 
 - e26293e: Updated dependencies.
   - @zap-studio/validation@0.3.2
 
-## 0.2.1
+## [0.2.1]
 
-### Patch Changes
+### Changed
 
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-## 0.2.0
+## [0.2.0]
 
 ### Changed
 
 - f0f503e: Made policy evaluation asynchronous by default.
-
-### Breaking Changes
-
-- f0f503e: `policy.can(...)` now returns `Promise<boolean>`.
-- f0f503e: `createPolicy()` now uses async-safe Standard Schema validation for resource schemas (including async resource schemas); this is not a separate `Policy` schema API.
-- f0f503e: The `Policy` interface changed so `can()` is async, and `mergePolicies`/`mergePoliciesAny` are async accordingly.
+- f0f503e: **Breaking:** `policy.can(...)` now returns `Promise<boolean>`.
+- f0f503e: **Breaking:** `createPolicy()` now uses async-safe Standard Schema validation for resource schemas (including async resource schemas); this is not a separate `Policy` schema API.
+- f0f503e: **Breaking:** The `Policy` interface changed so `can()` is async, and `mergePolicies`/`mergePoliciesAny` are async accordingly.
 - Action required: callers must `await policy.can(...)` and handle `mergePolicies`/`mergePoliciesAny` as async operations; also account for async-safe resource schema validation in `createPolicy()`.
-
-### Dependencies
-
 - f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
-## 0.1.3
+## [0.1.3]
 
-### Dependencies
+### Changed
 
 - e4542bb: Updated dependency `@zap-studio/validation` to `0.2.1`.
 
-## 0.1.2
+## [0.1.2]
 
 ### Changed
 
 - 2de8183: Adopted shared synchronous Standard Schema validator utilities from `@zap-studio/validation` for resource schema validation in `createPolicy`.
-
-### Dependencies
-
 - 2de8183: Updated dependency `@zap-studio/validation` to `0.2.0`.
 
-## 0.1.1
+## [0.1.1]
 
 ### Fixed
 
 - 907d903: Added runtime resource validation and fail-closed behavior, including deny-by-default when merges are invoked with no policies.
 
-## 0.1.0
+## [0.1.0]
 
 ### Added
 

package/README.md

@@ -2,137 +2,93 @@
 
 A type-safe, declarative authorization library for TypeScript with [Standard Schema](https://standardschema.dev/) support.
 
-## Features
-
-- Full type safety with TypeScript
-- Standard Schema support (Zod, Valibot, ArkType, etc.)
-- Declarative policy definitions
-- Role hierarchy support
-- Composable conditions (`and`, `or`, `not`)
-- Policy merging strategies
+Full documentation: [zapstudio.dev/permit](https://www.zapstudio.dev/permit)
 
 ## Installation
 
 ```bash
-pnpm add @zap-studio/permit
-# or
 npm install @zap-studio/permit
 ```
 
+You also need a schema library that implements [Standard Schema](https://standardschema.dev/), such as Zod, Valibot, or ArkType.
+
+## Features
+
+- **Full type safety** — actions, resources, and permissions are inferred from your schemas and `satisfies` declarations.
+- **Standard Schema support** via `Resources` — works with Zod, Valibot, ArkType, or any compatible library.
+- **Declarative policies** through `createPolicy(...)` with `allow()`, `deny()`, and `when(condition)`.
+- **Role hierarchy support** via `hasRole(role, hierarchy?)`, with inheritance resolved by `collectInheritedRoles`.
+- **Composable conditions** via `and`, `or`, and `not`.
+- **Policy merging strategies** via `mergePoliciesAnd` and `mergePoliciesOr`.
+- **Structured errors** with `PolicyError` for invalid configuration or evaluation failures.
+- **Tree-shakeable** — policies and conditions are plain functions; unused exports are dropped by any modern bundler.
+
 ## Quick Start
 
 ```ts
 import { z } from "zod";
 import { createPolicy, allow, deny, when } from "@zap-studio/permit";
-import type { Resources, Actions } from "@zap-studio/permit/types";
+import type { Resources, Actions } from "@zap-studio/permit";
 
-// 1. Define your resource schemas
 const resources = {
-  post: z.object({
-    id: z.string(),
-    authorId: z.string(),
-    visibility: z.enum(["public", "private"]),
-  }),
-  comment: z.object({
-    id: z.string(),
-    postId: z.string(),
-    authorId: z.string(),
-  }),
+  post: z.object({ id: z.string(), authorId: z.string() }),
 } satisfies Resources;
 
-// 2. Define actions per resource
 const actions = {
   post: ["read", "write", "delete"],
-  comment: ["read", "write"],
 } as const satisfies Actions<typeof resources>;
 
-// 3. Define your context type
-type AppContext = {
-  user: { id: string; role: "guest" | "user" | "admin" };
-};
+type AppContext = { user: { id: string } };
 
-// 4. Create your policy
 const policy = createPolicy<AppContext>({
   resources,
   actions,
   rules: {
     post: {
-      read: when((ctx, action, resource) => resource.visibility === "public"),
-      write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
-      delete: deny(),
-    },
-    comment: {
       read: allow(),
       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+      delete: deny(),
     },
   },
 });
 
-// 5. Check permissions
-const ctx: AppContext = { user: { id: "user-1", role: "user" } };
-const post = { id: "1", authorId: "user-1", visibility: "public" as const };
+const ctx: AppContext = { user: { id: "user-1" } };
+const post = { id: "1", authorId: "user-1" };
 
-await policy.can(ctx, "post:read", post); // true
-await policy.can(ctx, "post:write", post); // true (user is author)
-await policy.can(ctx, "post:delete", post); // false (always denied)
+await policy.can(ctx, "post:write", post); // true, inferred as boolean
 ```
 
-## API Reference
-
-### Policy Builders
+## Declarative Policies
 
-#### `allow()`
-
-Returns a policy function that always allows the action.
+Through `createPolicy(...)` with `allow()`, `deny()`, and `when(condition)`.
 
 ```ts
 rules: {
   post: {
-    read: allow(), // Anyone can read
+    read: allow(),
+    delete: deny(),
+    write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
   },
 }
 ```
 
-#### `deny()`
+## Role Hierarchy Support
 
-Returns a policy function that always denies the action.
+Via `hasRole(role, hierarchy?)`, with inheritance resolved by `collectInheritedRoles`.
 
 ```ts
-rules: {
-  post: {
-    delete: deny(), // No one can delete
-  },
-}
-```
-
-#### `when(condition)`
-
-Returns a policy function that allows or denies based on a condition.
+const hierarchy = { guest: [], user: ["guest"], admin: ["user"] };
 
-```ts
 rules: {
   post: {
-    write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+    read: when(hasRole("guest", hierarchy)), // admins and users inherit guest access
   },
 }
 ```
 
-### Condition Combinators
+## Composable Conditions
 
-#### `and(...conditions)`
-
-Returns a condition that is true only if all conditions are true.
-
-```ts
-const isOwnerAndPublished = and(
-  (ctx, action, resource) => ctx.user.id === resource.authorId,
-  (ctx, action, resource) => resource.status === "published"
-);
-```
-
-#### `or(...conditions)`
-
-Returns a condition that is true if any condition is true.
+Via `and`, `or`, and `not`.
 
 ```ts
 const isOwnerOrAdmin = or(
@@ -141,130 +97,52 @@ const isOwnerOrAdmin = or(
 );
 ```
 
-#### `not(condition)`
-
-Returns a condition that negates another condition.
-
-```ts
-const isNotOwner = not(
-  (ctx, action, resource) => ctx.user.id === resource.authorId
-);
-```
-
-### Context Helpers
-
-#### `has(key, value)`
-
-Checks if a context property equals a specific value.
-
-```ts
-rules: {
-  post: {
-    write: when(has("role", "admin")),
-  },
-}
-```
-
-#### `hasRole(role, hierarchy?)`
-
-Checks if the user has a specific role, with optional hierarchy support.
-
-```ts
-const hierarchy = {
-  guest: [],
-  user: ["guest"],
-  admin: ["user"],
-};
-
-rules: {
-  post: {
-    read: when(hasRole("guest", hierarchy)), // Admins and users inherit guest permissions
-  },
-}
-```
-
-### Policy Merging
-
-#### `mergePolicies(...policies)`
+## Policy Merging Strategies
 
-Merges policies with "deny-overrides" strategy. All policies must allow for the action to be permitted.
+Via `mergePoliciesAnd` and `mergePoliciesOr`.
 
 ```ts
-const merged = mergePolicies(basePolicy, restrictivePolicy);
+const merged = mergePoliciesAnd(basePolicy, restrictivePolicy);
 ```
 
-#### `mergePoliciesAny(...policies)`
-
-Merges policies with "allow-overrides" strategy. Any policy allowing is sufficient.
-
-```ts
-const merged = mergePoliciesAny(guestPolicy, memberPolicy);
-```
-
-## Type Helpers
-
-### `Resources`
+## Standard Schema Support
 
-Type helper for defining resource schemas with `satisfies`.
+Works with Zod, Valibot, ArkType, or any compatible library.
 
 ```ts
+// Zod, Valibot, ArkType, or any Standard Schema-compatible library
 const resources = {
   post: z.object({ id: z.string() }),
 } satisfies Resources;
 ```
 
-### `Actions<TResources>`
-
-Type helper for defining actions with `satisfies`. Ensures action keys match resource keys.
-
-```ts
-const actions = {
-  post: ["read", "write"],
-} as const satisfies Actions<typeof resources>;
-```
-
-### `InferResource<TResources, K>`
+## Structured Errors
 
-Infers the TypeScript type for a specific resource.
+`PolicyError` for invalid configuration or evaluation failures.
 
 ```ts
-type Post = InferResource<typeof resources, "post">;
-// { id: string }
-```
+import { PolicyError } from "@zap-studio/permit";
 
-### `InferAction<TActions, K>`
-
-Infers the action union type for a specific resource.
-
-```ts
-type PostAction = InferAction<typeof actions, "post">;
-// "read" | "write"
+try {
+  const policy = createPolicy(config);
+  await policy.can(ctx, "post:read", post);
+} catch (error) {
+  if (error instanceof PolicyError) console.error(error.message);
+}
 ```
 
-## Standard Schema Support
-
-This library uses [Standard Schema](https://standardschema.dev/) for resource validation, which means it works with any compatible schema library:
+## Runtime Support
 
-- [Zod](https://zod.dev/)
-- [Valibot](https://valibot.dev/)
-- [ArkType](https://arktype.io/)
+| Runtime            | Minimum version                                  |
+| ------------------ | ------------------------------------------------ |
+| Node.js            | 18.0.0                                           |
+| Bun                | 1.0.0                                            |
+| Deno               | 1.42                                             |
+| Cloudflare Workers | Any current release                              |
+| Browsers           | Latest evergreen (Chrome, Edge, Firefox, Safari) |
 
-```ts
-// With Zod
-import { z } from "zod";
-const resources = {
-  post: z.object({ id: z.string() }),
-} satisfies Resources;
+The package ships standard ESM only and uses no runtime-specific APIs. Deno 1.42 is the first release that can install packages from JSR (`deno add jsr:@zap-studio/permit`).
 
-// With Valibot
-import * as v from "valibot";
-const resources = {
-  post: v.object({ id: v.string() }),
-} satisfies Resources;
+## License
 
-// With ArkType
-import { type } from "arktype";
-const resources = {
-  post: type({ id: "string" }),
-} satisfies Resources;
-```
+MIT

package/dist/{index.d.mts → conditions.d.ts}

@@ -1,5 +1,5 @@
-import { Actions, ConditionFn, Context, PermitConfig, Policy, PolicyFn, Resources, Role, RoleHierarchy } from "./types.mjs";
-//#region src/index.d.ts
+import { ConditionFn, Context, HasRoleFn, PolicyFn, Role, RoleHierarchy } from "./types.js";
+//#region src/conditions.d.ts
 /**
  * Returns a policy function that always allows the action.
  *
@@ -133,17 +133,6 @@ declare const has: <TContext extends Context, K extends keyof TContext>(key: K,
  * ```
  */
 declare const collectInheritedRoles: <TRole extends Role = Role>(roles: TRole[], hierarchy: RoleHierarchy<TRole>) => Set<TRole>;
-/**
- * Call signatures for {@link hasRole}, preserving the with/without hierarchy overloads.
- */
-interface HasRoleFn {
-  <TContext extends {
-    role: Role | Role[];
-  }, TAction extends string = string, TResource = unknown>(role: Role): ConditionFn<TContext, TAction, TResource>;
-  <TContext extends {
-    role: TRole | TRole[];
-  }, TAction extends string = string, TResource = unknown, TRole extends Role = Role>(role: TRole, hierarchy: RoleHierarchy<TRole>): ConditionFn<TContext, TAction, TResource>;
-}
 /**
  * Returns a condition function that checks if the user has a specific role.
  * Supports role hierarchy for inherited permissions.
@@ -172,90 +161,6 @@ interface HasRoleFn {
  * ```
  */
 declare const hasRole: HasRoleFn;
-/**
- * Creates a type-safe policy from resource schemas, actions, and rules.
- *
- * @example
- * ```ts
- * import { z } from "zod";
- * import { createPolicy, allow, deny, when } from "@zap-studio/permit";
- * import type { Resources, Actions } from "@zap-studio/permit/types";
- *
- * // Define resource schemas
- * const resources = {
- *   post: z.object({
- *     id: z.string(),
- *     authorId: z.string(),
- *     visibility: z.enum(["public", "private"]),
- *   }),
- *   comment: z.object({
- *     id: z.string(),
- *     postId: z.string(),
- *     authorId: z.string(),
- *   }),
- * } satisfies Resources;
- *
- * // Define actions per resource
- * const actions = {
- *   post: ["read", "write", "delete"],
- *   comment: ["read", "write"],
- * } as const satisfies Actions<typeof resources>;
- *
- * // Define context type
- * type AppContext = { user: { id: string; role: string } };
- *
- * // Create the policy
- * const policy = createPolicy<AppContext>({
- *   resources,
- *   actions,
- *   rules: {
- *     post: {
- *       read: when((ctx, action, resource) => resource.visibility === "public"),
- *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
- *       delete: deny(),
- *     },
- *     comment: {
- *       read: allow(),
- *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
- *     },
- *   },
- * });
- *
- * // Check permissions
- * const post = { id: "1", authorId: "user-1", visibility: "public" as const };
- * await policy.can(ctx, "post:read", post); // true
- * await policy.can(ctx, "post:write", post); // depends on ctx.user.id
- * ```
- */
-declare const createPolicy: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(config: PermitConfig<TContext, TResources, TActions>) => Policy<TContext, TResources, TActions>;
-/**
- * Merges multiple policies into one using "deny-overrides" strategy.
- * If any policy denies, the merged policy denies. All must allow for the result to allow.
- *
- * @example
- * ```ts
- * const basePolicy = createPolicy({ ... });
- * const adminPolicy = createPolicy({ ... });
- *
- * const merged = mergePolicies(basePolicy, adminPolicy);
- * // Both policies must allow for the action to be permitted
- * ```
- */
-declare const mergePolicies: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(...policies: Policy<TContext, TResources, TActions>[]) => Policy<TContext, TResources, TActions>;
-/**
- * Merges multiple policies into one using "allow-overrides" strategy.
- * If any policy allows, the merged policy allows. All must deny for the result to deny.
- *
- * @example
- * ```ts
- * const guestPolicy = createPolicy({ ... });
- * const memberPolicy = createPolicy({ ... });
- *
- * const merged = mergePoliciesAny(guestPolicy, memberPolicy);
- * // If either policy allows, the action is permitted
- * ```
- */
-declare const mergePoliciesAny: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(...policies: Policy<TContext, TResources, TActions>[]) => Policy<TContext, TResources, TActions>;
 //#endregion
-export { allow, and, collectInheritedRoles, createPolicy, deny, has, hasRole, mergePolicies, mergePoliciesAny, not, or, when };
-//# sourceMappingURL=index.d.mts.map
+export { allow, and, collectInheritedRoles, deny, has, hasRole, not, or, when };
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","names":[],"sources":["../src/conditions.ts"],"mappings":";;;;;;;;;;;;;;;;;;cAgCa,QAET,iBAAiB,SACjB,iCACA,0BACG,SAAS,UAAU,SAAS;;;;;;;;;;;;;;;;;cAoBtB,OAET,iBAAiB,SACjB,iCACA,0BACG,SAAS,UAAU,SAAS;;;;;;;;;;;;;;;;;cAoBtB,OAET,iBAAiB,SACjB,iCACA,qBAEA,WAAW,YAAY,UAAU,SAAS,eACzC,SAAS,UAAU,SAAS;;;;;;;;;;;;;;;;;;cAqBpB,MAET,iBAAiB,SACjB,iCACA,wBAEG,YAAY,YAAY,UAAU,SAAS,iBAC7C,YAAY,UAAU,SAAS;;;;;;;;;;;;;;;;;;cAqBvB,KAET,iBAAiB,SACjB,iCACA,wBAEG,YAAY,YAAY,UAAU,SAAS,iBAC7C,YAAY,UAAU,SAAS;;;;;;;;;;;;;;;cAkBvB,MAET,iBAAiB,SACjB,iCACA,qBAEA,WAAW,YAAY,UAAU,SAAS,eACzC,YAAY,UAAU,SAAS;;;;;;;;;;;;;cAgBvB,MACV,iBAAiB,SAAS,gBAAgB,UACzC,KAAK,GACL,OAAO,SAAS,OACf,YAAY;;;;;;;;;;;;;;;;;;cAqBJ,wBAAyB,cAAc,OAAO,MACzD,OAAO,SACP,WAAW,cAAc,WACxB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgDM,SAAS"}