{"_id":"@adamkl/graphql-weaver","_rev":"1-d7faaad9dd319636eb1081f1c8f40490","name":"@adamkl/graphql-weaver","description":"A tool to combine, link and transform GraphQL schemas","dist-tags":{"latest":"0.10.0"},"versions":{"0.10.0":{"name":"@adamkl/graphql-weaver","version":"0.10.0","description":"A tool to combine, link and transform GraphQL schemas","main":"dist/main.js","types":"./dist/main.d.ts","scripts":{"build":"rimraf dist && tsc && dependency-check ./package.json","start":"node graphql-proxy","test":"tsc --noEmit --skipLibCheck && node graphql-weaver-test"},"repository":{"type":"git","url":"git+https://github.com/aeb-labs/graphql-weaver.git"},"author":"","license":"MIT","devDependencies":{"@types/body-parser":"^1.16.3","@types/cors":"^2.8.1","@types/fs-extra":"^3.0.2","@types/graphql":"^0.10.0","@types/jasmine":"^2.5.52","@types/node":"^7.0.22","@types/node-fetch":"^1.6.7","body-parser":"^1.17.2","cors":"^2.8.3","express":"^4.15.3","fs-extra":"^3.0.1","graphql":"^0.10.0","graphql-server-express":"^1.1.0","jasmine":"^2.6.0","jasmine-promises":"^0.4.1","jasmine-spec-reporter":"^4.1.0","ts-node":"^3.0.4","typescript":"^2.4.2","jsondiffpatch":"^0.2.4","rimraf":"^2.6.1","dependency-check":"^2.9.1","graphql-server-core":"^1.1.0"},"dependencies":{"dataloader":"~1.3.0","node-fetch":"~1.7.0","trace-error":"~0.0.7"},"peerDependencies":{"@types/graphql":"~0.10.0","graphql":"~0.10.0"},"gitHead":"18a01af449a857ed3d19d3b63a87b413d7fd205b","bugs":{"url":"https://github.com/aeb-labs/graphql-weaver/issues"},"homepage":"https://github.com/aeb-labs/graphql-weaver#readme","_id":"@adamkl/graphql-weaver@0.10.0","_npmVersion":"5.3.0","_nodeVersion":"8.4.0","_npmUser":{"name":"adamkl","email":"adam@kreczko-lenner.com"},"dist":{"integrity":"sha512-T4RSlt5YQX2aGZ9OM5WRjH7vGqSb4wvdPpfnNd553oDVGS5tBMgiIgawbf6fZr7mHgLf3MF0ru6dxaz3BACbuw==","shasum":"0136b9b9f858598f59dbc1171bc35d08223ebe06","tarball":"https://registry.npmjs.org/@adamkl/graphql-weaver/-/graphql-weaver-0.10.0.tgz","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIEsuk2Uegr3zcCP/VzlE4lvP2PJrkNhQ/T4uBsWAyt0YAiEAqpDqldFDrQ+6xjjNCyAQBpGBK/MI+yNfSCAG4jKy1lc="}]},"maintainers":[{"name":"adamkl","email":"adam@kreczko-lenner.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/graphql-weaver-0.10.0.tgz_1507821561195_0.47425535204820335"}}},"readme":"# graphql-weaver\n\n[![npm version](https://badge.fury.io/js/graphql-weaver.svg)](https://npmjs.org/graphql-weaver) [![Build Status](https://travis-ci.org/AEB-labs/graphql-weaver.svg?branch=master)](https://travis-ci.org/AEB-labs/graphql-weaver)\n\nA tool to combine, link and transform GraphQL schemas\n\nUse graphql-weaver if you have multiple GraphQL servers and want to combine them into one API. Features like namespacing, links and custom transformation modules allow you to augment the API as you like.\n\n## How to use\n\n```bash\nnpm install --save graphql-weaver\n```\n\nBasic usage:\n\n```typescript\nconst schema: GraphQLSchema = await weaveSchemas({\n    endpoints: [{\n        namespace: 'model',\n        typePrefix: 'Model',\n        url: 'http://localhost:8080/graphql' // url to a GraphQL endpoint\n    }, {\n        namespace: 'local',\n        schema: new GraphQLSchema(/* ... */) // use schema instance directly\n    }]\n})\n```\n\nA *woven schema* is an executable GraphQL schema built from several *endpoints*. For each endpoint, you can either specify a URL to a GraphQL server, pass an executable GraphQL schema instance, or implement the [`GraphQLClient`](src/graphql-client/graphql-client.ts) interface yourself.\n\nIn its basic configuration, `weaveSchemas` merges the query, mutation and subscription fields of all endpoints. To avoid name collisions, you can specify the `namespace` and `typePrefix` properties like seen above. The `typePrefix` will be prepended to all types; `namespace` causes the fields of this endpoint to be wrapped in a field, to be queried via `{ model { aFieldOfModel } }`.\n\n### Links\n\nIn the spirit of GraphQL, this tool allows you to create links between objects of different endpoints. Suppose you have a music recommendation service and a music library service. You can make the whole properties of a song available in the recommendation API without the recommendation service knowing all song properties.\n\n```typescript\nconst schema: GraphQLSchema = await weaveSchemas({\n    endpoints: [{\n        namespace: 'library',\n        url: 'http://example.com/library/graphql'\n    }, {\n        namespace: 'recommendations',\n        url: 'http://example.com/recommendations/graphql',\n        fieldMetadata: {\n            'Recommendation.song': { // Field song in type Recommendation\n                link: {\n                    field: 'library.Song', // field Song in namespace library\n                    argument: 'id', // argument of library.Song\n                    batchMode: false,\n                }\n            }\n        }\n     }]\n});\n```\nThis assumes the library schema has a field `Song` which accepts a `id` argument, and the recommendations schema has a type `Recommendation` with a field `song` which contains the song id. Then, you can query the recommendations with all song information like this:\n\n```graphql\nquery {\n    recommendations {\n        myRecommendations {\n            recommendedAt\n            song {\n                id\n                artist\n                title\n                year\n            }\n        }\n    }\n}\n```\n\nIf there are many recommendations, this is ineficcient because all songs are queried independently.  If the library schema supports querying multiple songs at once, you can set `batchMode` to `true`. If the library schema may return the songs in a different order than the ids its get, you need to set `keyField` too.\n\n```typescript\nconst schema: GraphQLSchema = await weaveSchemas({\n    endpoints: [{\n        namespace: 'library',\n        url: 'http://example.com/library/graphql'\n    }, {\n        namespace: 'recommendations',\n        url: 'http://example.com/recommendations/graphql',\n        fieldMetadata: {\n            'Recommendation.song': {\n                link: {\n                    field: 'library.allSongs',\n                    argument: 'filter.ids', // allSongs has an argument filter with an array field ids\n                    batchMode: true,\n                    keyField: 'id' // the name of a field in Song type that contains the id\n                }\n            }\n        }\n     }]\n});\n```\n\n### Joins\n\nWhat if you want to sort the recommendations by the song age, or filter by artist? The recommendation service currently does not know about these fields, so it does not offer an API to sort or order by any of them. Using graphql-weaver, this problem is easily solved:\n\n```typescript\nconst schema: GraphQLSchema = await weaveSchemas({\n    endpoints: [{\n        namespace: 'library',\n        url: 'http://example.com/library/graphql'\n    }, {\n        namespace: 'recommendations',\n        url: 'http://example.com/recommendations/graphql',\n        fieldMetadata: {\n            'Recommendation.song': {\n                link: {\n                    field: 'library.allSongs',\n                    argument: 'filter.ids',\n                    batchMode: true, // is now required\n                    keyField: 'id' // this one too\n                }\n            },\n            'Query.myRecommendations': { // Field myRecommendations on type Query\n                join: {\n                    linkField: 'song', // The field name song in the type Recommendation\n                }\n            }\n        }\n     }]\n});\n```\n\nThis assumes that the library service offers a way to filter and sort songs via the `orderBy` and `filter` arguments. Using it is simple:\n\n```graphql\nquery {\n    recommendations {\n        myRecommendations(filter: { song: { artist: \"Ed Sheeran\" } }, orderBy: song_year_DESC) {\n            recommendedAt\n            song {\n                id\n                artist\n                title\n                year\n            }\n        }\n    }\n}\n```\n\nA note on efficiency: The list of recommendations should be relatively small (not more than a few hundred), as all recommendations need to be fetched so that their ids can be sent to the library for filtering and sorting.\n\n### Custom Transformations\n\nAll four presented features (namespaces, type prefixes, links and joins) are implemented as independent modules. If you need something else, you can just write your own module:\n\n```typescript\nclass MyModule implements PipelineModule {\n    transformExtendedSchema(schema: ExtendedSchema): ExtendedSchema {\n        // do something with the schema\n        return schema;\n    }\n    transformQuery(query: Query): Query {\n        // do something with the query\n        return query;\n    }\n}\n\nconst schema: GraphQLSchema = weaveSchemas({\n    endpoints: [{\n        namespace: 'library',\n        url: 'http://example.com/library/graphql',\n        \n    }],\n    pipelineConfig: {\n        transformPreMergePipeline(modules: PipelineModule[], context: PreMergeModuleContext): PipelineModule[] {\n            // These modules are executed for each endpoint\n            return [\n                ...modules,\n                new MyModule()\n            ]\n        },\n        transformPostMergePipeline(modules: PipelineModule[], context: PostMergeModuleContext): PipelineModule[] {\n            // These modules are executed once for the merged schema\n            return [\n                ...modules,\n                new MyModule()\n            ]\n        }\n    }\n});\n```\n\nFor a simple module, see [`TypePrefixModule`](src/pipeline/type-prefixes.ts). The section *Architecture* below gives an overview over the pipeline architecture.\n\nTo simplify modifications to a schema, graphql-weaver ships [`transformSchema`](src/graphql/schema-transformer.ts) (and [`transformExtendedSchema`](src/extended-schema/extended-schema-transformer.ts)). You can change types and fields as you like with a simple function:\n\n```typescript\nconst transformedSchema = transformSchema(originalSchema, {\n    transformField(field: GraphQLNamedFieldConfig<any, any>, context) {\n        // Rename a field in a type\n        if (context.oldOuterType.name == 'MyType') {\n            return {\n                ...field,\n                name: field.name + 'ButCooler'\n            }\n        }\n        return field;\n    },\n\n    transformObjectType(type: GraphQLObjectTypeConfig<any, any>) {\n        if (type.name == 'MyType') {\n            return {\n                ...type,\n                name: 'MyCoolType'\n            };\n        }\n        return type;\n    },\n\n    transformFields(fields: GraphQLFieldConfigMap<any, any>, context) {\n        // You can even copy types on the fly and transform the copies\n        const type2 = context.copyType(context.oldOuterType, {\n            transformObjectType(typeConfig: GraphQLObjectTypeConfig<any, any>) {\n                return {\n                    ...typeConfig,\n                    name: typeConfig.name + '2',\n                    resolve: (source: any) => source\n                };\n            }\n        });\n\n        // This just adds a reflexive field \"self\" to all types, but its type does not have\n        // the \"self\" field (because it is a copy from the original type, see above)\n        // it also won't have the \"cool\" rename applied because the top-level transformers are not applied\n        return {\n            ...fields,\n            self: {\n                type: type2\n            }\n        }\n    }\n});\n```\n\n[This test case](spec/graphql/schema-transformer.spec.ts) demonstrates that and how it works.\n\n## Contributing\n\nAfter cloning the repository, run\n\n```bash\nnpm install\nnpm start\n```\n\nTo run the test suite, run\n\n```bash\nnpm test\n```\n\nTo debug/run the application (or tests) in WebStorm, right-click on `graphql-weaver.js` (or `graphql-weaver-tests.js`, respectively) and choose *Debug*/*Run*.\n\n### Release workflow\n\n* For **normal development**, create a branch from master, commit and create a merge request to master. \n* To **fix a bug in a previous release**, find the *release-* branch for the corresponding version, increase the *patch* level in `package.json` and push the changes. Once the tests pass, manually trigger the *deploy* stage in Gitlab. You can also release a *-rc.1* version before the actual release for prior testing in dependent modules.\n* To prepare a **new feature release** (currently, this means a new minor version), create a `release-0.x` branch from master. Set the version to `0.x-rc.1`, push and manually trigger the *deploy* stage in Gitlab. Test the changes in dependent modules. Once everything is ok, change the version to `0.x` and deploy again. Finally, merge the release branch into *master*. Do not delete the release branch as it is used for hotfixes.\n\n## Architecture\n\ngraphql-weaver takes a set of GraphQL endpoints, transforms them through pipelines, merges them, transforms the merged schema again and exposes that as its *woven schema*.\n\n```\n           +------+  +------+  +------+\nEndpoints  |Schema|  |Schema|  |Schema|\n           +------+  +------+  +------+\n\n           +------+  +------+  +------+\n            X    X    X    X    X    X\nPipelines    X  X      X  X      X  X\n              XX        XX        XX\n\n               +                  +\nMerge           +----------------+\n\n                     +------+\n                      X    X\nPipeline               X  X\n                        XX\n\n                     +------+\nServer               |Schema|\n                     +------+\n\n```\n\nThe *merge* in the middle simply merges all the fields of the Query/Mutation types. All the other features, like type prefixing, field namespacing, even resolvers, is implemented by pipeline modules.\n\nYou'll find the list of modules in `src/pipeline/pipeline.ts`. For a description of each module, please refer to the TypeDoc comments.\n\n## Module structure\n\n* `graphql` - general utilities for working with GraphQL schemas and queries\n* `extended-schema` - an implementation of storing and exposing metadata on fields, the concept being [discussed on GitHub](https://github.com/facebook/graphql/issues/300)\n* `graphql-client` - GraphQL client library, with local and http implementations\n* `pipeline` - the core, being framework and modules for graphql-weaver's features\n* `config` - configuration parameter types for `weaveSchemas`\n* `utils` - utilities unrelated to GraphQL\n* `typings` - typings for thirdparty modules\n","maintainers":[{"name":"adamkl","email":"adam@kreczko-lenner.com"}],"time":{"modified":"2022-04-04T11:25:28.542Z","created":"2017-10-12T15:19:22.412Z","0.10.0":"2017-10-12T15:19:22.412Z"},"homepage":"https://github.com/aeb-labs/graphql-weaver#readme","repository":{"type":"git","url":"git+https://github.com/aeb-labs/graphql-weaver.git"},"bugs":{"url":"https://github.com/aeb-labs/graphql-weaver/issues"},"license":"MIT","readmeFilename":"README.md"}