@fabrika/app 0.3.3 → 0.4.0

package/src/jobs/schedule.ts

@@ -0,0 +1,129 @@
+// The five-field cron expressions of `c.cron`, read in UTC: which minutes a job is due, so the runner can tell how
+// long ago it should last have succeeded. The crontab, not this module, triggers a run.
+
+interface Field {
+	readonly min: number
+	readonly max: number
+}
+
+const MINUTE: Field = { min: 0, max: 59 }
+const HOUR: Field = { min: 0, max: 23 }
+const DAY_OF_MONTH: Field = { min: 1, max: 31 }
+const MONTH: Field = { min: 1, max: 12 }
+// 7 is Sunday too, as in Vixie cron; it is folded into 0 below.
+const DAY_OF_WEEK: Field = { min: 0, max: 7 }
+
+const NUMBER = /^\d+$/
+const MINUTE_MS = 60_000
+/** How far back a due minute is looked for: a schedule that matches nothing in that window has no period. */
+const SEARCH_DAYS = 366 * 5
+
+export interface CronSchedule {
+	readonly minutes: ReadonlySet<number>
+	readonly hours: ReadonlySet<number>
+	readonly daysOfMonth: ReadonlySet<number>
+	readonly months: ReadonlySet<number>
+	readonly daysOfWeek: ReadonlySet<number>
+	/** Both day fields name days: a day is due when either matches (Vixie cron). */
+	readonly eitherDay: boolean
+}
+
+function number(text: string, field: Field): number | null {
+	if (!NUMBER.test(text)) {
+		return null
+	}
+	const value = Number.parseInt(text, 10)
+	return value >= field.min && value <= field.max ? value : null
+}
+
+/** `*`, `n`, `a-b`, each optionally `/step`, separated by commas; `null` for anything else. */
+function parseField(text: string, field: Field): Set<number> | null {
+	const values = new Set<number>()
+	for (const item of text.split(',')) {
+		const [range = '', step, extra] = item.split('/')
+		if (extra !== undefined) {
+			return null
+		}
+		const every = step === undefined ? 1 : number(step, { min: 1, max: field.max + 1 })
+		if (every === null) {
+			return null
+		}
+		let from: number | null = field.min
+		let to: number | null = field.max
+		if (range !== '*') {
+			const [low = '', high, more] = range.split('-')
+			if (more !== undefined) {
+				return null
+			}
+			from = number(low, field)
+			to = high === undefined ? (step === undefined ? from : field.max) : number(high, field)
+		}
+		if (from === null || to === null || from > to) {
+			return null
+		}
+		for (let value = from; value <= to; value += every) {
+			values.add(value)
+		}
+	}
+	return values
+}
+
+/** The schedule of a five-field expression, or `null` when it is not one this runner reads. */
+export function parseCron(expression: string): CronSchedule | null {
+	const fields = expression.split(' ')
+	if (fields.length !== 5) {
+		return null
+	}
+	const [minute = '', hour = '', dayOfMonth = '', month = '', dayOfWeek = ''] = fields
+	const minutes = parseField(minute, MINUTE)
+	const hours = parseField(hour, HOUR)
+	const daysOfMonth = parseField(dayOfMonth, DAY_OF_MONTH)
+	const months = parseField(month, MONTH)
+	const weekdays = parseField(dayOfWeek, DAY_OF_WEEK)
+	if (minutes === null || hours === null || daysOfMonth === null || months === null || weekdays === null) {
+		return null
+	}
+	const daysOfWeek = new Set([...weekdays].map((day) => day % 7))
+	return { minutes, hours, daysOfMonth, months, daysOfWeek, eitherDay: !dayOfMonth.startsWith('*') && !dayOfWeek.startsWith('*') }
+}
+
+function dayMatches(schedule: CronSchedule, day: Date): boolean {
+	if (!schedule.months.has(day.getUTCMonth() + 1)) {
+		return false
+	}
+	const byMonth = schedule.daysOfMonth.has(day.getUTCDate())
+	const byWeek = schedule.daysOfWeek.has(day.getUTCDay())
+	return schedule.eitherDay ? byMonth || byWeek : byMonth && byWeek
+}
+
+const descending = (values: ReadonlySet<number>): number[] => [...values].sort((left, right) => right - left)
+
+/** The latest `count` due minutes at or before `at`, newest first; fewer when the schedule is that rare. */
+export function previousDue(schedule: CronSchedule, at: Date, count: number): Date[] {
+	const due: Date[] = []
+	const hours = descending(schedule.hours)
+	const minutes = descending(schedule.minutes)
+	const limit = Math.floor(at.getTime() / MINUTE_MS) * MINUTE_MS
+	const today = Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate())
+	for (let back = 0; back <= SEARCH_DAYS && due.length < count; back++) {
+		const day = new Date(today - back * 24 * 60 * MINUTE_MS)
+		if (!dayMatches(schedule, day)) {
+			continue
+		}
+		for (const hour of hours) {
+			for (const minute of minutes) {
+				const time = day.getTime() + (hour * 60 + minute) * MINUTE_MS
+				if (time <= limit && due.length < count) {
+					due.push(new Date(time))
+				}
+			}
+		}
+	}
+	return due
+}
+
+/** The time between the two latest due minutes at or before `at`, or `null` when there are not two in the window. */
+export function periodAt(schedule: CronSchedule, at: Date): number | null {
+	const [latest, before] = previousDue(schedule, at, 2)
+	return latest === undefined || before === undefined ? null : latest.getTime() - before.getTime()
+}

package/src/jobs/types.ts

@@ -0,0 +1,44 @@
+// The handler types of a contract's jobs: one handler per `c.cron` job under `handlers.jobs`, each with a context
+// that reaches only the actions the job declares. A job has no request and no caller, so there is no `input`.
+
+import type { CronJob, DimensionOf } from '../contract/define'
+import type { Ref, Within } from '../implement/capability'
+
+/** Who a job's writes are stamped with (`createdBy`): the job itself, never a person. */
+export interface JobPrincipal {
+	readonly kind: 'job'
+	/** `job:<name>`. */
+	readonly id: string
+	readonly job: string
+}
+
+/**
+ * What a job handler gets. A capability is minted for a declared action only when the token IAM signed for the job's
+ * key at the start of the attempt carries it, with the job's `scope: 'app'`, and only while this attempt holds the
+ * job's lease: a capability of another attempt is refused, and so is every write after the attempt timed out or lost
+ * the lease.
+ */
+export interface JobContext<A extends string, D extends string> {
+	readonly principal: JobPrincipal
+	/** This attempt's id; it is also the holder of the job's lease. */
+	readonly runId: string
+	/** 1 for the first attempt, one more for each retry. */
+	readonly attempt: number
+	/** Aborted when the attempt times out or loses its lease. */
+	readonly signal: AbortSignal
+	/** Every value of `dimension`, for a declared action: what a list or an aggregate takes. */
+	within<const Act extends A, const Dim extends D>(action: Act, dimension: Dim): Within<Dim, Act>
+	/** One object of `dimension` for a declared action, located now: what a write takes. A missing object is NotFound. */
+	ref<const Act extends A, const Dim extends D>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>
+}
+
+export type JobHandler<A extends string, D extends string> = (args: { readonly ctx: JobContext<A, D> }) => void | Promise<void>
+
+type JobsOf<C> = C extends { readonly surface: { readonly jobs: infer J } } ? J : never
+
+/** `{ jobs: { <name>: handler } }` for a contract that declares jobs, and nothing for one that declares none. */
+export type JobHandlersOf<C> = [JobsOf<C>] extends [never] ? unknown : {
+	readonly jobs: {
+		readonly [K in keyof JobsOf<C>]: JobsOf<C>[K] extends CronJob<infer A, string> ? JobHandler<A, DimensionOf<C>> : never
+	}
+}

package/src/react/caller.tsx

@@ -0,0 +1,60 @@
+// Who the page's person is, from the caller document the SPA mount serves: their label, mailbox and what the token
+// grants. A page greets by it and shows or hides a control by it. It is information for the page only and never a
+// check: every endpoint decides again, so a hidden button protects nothing.
+
+import { type ReactNode, useMemo, useSyncExternalStore } from 'react'
+import type { PageCaller } from '../client/caller'
+import { useFabrika } from './provider'
+
+/** A scope value as the token names it: `{ type: 'org', value: 'acme' }`. */
+export interface CallerScope {
+	readonly type: string
+	readonly value: string
+}
+
+export interface Caller {
+	readonly label: string
+	readonly email: string
+	/**
+	 * Whether the token grants `action`: without `scope`, app-wide or in any scope value; with `scope`, app-wide or in
+	 * that value itself. A grant on a container is not seen from a value inside it (the page knows no chain): ask at
+	 * the dimension the person holds the role in.
+	 */
+	can(action: string, scope?: CallerScope): boolean
+}
+
+/** The caller of a parsed document; exported for a page that reads the document itself. */
+export function callerOf(document: PageCaller): Caller {
+	const app = new Set(document.actions.app)
+	return Object.freeze({
+		label: document.label,
+		email: document.email,
+		can(action: string, scope?: CallerScope): boolean {
+			if (app.has(action)) return true
+			return document.actions.scopes.some((held) =>
+				held.actions.includes(action) && (scope === undefined || (held.type === scope.type && held.value === scope.value))
+			)
+		},
+	})
+}
+
+/** The page's caller, or `null` while the document loads and when it could not be read (a public SPA answers 401). */
+export function useCaller(): Caller | null {
+	const source = useFabrika('useCaller').caller
+	const state = useSyncExternalStore((listener) => source.subscribe(listener), () => source.state, () => source.state)
+	return useMemo(() => (state.status === 'ready' ? callerOf(state.caller) : null), [state])
+}
+
+export interface CanProps {
+	readonly action: string
+	readonly scope?: CallerScope
+	/** Shown instead, also while the caller document loads; nothing by default. */
+	readonly fallback?: ReactNode
+	readonly children?: ReactNode
+}
+
+/** Renders its children when the caller's token grants `action` (see `Caller.can`). Never the access check. */
+export function Can({ action, scope, fallback = null, children }: CanProps): ReactNode {
+	const caller = useCaller()
+	return caller?.can(action, scope) === true ? children : fallback
+}

package/src/react/errors.ts

@@ -0,0 +1,82 @@
+// Every refusal a page meets, as one union it can switch on: the proxy's 401 with the login URL, a 403, a stale
+// `expectVersion` (409), a refused input with its field paths, a 404, and everything else.
+
+export type FabrikaError =
+	| {
+		readonly kind: 'unauthenticated'
+		readonly message: string
+		/** Where the proxy sends the person to sign in; `null` when the answer carried none. */
+		readonly loginUrl: string | null
+	}
+	| { readonly kind: 'forbidden'; readonly message: string }
+	| { readonly kind: 'conflict'; readonly message: string }
+	| {
+		readonly kind: 'validation'
+		readonly message: string
+		/** The first message for each refused field, by its dotted input path (`title`, `lines.0.amount`). */
+		readonly fields: Readonly<Record<string, string>>
+	}
+	| { readonly kind: 'not-found'; readonly message: string }
+	| {
+		readonly kind: 'other'
+		readonly message: string
+		/** The HTTP status; `0` when the request never got an answer. */
+		readonly status: number
+	}
+
+export type FabrikaErrorKind = FabrikaError['kind']
+
+interface Issue {
+	readonly path: string
+	readonly message: string
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === 'object' && value !== null
+}
+
+/** The `{ path, message }` issues of a 400; anything else in `issues` is ignored. */
+function issuesOf(value: unknown): readonly Issue[] {
+	if (!Array.isArray(value)) {
+		return []
+	}
+	return value.flatMap((issue: unknown) => {
+		if (!isRecord(issue)) return []
+		const path = issue['path']
+		const message = issue['message']
+		return typeof path === 'string' && typeof message === 'string' ? [{ path, message }] : []
+	})
+}
+
+/** The first message per path: a field shows one line. */
+export function fieldsOf(issues: readonly Issue[]): Readonly<Record<string, string>> {
+	const fields: Record<string, string> = {}
+	for (const issue of issues) {
+		fields[issue.path] ??= issue.message
+	}
+	return Object.freeze(fields)
+}
+
+/**
+ * A refused call as the union, read structurally off the client's `RpcError` (`httpStatus`, `type`, `issues`,
+ * `loginUrl`); any other thrown value (a bug in the page) is `other` with status `0`.
+ */
+export function toFabrikaError(error: unknown): FabrikaError {
+	const message = error instanceof Error ? error.message : 'Something went wrong'
+	const status = isRecord(error) && typeof error['httpStatus'] === 'number' ? error['httpStatus'] : 0
+	const type = isRecord(error) ? error['type'] : undefined
+	if (status === 401 || type === 'auth') {
+		const loginUrl = isRecord(error) ? error['loginUrl'] : undefined
+		return { kind: 'unauthenticated', message, loginUrl: typeof loginUrl === 'string' ? loginUrl : null }
+	}
+	if (status === 403) return { kind: 'forbidden', message }
+	if (status === 404) return { kind: 'not-found', message }
+	if (status === 409) return { kind: 'conflict', message }
+	if (status === 400) return { kind: 'validation', message, fields: fieldsOf(issuesOf(isRecord(error) ? error['issues'] : undefined)) }
+	return { kind: 'other', message, status }
+}
+
+/** The message for one field of a validation error, or `undefined`: what a form shows under that field. */
+export function fieldError(error: FabrikaError | null, path: string): string | undefined {
+	return error?.kind === 'validation' ? error.fields[path] : undefined
+}

package/src/react/hooks.ts

@@ -0,0 +1,239 @@
+// The data hooks over the typed client: `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction` and
+// `useInvalidate`. Each takes a client procedure (`api.deals.get`) as the typed name of the call; the answer comes back
+// through the procedure's own output schema, so its type is the contract's.
+
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import { z } from 'zod/v4'
+import type { Schema } from '../contract/define'
+import { type FabrikaError, toFabrikaError } from './errors'
+import { parentOf, prefixOf, useFabrika } from './provider'
+import type { PagesEntry, QueryEntry } from './store'
+import type { InputArgument, InvalidateTarget, PagedProcedure, PageInput, TypedProcedure } from './types'
+
+/** Pass as the input to wait: the query sends nothing until its input is known. */
+export const skip: unique symbol = Symbol('fabrika.skip')
+
+export type QueryState<T> =
+	& { readonly fetching: boolean; refetch(): Promise<void> }
+	& (
+		| { readonly status: 'idle'; readonly data: undefined; readonly error: null }
+		| { readonly status: 'loading'; readonly data: undefined; readonly error: null }
+		| { readonly status: 'success'; readonly data: T; readonly error: null }
+		/** `data` keeps the last answer when a refetch failed. */
+		| { readonly status: 'error'; readonly data: T | undefined; readonly error: FabrikaError }
+	)
+
+const IDLE = Object.freeze({ status: 'idle', data: undefined, error: null, fetching: false, refetch: () => Promise.resolve() } as const)
+
+const NO_ENTRY = { subscribe: () => () => {}, snapshot: null }
+
+/** An answer the cache holds, read back through the output schema; a value it refuses is an error, never a cast. */
+function readBack<O extends Schema>(schema: O, value: unknown): { readonly ok: true; readonly data: z.output<O> } | { readonly ok: false } {
+	const parsed = z.safeParse(schema, value)
+	return parsed.success ? { ok: true, data: parsed.data } : { ok: false }
+}
+
+const UNREADABLE: FabrikaError = { kind: 'other', message: 'the cached answer does not match the output schema', status: 0 }
+
+/** Starts the entry's first load once a view shows it, and again after it failed. */
+function useLoad(entry: QueryEntry | PagesEntry | null): void {
+	useEffect(() => {
+		if (entry !== null && entry.snapshot.status !== 'success' && !entry.snapshot.fetching) void entry.load()
+	}, [entry])
+}
+
+/**
+ * The answer of a query, cached by procedure and input: every view of one call shares one request, and a mutation
+ * that invalidates it refetches it. Pass `skip` as the input to wait for a value the input needs.
+ */
+export function useQuery<O extends Schema>(
+	procedure: TypedProcedure<Record<never, never> | undefined, O>,
+	input?: typeof skip,
+): QueryState<z.output<O>>
+export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input: I | typeof skip): QueryState<z.output<O>>
+export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input?: I | typeof skip): QueryState<z.output<O>> {
+	const fabrika = useFabrika('useQuery')
+	const target = useMemo(() => fabrika.target(procedure, 'useQuery'), [fabrika, procedure])
+	if (target.node.procedure?.type === 'mutation') throw new Error(`useQuery: '${target.id}' is a mutation; use useMutation`)
+	const waiting = input === skip
+	const key = waiting ? null : JSON.stringify(input ?? null)
+	// The entry follows the input's value, not its identity: a fresh object literal each render is the same query.
+	const entry = useMemo(() => (waiting ? null : fabrika.store.query(target, input ?? undefined)), [fabrika, target, key])
+	const source = entry ?? NO_ENTRY
+	const snapshot = useSyncExternalStore((listener) => source.subscribe(listener), () => source.snapshot, () => source.snapshot)
+	useLoad(entry)
+	const refetch = useCallback(() => entry?.load() ?? Promise.resolve(), [entry])
+	return useMemo((): QueryState<z.output<O>> => {
+		if (snapshot === null) return IDLE
+		const fetching = snapshot.fetching
+		if (snapshot.status === 'loading') return { status: 'loading', data: undefined, error: null, fetching, refetch }
+		const read = snapshot.data === undefined ? null : readBack(procedure.output, snapshot.data)
+		if (read !== null && !read.ok) return { status: 'error', data: undefined, error: UNREADABLE, fetching, refetch }
+		const data = read?.data
+		if (snapshot.status === 'error' && snapshot.error !== null) return { status: 'error', data, error: snapshot.error, fetching, refetch }
+		return data === undefined
+			? { status: 'loading', data: undefined, error: null, fetching, refetch }
+			: { status: 'success', data, error: null, fetching, refetch }
+	}, [snapshot, procedure, refetch])
+}
+
+export interface InfiniteQueryOptions {
+	/** How many pages the first load reads: `1` (the default) or every page (`'all'`, for a picker's options). */
+	readonly pages?: number | 'all'
+}
+
+export interface InfiniteQueryState<Item> {
+	readonly status: 'idle' | 'loading' | 'success' | 'error'
+	/** Every item of the loaded pages, in order. */
+	readonly items: readonly Item[]
+	readonly error: FabrikaError | null
+	readonly hasMore: boolean
+	readonly fetching: boolean
+	readonly loadingMore: boolean
+	loadMore(): Promise<void>
+	refetch(): Promise<void>
+	/** After a failed later page, asks for that page again; after a failed first load, loads again. */
+	retry(): Promise<void>
+}
+
+/**
+ * A cursor list (`{ items, next }`, input `after`): the loaded pages as one list and `loadMore` for the next page. A
+ * refetch reads as many pages as are loaded again, from the first cursor.
+ */
+export function useInfiniteQuery<I extends { readonly after?: string } | undefined, Item>(
+	procedure: PagedProcedure<I, Item>,
+	input: PageInput<I> | typeof skip,
+	options: InfiniteQueryOptions = {},
+): InfiniteQueryState<Item> {
+	const fabrika = useFabrika('useInfiniteQuery')
+	const target = useMemo(() => fabrika.target(procedure, 'useInfiniteQuery'), [fabrika, procedure])
+	const waiting = input === skip
+	const pages = options.pages === 'all' ? Number.POSITIVE_INFINITY : Math.max(1, options.pages ?? 1)
+	const key = waiting ? null : JSON.stringify(input ?? null)
+	const entry = useMemo(() => (waiting ? null : fabrika.store.pages(target, input ?? undefined, pages)), [fabrika, target, key, pages])
+	const source = entry ?? NO_ENTRY
+	const snapshot = useSyncExternalStore((listener) => source.subscribe(listener), () => source.snapshot, () => source.snapshot)
+	useLoad(entry)
+	const loadMore = useCallback(() => entry?.loadMore() ?? Promise.resolve(), [entry])
+	const refetch = useCallback(() => entry?.load() ?? Promise.resolve(), [entry])
+	return useMemo((): InfiniteQueryState<Item> => {
+		const retry = () => (snapshot !== null && snapshot.items.length > 0 && snapshot.next !== null ? loadMore() : refetch())
+		if (snapshot === null) {
+			return { status: 'idle', items: [], error: null, hasMore: false, fetching: false, loadingMore: false, loadMore, refetch, retry }
+		}
+		const read = readBack(procedure.output, { items: snapshot.items, next: snapshot.next })
+		return {
+			status: read.ok ? snapshot.status : 'error',
+			items: read.ok ? read.data.items : [],
+			error: read.ok ? snapshot.error : UNREADABLE,
+			hasMore: snapshot.next !== null,
+			fetching: snapshot.fetching,
+			loadingMore: snapshot.loadingMore,
+			loadMore,
+			refetch,
+			retry,
+		}
+	}, [snapshot, procedure, loadMore, refetch])
+}
+
+export type MutationResult<T> = { readonly ok: true; readonly data: T } | { readonly ok: false; readonly error: FabrikaError }
+
+export interface MutationState<I, T> {
+	readonly status: 'idle' | 'pending' | 'success' | 'error'
+	readonly pending: boolean
+	readonly data: T | undefined
+	readonly error: FabrikaError | null
+	/** Runs the call; never throws: a refusal is `{ ok: false, error }` and the state's `error`. */
+	mutate(input: I): Promise<MutationResult<T>>
+	reset(): void
+}
+
+export interface MutationOptions<T> {
+	/**
+	 * What to refetch after a success or a `conflict`: procedures and groups of the client. Without it the procedure's own group
+	 * (`api.deals` for `api.deals.create`); `[]` refetches nothing.
+	 */
+	readonly invalidates?: readonly InvalidateTarget[]
+	readonly onSuccess?: (data: T) => void
+}
+
+type RunState<T> = Pick<MutationState<unknown, T>, 'status' | 'data' | 'error'>
+
+/**
+ * The state machine of a call a person starts: pending, then its answer or its refusal, then what it invalidates. When
+ * calls overlap, only the latest one's outcome becomes the state, and `pending` holds while any of them runs.
+ */
+function useRun<I, T>(run: (input: I) => Promise<T>, after: () => Promise<void>, onSuccess?: (data: T) => void): MutationState<I, T> {
+	const [state, setState] = useState<RunState<T>>({ status: 'idle', data: undefined, error: null })
+	const [running, setRunning] = useState(0)
+	const latest = useRef(0)
+	const mutate = useCallback(async (input: I): Promise<MutationResult<T>> => {
+		const call = ++latest.current
+		setRunning((count) => count + 1)
+		setState({ status: 'pending', data: undefined, error: null })
+		try {
+			let data: T
+			try {
+				data = await run(input)
+			} catch (refusal) {
+				const error = toFabrikaError(refusal)
+				// A conflict means the rows changed under the page: refetch them, so a form reseeds from the current version.
+				if (error.kind === 'conflict') await after()
+				if (call === latest.current) setState({ status: 'error', data: undefined, error })
+				return { ok: false, error }
+			}
+			await after()
+			if (call === latest.current) setState({ status: 'success', data, error: null })
+			onSuccess?.(data)
+			return { ok: true, data }
+		} finally {
+			setRunning((count) => count - 1)
+		}
+	}, [run, after, onSuccess])
+	const reset = useCallback(() => {
+		latest.current++
+		setState({ status: 'idle', data: undefined, error: null })
+	}, [])
+	const status = running > 0 ? 'pending' : state.status
+	return { ...state, status, pending: running > 0, mutate, reset }
+}
+
+/**
+ * A mutation of the client: `mutate(input)` checks the input with the procedure's schema (a refused input is a
+ * `validation` error and sends nothing), calls it, and after a success refetches what `invalidates` names.
+ */
+export function useMutation<I, O extends Schema>(
+	procedure: TypedProcedure<I, O>,
+	options: MutationOptions<z.output<O>> = {},
+): MutationState<InputArgument<I>, z.output<O>> {
+	const fabrika = useFabrika('useMutation')
+	const target = useMemo(() => fabrika.target(procedure, 'useMutation'), [fabrika, procedure])
+	const run = useCallback(async (input: InputArgument<I>): Promise<z.output<O>> => {
+		const read = readBack(procedure.output, await target.run(input ?? undefined))
+		if (!read.ok) throw new Error(`'${target.id}' answered a value its output schema refuses`)
+		return read.data
+	}, [procedure, target])
+	const prefixes = useMemo(() => (options.invalidates === undefined ? [parentOf(target.node)] : options.invalidates.map(prefixOf)), [
+		target,
+		options.invalidates,
+	])
+	const after = useCallback(() => fabrika.store.invalidate(prefixes), [fabrika, prefixes])
+	return useRun(run, after, options.onSuccess)
+}
+
+/**
+ * A call that is no client procedure yet (a file upload until the client covers file collections), with the same
+ * state and error union as a mutation. It refetches only what `invalidates` names.
+ */
+export function useAction<I, T>(run: (input: I) => Promise<T>, options: MutationOptions<T> = {}): MutationState<I, T> {
+	const fabrika = useFabrika('useAction')
+	const prefixes = useMemo(() => (options.invalidates ?? []).map(prefixOf), [options.invalidates])
+	const after = useCallback(() => fabrika.store.invalidate(prefixes), [fabrika, prefixes])
+	return useRun(run, after, options.onSuccess)
+}
+
+/** Refetches every shown query under the procedures or groups given, and forgets the cached rest. */
+export function useInvalidate(): (...targets: readonly InvalidateTarget[]) => Promise<void> {
+	const fabrika = useFabrika('useInvalidate')
+	return useCallback((...targets) => fabrika.store.invalidate(targets.map(prefixOf)), [fabrika])
+}

package/src/react/index.ts

@@ -0,0 +1,31 @@
+// @fabrika/app/react — the paved road's data layer of an SPA: a provider over the typed clients, query and mutation
+// hooks typed from the contract, one error union, and the caller document. Browser-safe; React is a peer dependency.
+export { type Caller, callerOf, type CallerScope, Can, type CanProps, useCaller } from './caller'
+export { type FabrikaError, type FabrikaErrorKind, fieldError, toFabrikaError } from './errors'
+export {
+	type InfiniteQueryOptions,
+	type InfiniteQueryState,
+	type MutationOptions,
+	type MutationResult,
+	type MutationState,
+	type QueryState,
+	skip,
+	useAction,
+	useInfiniteQuery,
+	useInvalidate,
+	useMutation,
+	useQuery,
+} from './hooks'
+export { FabrikaProvider, type FabrikaProviderProps } from './provider'
+export type {
+	ClientGroup,
+	ClientProcedure,
+	InputArgument,
+	InvalidateTarget,
+	PageAnswer,
+	PagedProcedure,
+	PageInput,
+	ProcedureInput,
+	ProcedureResult,
+	TypedProcedure,
+} from './types'