Merge pull request #7 from OVYA/refactoring

Refactoring + concurrent unit tests + benchmark

Author: NicklasWallgren

README.md

@@ -8,11 +8,16 @@ A simple template engine for writing dynamic SQL queries.
 [![GoDoc](https://godoc.org/github.com/NicklasWallgren/sqlTemplate?status.svg)](https://godoc.org/github.com/NicklasWallgren/sqlTemplate)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/cabd5fbbcde543ec959fb4a3581600ed)](https://app.codacy.com/gh/NicklasWallgren/sqlTemplate?utm_source=github.com&utm_medium=referral&utm_content=NicklasWallgren/sqlTemplate&utm_campaign=Badge_Grade)
 
-Sometimes it can be hard to write comprehensible SQL queries with tools like SQL builders ([squirrel](https://github.com/Masterminds/squirrel)
-or [dbr](https://github.com/gocraft/dbr)), specially dynamic queries with optional statements and joins.
-It can be hard to see the overall cohesive structure of the queries, and the primary goal.
+Sometimes it can be hard to write comprehensible SQL queries with
+tools like SQL builders ([squirrel](https://github.com/Masterminds/squirrel)
+or [dbr](https://github.com/gocraft/dbr)), specially dynamic queries
+with optional statements and joins.
+It can be hard to see the overall cohesive structure of the queries,
+and the primary goal.
 
-The main motivation of this library is to separate the SQL queries from the Go code, and to improve the readability of complex dynamic queries.
+The main motivation of this library is to separate the SQL queries
+from the Go code, and to improve the readability of complex dynamic
+queries.
 
 Check out the API Documentation http://godoc.org/github.com/NicklasWallgren/sqlTemplate
 
@@ -77,17 +82,29 @@ fmt.Printf("query parameters %v\n", tmpl.GetParams())
 ```
 
 ## Unit tests
+
+```bash
+go test -v -race ./pkg
+```
+
+For benchmark :
+
 ```bash
-go test -v -race $(go list ./... | grep -v vendor)
+go test ./pkg -bench=.
 ```
 
 ### Code Guide
 
-We use GitHub Actions to make sure the codebase is consistent (`golangci-lint run`) and continuously tested (`go test -v -race ./pkg`). We try to keep comments at a maximum of 120 characters of length and code at 120.
+We use GitHub Actions to make sure the codebase is consistent
+(`golangci-lint run`) and continuously tested (`go test -v -race
+./pkg`). We try to keep comments at a maximum of 120 characters of
+length and code at 120.
 
 ## Contributing
 
-If you find any problems or have suggestions about this library, please submit an issue. Moreover, any pull request, code review and feedback are welcome.
+If you find any problems or have suggestions about this library,
+please submit an issue. Moreover, any pull request, code review and
+feedback are welcome.
 
 ## Contributors
 - [Nicklas Wallgren](https://github.com/NicklasWallgren)
@@ -97,4 +114,4 @@ If you find any problems or have suggestions about this library, please submit a
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE)

examples/embedded_files/main.go

@@ -11,7 +11,7 @@ import (
 var fs embed.FS
 
 func main() {
-	sqlT := sqlTemplate.NewQueryTemplateEngine()
+	sqlT := sqlTemplate.NewTemplateEngine()
 	if err := sqlT.Register("users", fs, ".tsql"); err != nil {
 		panic(err)
 	}

examples/map_as_param/main.go

@@ -11,7 +11,7 @@ func main() {
 	wd, _ := os.Getwd()
 	fs := os.DirFS(wd + "/examples/map_as_param/queries/users")
 
-	sqlT := sqlTemplate.NewQueryTemplateEngine()
+	sqlT := sqlTemplate.NewTemplateEngine()
 	if err := sqlT.Register("users", fs, ".tsql"); err != nil {
 		panic(err)
 	}

examples/postgresql_placeholder/main.go

@@ -13,7 +13,7 @@ func main() {
 
 	pgPlaceholder := func(_ any, index int) string { return fmt.Sprintf("$%d", index+1) }
 
-	sqlT := sqlTemplate.NewQueryTemplateEngine(sqlTemplate.WithPlaceholderFunc(pgPlaceholder))
+	sqlT := sqlTemplate.NewTemplateEngine(sqlTemplate.WithPlaceholderFunc(pgPlaceholder))
 	if err := sqlT.Register("users", fs, ".tsql"); err != nil {
 		panic(err)
 	}

examples/struct_as_param/main.go

@@ -17,7 +17,7 @@ func main() {
 	wd, _ := os.Getwd()
 	fs := os.DirFS(wd + "/examples/struct_as_param/queries/users")
 
-	sqlT := sqlTemplate.NewQueryTemplateEngine()
+	sqlT := sqlTemplate.NewTemplateEngine()
 	if err := sqlT.Register("users", fs, ".tsql"); err != nil {
 		panic(err)
 	}

pkg/template_binding.go

@@ -0,0 +1,68 @@
+package pkg
+
+type placeholderFunc func(value any, index int) string
+
+func defaultPlaceholderFunc(_ any, _ int) string { return "?" }
+
+type bindingEngine interface {
+	// StoreValue stores the given `value` and return the index order of
+	// the stored value.
+	storeValue(any) int
+	// GetValues get the stored values.
+	getValues() []any
+	// new returns an new instance.
+	new() bindingEngine
+	// SetPlaceholderFunc allows to set custom placeholderFunc.
+	SetPlaceholderFunc(placeholderFunc)
+	// getPlaceholderFunc returns the placeholder function.
+	getPlaceholderFunc() placeholderFunc
+}
+
+// DefaultBindingEngine is a base engine to handle bindings (placeholder "?" for MySQL-like dbe).
+// It can be oveload to provide other type if bindings (placeholder "$i" for PostgreSQL-like dbe).
+type DefaultBindingEngine struct {
+	values          []any
+	index           int
+	placeholderFunc placeholderFunc
+}
+
+func (b *DefaultBindingEngine) new() bindingEngine {
+	newBE := NewBindingEngine()
+	newBE.SetPlaceholderFunc(b.placeholderFunc)
+
+	return newBE
+}
+
+func (b *DefaultBindingEngine) getPlaceholderFunc() placeholderFunc {
+	if b.placeholderFunc == nil {
+		return defaultPlaceholderFunc
+	}
+
+	return b.placeholderFunc
+}
+
+// SetPlaceholderFunc allows to set custom placeholder function.
+func (b *DefaultBindingEngine) SetPlaceholderFunc(placeholderfunc placeholderFunc) {
+	b.placeholderFunc = placeholderfunc
+}
+
+func (b *DefaultBindingEngine) storeValue(value any) int {
+	b.values = append(b.values, value)
+	b.index++
+
+	return b.index - 1
+}
+
+func (b *DefaultBindingEngine) getValues() []any {
+	return b.values
+}
+
+// NewBindingEngine build a binding engine based on the default binding engine.
+func NewBindingEngine() bindingEngine {
+	return &DefaultBindingEngine{values: []any{}, index: 0, placeholderFunc: defaultPlaceholderFunc}
+}
+
+// bind is a dummy function which is never used while executing a template.
+func bind(_ interface{}) string {
+	panic("dummy function which should never be used.")
+}

pkg/template_engine.go

@@ -1,83 +1,95 @@
+// Package pkg is the public lib of SQLTemplate.
+// SQLTemplate is a simple template engine for writing
+// dynamic SQL queries.
 package pkg
 
 import (
+	"bytes"
 	"fmt"
 	"io/fs"
-	"text/template"
+	txtTemplate "text/template"
 )
 
-// QueryTemplateEngine is the interface implemented by types that can parse sql templates.
-type QueryTemplateEngine interface {
-	// Parse parses a sql template and returns the 'QueryTemplate'
-	Parse(namespace string, templateName string) (QueryTemplate, error)
-	// ParseWithValuesFromMap parses a sql template with values from a map and returns the 'QueryTemplate'
-	ParseWithValuesFromMap(namespace string, templateName string, parameters map[string]interface{}) (QueryTemplate, error)
-	// ParseWithValuesFromStruct parses a sql template with values from a struct and returns the 'QueryTemplate'
-	ParseWithValuesFromStruct(namespace string, templateName string, parameters interface{}) (QueryTemplate, error)
-	// Register registers a new namespace by template filesystem and extension
+// TemplateEngine is the interface implemented by types that can parse sql templates.
+type TemplateEngine interface {
+	// Parse parses a sql template and returns the 'Template'.
+	Parse(namespace string, templateName string) (Template, error)
+	// ParseWithValuesFromMap parses a sql template with values from a map and returns the 'Template'.
+	ParseWithValuesFromMap(namespace string, templateName string, parameters map[string]interface{}) (Template, error)
+	// ParseWithValuesFromStruct parses a sql template with values from a struct and returns the 'Template'.
+	ParseWithValuesFromStruct(namespace string, templateName string, parameters interface{}) (Template, error)
+	// Register registers a new namespace by template filesystem and extension.
 	Register(namespace string, filesystem fs.FS, extensions string) error
 }
 
-// QueryTemplate is the interface implemented by types that holds the parsed template sql query context.
-type QueryTemplate interface {
+// QueryTemplateEngine is for backwards compatibility.
+// Deprecated: use TemplateEngine.
+type QueryTemplateEngine = TemplateEngine
+
+// Template is the interface implemented by types that holds the parsed template sql context.
+type Template interface {
 	// GetQuery returns the query containing named values.
 	GetQuery() string
 	// GetParams returns the values in order.
 	GetParams() []interface{}
 }
 
+// QueryTemplate is for backwards compatibility.
+// Deprecated: use Template.
+type QueryTemplate = Template
+
 // Option definition.
-type Option func(*queryTemplateEngine)
+type Option func(*templateEngine)
 
-type queryTemplateEngine struct {
+type templateEngine struct {
 	repository    *repository
 	bindingEngine bindingEngine
 }
 
-type queryTemplate struct {
+type template struct {
 	template string
 	params   []interface{}
 }
 
-func (t queryTemplate) GetQuery() string {
+func (t template) GetQuery() string {
 	return t.template
 }
 
-func (t queryTemplate) GetParams() []interface{} {
+func (t template) GetParams() []interface{} {
 	return t.params
 }
 
 // WithTemplateFunctions creates an Option func to set template functions.
 // nolint:deadcode
-func WithTemplateFunctions(funcMap template.FuncMap) Option {
-	return func(queryTypeEngine *queryTemplateEngine) {
-		queryTypeEngine.repository.addFunctions(funcMap)
+func WithTemplateFunctions(funcMap txtTemplate.FuncMap) Option {
+	return func(templateTypeEngine *templateEngine) {
+		templateTypeEngine.repository.addFunctions(funcMap)
 	}
 }
 
 // WithBindingEngine creates an Option func to set custom binding engine.
 // nolint:deadcode
 func WithBindingEngine(bEngine bindingEngine) Option {
-	return func(queryTypeEngine *queryTemplateEngine) {
-		queryTypeEngine.bindingEngine = bEngine
+	return func(templateTypeEngine *templateEngine) {
+		templateTypeEngine.bindingEngine = bEngine
 	}
 }
 
 // WithPlaceholderFunc creates an Option func to set custom placeholder function.
 // nolint:deadcode
 func WithPlaceholderFunc(placeholderfunc placeholderFunc) Option {
-	return func(queryTypeEngine *queryTemplateEngine) {
-		if queryTypeEngine.bindingEngine == nil {
-			queryTypeEngine.bindingEngine = NewBindingEngine()
+	return func(templateTypeEngine *templateEngine) {
+		if templateTypeEngine.bindingEngine == nil {
+			templateTypeEngine.bindingEngine = NewBindingEngine()
 		}
 
-		queryTypeEngine.bindingEngine.SetPlaceholderFunc(placeholderfunc)
+		templateTypeEngine.bindingEngine.SetPlaceholderFunc(placeholderfunc)
 	}
 }
 
-// NewQueryTemplateEngine returns a new instance of 'QueryTemplateEngine'.
-func NewQueryTemplateEngine(options ...Option) QueryTemplateEngine {
-	templateEngine := &queryTemplateEngine{repository: newRepository(), bindingEngine: nil}
+// NewTemplateEngine returns a new instance of 'TemplateEngine'.
+func NewTemplateEngine(options ...Option) TemplateEngine {
+	templateEngine := &templateEngine{repository: newRepository(), bindingEngine: nil}
 
 	// Apply options if there are any, can overwrite default
 	for _, option := range options {
@@ -87,7 +99,12 @@ func NewQueryTemplateEngine(options ...Option) QueryTemplateEngine {
 	return templateEngine
 }
 
-func (q queryTemplateEngine) Register(namespace string, filesystem fs.FS, ext string) error {
+// Deprecated: use NewTemplateEngine.
+func NewQueryTemplateEngine(options ...Option) TemplateEngine {
+	return NewTemplateEngine(options...)
+}
+
+func (q templateEngine) Register(namespace string, filesystem fs.FS, ext string) error {
 	err := q.repository.add(namespace, filesystem, ext)
 	if err != nil {
 		return fmt.Errorf("could not register the namespace %s %w", namespace, err)
@@ -96,29 +113,59 @@ func (q queryTemplateEngine) Register(namespace string, filesystem fs.FS, ext st
 	return nil
 }
 
-func (q queryTemplateEngine) Parse(namespace string, templateName string) (QueryTemplate, error) {
-	sqlQuery, bindings, err := q.repository.parse(namespace, templateName, nil, q.bindingEngine)
+func (q templateEngine) Parse(namespace string, templateName string) (Template, error) {
+	sqlQuery, bindings, err := q.parse(namespace, templateName, nil)
 	if err != nil {
 		return nil, fmt.Errorf("unable to parse %s for namespace %s %w", templateName, namespace, err)
 	}
 
-	return &queryTemplate{sqlQuery, bindings}, nil
+	return &template{sqlQuery, bindings}, nil
 }
 
-func (q queryTemplateEngine) ParseWithValuesFromMap(namespace string, templateName string, parameters map[string]interface{}) (QueryTemplate, error) {
-	sqlQuery, bindings, err := q.repository.parse(namespace, templateName, parameters, q.bindingEngine)
+func (q templateEngine) ParseWithValuesFromMap(namespace string, templateName string, parameters map[string]interface{}) (Template, error) {
+	sqlQuery, bindings, err := q.parse(namespace, templateName, parameters)
 	if err != nil {
 		return nil, fmt.Errorf("unable to parse %s for namespace %s %w", templateName, namespace, err)
 	}
 
-	return &queryTemplate{sqlQuery, bindings}, nil
+	return &template{sqlQuery, bindings}, nil
 }
 
-func (q queryTemplateEngine) ParseWithValuesFromStruct(namespace string, templateName string, parameters interface{}) (QueryTemplate, error) {
-	sqlQuery, bindings, err := q.repository.parse(namespace, templateName, parameters, q.bindingEngine)
+func (q templateEngine) ParseWithValuesFromStruct(namespace string, templateName string, parameters interface{}) (Template, error) {
+	sqlQuery, bindings, err := q.parse(namespace, templateName, parameters)
 	if err != nil {
 		return nil, fmt.Errorf("unable to parse %s for namespace %s %w", templateName, namespace, err)
 	}
 
-	return &queryTemplate{sqlQuery, bindings}, nil
+	return &template{sqlQuery, bindings}, nil
+}
+
+// parse executes the template and returns the resulting SQL or an error.
+func (q templateEngine) parse(namespace string, name string, data interface{}) (string, []interface{}, error) {
+	tmpl, err := q.repository.getTemplate(namespace)
+	if err != nil {
+		return "", nil, err
+	}
+
+	var bEngine bindingEngine
+
+	// Apply the bind function which stores the values for any placeholder parameters
+	if q.bindingEngine == nil {
+		bEngine = &DefaultBindingEngine{values: []any{}, index: 0, placeholderFunc: defaultPlaceholderFunc}
+	} else {
+		bEngine = q.bindingEngine.new()
+	}
+
+	tmpl.Funcs(txtTemplate.FuncMap{"bind": func(value any) string {
+		index := bEngine.storeValue(value)
+
+		return bEngine.getPlaceholderFunc()(value, index)
+	}})
+
+	var b bytes.Buffer
+	if err := tmpl.ExecuteTemplate(&b, name, data); err != nil {
+		return "", nil, fmt.Errorf("unable to execute template %w", err)
+	}
+
+	return b.String(), bEngine.getValues(), nil
 }