fix #237: add option NoExpand to control default field "expand" behavior

Author: huandu

README.md

@@ -272,6 +272,7 @@ type ATable struct {
     unexported int                                       // Unexported field is not visible to Struct.
     Quoted     string `db:"quoted" fieldopt:"withquote"` // Add quote to the field using back quote or double quote. See `Flavor#Quote`.
     Empty      uint   `db:"empty" fieldopt:"omitempty"`  // Omit the field in UPDATE if it is a nil or zero value.
+    Expanded   Meta   `db:"expanded" fieldopt:"expand"`  // Force a nested struct to expand even when sqlbuilder.NoExpand is true.
     Payload    Meta   `db:"payload" fieldopt:"noexpand"` // Treat a nested struct as one column instead of expanding it.
 
     // The `omitempty` can be written as a function.
@@ -284,7 +285,7 @@ type ATable struct {
 }
 ```
 
-If a field is itself a struct and has a `db` tag, `Struct` treats that tag as a database alias and expands the nested fields. This is useful for `JOIN` projections built from reusable structs.
+If a field is itself a struct and has a `db` tag, `Struct` treats that tag as a database alias and expands the nested fields by default. This is useful for `JOIN` projections built from reusable structs.
 
 ```go
 type Post struct {
@@ -312,6 +313,27 @@ fmt.Println(sql)
 // SELECT post.id, post.text, comment.body FROM posts post JOIN comments comment ON post.id = comment.post_id
 ```
 
+Set `sqlbuilder.NoExpand = true` before first use of a `Struct` to keep tagged nested structs as a single column by default. When the flag is enabled, add `fieldopt:"expand"` to opt a specific field back into expansion.
+
+```go
+type Payload struct {
+    Key string `json:"key"`
+}
+
+type Row struct {
+    Payload Payload `db:"payload"`
+    Post    Post    `db:"post" fieldopt:"expand"`
+}
+
+sqlbuilder.NoExpand = true
+st := sqlbuilder.NewStruct(new(Row))
+
+fmt.Println(st.Columns())
+
+// Output:
+// [payload post.id post.text]
+```
+
 If a nested struct should stay as a single column, add `fieldopt:"noexpand"` to opt out of the automatic expansion. This is useful for JSON columns scanned into Go structs by the database driver.
 
 ```go

struct.go

@@ -21,16 +21,23 @@ var (
 	FieldTag = "fieldtag"
 
 	// FieldOpt is the options for a struct field.
+	// Supported options include withquote, omitempty, expand, and noexpand.
 	// As db column can contain "," in theory, field options should be provided in a separated tag.
 	FieldOpt = "fieldopt"
 
 	// FieldAs is the column alias (AS) for a struct field.
 	FieldAs = "fieldas"
+
+	// NoExpand changes the default behavior for tagged nested struct fields.
+	// When true, tagged nested structs stay as a single column unless fieldopt:"expand" is set.
+	// Set it before first use of a Struct if that Struct should use the non-expanding default.
+	NoExpand = false
 )
 
 const (
 	fieldOptWithQuote = "withquote"
 	fieldOptOmitEmpty = "omitempty"
+	fieldOptExpand    = "expand"
 	fieldOptNoExpand  = "noexpand"
 
 	optName   = "optName"

struct_test.go

@@ -403,6 +403,97 @@ func TestStructTaggedNestedFieldNoExpand(t *testing.T) {
 	a.Equal(addrs[1], &scanned.LiabVar)
 }
 
+func TestStructTaggedNestedFieldDisableExpand(t *testing.T) {
+	type varRec struct {
+		ChnlPH string `db:"ph"`
+		ExpVK  int64  `db:"vk"`
+	}
+
+	type decRec struct {
+		DecID   string `db:"dec_id"`
+		LiabVar varRec `db:"liab_var"`
+	}
+
+	a := assert.New(t)
+	old := NoExpand
+	NoExpand = true
+	defer func() {
+		NoExpand = old
+	}()
+
+	st := NewStruct(new(decRec)).For(PostgreSQL)
+	rec := &decRec{
+		DecID:   "dec-1",
+		LiabVar: varRec{ChnlPH: "ph", ExpVK: 7},
+	}
+
+	selectSQL, selectArgs := st.SelectFrom("decs d").Build()
+	a.Equal(selectSQL, "SELECT d.dec_id, d.liab_var FROM decs d")
+	a.Equal(selectArgs, nil)
+	a.Equal(st.Columns(), []string{"dec_id", "liab_var"})
+	a.Equal(st.Values(rec), []interface{}{rec.DecID, rec.LiabVar})
+
+	updateSQL, updateArgs := st.Update("decs", rec).Build()
+	a.Equal(updateSQL, "UPDATE decs SET dec_id = $1, liab_var = $2")
+	a.Equal(updateArgs, []interface{}{rec.DecID, rec.LiabVar})
+
+	insertSQL, insertArgs := st.InsertInto("decs", rec).Build()
+	a.Equal(insertSQL, "INSERT INTO decs (dec_id, liab_var) VALUES ($1, $2)")
+	a.Equal(insertArgs, []interface{}{rec.DecID, rec.LiabVar})
+
+	var scanned decRec
+	addrs := st.Addr(&scanned)
+	a.Equal(len(addrs), 2)
+	a.Equal(addrs[0], &scanned.DecID)
+	a.Equal(addrs[1], &scanned.LiabVar)
+}
+
+func TestStructTaggedNestedFieldExpandOverridesNoExpand(t *testing.T) {
+	type varRec struct {
+		ChnlPH string `db:"ph"`
+		ExpVK  int64  `db:"vk"`
+	}
+
+	type decRec struct {
+		DecID   string `db:"dec_id"`
+		LiabVar varRec `db:"liab_var" fieldopt:"expand"`
+	}
+
+	a := assert.New(t)
+	old := NoExpand
+	NoExpand = true
+	defer func() {
+		NoExpand = old
+	}()
+
+	st := NewStruct(new(decRec)).For(PostgreSQL)
+	rec := &decRec{
+		DecID:   "dec-1",
+		LiabVar: varRec{ChnlPH: "ph", ExpVK: 7},
+	}
+
+	selectSQL, selectArgs := st.SelectFrom("decs d").Build()
+	a.Equal(selectSQL, "SELECT d.dec_id, liab_var.ph, liab_var.vk FROM decs d")
+	a.Equal(selectArgs, nil)
+	a.Equal(st.Columns(), []string{"dec_id", "liab_var.ph", "liab_var.vk"})
+	a.Equal(st.Values(rec), []interface{}{rec.DecID, rec.LiabVar.ChnlPH, rec.LiabVar.ExpVK})
+
+	updateSQL, updateArgs := st.Update("decs", rec).Build()
+	a.Equal(updateSQL, "UPDATE decs SET dec_id = $1, liab_var.ph = $2, liab_var.vk = $3")
+	a.Equal(updateArgs, []interface{}{rec.DecID, rec.LiabVar.ChnlPH, rec.LiabVar.ExpVK})
+
+	insertSQL, insertArgs := st.InsertInto("decs", rec).Build()
+	a.Equal(insertSQL, "INSERT INTO decs (dec_id, liab_var) VALUES ($1, $2)")
+	a.Equal(insertArgs, []interface{}{rec.DecID, rec.LiabVar})
+
+	var scanned decRec
+	addrs := st.Addr(&scanned)
+	a.Equal(len(addrs), 3)
+	a.Equal(addrs[0], &scanned.DecID)
+	a.Equal(addrs[1], &scanned.LiabVar.ChnlPH)
+	a.Equal(addrs[2], &scanned.LiabVar.ExpVK)
+}
+
 func TestStructInsertIntoAnonymousFieldHasNoPrefix(t *testing.T) {
 	type embedded struct {
 		ID   string `db:"id"`
@@ -525,6 +616,38 @@ const (
 	OrderStatePaid
 )
 
+func ExampleNoExpand() {
+	type Post struct {
+		ID   string `db:"id"`
+		Text string `db:"text"`
+	}
+
+	type DefaultRow struct {
+		Post Post `db:"post"`
+	}
+
+	type ExpandedRow struct {
+		Post Post `db:"post" fieldopt:"expand"`
+	}
+
+	old := NoExpand
+	defer func() {
+		NoExpand = old
+	}()
+
+	NoExpand = false
+	fmt.Println(NewStruct(new(DefaultRow)).Columns())
+
+	NoExpand = true
+	fmt.Println(NewStruct(new(DefaultRow)).Columns())
+	fmt.Println(NewStruct(new(ExpandedRow)).Columns())
+
+	// Output:
+	// [post.id post.text]
+	// [post]
+	// [post.id post.text]
+}
+
 func ExampleStruct_useStructAsORM() {
 	// Suppose we defined following type for user db.
 	type User struct {

structfields.go

@@ -42,10 +42,18 @@ type structField struct {
 	omitEmptyTags omitEmptyTagMap
 }
 
+type structFieldExpandMode uint8
+
+const (
+	structFieldExpandDefault structFieldExpandMode = iota
+	structFieldExpandEnabled
+	structFieldExpandDisabled
+)
+
 type structFieldOptions struct {
 	isQuoted      bool
 	omitEmptyTags omitEmptyTagMap
-	noExpand      bool
+	expandMode    structFieldExpandMode
 }
 
 type structFieldsParser func() *structFields
@@ -182,8 +190,11 @@ func parseStructFieldOptions(field reflect.StructField) structFieldOptions {
 		case fieldOptWithQuote:
 			fieldOpts.isQuoted = true
 
+		case fieldOptExpand:
+			fieldOpts.expandMode = structFieldExpandEnabled
+
 		case fieldOptNoExpand:
-			fieldOpts.noExpand = true
+			fieldOpts.expandMode = structFieldExpandDisabled
 		}
 	}
 
@@ -223,7 +234,19 @@ func shouldExpandAnonymousStructField(t reflect.Type) bool {
 }
 
 func shouldExpandTaggedStructField(t reflect.Type, dbtag string, fieldOpts structFieldOptions) bool {
-	return dbtag != "" && !fieldOpts.noExpand && canExpandStructType(t)
+	if dbtag == "" || !canExpandStructType(t) {
+		return false
+	}
+
+	switch fieldOpts.expandMode {
+	case structFieldExpandEnabled:
+		return true
+
+	case structFieldExpandDisabled:
+		return false
+	}
+
+	return !NoExpand
 }
 
 func canExpandStructType(t reflect.Type) bool {