Data and actions

On this page

Sources are the data pages can show; actions are what people can do, some of which change data. Both are declared on the contract, and both run through the application's own code, its bindings, with the person's own permissions. Planners see sources' schemas, never their rows, and nothing changes data without the person's yes.

Sources

A source is a typed read model: a flat row schema, the field that identifies a row, the field that names it, and what the binding can do by itself.

ts
export const sources = {
  orders: source({
    label: 'Orders',
    description: 'Orders customers placed, with their total and where they are in fulfillment',
    keywords: ['sales', 'purchases'],
    row: z.object({
      id: z.string(),
      number: z.number(),
      total: field.money({ currency: 'currency' }),
      currency: z.string(),
      status: field.enum(['pending', 'paid', 'shipped', 'canceled']),
      placed: field.time(),
      customer: field.ref('customers'),
    }),
    key: 'id',
    title: 'number',
    summary: ['total', 'status'],
    // What the API does itself; Uitive does the rest on the client.
    capabilities: {
      filter: { status: ['eq', 'in'], placed: ['gte', 'lt'], customer: ['eq'] },
      sort: ['placed'],
      pagination: 'offset',
    },
  }),
  customers: source({
    label: 'Customers',
    description: 'People who order from the shop',
    row: z.object({ id: z.string(), name: z.string(), email: z.string() }),
    key: 'id',
    title: 'name',
    // Orders show their customer's name, read by key rather than by scanning every customer.
    capabilities: { search: true, filter: { id: ['in'] }, pagination: 'offset' },
  }),
};

Field helpers say what a value means, so it shows and filters correctly. Plain zod types work too, with their meaning inferred: a string is text, a number is a number, a boolean is yes or no, an enum is an enum.

HelperWhat it holds
field.text()Text, such as a name
field.number()A number that isn't money, such as a count
field.money({ currency, code, minor })An amount: currency names the field with each row's currency, code fixes one, minor means cents
field.time({ unit })A moment: an ISO string, an ISO date with unit: 'date', or seconds or milliseconds with 's' or 'ms'
field.enum([...])One of a fixed set, such as a status
field.ref('customers')Another source's key, which makes a relation queries can follow one hop
field.bool()Yes or no

Every helper takes a label, shown as a column's header, and a description.

Minor units follow ISO 4217: two decimal places for most currencies, none for JPY or KRW, three for KWD. Where an API counts differently, digits says so per currency: Stripe, for one, keeps ISK in hundredths and MGA in whole units, so its amounts take field.money({ currency: 'currency', minor: true, digits: { ISK: 2, MGA: 0 } }). A z.iso.date() field is a day, read in the person's time zone.

  • title names a row, and summary lists the fields that sum it up; a relation one hop away can show only those.
  • capabilities declares what the binding does itself: which filters, which sorts, text search and paging. Uitive pushes those down and does the rest on the client, over at most scan rows (500 by default). A result cut short says it is partial: when the cap stops it, when a source without pagination fills its one page, or when related rows were left unread.
  • maxLimit caps the rows one query may ask for (100 by default), and ttl how many seconds a result stays fresh once it arrives (30 by default, and at least one).

Sources from an API description

With an OpenAPI description, sources and actions are generated rather than written: uitive survey lists what the description holds, a curation.json keeps what the interface shows, and uitive generate sources writes a module of sources, actions and endpoints to spread into the contract. Coding agents has the steps and every curation key.

Bindings

Bindings are the application's code behind the contract: fetch reads sources, perform runs actions, navigate follows links, and context says who and where the person is. For REST APIs, restFetch and restPerform take each endpoint as data, and read and write with the application's own session.

ts
// Reads and writes as the signed-in person, with the application's own session cookie.
export const bindings: Bindings<typeof shop> = {
  fetch: restFetch({
    base: '/api',
    credentials: 'include',
    sources: {
      orders: {
        path: '/orders',
        rows: '/orders',
        filters: {
          'status:eq': 'status',
          'status:in': 'status',
          'placed:gte': 'placed_after',
          'placed:lt': 'placed_before',
          'customer:eq': 'customer',
        },
        sort: { param: 'order', format: '-field' },
        pagination: { kind: 'offset', param: 'offset' },
        item: { path: '/orders/{id}', row: '/order' },
      },
      customers: {
        path: '/customers',
        rows: '/customers',
        search: 'q',
        filters: { 'id:in': 'id' },
        pagination: { kind: 'offset', param: 'offset' },
      },
    },
  }),
  perform: restPerform({
    base: '/api',
    credentials: 'include',
    actions: {
      'orders.note': { method: 'POST', path: '/orders/{order}/notes' },
      'orders.cancel': { method: 'POST', path: '/orders/{order}/cancel' },
    },
  }),
  // Who is signed in, for `$me`, and where they are, for "today" and time buckets.
  context: () => ({
    me: signedIn(),
    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  }),
};
  • filters maps a field and operator to a query parameter, such as placed:gte to placed_after; between maps to its own parameter, or to the field's gte and lte. Declare only what the endpoint applies, and declare the same in the source's capabilities: a filter, sort or search pushed to an endpoint that can't apply it fails rather than being dropped.
  • rows is a JSON pointer to the rows in a response; pick lifts nested values into fields, and query adds parameters every request needs.
  • pagination is cursor, offset, page or none. An API may cap its pages below the limit asked for, so point more at its has-more flag, or a cursor's next at its next token; without either, a short page is the last.
  • item reads one row by key; a row it answers 404 for is missing, not an error.
  • context() returns me, the signed-in person that $me names, timeZone, where "today" and time buckets fall, and locale. Each read passes it to fetch.
  • In restPerform, params fill the {placeholders} of the path and the rest go in the body, as JSON or a form.

For anything else, write the binding: a Fetch takes a request (the source, fields, filters, sort, limit, cursor and search it may apply) and returns rows; a Perform takes params and returns a message or where to go next. Params never fill a path with . or ... fromRows serves rows held in memory, for demonstrations and tests, comparing values exactly as an API would, and ignoring case only for contains and prefix.

Queries

A query is a question about one source, as plain data: fields, filters, sorts, a limit, search text and an optional summary. Pages use them, and so can your own components.

tsx
const unshipped = query('orders', {
  fields: ['orders.number', 'orders.total', 'orders.currency', 'orders.customer.name'],
  filter: [
    { field: 'orders.status', op: 'eq', values: ['paid'] },
    { field: 'orders.placed', op: 'lt', values: ['-2d'] },
  ],
  sort: [{ field: 'orders.placed', direction: 'asc' }],
  limit: 10,
});

Fields are qualified by source (orders.total) and may follow one relation (orders.customer.name). Values are text, parsed by each field's type when the query runs, so a saved "last two days" stays relative.

Field typeOperators
texteq, ne, in, nin, contains, prefix, empty, present
numbereq, ne, gt, gte, lt, lte, between, in, nin, empty, present
moneyeq, ne, gt, gte, lt, lte, between, empty, present
timegt, gte, lt, lte, between, empty, present
enum, refeq, ne, in, nin, empty, present
booleq, empty, present
  • Times take ISO dates and times, or values relative to now: now, today, yesterday, tomorrow, -7d or +3h (with m, h, d, w, mo, q and y), and start:month or start:week-1w, in the person's time zone. Days and longer move along the calendar, so -1d keeps the time of day across a daylight-saving change, and a time without an offset is the person's wall-clock time.
  • Money is in major units, with a point for decimals, such as 25.50: 25,50 is refused, since its comma may be a decimal comma. Text and enums ignore case; keys and references compare exactly.
  • Tokens: $current is the row the page is about, and $me the signed-in person, as context() names them. A query with $me fails while no one is signed in.
  • Summaries count, sum, average, take the minimum or maximum, or count distinct values, grouped by a field or a time bucket and optionally split by another. Money in different currencies is never added together: an amount one relation away is summed in its related row's currency, so its summary filters or groups by that currency, such as orders.customer.currency. Time buckets follow the person's wall clock, and rows without a time come last.
  • A query reads at most 12 fields, with 8 filters and 3 sorts; a page runs at most 8 queries.

useQuery reads a query's result in a component, shared and cached with every other reader:

tsx
/** Orders paid more than two days ago and not shipped, read with the person's own session. */
export function Unshipped() {
  const entry = useQuery(uitive, unshipped);
  if (!entry.result) return <p role="status">{entry.error ?? 'Loading'}</p>;
  return (
    <ul>
      {entry.result.rows.map((row) => (
        <li key={String(row['orders.number'])}>
          Order {String(row['orders.number'])} for {String(row['orders.customer.name'])}
        </li>
      ))}
    </ul>
  );
}

Outside React, client.data?.load(query) returns the result; client.data exists when the bindings can fetch.

Running actions

An action with an effect runs through perform.

EffectWhat happens
readIt runs at once, such as an export.
writeFrom a generated page, it waits for one yes, shown with its params: a confirmation, or a form showing every value.
destructiveIt waits for a typed phrase: the action's label, unless confirm says otherwise.

A run ends done, canceled by the person, failed in the binding or for want of one, or refused before it starts: when its params don't fit the action's schema, when no interface can ask for confirmation, when another run is already waiting, or while a redesign is being previewed. A run that succeeds is recorded as use, without its params, and invalidates refreshes results that read the sources it changed. Each run carries an idempotency key the binding may use to refuse doing it twice; restPerform sends it in the header its idempotency option names.

Generated pages ask through the confirmation interface you mount once: <Confirmations /> in React, <uitive-confirm> elsewhere. The application's own controls ask in their own way; send them through useAction, so their runs count as use:

tsx
/** The application's own button: it asks in its own way, and each run counts as use. */
export function CancelButton({ order }: { order: string }) {
  const cancel = useAction(uitive, 'orders.cancel');
  return (
    <button
      type="button"
      onClick={() => {
        if (window.confirm(`Cancel order ${order}?`)) void cancel({ order });
      }}
    >
      Cancel order
    </button>
  );
}

Actions without an effect belong to the interface, such as opening a page or choosing a tool. Record their use with client.record, or let perform call the binding for them too.