Skip to content

Workspaces

Most applications only need the default root workspace. The recommended VPerms API binds that scope once, so operations do not take a workspace ID:

import { createVPerms, DEFAULT_WORKSPACE_ID, VeguiPermsMemoryAdapter } from "vperms";
const adapter = new VeguiPermsMemoryAdapter();
const vperms = createVPerms({ adapter });
vperms.workspaceId === DEFAULT_WORKSPACE_ID; // true: "root"

Authorization domains, not feature namespaces

Section titled “Authorization domains, not feature namespaces”

Workspaces isolate complete authorization domains/applications. They are not intended to organize billing, users, admin or other modules inside one application. Use permission paths such as app.billing.read, app.billing.write, app.billing.*, users.* and admin.* for that.

Multiple workspaces are useful when applications or products share the same VeguiPerms infrastructure or adapter but require isolated subjects and grants. The same subject ID may exist independently in each workspace; inheritance and default parents resolve only inside the current workspace.

const appA = vperms.workspace("app-a");
const appB = vperms.workspace("app-b");
const alsoAppB = appA.workspace("app-b");
vperms.workspaceId; // "root", unchanged
appA.workspaceId; // "app-a"
alsoAppB.workspaceId; // "app-b", not a child of app-a
appA.service === appB.service; // true
const custom = createVPerms({ adapter, workspaceId: "my-app" });

Every workspace() call returns a new immutable VPerms instance sharing the same service and configuration. workspaceId and service are readonly. Workspace IDs must be non-empty and remain case-sensitive, as do subject IDs. Only permission paths are normalized to lowercase.

.service exposes the underlying VeguiPermsService for framework integrations and dynamic operations across many workspaces:

await vperms.can("user", "projects.read");
// Equivalent to:
await vperms.service.can(vperms.workspaceId, "user", "projects.read");

The raw service retains all existing explicit-workspace methods. You can also wrap an existing service without replacing it:

import { VeguiPermsService, VPerms } from "vperms";
const service = new VeguiPermsService({ adapter });
const scoped = new VPerms(service); // defaults to root
scoped.service === service; // true

VPerms delegates directly to this service; validation and authorization logic remain in the existing service and core engine. See the API reference.