{"id":13564234,"url":"https://github.com/graphql-kit/graphql-lodash","last_synced_at":"2025-04-09T10:04:20.673Z","repository":{"id":40641694,"uuid":"86464743","full_name":"graphql-kit/graphql-lodash","owner":"graphql-kit","description":"🛠 Data manipulation for GraphQL queries with lodash syntax","archived":false,"fork":false,"pushed_at":"2022-06-21T21:48:08.000Z","size":5936,"stargazers_count":1237,"open_issues_count":13,"forks_count":48,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-02T08:16:26.666Z","etag":null,"topics":["api","functional-programming","graphql","lodash"],"latest_commit_sha":null,"homepage":"https://apis.guru/graphql-lodash/","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/graphql-kit.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2017-03-28T13:41:27.000Z","updated_at":"2025-03-30T20:21:45.000Z","dependencies_parsed_at":"2022-07-14T04:30:36.733Z","dependency_job_id":null,"html_url":"https://github.com/graphql-kit/graphql-lodash","commit_stats":null,"previous_names":["ivangoncharov/graphql-lodash","apis-guru/graphql-lodash"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-kit%2Fgraphql-lodash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-kit%2Fgraphql-lodash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-kit%2Fgraphql-lodash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-kit%2Fgraphql-lodash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphql-kit","download_url":"https://codeload.github.com/graphql-kit/graphql-lodash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246947793,"owners_count":20859317,"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":["api","functional-programming","graphql","lodash"],"created_at":"2024-08-01T13:01:28.430Z","updated_at":"2025-04-09T10:04:20.636Z","avatar_url":"https://github.com/graphql-kit.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","graphql"],"sub_categories":[],"readme":"![GraphQL Lodash logo](docs/gqlodash-logo.png)\n\n# GraphQL Lodash\n[![npm](https://img.shields.io/npm/v/graphql-lodash.svg)](https://www.npmjs.com/package/graphql-lodash) [![David](https://img.shields.io/david/APIs-guru/graphql-lodash.svg)](https://david-dm.org/APIs-guru/graphql-lodash)\n[![David](https://img.shields.io/david/dev/APIs-guru/graphql-lodash.svg)](https://david-dm.org/APIs-guru/graphql-lodash?type=dev)\n[![npm](https://img.shields.io/npm/l/graphql-lodash.svg)](https://github.com/APIs-guru/graphql-lodash/blob/master/LICENSE)\n\nUnleash the power of [lodash](https://lodash.com/) inside your GraphQL queries\n\n#### Table of contents\n- [Why?](#why)\n- [Example queries](#example-queries)\n- [API](#api)\n- [Usage Examples](#usage-examples)\n  - [`fetch`](#fetch-example)\n  - [Caching clients](#caching-clients)\n  - [**Usage with react-apollo**](#usage-with-react-apollo)\n- [Usage on server-side](#usage-on-server-side) (tl;dr **don't**)\n\n## Why?\nGraphQL allows to ask for what you need and get exactly that. But what about the shape?\nGraphQL Lodash gives you the power of `lodash` right inside your GraphQL Query using `@_` directive.\n\n[![lodash usage gif](docs/lodash.gif)](https://apis.guru/graphql-lodash/)\n\n**Note**: This is an **experimental** project created to explore the concept of **Query and transformation collocation**.\n\nWe encourage you to try it inside our [demo](https://apis.guru/graphql-lodash/) or check detailed [walkthrough](https://docs.google.com/presentation/d/1aBXjC98hfYrbjUKlWGFMWgAMh9FcxeW_w97uatNYXls/pub?start=false\u0026loop=false\u0026delayms=3000).\n\n## Example queries\nHere are a few query examples you can run against StartWars API:\n\n#### Find the planet with the biggest population\n![Find the planet with the biggest population](docs/planet_with_max_population.png)\n#### Get gender statistics\n![Get gender statistics](docs/gender_stats.png)\n#### Map characters to films they are featured in\n![Map characters to films they are featured in](docs/people_to_films.png)\n\n## Install\n\n    npm install --save graphql-lodash\nor\n\n    yarn add graphql-lodash\n\n## API\n\n### `graphqlLodash(query, [operationName])`\n\n- **query** (_required_) - query string or query AST\n- **operationName** (_optional_) - required only if the query contains multiple operations\n\n### Returns\n```\n{\n  query: string|object,\n  transform: Function\n}\n```\n- **query** - the original query with stripped `@_` directives\n- **transform** - function that receives `response.data` as a single argument and returns\nthe same data in the intended shape.\n\n\n\n## Usage Examples\n\nThe simplest way to integrate `graphql-lodash` is to write wrapper function for graphql client of you choice:\n```js\nimport { graphqlLodash } from 'graphql-lodash';\n\nfunction lodashQuery(queryWithLodash) {\n  let { query, transform } = graphqlLodash(queryWithLodash);\n  // Make a GraphQL call using 'query' variable as a query\n  // And place result in 'result' variable\n  ...\n  result.data = transform(result.data);\n  return result;\n}\n```\n\n### Fetch example\nAn example of a simple client based on [fetch API](https://developer.mozilla.org/en/docs/Web/API/Fetch_API):\n```js\nfunction executeGraphQLQuery(url, query) {\n  return fetch(url, {\n    method: 'POST',\n    headers: new Headers({\"content-type\": 'application/json'}),\n    body: JSON.stringify({ query: query })\n  }).then(response =\u003e {\n    if (response.ok)\n      return response.json();\n    return response.text().then(body =\u003e {\n      throw Error(response.status + ' ' + response.statusText + '\\n' + body);\n    });\n  });\n}\n\nfunction lodashQuery(url, queryWithLodash) {\n  let { query, transform } = window.GQLLodash.graphqlLodash(queryWithLodash);\n  return executeGraphQLQuery(url, query).then(result =\u003e {\n    result.data = transform(result.data);\n    return result;\n  });\n}\n\n// then use as bellow\nlodashQuery('https://swapi.apis.guru', `{\n  planetWithMaxPopulation: allPlanets @_(get: \"planets\") {\n    planets @_(maxBy: \"population\") {\n      name\n      population\n    }\n  }\n}`).then(result =\u003e console.log(result.data));\n```\n\n### Caching clients\nFor caching clients like Relay and Apollo we recommend to apply the transformation after the caching layer.\nHere is proposed solution for Relay:\n\n![Relay usage](docs/relay-architecture.png)\n\nWe are still figuring out how to do this and any [feedback](https://github.com/APIs-guru/graphql-lodash/issues/new) is welcome.\n\n#### Usage with [react-apollo](https://github.com/apollographql/react-apollo)\n\nWhen using with Apollo you can use `props` option to apply transformations:\n\n```js\nconst rawQuery = gql`\n  # query with @_ directives\n`;\n\nconst {query, transform} = graphqlLodash(rawQuery);\nexport default graphql(query, {\n  props: (props) =\u003e ({...props, rawData: props.data, data: transform(props.data)})\n})(Component);\n```\n\nYou can write a simple wrapper for simplicity:\n\n```js\nimport { graphql } from 'react-apollo';\nimport { graphqlLodash } from 'graphql-lodash';\n\nexport function gqlLodash(rawQuery, config) {\n  const {query, transform} = graphqlLodash(rawQuery);\n  let origProps = (config \u0026\u0026 config.props) || ((props) =\u003e props);\n\n  return (comp) =\u003e graphql(query, {...config,\n    props: (props) =\u003e origProps({\n      ...props,\n      rawData: props.data,\n      data: transform(props.data)\n    })\n  })(comp);\n}\n// then use as bellow\nexport default gqlLodash(query)(Component);\n```\n\nJust replace `graphql` with `gqlLodash` and you are ready to use lodash in your queries.\nCheck out the [react-apollo-lodash-demo](https://github.com/APIs-guru/react-apollo-lodash-demo) repo.\n\nYou can also do the transformation inside an [Apollo\nLink](https://www.apollographql.com/docs/link/) by rewriting the\nparsed GraphQL `Document`:\n\n```js\nnew ApolloLink((operation, forward) =\u003e {\n  const { query, transform } = graphqlLodash(operation.query);\n  operation.query = query;\n  return forward(operation)\n    .map(response =\u003e ({\n      ...response,\n      data: transform(response.data),\n    }));\n});\n```\n\nChaining this link with the other links passed to your `ApolloClient`\nwill apply the transformation to every query that\nApollo runs, such as those from the `\u003cQuery /\u003e` component or\nsubscriptions.\n\n### Introspection queries\n\nIf your application uses introspection queries (like GraphiQL does to\nget documentation and autocomplete information), you will also need to\nextend the introspection query result with the directives from\ngraphql-lodash. One way you could do this is:\n\n```js\nimport {\n  buildClientSchema,\n  extendSchema,\n  graphqlSync,\n  introspectionQuery,\n} from 'graphql';\n\n// inside the above ApolloLink function\nif (response.data \u0026\u0026 response.data.__schema) {\n  const schema = extendSchema(\n    buildClientSchema(response.data),\n    lodashDirectiveAST,\n  );\n  return graphqlSync(schema, introspectionQuery);\n}\n```\n\nSee the `demo/` source in this repo for another example of modifying\nthe introspection query result.\n\n## Usage on server side\n\nIn theory, this tool can be used on the server. But this will break the contract and, most likely,\nwill break all the GraphQL tooling you use. Use it on server-side only if you know what you do.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-kit%2Fgraphql-lodash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphql-kit%2Fgraphql-lodash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-kit%2Fgraphql-lodash/lists"}