test(example): layered SQLite API sample app (ports & adapters)

go.mod

@@ -10,5 +10,6 @@ require (
 require (
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	golang.org/x/sync v0.21.0 // indirect
 	golang.org/x/text v0.29.0 // indirect
 )

go.sum

@@ -18,8 +18,7 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
-golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
 golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
 golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

go.work

@@ -0,0 +1,6 @@
+go 1.25.0
+
+use (
+	.
+	./testdata/example
+)

go.work.sum

@@ -0,0 +1,9 @@
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/stretchr/objx v0.1.0 h1:4G4v2dO3VZwixGIRoQ5Lfboy6nUhCyYzaqnIAPPhYs4=
+golang.org/x/mod v0.27.0 h1:kb+q2PyFnEADO2IEF935ehFUXlWiNjJWtRNgBLSfbxQ=
+golang.org/x/mod v0.27.0/go.mod h1:rWI627Fq0DEoudcK+MBkNkCe0EetEaDSwJJkCcjpazc=
+golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
+golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

testdata/example/go.mod

@@ -0,0 +1,25 @@
+module github.com/mpyw/bisql/example
+
+go 1.25.0
+
+require (
+	github.com/mpyw/bisql v0.0.0-00010101000000-000000000000
+	github.com/samber/lo v1.53.0
+	modernc.org/sqlite v1.56.0
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/expr-lang/expr v1.17.8 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
+	modernc.org/libc v1.74.4 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+)
+
+replace github.com/mpyw/bisql => ../..

testdata/example/go.sum

@@ -0,0 +1,62 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/expr-lang/expr v1.17.8 h1:W1loDTT+0PQf5YteHSTpju2qfUfNoBt4yw9+wOEU9VM=
+github.com/expr-lang/expr v1.17.8/go.mod h1:8/vRC7+7HBzESEqt5kKpYXxrxkr31SaO8r40VO/1IT4=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
+github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/samber/lo v1.53.0 h1:t975lj2py4kJPQ6haz1QMgtId2gtmfktACxIXArw3HM=
+github.com/samber/lo v1.53.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+modernc.org/cc/v4 v4.29.1 h1:MKgdCV3WykTSPqpVrnxdEDS0HEd2FHpKZDzxzU5LyeI=
+modernc.org/cc/v4 v4.29.1/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.34.6 h1:sBgfIwyN0TQ9C5hwIeuqyeAKyMWnbvj2fvpF4L11uzU=
+modernc.org/ccgo/v4 v4.34.6/go.mod h1:SZ8YcN9NG7XVsQYdm6jYBvi8PQP1qi+kqB6OhjqI3Fk=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.4 h1:2g65LGVSmFQrXeITAw97x7hCRvZFcyE1uDP+7Vng7JI=
+modernc.org/gc/v3 v3.1.4/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k=
+modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.56.0 h1:/D8e2RfFqoy/Zc6PuC76U28zFwmI/sYx1Kjm4yEn9e0=
+modernc.org/sqlite v1.56.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

testdata/example/src/app/app.go

@@ -0,0 +1,40 @@
+// Package app is the application core. App aggregates the query ports — received via manual
+// dependency injection in cmd/serve — behind the methods the presentation layer calls. The logic
+// here is deliberately thin: it is the seam where validation, authorization, and orchestration
+// would live.
+package app
+
+import (
+	"context"
+
+	"github.com/mpyw/bisql/example/src/app/query"
+)
+
+// App is the application service, wiring the query ports behind request methods.
+type App struct {
+	users    query.UserSearcher
+	activity query.ActivityReporter
+	writer   query.AuditLogWriter
+	lookup   query.AuditLogLookup
+}
+
+// New wires the query ports into an App (manual DI).
+func New(users query.UserSearcher, activity query.ActivityReporter, writer query.AuditLogWriter, lookup query.AuditLogLookup) *App {
+	return &App{users: users, activity: activity, writer: writer, lookup: lookup}
+}
+
+func (a *App) SearchUsers(ctx context.Context, in query.SearchUsersInput) ([]query.Row, error) {
+	return a.users.SearchUsers(ctx, in)
+}
+
+func (a *App) ReportActivity(ctx context.Context, in query.ActivityReportInput) ([]query.Row, error) {
+	return a.activity.ReportActivity(ctx, in)
+}
+
+func (a *App) AppendAuditLogs(ctx context.Context, events []query.AuditEvent) (int64, error) {
+	return a.writer.AppendAuditLogs(ctx, events)
+}
+
+func (a *App) LookupAuditLogs(ctx context.Context, keys []query.AuditKey) ([]query.Row, error) {
+	return a.lookup.LookupAuditLogs(ctx, keys)
+}

testdata/example/src/app/infrastructure/query/activity_report.go

@@ -0,0 +1,21 @@
+package query
+
+import (
+	"context"
+
+	"github.com/samber/lo"
+
+	port "github.com/mpyw/bisql/example/src/app/query"
+)
+
+// ReportActivity aggregates audit events per department over an optional date window.
+func (q *Queries) ReportActivity(ctx context.Context, in port.ActivityReportInput) ([]port.Row, error) {
+	params := lo.OmitByValues(map[string]any{
+		"since": in.Since,
+		"until": in.Until,
+	}, []any{""})
+	if len(in.Actions) > 0 {
+		params["actions"] = lo.ToAnySlice(in.Actions)
+	}
+	return q.rows(ctx, "audit_logs/activity-report.sql", params)
+}

testdata/example/src/app/infrastructure/query/audit_log.go

@@ -0,0 +1,35 @@
+package query
+
+import (
+	"context"
+
+	"github.com/samber/lo"
+
+	port "github.com/mpyw/bisql/example/src/app/query"
+)
+
+// AppendAuditLogs inserts a batch of events with one round trip (bulk-insert.sql: a zero-row
+// seed plus one `union all select` per event).
+func (q *Queries) AppendAuditLogs(ctx context.Context, events []port.AuditEvent) (int64, error) {
+	rows := lo.Map(events, func(e port.AuditEvent, _ int) any {
+		return map[string]any{"userId": e.UserID, "action": e.Action}
+	})
+	stmt, err := q.build("audit_logs/bulk-insert.sql", map[string]any{"events": rows})
+	if err != nil {
+		return 0, err
+	}
+	res, err := q.db.ExecContext(ctx, stmt.SQL, stmt.Args...)
+	if err != nil {
+		return 0, err
+	}
+	return res.RowsAffected()
+}
+
+// LookupAuditLogs fetches rows for a set of composite (user_id, action) keys (find-by-keys.sql:
+// a row-value IN over a union-all subquery).
+func (q *Queries) LookupAuditLogs(ctx context.Context, keys []port.AuditKey) ([]port.Row, error) {
+	rows := lo.Map(keys, func(k port.AuditKey, _ int) any {
+		return map[string]any{"userId": k.UserID, "action": k.Action}
+	})
+	return q.rows(ctx, "audit_logs/find-by-keys.sql", map[string]any{"keys": rows})
+}

testdata/example/src/app/infrastructure/query/query.go

@@ -0,0 +1,88 @@
+// Package query implements the app/query ports over a *sql.DB, building each statement from the
+// embedded bisql templates (SQLite dialect). The .sql templates live under sql/, organized by
+// domain, with reusable fragments under a fragment/ subdirectory pulled in via @include.
+package query
+
+import (
+	"context"
+	"database/sql"
+	"embed"
+	"io/fs"
+
+	"github.com/samber/lo"
+
+	"github.com/mpyw/bisql"
+	"github.com/mpyw/bisql/dialect"
+	port "github.com/mpyw/bisql/example/src/app/query"
+)
+
+//go:embed sql
+var embedded embed.FS
+
+// templates is the query tree rooted at sql/, so a name like "users/search.sql" resolves and its
+// @include fragments resolve from the same FS.
+var templates = lo.Must(fs.Sub(embedded, "sql"))
+
+// Queries implements every app/query port over db, sharing one immutable Parser.
+type Queries struct {
+	db     *sql.DB
+	parser *bisql.Parser
+}
+
+var (
+	_ port.UserSearcher     = (*Queries)(nil)
+	_ port.ActivityReporter = (*Queries)(nil)
+	_ port.AuditLogWriter   = (*Queries)(nil)
+	_ port.AuditLogLookup   = (*Queries)(nil)
+)
+
+// New returns a Queries backed by db.
+func New(db *sql.DB) *Queries {
+	return &Queries{db: db, parser: bisql.NewParser(bisql.WithDialect(dialect.SQLite))}
+}
+
+func (q *Queries) build(root string, params map[string]any) (bisql.Statement, error) {
+	tmpl, err := q.parser.ParseFile(templates, root)
+	if err != nil {
+		return bisql.Statement{}, err
+	}
+	return tmpl.Build(params)
+}
+
+// rows builds root with params, runs it, and returns the result rows.
+func (q *Queries) rows(ctx context.Context, root string, params map[string]any) ([]port.Row, error) {
+	stmt, err := q.build(root, params)
+	if err != nil {
+		return nil, err
+	}
+	rows, err := q.db.QueryContext(ctx, stmt.SQL, stmt.Args...)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rows.Close() }()
+	return scanAll(rows)
+}
+
+// scanAll reads every row into a column-keyed map, so a query with a conditional column (the
+// optional department in users/search) needs no special handling.
+func scanAll(rows *sql.Rows) ([]port.Row, error) {
+	cols, err := rows.Columns()
+	if err != nil {
+		return nil, err
+	}
+	out := []port.Row{}
+	for rows.Next() {
+		vals := make([]any, len(cols))
+		ptrs := lo.Map(vals, func(_ any, i int) any { return &vals[i] })
+		if err := rows.Scan(ptrs...); err != nil {
+			return nil, err
+		}
+		out = append(out, lo.SliceToMap(lo.Range(len(cols)), func(i int) (string, any) {
+			if b, ok := vals[i].([]byte); ok {
+				return cols[i], string(b)
+			}
+			return cols[i], vals[i]
+		}))
+	}
+	return out, rows.Err()
+}