vesper Framework Documentation

As applications grow, Vesper provides a module abstraction to separate different parts of your application into distinct directories. Instead of a single src directory, you can group related entities, modules, controllers, and schemas into dedicated folders.

To implement a module:

1. Create a dedicated directory for the feature (e.g., src/user).
2. Place all related files (entities, controllers, schemas, etc.) inside that directory.
3. Create a class representing the module (e.g., UserModule.ts) that defines the module's configuration in its constructor.

export class UserModule {
    constructor() {
        this.schemas = [
            __dirname + "/schema/**/*.graphql"
        ];
        this.controllers = [
            { controller: UserController, action: "users", type: "query" },
            { controller: UserController, action: "user", type: "query" },
            { controller: UserController, action: "userSave", type: "mutation" },
            { controller: UserController, action: "userDelete", type: "mutation" },
        ];
        this.entities = [
            User
        ];
        this.resolvers = [
            // ...
        ];
    }
}

By default, a resolver method is called once for every item in a list, which can cause N+1 query problems. To optimize this, use the many: true flag in your resolver registration.

When many: true is set, the resolver method receives an array of parent objects instead of a single object. This allows you to perform a single batch database query (similar to the DataLoader pattern) to fetch data for all items at once.

// Resolver implementation receiving an array of posts
categoryNames(posts) {
    const postIds = posts.map(post => post.id);
    return this.entityManager
        .createQueryBuilder(Category, "category")
        .innerJoinAndSelect("category.posts", "post", "post.id IN (:...postIds)", { postIds })
        .getMany()
        .then(categories => {
            return posts.map(post => {
                return categories
                    .filter(category => category.posts.some(categoryPost => categoryPost.id === post.id))
                    .map(category => category.name);
            });
        });
}

// Registration with 'many: true'
bootstrap({
    resolvers: [
        { 
            resolver: PostResolver, 
            model: Post, 
            methods: [{ methodName: "categoryNames", many: true }] 
        },
    ],
});

In Vesper, Resolver classes are used to resolve fields in a GraphQL model that require additional logic or database queries beyond what a standard controller provides. Instead of bloating your controller with logic for fields that might not even be requested, you should move that logic into a dedicated Resolver class.

For example, if a Post model has a categoryNames field that isn't part of the base Post entity, you create a PostResolver to handle that specific field.

import {EntityManager} from "typeorm";
import {Category} from "../entity/Category";

export class PostResolver {
    constructor(container) {
        this.entityManager = container.get(EntityManager);
    }

    categoryNames(post) {
        return this.entityManager
            .createQueryBuilder(Category, "category")
            .innerJoin("category.posts", "post", "post.id = :postId", { postId: post.id })
            .getMany()
            .then(categories => categories.map(category => category.name));
    }
}

To maintain consistency, follow these naming conventions for your core components:

Models

Models must reside in the model or entity directory. Use a single file per model with the filename matching the class name.

• Example: Photo.ts, Album.ts

Controllers

Use one controller per model. The controller name should include the model name followed by Controller.

• Example: PhotoController.ts, AlbumController.ts

GraphQL Schemas

Create separate .graphql files for each model and controller. Store them in the appropriate subdirectories within schema/.

• Model Schemas: schema/model/Photo.graphql, schema/model/Album.graphql
• Controller Schemas: schema/controller/PhotoController.graphql, schema/controller/AlbumController.graphql

Args

For argument interfaces, take the method name and append the Args postfix. Place these in the args/ directory.

• Example: For a postSave mutation, create PostSaveArgs.ts in the args/ directory.

// model/Photo.ts
export class Photo {
    // ...
}

// controller/PhotoController.ts
export class PhotoController {
    // ...
}

# schema/model/Photo.graphql
type Photo {
    # ...
}

# schema/controller/PhotoController.graphql
type PhotoController {
    # ...
}

By default, a resolver method is called once for every instance of the model being resolved. If you are loading a list of items, this can lead to the 'N+1 query problem'.

To optimize this, Vesper allows you to accept an array of models in your @Resolve() method. This enables you to perform a single batch query (e.g., using an IN clause) to fetch all required data for the entire collection at once.

Instead of: categoryNames(post: Post)

Use: categoryNames(posts: Post[])

@Resolver(Post)
export class PostResolver implements ResolverInterface<Post> {

    constructor(private entityManager: EntityManager) {}

    @Resolve()
    categoryNames(posts: Post[]) {
        const postIds = posts.map(post => post.id);
        return this.entityManager
            .createQueryBuilder(Category, "category")
            .innerJoinAndSelect("category.posts", "post", "post.id IN (:...postIds)", { postIds })
            .getMany()
            .then(categories => {
                return posts.map(post => {
                    return categories
                        .filter(category => category.posts.some(categoryPost => categoryPost.id === post.id))
                        .map(category => category.name);
                });
            });
    }
}

To prevent the N+1 query problem, Vesper allows you to implement batch loading in your resolvers. Instead of receiving a single entity, your @Resolve() method can accept an array of the parent entities. This allows you to perform a single database query for all requested items in a single execution cycle.

@Resolver(Post)
export class PostResolver implements ResolverInterface<Post> {
    @Resolve()
    async categoryNames(posts: Post[]) {
        // 'posts' is an array of all parent entities in the current batch
        const postIds = posts.map(post => post.id);
        
        // Perform one query for all IDs
        const categories = await this.entityManager
            .createQueryBuilder(Category, "category")
            .innerJoinAndSelect("category.posts", "post", "post.id IN (:...postIds)", { postIds })
            .getMany();

        // Map results back to the original array order
        return posts.map(post => {
            return categories
                .filter(category => category.posts.some(categoryPost => categoryPost.id === post.id))
                .map(category => category.name);
        });
    }
}