graphql-normalizr
A lightweight library that normalizes nested GraphQL responses into flat, key-value objects for efficient client-side caching.
What is graphql-normalizr?
GraphQL Normalizr is a JavaScript library that normalizes nested GraphQL API responses into flat, key-value objects for efficient client-side caching. It solves the problem of persisting GraphQL data in state management libraries like Redux or Apollo Client by converting deeply nested structures into normalized collections, enabling faster data access and updates.
Frontend developers working with GraphQL APIs who need to cache responses in client-side state management systems like Redux, Apollo Client, or custom Flux stores.
Developers choose GraphQL Normalizr for its lightweight, configurable approach to normalization without heavy dependencies, offering fine-grained control over entity mapping, ID fields, and connection handling while maintaining performance.
Overview
Normalize GraphQL responses for persisting in the client cache/state
Use Cases
Best For
- Caching GraphQL responses in Redux stores for efficient state updates
- Integrating GraphQL data with Apollo Client's local cache management
- Handling Relay-style connections and paginated data in client caches
- Optimizing performance in applications with deeply nested GraphQL queries
- Building custom state management solutions that require normalized data structures
- Preparing GraphQL data for offline persistence or real-time updates
Not Ideal For
- Projects using Apollo Client or Relay with built-in caching, where additional normalization could cause conflicts or redundancy
- GraphQL APIs that lack consistent `__typename` or `id` fields and cannot be modified server-side
- Applications with simple, flat data structures where normalization adds complexity without performance gains
- Teams needing server-side data processing or normalization outside of JavaScript environments
Pros & Cons
Pros
Efficiently flattens nested GraphQL responses into key-value stores using `__typename` and `id` fields, as shown in the TL;DR transformation example, enabling faster cache lookups.
Supports custom ID keys, entity naming, field ignoring, and GraphQL connections through a comprehensive config object, such as `idKey: 'uid'` or `useConnections: true`, allowing tailored integration.
Automatically adds required `__typename` and `id` fields to GraphQL queries if missing, via the `parse` or `addRequiredFields` methods, simplifying client-side setup without modifying server queries.
Includes optional caching to prevent re-normalization of unchanged data, improving efficiency for scenarios like polling or repeated queries, as noted in the caching configuration.
Cons
Version 2.x introduced changes to entity name casing that require manual configuration adjustments, as highlighted in the migration guide, which can be a hurdle for upgrades.
With numerous options like typeMap, ignore, lists, and casing, the setup can be overwhelming and error-prone for developers not needing fine-grained control, increasing initial time investment.
Relies on `__typename` and `id` fields being present or augmentable, which may not be feasible if the GraphQL server doesn't support these or if queries are static and unmodifiable.
Frequently Asked Questions
Related Projects
PrismaNext-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB
BitAI-powered development workspaces with reusable components, architectural clarity and zero overhead.
AmplicationAmplication brings order to the chaos of large-scale software development by creating Golden Paths for developers - streamlined workflows that drive consistency, enable high-quality code practices, simplify onboarding, and accelerate standardized delivery across teams.
graphql-code-generatorA tool for generating code based on a GraphQL schema and GraphQL operations (query/mutation/subscription), with flexible support for custom plugins.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.