# graphql-introspection-filtering Extends schema mapper abilities and allows filtering/modifying introspection query results. > **NOTE:** For successful introspection all dependent types must be returned. If any of dependent types is missing, it's not possible to rebuild graph on client side, for example graphql playground is unable to build an interactive documentation. > **NOTE:** `Query` type definition is required > **NOTE:** Object types must contain at least one visible field > **NOTE:** GraphQL now does not validate data against full schema, remember to implement logic in base mappers > **Tested with GraphQL 16.6.0 & @graphql-tools 8.0.0 - 10.0.0 (for legacy graphql-tools support check release 2.1.0) ** ## Installation ```bash npm install --save graphql-introspection-filtering ``` or ```bash yarn add graphql-introspection-filtering ``` ## Usage ### Create schema Filtering is possible on schemas created with `makeExecutableSchema`, provided by `graphql-introspection-filtering`. To enable filtering, a mapper has to be applied to schema. ``` import makeExecutableSchema, { mapSchema } from 'graphql-introspection-filtering'; export default mapSchema(makeExecutableSchema(schemaConfig[, builder]), mapper); ``` - `schemaConfig` - schema configuration, extended original `makeExecutableSchema`'s config object Additional options | Option | Type | Default | Description | |---------------------|------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **shouldSkipQuery** | `null`, `number`, `(context) => boolean` | `null` | When positive number provided, this number of introspection queries will be unfiltered. Alternatively callback can be provided, it takes `context` as an argument, and should return boolean. | | **hookDirectives** | `boolean`, `string[]` | `true` | Whether to hook directives, array of specific directive names can be provided | - `builder` - builder function (default: original graphql `makeExecutableSchema`) - `mapper` - introspection schema mapper ### Create introspection schema mapper Every object and field is visited by a directive visitor, where corresponding directive is applied on it in a schema definition (directives configured separately) **AND** applied mapper contains a corresponding introspection visitor method. When *falsy* value is returned by a mapped resolver, the field / object is excluded from introspection result. Example introspection mapper can be found below. ```ts export const mapper = { // (optional) If defined instance can visit `scalar` definitions [IntrospectionMapperKind.SCALAR_TYPE](result: GraphQLScalarType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit `enum` definitions [IntrospectionMapperKind.ENUM_TYPE](result: GraphQLEnumType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit object `type` definitions [IntrospectionMapperKind.OBJECT_TYPE](result: GraphQLObjectType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit `input` object definitions [IntrospectionMapperKind.INPUT_OBJECT_TYPE](result: GraphQLInputObjectType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit `union` definitions [IntrospectionMapperKind.UNION_TYPE](result: GraphQLUnionType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit `interface` definitions [IntrospectionMapperKind.INTERFACE_TYPE](result: GraphQLInterfaceType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit enum value definitions [IntrospectionMapperKind.ENUM_VALUE](result: GraphQLEnumValue, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit object field definitions [IntrospectionMapperKind.OBJECT_FIELD](result: GraphQLField, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit field argument definitions [IntrospectionMapperKind.ARGUMENT](result: GraphQLArgument, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit input field definitions [IntrospectionMapperKind.INPUT_OBJECT_FIELD](result: GraphQLInputField, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, // (optional) If defined instance can visit `directive` definitions [IntrospectionMapperKind.DIRECTIVE](result: GraphQLDirective) { return wrap(result, schema, resolver); } } satisfies IntrospectionSchemaMapper & SchemaMapper; ``` ## Examples ### Integration tests There are working examples available, to start local server use `npm run example` or `yarn example`. Those examples use schema mocks from `tests/integration/__mocks__`. ### Authentication example This example provides simple authentication based on roles provided in context. #### Schema ```graphql enum Role @auth(requires: ADMIN) { ADMIN REVIEWER USER UNKNOWN } directive @auth( requires: Role = ADMIN, ) on OBJECT | FIELD_DEFINITION | ENUM type Book @auth(requires: ADMIN) { title: String author: String } type Query { me: User books: [Book] @auth(requires: ADMIN) } ``` #### Authentication mapper ```ts type WrappedResolverType = ( directive: Record, orig: GraphQLFieldResolver, ...passtrough: Parameters> ) => TResult; const check = (context: ContextType, requiredPermission?: string) => { // permission check }; const introspectionResolver = ( directive: Record, orig: GraphQLFieldResolver, parent: unknown, args: Record, context: ContextType, info: GraphQLResolveInfo ) => { if (check(context, directive.requires)) { return orig(parent, args, context, info); } return null; }; const resolver = ( directive: Record, orig: GraphQLFieldResolver, parent: unknown, args: Record, context: ContextType, info: GraphQLResolveInfo ) => { if (!check(context, directive.requires)) { throw new ValidationError(`Cannot query field "${info.fieldName}" on type "${info.parentType.name}".`); } return orig(parent, args, context, info); }; type WrappableIntrospectionType = VisitableIntrospectionType & { resolve: GraphQLFieldResolver | null; subscribe: GraphQLFieldResolver | null; // not precise } const isWrappable = (val: any): val is WrappableIntrospectionType => !!val; const wrap = (result: T, schema: GraphQLSchema, resolver: WrappedResolverType) => { const directive = getDirective(schema, result as any, 'auth')?.[0]; if (directive && isWrappable(result)) { const key = result.subscribe ? 'subscribe' : 'resolve'; const current = result[key]; result[key] = resolver.bind(undefined, directive, current || defaultFieldResolver); } return result; }; export const authMapper = { [IntrospectionMapperKind.SCALAR_TYPE](result: GraphQLScalarType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.ENUM_TYPE](result: GraphQLEnumType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.OBJECT_TYPE](result: GraphQLObjectType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.INPUT_OBJECT_TYPE](result: GraphQLInputObjectType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.UNION_TYPE](result: GraphQLUnionType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.INTERFACE_TYPE](result: GraphQLInterfaceType, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.ENUM_VALUE](result: GraphQLEnumValue, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.OBJECT_FIELD](result: GraphQLField, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.ARGUMENT](result: GraphQLArgument, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.INPUT_OBJECT_FIELD](result: GraphQLInputField, parent: any, schema: GraphQLSchema) { return wrap(result, schema, introspectionResolver); }, [IntrospectionMapperKind.DIRECTIVE](result: GraphQLDirective) { if (result.name === 'auth' && isWrappable(result)) { result.resolve = () => null; } return result; }, [MapperKind.ENUM_TYPE](result, schema) { return wrap(result, schema, resolver); }, [MapperKind.OBJECT_FIELD](result, _, __, schema) { return wrap(result as any, schema, resolver); }, [MapperKind.INPUT_OBJECT_FIELD](result, _, __, schema) { return wrap(result as any, schema, resolver); } } satisfies IntrospectionSchemaMapper & SchemaMapper; ``` #### Make it executable ```ts import makeExecutableSchema, { mapSchema } from 'graphql-introspection-filtering'; export default mapSchema(makeExecutableSchema({ typeDefs: ...schema..., ..., }), authMapper); ```

graphql-introspection-filtering

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past