docs: finalize release notes for 9.0.0

Author: nodkz

docs/releases/9.0.0.md

@@ -3,10 +3,12 @@
 <!-- TOC depthFrom:2 -->
 
 - [What's new?](#whats-new)
-  - [🛑 resolver creation (factory)](#🛑-resolver-creation-factory)
+  - [A new way for resolver creation (via factory)](#a-new-way-for-resolver-creation-via-factory)
+  - [An full example using TypeScript with mongoose, graphql-compose-mongoose, and a new DataLoader resolver.](#an-full-example-using-typescript-with-mongoose-graphql-compose-mongoose-and-a-new-dataloader-resolver)
+  - [Expose `resolverFactory` for advanced cases of resolver creation](#expose-resolverfactory-for-advanced-cases-of-resolver-creation)
   - [Mutations got `error: ErrorInterface` field in theirs payload for better error handling](#mutations-got-error-errorinterface-field-in-theirs-payload-for-better-error-handling)
   - [Added a new `ValidationError`](#added-a-new-validationerror)
-- [Improvements](#improvements)
+- [Enhancements](#enhancements)
   - [Now `_id` field can be of any type (Int, String, Object)](#now-_id-field-can-be-of-any-type-int-string-object)
   - [Add nested fields support, new operators `regex`, `exists` for `filter._operators`](#add-nested-fields-support-new-operators-regex-exists-for-filter_operators)
   - [Better alias support for nested embedded fields](#better-alias-support-for-nested-embedded-fields)
@@ -27,13 +29,154 @@
 
 ## What's new?
 
-### 🛑 resolver creation (factory)
+### A new way for resolver creation (via factory)
 
-- Refactor resolver creation #263
-- Expose `mongooseResolvers` for manual creation of resolvers #274
-- feat: expose `resolverFactory` for manual resolver creation, eg. for cloned types: `resolverFactory.findMany(UserModel, ClonedUserTC, opts)` – it generates Resolver's types according to `ClonedUserTC` type and will use mongoose `UserModel` for making requests to DB
-- feat: added new function `composeMongoose` which generates TypeComposer without resolvers. Now Resolvers can be generated on-demand in such way `PostTC.mongooseResolvers.findMany()` (before was `PostTC.getResolver('findMany')`)
-- Improve Typescript definitions for resolvers
+Before 9.0.0 `graphql-compose-mongoose` generates type & resolvers together on `composeWithMongoose` call. This approach have the following disadvantages:
+- no static analysis for resolver names (are you sure that `findById` exists?)
+- under the hood generated around 15 resolvers and many graphql types for them (do you really use all of these resolvers?)
+- no static analysis for available args when you are crating relations
+- quite awkward mechanics of creating new resolvers, cloning, or wrapping them (what if you need to change type before resolvers creation? what if I need several copies of one resolver with a different set of args?)
+- no `go-to` support in IDE via ctrl+click for opening resolver definition.
+
+To overcome all these problems was created a new `composeMongoose` method. And I strongly recommend to migrate your codebase from the old `composeWithMongoose` to a new one method for making your code more stable and faster:
+
+```diff
+- import { composeWithMongoose } from 'graphql-compose-mongoose';
++ import { composeMongoose } from 'graphql-compose-mongoose';
+
+// generate GraphQL types & resolvers from mongoose model
+- const UserTC = composeWithMongoose(UserModel);
++ const UserTC = composeMongoose(UserModel);
+
+// getting generated resolver by name `findById`
+- const findByIdResolver = UserTC.getResolver('findById');
++ const findByIdResolver = UserTC.mongooseResolvers.findById();
+```
+
+Under the hood new `composeMongoose` method on its call:
+- will create just two types `ObjectTypeComposer` & `InputTypeComposer`
+- will not generate resolvers automatically, but instead of this, it adds `mongooseResolvers` property with a factory for resolver creation on demand.
+
+It will provide the following advantages:
+- You may programmatically modify `TypeComposer` and only after that generate resolvers with their sub-types based on already customized fields in `TypeComposer`.
+- Safe memory and time on the bootstrap server phase, because it won't generate unused resolvers.
+- You may call one resolver generator several times with different configurations.
+- `mongooseResolvers` factory has improved typescript definitions. And you will get not only a list of available resolvers by names but also their customization options. Moreover, all generated Resolvers will know its `source: Model<IDoc>`.
+- According to its customization options for every resolver, you may control how your resolvers will be generated. Also, it unlocks the ability in future releases to add more options like `before` & `after` hooks, ACL, additional filters, and sorts params.
+
+[Issue #263](https://github.com/graphql-compose/graphql-compose-mongoose/issues/263)
+
+### An full example using TypeScript with mongoose, graphql-compose-mongoose, and a new DataLoader resolver.
+
+An example of TypeScript usage with a lot of type checks and autosuggestions:
+
+```ts
+import { SchemaComposer } from 'graphql-compose';
+import { composeMongoose } from 'graphql-compose-mongoose';
+import { mongoose } from 'mongoose';
+
+// type for context which is provided by graphql-server
+interface TContext {
+  req: Request;
+}
+
+// creating a schema with TContext
+const schemaComposer = new SchemaComposer<TContext>();
+
+// describe mongoose schema for User
+const UserSchema = new mongoose.Schema({
+  name: { type: String, required: true },
+});
+
+// define interface for your mongoose model IUser
+interface IUser extends mongoose.Document {
+  name: string;
+}
+
+// describe mongoose schema for Post
+const PostSchema = new mongoose.Schema({
+  title: { type: String, required: true },
+  authorId: { type: mongoose.Types.ObjectId },
+  reviewerIds: { type: [mongoose.Types.ObjectId] },
+});
+
+// define interface for your mongoose model IPost
+interface IPost extends mongoose.Document {
+  title: string;
+  authorId?: mongoose.Types.ObjectId;
+  reviewerIds?: [mongoose.Types.ObjectId];
+}
+
+// Create mongoose models with typescript definitions
+// Bored with describing fields two times for Schema and for Interface –
+//   try typegoose: https://typegoose.github.io/typegoose/
+const UserModel = mongoose.model<IUser>('User', UserSchema);
+const PostModel = mongoose.model<IPost>('Post', PostSchema);
+
+// create ObjectTypeComposers via the new method
+const UserTC = composeMongoose(UserModel);
+const PostTC = composeMongoose(PostModel);
+
+// make relations between Post <--> Author
+// via adding a new field `author` and using DataLoader
+PostTC.addRelation('author', {
+  resolver: UserTC.mongooseResolvers.dataLoader({ lean: true }),
+  //                                ^^^         ^^^
+  //                     autosuggestion for available resolvers and available options  
+  prepareArgs: {
+    // here will be allowed only `_id` key, cause only one this arg is available in `dataLoader` resolver
+    _id: (s) => s.authorId,
+    //          ^^^ source is typed to IPost interface
+  },
+  projection: { authorId: true },
+});
+
+// Describe another relation via `dataLoaderMany`
+PostTC.addRelation('reviewers', {
+  resolver: UserTC.mongooseResolvers.dataLoaderMany({ lean: true }),
+  prepareArgs: {
+    _ids: (s) => s.reviewerIds,
+  },
+  projection: { reviewerIds: true },
+});
+
+// defining schema entrypoints for Query
+schemaComposer.Query.addFields({
+  post: PostTC.mongooseResolvers.findById(),
+  posts: PostTC.mongooseResolvers.findMany(),
+  user: UserTC.mongooseResolvers.findById(),
+  users: UserTC.mongooseResolvers.findMany({ sort: false }),
+});
+
+// defining schema entrypoints for Mutation
+schemaComposer.Query.addFields({
+  postCreate: PostTC.mongooseResolvers.createOne(),
+  userCreate: UserTC.mongooseResolvers.createOne(),
+});
+
+// generating GraphQL schema instance
+const schema = schemaComposer.buildSchema();
+```
+
+### Expose `resolverFactory` for advanced cases of resolver creation
+
+`graphql-compose-mongoose` exposes `resolverFactory` variable which contains all available resolver generators, eg. `resolverFactory.createOne(someMongooseModel, someTC, customizationOpts)`. This resolver generation way unlocks the following scenarios:
+- you have several mongoose models with different databases connection and one TypeComposer, so you can reuse one GraphQL type for using it with different MongoDBs.
+- you have one mongoose model and want to use different GraphQL types (for admins with a full set of fields, and for clients with a reduced set of fields).
+
+The following example demonstrates how to use the second scenario with `ClonedPostTC` type for the reduced set of fields and existing mongoose `PostModel` for making requests to DB:
+
+```ts
+import { resolverFactory } from 'graphql-compose-mongoose';
+import { PostModel, PostTC } from './the-example-above';
+
+const ClonedPostTC = PostTC.clone('ReducedPost');
+ClonedPostTC.getInputTypeComposer().removeField('authorId');
+
+const createPostWithoutAuthor = resolverFactory.createOne(PostModel, ClonedPostTC, { suffix: 'CustomCreate' });
+```
+
+[Issue #274](https://github.com/graphql-compose/graphql-compose-mongoose/issues/274)
 
 ### Mutations got `error: ErrorInterface` field in theirs payload for better error handling
 
@@ -228,7 +371,7 @@ You will receive the following response:
 
 [Issue #248](https://github.com/graphql-compose/graphql-compose-mongoose/issues/248)
 
-## Improvements
+## Enhancements
 
 ### Now `_id` field can be of any type (Int, String, Object)