Nest Graphql Filters

Generate filters in a simple, automatic and standardized way in the @nestjs framework and @nestjs/graphql using decorators.

Installation

npm install @gabrieljsilva/nest-graphql-filters

or

yarn add @gabrieljsilva/nest-graphql-filters

Usage

First, it's necessary to register the module, where the registration method requires a mandatory param called databaseProvider. This information is crucial in the subsequent serialization process. Ex:

import { NestFilterModule } from '@gabrieljsilva/nest-graphql-filters';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: join(process.cwd(), 'schema.gql')
    }),
    NestFilterModule.register('pg'),
    // rest of imports...
  ],
  controllers: [],
  providers: [],
  exports: [],
})
export class AppModule {}

After registering the module, the second step is to declare the entities using a class and applying the decorators: FilterableEntity and FilterableField.

• FilterableEntity: Marks a class as an entity.
• FilterableField: Marks a class property as a "filterable" field.

ex:

import { ID } from '@nestjs/graphql';
import { FilterableEntity, FilterableField } from '@gabrieljsilva/nest-graphql-filters';

@FilterableEntity()
export class User {
  @FilterableField(() => ID)
  id: string;
  
  @FilterableField()
  name: string;

  @FilterableField()
  email: string;
  
  password: string;
    
  @FilterableField()
  createdAt: Date;
  
  @FilterableField()
  deletedAt?: Date;
}

To apply this filter in a Resolver, use the FilterArgs decorator, passing the target entity as an argument. It's possible to infer type using "FilterOf" generic. Ex:

import { Query, Resolver } from '@nestjs/graphql';
import { FilterArgs, FilterOf } from '@gabrieljsilva/nest-graphql-filters';

import { UserService } from './user.service';
import { User } from '../../models';

@Resolver(User)
export class UserResolver {
    constructor(private readonly userService: UserService) {}
    
    @Query(() => [User])
    async findUsers(@FilterArgs(User) userFilter: FilterOf<User>) {
        return this.userService.findUsers(userFilter);
    }
}

Operations

Each primitive type has an associated filter with its own operators:

| | Boolean | ID | Int | Float | String | Date | Timestamp | |----------|---------|-----|-----|-------|--------|------|-----------| | Is | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Like | ✕ | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | | In | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | | Gt | ✕ | ✕ | ✓ | ✓ | ✕ | ✓ | ✓ | | Lt | ✕ | ✕ | ✓ | ✓ | ✕ | ✓ | ✓ | | Gte | ✕ | ✕ | ✓ | ✓ | ✕ | ✓ | ✓ | | Lte | ✕ | ✕ | ✓ | ✓ | ✕ | ✓ | ✓ |

Also, each entity is created with the following logical operators:

| Name | Description | |----------|----------------------------------------------------| | _AND | A list of entities that perform an "AND" operation | | _OR | A list of entities that perform an "OR" operation | | _NOT | A list of entities that perform an "NOT" operation |

Querying

Through the previously defined User entity and the findUsers query, it is possible to construct the following GraphQL query:

Example Query

query FindUsers($filter: UserFilter) {
    findUsers(filters: $filter){
        id
        name
        email
        createdAt
        deletedAt
    }
}

Example Variables

{
  "filters": {
    "name": {
      "like": "John"
    },
    "createdAt": {
      "gte": "2024-01-01" 
    },
    "_NOT": [
      {
        "name": {
          "is": "John Doe"
        }
      }
    ]
  }  
}

Relationships

In addition to filters based on primitive types, it is also possible to create relationships between entities. Ex:

import { ID } from '@nestjs/graphql';
import { FilterableEntity, FilterableField } from '@gabrieljsilva/nest-graphql-filters';

@FilterableEntity()
export class Photo {
    @FilterableField(() => ID)
    id: string;

    @FilterableField()
    url: string;
    
    @FilterableField()
    category: string
}

@FilterableEntity()
export class User {
  @FilterableField(() => ID)
  id: string;
  
  @FilterableField()
  name: string;

  @FilterableField()
  photo: Photo
}

Example Query

query FindUsers($filter: UserFilter) {
    findUsers(filters: $filter){
        id
        name
        photo {
            id
            url
            category
        }
    }
}

Example Variables

{
  "filters": {
    "email": {
      "is": "[email protected]"
    },
    "photo": {
      "category": {
        "is": "Nature"
      }  
    }
  }  
}

Circular Dependency

Although not recommended, it is still possible to create circular types (types that depend on each other simultaneously).

import { ID } from '@nestjs/graphql';
import { FilterableEntity, FilterableField } from '@gabrieljsilva/nest-graphql-filters';

@FilterableEntity()
export class Credentials {
    @FilterableField(() => ID)
    id: string;

    @FilterableField()
    email: string;

    password: string;

    @FilterableField(() => User)
    user: User
}

@FilterableEntity()
export class User {
    @FilterableField(() => ID)
    id: string;

    @FilterableField()
    name: string;

    @FilterableField()
    Credentials: Credentials
}

PS: The SWC compiler does not correctly load circular dependencies.

Serialization

It's possible to use pipes to serialize the data received in the request. Ex:

import { FilterOptions } from '@gabrieljsilva/nest-graphql-filters';

export const ToPrismaQueryPipe = memoize<(type: Type) => PipeTransform>(
    createToPrismaQueryPipe,
);

function createToPrismaQueryPipe(type: Type): Type<PipeTransform> {
    class ToPrismaQueryPipe implements PipeTransform {
        constructor(@Inject(FilterOptions) filterOptions: FilterOptions) {}

        async transform<T = unknown>(value: FilterOf<T>) {
            if (!value) {
                return {};
            }
            const fieldMetadata = FilterTypeMetadataStorage.getIndexedFieldsByType(type);
            return this.getWhereInputQuery(value, fieldMetadata);
        }

        getWhereInputQuery(
            filter: FilterOf<unknown>,
            metadata: Map<string, FieldMetadata>,
            query = {},
        ) {
            // Implements your query here
        }
    }

    return ToPrismaQueryPipe;
}

The property filterOptions contains the property named provider, which is the name of the database provider. Since even among relational databases that use SQL, there are some differences in query construction, this information can assist in writing more generic pipes and facilitate the database switch at some point.

To use pipes with parameters, it's necessary to create a function that returns the pipe class, or it's instance. By using this method, a new pipe is created for each implementation of the filter. To prevent redundancy in pipe creation, the memoization technique can be applied, ensuring the use of the same pipe even when implemented in multiple different queries.

It's possible to create more complex pipes by utilizing metadata extracted from the following functions:

| Name | Return Type | description | |--------------------|----------------------------|------------------------------------------------------------| | getFieldMetadata | Set | Returns a set of FieldMetadata. | | getIndexedFields | Map<string, FieldMetadata> | Returns a Map where the keys are the names of the Schemas. |

Both functions have different goals. The getFieldMetadata function aims to be iterable and presents a complexity of O(N), while the getIndexedFields function aims to be indexed by name to avoid iterations and optimize performance in runtime with a complexity of O(1).

FieldMetadata

| Property | Type | Description | |-------------------|-----------|------------------------------------| | name | string | Name of the property (public) | | originalName | string | Original name of the property | | type | Type | Property original type | | isPrimitiveType | boolean | Whether type is a primitive | | nullable | boolean | Whether the field is nullable | | isArray | boolean | Whether the property is an array | | description | string? | Custom description of the property |

PS: Marking a property as "array" or "nullable" does not imply that the generated filter property by the library is an "array" or "null", refers only to the original entity property. Marking a field as "nullable" or "array" serves to guide pipes to the exact structure of the original entity.

Applying pipes

import { ToPrismaQueryPipe } from '../../pipes';

@Resolver(User)
export class UserResolver {
    constructor(private readonly userService: UserService) {}

    @Query(() => [User])
    async findUsers(@FilterArgs(User, ToPrismaQueryPipe(User)) userFilter: FilterOf<User>) {
        return this.userService.findUsers(userFilter);
    }
}

Customization

It's possible to make some customizations to the generated types or metadata through decorators:

// Defines a custom name for the type that will be exposed by the API
@FilterableEntity('CustomUserFilterName')
export class User {
    @FilterableField(() => ID)
    id: string;

    // Defines a custom name and description for the property that will be exposed by the API 
    // and defines in the metadata that this property is not nullabe
    @FilterableField({ name: 'customUserName', description: 'My Awesome Name', nullable: false })
    name: string;

    // Defines in the metadata that this field is an array of a specific type
    @FilterableField(() => [Photo])
    photo: Photo[]

    // Explicitly defines type and options
    @FilterableField(() => Address, { name: 'myAddress', nullable: true })
    address?: Address
}