Actions

An action is a named operation on your domain: what it accepts, what it returns, and the code that decides what changes. It is the only way data changes. The browser reads live, but it cannot write.

Why. A generic client write ("set status to paid") lets any screen or script change any field the rules allow. An action names the business operation (orders.pay), validates it and records who ran it. Reading the domain tells you every way its data can change.

import { domain, defineAction, i } from "@domainruntime/domain";
import { z } from "zod";

export default domain("orders")
  .withSchema({
    entities: {
      orders_order: i.entity({
        status: i.string().indexed(),
        total: i.number(),
        placedAt: i.date().indexed(),
      }),
    },
    links: {
      orders_orderOwner: {
        forward: { on: "orders_order", has: "one", label: "owner" },
        reverse: { on: "$users", has: "many", label: "orders" },
      },
    },
    rooms: {},
  })
  .withActions({
    place: defineAction({
      input: z.object({ orderId: z.string().uuid(), total: z.number().positive() }),
      output: z.object({ orderId: z.string() }),
      async execute({ input, runtime }) {
        const user = runtime.auth.user;
        if (!user) throw new Error("Sign in to place an order");

        await runtime.tx((tx) =>
          tx.orders_order[input.orderId]
            .update({ status: "open", total: input.total, placedAt: Date.now() })
            .link({ owner: user.id }),
        );
        return { orderId: input.orderId };
      },
    }),
  });

The caller picks orderId, a fresh UUID. Retries explains why.

async execute({ input, runtime }) {
  const user = runtime.auth.user;
  if (!user) throw new Error("Sign in to place an order");

  const db = await runtime.db();              // the caller-scoped database
  await db.transact(
    db.tx.orders_order[input.orderId]
      .update({ status: "open", total: input.total, placedAt: Date.now() })
      .link({ owner: user.id }),
  );
  return { orderId: input.orderId };
}

Calling an action

const { orderId } = await db.actions.orders.place({ orderId: crypto.randomUUID(), total: 120 });

The runtime checks the input against the schema before your code runs, and the output before it returns it. If your code throws, the execution ends failed with error code action_failed and your message, which the caller receives.

const result = await client.action("orders.place")({ orderId, total: 120 });
// { type: "result", result: { orderId } }

Inside execute

Reads and writes run as the caller, in development and in production: a query returns only what the caller could see, and a write fails if the caller's permissions forbid it. The execution then ends failed with action_failed.

runtime.auth

The caller is captured when the call is admitted and cannot change while the execution runs, even across a workflow's steps. runtime.auth is read-only.

Writing: runtime.tx

await runtime.tx((tx) => [
  tx.orders_order[orderId].create({ status: "open", total, placedAt: Date.now() }), // new object only
  tx.orders_order[orderId].update({ status: "paid" }),            // create or update
  tx.orders_order[orderId].merge({ meta: { paidBy: "card" } }),   // deep-merge a json attribute
  tx.orders_order[orderId].link({ owner: userId }),              // connect
  tx.orders_order[orderId].unlink({ owner: previousOwnerId }),   // disconnect
  tx.orders_order[orderId].delete(),                              // remove
]);

One runtime.tx is one transaction. Two calls are two transactions. If the second fails, the first stays applied. An action as a whole is not a transaction: changes that must succeed or fail together go in the same tx.

To address an object by a unique attribute instead of its id:

import { lookup } from "@instantdb/core";

tx.orders_customer[lookup("email", input.email)].update({ name: input.name });

If no object has that value yet, update creates one.

Retries and idempotency

Every call carries a request id (a UUID the client sends) and gets an execution record.

So the runtime never runs your code twice for one request, but a failed execution may have done part of its work, and the caller will retry with a new request id. Make that retry harmless:

• Put all of an action's writes in one runtime.tx when you can. A failure then leaves everything or nothing.
• Let the caller choose the id of what the action creates (orderId above), or address it by a .unique() attribute with lookup. A second run then updates the same object instead of creating another.

Do not check with a query and then create: two concurrent calls can both see "nothing there". See Guarantees.

Keeping implementations elsewhere

When an action grows, move its body to its own file. The domain still shows the contract:

import { placeOrder } from "./actions/place-order";

export default domain("orders")
  .withSchema({ /* … */ })
  .withActions({
    place: defineAction({
      input: z.object({ orderId: z.string().uuid(), total: z.number().positive() }),
      output: z.object({ orderId: z.string() }),
      execute: placeOrder,
    }),
  });

The Zod schemas are the contract; TypeScript infers the types from them. Do not declare separate input or output types.

Who may call an action

Every action in the published domain can be called by any identity of the environment: any signed-in user, or a service key. Deciding who may run it is your code's job, in the first lines of execute:

async execute({ input, runtime }) {
  const { user, admin } = runtime.auth;
  if (!user && !admin) throw new Error("Not signed in");
  if (user && user.claims.role !== "manager") throw new Error("Managers only");
  // ...
}

Permission rules protect the data; the check in execute protects the operation. Write both.

Exposing actions

withActions lists a domain's own actions. Including another domain brings its entities into scope; to offer its actions through your domain's typed client, re-expose them:

export default domain("shop")
  .includes(orders)
  .withSchema({ entities: {}, links: {}, rooms: {} })
  .withActions({ place: orders.actions.place });

The action keeps its id, orders.place. This shapes the typed client; it is not access control (see above).

Long-running work

An action should finish in seconds; a call waits up to 110 s. For work that waits on people, other systems or timers, make it a workflow.

Next

• Guarantees: what is atomic, what runs once, what is live.
• Error handling: failing on purpose, and what the caller sees.
• Patterns: ownership, idempotent creates, uniqueness, imports.