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.
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: falseSignature(link to this section)
// 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)
| Name | Type | Description |
|---|---|---|
initialState | T | null | The object the store starts with. Anything other than null starts with loaded: true.Default: null |
deepMerge | boolean | Merge nested plain objects on update and type the patch as DeepPartial<T>.Default: false |
middleware | ZentyMiddleware<EntityStoreState<T, D>> | Zustand middleware such as persist or devtools. See the middleware guide. |
State(link to this section)
| Name | Type | Description |
|---|---|---|
entity | T | null | The object, or null before set() and after clear(). |
loaded | boolean | True after set() or a successful update(); false again after clear(). |
loading | boolean | Set it with setLoading(true). set, update and setError('…') set it back to false. |
error | string | null | The last error message. A successful set or update clears it. |
Actions(link to this section)
| Name | Type | Description |
|---|---|---|
set | (entity: T) => void | Replaces the whole object. |
update | (patch: Partial<T> | DeepPartial<T>) => void | Merges the patch into the object. Before anything is set, it sets error to “Cannot update: no entity is set. Call set() first.” |
clear | () => void | Resets entity to null and loaded, loading and error to their defaults. |
setLoading | (loading: boolean) => void | Sets loading. |
setError | (error: string | null) => void | Sets 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.
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 untouchedRelated types exported from zenty:
EntityStore<T, D>andEntityStoreState<T, D>, whereDistruewith deep merge.EntityPatch<T, D>: the patch type ofupdate, andDeepPartial<T>.deepMerge(target, source): the merge helper itself, if you need it elsewhere.
Found a mistake? Open an issue.