@nakedev/go-scaffold 0.5.4 → 0.8.0

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

@@ -47,7 +47,7 @@ internal/
 ├── platform/                # talks to real external systems
 │   └── database/             # PostgreSQL connection and pool
 ├── shared/                  # pure logic/framework glue, no I/O
-│   ├── config/  apperror/  dberr/  httpx/  id/
+│   ├── config/  apperror/  dberr/  dbq/  httpx/  id/
 │   └── middleware/  pagination/  tx/
 └── app/                     # domain packages (one per feature)
     └── <domain>/
@@ -129,12 +129,15 @@ call site, no error-shape drift between domains.
 - DB errors are classified once in `shared/dberr` (`IsDuplicate`,
   `IsForeignKey`) and mapped to the right HTTP status per domain
 
-## 6. Pagination
+## 6. Pagination and Filtering
 
-**Decision:** Shared `limit`/`offset` parsing and response envelope
-(`shared/pagination`), used by every list endpoint.
-**Rationale:** One implementation, one response shape (`{data, limit,
-offset}`) — no per-domain reinvention.
+**Decision:** Shared `limit`/`offset`/`q` parsing and response envelope
+(`shared/pagination`), used by every list endpoint, with the SQL a filter
+repeats in `shared/dbq`. A list takes one filter struct from `ports/` and
+answers a page plus its total.
+**Rationale:** One implementation, one response shape (`{data, limit, offset,
+total}`) — no per-domain reinvention, and no per-domain LIKE escaping to get
+wrong. See `patterns.md`, "Filtered Lists".
 
 ## 7. Persistence
 

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

@@ -11,3 +11,8 @@ Offset:
   name: offset
   in: query
   schema: { type: integer, default: 0, minimum: 0 }
+Search:
+  name: q
+  in: query
+  description: "free-text search; which columns it matches is documented per endpoint"
+  schema: { type: string, maxLength: 100 }

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

@@ -4,6 +4,7 @@ PageEnvelope:
   properties:
     limit: { type: integer }
     offset: { type: integer }
+    total: { type: integer, description: "rows the filter matched; present on endpoints that count them" }
 
 Error:
   type: object

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

@@ -250,6 +250,66 @@ those markers** — they're where the next `generate method` call inserts. The
 method body is always left as a compiling `TODO` rather than guessing at
 business logic — same spirit as `generate module`'s placeholder fields.
 
+## Filtered Lists — one filter struct, a page and its total
+
+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
+*no* filter, not `400` — a list narrows on a best effort.
+
+**2. One filter struct, in `ports/`.** `ports.ListFilter` travels whole through
+handler → application → repository, so adding a filter later is one field and
+not a fourth positional argument on three signatures. It lives in `ports/`
+because that is the only package all three may import — `ports` importing
+`application` would be a cycle. Its zero value means "the first page of
+everything".
+
+```go
+type ListFilter struct {
+    Search string
+    Limit  int
+    Offset int
+    // Status, OwnerID, DateFrom … whatever this module actually filters by.
+}
+```
+
+**3. The repository returns the page *and* the total**, because a client that
+pages needs both and only SQL can answer either:
+
+```go
+FindAll(context.Context, ListFilter) ([]domain.Thing, int64, error)
+```
+
+Build the conditions in a closure and call it once per query — conditions
+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.
+
+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.
+
+**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.
+
+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
+envelope, not in it, and are computed from the filter minus the field the tabs
+switch. A tab that recounted itself when clicked would always read the same
+number.
+
 ## Testing Conventions
 
 - Unit and integration tests live in the same directory as the code under

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

@@ -21,9 +21,10 @@ get:
   parameters:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
+    - $ref: '../common/parameters.yaml#/Search'
   responses:
     "200":
-      description: paginated list
+      description: "paginated list; narrow it with ?q= and whatever filters this module adds"
       content:
         application/json:
           schema:

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

@@ -7,6 +7,7 @@ import (
 
 	"{{goModule}}/internal/app/{{modulePath}}/application"
 	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
 	"{{goModule}}/internal/shared/apperror"
 	"{{goModule}}/internal/shared/httpx"
 {{#if auth}}	"{{goModule}}/internal/shared/middleware"
@@ -107,10 +108,14 @@ func (h *Handler) create(c *gin.Context) {
 
 func (h *Handler) list(c *gin.Context) {
 	p := pagination.Parse(c)
+	// 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}
 {{#if cqrs}}
-	items, err := h.queries.List(c.Request.Context(), p.Limit, p.Offset)
+	items, total, err := h.queries.List(c.Request.Context(), filter)
 {{else}}
-	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	items, total, err := h.svc.List(c.Request.Context(), filter)
 {{/if}}
 	if err != nil {
 		c.Error(appError(err))
@@ -120,7 +125,7 @@ func (h *Handler) list(c *gin.Context) {
 	for i := range items {
 		out[i] = toResponse(application.ToResponse(&items[i]))
 	}
-	c.JSON(http.StatusOK, p.Response(out))
+	c.JSON(http.StatusOK, p.ResponseWithTotal(out, total))
 }
 
 func (h *Handler) get(c *gin.Context) {

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

@@ -6,6 +6,7 @@ import (
 
 	"{{goModule}}/internal/app/{{modulePath}}/domain"
 	"{{goModule}}/internal/app/{{modulePath}}/ports"
+	"{{goModule}}/internal/shared/dbq"
 	"{{goModule}}/internal/shared/dberr"
 	"{{goModule}}/internal/shared/tx"
 
@@ -30,16 +31,38 @@ func (r *Repository) Create(ctx context.Context, m *domain.{{pascalName}}) error
 	return nil
 }
 
-func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+// 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.
+func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]domain.{{pascalName}}, int64, error) {
+	// A closure rather than one *gorm.DB reused twice: conditions accumulate
+	// on the value, so the count would silently inherit the page's LIMIT.
+	matching := func() *gorm.DB {
+		q := tx.From(ctx, r.db).WithContext(ctx).Model(&{{pascalName}}Model{})
+		// TODO: name the columns this list is searched by. dbq.Search is a
+		// no-op until it has at least one, so ?q= is accepted and ignored
+		// until then. Add this module's own filters beside it.
+		q = dbq.Search(q, filter.Search /*, "name", "code" */)
+		return q
+	}
+
+	var total int64
+	if err := matching().Count(&total).Error; err != nil {
+		return nil, 0, mapDatabaseError(err)
+	}
+
 	var rows []{{pascalName}}Model
-	if err := tx.From(ctx, r.db).WithContext(ctx).Order("id desc").Limit(limit).Offset(offset).Find(&rows).Error; err != nil {
-		return nil, mapDatabaseError(err)
+	// 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 {
+		return nil, 0, mapDatabaseError(err)
 	}
 	items := make([]domain.{{pascalName}}, len(rows))
 	for i := range rows {
 		items[i] = *toDomain(&rows[i])
 	}
-	return items, nil
+	return items, total, nil
 }
 
 func (r *Repository) FindByID(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {

package/templates/generate/module/hexagonal/application/cqrs_test.go.hbs

@@ -15,7 +15,7 @@ import (
 // which side of the CQRS boundary was called.
 type repositoryStub struct {
 	createFn   func(context.Context, *domain.{{pascalName}}) error
-	findAllFn  func(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	findAllFn  func(context.Context, ports.ListFilter) ([]domain.{{pascalName}}, int64, error)
 	findByIDFn func(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	updateFn   func(context.Context, *domain.{{pascalName}}) error
 	deleteFn   func(context.Context, uuid.UUID) error
@@ -28,11 +28,11 @@ func (s *repositoryStub) Create(ctx context.Context, m *domain.{{pascalName}}) e
 	}
 	return s.createFn(ctx, m)
 }
-func (s *repositoryStub) FindAll(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+func (s *repositoryStub) FindAll(ctx context.Context, filter ports.ListFilter) ([]domain.{{pascalName}}, int64, error) {
 	if s.findAllFn == nil {
 		panic("unexpected repository.FindAll call")
 	}
-	return s.findAllFn(ctx, limit, offset)
+	return s.findAllFn(ctx, filter)
 }
 func (s *repositoryStub) FindByID(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
 	if s.findByIDFn == nil {

package/templates/generate/module/hexagonal/application/queries.crud.go.hbs

@@ -9,7 +9,7 @@ import (
 )
 
 type QueryPort interface {
-	List(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	List(context.Context, ports.ListFilter) ([]domain.{{pascalName}}, int64, error)
 	Get(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	// go-scaffold:query-interface
 }
@@ -22,8 +22,8 @@ func NewQueryHandler(repo ports.QueryRepository) *QueryHandler {
 	return &QueryHandler{repo: repo}
 }
 
-func (h *QueryHandler) List(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
-	return h.repo.FindAll(ctx, limit, offset)
+func (h *QueryHandler) List(ctx context.Context, filter ports.ListFilter) ([]domain.{{pascalName}}, int64, error) {
+	return h.repo.FindAll(ctx, filter)
 }
 
 func (h *QueryHandler) Get(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {

package/templates/generate/module/hexagonal/application/service.crud.go.hbs

@@ -13,7 +13,7 @@ import (
 
 type ServicePort interface {
 	Create(context.Context, CreateInput) (*domain.{{pascalName}}, error)
-	List(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	List(context.Context, ports.ListFilter) ([]domain.{{pascalName}}, int64, error)
 	Get(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	Update(context.Context, uuid.UUID, UpdateInput) (*domain.{{pascalName}}, error)
 	Delete(context.Context, uuid.UUID) error
@@ -38,8 +38,8 @@ func (s *Service) Create(ctx context.Context, in CreateInput) (*domain.{{pascalN
 	return m, nil
 }
 
-func (s *Service) List(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
-	return s.repo.FindAll(ctx, limit, offset)
+func (s *Service) List(ctx context.Context, filter ports.ListFilter) ([]domain.{{pascalName}}, int64, error) {
+	return s.repo.FindAll(ctx, filter)
 }
 
 func (s *Service) Get(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {

package/templates/generate/module/hexagonal/application/service_test.go.hbs

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
 
 	"github.com/google/uuid"
 )
@@ -15,7 +16,7 @@ import (
 // orchestration.
 type repositoryStub struct {
 	createFn   func(context.Context, *domain.{{pascalName}}) error
-	findAllFn  func(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	findAllFn  func(context.Context, ports.ListFilter) ([]domain.{{pascalName}}, int64, error)
 	findByIDFn func(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	updateFn   func(context.Context, *domain.{{pascalName}}) error
 	deleteFn   func(context.Context, uuid.UUID) error
@@ -28,11 +29,11 @@ func (s *repositoryStub) Create(ctx context.Context, m *domain.{{pascalName}}) e
 	}
 	return s.createFn(ctx, m)
 }
-func (s *repositoryStub) FindAll(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+func (s *repositoryStub) FindAll(ctx context.Context, filter ports.ListFilter) ([]domain.{{pascalName}}, int64, error) {
 	if s.findAllFn == nil {
 		panic("unexpected repository.FindAll call")
 	}
-	return s.findAllFn(ctx, limit, offset)
+	return s.findAllFn(ctx, filter)
 }
 func (s *repositoryStub) FindByID(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
 	if s.findByIDFn == nil {

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

@@ -11,10 +11,26 @@ import (
 	"github.com/google/uuid"
 )
 
+// ListFilter is the whole question the list endpoint asks. The zero value is
+// "the first page of everything", so a caller only sets what it narrows by.
+//
+// Put this module's own filters here as fields rather than as arguments: one
+// struct travels handler -> application -> repository, so adding a filter
+// later is a field and not a fourth parameter on three signatures.
+type ListFilter struct {
+	// Search is ?q= as shared/pagination parsed it, empty when the caller
+	// sent none.
+	Search string
+	Limit  int
+	Offset int
+}
+
 // Repository is the complete persistence port for service-style modules.
 type Repository interface {
 	Create(context.Context, *domain.{{pascalName}}) error
-	FindAll(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	// FindAll answers one page and the total the filter matched, which is what
+	// a client needs to draw "page 3 of 12".
+	FindAll(context.Context, ListFilter) ([]domain.{{pascalName}}, int64, error)
 	FindByID(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	Update(context.Context, *domain.{{pascalName}}) error
 	Delete(context.Context, uuid.UUID) error
@@ -32,7 +48,7 @@ type CommandRepository interface {
 }
 
 type QueryRepository interface {
-	FindAll(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	FindAll(context.Context, ListFilter) ([]domain.{{pascalName}}, int64, error)
 	FindByID(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
 	// go-scaffold:query-repository-interface
 }