Patterns

These patterns combine flows and routes with the rest of Pawabase. Each is a full design you can copy.

Checkout

Goal: the user presses “Pay”. You must create an order, charge a card with a secret you cannot expose, and tell the user the result. Design:

The browser calls a route: POST /orders/{id}/pay.
The route runs a flow that loads the order from the database (never trusting a price from the browser), charges the card through the provider’s API with a secret, marks the order paid, and returns { status, receiptUrl }.
The browser shows the result.

async function pay(orderId: string) {
  const key = crypto.randomUUID();                       // one key per attempt, see below
  try {
    const { status, receiptUrl } = await pawabase.routes.post<{ status: string; receiptUrl: string }>(
      `orders/${orderId}/pay`,
      { method: "card", key },
      { idempotent: true, timeoutMs: 45_000 },
    );
    return { ok: status === "paid", receiptUrl };
  } catch (e) {
    if (e instanceof ApiError && e.code === "card_declined") return { ok: false, reason: "Your card was declined." };
    if (e instanceof ConflictError) return { ok: true };           // already paid
    throw e;
  }
}

The key lets the flow recognise a repeat of the same attempt and return the earlier result instead of charging twice. That is what makes idempotent: true safe. Without it, never set that flag on a payment.

Long-running work

Goal: “Export all my data” takes two minutes. A browser request should not wait that long. Design:

The browser calls flows.run("start-export"). The flow creates an exports record with status: "preparing", queues the real work in the background, and returns { exportId } immediately.
The background work builds the file, uploads it to storage, and updates the record to status: "ready" with the file’s key.
The browser watches that record (or a channel) and shows a download button when it is ready.

const { exportId } = await pawabase.flows.run<{ exportId: string }>("start-export", {});

const channel = pawabase.realtime.channel("resource:exports");
channel.on("message", async ({ event, payload }) => {
  const row = payload.record;
  if (row.id !== exportId || event === "deleted") return;
  if (row.status === "ready") {
    const { url } = await pawabase.storage.from("exports").createSignedUrl(row.file_key, { expiresIn: 300 });
    window.location.assign(url);
  } else if (row.status === "failed") {
    show("The export failed. Try again.");
  }
});
await channel.subscribe();

Keeping the state in a record is the key. If the person reloads the page or loses their connection, the app reads the record and shows the right thing, instead of losing track.

Safe retries

A network drop can leave you not knowing whether a POST arrived. Decide, per feature:

The call	If it might run twice	Do
Reads (`GET`)	Harmless	Let the client retry
Set a value (`PATCH`)	Harmless	`idempotent: true`
Create something	Duplicates	Send a unique `key`; the server returns the same result for the same key
Charge, send, publish	Harmful	Server-side idempotency key, then `idempotent: true`

The client already retries rate limits and 502/503/504 for you. The flag only matters for repeating a POST after the connection broke.

Cancel a request

Give long calls an AbortSignal so the user can back out, and so a component that unmounts does not leave work behind.

useEffect(() => {
  const controller = new AbortController();
  pawabase.routes
    .get("reports/summary", { signal: controller.signal })
    .then(setSummary)
    .catch((e) => { if (!(e instanceof AbortError)) setError(e); });
  return () => controller.abort();
}, []);

Optimistic UI

For quick actions, change the screen first, call the server, and undo if it fails.

async function like(post: Post) {
  setPost({ ...post, liked: true, likes: post.likes + 1 });
  try {
    await pawabase.routes.post(`posts/${post.id}/like`);
  } catch {
    setPost(post);                    // roll back
    show("Couldn't save your like.");
  }
}

Validate on the server, show on the client

The flow checks the input and answers with ValidationError and a field name. The client shows it next to the right input:

try {
  await pawabase.flows.run("profile-update", values);
} catch (e) {
  if (e instanceof ValidationError) setFieldErrors(e.byField());   // { displayName: ["too long"] }
}

Keep the same rules in the browser for quick feedback, but treat the server’s as the truth.

Act for the user on a server

When your own backend calls Pawabase for someone who is signed in to your app, send their token, so the same access rules apply:

const asUser = createClient({ url, apiKey: publishableKey, accessToken: userToken });
await asUser.routes.post("orders/42/pay", { method: "card" });

See Node.js.

Testing

Unit-test the logic itself where it is written.
Integration-test the contract from a script against a development environment: sign in as a test user, call the route, assert the result and the error codes.
Test refusals as carefully as successes: call with no sign-in, with the wrong user, with bad input. The access rule is a feature.

import { PermissionError } from "@pawabase/client";

it("won't let someone pay another person's order", async () => {
  const bob = await signedInClient("bob@example.com");
  await expect(bob.routes.post("orders/ADAS_ORDER/pay", {})).rejects.toBeInstanceOf(PermissionError);
});

Access rules

How a route or flow decides who may call it.

Errors

Every error type.

Server logic

Block reference

Checkout

Long-running work

Safe retries

Cancel a request

Optimistic UI

Validate on the server, show on the client

Act for the user on a server

Testing

Access rules

Errors

​Checkout

​Long-running work

​Safe retries

​Cancel a request

​Optimistic UI

​Validate on the server, show on the client

​Act for the user on a server

​Testing

Access rules

Errors

Checkout

Long-running work

Safe retries

Cancel a request

Optimistic UI

Validate on the server, show on the client

Act for the user on a server

Testing