entc/gen: add support for WithNamed<E> feature-flag (#2792)

* entc/gen: struct fields and methods for NamedEdge api

* entc/gen: generate WithNamedEdge methods for named-edges

* entc/gen: implement eager-loading for named-edges

* entc/gen: simplify eager-loading template

* entc/gen: drop support for unqiue edges in named-based loading

* all: codegen

* doc/website: named-edges feature-flag

* Update doc/md/eager-load.mdx

* Update doc/md/eager-load.mdx

doc/md/eager-load.mdx

@@ -3,6 +3,9 @@ id: eager-load
 title: Eager Loading
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 ## Overview
 
 `ent` supports querying entities with their associations (through their edges). The associated entities
@@ -109,7 +112,78 @@ for _, admin := range admins {
 Each query-builder has a list of methods in the form of `With<E>(...func(<N>Query))` for each of its edges.
 `<E>` stands for the edge name (like, `WithGroups`) and `<N>` for the edge type (like, `GroupQuery`).
  
-Note that, only SQL dialects support this feature.
+Note that only SQL dialects support this feature.
+
+## Named Edges
+
+In some cases there is a need for preloading edges with custom names. For example, a GraphQL query that has two aliases
+referencing the same edge with different arguments. For this situation, Ent provides another API named `WithNamed<E>`
+that can be enabled using the [`namedges`](features.md#named-edges) feature-flag and seamlessly integrated with
+[EntGQL Fields Collection](tutorial-todo-gql-field-collection.md).
+
+<Tabs
+defaultValue="ent"
+values={[
+{label: 'Ent', value: 'ent'},
+{label: 'GraphQL', value: 'graphql'},
+]}>
+<TabItem value="ent">
+
+See the GraphQL tab to learn more about the motivation behind this API.
+
+```go
+posts, err := client.Post.Query().
+    WithNamedComments("published", func(q *ent.CommentQuery) {
+        q.Where(comment.StatusEQ(comment.StatusPublished))
+    })
+    WithNamedComments("draft", func(q *ent.CommentQuery) {
+        q.Where(comment.StatusEQ(comment.StatusDraft))
+    }).
+    Paginate(...)
+
+// Get the preloaded edges by their name:
+for _, p := range posts {
+    published, err := p.Edges.NamedComments("published")
+    if err != nil {
+        return err
+    }
+    draft, err := p.Edges.NamedComments("draft")
+    if err != nil {
+        return err
+    }
+}
+```
+
+</TabItem>
+<TabItem value="graphql">
+
+An example of a GraphQL query that has two aliases referencing the same edge with different arguments.
+
+```graphql
+query {
+  posts {
+    id
+    title
+    published: comments(where: { status: PUBLISHED }) {
+      edges {
+        node {
+          text
+        }
+      }
+    }
+    draft: comments(where: { status: DRAFT }) {
+      edges {
+        node {
+          text
+        }
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
 
 ## Implementation
 

doc/md/features.md

@@ -51,21 +51,7 @@ func main() {
 
 ## List of Features
 
-#### Privacy Layer
-
-The privacy layer allows configuring privacy policy for queries and mutations of entities in the database.
-
-This option can added to a project using the `--feature privacy` flag, and its full documentation exists
-in the [privacy page](privacy.md).
-
-#### EntQL Filtering
-
-The `entql` option provides a generic and dynamic filtering capability at runtime for the different query builders.
-
-This option can be added to a project using the `--feature entql` flag, and more information about it exists
-in the [privacy page](privacy.md#multi-tenancy).
-
-#### Auto-Solve Merge Conflicts
+### Auto-Solve Merge Conflicts
 
 The `schema/snapshot` option tells `entc` (ent codegen) to store a snapshot of the latest schema in an internal package,
 and use it to automatically solve merge conflicts when user's schema can't be built.
@@ -73,7 +59,28 @@ and use it to automatically solve merge conflicts when user's schema can't be bu
 This option can be added to a project using the `--feature schema/snapshot` flag, but please see
 [ent/ent/issues/852](https://github.com/ent/ent/issues/852) to get more context about it.
 
-#### Schema Config
+### Privacy Layer
+
+The privacy layer allows configuring privacy policy for queries and mutations of entities in the database.
+
+This option can be added to a project using the `--feature privacy` flag, and you can learn more about in the
+[privacy](privacy.md) documentation.
+
+### EntQL Filtering
+
+The `entql` option provides a generic and dynamic filtering capability at runtime for the different query builders.
+
+This option can be added to a project using the `--feature entql` flag, and you can learn more about in the
+[privacy](privacy.md#multi-tenancy) documentation.
+
+### Named Edges
+
+The `namedges` option provides an API for preloading edges with custom names.
+
+This option can be added to a project using the `--feature namedges` flag, and you can learn more about in the
+[Eager Loading](eager-load.mdx) documentation.
+
+### Schema Config
 
 The `sql/schemaconfig` option lets you pass alternate SQL database names to models. This is useful when your models don't all live under one database and are spread out across different schemas.
 
@@ -88,7 +95,7 @@ c.User.Query().All(ctx) // SELECT * FROM `usersdb`.`users`
 c.Car.Query().All(ctx) 	// SELECT * FROM `carsdb`.`cars`
 ```
 
-#### Row-level Locks
+### Row-level Locks
 
 The `sql/lock` option lets configure row-level locking using the SQL `SELECT ... FOR {UPDATE | SHARE}` syntax.
 
@@ -114,7 +121,7 @@ tx.Pet.Query().
 	Only(ctx)
 ```
 
-#### Custom SQL Modifiers
+### Custom SQL Modifiers
 
 The `sql/modifier` option lets add custom SQL modifiers to the builders and mutate the statements before they are executed.
 
@@ -245,7 +252,7 @@ ORDER BY
     `groups`.`id` ASC
 ```
 
-#### SQL Raw API
+### SQL Raw API
 
 The `sql/execquery` option allows executing statements using the `ExecContext`/`QueryContext` methods of the underlying
 driver. For full documentation, see: [DB.ExecContext](https://pkg.go.dev/database/sql#DB.ExecContext), and
@@ -276,7 +283,7 @@ Statements executed using `ExecContext`/`QueryContext` do not go through Ent, an
 application such as hooks, privacy (authorization), and validators.
 :::
 
-#### Upsert
+### Upsert
 
 The `sql/upsert` option lets configure upsert and bulk-upsert logic using the SQL `ON CONFLICT` / `ON DUPLICATE KEY`
 syntax. For full documentation, go to the [Upsert API](crud.md#upsert-one).