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.
Selecting another workspace
Section titled “Selecting another workspace”const appA = vperms.workspace("app-a");const appB = vperms.workspace("app-b");const alsoAppB = appA.workspace("app-b");
vperms.workspaceId; // "root", unchangedappA.workspaceId; // "app-a"alsoAppB.workspaceId; // "app-b", not a child of app-aappA.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.
Advanced raw service
Section titled “Advanced raw service”.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 rootscoped.service === service; // trueVPerms delegates directly to this service; validation and authorization logic
remain in the existing service and core engine. See the API reference.