weft
ir 2.6.0 · warp 1.8.0
generatedread out of the source that implements it

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.

app/intents/cart.ts
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.

FieldTypeRequired
namestringrequired
writesreadonly string[]required
readsreadonly string[]optional
capabilitiesreadonly string[]optional
signedbooleanoptional
input(raw: unknown) => Ioptional
limitIntentLimitoptional
invalidatesAllbooleanoptional
run(ctx: IntentContext, input: I) => Promise<IntentResult | void> | IntentResult | voidrequired

Read from packages/kernel/src/intent.ts · Intent

namerequired

Type
string
Default
—

Human-readable, for logs and weft why. Never on the wire.

name: 'cart.add'

writesrequired

Type
readonly string[]
Default
—

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

Type
readonly string[]
Default
—

Request state this intent reads. Declared for the same reason a fragment's reads are.

reads: ['session']

capabilitiesoptional

Type
readonly string[]
Default
—

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

Type
boolean
Default
—

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: true

inputoptional

Type
(raw: unknown) => I
Default
—

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

Type
IntentLimit
Default
—

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

Type
boolean
Default
—

Invalidate every declared tag on success without naming them again.

// Every tag in `writes`, without naming them a second time.
invalidatesAll: true

runrequired

Type
(ctx: IntentContext, input: I) => Promise<IntentResult | void> | IntentResult | void
Default
—

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' }
}