Package Exports

nestjs-decorated-dataloaders
nestjs-decorated-dataloaders/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nestjs-decorated-dataloaders) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

NestJS Decorated Dataloaders

A lightweight wrapper around Dataloader that lets you declare where to batch and cache instead of wiring it by hand. Add an @Load decorator to any field, register a handler, and the N+1 query problem is gone.

Installation

npm install nestjs-decorated-dataloaders

or using yarn:

yarn add nestjs-decorated-dataloaders

Quick Start

Module Configuration

Configure the DataloaderModule in your application module:

import { Module } from "@nestjs/common";
import { GraphQLModule } from "@nestjs/graphql";
import { LRUMap } from "lru_map";
import { DataloaderModule } from "nestjs-decorated-dataloaders";

@Module({
  imports: [
    GraphQLModule.forRoot({
      autoSchemaFile: true,
    }),
    DataloaderModule.forRoot({
        name: "MyAwesomeDataloader",
        cache: true,
        maxBatchSize: 100,
        getCacheMap: () => new LRUMap(100),
    }),
  ],
})
export class AppModule {}

name: Names the dataloader for better tracking and debugging.
cache: Enables caching.
maxBatchSize: Limits the maximum number of batched requests.
getCacheMap: Defines a custom cache implementation (e.g., LRU Cache).

Defining Entities

PhotoEntity

import { Field, Int, ObjectType } from "@nestjs/graphql";
import { Load } from "nestjs-decorated-dataloaders";
import { UserEntity } from "./user.entity";

@ObjectType()
export class PhotoEntity {
  @Field(() => Int)
  id: number;

  @Field(() => String)
  url: string;

  @Field(() => Number)
  userId: number;
}

UserEntity

import { Field, Int, ObjectType } from "@nestjs/graphql";
import { Load } from "nestjs-decorated-dataloaders";
import { PhotoEntity } from "./photo.entity";

@ObjectType()
export class UserEntity {
  @Field(() => Int)
  id: number;

  @Field(() => String)
  name: string;

  @Field(() => Date)
  createdAt: Date;

  // One-to-one relationship with PhotoEntity
  @Load<PhotoEntity, UserEntity>(() => PhotoEntity, { key: "id", parentKey: "userId", handler: "LOAD_PHOTOS_BY_USER_ID" })
  photo: PhotoEntity;

  // One-to-many relationship with PhotoEntity
  @Load<PhotoEntity, UserEntity>(() => [PhotoEntity], { key: "id", parentKey: "userId", handler: "LOAD_PHOTOS_BY_USER_ID" })
  photos: PhotoEntity[];
  
  // Many-to-many relationship with PhotoEntity
  
  userPhotos: UserPhotoEntity[]; // intermediate table
  
  @Load<PhotoEntity, UserEntity>(() => [PhotoEntity], { key: "id", parentKey: "userPhotos.userId", handler: "LOAD_PHOTOS_BY_USER_ID" })
  photosByUsers: PhotoEntity[];
}

Dataloader Handlers

Dataloader handlers define how data is fetched from the data source. Handlers are tied to specific dataloaders using the @DataloaderHandler decorator.

import { Inject, Injectable } from "@nestjs/common";
import { DataloaderHandler } from "nestjs-decorated-dataloaders";
import { PhotoEntity } from "../../entities/photo.entity";
import { DatabaseService } from "../database/database.service";

// tip: define constants for handler keys in a separated file
export const LOAD_PHOTOS_BY_USER = "LOAD_PHOTOS_BY_USER";

@Injectable()
export class PhotoRepository {
  constructor(
    @Inject(DatabaseService)
    private readonly database: DatabaseService,
  ) {}
    
  /**
   * This method will be called by the dataloader with batched user IDs
   */
  @DataloaderHandler(LOAD_PHOTOS_BY_USER)
  async findAllByUsersIds(usersIds: number[]): Promise<PhotoEntity[]> {
    // Fetch all photos from some data source
    const photos = await this.database.getPhotos({
        where: {
            userId: { in: usersIds }
        }
    });

    return photos
  }
}

Using Dataloaders in Resolvers

Resolvers use the DataloaderService to load related entities, ensuring requests are batched and cached.

import { Inject } from "@nestjs/common";
import { Parent, ResolveField, Resolver } from "@nestjs/graphql";
import { DataloaderService } from "nestjs-decorated-dataloaders";
import { GroupEntity } from "../entities/group.entity";
import { PhotoEntity } from "../entities/photo.entity";
import { UserEntity } from "../entities/user.entity";

@Resolver(() => UserEntity)
export class UserResolver {
  constructor(
    @Inject(DataloaderService)
    private readonly dataloaderService: DataloaderService,
  ) {}
    
  /**
   * This resolver field uses the dataloader to fetch photos for a user
   * The dataloader will batch and cache requests for optimal performance
   */
  @ResolveField(() => [PhotoEntity])
  async photos(@Parent() user: UserEntity) {
    return this.dataloaderService.load({ 
      from: UserEntity,
      field: "photos",
      data: user
    });
  }
}

Advanced Concepts

Function-Based Mapper

Function-Based Mapper allows you to use functions instead of string paths for the key and parentKey properties in the @Load decorator. This is particularly useful when you need to work with composite keys or when you need more complex mapping logic.

import { Field, Int, ObjectType } from "@nestjs/graphql";
import { Load } from "nestjs-decorated-dataloaders";
import { CategoryPostEntity } from "./category-post.entity";
import { CategoryEntity } from "./category.entity";

@ObjectType()
export class PostEntity {
  @Field(() => Int)
  id: number;

  @Field(() => String)
  title: string;

  @Field(() => String)
  content: string;

  @Field(() => String)
  createdAt: string;

  // Relationship with CategoryPostEntity for the many-to-many relationship
  categoryPosts: CategoryPostEntity[];

  /**
   * Using Function-Based Mapper for complex relationships
   * This handles a many-to-many relationship through a join table
   */
  @Load<CategoryEntity, PostEntity>(() => [CategoryEntity], {
    key: (post) => post.categoryPosts.map((cp) => cp.postId),
    parentKey: (category) => category.id,
    handler: "LOAD_CATEGORY_BY_POSTS",
  })
  categories: CategoryEntity[];
}

In this example, the key function extracts the postId values from the categoryPosts array, and the parentKey function maps through the categoryPosts array to extract all id values.

Benefits of Function-Based Mapper

Complex Mapping: You can implement complex mapping logic that goes beyond simple property access.
Composite Keys: You can create composite keys by combining multiple fields.
Flexibility: You can use any JavaScript expression to compute the key.
Performance: Function-based mappers are more CPU efficient compared to string-based mappers.

Type Safety

You can use TypeScript generics to ensure type safety when declaring a Dataloader field.

import { Field, Int, ObjectType } from "@nestjs/graphql";
import { Load } from "nestjs-decorated-dataloaders";
import { PhotoEntity } from "./photo.entity";

@ObjectType()
export class UserEntity {
  @Field(() => Int)
  id: number;

  @Field(() => String)
  name: string;

  @Field(() => Date)
  createdAt: Date;
  
  @Load<PhotoEntity, UserEntity>(() => [PhotoEntity], {
    key: (user) => user.id,
    parentKey: (photo) => photo.userId,
    handler: "LOAD_PHOTOS_BY_USER",
  })
  photos: Array<PhotoEntity>;
}

In this example, the key function is typed to receive a UserEntity and the parentKey function is typed to receive a PhotoEntity.

Handling Circular Dependencies

Circular dependencies between entities (e.g., User ↔ Photo) can cause metadata resolution errors when using reflect-metadata. For example:

reflect-metadata tries to read metadata from User, which references Photo.

Photo in turn references User, but if User hasn't been fully initialized, its metadata resolves to undefined.

This issue is common in environments using SWC. To resolve it, use the Relation wrapper provided by nestjs-decorated-dataloaders.

Solution: Wrapping Circular References Encapsulate circular properties with Relation. This prevents reflect-metadata from attempting to resolve the circular dependency during type introspection.

Example:

import { Relation } from 'nestjs-decorated-dataloaders';

class User {
  photo: Relation<Photo>;
}

class Photo {
  user: Relation<User>;
}

How It Works Generic Type Erasure: reflect-metadata cannot infer generic types like Relation, so it defaults the metadata to undefined, avoiding circular resolution errors.

Explicit Type Declaration: You must manually specify the wrapped type (e.g., Relation) to retain type safety in your code.

Important Notes Use Relation only for circular dependencies. For non-circular references, use direct types (e.g., Photo instead of Relation). Ensure the generic type (e.g., Photo inside Relation) is explicitly declared to avoid type inference issues.

Aliases

Aliases let you associate a dataloader handler with an abstract class, offering a simple way to handle cases where decorators can't be used, especially in complex architectures with shared or abstract classes.

Using Aliases

@AliasFor(() => AbstractPhotoService)
export class ConcretePhotoService {}

This allows PhotoService to serve as the dataloader handler for AbstractPhotoService.

Under the Hood

nestjs-decorated-dataloaders is built on top of the GraphQL Dataloader library. At its core, a dataloader is a mechanism for batching and caching database or API requests, reducing the number of round trips required to fetch related data.

Batching: Dataloader batches multiple requests for the same resource into a single query. This ensures that, rather than issuing one query per entity (e.g., fetching one photo per user), the dataloader combines them into a single query that fetches all the photos for the users in one go.
Caching: Dataloader caches query results, preventing redundant queries for the same data within the same request cycle. This ensures that once a resource is fetched, later requests for the same resource will use the cached data.

High-Level Nest.js Abstraction

nestjs-decorated-dataloaders abstracts the complexities of manually managing dataloaders and integrates seamlessly with Nest.js using decorators. It provides a declarative and maintainable approach to solving the N+1 problem, allowing you to focus on building features without worrying about the underlying dataloader logic.

By using decorators like @Load and @DataloaderHandler, this module streamlines dataloader setup, making it simple to handle related entities in GraphQL resolvers without manual dataloader instantiation or dependency injection.