@nakedev/go-scaffold 0.8.0 → 0.9.0

package/README.md

@@ -325,6 +325,20 @@ CRUD modules contain the starter list/get/create/update/delete methods. Lean
 modules keep the endpoint surface small so it can be extended with
 generate method.
 
+Every generated list endpoint reads `?limit=&offset=&q=&sort=&order=`, passes
+one `ports.ListFilter` from handler to application to repository, and answers
+the page beside the total the filter matched. The lists `add auth` and
+`add rbac` own use the same contract. `FindAll` calls `dbq.Search` with no
+columns and carries a `dbq.Sort` with no columns either, so `?q=` and `?sort=`
+are accepted and ignored until you name them in
+`adapters/outbound/postgres/repository.go`; add further filters as fields on
+`ListFilter` rather than as parameters.
+
+`dbq.Sort` is why a sort name off the request never reaches the SQL — `ORDER
+BY` takes no bound parameter, so only a key of its `Columns` map is ever
+interpolated — and it adds the tiebreaker and `NULLS LAST` that every stable
+paged list needs.
+
 CQRS modules additionally contain:
 
 ~~~text
@@ -361,6 +375,13 @@ If the module, method name, or endpoint details are omitted, the wizard asks
 for them. The module selector lists modules that exist on disk, so the command
 does not require memorising the normalised Go package name.
 
+`generate method` extends the modules `generate module` created, and the one
+`add auth` owns. It refuses `add rbac`'s role module: that module builds its
+HTTP response from a role *together with its permissions* rather than from the
+entity alone, so no generated body fits it. Add an endpoint there by hand — a
+route in `internal/app/role/adapters/inbound/http/handler.go`, a method on the
+application service, and its OpenAPI entry.
+
 ### Method options
 
 | Option | Effect |
@@ -373,7 +394,7 @@ The generated route and code depend on the method type:
 
 | Input | Route shape | Result |
 |---|---|---|
-| get --get-mode all | GET /<plural>/<method> | Uses the module's list query; add real filtering yourself |
+| get --get-mode all | GET /<plural>/<method> | Reuses the module's list query, so it inherits ListFilter, ?q= and the total |
 | get --get-mode one --field <field> | GET /<plural>/<field>/:<field> | Adds a FindBy<Field> query and a column/index migration |
 | post | POST /<plural>/<method> | Adds a request body DTO and a TODO service method |
 | put / patch | <VERB> /<plural>/:id/<method> | Loads by ID and leaves the update behavior as a TODO |
@@ -597,11 +618,11 @@ my-api/
 │   │   ├── config/                 # environment configuration
 │   │   ├── apperror/               # consistent application errors
 │   │   ├── dberr/                  # database error classification
-│   │   ├── dbq/                    # escaped contains-search for list filters
+│   │   ├── dbq/                    # escaped contains-search and whitelisted sort
 │   │   ├── httpx/                  # HTTP parsing and binding helpers
 │   │   ├── id/                     # UUID generation
 │   │   ├── middleware/             # request ID, logging, errors, CORS
-│   │   ├── pagination/             # pagination and ?q= parsing, responses
+│   │   ├── pagination/             # ?limit/offset/q/sort/order parsing, responses
 │   │   └── tx/                     # transaction context helpers
 │   └── app/                        # empty until generate module is used
 ├── migrations/                     # embedded, versioned SQL migrations

package/dist/utils/hexagonal-method-patcher.js

@@ -140,7 +140,13 @@ function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper, a
             body: [
                 `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
                 `\tp := pagination.Parse(c)`,
-                `\tfilter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}`,
+                `\tfilter := ports.ListFilter{`,
+                `\t\tSearch: p.Search,`,
+                `\t\tSort:   p.Sort,`,
+                `\t\tDesc:   p.Desc,`,
+                `\t\tLimit:  p.Limit,`,
+                `\t\tOffset: p.Offset,`,
+                `\t}`,
                 `\titems, total, err := ${receiver}.${method.pascalName}(c.Request.Context(), filter)`,
                 `\tif err != nil {`,
                 `\t\tc.Error(${errorMapper}(err))`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler.go.hbs

@@ -157,7 +157,13 @@ func (h *Handler) adminListUsers(c *gin.Context) {
 	p := pagination.Parse(c)
 	// One struct all the way down, so a filter added later is a field on
 	// ports.ListFilter and not a new argument on the three signatures below.
-	filter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}
+	filter := ports.ListFilter{
+		Search: p.Search,
+		Sort:   p.Sort,
+		Desc:   p.Desc,
+		Limit:  p.Limit,
+		Offset: p.Offset,
+	}
 	items, total, err := h.svc.List(c.Request.Context(), filter)
 	if err != nil {
 		c.Error(toHTTPError(err))

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/repository.go.hbs

@@ -77,6 +77,25 @@ func (r *Repository) UpdateUser(ctx context.Context, user *domain.User) error {
 	}))
 }
 
+// sortable is the whole of what ?sort= may say on the admin user list: dbq.Sort
+// resolves the requested name against Columns, so nothing off the request is
+// ever interpolated into the ORDER BY.
+var sortable = dbq.Sort{
+	Columns: map[string]string{
+		"name":       "name",
+		"role":       "role",
+		"created_at": "created_at",
+		// The address lives one table over, and only one row per user is
+		// primary (idx_user_emails_primary), so the subquery answers exactly
+		// one value. Correlated, so it runs per matching row — fine for a
+		// staff table; make it a LEFT JOIN on that index if this ever pages
+		// thousands, and give the query its own SELECT list when you do.
+		"email": "(SELECT e.email FROM user_svc.user_emails e WHERE e.user_id = user_svc.users.id AND e.is_primary)",
+	},
+	Default:  "created_at desc",
+	Tiebreak: "id",
+}
+
 // FindAll answers one page of the filter and how many accounts it matched
 // altogether. Two queries for that, because a count over a LIMITed query would
 // only ever count the page.
@@ -104,10 +123,12 @@ func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]do
 	}
 
 	var rows []User
-	// id breaks ties in created_at: without it two accounts created in the
-	// same instant can swap between page 1 and page 2, showing one twice and
-	// hiding the other.
-	err := matching().Order("created_at desc, id").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
+	// Newest account first until a client asks for something else, and always
+	// with the tiebreaker sortable carries: without it two accounts created in
+	// the same instant can swap between page 1 and page 2, showing one twice
+	// and hiding the other.
+	order := sortable.OrderBy(filter.Sort, filter.Desc)
+	err := matching().Order(order).Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
 	if err != nil {
 		return nil, 0, persistenceError(err)
 	}

package/templates/add/auth/internal/app/user/ports/repository.go.hbs

@@ -21,6 +21,11 @@ type ListFilter struct {
 	// Search is ?q= as shared/pagination parsed it, matched against the name
 	// and the primary email address.
 	Search string
+	// Sort is ?sort= and Desc is ?order=desc, both as shared/pagination parsed
+	// them. Which column names are accepted is the repository's to say — see
+	// the dbq.Sort beside its FindAll.
+	Sort   string
+	Desc   bool
 	Limit  int
 	Offset int
 }

package/templates/add/rbac/docs/users.yaml.hbs

@@ -7,9 +7,14 @@ get:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
     - $ref: '../common/parameters.yaml#/Search'
+    - $ref: '../common/parameters.yaml#/Sort'
+    - $ref: '../common/parameters.yaml#/Order'
   responses:
     "200":
-      description: "paginated list; `q` matches name and primary email"
+      description: >-
+        paginated list; `q` matches name and primary email, and `sort` takes
+        name, email, role or created_at — anything else is the default order,
+        newest account first
       content:
         application/json:
           schema:

package/templates/create/base/internal/shared/dbq/dbq.go.hbs

@@ -45,3 +45,51 @@ func Search(db *gorm.DB, term string, cols ...string) *gorm.DB {
 	// narrowing it.
 	return db.Where("("+strings.Join(conds, " OR ")+")", args...)
 }
+
+// Sort is a list endpoint's ordering contract: the columns it accepts, the
+// order it has before anyone asks for one, and the column that breaks ties.
+// Declare it once per repository, beside the FindAll that uses it.
+type Sort struct {
+	// Columns maps the names the API accepts to the SQL each one means, and is
+	// the whole of what can reach the clause: ORDER BY takes no bound
+	// parameter, so a ?sort= that is not a key here is never interpolated. A
+	// value the table does not hold — an address one table over — is a
+	// subquery rather than a join, which would need its own SELECT list to
+	// keep Find scanning the right row.
+	Columns map[string]string
+	// Default is the order for a request that asked for nothing Columns knows,
+	// written without the tiebreaker: OrderBy adds it.
+	Default string
+	// Tiebreak is a column unique enough to page by, usually the primary key.
+	// Without it two rows equal on the sorted column can swap places between
+	// page 1 and page 2, showing one twice and hiding the other. Leave it empty
+	// only when Columns and Default are unique on their own.
+	Tiebreak string
+}
+
+// OrderBy resolves what the request asked for into an ORDER BY clause:
+//
+//	q = q.Order(thingSort.OrderBy(filter.Sort, filter.Desc))
+//
+// Sorted columns get NULLS LAST in both directions, because a row with no
+// value is missing an answer rather than holding the largest one — the account
+// that has never signed in belongs at the bottom whichever way the column is
+// pointed. It is a no-op on a column that cannot be null.
+func (s Sort) OrderBy(sort string, desc bool) string {
+	clause := s.Default
+	if col, ok := s.Columns[sort]; ok {
+		dir := "asc"
+		if desc {
+			dir = "desc"
+		}
+		clause = col + " " + dir + " NULLS LAST"
+	}
+	switch {
+	case s.Tiebreak == "":
+		return clause
+	case clause == "":
+		return s.Tiebreak
+	default:
+		return clause + ", " + s.Tiebreak
+	}
+}

package/templates/create/base/internal/shared/dbq/dbq_test.go.hbs

@@ -64,3 +64,37 @@ func TestSearchWithoutATermIsANoOp(t *testing.T) {
 		t.Errorf("empty term still filtered: %s", stmt.SQL.String())
 	}
 }
+
+// The whitelist is the security boundary: ?sort= comes off the request, and
+// ORDER BY takes no bound parameter. The rest is the two rules every list gets
+// for free — a tiebreaker, and empty values last.
+func TestSortOrderBy(t *testing.T) {
+	sorter := Sort{
+		Columns:  map[string]string{"name": "name", "seen_at": "seen_at"},
+		Default:  "created_at desc",
+		Tiebreak: "id",
+	}
+	for _, tc := range []struct {
+		sort string
+		desc bool
+		want string
+	}{
+		{"name", false, "name asc NULLS LAST, id"},
+		{"seen_at", true, "seen_at desc NULLS LAST, id"},
+		// Nobody asked for an order.
+		{"", false, "created_at desc, id"},
+		// A name that is not on the list is the default order, not SQL.
+		{"name; DROP TABLE things --", true, "created_at desc, id"},
+	} {
+		if got := sorter.OrderBy(tc.sort, tc.desc); got != tc.want {
+			t.Errorf("OrderBy(%q, %v) = %q, want %q", tc.sort, tc.desc, got, tc.want)
+		}
+	}
+
+	// A table keyed by something unique on its own needs no tiebreaker, and
+	// must not be given one it has no column for.
+	byCode := Sort{Columns: map[string]string{"name": "name"}, Tiebreak: "code"}
+	if got := byCode.OrderBy("", false); got != "code" {
+		t.Errorf("no default and no sort should be the tiebreaker alone, got %q", got)
+	}
+}

package/templates/create/base/internal/shared/pagination/pagination.go.hbs

@@ -24,10 +24,17 @@ type Params struct {
 	// Search is ?q= trimmed, empty when the caller sent none — so a repository
 	// can pass it straight to dbq.Search, which no-ops on an empty term.
 	Search string
+	// Sort is ?sort=, the column the client asked to be ordered by, and Desc
+	// is ?order=desc. Nothing is validated here on purpose: which names an
+	// endpoint accepts is its repository's to say, and dbq.Sort is where that
+	// whitelist is applied — a name it does not know falls back to the list's
+	// own order rather than failing the request.
+	Sort string
+	Desc bool
 }
 
-// Parse reads ?limit=&offset=&q= off the request so every feature parses the
-// same way.
+// Parse reads ?limit=&offset=&q=&sort=&order= off the request so every feature
+// parses the same way.
 func Parse(c *gin.Context) Params {
 	p := Params{Limit: defaultLimit}
 	if v, err := strconv.Atoi(c.Query("limit")); err == nil && v > 0 {
@@ -47,6 +54,10 @@ func Parse(c *gin.Context) Params {
 		}
 		p.Search = q
 	}
+	p.Sort = strings.TrimSpace(c.Query("sort"))
+	// Ascending unless asked otherwise: one spelling of "the other way", and
+	// anything else read as the default rather than refused.
+	p.Desc = c.Query("order") == "desc"
 	return p
 }
 

package/templates/create/features/docs/common/parameters.yaml.hbs

@@ -16,3 +16,13 @@ Search:
   in: query
   description: "free-text search; which columns it matches is documented per endpoint"
   schema: { type: string, maxLength: 100 }
+Sort:
+  name: sort
+  in: query
+  description: "column to order by; which columns are accepted is documented per endpoint, and anything else is read as that list's own default order"
+  schema: { type: string }
+Order:
+  name: order
+  in: query
+  description: "direction for `sort`; ascending unless this is `desc`. Rows with no value sort last either way"
+  schema: { type: string, enum: [asc, desc], default: asc }

package/templates/create/features/docs/patterns.md.hbs

@@ -255,9 +255,10 @@ business logic — same spirit as `generate module`'s placeholder fields.
 A `crud`-surface module is generated with this already wired; a module that
 grows a list later copies the same four steps. Nothing about it is magic.
 
-**1. Parse at the boundary.** `pagination.Parse(c)` returns `Limit`, `Offset`
-and `Search` (`?q=`, trimmed and capped at 100 runes). Read the filters this
-endpoint owns off the query string beside it. An unreadable filter value means
+**1. Parse at the boundary.** `pagination.Parse(c)` returns `Limit`, `Offset`,
+`Search` (`?q=`, trimmed and capped at 100 runes) and the requested order —
+`Sort` (`?sort=`) and `Desc` (`?order=desc`). Read the filters this endpoint
+owns off the query string beside them. An unreadable filter value means
 *no* filter, not `400` — a list narrows on a best effort.
 
 **2. One filter struct, in `ports/`.** `ports.ListFilter` travels whole through
@@ -270,6 +271,8 @@ everything".
 ```go
 type ListFilter struct {
     Search string
+    Sort   string
+    Desc   bool
     Limit  int
     Offset int
     // Status, OwnerID, DateFrom … whatever this module actually filters by.
@@ -288,21 +291,47 @@ accumulate on a `*gorm.DB` value, so a count reusing the page's query object
 silently inherits its `LIMIT`. Use `dbq.Search(q, term, cols...)` for a
 contains-search over columns on the same table, and `dbq.LikePattern(term)`
 when the search spans a subquery or a join. Both escape `%` and `_`, so
-someone typing `50%` searches for `50%` instead of matching every row. Always
-keep a tiebreaker in the sort (`ORDER BY created_at DESC, id`) or two rows
-written in the same instant can swap between page 1 and page 2 — showing one
-twice and hiding the other.
+someone typing `50%` searches for `50%` instead of matching every row.
 
-The generated `FindAll` calls `dbq.Search` with no columns, which is a no-op:
-`?q=` is accepted and ignored until you name the columns this list is searched
-by. That TODO is the one line standing between the scaffold and a working
-search.
+The order is a `dbq.Sort` declared beside `FindAll`, not an `Order` string
+written per query:
+
+```go
+var sortable = dbq.Sort{
+    Columns:  map[string]string{"name": "name", "created_at": "created_at"},
+    Default:  "created_at desc",
+    Tiebreak: "id",
+}
+...
+q = q.Order(sortable.OrderBy(filter.Sort, filter.Desc))
+```
+
+`Columns` maps the names the API accepts to the SQL each one means and is the
+whole of what can reach the clause — `ORDER BY` takes no bound parameter, so a
+`?sort=` that is not one of its keys falls back to `Default` rather than being
+interpolated. `OrderBy` adds what every list needs and nobody should have to
+remember: `Tiebreak` on the end (without it two rows equal on the sorted column
+swap between page 1 and page 2, showing one twice and hiding the other) and
+`NULLS LAST` in both directions (a row with no value is missing an answer, not
+holding the largest one). A table already unique on its order — roles, keyed by
+`code` — sets `Tiebreak` to that column and leaves `Default` empty.
+
+A column the client sees but this table does not hold, such as a primary email
+one table over, belongs in `Columns` as a subquery rather than a join: a join
+would need its own `SELECT` list to keep `Find` scanning the right row.
+
+The generated `FindAll` calls `dbq.Search` with no columns and carries an empty
+`Columns` map, both no-ops: `?q=` and `?sort=` are accepted and ignored until
+you name the columns this list is searched and ordered by. Those two TODOs are
+the lines standing between the scaffold and a working list.
 
 **4. Respond with the shared envelope.** `p.ResponseWithTotal(out, total)` —
 `{ data, limit, offset, total }`, the same shape for every resource. Anything
 extra is a named key added to that map and documented in the endpoint's
-OpenAPI file. Reuse `common/parameters.yaml#/Search`, `#/Limit` and `#/Offset`
-for the query parameters.
+OpenAPI file. Reuse `common/parameters.yaml#/Search`, `#/Limit`, `#/Offset`,
+`#/Sort` and `#/Order` for the query parameters. `#/Sort` carries no enum —
+which columns an endpoint accepts is a sentence in its own response
+description, the same way `q` says what it matches.
 
 Counts that answer a *different* question from the page — "how many are open
 and how many are closed, whichever tab is showing" — belong beside the

package/templates/generate/module/docs/collection.yaml.hbs

@@ -22,9 +22,11 @@ get:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
     - $ref: '../common/parameters.yaml#/Search'
+    - $ref: '../common/parameters.yaml#/Sort'
+    - $ref: '../common/parameters.yaml#/Order'
   responses:
     "200":
-      description: "paginated list; narrow it with ?q= and whatever filters this module adds"
+      description: "paginated list; narrow it with ?q= and whatever filters this module adds, and order it with ?sort= once the repository's dbq.Sort names a column"
       content:
         application/json:
           schema:

package/templates/generate/module/hexagonal/adapters/inbound/http/handler.go.hbs

@@ -111,7 +111,13 @@ func (h *Handler) list(c *gin.Context) {
 	// One struct all the way down, so this module's own filters are read off
 	// the query string here and added as fields on ports.ListFilter — never as
 	// extra arguments on the three signatures below.
-	filter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}
+	filter := ports.ListFilter{
+		Search: p.Search,
+		Sort:   p.Sort,
+		Desc:   p.Desc,
+		Limit:  p.Limit,
+		Offset: p.Offset,
+	}
 {{#if cqrs}}
 	items, total, err := h.queries.List(c.Request.Context(), filter)
 {{else}}

package/templates/generate/module/hexagonal/adapters/outbound/postgres/repository.go.hbs

@@ -31,6 +31,20 @@ func (r *Repository) Create(ctx context.Context, m *domain.{{pascalName}}) error
 	return nil
 }
 
+// sortable is the whole of what ?sort= may say for this list: dbq.Sort
+// resolves the requested name against Columns, so nothing off the request is
+// ever interpolated into the ORDER BY.
+//
+// TODO: name the columns this list may be ordered by, mapping the name the API
+// accepts to the SQL it means — {"name": "name", "created_at": "created_at"}.
+// Until then ?sort= is accepted and ignored, the same way dbq.Search is until
+// it has columns.
+var sortable = dbq.Sort{
+	Columns:  map[string]string{},
+	Default:  "created_at desc",
+	Tiebreak: "id",
+}
+
 // FindAll answers one page of the filter and how many rows it matched
 // altogether. Two queries, because a count over a LIMITed query would only
 // ever count the page.
@@ -52,10 +66,12 @@ func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]do
 	}
 
 	var rows []{{pascalName}}Model
-	// created_at orders it, id breaks the ties: without the tiebreaker two
-	// rows written in the same instant can swap between page 1 and page 2,
-	// showing one twice and hiding the other.
-	if err := matching().Order("created_at desc, id").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error; err != nil {
+	// Newest first until a client asks for something else, and always with the
+	// tiebreaker sortable carries: without it two rows written in the same
+	// instant can swap between page 1 and page 2, showing one twice and hiding
+	// the other.
+	order := sortable.OrderBy(filter.Sort, filter.Desc)
+	if err := matching().Order(order).Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error; err != nil {
 		return nil, 0, mapDatabaseError(err)
 	}
 	items := make([]domain.{{pascalName}}, len(rows))

package/templates/generate/module/hexagonal/ports/repository.go.hbs

@@ -21,6 +21,11 @@ type ListFilter struct {
 	// Search is ?q= as shared/pagination parsed it, empty when the caller
 	// sent none.
 	Search string
+	// Sort is ?sort= and Desc is ?order=desc, both as shared/pagination parsed
+	// them. Which column names are accepted is the repository's to say — see
+	// the dbq.Sort beside its FindAll.
+	Sort   string
+	Desc   bool
 	Limit  int
 	Offset int
 }