Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/reatom/reatom/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

reatomRecord creates an atom that manages record (object) state with built-in methods for merging partial updates, omitting keys, and resetting to initial values. It’s ideal for managing form state, settings, or any structured object data.

​
Import

import { reatomRecord } from '@reatom/core'

​
Type Signature

interface RecordAtom<T extends Rec> extends Atom<T> {
  merge: Action<[slice: Partial<T>], T>
  omit: Action<Array<keyof T>, T>
  reset: Action<Array<keyof T>, T>
}

function reatomRecord<T extends Rec>(
  initState: Exclude<T, Fn>,
  name?: string
): RecordAtom<T>

​
Parameters

​
initState
Exclude<T, Fn>
required
The initial record/object value. Must be a plain object (not a function)
​
name
string
default:"'recordAtom'"
Optional name for the atom, useful for debugging

​
Methods

​
merge

Merges a partial update into the record. Only triggers an update if at least one value has changed.
​
slice
Partial<T>
A partial object with keys to update
Returns: T - The updated record 
const person = reatomRecord({
  civis: true,
  paterfamilias: true,
  servus: false,
  vir: true,
  coniugium: false,
  senator: true,
})

person.merge({
  civis: false,
  servus: true,
  senator: false,
})

console.log(person())
// {
//   civis: false,
//   paterfamilias: true,
//   servus: true,
//   vir: true,
//   coniugium: false,
//   senator: false,
// }

​
omit

Removes specified keys from the record.
​
...keys
Array<keyof T>
Keys to remove from the record
Returns: T - The updated record with keys removed 
const person = reatomRecord({
  civis: true,
  paterfamilias: true,
  servus: false,
  vir: true,
  coniugium: false,
  senator: true,
})

person.omit('coniugium')

console.log(person())
// {
//   civis: true,
//   paterfamilias: true,
//   servus: false,
//   vir: true,
//   senator: true,
// }

​
reset

Resets specified keys (or all keys if none specified) to their initial values.
​
...keys
Array<keyof T>
Keys to reset. If empty, resets the entire record to initial state
Returns: T - The updated record 
const person = reatomRecord({
  civis: true,
  servus: false,
  senator: true,
})

person.merge({ civis: false, servus: true })
console.log(person()) // { civis: false, servus: true, senator: true }

// Reset specific keys
person.reset('civis', 'servus')
console.log(person()) // { civis: true, servus: false, senator: true }

// Reset all keys
person.merge({ senator: false })
person.reset()
console.log(person()) // { civis: true, servus: false, senator: true }

​
Basic Usage

import { reatomRecord } from '@reatom/core'

// Create a record atom
const userSettings = reatomRecord({
  theme: 'dark',
  language: 'en',
  notifications: true,
  autoSave: false,
})

// Read the current value
console.log(userSettings())
// { theme: 'dark', language: 'en', notifications: true, autoSave: false }

// Merge partial updates
userSettings.merge({ theme: 'light', autoSave: true })
console.log(userSettings())
// { theme: 'light', language: 'en', notifications: true, autoSave: true }

// Remove a setting
userSettings.omit('autoSave')
console.log(userSettings())
// { theme: 'light', language: 'en', notifications: true }

// Reset specific settings
userSettings.reset('theme')
console.log(userSettings())
// { theme: 'dark', language: 'en', notifications: true }

​
Advanced Usage

​
Form State Management

interface FormData {
  email: string
  password: string
  rememberMe: boolean
  agreedToTerms: boolean
}

const formAtom = reatomRecord<FormData>({
  email: '',
  password: '',
  rememberMe: false,
  agreedToTerms: false,
})

// Update a single field
function updateField<K extends keyof FormData>(key: K, value: FormData[K]) {
  formAtom.merge({ [key]: value } as Partial<FormData>)
}

updateField('email', 'user@example.com')
updateField('rememberMe', true)

// Reset the form
function resetForm() {
  formAtom.reset()
}

​
User Profile with Partial Updates

interface UserProfile {
  firstName: string
  lastName: string
  email: string
  age: number
  country: string
}

const profileAtom = reatomRecord<UserProfile>({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  age: 30,
  country: 'US',
})

// Update multiple fields at once
profileAtom.merge({
  firstName: 'Jane',
  age: 31,
})

// Reset only certain fields
profileAtom.reset('email', 'country')

​
Combining with Computed Atoms

import { computed } from '@reatom/core'

const settings = reatomRecord({
  darkMode: true,
  fontSize: 14,
  compactView: false,
})

const cssVars = computed(() => {
  const s = settings()
  return {
    '--bg-color': s.darkMode ? '#000' : '#fff',
    '--font-size': `${s.fontSize}px`,
    '--spacing': s.compactView ? '8px' : '16px',
  }
})

​
Using with Atom Methods

Since RecordAtom extends Atom, you can use standard atom methods: 
const recordAtom = reatomRecord({ a: 1, b: 2 })

// Direct state updates
recordAtom.set({ a: 10, b: 20 })

// Functional updates
recordAtom.set(prev => ({
  ...prev,
  a: prev.a * 2
}))

// Subscribe to changes
const unsubscribe = recordAtom.subscribe((value) => {
  console.log('Record changed:', value)
})

​
Notes

  • merge only triggers updates when at least one value actually changes (uses Object.is() for comparison)
  • omit only triggers updates if at least one specified key exists in the record
  • reset with no arguments resets the entire record to the initial state
  • reset with specific keys only resets those keys to their initial values
  • All mutations create new object instances, preserving immutability
  • Direct mutations like recordAtom().key = value will not trigger updates; use merge() or set() instead

Build docs developers (and LLMs) love

Get started for freeTalk to us