microsoft / graphitation

GraphQL tooling & runtime support needed for MS Teams and beyond

Graphitation

GraphQL tooling & runtime support needed for MS Teams and beyond

Packages

• @graphitation/apollo-mock-client: An Apollo Client that allows mocking of payloads in response to operations, rather than having to provide them all upfront.
• @graphitation/apollo-react-relay-duct-tape: A compatibility wrapper that provides the react-relay API on top of Apollo Client.
• @graphitation/graphitation-cli: binaries for the codegen and extractors.
• @graphitation/graphql-codegen: generates resolver types and models.
• @graphitation/graphql-codegen-supermassive-schema-extraction-plugin: GraphQL codegen supermassive schema extraction.
• @graphitation/graphql-js-operation-payload-generator: Generates a payload for a given GraphQL operation expressed in graphql-js AST and a GraphQL Schema.
• @graphitation/graphql-js-tag: A simple graphql-js AST based graphql tagged template function.
• @graphitation/graphql-eslint-rules: Graphql eslint rules
• @graphitation/rempl-apollo-devtools: Rempl apollo devtools
• @graphitation/supermassive: Supermassive is a lightweight schema-less GraphQL executor and query build-time compiler
• @graphitation/supermassive-extractors: extracts implicit resolvers
• @graphitation/apollo-react-relay-duct-tape-compiler: The build tools to cater to @graphitation/apollo-react-relay-duct-tape's needs.

Contributing

Please see CONTRIBUTING.md for development instructions.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

graphitation's Issues

[ARRDT] Add support for imperative list updater functions

If #85 is not enough

[supermassive] Deal with conditional resolving AOT

If we do AOT compilation of some sort, we can do some of the work that resolvers sometimes do at runtime where they reflect on the request AST to determine what fields are selected and if all data is already available or needs to be fetched from a [remote] I/O bound source.

A contrived example is when only an id field of an object is selected, in which case we wouldn't need to fetch the full user object:

type User {
  id: ID!
  name: String!
}

type Query {
  user(id: ID!): User
}

query {
  user(id: 42) {
    id
  }
}

function userResolver(_source, args, context, info) {
  if (onlyNeedsIdField(info)) {
    return { id: args.id }
  } else {
    return getUser(args.id)
  }
}

[AARDT] TODOs for 1JS

With highest priority first:

• Fix bug which breaks @connection with filters when duct-tape tries to read from the cache: #300
• Apply fix from 1JS 352fbc5ec42a5705027409dc7c7ab2480e664ae3
• Apply fix from 1JS 6f6b783e03820492d03dd7cbaad4bb3baac50982
• Make duct-tape cli/compiler package which:
  * wraps relay-compiler
  * wraps the TS plugin
  * has the graphitisation plugin bits
  * exposes a duct-tape cli bin
  * Move createImportDocumentsTransform to cli/compiler package
• Come to a decision about overloading the Query.node field with a field-policy
• Figure out way to not need to patch @apollo/client.
• Deprecate fragment interpolation:
  * Throw a warning
  * Don't need it otherwise

Tasks

Beta Give feedback

1. Add doc warning that without emitting documents you need to have stable inlined docs

supermassive v3 Roadmap

• @defer / @stream
  • @defer and @stream support
  • unify subscription into execution
• move implicit resolvers into document
• change document format to use SDL in directive instead of inline nodes

[ARRDT] Throw error from useLazyLoadQuery instead of returning

This would make the API compatibly exactly with react-relay. Will an error boundary suffice?

[ARRDT] look into optimism thrashing

According to @vladar any read from the cache adds entries to optimism. We need to verify this and try to avoid it, perhaps as described here apollographql/apollo-client#9306 (comment)

[ARRDT] Re-export graphql tagged template function

We need to allow the user to write imports like the following, so they remain portable with react-relay

import {
  graphql,
  useLazyLoadQuery,
} from "@graphitation/apollo-react-relay-duct-tape";

Import vision doc from TMP

NOTE: This needs updating based on latest packages and new thinking.

nova-facade-react-graphql

This package aims to provide a React component tree with the means to retrieve data from an abstract GraphQL client, allowing the components to focus on the generic UI needs rather than host specific data resolving.

The following details are not stricly related to just GraphQL in the context of Nova, but until this effort outgrows the current Nova goals, this seems as good a place as any to give this overview.

Flavours:

We want high value components to be shareable with a wide range of host applications, however not all host applications are equal in the data layers—let alone in their offering of a GraphQL layer. Similarly, not all high value components have the same needs of a GraphQL client/layer. Thus there's a need to provide a matrix of runtime/build-time flavours.

Runtime flavours:

1. At a baseline it will provide an unopiniated way to fetch a fat query operation, leaving distribution of the data among the component tree up to the component implementors.

2. However, it will also come with an opinionated way of 'fragmentizing' data requirements, such that a component can express its own data needs using a co-located GraphQL fragment and remain fully isolated from its parents' and children's needs, thus aiming to improve maintenanability of a large component tree and making it easier to avoid over/under fetching of data.

   For more information on this concept, see for example this article.

   Note that this is nothing more than a way to organize code and requirements; at runtime there is no promise that the implementation needs to do anything more than pass through the data from the parent.

3. With #2 in place, this fragmentized approach will allow us to optimize generic concerns that a larger application has, such as avoiding unnecessary re-renders while staying in-sync with the data it represents, as it exists in a normalized store.

   For more information on this topic, see for example this article.

Build-time flavours:

1. A high value component targeting any of the runtime flavours can use the provided high-performance CLI tool (nova-facade-graphql-compiler) to codegen TypeScript typings for its GraphQL query operations. However, the opinionated runtime flavours are required to do so due to the specialized manner in which the typings are emitted to enforce data-masking.

2. A host application that can statically know about all operations that can be performed could compile away any GraphQL schema request execution. Thus entirely doing away with parsing and validating of documents, finding the set of resolvers needed to resolve the request, etc.

3. A high value component tree that has no normalized store needs could be compiled in such a way that no little to no overhead exists at runtime when distributing resolved data along the component tree.

4. Likewise, a high value component tree that does have normalized store needs could be compiled in a way that does come with runtime overhead, but would aim to reduce the need for performance optimizations work in every component.

Work items for a first naive version to allow building of the AppBar

• Provide a means to perform a lazy query operation, meaning to initiate a query during rendering of a component tree. (Runtime flavour #1.)
• Provide a way to fragmentize React components, meaning a component's data requirements can be co-located with the component, rather than living at the root of the component tree. (Runtime flavour #2.)
• Provide a way to codegen TypeScript typings for operation/fragment documents with opaque data-masking for fragment references.
• Provide a way for host to inject dependencies.
• Provide a way to easily (unit) test a fragmentized component tree.
• Possibly provide a babel transform that can inline the graphql tag AST at build time. The existing babel-plugin-graphql-tag transform relies on the graphql-tag package, which is normally known to add AST of referenced fragments, rather than referring to the existing AST objects. We don't want that and are avoiding it currently in the uncompiled use of the graphql tag.
• Possibly provide a simple built-in way to check fragment data to avoid unnecessary re-renders.

Work items for the longer term

• Provide a way to statically compile away the need for an executable GraphQL schema. Likely leveraging the work the Relay team has done to offer a Rust based framework for GraphQL manipulations. (Build-time flavour #2.)
• Provide a way to statically compile away runtime overhead for components that do not have normalized store needs. (Build-time flavour #3.)
• Provide an optimized runtime flavour that provides features requiring a normalized store. (Runtime flavour #3 & build-time flavour #4.)

[ARRDT] Import hooks docs

• Setup docusaurus
• Import and modify docs
• Remove comment docs from hooks and link to public docs instead
• Upstream doc changes

Monorepo tasks

• Add a clean task that removes build artefacts from all packages
• Why does the example app need built versions of the packages?
• Can we reconfigure things such that I can just run jest from any package without passing the path to the config file?

Duct tape compiler doesn't work with connections and complex connection args

Check PR link for repro: #402

In this case after adding complex argument to connection, if defaultValue is specified for that argument, running yarn duct-tape-compiler in apollo-watch-fragments fails with

➜  apollo-watch-fragments (main) yarn duct-tape-compiler
yarn run v1.22.15
$ duct-tape-compiler --schema ./data/schema.graphql --src ./src --emitQueryDebugComments

Writing ts
DeprecationWarning: 'createTypeAliasDeclaration' has been deprecated since v4.8.0. Decorators are no longer supported for this function. Callers should switch to an overload that does not accept a 'dec
orators' parameter.
DeprecationWarning: 'createImportDeclaration' has been deprecated since v4.8.0. Decorators are no longer supported for this function. Callers should switch to an overload that does not accept a 'decora
tors' parameter.
ERROR:
Error writing modules:
TypeError: value.hasOwnProperty is not a function
    at collectMetadata (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:48:19)
    at collectMetadata (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:49:29)
    at collectMetadata (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:49:29)
    at collectMetadata (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:49:29)
    at collectMetadata (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:49:29)
    at dedupeJSONStringify (C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\util\dedupeJSONStringify.js:22:3)
    at printExports (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\src\formatModule.ts:152:143)
    at C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\src\formatModule.ts:118:18
    at C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\codegen\writeRelayGeneratedFile.js:153:22
    at Generator.next (<anonymous>)

Here is where we add the defaultValue:

[ARRDT] Add preloading APIs

E.g. usePreloadedQuery

[ARRDT] Make node field policy work for ids without typename prefix

When node ids are truly unique, Apollo Cache can be configured to not prefix typename. In this case, we need to adjust the cache redirect from the node field policy, which means we can do less work as we don't need to infer the typename from the fragment.

[ARRDT] Add support for @relay(plural: true)

https://relay.dev/docs/api-reference/graphql-and-directives/#relayplural-boolean

Duct tape compiler not working with Typescript 5

I am trying to integrate the new compiler in 1JS. During that process I stumbled upon error when trying to run the compiler. I was able to reproduce this issue inside graphitation repo by basically bumping TS to version 5 (which is what 1JS is using). The error is during generation is:

➜  apollo-watch-fragments (main) yarn duct-tape-compiler
yarn run v1.22.15
$ duct-tape-compiler --schema ./data/schema.graphql --src ./src --emitQueryDebugComments

Writing ts
ERROR:
Error writing modules:
Error: Debug Failure. Unhandled SyntaxKind: Unknown.
    at pipelineEmitWithHintWorker (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111514:13)  
    at pipelineEmitWithHint (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111058:9)
    at pipelineEmitWithComments (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:114842:7)     
    at pipelineEmit (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111007:7)
    at emit (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:110975:7)
    at emitTypeAliasDeclaration (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:112937:7)     
    at pipelineEmitWithHintWorker (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111244:20)  
    at pipelineEmitWithHint (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111058:9)
    at pipelineEmitWithComments (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:114842:7)     
    at pipelineEmit (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\node_modules\typescript\lib\typescript.js:111007:7)
error Command failed with exit code 100.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Could we get compiler working with TS 5?

[payload-generator] Failing to generate for merged selection set

When there are two fragments on the same type, the selection sets should be merged. This isn't happening. It might also be related to the object being inside a list.

Needs a failing test case.

/cc @sjwilczynski

[ARRDT] Dispose any refetch query on unmount

Previously my understanding of the upstream code was that this was only done for pagination queries.

It's being done here https://github.com/facebook/relay/blob/a3c0c0c52976d06a0a48467b6e084aa49ce69916/packages/react-relay/relay-hooks/useQueryLoader.js#L125-L130

Remove tslint-ignore comment from relay-compiler artifacts

[loader] Improve source-map handling

See mozilla/source-map#216 for details on resolution

[AARDT] Re-use metadata relay-compiler already extracts

Don't re-invent the wheel, check the IR metadata that relay-compiler normally emits to see if it has stuff we re-implemented.

Setup monorepo

This repo will output several JS (TypeScript) packages. In the future we'll also output some Rust packages, but the first focus is JS.

@kenotron has shown interest in bootstrapping the infrastructure for that 🎉

[ARRDT] Add support for declarative list updater directives

@deleteNode, @appendEdge etc

[ARRDT] Add support fragment arguments directives

• https://relay.dev/docs/api-reference/graphql-and-directives/#arguments
• https://relay.dev/docs/api-reference/graphql-and-directives/#argumentdefinitions

[ARRDT] Support the relay eslint rules

https://github.com/relayjs/eslint-plugin-relay

New webpack loader is not working with babel-loader

I created a branch with repro at https://github.com/sjwilczynski/graphitation/tree/stwilczy/NotWorkingBabelLoader. Now I receive there same error as in 1JS when using babel-loader instead of ts-loader:

apollo-watch-fragments (main) yarn serve
yarn run v1.22.15
$ webpack serve
<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:8080/
<i> [webpack-dev-server] On Your Network (IPv4): http://192.168.1.38:8080/
<i> [webpack-dev-server] On Your Network (IPv6): http://[fe80::c18f:6677:eac0:c7ed]:8080/
<i> [webpack-dev-server] Content not from webpack is served from './public' directory
1 asset
462 modules

ERROR in ./src/App.tsx
Module build failed (from ../../node_modules/babel-loader/lib/index.js):
Error: .inputSourceMap must be a boolean, object, or undefined

webpack 5.81.0 compiled with 1 error in 7366 ms

[ARRDT] Document important differences with relay

• Only fragments on a Node type will create a new observable

Packages missing `types` conditional in package.json `exports` field.

The packages here has main, types, module and exports field. The exports field can contain the information from the other fields.

When using TyperScript with the moduleResolution: "bundler" setting, TypeScript will verify that all imports has an entry in the exports map, if the export map exists, and this includes the types entry.

In this repo the exports field doesn't add the types conditional, and errors with the following message:

packages/nova-dev-app-providers/src/DevAppProvider.tsx:5:26 - error TS7016: Could not find a declaration file for module '@graphitation/apollo-react-relay-duct-tape'. 'node_modules/@graphitation/apollo-react-relay-duct-tape/lib/index.mjs' implicitly has an 'any' type.
  There are types at 'node_modules/@graphitation/apollo-react-relay-duct-tape/lib/index.d.ts', but this result could not be resolved when respecting package.json "exports". The '@graphitation/apollo-react-relay-duct-tape' library may need to update its package.json or typings.

5 import * as graphQL from "@graphitation/apollo-react-relay-duct-tape";
                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1 error

The fix would be to add the types conditional for each entry in the exports map.

[ARRDT] Record variables with default values in stored request variables

[MockPayloadGenerator] Try a direct port from upstream

Current version was a cleanroom implementation, but I think that it makes sense by now to just try a direct port instead to achieve full support/parity.

WIP here https://github.com/microsoft/graphitation/tree/alloy/port-upstream-mock-payload-generator

Compiler fails if there are two fragments in a single file

On https://github.com/sjwilczynski/graphitation/tree/user/stwilczy/fragmentRepro I added another fragment to two components in apollo-watch-fragments example. They mimic setup we have in 1JS, where we very often have more than one fragment (view data and domain data, and sometimes even another domain data one). In such case even if the fragment is very simple compiler fails with:

➜  apollo-watch-fragments (user/stwilczy/fragmentRepro) yarn duct-tape-compiler
yarn run v1.22.15
$ duct-tape-compiler --schema ./data/schema.graphql --src ./src --emitQueryDebugComments

Writing ts
DeprecationWarning: 'createTypeAliasDeclaration' has been deprecated since v4.8.0. Decorators are no longer supported for this function. Callers should switch to an 
overload that does not accept a 'decorators' parameter.
DeprecationWarning: 'createImportDeclaration' has been deprecated since v4.8.0. Decorators are no longer supported for this function. Callers should switch to an ove
rload that does not accept a 'decorators' parameter.
ERROR:
Error writing modules:
Invariant Violation: Expected to find a @refetchable directive on TodoList_viewDataFragment
    at invariant (C:\Users\stwilczy\Repos\graphitation\node_modules\invariant\invariant.js:40:15)
    at printWatchNodeQueryReExport (C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\src\formatModule.ts:118:12)
    at C:\Users\stwilczy\Repos\graphitation\packages\apollo-react-relay-duct-tape-compiler\src\formatModule.ts:98:33
    at C:\Users\stwilczy\Repos\graphitation\node_modules\relay-compiler\lib\codegen\writeRelayGeneratedFile.js:153:22
    at Generator.next (<anonymous>)
    at asyncGeneratorStep (C:\Users\stwilczy\Repos\graphitation\node_modules\@babel\runtime\helpers\asyncToGenerator.js:3:24)
    at _next (C:\Users\stwilczy\Repos\graphitation\node_modules\@babel\runtime\helpers\asyncToGenerator.js:25:9)
    at C:\Users\stwilczy\Repos\graphitation\node_modules\@babel\runtime\helpers\asyncToGenerator.js:32:7
    at new Promise (<anonymous>)
    at C:\Users\stwilczy\Repos\graphitation\node_modules\@babel\runtime\helpers\asyncToGenerator.js:21:12
error Command failed with exit code 100.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

[ARRDT] Support Suspense

I don't recall why I didn't add Suspense support immediately, but I feel like that should be revisited as the changes needed seem minimal.

[ARRDT] Port ts-loader transform to native webpack plugin.

It would be ideal if our transformer was webpack loader agnostic and not add extra parsing/printing overhead.

For instance, TMP wants to use esbuild-loader instead of ts-loader (and esbuild doesn't have any way to hook in a transformer).

Example plugin that hooks into webpack's native AST is https://github.com/webpack/webpack/blob/fde018300aa52262c384e937c408d5dd97d62951/lib/UseStrictPlugin.js

[graphql-codegen-typename-plugin] Fix casing of symbols in all cases

Use graphql-codegen's own way to track the naming variants. Currently our enums names are not being renamed in terms of casing and it's not clear how graphql-codegen exactly keeps track of that itself.

[website] Move docs into respective packages

Docs for package X should simply exist at ./packages/X/docs so a source reader can easily find them.

See

• facebook/docusaurus#852 (comment)
• facebook/docusaurus#4085

[payload-generator] Take schema types from graphql-codegen for custom mocks

Something like this should be checkable:

    MockPayloadGenerator.generate<SchemaTypes>(operation, {
      Person: () => ({
        defaultName: {
          displayName: "Eloy Durán",
        },
      }),
      ChatTextMessage: () => ({
        arrivalTime: new Date().toISOString(),
        content: "Look mom, I'm in a storybook!",
      }),
      ChatMessageConnection: () => ({
        edges: new Array(40).fill(undefined),
        pageInfo: {
          hasNextPage: true,
        },
      }),
    })

[ARRDT] Known excessive render update

These are known and will NOT be fixed, as they would require substantial complexity changes and are automatically fixed by virtue of updating to React v18 (when that goes stable).

usePaginationFragment

The new variables and the loading status changes are already batched, but the new data coming from the useFragment hook comes in a separate update.

(NOTE: I did get rid of the needless addition of id: undefined, but it does not cause any additional renders, just debugging noise.)

React v17

React v18