Composables

All composables are auto-imported and fully typed from your ZModel schema. They communicate with the auto-generated server endpoints and keep a normalized store in sync.

useZenstackCreate

Creates a new record.

const { mutate, data, error, status, loading, reset } = useZenstackCreate('User')

Usage

const { mutate: createUser, error, loading } = useZenstackCreate('User')

async function onSubmit() {
  await createUser({ email: '[email protected]', name: 'Alice' })
}

Returns

Property	Type	Description
data	Ref<Item | null>	The created record
error	Ref<$Zerror | null>	Error from the last call
status	Ref<'idle' | 'pending' | 'success' | 'error'>	Current status
loading	ComputedRef<boolean>	true while the request is in flight
mutate	(input) => Promise<Item | null>	Trigger the create operation
reset	() => void	Reset data, error, and status to initial values

---

useZenstackRead

Fetches a single record by ID.

const { data, error, status, loading, query } = await useZenstackRead('User', userId)

Usage

const { data: user } = await useZenstackRead('User', userId)

// With related models
const { data: user } = await useZenstackRead('User', userId, {
  include: { posts: true },
})

Options

Option	Type	Default	Description
fetchPolicy	FetchPolicy	module default	Override the global fetch policy for this call
immediate	boolean	true	Run the query immediately on call
include	object	—	Related models to include (typed from schema)

Returns

Property	Type	Description
data	Ref<Item | null>	The fetched record
error	Ref<$Zerror | null>	Error from the last query
status	Ref<Status>	Current status
loading	ComputedRef<boolean>	true while fetching
query	() => Promise<void>	Re-run the query manually

---

useZenstackReadMany

Fetches a list of records with optional filtering, ordering, and pagination.

const { data, error, status, loading, query, queryMore, canQueryMore, reset } =
  await useZenstackReadMany('User')

Usage

// Basic list
const { data: users } = await useZenstackReadMany('User')

// Filtered and ordered
const search = ref('')

const { data: users } = await useZenstackReadMany('User', {
  where: () => ({ name: { contains: search.value } }),
  orderBy: { createdAt: 'desc' },
  take: 20,
  watch: true, // re-query automatically when reactive `where`/`orderBy` change
})

// Load more (cursor-based pagination)
const { data: posts, queryMore, canQueryMore } = await useZenstackReadMany('Post', {
  take: 10,
})

// Call queryMore() to append the next page
await queryMore()

// Example with VueUse useInfiniteScroll
import { useInfiniteScroll } from '@vueuse/core'

const containerRef = ref<HTMLElement | null>(null)

useInfiniteScroll(
  containerRef,
  () => queryMore(),
  {
    distance: 10,
    canLoadMore: () => canQueryMore.value
  }
)

Options

Option	Type	Default	Description
fetchPolicy	FetchPolicy	module default	Override the global fetch policy
immediate	boolean	true	Run the query immediately
include	object	—	Related models to include
where	MaybeRefOrGetter<Where>	—	Filter criteria
orderBy	MaybeRefOrGetter<OrderBy>	—	Sort criteria
take	number	—	Max records per page
watch	boolean	false	Re-query when where/orderBy refs change

Returns

Property	Type	Description
data	Ref<Item[] | null>	The fetched records
error	Ref<$Zerror | null>	Error from the last query
status	Ref<Status>	Current status
loading	ComputedRef<boolean>	true while fetching
canQueryMore	Ref<boolean>	false when all records have been loaded
query	() => Promise<void>	Re-run the query (resets to first page)
queryMore	() => Promise<void>	Append the next page of results
reset	() => void	Reset data and pagination state

---

useZenstackUpdate

Updates an existing record by ID.

const { mutate, data, error, status, loading, reset } = useZenstackUpdate('User')

Usage

const { mutate: updateUser, loading } = useZenstackUpdate('User')

await updateUser(userId, { name: 'New Name' })

Returns

Property	Type	Description
data	Ref<Item | null>	The updated record
error	Ref<$Zerror | null>	Error from the last call
status	Ref<Status>	Current status
loading	ComputedRef<boolean>	true while the request is in flight
mutate	(id, input) => Promise<Item | null>	Trigger the update
reset	() => void	Reset state

---

useZenstackDelete

Deletes a record by ID.

const { mutate, data, error, status, loading, reset } = useZenstackDelete('User')

Usage

const { mutate: deleteUser, loading } = useZenstackDelete('User')

await deleteUser(userId)

Returns

Property	Type	Description
data	Ref<Item | null>	The deleted record
error	Ref<$Zerror | null>	Error from the last call
status	Ref<Status>	Current status
loading	ComputedRef<boolean>	true while the request is in flight
mutate	(id) => Promise<Item | null>	Trigger the delete
reset	() => void	Reset state

---

Error Handling

All composables return an error ref typed as $Zerror | null. This type is an extension of FetchError that includes ZenStack's specific ORMError properties when a database or policy error occurs.

$Zerror Properties

When the server encounters a ZenStack error, the error object will contain the following properties inside its data payload:

Property	Type	Description
reason	ORMErrorReason	The reason code for the error (e.g., 'rejected-by-policy', 'not-found', 'db-query-error', 'invalid-input').
model	string	The name of the ZModel that the error pertains to.
dbErrorCode	unknown	The raw error code given by the underlying database driver.
dbErrorMessage	string	The raw error message given by the underlying database driver.
rejectedByPolicyReason	RejectedByPolicyReason	If reason is 'rejected-by-policy', this indicates why ('no-access', 'cannot-read-back', etc).
statusCode	number	The HTTP status code returned by the auto-generated API endpoint (e.g., 403 for policy rejections).

For more details on ZenStack's error handling, refer to the ZenStack ORM Errors Documentation.