feat: implement prototype

Author: tmzane

LICENSE

@@ -0,0 +1,28 @@
+.POSIX:
+.SUFFIXES:
+
+all: test lint
+
+test:
+	go test -race -shuffle=on -cover ./...
+
+test/cover:
+	go test -race -shuffle=on -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out
+
+lint:
+	golangci-lint run
+
+tidy:
+	go mod tidy
+
+generate:
+	go generate ./...
+
+# run `make pre-commit` once to install the hook.
+pre-commit: .git/hooks/pre-commit test lint tidy generate
+	git diff --exit-code
+
+.git/hooks/pre-commit:
+	echo "make pre-commit" > .git/hooks/pre-commit
+	chmod +x .git/hooks/pre-commit

Makefile

@@ -0,0 +1,12 @@
+# queries
+
+[WIP] Convenience helpers for working with SQL queries.
+
+## Features
+
+- `Builder`: an `fmt`-based query builder with an API similar to `strings.Builder`.
+- `Scanner`: a query-to-struct scanner, a lightweight version of `sqlx` with a smaller and stricter API.
+
+## Usage
+
+See [examples](example_test.go).

README.md

@@ -0,0 +1,67 @@
+package queries
+
+import (
+	"fmt"
+	"slices"
+	"strings"
+)
+
+type Builder struct {
+	query        strings.Builder
+	Args         []any
+	counter      int
+	placeholders []rune
+}
+
+func (b *Builder) Appendf(format string, args ...any) {
+	a := make([]any, len(args))
+	for i, arg := range args {
+		a[i] = argument{value: arg, builder: b}
+	}
+	fmt.Fprintf(&b.query, format, a...)
+}
+
+func (b *Builder) String() string {
+	slices.Sort(b.placeholders)
+	if len(slices.Compact(b.placeholders)) > 1 {
+		panic(fmt.Sprintf("queries.Builder: bad query: %s placeholders used", string(b.placeholders)))
+	}
+
+	s := b.query.String()
+	if strings.Contains(s, "%!") {
+		// fmt silently recovers panics and writes them to the output.
+		// we want panics to be loud, so we find and rethrow them.
+		// see also https://github.com/golang/go/issues/28150.
+		panic(fmt.Sprintf("queries.Builder: bad query: %s", s))
+	}
+
+	return s
+}
+
+type argument struct {
+	value   any
+	builder *Builder
+}
+
+// Format implements the [fmt.Formatter] interface.
+func (a argument) Format(s fmt.State, verb rune) {
+	switch verb {
+	case '?', '$', '@':
+		a.builder.Args = append(a.builder.Args, a.value)
+		a.builder.placeholders = append(a.builder.placeholders, verb)
+	}
+
+	switch verb {
+	case '?': // MySQL, SQLite
+		fmt.Fprint(s, "?")
+	case '$': // PostgreSQL
+		a.builder.counter++
+		fmt.Fprintf(s, "$%d", a.builder.counter)
+	case '@': // MSSQL
+		a.builder.counter++
+		fmt.Fprintf(s, "@p%d", a.builder.counter)
+	default:
+		format := fmt.FormatString(s, verb)
+		fmt.Fprintf(s, format, a.value)
+	}
+}

assert/EF/alias.go

@@ -0,0 +1,91 @@
+package queries_test
+
+import (
+	"testing"
+
+	"go-simpler.org/queries"
+	"go-simpler.org/queries/assert"
+	. "go-simpler.org/queries/assert/EF"
+)
+
+//go:generate go run -tags=cp go-simpler.org/assert/cmd/cp@v0.9.0
+
+func TestBuilder(t *testing.T) {
+	var qb queries.Builder
+	qb.Appendf("select %s from tbl where 1=1", "*")
+	qb.Appendf(" and foo = %$", 1)
+	qb.Appendf(" and bar = %$", 2)
+	qb.Appendf(" and baz = %$", 3)
+
+	assert.Equal[E](t, qb.String(), "select * from tbl where 1=1 and foo = $1 and bar = $2 and baz = $3")
+	assert.Equal[E](t, qb.Args, []any{1, 2, 3})
+}
+
+func TestBuilder_placeholders(t *testing.T) {
+	tests := map[string]struct {
+		format string
+		query  string
+	}{
+		"?": {
+			format: "select * from tbl where foo = %? and bar = %? and baz = %?",
+			query:  "select * from tbl where foo = ? and bar = ? and baz = ?",
+		},
+		"$": {
+			format: "select * from tbl where foo = %$ and bar = %$ and baz = %$",
+			query:  "select * from tbl where foo = $1 and bar = $2 and baz = $3",
+		},
+		"@": {
+			format: "select * from tbl where foo = %@ and bar = %@ and baz = %@",
+			query:  "select * from tbl where foo = @p1 and bar = @p2 and baz = @p3",
+		},
+	}
+
+	for name, tt := range tests {
+		t.Run(name, func(t *testing.T) {
+			var qb queries.Builder
+			qb.Appendf(tt.format, 1, 2, 3)
+			assert.Equal[E](t, qb.String(), tt.query)
+			assert.Equal[E](t, qb.Args, []any{1, 2, 3})
+		})
+	}
+}
+
+func TestBuilder_badQuery(t *testing.T) {
+	tests := map[string]struct {
+		appends  func(*queries.Builder)
+		panicMsg string
+	}{
+		"bad verb": {
+			appends: func(qb *queries.Builder) {
+				qb.Appendf("select %d from tbl", "foo")
+			},
+			panicMsg: "queries.Builder: bad query: select %!d(string=foo) from tbl",
+		},
+		"too few arguments": {
+			appends: func(qb *queries.Builder) {
+				qb.Appendf("select %s from tbl")
+			},
+			panicMsg: "queries.Builder: bad query: select %!s(MISSING) from tbl",
+		},
+		"too many arguments": {
+			appends: func(qb *queries.Builder) {
+				qb.Appendf("select %s from tbl", "foo", "bar")
+			},
+			panicMsg: "queries.Builder: bad query: select foo from tbl%!(EXTRA queries.argument=bar)",
+		},
+		"different placeholders": {
+			appends: func(qb *queries.Builder) {
+				qb.Appendf("select * from tbl where foo = %? and bar = %$ and baz = %@", 1, 2, 3)
+			},
+			panicMsg: "queries.Builder: bad query: $?@ placeholders used",
+		},
+	}
+
+	for name, tt := range tests {
+		t.Run(name, func(t *testing.T) {
+			var qb queries.Builder
+			tt.appends(&qb)
+			assert.Panics[E](t, func() { _ = qb.String() }, tt.panicMsg)
+		})
+	}
+}

assert/assert.go

@@ -0,0 +1,62 @@
+// nolint (WIP)
+package queries_test
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"os"
+	"os/signal"
+	"strings"
+	"time"
+
+	"go-simpler.org/queries"
+	// <database driver of your choice>
+)
+
+func main() {
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer cancel()
+
+	if err := run(ctx); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context) error {
+	db, err := sql.Open("<driver name>", "<connection string>")
+	if err != nil {
+		return err
+	}
+
+	columns := []string{"first_name", "last_name"}
+	if true {
+		columns = append(columns, "created_at")
+	}
+
+	var qb queries.Builder
+	qb.Appendf("select %s from users", strings.Join(columns, ", "))
+	if true {
+		qb.Appendf(" where created_at >= %$", time.Date(2024, time.January, 1, 0, 0, 0, 0, time.Local))
+	}
+
+	// select first_name, last_name, created_at from users where created_at >= $1
+	rows, err := db.QueryContext(ctx, qb.String(), qb.Args...)
+	if err != nil {
+		return err
+	}
+	defer rows.Close()
+
+	var users []struct {
+		FirstName string    `sql:"first_name"`
+		LastName  string    `sql:"last_name"`
+		CreatedAt time.Time `sql:"created_at"`
+	}
+	if err := queries.ScanAll(&users, rows); err != nil {
+		return err
+	}
+
+	fmt.Println(users)
+	return nil
+}

builder.go

@@ -0,0 +1,3 @@
+module go-simpler.org/queries
+
+go 1.18