Nano Stores DeepMap

Deep maps extension for Nano Stores state manager. It provides a store to put big nested objects or arrays and change keys by path with fine-grained reactivity.

Install

npm install @nanostores/deepmap

Usage

Import deepMap from this package to initialize a store with a deeply nested object or array.

import { deepMap } from '@nanostores/deepmap'

type StoreType = {
  user?: {
    name: string
    age: number
  }
  count?: number
  items?: { id: string }[]
}

const $store = deepMap<StoreType>({
  user: {
    name: 'Luke',
    age: 19,
  },
  count: 0,
})

Path Syntax

deepMap provides various methods to interact with your nested state easily without mutating the original object. It supports two path syntaxes:

• key.subkey: To access a deeply nested property in a object.
• key[0]: To access an item in an array by index.

GetKey

Use getKey to obtain the current value at a specific path.

$store.getKey('user.name')
// -> "Luke"

SetKey

Use setKey to create or replace any value at a specific path.

// Replaces the value at 'count'
$store.setKey('count', 1)

// Note: undefined value is reserved for deletion

UpdateKey and Update

Use updateKey to merge new data into an existing object or to concatenate items into an array. If the target isn't an object or array, it will simply be replaced. Use update to modify the root state object.

$store.updateKey('user.age', 42)
// -> { user: { name: 'Luke', age: 42 }, ... }

// Pushes/concatenates new items to an array
// Note: You need to use the [] syntax to update an array
$store.updateKey('items', [{ id: 'uuid-2' }])
// -> { items: [{ id: 'uuid-1' }, { id: 'uuid-2' }] }

DeleteKey

Use deleteKey to remove a property from an object. You can also use setKey with an undefined value.

// Deletes 'count' from the store
$store.deleteKey('count')
$store.setKey('count', undefined)

TypeScript Support

The package is written in TypeScript and provides autocomplete for all methods and properties, even the nested ones.

type UserType = {
  id?: string
  settings?: { theme: string }
}

const $user = deepMap<UserType>({})

// Autocomplete will suggest 'id' and 'settings.theme'
$user.setKey('settings.theme', 'dark')

Typescript automatically infers and validates the type of the value at the specified path:

$store.setKey('count', 'randomString')
// Type Error -> 'string' is not assignable to type 'number'

Integrations

React & Preact

When using a hook useStore you can pass an array of keys for listening to changes.

// Reactivity in user branch, any child mutation fire a re-render
const { name } = useStore($store, { keys: ['user']})

// Specific reactivity

const { name } = useStore($store, { keys: ['user.name']}) // Only listen the exact key path

If your component only depends on a specific nested value, listen to the exact path. This prevents unnecessary re-renders when sibling properties change.

License

MIT

Credits

• Dan Kozlov the author of deepmap() in Nano stores core.