pinia-colada-plugin-normalizer

npm · GitHub

Normalized entity caching plugin for Pinia Colada. Apollo-style normalization with zero configuration and Vue-native performance.

Store each entity once. Update it in one place, every query sees the change. No more stale data from missed cache invalidations.

• Transparent — uses Vue's customRef to intercept reads/writes. Your app code doesn't know normalization exists.
• Minimal — ~2,400 LOC, zero runtime dependencies. Just Vue + Pinia Colada.
• Type-safe — optional EntityRegistry for end-to-end typed entity access across the entire API.
• Extensible — swappable EntityStore interface for custom backends (IndexedDB, SQLite+WASM).

Installation

pnpm add pinia-colada-plugin-normalizer

Requires @pinia/colada >= 1.0.0, pinia >= 2.1.0, vue >= 3.3.0.

Quick Start

import { PiniaColada } from "@pinia/colada";
import { PiniaColadaNormalizer, defineEntity } from "pinia-colada-plugin-normalizer";

app.use(PiniaColada, {
  plugins: [
    PiniaColadaNormalizer({
      entities: {
        contact: defineEntity<Contact>({ idField: "contactId" }),
        order: defineEntity<Order>({ idField: "orderId" }),
      },
    }),
  ],
});

Opt in per query:

const { data } = useQuery({
  key: ["contacts"],
  query: () => fetchContacts(),
  normalize: true,
});

Type Safety

Augment the EntityRegistry interface for end-to-end typed access:

declare module "pinia-colada-plugin-normalizer" {
  interface EntityRegistry {
    contact: Contact;
    order: Order;
  }
}

// Now fully typed everywhere:
entityStore.get("contact", "1"); // ShallowRef<Contact | undefined>
entityStore.set("contact", "1", data); // data must match Contact
useEntityQuery("contact", (c) => c.name); // c is Contact
onEntityAdded("contact", (e) => e.data); // data is Contact | undefined

Without the registry, everything defaults to EntityRecord — fully backwards compatible.

The Problem

Pinia Colada stores data per query key. When the same entity appears in multiple queries, it lives as independent copies that can diverge:

const { data: contacts } = useQuery({ key: ["contacts"], query: fetchContacts });
const { data: contact } = useQuery({ key: ["contacts", 5], query: () => fetchContact(5) });

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

With normalization, contact 5 is stored once. Both queries read from the same entity. One write, all views update.

Entity Store Writes

Write directly to the entity store — no invalidation needed:

import { useEntityStore } from "pinia-colada-plugin-normalizer";

const entityStore = useEntityStore();

// From a WebSocket event:
ws.on("CONTACT_UPDATED", (data) => {
  entityStore.set("contact", data.contactId, data);
});

// From a mutation response:
const { mutate } = useMutation({
  mutation: (data) => api.updateContact(data),
  onSuccess: (response) => {
    entityStore.set("contact", response.contactId, response);
    // All queries referencing this contact update instantly. No refetch.
  },
});

Optimistic Updates

Transaction-based with rollback. Handles concurrent mutations correctly:

import { useOptimisticUpdate } from "pinia-colada-plugin-normalizer";

const { apply, transaction } = useOptimisticUpdate();

// Simple (single mutation):
const { mutate } = useMutation({
  mutation: (data) => api.updateContact(data),
  onMutate: (data) => apply("contact", data.contactId, data),
  onError: (_err, _vars, rollback) => rollback?.(),
});

// Multi-mutation transaction:
const tx = transaction();
tx.set("contact", "1", { name: "Alicia" });
tx.set("order", "5", { status: "confirmed" });
// On success: tx.commit()
// On failure: tx.rollback() — restores server truth, replays other active transactions

Cache Redirects (Zero-Spinner Navigation)

Navigate from a list to a detail page with zero loading spinner — if the entity was already fetched by a list query, the detail page shows it instantly while the full data loads in the background.

Automatic (convention-based)

PiniaColadaNormalizer({
  entities: { contact: defineEntity({ idField: "contactId" }) },
  autoRedirect: true, // ← one flag
});

// Any query with key ['contact', id] auto-serves from cache:
const { data, isPlaceholderData } = useQuery({
  key: ["contact", id],
  query: () => fetchContact(id),
  normalize: true,
});
// data is available INSTANTLY if contact was in a prior list query.
// isPlaceholderData is true until the real fetch completes.

The convention: if a query key is [registeredEntityType, id] (exactly 2 segments, first matches an entity in your config), the plugin auto-injects placeholderData from the entity store. List queries (1 segment) and nested resources (3+ segments) are skipped.

Per-query overrides:

// Disable for a specific query:
useQuery({ key: ["contact", id], ..., redirect: false });

// Custom mapping for non-standard keys:
useQuery({ key: ["dashboard-contact", id], ..., redirect: { entityType: "contact" } });

Manual (composable)

For full control, use useCachedEntity directly:

import { useCachedEntity } from "pinia-colada-plugin-normalizer";

const { data } = useQuery({
  key: ["contact", id],
  query: () => fetchContact(id),
  placeholderData: useCachedEntity("contact", () => id),
});

Array Operations

Add or remove entities from list queries without refetching:

import { updateQueryData, deleteEntity } from "pinia-colada-plugin-normalizer";

// Add to a specific list query:
entityStore.set("contact", "99", newContact);
updateQueryData(["contacts"], (data) => [...(data as any[]), newContact]);

// Remove from ALL queries + entity store (one call):
deleteEntity("contact", "42");

Real-Time Hooks

Fine-grained entity lifecycle events:

import { onEntityAdded, onEntityUpdated, onEntityRemoved } from "pinia-colada-plugin-normalizer";

onEntityAdded("contact", (event) => toast.success(`${event.data.name} joined!`));
onEntityUpdated("contact", (event) => console.log("Updated:", event.id));
onEntityRemoved("contact", (event) => toast.info(`${event.previousData?.name} left`));

Entity Queries & Indexes

Filtered reactive views and O(1) field lookups:

import { useEntityQuery, createEntityIndex } from "pinia-colada-plugin-normalizer";

// Filtered view (reactive, updates automatically)
const activeContacts = useEntityQuery("contact", (c) => c.status === "active");

// Index for O(1) lookups by field value
const statusIndex = createEntityIndex("contact", "status");
const active = statusIndex.get("active"); // ComputedRef<Contact[]>

Coalescing

Batch multiple notifications into a single fetch:

import { createCoalescer } from "pinia-colada-plugin-normalizer";

const coalescer = createCoalescer(async (entityKeys) => {
  const entities = await api.fetchEntitiesByIds(entityKeys);
  for (const entity of entities) {
    entityStore.set("contact", entity.id, entity);
  }
}, 100); // 100ms batching window

ws.on("ENTITY_STALE", ({ key }) => coalescer.add(key));

API Reference

PiniaColadaNormalizer(options?)

Creates the plugin.

| Option | Type | Default | Description | | ---------------- | ---------------------------------- | --------- | ---------------------------------------------- | | entities | Record<string, EntityDefinition> | {} | Entity type configurations | | defaultIdField | string | 'id' | Default ID field for auto-detection | | store | EntityStore | in-memory | Custom storage backend | | autoNormalize | boolean | false | Normalize all queries by default | | autoRedirect | boolean | false | Auto-serve cached entities as placeholder data |

defineEntity<T>(config)

Configure an entity type. The generic T provides type safety for callbacks.

| Option | Type | Default | Description | | --------- | --------------------------------- | ------------- | ----------------------------------------- | | idField | string & keyof T | 'id' | Field containing the entity ID | | getId | (entity: T) => string \| null | — | Custom ID extraction (for composite keys) | | merge | (existing: T, incoming: T) => T | shallow merge | Custom merge strategy |

useEntityStore(pinia?)

Access the entity store. Returns typed results when EntityRegistry is augmented.

invalidateEntity(entityType, id, pinia?)

Refetch all active queries referencing the given entity.

updateQueryData(key, updater, pinia?)

Update a query's data directly. Updater receives denormalized data, result is re-normalized.

deleteEntity(entityType, id, pinia?)

Remove an entity from all normalized queries and the entity store.

useCachedEntity(entityType, id, pinia?)

Returns a placeholderData-compatible function that serves cached entities instantly. See Cache Redirects.

useOptimisticUpdate(pinia?)

Returns { apply, transaction } for optimistic updates with rollback.

createCoalescer<T>(onFlush, delay?)

Batch items and flush after a delay. Framework-agnostic.

Entity Store Interface

| Method | Description | | ---------------------------------------- | --------------------------------------------------------- | | set(type, id, data) | Shallow-merge entity | | replace(type, id, data) | Full replacement (no merge) | | setMany(entities) | Batch write | | remove(type, id) | Remove entity | | get(type, id) | Reactive ref (typed when registry used) | | getByType(type) | Reactive computed array (typed when registry used) | | getEntriesByType(type) | Non-reactive snapshot of {id, data} pairs | | has(type, id) | Check existence | | subscribe(listener, filter?) | Entity change events (typed when registry used) | | retain(type, id) / release(type, id) | Reference counting for GC | | gc() | Collect unreferenced entities | | toJSON() / hydrate(snapshot) | Serialization / SSR hydration (handles nested EntityRefs) | | clear() | Remove all entities |

How It Works

Uses Vue's customRef to transparently intercept reads and writes on entry.state:

1. On write: When Pinia Colada sets query state, the customRef setter extracts entities, stores them in the entity store, and saves references internally
2. On read: When components access query data, the customRef getter replaces references with live reactive entity data
3. On entity change: entityStore.set() or remove() writes directly — Vue reactivity propagates to all queries referencing that entity. Entities that arrive late (out-of-order) or are removed and re-added trigger re-renders automatically.

Follows the delay plugin's pattern of replacing entry properties with customRef during the extend hook. SSR-safe via defineStore scoping.

License

MIT