Updated for transaction and fully documented

Author: YamiOdymel

README.md

@@ -0,0 +1,97 @@
+# Goshia
+
+Goshia 是採用 [go-gorm/gorm](https://github.com/go-gorm/gorm/) 與 [teacat/rushia](https://github.com/teacat/rushia/) 的私有套件，這能夠以 Gorm（資料庫連線）作為 Rushia（SQL 語法建置函式庫）的執行基底。
+
+## 使用方式
+
+打開終端機並且透過 `go get` 安裝此套件即可，這個套件的版本通常會與 Rushia 相同。
+
+```bash
+$ go get github.com/teacat/goshia/v3
+```
+
+### 初始化
+
+使用 Goshia 之前，需要先初始化一個 Gorm 資料庫連線並最後將其帶入至 `goshia.New(db)`。
+
+```go
+// 初始化 Gorm 至資料庫的連線。
+db, err := gorm.Open(mysql.Open(dsn))
+if err != nil {
+    log.Fatalf(err)
+}
+// 將 Gorm 帶入給 Goshia 並初始化一個輔助函式。
+goshia := goshia.New(db)
+```
+
+### 查詢（Query）
+
+這是最常使用的函式，查詢（如：Select 語法）可以讓 Goshia 將資料直接映射到指定的指針。
+
+```go
+var user User
+err := goshia.Query(rushia.NewQuery("Users").Where("user_id = ?", ColumnUserID, 10).Select(), &user)
+// 等效於：SELECT * FROM Users WHERE `user_id` = ?
+```
+
+### 查詢與計數（QueryCount）
+
+這與 `Query` 的用法相同，但會私底下額外執行一個相同但沒有筆數限制的 SQL 去取得計數筆數。
+
+這個使用時機通常是：希望進行分頁並且需要知道總筆數。由於執行 `LIMIT 1, 10` 諸如此類篩選限制 SQL 會導致沒辦法取得真正的總筆數，
+
+因此需要透過 `QueryCount` 自動額外取得不受限制時的總筆數資料。
+
+```go
+var users []User
+count, err := goshia.Query(rushia.NewQuery("Users").Limit(10, 20).Select(), &users)
+// 等效於：SELECT * FROM Users LIMIT 10, 20
+// 等效於：SELECT COUNT(*) FROM Users
+```
+
+### 執行（Exec）
+
+執行 `DELETE` 或 `UPDATE`…等語法時，可以使用 `Exec` 執行並且取得影響的筆數為何。
+
+```go
+var user User
+affectedRows, err := goshia.Query(rushia.NewQuery("Users").Where("user_id = ?", 30).Update(user))
+// 等效於：UPDATE Users SET ... WHERE `user_id` = ?
+```
+
+### 執行與編號（ExecID）
+
+如果欄位帶有自動遞增且希望在 `INSERT` 插入時取得這個新的遞增值，就可以使用 `ExecID` 來取得這個新的編號。
+
+```go
+var user User
+id, affectedRows, err := goshia.Query(rushia.NewQuery("Users").Insert(user))
+// 等效於：INSERT INTO Users SET ...
+```
+
+### 交易與回溯（Transaction）
+
+若希望初始化一個事務交易（Transaction），正如其名可以直接呼叫 `Transaction` 並在裡面執行 SQL 語法。
+
+如果該處理函式回傳任何 `error` 則會導致 Goshia 自動回溯所有行為。
+
+如果一個 Goshia 不是由 `Transaction` 被建立的而卻呼叫其事務交易函式會直接觸發 `panic`。
+
+除此之外，Goshia 也提供使用 Gorm 的 `Rollback`、`RollbackTo`、`SavePoint`…等函式。
+
+```go
+goshia.Transaction(func (tx *goshia.Goshia) error {
+    _, err := tx.Exec(rushia.NewQuery("Users").Where("user_id = ?", 30).Update(user))
+    // 等效於：UPDATE Users SET ... WHERE `user_id` = ?
+    if err != nil {
+        return err
+    }
+    // 蹦蹦！記得要 Commit！
+    tx.Commit()
+    return nil
+})
+```
+
+### 輔助資料型態
+
+透過 `goshia.Int`、`goshia.Bool` 等函式，可以將一個值轉換成指針作為填補 SQL 的 Nullable 欄位。這個用法正如 [AWS SDK](https://docs.aws.amazon.com/sdk-for-go/api/aws/) 一樣。

go.mod

@@ -1,8 +1,8 @@
-module github.com/teacat/goshia
+module github.com/teacat/goshia/v3
 
 go 1.16
 
 require (
-	github.com/teacat/rushia/v2 v2.0.4
+	github.com/teacat/rushia/v3 v3.0.0
 	gorm.io/gorm v1.21.16
 )

go.sum

@@ -9,8 +9,8 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/teacat/rushia/v2 v2.0.4 h1:LIUBaGYfDJ81eQh+NV0YIPhY8KmI74KoZGWfcJNSJ9c=
-github.com/teacat/rushia/v2 v2.0.4/go.mod h1:DwC5hz+pMv1NihJnlYcIC6NQLaBos6xA6nG7dI5Ldf0=
+github.com/teacat/rushia/v3 v3.0.0 h1:PGsJteCB3yn8BLWb599LqNawGx+/vnOcEqFHxtrf+qA=
+github.com/teacat/rushia/v3 v3.0.0/go.mod h1:hq1jtclK8gQjOw8JCd934rWZjrJgG6JXaoWZRdDjguM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

goshia.go

@@ -1,20 +1,29 @@
 package goshia
 
 import (
-	"reflect"
+	"errors"
 	"time"
 
-	"github.com/teacat/rushia/v2"
+	"github.com/teacat/rushia/v3"
 	"gorm.io/gorm"
 )
 
+var (
+	ErrNotTransaction = errors.New("goshia: processing non-transaction")
+)
+
 // Goshia
 type Goshia struct {
-	Gorm *gorm.DB
+	Gorm          *gorm.DB
+	isTransaction bool
+}
+
+//
+type Transaction struct {
 }
 
-// NewGoshia
-func NewGoshia(g *gorm.DB) *Goshia {
+// New
+func New(g *gorm.DB) *Goshia {
 	return &Goshia{
 		Gorm: g,
 	}
@@ -28,7 +37,7 @@ func (g *Goshia) Query(q *rushia.Query, dest interface{}) error {
 
 // QueryCount
 func (g *Goshia) QueryCount(q *rushia.Query, dest interface{}) (count int, err error) {
-	countQuery, countParams := rushia.Build(q.Copy().ClearLimit())
+	countQuery, countParams := rushia.Build(q.Copy().ClearLimit().Select("COUNT(*)"))
 	if err := g.Gorm.Raw(countQuery, countParams...).Scan(&count).Error; err != nil {
 		return 0, err
 	}
@@ -37,13 +46,16 @@ func (g *Goshia) QueryCount(q *rushia.Query, dest interface{}) (count int, err e
 }
 
 // Exec
-func (g *Goshia) Exec(q *rushia.Query) error {
+func (g *Goshia) Exec(q *rushia.Query) (affectedRows int, err error) {
 	query, params := rushia.Build(q)
-	return g.Gorm.Exec(query, params...).Error
+	result := g.Gorm.Exec(query, params...)
+	affectedRows = int(result.RowsAffected)
+	err = result.Error
+	return
 }
 
 // ExecID
-func (g *Goshia) ExecID(q *rushia.Query) (id int, err error) {
+func (g *Goshia) ExecID(q *rushia.Query) (id int, affectedRows int, err error) {
 	query, params := rushia.Build(q)
 
 	err = g.Gorm.Transaction(func(tx *gorm.DB) error {
@@ -58,37 +70,81 @@ func (g *Goshia) ExecID(q *rushia.Query) (id int, err error) {
 	return
 }
 
-// Interfaces
-func Interfaces(v interface{}) []interface{} {
-	valuesVal := reflect.ValueOf(v)
-	interfaceVals := make([]interface{}, 0)
-	for i := range interfaceVals {
-		interfaceVals[i] = valuesVal.Index(i).Interface()
+// Transaction
+func (g *Goshia) Transaction(handler func(tx *Goshia) error) error {
+	return g.Gorm.Transaction(func(tx *gorm.DB) error {
+		return handler(&Goshia{
+			Gorm:          tx,
+			isTransaction: true,
+		})
+	})
+}
+
+// Rollback
+func (g *Goshia) Rollback() *Goshia {
+	if !g.isTransaction {
+		panic(ErrNotTransaction)
+	}
+	return &Goshia{
+		Gorm:          g.Gorm.Rollback(),
+		isTransaction: true,
+	}
+}
+
+// RollbackTo
+func (g *Goshia) RollbackTo(name string) *Goshia {
+	if !g.isTransaction {
+		panic(ErrNotTransaction)
+	}
+	return &Goshia{
+		Gorm:          g.Gorm.RollbackTo(name),
+		isTransaction: true,
+	}
+}
+
+// Commit
+func (g *Goshia) Commit() *Goshia {
+	if !g.isTransaction {
+		panic(ErrNotTransaction)
+	}
+	return &Goshia{
+		Gorm:          g.Gorm.Commit(),
+		isTransaction: true,
+	}
+}
+
+// SavePoint
+func (g *Goshia) SavePoint(name string) *Goshia {
+	if !g.isTransaction {
+		panic(ErrNotTransaction)
+	}
+	return &Goshia{
+		Gorm:          g.Gorm.SavePoint(name),
+		isTransaction: true,
 	}
-	return interfaceVals
 }
 
-// String
+// String 會回傳一個指針字串，這用來填補 SQL 中的 Nullable 欄位。
 func String(v string) *string {
 	return &v
 }
 
-// Bool
+// Bool 會回傳一個指針布林值，這用來填補 SQL 中的 Nullable 欄位。
 func Bool(v bool) *bool {
 	return &v
 }
 
-// Int
+// Int 會回傳一個指針正整數，這用來填補 SQL 中的 Nullable 欄位。
 func Int(v int) *int {
 	return &v
 }
 
-// Float64
+// Float64 會回傳一個指針浮點數，這用來填補 SQL 中的 Nullable 欄位。
 func Float64(v float64) *float64 {
 	return &v
 }
 
-// Time
+// Time 會回傳一個指針時間，這用來填補 SQL 中的 Nullable 欄位。
 func Time(v time.Time) *time.Time {
 	return &v
 }