npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@kundinos/nanostores

v0.4.5

Published

A tiny (152 bytes) state manager for React/Preact/Vue/Svelte with many atomic tree-shakable stores

Downloads

12

Readme

Nano Stores

A tiny state manager for React, React Native, Preact, Vue, Svelte, and vanilla JS. It uses many atomic stores and direct manipulation.

  • Small. between 172 and 526 bytes (minified and gzipped). Zero dependencies. It uses Size Limit to control size.
  • Fast. With small atomic and derived stores, you do not need to call the selector function for all components on every store change.
  • Tree Shakable. The chunk contains only stores used by components in the chunk.
  • Was designed to move logic from components to stores.
  • It has good TypeScript support.
// store/users.ts
import { createStore, update } from 'nanostores'

export const users = createStore<User[]>(() => {
  users.set([])
})

export function addUser(user: User) {
  update(users, current => [...current, user])
}
// store/admins.ts
import { createDerived } from 'nanostores'

import { users } from './users.js'

export const admins = createDerived(users, list =>
  list.filter(user => user.isAdmin)
)
// components/admins.tsx
import { useStore } from 'nanostores/react'

import { admins } from '../stores/admins.js'

export const Admins = () => {
  const list = useStore(admins)
  return (
    <ul>
      {list.map(user => <UserItem user={user} />)}
    </ul>
  )
}

Table of Contents

Install

npm install nanostores

Tools

  • Persistent store to save data to localStorage and synchronize changes between browser tabs.
  • Router store.
  • Logux Client: stores with WebSocket sync and CRDT conflict resolution.

Guide

In Nano Stores, stores are smart. They subscribe to events, validate input, send AJAX requests, etc. For instance, Router store subscribes to click on <a> and window.onpopstate. It simplifies testing and switching between UI frameworks (like from React to React Native).

import { createStore } from 'nanostores'

export type StoreType = …

export const simpleStore = createStore<StoreType>(() => {
  simpleStore.set(initialValue)
  // initializer: subscribe to events
  return () => {
    // destructor: unsubscribe from all events
  }
})

Stores have two modes: active and disabled. From the beginning, the store is in disabled mode and does not keep value. On the first call of store.listen or store.subscribe, the store will call the initializer and will move to active mode. One second after unsubscribing of the last listener, the store will call the destructor.

The only way to get store’s value is to subscribe to store’s changes:

const unsubscribe2 = store.listen(value => {
  // Call listener on store changes
})

const unsubscribe1 = store.subscribe(value => {
  // Call listener immediately after subscribing and then on any changes
})

We have shortcut to subscribe, return value and unsubscribe:

import { getValue } from 'nanostores'

getValue(store) //=> store’s value

And there is shortcut to get current value, change it and set new value.

import { update } from 'nanostores'

update(store, value => newValue)

Simple Store

Simple store API is the basement for all other stores.

import { createStore, update } from 'nanostores'

export const counter = createStore<number>(() => {
  counter.set(0)
})

export function increaseCounter() {
  update(counter, value => value + 1)
}

You can change store value by calling the store.set(newValue) method.

All async operations in store you need to wrap to effect (or use startEffect). It will help to wait async operations end in tests.

import { effect } from 'nanostore'

export function saveUser() {
  effect(async () => {
    await api.saveUser(getValue(userStore))
  })
}

Map Store

This store is with key-value pairs.

import { createMap } from 'nanostores'

export interface ProfileValue {
  name: string,
  email?: string
}

export const profile = createMap<ProfileValue>(() => {
  profile.setKey('name', 'anonymous')
})

In additional to store.set(newObject) it has store.setKey(key, value) to change specific key. There is a special shortcut updateKey(store, key, updater) in additional to update(store, updater).

Changes listener receives changed key as a second argument.

profile.listen((value, changed) => {
  console.log(`${changed} new value ${value[changed]}`)
})

Map store object link is the same. store.set(newObject) changes all keys inside the old object.

Lazy Store

All stores in Nano Stores are lazy. Without subscribers they are going to disabled mode and could remove their value.

If you want to keep the data, you can keep store in active mode even without subscribes by using keepActive().

import { keepActive } from 'nanostores'

export const store = createMap(…)

keepActive(store)

This feature was created for the stores with a logic (like router or stores, which load data from the server). Moving them to disabled mode will reduce memory usage.

Derived Store

The store is based on other store’s value.

import { createDerived } from 'nanostores'

import { users } from './users.js'

export const admins = createDerived(users, all => {
  // This callback will be called on every `users` changes
  return all.filter(user => user.isAdmin)
})

You can combine a value from multiple stores:

import { lastVisit } from './lastVisit.js'
import { posts } from './posts.js'

export const newPosts = createDerived([lastVisit, posts], (when, allPosts) => {
  return allPosts.filter(post => post.publishedAt > when)
})

Store Builder

A template to create a similar store. Each store made by the template is a map store with at least the id key.

import { defineMap, BuilderStore } from 'nanostores'

export interface PostValue {
  id: string
  title: string
  updatedAt: number
}

export const Post = defineMap<PostValue>((newPost, id) => {
  newPost.setKey('title', 'New post')
  newPost.setKey('updatedAt', Date.now())
  // initializer: subscribe to events
  return () => {
    // destructor: unsubscribe from all events
  }
})

export function renamePost (post: BuilderStore<typeof Post>, newTitle: string) {
  post.setKey('title', newTitle)
  post.setKey('updatedAt', Date.now())
}

Builder is a function, which returns a new store instance.

import { Post } from '../stores/post.js'

const post = Post(id)

If a store has listeners, the builder will return the old post instance on the same store’s ID.

Post('same ID') === Post('same ID')

Integration

React & Preact

Use useStore() hook to get store’s value and re-render component on store’s changes.

import { useStore } from 'nanostores/react' // or 'nanostores/preact'

import { profile } from '../stores/profile.js'
import { User } from '../stores/user.js'

export const Header = () => {
  const { userId } = useStore(profile)
  const currentUser = useStore(User(userId))
  return <header>{currentUser.name}<header>
}

Vue

Use useStore() composable function to get store’s value and re-render component on store’s changes.

<template>
  <header>{{ currentUser.name }}</header>
</template>

<script>
  import { useStore } from 'nanostores/vue'

  import { profile } from '../stores/profile.js'
  import { User } from '../stores/user.js'

  export default {
    setup () {
      const { userId } = useStore(profile).value
      const currentUser = useStore(User(userId))
      return { currentUser }
    }
  }
</script>

Svelte

Every store implements Svelte store contract. Put $ before store variable to get store’s value and subscribe for store’s changes.

<script>
  import { profile } from '../stores/profile.js'
  import { User } from '../stores/user.js'

  const { userId } = useStore(profile)
  const currentUser = useStore(User(userId))
</script>

<header>{$currentUser.name}</header>

Vanilla JS

Store#subscribe() calls callback immediately and subscribes to store changes. It passes store’s value to callback.

let prevUserUnbind
profile.subscribe(({ userId }) => {
  // Re-subscribe on current user ID changes
  if (prevUserUnbind) {
    // Remove old user listener
    prevUserUnbind()
  }
  // Add new user listener
  prevUserUnbind = User(userId).subscribe(currentUser => {
    console.log(currentUser.name)
  })
})

Use Store#listen() if you need to add listener without calling callback immediately.

Server-Side Rendering

Nano Stores support SSR. Use standard strategies.

if (isServer) {
  settings.set(initialSettings)
  router.open(renderingPageURL)
}

You can wait for async operations (for instance, data loading via isomorphic fetch()) before rendering the page:

import { allEffects } from 'nanostores'

store.listen(() => {}) // Move store to active mode to start data loading
await allEffects()

const html = ReactDOMServer.renderToString(<App />)

Tests

Adding an empty listener by keepActive(store) keeps the store in active mode during the test. cleanStores(store1, store2, …) cleans stores used in the test.

import { getValue, cleanStores, keepActive } from 'nanostores'

import { profile } from './profile.js'

afterEach(() => {
  cleanStores(profile)
})

it('is anonymous from the beginning', () => {
  keepActive(profile)
  expect(getValue(profile)).toEqual({ name: 'anonymous' })
})

You can use allEffects() to wait all async operations in stores.

import { getValue, allEffects } from 'nanostores'

it('saves user', async () => {
  saveUser()
  await allEffects()
  expect(getValue(analyticsEvents)).toEqual(['user:save'])
})

Best Practices

Move Logic from Components to Stores

Stores are not only to keep values. You can use them to track time, to load data from server.

import { createStore } from 'nanostores'

export const currentTime = createStore<number>(() => {
  currentTime.set(Date.now())
  const updating = setInterval(() => {
    currentTime.set(Date.now())
  }, 1000)
  return () => {
    clearInterval(updating)
  }
})

Use derived stores to create chains of reactive computations.

import { createDerived } from 'nanostores'

import { currentTime } from './currentTime.js'

const appStarted = Date.now()

export const userInApp = createDerived(currentTime, now => {
  return now - appStarted
})

We recommend moving all logic, which is not highly related to UI, to the stores. Let your stores track URL routing, validation, sending data to a server.

With application logic in the stores, it is much easier to write and run tests. It is also easy to change your UI framework. For instance, add React Native version of the application.

Think about Tree Shaking

We recommend doing all store changes in separated functions. It will allow to tree shake unused functions from JS bundle.

export function changeStore (newValue: string) {
  if (validate(newValue)) {
    throw new Error('New value is not valid')
  } else {
    store.set(newValue)
  }
}

For builder, you can add properties to the store, but try to avoid it.

interface UserExt {
  avatarCache?: string
}

export function User = defineMap<UserValue, [], UserExt>((store, id) => {
  …
})

function getAvatar (user: BuilderStore<typeof User>) {
  if (!user.avatarCache) {
    user.avatarCache = generateAvatar(getValue(user).email)
  }
  return user.avatarCache
}

Separate changes and reaction

Use a separated listener to react on new store’s value, not a function where you change this store.

  function increase () {
    update(counter, value => value + 1)
-   printCounter(getValue(counter))
  }

+ counter.subscribe(value => {
+   printCounter(value)
+ })

A "change" function is not only a way for store to a get new value. For instance, persistent store could get the new value from another browser tab.

With this separation your UI will be ready to any source of store’s changes.

Reduce getValue() usage outside of tests

getValue() returns current value and it is a good solution for tests.

But it is better to use useStore(), $store, or Store#subscribe() in UI to subscribe to store changes and always render the actual data.

- const { userId } = getValue(profile)
+ const { userId } = useStore(profile)

In store’s functions you can use update and updateKey shortcuts:

  function increase () {
-   counter.set(getValue(counter) + 1)
+   update(counter, value => value + 1)
  }

Known Issues

Diamond Problem

To make stores simple and small, Nano Stores doesn’t solve “Diamond problem”.

  A
  ↓
F←B→C
↓   ↓
↓   D
↓   ↓
G→H←E

On A store changes, H store will be called twice in different time by change signals coming from different branches.

You need to care about these changes on your own.

ESM

Nano Stores use ES modules and doesn’t provide CommonJS exports. You need to use ES modules in your application to import Nano Stores.

For instance, for Next.js you need to use next-transpile-modules to fix lack of ESM support in Next.js.

// next.config.js
const withTM = require('next-transpile-modules')(['nanostores'])

module.exports = withTM({
  /* previous configuration goes here */
})