{"id":20470174,"url":"https://github.com/dividab/graphql-norm-patch","last_synced_at":"2025-04-13T10:43:59.513Z","repository":{"id":57252854,"uuid":"145111435","full_name":"dividab/graphql-norm-patch","owner":"dividab","description":"Declarative patching of normalized GraphQL responses","archived":false,"fork":false,"pushed_at":"2020-07-21T12:39:47.000Z","size":351,"stargazers_count":6,"open_issues_count":5,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T23:02:24.456Z","etag":null,"topics":["cache","graphql","normalization"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dividab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-17T11:16:58.000Z","updated_at":"2022-02-09T03:47:31.000Z","dependencies_parsed_at":"2022-08-31T22:11:16.750Z","dependency_job_id":null,"html_url":"https://github.com/dividab/graphql-norm-patch","commit_stats":null,"previous_names":["dividab/gql-cache-patch"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fgraphql-norm-patch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fgraphql-norm-patch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fgraphql-norm-patch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fgraphql-norm-patch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dividab","download_url":"https://codeload.github.com/dividab/graphql-norm-patch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248702052,"owners_count":21148114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","graphql","normalization"],"created_at":"2024-11-15T14:12:00.557Z","updated_at":"2025-04-13T10:43:59.491Z","avatar_url":"https://github.com/dividab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql-norm-patch\n\n[![npm version][version-image]][version-url]\n[![travis build][travis-image]][travis-url]\n[![Coverage Status][codecov-image]][codecov-url]\n[![code style: prettier][prettier-image]][prettier-url]\n[![MIT license][license-image]][license-url]\n\nDeclarative patching of normalized GraphQL responses\n\n## Overview\n\nThis package contains functions to do declarative patching of normalized GraphQL responses. I was design to work with [graphql-norm](https://www.npmjs.com/package/graphql-norm) but it should also work with any plain JS object that contains a normalized structure of GraphQL responses.\n\nYou can declare patches as data and then apply them. One usage is to apply optimistic updates to the cache when doing mutations.\n\nSince the patches are data you can also return patches from the server. So the server could return patches to the client as part of the mutation response, and the client can then apply them to get the needed upates. One benefit of this is that the server now is responsible for knowing what parts of the schema needs updating after a mutation has been executed.\n\n## How to install\n\n```\nnpm install graphql-norm-patch --save\n```\n\n## How to use\n\nThe package has the following constructor functions for creating the patches:\n\n```ts\nexport function createEntity\u003cT\u003e(\n  id: GraphQLEntityCache.EntityId,\n  newValue: T\n): CreateEntity;\n\nexport function deleteEntity(id: GraphQLEntityCache.EntityId): DeleteEntity;\n\nexport function updateField\u003cT\u003e(\n  id: string,\n  fieldName: Extract\u003ckeyof T, string\u003e,\n  newValue: GraphQLEntityCache.EntityFieldValue | null\n): UpdateField;\n\nexport function insertElement\u003cT\u003e(\n  id: GraphQLEntityCache.EntityId,\n  fieldName: Extract\u003ckeyof T, string\u003e,\n  index: number,\n  newValue: GraphQLEntityCache.EntityFieldValue\n): InsertElement;\n\nexport function removeElement\u003cT\u003e(\n  id: GraphQLEntityCache.EntityId,\n  fieldName: Extract\u003ckeyof T, string\u003e,\n  index: number\n): RemoveElement;\n\nexport function removeEntityElement\u003cT\u003e(\n  id: GraphQLEntityCache.EntityId,\n  fieldName: Extract\u003ckeyof T, string\u003e,\n  entityId: GraphQLEntityCache.EntityId\n): RemoveEntityElement;\n```\n\nIt also has a function to apply the patches to a normalized map and returns the new normalized map:\n\n```ts\nexport function apply(patches: ReadonlyArray\u003cPatch\u003e, cache: NormMap): NormMap;\n```\n\nHere is a small example:\n\n```js\nimport { createEntity, apply } from \"graphql-norm-patch\";\n\nconst cache = {};\nconst patch = createEntity(\"myid\", { id: \"myid\", name: \"foo\" });\nconst patchedCache = apply(testCase.patches, cache);\n\nconsole.log(JSON.stringify(cache));\n/* { myid: { id: \"myid\", name: \"foo\" } } */\n```\n\n## How patches are applied to the cache\n\nA patch always specifies an ID for an entity in the cache. If the specified ID does not exist in cache, applying the patch will silently do nothing. The exception to this rule is the `CreateEntity` patch which will create the entity in the cache.\n\nApplying patches that specify a field name will only have effect if that field name already exits in the cache. If the field name does not exist on the specified entity in the cache, then applying the patch will silently do nothing. If a field exists but have value `null` and a `InsertElement` patch is applied to that field, a new array will automatically be created when applying the patch.\n\n## Type safety\n\nThis package has built-in typescript types, and when using typescript some type saftey can be achieved by using types generated for the GraphQL schema. Types for the schema can be genereted using for example [graphql-code-generator](https://www.npmjs.com/package/graphql-code-generator) and then be used as this:\n\n```ts\nimport { updateField } from \"graphql-norm-patch\";\n\nconst patch = updateField\u003cGraphQLSchemaTypes.Foo\u003e(\"myid\", \"myfield\", \"myvalue\");\n```\n\n## Future work\n\nIt would be interesting to investigate returning patches as an [extension](http://facebook.github.io/graphql/June2018/#sec-Response-Format) of the graphql response.\n\n## How to develop\n\nTo execute the tests run `yarn test`.\n\n## How to publish\n\n```\nyarn version --patch\nyarn version --minor\nyarn version --major\n```\n\n[version-image]: https://img.shields.io/npm/v/graphql-norm-patch.svg?style=flat\n[version-url]: https://www.npmjs.com/package/graphql-norm-patch\n[travis-image]: https://travis-ci.com/dividab/graphql-norm-patch.svg?branch=master\u0026style=flat\n[travis-url]: https://travis-ci.com/dividab/graphql-norm-patch\n[codecov-image]: https://codecov.io/gh/dividab/graphql-norm-patch/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/dividab/graphql-norm-patch\n[license-image]: https://img.shields.io/github/license/dividab/graphql-norm-patch.svg?style=flat\n[license-url]: https://opensource.org/licenses/MIT\n[prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat\n[prettier-url]: https://github.com/prettier/prettier\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Fgraphql-norm-patch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdividab%2Fgraphql-norm-patch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Fgraphql-norm-patch/lists"}