defineIntent
Every field a mutation declares: what it writes, who may run it, and how much of it one caller gets.
A render cannot write — that is enforced by the type of the context a render receives — so every mutation is an intent, and intents are the only thing in this framework allowed to change anything.
A module under app/intents/ is the manifest. The id a client carries is intentId(module, export): six hex characters derived from the file path and the export name and from nothing else. So renaming the function changes the wire, and the wire never discloses a function name.
Three of the fields below declare something this deployment has to have bound, and each is refused rather than waved through when it is not: a capability with no check is E_NO_CAPABILITY_CHECK, a signature with no verifier is E_NO_VERIFIER, and a limit with nothing counting is E_NO_RATE_LIMIT.
import { defineIntent } from '@weftjs/core'
export const add = defineIntent<{ sku: string; qty: number }>({
name: 'cart.add', // for logs and `weft why`. Never on the wire
writes: ['cart'], // the complete set this may invalidate
capabilities: ['cart:write'], // refused unless `authority` is bound
limit: { max: 20, windowMs: 60_000 },
input: (raw) => parse(raw), // throwing here is a 422, not a 500
async run(ctx, { sku, qty }) {
await db.cart.add(ctx.session, sku, qty)
await ctx.revalidate('cart') // an undeclared tag throws
},
})A mutation, and the only thing in this framework allowed to write. writes is the complete set; an undeclared one throws.
| Field | Type | Required |
|---|---|---|
name | string | required |
writes | readonly string[] | required |
reads | readonly string[] | optional |
capabilities | readonly string[] | optional |
signed | boolean | optional |
input | (raw: unknown) => I | optional |
limit | IntentLimit | optional |
invalidatesAll | boolean | optional |
run | (ctx: IntentContext, input: I) => Promise<IntentResult | void> | IntentResult | void | required |
Read from packages/kernel/src/intent.ts · Intent
namerequired
Human-readable, for logs and weft why. Never on the wire.
name: 'cart.add'writesrequired
Tags this intent may invalidate. The complete set; anything else throws.
// The complete set. `ctx.revalidate('orders')` from here throws.
writes: ['cart', 'cart-count']readsoptional
Request state this intent reads. Declared for the same reason a fragment's reads are.
reads: ['session']capabilitiesoptional
Capabilities the caller must hold. Unchecked capabilities are refused, not waved through.
// Refused as E_NO_CAPABILITY_CHECK unless `authority` is bound.
capabilities: ['cart:write']signedoptional
Reachable only with a signed, expiring token this deployment minted. A different question from a capability, and both are asked. Declared and unverifiable is E_NO_VERIFIER.
// A token this deployment minted. There is no no-JavaScript path for a signed intent.
signed: trueinputoptional
Parse and validate the raw payload. Throwing here is E_INTENT_INPUT, a 422, not a 500.
// Throwing here is E_INTENT_INPUT — a 422, not a 500.
input: (raw) => {
const { sku, qty } = raw as { sku: unknown; qty: unknown }
if (typeof sku !== 'string') throw new Error('sku must be a string')
return { sku, qty: Number(qty) || 1 }
}limitoptional
How much traffic this mutation can take, over how long. Deliberately cannot say *whose* — that is the limits port's job. Declared and unenforceable is E_NO_RATE_LIMIT.
// What it is counted *against* is the deployment's, in `limits`.
limit: { max: 20, windowMs: 60_000 }invalidatesAlloptional
Invalidate every declared tag on success without naming them again.
// Every tag in `writes`, without naming them a second time.
invalidatesAll: truerunrequired
The mutation itself — the only thing allowed to change anything. ctx is the one context with a revalidate on it, which is how "a render cannot write" is enforced by the type system. Throwing is a 500; refusing input is input's job and is a 422.
async run(ctx, { sku, qty }) {
await db.cart.add(ctx.session, sku, qty)
await ctx.revalidate('cart')
return { redirect: '/cart' }
}