ent: initial support for edge schemas

[a8m]

Edge Schema

The Through option allows setting intermediate entity schemas for edges of type M2M. We name such schemas "edge schemas".
Using this option, users can expose relationships in their API, store additional fields on their edges/relationships,
apply CRUD operations, and set hooks and privacy policy on them.

User Friendships Example

In the following example, we demonstrate how to model the friendship between two users using edge schema with the two
required fields of the relationship (user_id and friend_id) and an additional field named created_at that its value
is automatically set on creation.

// User holds the schema definition for the User entity.
type User struct {
	ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("name").
			Default("Unknown"),
	}
}

// Edges of the User.
func (User) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("friends", User.Type).
			Through("friendships", Friendship.Type),
	}
}

// Friendship holds the edge schema definition of the Friendship relationship.
type Friendship struct {
	ent.Schema
}

// Fields of the Friendship.
func (Friendship) Fields() []ent.Field {
	return []ent.Field{
		field.Time("created_at").
			Default(time.Now),
		field.Int("user_id"),
		field.Int("friend_id"),
	}
}

// Edges of the Friendship.
func (Friendship) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("user", User.Type).
			Required().
			Unique().
			Field("user_id"),
		edge.To("friend", User.Type).
			Required().
			Unique().
			Field("friend_id"),
	}
}

Notes

• Similar to entity schemas, the ID field is automatically generated for edge schemas if not stated otherwise.
• Edge schema cannot be used by more than one relationship (an edge and its back-reference).
• The user_id and friend_id edge-fields are required in the edge schema as they are composing the relationship.:::

User Likes Example

In the following example, we demonstrate how to model a system where users can "like" tweets, and the timestamp of when
exactly the "like" has happened is stored in the database. i.e. store additional fields on the edge.

// User holds the schema definition for the User entity.
type User struct {
	ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("name").
			Default("Unknown"),
	}
}

// Edges of the User.
func (User) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("liked_tweets", Tweet.Type).
			Through("likes", Like.Type),
	}
}

// Tweet holds the schema definition for the Tweet entity.
type Tweet struct {
	ent.Schema
}

// Fields of the Tweet.
func (Tweet) Fields() []ent.Field {
	return []ent.Field{
		field.Text("text"),
	}
}

// Edges of the Tweet.
func (Tweet) Edges() []ent.Edge {
	return []ent.Edge{
		edge.From("liked_users", User.Type).
			Ref("liked_tweets").
			Through("likes", Like.Type),
	}
}

// Like holds the edge schema definition for the Like edge.
type Like struct {
	ent.Schema
}

func (Like) Annotations() []schema.Annotation {
	return []schema.Annotation{
		field.ID("user_id", "tweet_id"),
	}
}

// Fields of the Like.
func (Like) Fields() []ent.Field {
	return []ent.Field{
		field.Time("liked_at").
			Default(time.Now),
		field.Int("user_id"),
		field.Int("tweet_id"),
	}
}

// Edges of the Like.
func (Like) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("user", User.Type).
			Unique().
			Required().
			Field("user_id"),
		edge.To("tweet", Tweet.Type).
			Unique().
			Required().
			Field("tweet_id"),
	}
}

Notes

Since the field.ID annotation is used for configuring a composite identifier (i.e. primary key) for the edge schema,
the ID field will not be generated along with any of its builder methods. e.g. Get, OnlyID, etc.

[fgm]

That looks really convenient. Just one small thing: it seems the Fields() could be implied since they are listed in the Edge(), so they could be created by default if not defined, making the definition more compact.

[a8m]

Thanks for the feedback @fgm. For now, I decided to go with the "explicit way" as mentioned in #1949 (comment). Let's give this feature some time, get some feedback on it, and may improve it in the near future.

Appreciate your help in #1949 🙏