Normalized entity caching — interest check and design discussion

[Danny-Devs]

The problem

Pinia Colada's cache is document-based: each query key maps to one data blob. When the same entity appears in multiple queries, it lives as independent copies that can diverge:

// These two queries both contain contact id=5, stored separately.
const { data: contacts } = useQuery({
  key: ['contacts'],
  query: () => fetchContacts(), // returns [{ contactId: 5, name: 'Alice' }, ...]
})

const { data: contact } = useQuery({
  key: ['contacts', 5],
  query: () => fetchContact(5), // returns { contactId: 5, name: 'Alice' }
})

// A WebSocket event updates contact 5's name to 'Alicia'.
// Only one cache entry gets the update. The other is stale.

For most apps, this is fine — you invalidate and refetch. But in WebSocket-heavy apps where the server pushes entity updates, you want a single write to propagate everywhere instantly — no invalidation, no refetch. That requires normalized storage: entities stored once by type+ID, queries holding references instead of copies.

This is the same problem Apollo Client solved for GraphQL. I haven't found an equivalent for REST/generic data-fetching in the Vue ecosystem — if I'm wrong, I'd love to know about it.

What I'm proposing

A normalization plugin that:

1. On write: intercepts setEntryState via $onAction, normalizes incoming data using a schema (normalizr-inspired), and stores entities in a shared Pinia store. The query entry keeps normalized references instead of full objects.
2. On read: denormalizes references back into full objects. Since the shared store is reactive, changes to any entity propagate to every query that references it — Vue's dependency tracking does the work.

The write path is straightforward — setEntryState is the canonical choke point, and setQueryData flows through it. The extend and remove hooks handle lifecycle.

The read path is the interesting design question, and that's mainly what I'd like your input on.

Background

I've built this pattern in production — replacing TanStack Query with Pinia + normalizr in a WebSocket-heavy Vue 3 app. Entities stored once, WS events writing directly to normalized stores, all views updating reactively. It works well, and I'd like to generalize the approach into something the broader Pinia Colada ecosystem could use.

Questions

1. Is this something you'd want as an official plugin, or better as a community package? Happy either way — just want to align before writing code.

2. The read interception problem: useQuery reads entry.state.value.data through a computed with no plugin hook in that path. I noticed the delay plugin replaces entry.asyncStatus during extend and useQuery reads through the replacement seamlessly — would a similar pattern for entry.state be reasonable here? Or would you prefer something different, like a lightweight transformData hook in the data path? (Your comment on Discussion #113 about select being a plugin concern feels adjacent.)

3. Schema-to-query mapping: The plugin needs to know which schemas apply to which query keys. I'm leaning toward a top-level config ({ schemas: { contacts: contactSchema } }) rather than per-query options. Does that align with how you think about plugin configuration?

Happy to build a proof-of-concept first if that's more useful than discussing in the abstract.

[posva]

1. This sounds amazing! I've already had an eye on normalizr normy (although any normalization lib could do) but I don't have the time to create a package like this and maintain (especially not having an app that would use it), so I will gladly welcome a community plugin that I can add to docs

I noticed the delay plugin replaces entry.asyncStatus during extend and useQuery reads through the replacement seamlessly — would a similar pattern for entry.state be reasonable here

2. I think so, yes. I should work out nicely because state is the source of truth

3. I'm not sure of this because I barely have any experience with data normalization and what could cause friction and bugs. On one hand a top level config is convenient, on another hand it's not tree shakable but maybe just having lazy loaded versions is enough: schemas: { contacts: () => import('...') }

[Danny-Devs]

Hey @posva, thank you for the response! I'm happy to create and maintain this package--I whipped up a working implementation.

TL;DR: The plugin is published as
pinia-colada-plugin-normalizer and there's a live playground to try it.

The customRef approach you suggested for entry.state worked perfectly — the setter normalizes (extracts entities into a shared store, saves references internally), and the getter denormalizes (replaces references with live entity data).

app.use(PiniaColada, {
  plugins: [
    PiniaColadaNormalizer({
      entities: {
        contact: defineEntity({ idField: 'contactId' }),
      },
    }),
  ],
})

// Opt in per query:
const { data } = useQuery({
  key: ['contacts'],
  query: () => fetchContacts(),
  normalize: true,
})

// WebSocket writes propagate to all queries automatically:
const entityStore = useEntityStore()
ws.on('CONTACT_UPDATED', (payload) => {
  entityStore.set('contact', payload.contactId, payload)
})

Re: #1
Published as a community plugin following your naming convention. Happy to submit a PR to add it to the community plugins page when you think it's ready.

Re: #2 (read interception)
customRef replacement in extend worked great.

Re: #3 (schema config)
Went with per-entity-type config rather than per-query schemas. Simpler, no schema library dependency.

defineEntity({ idField: 'contactId' }) is the whole API for most cases. No tree-shaking concerns since entity defs are plain objects.

---

~10KB gzip, zero runtime dependencies.

Would love your feedback on the API surface.

Created with assistance from Claude Code, vetted by HITL (DannyDevs)