operation refs

Expose a reviewed contract, not raw route exploration.

Registered operations are allowlisted REST or GraphQL templates. Client code calls a name or ref; the server resolves the template, substitutes variables, and executes through normal @async/db validation and shaping.

Operation source

{
  "name": "GetUserProfile",
  "ref": "users.profile.get",
  "method": "GET",
  "path": "/users/{id}.json",
  "query": {
    "select": "id,name,email"
  }
}

Client call

import { createDbClient } from '@async/db/client';
import operationRefs from './generated/db.operation-refs.json';

const db = createDbClient({ apiBase: '/api/db' });

await db.query(
  operationRefs.operations.GetUserProfile.ref,
  { id: 'u_1' },
);

Production contract checklist

build refs

Generate server-side registry output and browser-safe operation refs.

accept refs

Prefer `operations.acceptRefs: "ref"` for public clients.

lock raw rest

Set `server.expose.rest: "registered-only"` once raw routes should close.

own policy

Refs are not secrets. App code still owns auth, authorization, limits, and observability.