diff --git a/doc/md/code-gen.md b/doc/md/code-gen.md index dcb4a3d5f..da1145642 100755 --- a/doc/md/code-gen.md +++ b/doc/md/code-gen.md @@ -115,11 +115,14 @@ go run entgo.io/ent/cmd/ent generate --template --template glob="path More information and examples can be found in the [external templates doc](templates.md). -## Use `entc` As A Package +## Use `entc` as a Package -Another option for running `ent` CLI is to use it as a package as follows: +Another option for running `ent` code generation is to create a file named `ent/entc.go` with the following content, +and then the `ent/generate.go` file to execute it: + +```go title="ent/entc.go" +// +build ignore -```go package main import ( @@ -141,8 +144,13 @@ func main() { } ``` -The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/entcpkg). +```go title="ent/generate.go" +package ent +//go:generate go run -mod=mod entc.go +``` + +The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/entcpkg). ## Schema Description @@ -232,6 +240,60 @@ func EnsureStructTag(name string) gen.Hook { } ``` +## External Dependencies + +In order to extend the generated client and builders under the `ent` package, and inject them external +dependencies as struct fields, use the `entc.Dependency` option in your [`ent/entc.go`](#use-entc-as-a-package) +file: + +```go title="ent/entc.go" {3-12} +func main() { + opts := []entc.Option{ + entc.Dependency( + entc.DependencyType(&http.Client{}), + ), + entc.Dependency( + entc.DependencyName("Writer"), + entc.DependencyTypeInfo(&field.TypeInfo{ + Ident: "io.Writer", + PkgPath: "io", + }), + ), + } + if err := entc.Generate("./schema", &gen.Config{}, opts...); err != nil { + log.Fatalf("running ent codegen: %v", err) + } +} +``` + +Then, use it in your application: + +```go title="example_test.go" {5-6,15-16} +func Example_Deps() { + client, err := ent.Open( + "sqlite3", + "file:ent?mode=memory&cache=shared&_fk=1", + ent.Writer(os.Stdout), + ent.HTTPClient(http.DefaultClient), + ) + if err != nil { + log.Fatalf("failed opening connection to sqlite: %v", err) + } + defer client.Close() + // An example for using the injected dependencies in the generated builders. + client.User.Use(func(next ent.Mutator) ent.Mutator { + return hook.UserFunc(func(ctx context.Context, m *ent.UserMutation) (ent.Value, error) { + _ = m.HTTPClient + _ = m.Writer + return next.Mutate(ctx, m) + }) + }) + // ... +} +``` + +The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/entcpkg). + ## Feature Flags The `entc` package provides a collection of code-generation features that be added or removed using flags. diff --git a/doc/md/faq.md b/doc/md/faq.md index 56019be11..428e0b078 100644 --- a/doc/md/faq.md +++ b/doc/md/faq.md @@ -553,52 +553,8 @@ If your custom fields/methods require additional imports, you can add those impo #### How to extend the generated builders? -In case you want to extend the generated client and add dependencies to all different builders under the `ent` package, -you can use the `"config/{fields,options}/*"` templates as follows: - -```gotemplate -{{/* A template for adding additional config fields/options. */}} -{{ define "config/fields/httpclient" -}} - // HTTPClient field added by a test template. - HTTPClient *http.Client -{{ end }} - -{{ define "config/options/httpclient" }} - // HTTPClient option added by a test template. - func HTTPClient(hc *http.Client) Option { - return func(c *config) { - c.HTTPClient = hc - } - } -{{ end }} -``` - -Then, you can inject this new dependency to your client, and access it in all builders: - -```go -func main() { - client, err := ent.Open( - "sqlite3", - "file:ent?mode=memory&cache=shared&_fk=1", - // Custom config option. - ent.HTTPClient(http.DefaultClient), - ) - if err != nil { - log.Fatal(err) - } - defer client.Close() - ctx := context.Background() - client.User.Use(func(next ent.Mutator) ent.Mutator { - return hook.UserFunc(func(ctx context.Context, m *ent.UserMutation) (ent.Value, error) { - // Access the injected HTTP client here. - _ = m.HTTPClient - return next.Mutate(ctx, m) - }) - }) - // ... -} -``` - +See the *[Injecting External Dependencies](code-gen.md#external-dependencies)* section, or follow the +example on [GitHub](https://github.com/ent/ent/tree/master/examples/entcpkg). #### How to store Protobuf objects in a BLOB column? diff --git a/doc/md/graphql.md b/doc/md/graphql.md index ee76d78b6..7c22758cf 100644 --- a/doc/md/graphql.md +++ b/doc/md/graphql.md @@ -14,7 +14,7 @@ Follow these 3 steps to enable it to your project: 1\. Create a new Go file named `ent/entc.go`, and paste the following content: -```go +```go title="ent/entc.go" // +build ignore package main @@ -40,7 +40,7 @@ func main() { 2\. Edit the `ent/generate.go` file to execute the `ent/entc.go` file: -```go +```go title="ent/generate.go" package ent //go:generate go run -mod=mod entc.go