Export createCatalogLoader function

.changeset/polite-turkeys-happen.md

@@ -0,0 +1,6 @@
+---
+'@frontside/backstage-plugin-graphql-backend-module-catalog': patch
+'@frontside/backstage-plugin-graphql-backend': patch
+---
+
+Export `createCatalogLoader` function

plugins/graphql-backend-module-catalog/README.md

@@ -31,10 +31,24 @@ This package provides two GraphQL modules:
 ### Backstage Plugins
 
 For the [Backstage plugin system](https://backstage.io/docs/plugins/backend-plugin),
-you can learn how to add GraphQL modules by checking out [GraphQL Modules](../graphql-backend/README.md#graphql-modules)
-section in `@frontside/backstage-plugin-graphql-backend` package.
+you have to pass `Catalog` or `Relation` GraphQL module to the `modules` option and
+create catalog `DataLoader`:
 
-This package exports `Catalog` and `Relation` modules
+```ts
+import { createRouter } from '@frontside/backstage-plugin-graphql-backend';
+import { Catalog } from '@frontside/backstage-plugin-graphql-backend-module-catalog';
+
+// packages/backend/src/plugins/graphql.ts
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    logger: env.logger,
+    modules: [Catalog],
+    loaders: { ...createCatalogLoader(env.catalogClient) },
+  });
+}
+```
 
 ### Experimental Backend System
 
@@ -108,19 +122,9 @@ type System {
 }
 ```
 
-## Catalog Data Loader (Advanced)
-
-In most use cases, you will not need to create a Catalog `dataloader` by
-hand. However, when writing [custom data loaders for accessing 3rd
-party sources][custom-loader] or [rolling your own GraphQL Server
-implementation][roll-your-own] you will need to provide the Catalog
-loader yourself. This plugin provides the `createLoader` helper to do
-just that.
-
 [graphql-backend]: ../graphql-backend/README.md
 [graphql-modules]: https://the-guild.dev/graphql/modules
 [relay]: https://relay.dev/docs/guides/graphql-server-specification
 [custom-loader]: ../graphql-backend/README.md#custom-data-loaders-advanced
-[roll-your-own]: ../graphql-common/README.md#getting-started
 [catalog]: https://backstage.io/docs/features/software-catalog/software-catalog-overview
-[directives-api]: ../graphql-common/README.md#directives-api
+[directives-api]: https://github.com/thefrontside/HydraphQL/blob/main/README.md#directives-api

plugins/graphql-backend-module-catalog/src/catalogModule.ts

@@ -4,8 +4,7 @@ import {
   graphqlLoadersExtensionPoint,
   graphqlModulesExtensionPoint,
 } from '@frontside/backstage-plugin-graphql-backend';
-import { createEntitiesLoadFn } from './entitiesLoadFn';
-import { CATALOG_SOURCE } from './constants';
+import { createCatalogLoader } from './entitiesLoadFn';
 import { Catalog } from './catalog/catalog';
 
 /** @public */
@@ -21,7 +20,7 @@ export const graphqlModuleCatalog = createBackendModule({
       },
       async init({ catalog, modules, loaders }) {
         modules.addModules([Catalog]);
-        loaders.addLoaders({ [CATALOG_SOURCE]: createEntitiesLoadFn(catalog) });
+        loaders.addLoaders(createCatalogLoader(catalog));
       },
     });
   },

plugins/graphql-backend-module-catalog/src/entitiesLoadFn.ts

@@ -2,10 +2,10 @@ import type { CatalogApi } from '@backstage/catalog-client';
 import { Entity } from '@backstage/catalog-model';
 import { NodeQuery } from '@frontside/hydraphql';
 import { GraphQLError } from 'graphql';
+import { CATALOG_SOURCE } from './constants';
 
-export const createEntitiesLoadFn =
-  (catalog: CatalogApi) =>
-  async (
+export const createCatalogLoader = (catalog: CatalogApi) => ({
+  [CATALOG_SOURCE]: async (
     queries: readonly (NodeQuery | undefined)[],
   ): Promise<Array<Entity | GraphQLError>> => {
     // TODO: Support fields
@@ -27,4 +27,5 @@ export const createEntitiesLoadFn =
           new GraphQLError(`no such entity with ref: '${queries[index]}'`)),
     );
     return entities;
-  };
+  },
+});

plugins/graphql-backend-module-catalog/src/index.ts

@@ -2,3 +2,4 @@ export * from './catalog';
 export * from './relation';
 export * from './catalogModule';
 export * from './relationModule';
+export * from './entitiesLoadFn';

plugins/graphql-backend-module-catalog/src/relationModule.ts

@@ -4,8 +4,7 @@ import {
   graphqlLoadersExtensionPoint,
   graphqlModulesExtensionPoint,
 } from '@frontside/backstage-plugin-graphql-backend';
-import { createEntitiesLoadFn } from './entitiesLoadFn';
-import { CATALOG_SOURCE } from './constants';
+import { createCatalogLoader } from './entitiesLoadFn';
 import { Relation } from './relation/relation';
 
 /** @public */
@@ -21,7 +20,7 @@ export const graphqlModuleRelationResolver = createBackendModule({
       },
       async init({ catalog, modules, loaders }) {
         modules.addModules([Relation]);
-        loaders.addLoaders({ [CATALOG_SOURCE]: createEntitiesLoadFn(catalog) });
+        loaders.addLoaders(createCatalogLoader(catalog));
       },
     });
   },

plugins/graphql-backend/docs/backend-plugins.md

@@ -56,10 +56,10 @@ installed, you won't be able to do much with it.
 The way to add new types and new resolvers to your GraphQL backend is
 with [GraphQL Modules][graphql-modules]. These are portable little
 bundles of schema that you can drop into place and have them extend
-your GraphQL server. The most important of these that is maintained by
-the Backstage team is the [graphql-backend-module-catalog][] module that makes your
-Catalog accessible via GraphQL. To add this module to your GraphQL server,
-add it to the `modules` array in your backend config:
+your GraphQL server. The most important of these that is the
+[graphql-backend-module-catalog][] module that makes your
+Catalog accessible via GraphQL. To add this module and catalog loader to your GraphQL server,
+add it to the `modules` array in your backend config and create a catalog `DataLoader`:
 
 ```ts
 import { createRouter } from '@frontside/backstage-plugin-graphql-backend';
@@ -72,6 +72,7 @@ export default async function createPlugin(
   return await createRouter({
     logger: env.logger,
     modules: [Catalog],
+    loaders: { ...createCatalogLoader(env.catalogClient) },
   });
 }
 ```