Feature requests for the version 3 of the library

[pacyL2K19]

Context

I have been dabbling with the library for the past few days on a project built on the Nest.js library, and I ended up with a small set of suggestions, wanted to know what the community/maintainers think about them

Here are a couple of feature requests I collected so far, I would like to get your feedback, I am also open to helping build them if it's something that aligns with the vision of the library

1. Enhanced Support for Complex Object Graphs

Description

This feature aims to implement a more intuitive and streamlined approach to handle complex object relationships and nested factories within Fishery. Key aspects of this enhancement would include:

• Auto-Detection of Relationships: Automatically identify and set up relationships between different entities, reducing manual configuration.
• Simplified Setup for Nested Objects: Provide a more straightforward method to define nested object structures within factories.
• Improved Syntax for Interconnected Factories: Develop a clearer and more concise syntax for defining and using interconnected factories.

Justification

Complex object graphs are prevalent in real-world applications, particularly those involving relational data models like in ORM frameworks. The current process of setting up and managing these relationships in Fishery can be unintuitive, especially for users who are dealing with intricate and deeply nested data models. Simplifying this aspect of Fishery would make it more accessible to a wider range of developers and reduce the learning curve, ultimately enhancing productivity and adoption.

Potential Implementation Ideas

• Leverage TypeScript's introspection capabilities to analyze class relationships and automatically generate the necessary factory configurations.
• Introduce new API methods or syntax that simplify the declaration of nested objects and their relationships.
• Provide integration examples with popular ORMs (like TypeORM, Sequelize) to demonstrate the setup of complex object graphs.

Example Use Case

Consider an application with a typical blog structure where a User has many Posts, and each Post has many Comments. Setting up factories for these entities with complex relationships can currently be verbose and error-prone.

Current Approach:

// Defining factories for User, Post, and Comment with manual relationship setup
const userFactory = Factory.define<User>(() => ({ ... }));
const postFactory = Factory.define<Post>(() => ({ ... }));
const commentFactory = Factory.define<Comment>(() => ({ ... }));

// Manually setting up relationships
const user = userFactory.build();
const posts = postFactory.buildList(3, { userId: user.id });
posts.forEach(post => {
    const comments = commentFactory.buildList(2, { postId: post.id });
    post.comments = comments;
});

Proposed Approach with Enhanced Feature:

// Defining factories with automatic relationship detection
const userFactory = Factory.define<User>(() => ({ ... }));
const postFactory = Factory.define<Post>(() => ({ ... }));
const commentFactory = Factory.define<Comment>(() => ({ ... }));

// Simplified object graph creation
const userWithPostsAndComments = userFactory.buildGraph();

In the proposed approach, buildGraph() would automatically create the user, their posts, and comments associated with those posts, based on predefined relationships.

Conclusion

Enhancing Fishery with better support for complex object graphs aligns with modern development practices and addresses a significant pain point for many developers. This feature would make Fishery a more robust and user-friendly tool in the ecosystem of TypeScript testing utilities.

2. Simplified Syntax for Transient Parameters and Associations

Description

This feature request proposes the development of a more concise and readable syntax for defining and passing transient parameters and associations in Fishery. The enhancement would involve introducing syntactic sugar or new API methods that aim to:

• Reduce Boilerplate: Minimize the amount of repetitive and verbose code needed to define transient parameters and associations.
• Enhance Code Readability: Improve the clarity and maintainability of the code by simplifying the syntax used to handle these parameters.

Justification

The current approach to handling transient parameters and associations in Fishery, while powerful, can lead to verbose and complex code structures, especially in scenarios where multiple such parameters are involved. This verbosity can detract from code readability and maintainability, making it challenging for developers to quickly understand or modify test setups. A more streamlined syntax would significantly enhance the developer experience, making it easier to work with complex test data setups and ultimately improving the overall quality and maintainability of test suites.

Potential Implementation Ideas

Introduce a new, simplified API for defining transient parameters and associations directly within the factory definition.
Explore the possibility of using decorators or similar TypeScript features to declaratively specify transient parameters and associations.
Provide utility functions or shorthand methods that abstract away the complexity of the current verbose syntax.

Example Use Case

Consider a scenario where we need to create a user with specific transient data and associations:

Current Approach:

const user = userFactory.build({}, {
  transient: { isAdmin: true, numberOfPosts: 5 },
  associations: { profile: profileFactory.build() }
});

Proposed Approach with Simplified Syntax:

const user = userFactory.buildWith({
  isAdmin: true,
  numberOfPosts: 5,
  profile: profileFactory.build()
});

In the proposed approach, buildWith() is a new method that seamlessly integrates transient parameters and associations, making the code more concise and readable.

Conclusion

Simplifying the syntax for transient parameters and associations in Fishery would make the library more accessible and user-friendly. It would encourage best practices in writing clean and maintainable test code, aligning Fishery more closely with the needs and expectations of the modern TypeScript developer community.

3. Automatic Factory Creation with Class Decorators

Description

This feature request involves the implementation of a class decorator in Fishery, which would be utilized to automatically generate factories for classes. The proposed decorator would analyze class properties and methods to create a corresponding factory with minimal manual setup. The main aspects of this feature would include:

• Introspection of Class Structure: Automatically detect and utilize class properties and methods to set up a corresponding factory.
• Decorator-Driven Factory Generation: Use a decorator on the class to indicate that a factory should be automatically generated for it.

Justification

In large-scale applications or projects with a significant number of models/entities, manually defining factories for each class can be a tedious and time-consuming process. By introducing a class decorator for automatic factory generation, Fishery would significantly streamline this process. This feature aligns well with the TypeScript ecosystem, which supports decorators natively(from version 5 of ts), and it would be particularly beneficial for the ts community and in projects using TypeScript-based frameworks like Nest.js and Angular that embrace decorators for various functionalities.

Potential Implementation Ideas

Develop a @Factory decorator (or similarly named) that can be applied to class definitions.
The decorator should handle the creation of a standard factory based on the class's properties, with options for customization.
Integrate this feature with TypeScript's reflection capabilities to accurately map class properties to factory attributes.

Example Use Case

Consider a simple User model in a TypeScript application:

Current Approach:

class User {
  id: number;
  name: string;
  // Other properties...
}

// Manually creating a factory for the User class
const userFactory = Factory.define<User>(() => ({
  id: sequence,
  name: 'Default Name',
  // Other default values...
}));

Proposed Approach with Class Decorators:

@Factory()
class User {
  id: number;
  name: string;
  // Other properties are automatically mapped...
}

// The factory for User is automatically created and ready to use
const user = User.userFactory.build({ name: 'Alice' }); // we could inject this in the class on run-time so we don't have to create the userFactory by hands

In this proposed approach, the @Factory() decorator automatically generates a factory for the User class, reducing boilerplate and streamlining factory setup.

Conclusion

Introducing automatic factory creation through class decorators would be a significant enhancement to Fishery, reducing setup time and complexity, especially in large applications with numerous models. This feature would make Fishery a more powerful and convenient tool in the TypeScript ecosystem, especially for developers working with frameworks that embrace decorator patterns.

cc: @MalcolmTomisin @Tresor11