snapshot(): Batch Checks in a Single Round-Trip

snapshot is the pattern for server-rendered frameworks and any code path that performs multiple authorization checks for the same principal. Instead of making a separate async call for each check, you call client.snapshot(principal) once, for a single provider round-trip, and then call .can(), .canAny(), .require(), and .requireAny() synchronously on the returned snapshot. Every check in the snapshot sees one consistent instant of the principal’s access data, which is a stronger per-request guarantee than calling can repeatedly against a TTL cache that may tick over mid-render.

`client.snapshot(principal, options?)`

async snapshot(
  principal: PrincipalRef,
  options?: SnapshotOptions<S>,
): Promise<AlfizSnapshot<K, P, S>>

PrincipalRef

required

Identifies who the snapshot is for. Either { userId: string } for a human user or { serviceId: string } for a machine principal.

readonly LooseScopeId<S>[]

Scope instances to pre-resolve for synchronous scoped checks. You only need to list scopes for hierarchical scope types, those whose catalog declaration has a non-null parent. Flat, top-level scope types (declared with parent: null) are resolved synchronously from the catalog without I/O, so you do not need to list them here. Scopes that appear in the principal’s own grant and revoke rows are always pre-resolved automatically.

boolean

default:"false"

When true, bypasses both the subject-closure cache and the object ancestor-chain cache, fetching fresh data from the provider. Equivalent to calling can.fresh for every check in the snapshot.

boolean

default:"true"

Whether checks made on this snapshot emit metrics observations. Inert unless the client was constructed with metrics. Snapshot checks are the render path’s conditional-UI traffic, the highest-volume shape there is, and what sampleRate.visibility exists for. Pass false to suppress the whole snapshot; view-as previews do this on the previewed subject’s side, so attribution never follows the preview.

Checking a hierarchical scope the snapshot has not resolved throws UnresolvedScopeError rather than evaluating a truncated chain, which would fail open on an ancestor revoke. Name those scopes in scopes, or extend the snapshot afterwards with await snap.resolve(scopes). The error carries the scope, its type, whether it is declared, and the scopes this snapshot can evaluate.

Return value

Promise<AlfizSnapshot>

A snapshot containing the compiled closure data and grant rows for the principal at the moment of the round-trip. Once resolved, all checks on the snapshot are synchronous.

Show AlfizSnapshot members

(key: K | readonly K[], scope?: LooseScopeId<S>) => boolean

Synchronous authorization gate. Agrees with client.can for every pre-resolved scope. Throws for unresolved hierarchical scopes. Call await snap.resolve([...scopes]) first.

(pattern: P) => boolean

Synchronous visibility affordance. Exact, not approximate: every granted scope’s chain was resolved at snapshot time. Never a gate. same rule as client.canAny.

(key: K | readonly K[], scope?: LooseScopeId<S>) => void

Throwing form of snap.can. Throws AccessDeniedError on denial.

(pattern: P) => void

Throwing form of snap.canAny.

(key: LooseKey<K>) => boolean

Returns true if the principal holds key at any scope. The single-key form of heldKeys.

ReadonlySet<PermissionKey>

Every concrete catalog key the principal holds somewhere. Computed once per snapshot on first access, the per-request cache for unscoped conditional UI.

(key: LooseKey<K>) => { granted: Set<ScopeId>, revoked: Set<ScopeId> }

Synchronous listing primitive, with the same result as client.grantedScopes but without an async call.

(key: LooseKey<K>, scope?) => CheckExplanation & { objectClosure, active, implied, impliedBy }

Synchronous explain, with the same result as client.explain.

(scopes: readonly LooseScopeId<S>[]) => Promise<this>

Extends the snapshot with additional pre-resolved chains, without re-fetching subject data. The data instant and evaluation clock are unchanged.

boolean

Whether the principal is active. Inactive principals return false for every check without a provider call.

number

The evaluation instant (epoch ms) used for grant expiry across every check in this snapshot.

PrincipalRef

The principal this snapshot was taken for.

When to use a snapshot

Use client.snapshot(principal) whenever a single request or render performs more than one check for the same principal:

RSC (React Server Component) renders that check multiple permissions in a single pass, inside .map() callbacks, conditional sections, and layout components.
List pages that render per-item action buttons (edit, delete, share) for every row in a result set.
Route loaders that guard the page and then conditionally load additional data based on permissions.
Any helper function that needs to call can without being async, pass the snapshot down instead of the client.

Use client.can / client.can.fresh directly when:

You need a single check and are not in a server render.
You are performing a destructive action and want fresh semantics for the entire snapshot (pass { fresh: true } to get this with a snapshot too).

Staleness and freshness

A snapshot is a point-in-time view of a principal’s access. It draws from the same caches as client.can, and a snapshot is one consistent instant of those caches, which is a stronger per-request guarantee (every check sees the same data), not a weaker one. For destructive actions within a render, do not re-use the snapshot. Use client.can.fresh(...) for the destructive gate, keeping the snapshot for read checks.

A snapshot captures the subject-closure data once. Do not reuse a snapshot across requests or background jobs. Take a fresh snapshot at the start of each request.

Examples

RSC page with multiple checks

// app/docs/[docId]/page.tsx (React Server Component)
export default async function DocPage({
  params,
}: {
  params: { docId: string };
}) {
  const { userId } = await getSession();
  const scope = `docs.doc:${params.docId}`;

  // One round-trip for all checks on this page. `docs.doc` is a HIERARCHICAL
  // scope type, so name it in `scopes`, and the snapshot resolves its ancestor
  // chain now, and every check below stays synchronous.
  const snap = await alfiz.snapshot({ userId }, { scopes: [scope] });

  // Gate the page.
  snap.require("docs.files.read", scope);

  const canEdit   = snap.can("docs.files.update_file", scope);
  const canDelete = snap.can("docs.files.delete",      scope);

  const doc = await db.docs.findById(params.docId);

  return (
    <DocView
      doc={doc}
      canEdit={canEdit}
      canDelete={canDelete}
    />
  );
}

List page with per-item action buttons

export default async function DocsListPage() {
  const { userId } = await getSession();

  // Snapshot pre-resolves all scopes in the principal's own grant rows.
  const snap = await alfiz.snapshot({ userId });

  snap.require("docs.files.read");

  const docs = await db.docs.findMany();

  // Pre-resolve the doc scopes for all rows in one call.
  await snap.resolve(docs.map((d) => `docs.doc:${d.id}`));

  return (
    <ul>
      {docs.map((doc) => {
        const scope = `docs.doc:${doc.id}`;
        return (
          <li key={doc.id}>
            {doc.title}
            {snap.can("docs.files.update_file", scope) && (
              <EditButton docId={doc.id} />
            )}
            {snap.can("docs.files.delete", scope) && (
              <DeleteButton docId={doc.id} />
            )}
          </li>
        );
      })}
    </ul>
  );
}

For large result sets (hundreds or thousands of rows), prefer pushing the filter into the database using client.grantedScopes rather than resolving a chain per row. snap.resolve is ideal for tens-of-rows cases or for enriching a snapshot mid-request with a small number of additional scopes.

Passing a snapshot to synchronous helpers

import type { SnapshotOf } from "@alfiz/core";
import { catalog } from "./catalog.js";

// SnapshotOf<typeof catalog> is the typed snapshot, with no hand-written params.
function renderActions(
  doc: Doc,
  snap: SnapshotOf<typeof catalog>,
): ActionItem[] {
  const scope = `docs.doc:${doc.id}`;
  const actions: ActionItem[] = [];
  if (snap.can("docs.files.update_file", scope)) actions.push("edit");
  if (snap.can("docs.files.delete",      scope)) actions.push("delete");
  return actions;
}

Fresh snapshot for just-in-time elevation

// Take a fresh snapshot when the user has just been granted temporary access.
const snap = await alfiz.snapshot(
  { userId },
  { fresh: true, scopes: [`docs.doc:${docId}`] },
);
snap.require("docs.files.read", `docs.doc:${docId}`);

Client API

Application

Catalog Definition

Static Verification

Alfiz Cloud API

snapshot(): Batch Checks in a Single Round-Trip

`client.snapshot(principal, options?)`

Return value

When to use a snapshot

Staleness and freshness

Examples

RSC page with multiple checks

List page with per-item action buttons

Passing a snapshot to synchronous helpers

Fresh snapshot for just-in-time elevation

​client.snapshot(principal, options?)

​Return value

​When to use a snapshot

​Staleness and freshness

​Examples

​RSC page with multiple checks

​List page with per-item action buttons

​Passing a snapshot to synchronous helpers

​Fresh snapshot for just-in-time elevation

`client.snapshot(principal, options?)`

Return value

When to use a snapshot

Staleness and freshness

Examples

RSC page with multiple checks

List page with per-item action buttons

Passing a snapshot to synchronous helpers

Fresh snapshot for just-in-time elevation