@vperms/react

@vperms/react exposes two entry points — @vperms/react (server, resolved under the react-server condition) and @vperms/react/client.

Server

interface ServerVPermsConfig extends VPermsConfig {
  cache?: CacheWrapper;
}

interface ServerVPerms {
  client: VPermsClient;
  getResolvedSubject(subjectId?): Promise<ResolvedSubject>;
  getAbility(subjectId?): Promise<PermissionAbility>;
  Provider: (props: { children?: ReactNode }) => Promise<ReactNode>;
  Ability: (props: AbilityProps) => Promise<ReactNode>;
}

function createVPerms(
  origin: string,
  config?: ServerVPermsConfig,
): ServerVPerms;

getResolvedSubject and getAbility are wrapped in React.cache by default, so a subject is resolved once per render.

Standalone exports getResolvedSubject, getAbility, Provider and ServerAbility (alias Ability) use the most recently created instance, or throw MISSING_INSTANCE_MESSAGE.

Client

interface ClientVPerms {
  client: VPermsClient;
  getResolvedSubject: VPermsClient["getResolvedSubject"];
  getAbility: VPermsClient["getAbility"];
  Provider: typeof AbilityProvider;
  Ability: typeof ClientAbility;
  useAbility: typeof useAbility;
}

function createVPerms(origin: string, config?: VPermsConfig): ClientVPerms;

function useAbility(): PermissionAbility;

useAbility throws MISSING_PROVIDER_MESSAGE when used outside AbilityProvider.

Components

interface AbilityProps {
  permission?: string;
  permissions?: string[];
  any?: boolean;
  fallback?: ReactNode;
  children?: ReactNode;
}

interface AbilityProviderProps {
  subject: ResolvedSubject;
  children?: ReactNode;
}

function AbilityProvider(props: AbilityProviderProps): JSX.Element;
function ClientAbility(props: AbilityProps): JSX.Element;
const Ability = ClientAbility;
function ServerAbility(props: AbilityProps): Promise<ReactNode>;

permission and permissions require all permissions by default; set any to require at least one. Denied renders fallback (or nothing).

Helpers

interface AbilityCheck {
  permission?: string;
  permissions?: string[];
  any?: boolean;
}

function abilityAllows(
  ability: PermissionAbility,
  check: AbilityCheck,
): boolean;

function getAbilityContext(): Context<PermissionAbility | null>;

abilityAllows combines permission and permissions, requires everything by default and short-circuits on any.

Constants

MISSING_INSTANCE_MESSAGE (server), MISSING_PROVIDER_MESSAGE (client).