API reference

'use client';
 
import { useMemo } from 'react';
import type { ReactNode } from 'react';
import { hydratePolicy } from '@evanion/acl';
import type { Matrix } from '@evanion/acl';
import { PolicyProvider } from '@evanion/react-acl';
 
type Shopper = { id: string; role: 'customer' | 'bookseller' | 'owner' };
 
export function ShopAccess({
  matrix,
  shopper,
  now,
  children,
}: {
  matrix: Matrix;
  shopper: Shopper;
  now: string;
  children: ReactNode;
}) {
  // hydratePolicy validates, deep-clones and deep-freezes the document, so it
  // runs once per matrix rather than once per render.
  const access = useMemo(() => hydratePolicy(matrix), [matrix]);
  const context = useMemo(() => ({ now }), [now]);
 
  return (
    <PolicyProvider access={access} subject={shopper} context={context}>
      {children}
    </PolicyProvider>
  );
}

'use client';
 
import { useCan } from '@evanion/react-acl';
 
type Listing = { id: string; sellerId: string; status: 'draft' | 'published' };
 
export function EditControl({ listing }: { listing: Listing }) {
  const decision = useCan('listing', 'edit', listing);
 
  if (!decision.allowed) return null;
 
  return <button type="button">Edit listing</button>;
}

'use client';
 
import { useCanMany } from '@evanion/react-acl';
 
type Listing = { id: string; sellerId: string; status: 'draft' | 'published' };
 
export function ListingTable({ listings }: { listings: Listing[] }) {
  const decisions = useCanMany('listing', 'edit', listings);
 
  return (
    <ul>
      {listings.map((listing, index) => (
        <li key={listing.id}>
          {listing.id}
          {decisions[index]?.allowed ? (
            <button type="button">Edit</button>
          ) : null}
        </li>
      ))}
    </ul>
  );
}

'use client';
 
import { useCanFields } from '@evanion/react-acl';
 
type Listing = {
  id: string;
  blurb: string;
  price: number;
  sellerId: string;
  status: 'draft' | 'published';
};
 
export function ListingForm({ listing }: { listing: Listing }) {
  const decision = useCanFields('listing', 'edit', listing, 'write');
 
  // The field map carries a state for every field whatever the action decided,
  // so a form that reads it without this gate offers a write the engine
  // refused.
  if (!decision.action.allowed) {
    return <p>You cannot edit this listing.</p>;
  }
 
  return (
    <form>
      <label>
        Blurb
        <input
          name="blurb"
          defaultValue={listing.blurb}
          readOnly={decision.fields['blurb'] !== 'allowed'}
        />
      </label>
      <label>
        Price
        <input
          name="price"
          defaultValue={listing.price}
          readOnly={decision.fields['price'] !== 'allowed'}
        />
      </label>
    </form>
  );
}

'use client';
 
import { useCapabilities } from '@evanion/react-acl';
 
export function ShopMenu() {
  const capabilities = useCapabilities();
 
  return (
    <nav aria-label="Shop">
      {Object.entries(capabilities)
        .filter(([, decision]) => decision.allowed)
        .map(([key]) => (
          <a key={key} href={`/${key.replace('.', '/')}`}>
            {key}
          </a>
        ))}
    </nav>
  );
}

'use client';
 
import { policy } from '@evanion/acl';
import type { Action } from '@evanion/acl';
import { createPolicyContext } from '@evanion/react-acl';
 
type Shopper = { id: string; role: 'customer' | 'bookseller' | 'owner' };
type Listing = {
  id: string;
  sellerId: string;
  status: 'draft' | 'published';
  blurb: string;
};
 
type ShopObjects = { listing: Listing };
type ShopVerbs = { listing: Action | 'edit' };
 
export const shop = policy<Shopper, ShopObjects, ShopVerbs>()
  .for('listing', (p) =>
    p
      .allow('read', p.always)
      .allow('edit', p.eq('object.sellerId', 'subject.id'))
      .deny('edit', p.eq('object.status', 'published'))
      .fields(['blurb']),
  )
  .build();
 
// Shopper and the object map are named once, above. Nothing here repeats them.
export const { PolicyProvider: ShopAccess, useCan } = createPolicyContext(shop);
 
export function EditControl({ listing }: { listing: Listing }) {
  // 'listing' and 'edit' are checked against the policy. A typo in either is a
  // compile error here. The untyped useCan compiles it, and the evaluator
  // throws UnknownObjectKeyError or UnknownPermissionError at render.
  const decision = useCan('listing', 'edit', listing);
 
  if (!decision.allowed) return null;
 
  return <button type="button">Edit listing</button>;
}