Skip to content
Zenty

createEntityStore

API reference for createEntityStore: one object in a Zustand store with set, update and clear, optional deep merge and DeepPartial updates.

Applies to zenty v1.1.0

createEntityStore holds exactly one object, or null before you set it. Use it for settings, the signed-in user, a form draft or anything else that isn't a list.

stores/current-user.ts
import { createEntityStore } from 'zenty'

type User = { id: string; name: string; email: string }

export const useCurrentUser = createEntityStore<User>()

const { set, update, clear } = useCurrentUser.getState()
set({ id: 'u1', name: 'Lena', email: 'lena@example.com' })
update({ email: 'lena.anders@example.com' })
clear() // entity: null, loaded: false

Signature(link to this section)

zenty
// update takes a Partial<T>
function createEntityStore<T>(
  options?: EntityStoreOptions<T, false>
): EntityStore<T, false>

// with deepMerge: true, update takes a DeepPartial<T>
function createEntityStore<T>(
  options: EntityStoreOptions<T, true> & { deepMerge: true }
): EntityStore<T, true>

Options(link to this section)

createEntityStore options
NameTypeDescription
initialStateT | nullThe object the store starts with. Anything other than null starts with loaded: true.Default: null
deepMergebooleanMerge nested plain objects on update and type the patch as DeepPartial<T>.Default: false
middlewareZentyMiddleware<EntityStoreState<T, D>>Zustand middleware such as persist or devtools. See the middleware guide.

State(link to this section)

createEntityStore state
NameTypeDescription
entityT | nullThe object, or null before set() and after clear().
loadedbooleanTrue after set() or a successful update(); false again after clear().
loadingbooleanSet it with setLoading(true). set, update and setError('…') set it back to false.
errorstring | nullThe last error message. A successful set or update clears it.

Actions(link to this section)

createEntityStore actions
NameTypeDescription
set(entity: T) => voidReplaces the whole object.
update(patch: Partial<T> | DeepPartial<T>) => voidMerges the patch into the object. Before anything is set, it sets error to “Cannot update: no entity is set. Call set() first.”
clear() => voidResets entity to null and loaded, loading and error to their defaults.
setLoading(loading: boolean) => voidSets loading.
setError(error: string | null) => voidSets error. A message also ends loading; null keeps loading as it is.

Deep merge(link to this section)

Without deepMerge, update is a shallow merge: passing { ui: { theme: 'dark' } } would replace the whole ui object. With deepMerge: true, nested plain objects are merged key by key, so the fields you didn't pass stay as they were.

stores/settings.ts
interface Settings {
  ui: { theme: string; language: string }
  notifications: { email: boolean; push: boolean }
}

const useSettings = createEntityStore<Settings>({
  deepMerge: true,
  initialState: {
    ui: { theme: 'light', language: 'en' },
    notifications: { email: true, push: false },
  },
})

// update is typed as DeepPartial<Settings>: no cast needed
useSettings.getState().update({ ui: { theme: 'dark' } })
// ui.language is still 'en', notifications are untouched

Related types exported from zenty:

  • EntityStore<T, D> and EntityStoreState<T, D>, where D is true with deep merge.
  • EntityPatch<T, D>: the patch type of update, and DeepPartial<T>.
  • deepMerge(target, source): the merge helper itself, if you need it elsewhere.

Found a mistake? Open an issue.