Hooks

About Hooks v1:

Generally, User use Hook will implement the callback method through the operated document. But many operations of Qmgo don't have documents as parameter(like Update method), which we think it's a very concise way.

So the Hook v1 of Qmgo will be different from the "general" Hook implementation:

• The user implements the struct method of Hook, and passes it through options of a specific operation API, then Qmgo automatically do callback.

• Only InsertOne、InsertMany and UpdateWithDocument can do hook without options

• If the Hook operation fails, there is no rollback operation in current version.

Insert Hook

User need to implement struct methods to use Insert Hook：

BeforeInsert() error 
AfterInsert() error

InsertOne

In the InsertOne process

• Implement the Hook method of Insert through a custom struct (User in the following example)

• Pass in options.InsertOneOptions to make Hook work

• If the second parameter doc implement the Hook method, options.InsertOneOptions can be ignore in InsertOne.

• If you use the document User to implement the method and modify the document in BeforeInsert(), the modified document will be inserted into the database

type User struct {
	Name         string    `bson:"name"`
	Age          int       `bson:"age"`
}
func (u *User) BeforeInsert() error {
  fmt.Println("before insert called")
	return nil
}
func (u *User) AfterInsert() error {
  fmt.Println("before insert called")
	return nil
}

u := &User{Name: "Alice", Age: 7}

_, err := cli.InsertOne(context.Background(), u)

// following example also works
// _, err := cli.InsertOne(context.Background(), u, options.InsertOneOptions{
//  InsertHook: u,
// })

InsertMany

In the InsertMany process

• Implement the Hook method of Insert through a custom structure (User in the following example),

• Pass in options.InsertManyOptions to make Hook work.

• If the second parameter docs implement the Hook method, options.InsertManyOptions can be ignore in InsertMany.

• If you use the document User to implement method and modify the document in BeforeInsert(), the modified document will be inserted into the database

• Because multiple documents are inserted, and Hook happens for each document, so Hook will be called back multiple times according to the number of inserted documents

type User struct {
	Name         string    `bson:"name"`
	Age          int       `bson:"age"`
}
func (u *User) BeforeInsert() error {
  fmt.Println("before insert called")
	return nil
}
func (u *User) AfterInsert() error {
  fmt.Println("before insert called")
	return nil
}

u1 := &User{Name: "Lucas", Age: 7}
u2 := &User{Name: "Alice", Age: 7}
us := []*User{u1, u2}

_, err := cli.InsertMany(ctx, us)

// following example also works
// _, err := cli.InsertMany(ctx, us, options.InsertManyOptions{
//  InsertHook: us,
// })

Update Hook

User need to implement struct methods to use Update Hook：

BeforeUpdate() error
AfterUpdate() error

UpdateOne/UpdateAll

• Implement the Hook method of Update through a custom struct (MyUpdateHook in the following example)

• Pass in options.UpdateOptions to make Hook work.

• If you use the document User to directly implement methods and modify the document in the BeforeUpdate(), will not affect the document written in the database.

type MyUpdateHook struct {
	beforeUpdateCount int
	afterUpdateCount  int
}
func (u *MyUpdateHook) BeforeUpdate() error {
	u.beforeUpdateCount++
	return nil
}
func (u *MyUpdateHook) AfterUpdate() error {
	u.afterUpdateCount++
	return nil
}

u := User{Name: "Lucas", Age: 7}
uh := &MyUpdateHook{}
_, err := cli.InsertOne(context.Background(), u)
ast.NoError(err)

err = cli.UpdateOne(ctx, bson.M{"name": "Lucas"}, bson.M{operator.Set: bson.M{"age": 27}}, options.UpdateOptions{
  UpdateHook: uh,
})

cli.UpdateAll(ctx, bson.M{"name": "Lucas"}, bson.M{operator.Set: bson.M{"age": 27}}, options.UpdateOptions{
  UpdateHook: uh,
})

UpdateWithDocument

• Implement the Hook method of Update through a custom struct (User in the following example)

• Pass in options.UpdateOptions to make Hook work.

• If the third parameter doc implement the Hook method, options.UpdateOptions can be ignore in UpdateWithDocument.

• If you use the document User to directly implement methods and modify the document in the BeforeUpdate(), the modified document will be updated into the database.

type User struct {
	Name string `bson:"name"`
	Age  int    `bson:"age"`

	beforeUpdate int
	afterUpdate  int
}

func (u *User) BeforeUpdate() error {
	u.beforeUpdate++
	return nil
}

func (u *User) AfterUpdate() error {
	u.afterUpdate++
	return nil
}

u := &User{}
err = cli.UpdateWithDocument(ctx, bson.M{"name": "Lucas"}, &u)

// following example also works
// err = cli.UpdateWithDocument(ctx, bson.M{"name": "Lucas"}, &u, options.UpdateOptions{
//		UpdateHook: u,
// })

Upsert Hook

User need to implement struct methods to use Upsert Hook：

BeforeUpsert() error
AfterUpsert() error

In the Upsert API

• Implement the Hook method of Upsert through a custom struct (User in the following example)

• Pass in options.UpsertOptions to make Hook work

• If the second parameter doc implement the Hook method, options.UpsertOptions can be ignore in Upsert.

• If you use the document User to implement the method and modify the document in BeforeUpsert(), the modified document will be inserted into the database

type User struct {
	Name         string    `bson:"name"`
	Age          int       `bson:"age"`
}
func (u *User) BeforeUpsert() error {
	return nil
}

func (u *User) AfterUpsert() error {
	return nil
}

u := &User{Name: "Alice", Age: 7}
_, err = cli.Upsert(context.Background(), bson.M{"name": "Lucas"}, u)

// following example also works
// _, err = cli.Upsert(context.Background(), bson.M{"name": "Lucas"}, u, options.UpsertOptions{
//	UpsertHook: myHook,
//})

Remove Hook

User need to implement struct methods to use Remove Hook：

BeforeRemove() error
AfterRemove() error

Remove/RemoveAll

• A custom structure (MyRemoveHook in the following example) implements the Hook method of Remove

• Pass in options.RemoveOptions to make Hook work.

type MyRemoveHook struct {
	beforeCount int
	afterCount  int
}

func (m *MyRemoveHook) BeforeRemove() error {
	m.beforeCount++
	return nil
}

func (m *MyRemoveHook) AfterRemove() error {
	m.afterCount++
	return nil
}

rh := &MyRemoveHook{}
err = cli.Remove(ctx, bson.M{"age": 17}, options.RemoveOptions{
  RemoveHook: rh,
})

rh = &MyRemoveHook{}
_, err = cli.RemoveAll(ctx, bson.M{"age": "7"}, options.RemoveOptions{
  RemoveHook: rh,
})

QueryHook

User need to implement struct methods to use Query Hook：

BeforeQuery() error
AfterQuery() error

Find().One/Find().All()

• A custom struct (MyQueryHook in the following example) implements the Hook method of Query
• Pass in options.FindOptions to make Hook work.

type MyQueryHook struct {
	beforeCount int
	afterCount  int
}

func (q *MyQueryHook) BeforeQuery() error {
	q.beforeCount++
	return nil
}

func (q *MyQueryHook) AfterQuery() error {
	q.afterCount++
	return nil
}

qk := &MyQueryHook{}
err = cli.Find(ctx, bson.M{"age": 17}, options.FindOptions{
  QueryHook: qk,
}).One(ur)

err = cli.Find(ctx, bson.M{"age": 17}, options.FindOptions{
  QueryHook: qh,
}).All(&ur)