Allow graphql dataProviders to leverage the introspection results

Author: djhi

packages/ra-data-graphql/README.md

@@ -199,6 +199,116 @@ The `./schema` file is a `schema.json` in `./src` retrieved with [get-graphql-sc
 
 > Note: Importing the `schema.json` file will significantly increase the bundle size.
 
+## Leveraging Introspection In Custom Methods
+
+If you need to build custom methods based on the introspection, you can leverage the `getIntrospection` method of the `dataProvider`. It returns an object with the following format:
+
+```js
+{
+    // The original schema as returned by the Apollo client
+    schema: {},
+    // An array of object describing the types that are compatible with react-admin resources
+    // and the methods they support. Note that not all methods may be supported.
+    resources: [
+        {
+            type: { name: 'name-of-the-type' }, // e.g. Post
+            GET_LIST: { name: 'name-of-the-query' }, // e.g. allPosts
+            GET_MANY: { name: 'name-of-the-query' }, // e.g. allPosts
+            GET_MANY_REFERENCE: { name: 'name-of-the-query' }, // e.g. allPosts
+            GET_ONE: { name: 'name-of-the-query' }, // e.g. Post
+            CREATE: { name: 'name-of-the-query' }, // e.g. createPost
+            UPDATE: { name: 'name-of-the-query' }, // e.g. updatePost
+            DELETE: { name: 'name-of-the-query' }, // e.g. deletePost
+        },
+    ],
+}
+```
+
+This is useful if you need to support custom dataProvider methods such as those needed for ['@react-admin/ra-realtime'](https://react-admin-ee.marmelab.com/documentation/ra-realtime#dataprovider-requirements):
+
+```tsx
+import { Identifier, GET_LIST, GET_ONE } from 'ra-core';
+import { RealTimeDataProvider } from '@react-admin/ra-realtime';
+import { IntrospectedResource } from 'ra-data-graphql';
+
+const subscriptions: {
+    topic: string;
+    subscription: any;
+    subscriptionCallback: any;
+}[];
+
+const baseDataProvider = buildDataProvider(/* */);
+
+export const dataProvider: RealTimeDataProvider = {
+    ...baseDataProvider,
+    subscribe: async (topic, subscriptionCallback) => {
+        const raRealTimeTopic = topic.startsWith('resource/') ? topic.split('/') : null;
+        if (!raRealTimeTopic) throw new Error(`Invalid ra-realtime topic ${topic}`);
+    
+        // Two possible topic patterns
+        //    1. resource/${resource}
+        //    2. resource/${resource}/${id}
+        const [, resourceName, id] = raRealTimeTopic;
+        const introspectionResults = await baseDataProvider.getIntrospection();
+        const resourceIntrospection = introspectionResults.resources.find(
+            resource => resource.type.name === resourceName
+        );
+        if (!resourceIntrospection) throw new Error(`Invalid resource ${resourceName}`);
+
+        const { query, queryName, variables } = buildQuery({ id, resource, resourceIntrospection });
+        const subscription = dataProvider.client
+            .subscribe({ query, variables })
+            .subscribe(data =>
+                subscriptionCallback(data.data[queryName].event)
+            );
+
+        subscriptions.push({
+            topic,
+            subscription,
+            subscriptionCallback,
+        });
+
+        return Promise.resolve({ data: null });
+    },
+    unsubscribe: async (topic: string, subscriptionCallback: any) => {
+        subscriptions = subscriptions.filter(
+            subscription =>
+                subscription.topic !== topic ||
+                subscription.subscriptionCallback !== subscriptionCallback
+        );
+        return Promise.resolve({ data: null });
+    },
+}
+
+const buildQuery = (
+    {
+        id,
+        resource,
+        resourceIntrospection
+    }: {
+        id: Identifier | undefined;
+        resource: string;
+        resourceIntrospection: IntrospectedResource
+    }
+) => {
+    if (!id) {
+        if (!resourceIntrospection[GET_LIST]) throw new Error(`Resource ${resource} does not support the getList method`);
+        return {
+            queryName: resourceIntrospection[GET_LIST],
+            query: gql`subscription ${queryName} { ${queryName}{ topic event } }`,
+            variables: {},
+        }
+    }
+
+    if (!resourceIntrospection[GET_ONE]) throw new Error(`Resource ${resource} does not support the getOne method`);
+    return {
+        queryName: resourceIntrospection[GET_LIST],
+        query: gql`subscription ${queryName}($id: ID!) { ${queryName}(id: $id){ topic event } }`,
+        variables: { id },
+    }
+}
+```
+
 ## Troubleshooting
 
 ## When I create or edit a resource, the list or edit page does not refresh its data

packages/ra-data-graphql/src/index.test.ts

@@ -49,4 +49,66 @@ describe('GraphQL data provider', () => {
             });
         });
     });
+    describe('getIntrospection', () => {
+        it('returns introspection result', async () => {
+            const schema = {
+                queryType: { name: 'Query' },
+                mutationType: { name: 'Mutation' },
+                types: [
+                    {
+                        name: 'Query',
+                        fields: [{ name: 'allPosts' }, { name: 'Post' }],
+                    },
+                    {
+                        name: 'Mutation',
+                        fields: [
+                            { name: 'createPost' },
+                            { name: 'updatePost' },
+                            { name: 'deletePost' },
+                        ],
+                    },
+                    { name: 'Post' },
+                ],
+            };
+            const client = {
+                query: jest.fn(() =>
+                    Promise.resolve({
+                        data: {
+                            __schema: schema,
+                        },
+                    })
+                ),
+            };
+
+            const dataProvider = buildDataProvider({
+                client: client as unknown as ApolloClient<unknown>,
+                buildQuery: () => () => undefined,
+            });
+
+            const introspection = await dataProvider.getIntrospection();
+            expect(introspection).toEqual({
+                queries: [
+                    { name: 'allPosts' },
+                    { name: 'Post' },
+                    { name: 'createPost' },
+                    { name: 'updatePost' },
+                    { name: 'deletePost' },
+                ],
+                types: [{ name: 'Post' }],
+                resources: [
+                    {
+                        type: { name: 'Post' },
+                        GET_LIST: { name: 'allPosts' },
+                        GET_MANY: { name: 'allPosts' },
+                        GET_MANY_REFERENCE: { name: 'allPosts' },
+                        GET_ONE: { name: 'Post' },
+                        CREATE: { name: 'createPost' },
+                        UPDATE: { name: 'updatePost' },
+                        DELETE: { name: 'deletePost' },
+                    },
+                ],
+                schema,
+            });
+        });
+    });
 });

packages/ra-data-graphql/src/index.ts

@@ -131,7 +131,7 @@ export type Options = {
     watchQuery?: GetWatchQueryOptions;
 };
 
-const buildGraphQLProvider = (options: Options): DataProvider => {
+const buildGraphQLProvider = (options: Options): GraphqlDataProvider => {
     const {
         client: clientObject,
         clientOptions,
@@ -224,7 +224,7 @@ const buildGraphQLProvider = (options: Options): DataProvider => {
         );
     };
 
-    const raDataProvider: DataProvider = {
+    const raDataProvider: GraphqlDataProvider = {
         create: (resource, params) => callApollo(CREATE, resource, params),
         delete: (resource, params) => callApollo(DELETE, resource, params),
         deleteMany: (resource, params) =>
@@ -237,6 +237,19 @@ const buildGraphQLProvider = (options: Options): DataProvider => {
         update: (resource, params) => callApollo(UPDATE, resource, params),
         updateMany: (resource, params) =>
             callApollo(UPDATE_MANY, resource, params),
+        getIntrospection: () => {
+            if (introspection) {
+                if (!introspectionResultsPromise) {
+                    introspectionResultsPromise = resolveIntrospection(
+                        client,
+                        introspection
+                    );
+                }
+
+                return introspectionResultsPromise;
+            }
+        },
+        client,
     };
 
     return raDataProvider;
@@ -261,4 +274,9 @@ const getQueryOperation = query => {
     throw new Error('Unable to determine the query operation');
 };
 
+export type GetIntrospection = () => Promise<IntrospectionResult>;
+export type GraphqlDataProvider = DataProvider & {
+    getIntrospection: GetIntrospection;
+};
+
 export default buildGraphQLProvider;