Classy Store

Reactive Collections

Use reactiveMap and reactiveSet collections inside Classy Store instances.

Use reactiveMap() and reactiveSet() when mutations such as .set(), .add(), .delete(), and .clear() need to notify store subscribers. Put the collection inside a store created by createClassyStore() and mutate it through that store.

Native Map and Set are opaque leaves: replacing their property can notify subscribers, but mutating their contents does not. Reactive collections use arrays internally and expose Map-like and Set-like methods. They are not native Map or Set instances, and key/value lookups scan those arrays.

Try the Collections example →

Collection behavior

  • Reading .size takes constant time. Looking up, inserting, replacing, or deleting an entry can scan the backing array. Passing validated entries or values to the factory deduplicates the initial iterable in one pass.
  • Prefer primitive map keys and set values. Objects read through a store can be proxied, and snapshots copy supported objects; their identity may differ from the original input object.
  • Lookup methods use Object.is, which distinguishes 0 and -0. Initial iterables are deduplicated with native Map/Set semantics, which treat those two values as equal. Avoid depending on signed-zero keys.
  • Iterators copy the entry/value list when created. Later additions and removals do not change that list; referenced objects can still change. This differs from native live iterators.
  • Both collections expose size, has, delete, clear, keys, values, entries, forEach, and iteration with for...of. The map also exposes get and set. The set exposes add.

Reactive updates

import {createClassyStore} from '@codebelt/classy-store';
import {reactiveMap, reactiveSet} from '@codebelt/classy-store/collections';

class DirectoryStore {
  labels = reactiveMap<string, string>();
  selected = reactiveSet<string>();

  select(id: string, label: string) {
    this.labels.set(id, label);
    this.selected.add(id);
  }
}

const directoryStore = createClassyStore(new DirectoryStore());
directoryStore.select('u1', 'Alice');

React components read these collections with useClassyStore, just like other store data. Select an existing snapshot property or a primitive such as .size; if a selector creates a new array, consider shallowEqual where its one-level comparison matches your needs.

ReactiveMap and ReactiveSet are public types from the collections entry. Construct values with the factory functions.

Persisting a ReactiveMap

JSON does not retain a collection's prototype or methods. Use a property transform to serialize entries and reconstruct the collection during hydration. For string keys and values:

import {createClassyStore} from '@codebelt/classy-store';
import {reactiveMap} from '@codebelt/classy-store/collections';
import {persist} from '@codebelt/classy-store/utils';

class LabelStore {
  labels = reactiveMap<string, string>();
}

const labelStore = createClassyStore(new LabelStore());
const persistence = persist(labelStore, {
  name: 'labels',
  storage: localStorage,
  properties: [
    {
      key: 'labels',
      serialize: (labels) => [...labels.entries()],
      deserialize: (stored) => {
        if (!Array.isArray(stored)) throw new Error('Expected label entries');
        const entries = stored.map((entry): [string, string] => {
          if (
            !Array.isArray(entry) ||
            entry.length !== 2 ||
            typeof entry[0] !== 'string' ||
            typeof entry[1] !== 'string'
          ) {
            throw new Error('Invalid label entry');
          }
          return [entry[0], entry[1]];
        });
        return reactiveMap(entries);
      },
    },
  ],
});

After saving labelStore.labels.set('u1', 'Alice'), the storage envelope contains:

{
  "version": 0,
  "state": {
    "labels": [["u1", "Alice"]]
  }
}

The restored labels value retains .get(), .set(), and the other collection methods. Validate object-valued entries according to your application's schema before constructing the collection.

Persisting a ReactiveSet

Serialize the values and rebuild the set after validating stored input:

import {createClassyStore} from '@codebelt/classy-store';
import {reactiveSet} from '@codebelt/classy-store/collections';
import {persist} from '@codebelt/classy-store/utils';

class TagStore {
  tags = reactiveSet<string>();
}

const tagStore = createClassyStore(new TagStore());
const persistence = persist(tagStore, {
  name: 'tags',
  storage: localStorage,
  properties: [
    {
      key: 'tags',
      serialize: (tags) => [...tags],
      deserialize: (stored) => {
        if (!Array.isArray(stored)) throw new Error('Expected tags');
        if (!stored.every((value) => typeof value === 'string')) {
          throw new Error('Invalid tag');
        }
        return reactiveSet<string>(stored);
      },
    },
  ],
});

With tags added, the stored state is an array of strings:

{
  "version": 0,
  "state": {
    "tags": ["typescript", "react"]
  }
}

These are client-only setup examples. Dispose the persistence handle when its owner is torn down. For React and SSR, create it in an effect and call persistence.dispose() in cleanup; see store scoping. Transform failures are reported as parse errors during hydration. Explicit rehydrate() calls also reject, so handle their promises as described in the persistence guide.

On this page