The VPerms API
VPerms is the recommended application-facing API exported by vperms.
It binds a workspace once and delegates to VeguiPermsService, which owns
validation, permission resolution, inheritance, cycle protection and evaluation;
the adapter only persists data.
import { createVPerms, type SubjectResolver, SubjectType, VeguiPermsMemoryAdapter,} from "vperms";
const vperms = createVPerms({ adapter: new VeguiPermsMemoryAdapter(), defaultParents: { global: ["everyone"] },});Options
Section titled “Options”interface VPermsOptions { adapter: VeguiPermsAdapter; workspaceId?: string; // defaults to DEFAULT_WORKSPACE_ID ("root") defaultParents?: DefaultParents;}defaultParents is validated with DefaultParentsSchema when the service is
constructed. See Inheritance.
Methods
Section titled “Methods”| Method | Returns | Description |
|---|---|---|
can(subject, permission) |
Promise<boolean> |
Whether the subject may perform the permission. |
resolvePermissions(subject) |
Promise<ResolvedSubject> |
Full effective permission snapshot. |
saveSubject(subject) |
Promise<Subject> |
Create or update a subject. |
deleteSubject(subject) |
Promise<boolean> |
Delete a subject; true when it existed. |
setPermission(subject, permission, value) |
Promise<PermissionGrant> |
Upsert an allow/deny grant. |
unsetPermission(subject, permission) |
Promise<boolean> |
Remove a grant; true when it existed. |
Methods identifying a subject accept a raw subject id, an explicit
SubjectRef, or a domain object implementing
SubjectResolver; saveSubject accepts a
full record. All public inputs are validated
with Zod; invalid input throws a ZodError.
class User implements SubjectResolver<"user"> { constructor(public id: string, public email: string) {} getSubjectId() { return this.id; } getSubjectType() { return "user" as const; }}
await vperms.saveSubject({ id: "user", type: SubjectType.User, parents: ["developers"],});await vperms.saveSubject({ id: "developers", type: SubjectType.Group, parents: [] });await vperms.setPermission("developers", "posts.read", true);
await vperms.can(new User("user", "user@example.com"), "POSTS.READ"); // trueawait vperms.resolvePermissions("user");can() returns false when the adapter has no record for the subject.
resolvePermissions() throws SubjectNotFoundError in that case, because the
snapshot needs a subject record. Direct grants short-circuit inheritance; then
explicit, type-default and global-default layers are consulted in order.
Permissions are normalized to lowercase on writes and in resolved snapshots. Updating or removing a permission uses the same canonical path regardless of casing. See Permission normalization.
Workspaces and the raw service
Section titled “Workspaces and the raw service”Most applications use root. vperms.workspace(id) creates a new immutable
scope over the same service; it never changes the current instance. Use
permission paths for application features, not workspaces.
See Workspaces for isolated applications.
vperms.service is the readonly escape hatch to the existing low-level
VeguiPermsService, whose operations take the workspace ID first:
await vperms.service.can(vperms.workspaceId, "user", "posts.read");Request runtime (advanced)
Section titled “Request runtime (advanced)”The runtime helpers are shared by all framework integrations. They hydrate a request-scoped context exactly once per request.
import { createAbility, resolveRequestContext, resolveSubjectId,} from "vperms";
const ability = createAbility(vperms.service, vperms.workspaceId, "user");await ability.can("posts.read"); // memoized per permissioncreateAbility(service, workspaceId, subject) returns an Ability whose
can(permission) memoizes the promise, so the same permission is never
evaluated twice within a request.
resolveRequestContext performs the whole dance:
const context = await resolveRequestContext({ adapter, service: vperms.service, workspaceId: vperms.workspaceId, subject: await getCurrentUser(), // SubjectInput | null});
context.id; // resolved subject id ("anonymous" when subject was null)context.subject; // Subject record, or undefined when not persistedcontext.kind; // SubjectType, or undefinedcontext.ability; // AbilityWhen the resolver returns null/undefined, the anonymous subject is
loaded — created on demand with SubjectType.Anon via
ensureAnonymousSubject — so defaultParents.byType.anon applies
automatically. ANONYMOUS_SUBJECT_ID is "anonymous".
The Ability interface is intentionally minimal:
interface Ability { can(permission: string): Promise<boolean>;}Middleware, guards, decorators and permission-export handlers all reuse the same instance.