@apso/cli 0.11.0 → 0.12.0

package/dist/lib/templates/go/utils/query.eta

@@ -0,0 +1,301 @@
+<%~ includeFile('../../header.eta', it) %>
+
+package utils
+
+import (
+	"fmt"
+	"math"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"gorm.io/gorm"
+)
+
+const (
+	MaxLimit     = 200
+	DefaultLimit = 25
+	DefaultPage  = 1
+)
+
+// ParseQueryParams parses standard query parameters from a url.Values map
+// into a QueryOptions struct.
+func ParseQueryParams(params url.Values) QueryOptions {
+	opts := DefaultQueryOptions()
+
+	// Filters: ?filter=field||$op||value (repeatable)
+	for _, raw := range params["filter"] {
+		if f := parseFilterParam(raw); f != nil {
+			opts.Filters = append(opts.Filters, *f)
+		}
+	}
+
+	// OR filters: ?or=field||$op||value (repeatable)
+	for _, raw := range params["or"] {
+		if f := parseFilterParam(raw); f != nil {
+			opts.OrFilters = append(opts.OrFilters, *f)
+		}
+	}
+
+	// Sorts: ?sort=field,ASC (repeatable)
+	for _, raw := range params["sort"] {
+		if s := parseSortParam(raw); s != nil {
+			opts.Sorts = append(opts.Sorts, *s)
+		}
+	}
+
+	// Fields: ?fields=field1,field2
+	if fieldsRaw := params.Get("fields"); fieldsRaw != "" {
+		for _, f := range strings.Split(fieldsRaw, ",") {
+			f = strings.TrimSpace(f)
+			if f != "" {
+				opts.Fields = append(opts.Fields, f)
+			}
+		}
+	}
+
+	// Joins: ?join=relation or ?join=relation||field1,field2 (repeatable)
+	for _, raw := range params["join"] {
+		opts.Joins = append(opts.Joins, parseJoinParam(raw))
+	}
+
+	// Pagination
+	if limitRaw := params.Get("limit"); limitRaw != "" {
+		if v, err := strconv.Atoi(limitRaw); err == nil {
+			if v > MaxLimit {
+				v = MaxLimit
+			}
+			if v > 0 {
+				opts.Limit = v
+			}
+		}
+	}
+
+	if pageRaw := params.Get("page"); pageRaw != "" {
+		if v, err := strconv.Atoi(pageRaw); err == nil && v > 0 {
+			opts.Page = v
+		}
+	}
+
+	return opts
+}
+
+// ApplyQuery applies filters, sorts, and pagination from QueryOptions to a
+// GORM query. The allowedFields map restricts which column names can be used
+// in filters and sorts to prevent injection.
+func ApplyQuery(db *gorm.DB, opts QueryOptions, allowedFields map[string]bool) (*gorm.DB, int64, int) {
+	query := db
+
+	// AND filters
+	for _, f := range opts.Filters {
+		if !allowedFields[f.Field] {
+			continue
+		}
+		query = applyOperator(query, f.Field, f.Operator, f.Value, false)
+	}
+
+	// OR filters
+	if len(opts.OrFilters) > 0 {
+		query = query.Where(func(tx *gorm.DB) *gorm.DB {
+			first := true
+			for _, f := range opts.OrFilters {
+				if !allowedFields[f.Field] {
+					continue
+				}
+				if first {
+					tx = applyOperator(tx, f.Field, f.Operator, f.Value, false)
+					first = false
+				} else {
+					tx = applyOperator(tx, f.Field, f.Operator, f.Value, true)
+				}
+			}
+			return tx
+		}(db.Session(&gorm.Session{NewDB: true})))
+	}
+
+	// Count before pagination
+	var total int64
+	countQuery := query.Session(&gorm.Session{})
+	countQuery.Count(&total)
+
+	// Sorting
+	for _, s := range opts.Sorts {
+		if !allowedFields[s.Field] {
+			continue
+		}
+		dir := "ASC"
+		if strings.EqualFold(s.Direction, "DESC") {
+			dir = "DESC"
+		}
+		query = query.Order(fmt.Sprintf("%s %s", s.Field, dir))
+	}
+
+	// Field selection
+	if len(opts.Fields) > 0 {
+		var safe []string
+		for _, f := range opts.Fields {
+			if allowedFields[f] {
+				safe = append(safe, f)
+			}
+		}
+		if len(safe) > 0 {
+			query = query.Select(safe)
+		}
+	}
+
+	// Joins (Preloads)
+	for _, j := range opts.Joins {
+		query = query.Preload(j.Relation)
+	}
+
+	// Pagination
+	offset := (opts.Page - 1) * opts.Limit
+	query = query.Offset(offset).Limit(opts.Limit)
+
+	pageCount := int(math.Ceil(float64(total) / float64(opts.Limit)))
+	if pageCount < 1 {
+		pageCount = 1
+	}
+
+	return query, total, pageCount
+}
+
+// ---------------------------------------------------------------------------
+// Internal parsers
+// ---------------------------------------------------------------------------
+
+func parseFilterParam(raw string) *ParsedFilter {
+	parts := strings.SplitN(raw, "||", 3)
+	if len(parts) < 2 {
+		return nil
+	}
+	value := ""
+	if len(parts) > 2 {
+		value = parts[2]
+	}
+	return &ParsedFilter{
+		Field:    parts[0],
+		Operator: parts[1],
+		Value:    value,
+	}
+}
+
+func parseSortParam(raw string) *ParsedSort {
+	parts := strings.SplitN(raw, ",", 2)
+	if len(parts) == 0 || parts[0] == "" {
+		return nil
+	}
+	dir := "ASC"
+	if len(parts) > 1 {
+		d := strings.ToUpper(strings.TrimSpace(parts[1]))
+		if d == "DESC" {
+			dir = "DESC"
+		}
+	}
+	return &ParsedSort{
+		Field:     parts[0],
+		Direction: dir,
+	}
+}
+
+func parseJoinParam(raw string) ParsedJoin {
+	parts := strings.SplitN(raw, "||", 2)
+	j := ParsedJoin{Relation: parts[0]}
+	if len(parts) > 1 && parts[1] != "" {
+		for _, f := range strings.Split(parts[1], ",") {
+			f = strings.TrimSpace(f)
+			if f != "" {
+				j.Fields = append(j.Fields, f)
+			}
+		}
+	}
+	return j
+}
+
+// ---------------------------------------------------------------------------
+// Operator application
+// ---------------------------------------------------------------------------
+
+func applyOperator(query *gorm.DB, field, op, value string, useOr bool) *gorm.DB {
+	where := query.Where
+	if useOr {
+		where = query.Or
+	}
+
+	switch op {
+	case "$eq":
+		return where(fmt.Sprintf("%s = ?", field), value)
+	case "$ne":
+		return where(fmt.Sprintf("%s != ?", field), value)
+	case "$gt":
+		return where(fmt.Sprintf("%s > ?", field), value)
+	case "$gte":
+		return where(fmt.Sprintf("%s >= ?", field), value)
+	case "$lt":
+		return where(fmt.Sprintf("%s < ?", field), value)
+	case "$lte":
+		return where(fmt.Sprintf("%s <= ?", field), value)
+	case "$starts":
+		return where(fmt.Sprintf("%s LIKE ?", field), value+"%")
+	case "$ends":
+		return where(fmt.Sprintf("%s LIKE ?", field), "%"+value)
+	case "$cont":
+		return where(fmt.Sprintf("%s LIKE ?", field), "%"+value+"%")
+	case "$excl":
+		return where(fmt.Sprintf("%s NOT LIKE ?", field), "%"+value+"%")
+	case "$in":
+		return where(fmt.Sprintf("%s IN ?", field), splitValue(value))
+	case "$notin":
+		return where(fmt.Sprintf("%s NOT IN ?", field), splitValue(value))
+	case "$isnull":
+		return where(fmt.Sprintf("%s IS NULL", field))
+	case "$notnull":
+		return where(fmt.Sprintf("%s IS NOT NULL", field))
+	case "$between":
+		vals := splitValue(value)
+		if len(vals) >= 2 {
+			return where(fmt.Sprintf("%s BETWEEN ? AND ?", field), vals[0], vals[1])
+		}
+		return query
+	case "$eqL":
+		return where(fmt.Sprintf("LOWER(%s) = ?", field), strings.ToLower(value))
+	case "$neL":
+		return where(fmt.Sprintf("LOWER(%s) != ?", field), strings.ToLower(value))
+	case "$startsL":
+		return where(fmt.Sprintf("LOWER(%s) LIKE ?", field), strings.ToLower(value)+"%")
+	case "$endsL":
+		return where(fmt.Sprintf("LOWER(%s) LIKE ?", field), "%"+strings.ToLower(value))
+	case "$contL":
+		return where(fmt.Sprintf("LOWER(%s) LIKE ?", field), "%"+strings.ToLower(value)+"%")
+	case "$exclL":
+		return where(fmt.Sprintf("LOWER(%s) NOT LIKE ?", field), "%"+strings.ToLower(value)+"%")
+	case "$inL":
+		vals := splitValue(value)
+		lower := make([]string, len(vals))
+		for i, v := range vals {
+			lower[i] = strings.ToLower(v)
+		}
+		return where(fmt.Sprintf("LOWER(%s) IN ?", field), lower)
+	case "$notinL":
+		vals := splitValue(value)
+		lower := make([]string, len(vals))
+		for i, v := range vals {
+			lower[i] = strings.ToLower(v)
+		}
+		return where(fmt.Sprintf("LOWER(%s) NOT IN ?", field), lower)
+	default:
+		return query
+	}
+}
+
+func splitValue(value string) []string {
+	parts := strings.Split(value, ",")
+	result := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			result = append(result, p)
+		}
+	}
+	return result
+}

package/dist/lib/templates/go/utils/types.eta

@@ -0,0 +1,50 @@
+<%~ includeFile('../../header.eta', it) %>
+
+package utils
+
+// ParsedFilter represents a single filter condition.
+type ParsedFilter struct {
+	Field    string
+	Operator string
+	Value    string
+}
+
+// ParsedSort represents a single sort directive.
+type ParsedSort struct {
+	Field     string
+	Direction string // "ASC" or "DESC"
+}
+
+// ParsedJoin represents a relation to eager-load.
+type ParsedJoin struct {
+	Relation string
+	Fields   []string // nil means load all fields
+}
+
+// QueryOptions holds the parsed query parameters for list endpoints.
+type QueryOptions struct {
+	Filters   []ParsedFilter
+	OrFilters []ParsedFilter
+	Sorts     []ParsedSort
+	Fields    []string
+	Joins     []ParsedJoin
+	Limit     int
+	Page      int
+}
+
+// PaginatedResult is the standard paginated response envelope.
+type PaginatedResult struct {
+	Data      interface{} `json:"data"`
+	Count     int         `json:"count"`
+	Total     int64       `json:"total"`
+	Page      int         `json:"page"`
+	PageCount int         `json:"pageCount"`
+}
+
+// DefaultQueryOptions returns options with default pagination values.
+func DefaultQueryOptions() QueryOptions {
+	return QueryOptions{
+		Limit: 25,
+		Page:  1,
+	}
+}

package/dist/lib/templates/python/routers/router.eta

@@ -1,7 +1,7 @@
 <%~ includeFile('../header.eta', it) %>
 
 from typing import List, Optional
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.database import get_db
@@ -14,6 +14,7 @@ from ..schemas.<%= it.entityName.toLowerCase() %> import (
     <%= it.entityName %>List,
 )
 from ..services.<%= it.entityName.toLowerCase() %> import <%= it.entityName %>Service
+from ..utils.query import parse_query_params
 
 router = APIRouter(
     prefix="/<%= it.pluralEntityName.toLowerCase() %>",
@@ -27,39 +28,30 @@ router = APIRouter(
     summary="Retrieve multiple <%= it.pluralEntityName %>",
 )
 async def get_many(
+    request: Request,
     db: AsyncSession = Depends(get_db),
-    skip: int = Query(0, ge=0),
-    limit: int = Query(10, ge=1, le=100),
-    sort: Optional[str] = Query(None, description="Sort field (prefix with - for descending)"),
-<% /* Add filter parameters for common fields */ %>
-<% it.associations.filter(a => a.type === 'ManyToOne').forEach((assoc) => { %>
-    <%= assoc.camelCasedId %>: Optional[<% if (assoc.referencedEntityPrimaryKeyType === 'uuid') { %>str<% } else { %>int<% } %>] = Query(None),
-<% }) %>
 ) -> <%= it.entityName %>List:
     """
     Retrieve a paginated list of <%= it.pluralEntityName %>.
+
+    Supports query parameters:
+    - filter=field||$operator||value (repeatable)
+    - or=field||$operator||value (repeatable)
+    - sort=field,ASC (repeatable)
+    - fields=field1,field2
+    - join=relation (repeatable)
+    - limit=25&page=1
     """
     service = <%= it.entityName %>Service(db)
-
-    filters = {}
-<% it.associations.filter(a => a.type === 'ManyToOne').forEach((assoc) => { %>
-    if <%= assoc.camelCasedId %> is not None:
-        filters["<%= assoc.camelCasedId %>"] = <%= assoc.camelCasedId %>
-<% }) %>
-
-    items, total = await service.get_many(
-        skip=skip,
-        limit=limit,
-        sort=sort,
-        filters=filters,
-    )
+    options = parse_query_params(request.query_params)
+    result = await service.get_many(options)
 
     return <%= it.entityName %>List(
-        data=items,
-        total=total,
-        page=(skip // limit) + 1 if limit > 0 else 1,
-        pageSize=limit,
-        totalPages=(total + limit - 1) // limit if limit > 0 else 1,
+        data=result.data,
+        count=result.count,
+        total=result.total,
+        page=result.page,
+        pageCount=result.page_count,
     )
 
 
@@ -70,31 +62,19 @@ async def get_many(
 )
 async def get_one(
     id: <% if (it.primaryKeyType === 'uuid') { %>str<% } else { %>int<% } %>,
+    request: Request,
     db: AsyncSession = Depends(get_db),
-<% /* Add join parameters */ %>
-<% it.associations.forEach((assoc) => { %>
-<% if (assoc.type === 'OneToMany' || assoc.type === 'ManyToMany') { %>
-    join_<%= assoc.pluralizedRelationshipName %>: bool = Query(False, alias="join[<%= assoc.pluralizedRelationshipName %>]"),
-<% } else { %>
-    join_<%= assoc.relationshipName %>: bool = Query(False, alias="join[<%= assoc.relationshipName %>]"),
-<% } %>
-<% }) %>
 ) -> <%= it.entityName %>Schema:
     """
     Retrieve a single <%= it.entityName %> by ID.
+
+    Supports query parameters:
+    - join=relation (repeatable)
     """
     service = <%= it.entityName %>Service(db)
 
-    joins = []
-<% it.associations.forEach((assoc) => { %>
-<% if (assoc.type === 'OneToMany' || assoc.type === 'ManyToMany') { %>
-    if join_<%= assoc.pluralizedRelationshipName %>:
-        joins.append("<%= assoc.pluralizedRelationshipName %>")
-<% } else { %>
-    if join_<%= assoc.relationshipName %>:
-        joins.append("<%= assoc.relationshipName %>")
-<% } %>
-<% }) %>
+    options = parse_query_params(request.query_params)
+    joins = [j.relation for j in options.joins] if options.joins else None
 
     item = await service.get_one(id, joins=joins)
     if not item:

package/dist/lib/templates/python/schemas/schema.eta

@@ -81,7 +81,7 @@ class <%= it.entityName %>(BaseModel):
 class <%= it.entityName %>List(BaseModel):
     """Paginated list response for <%= it.entityName %>"""
     data: List[<%= it.entityName %>]
+    count: int
     total: int
     page: int
-    pageSize: int
-    totalPages: int
+    pageCount: int

package/dist/lib/templates/python/services/service.eta

@@ -1,12 +1,12 @@
 <%~ includeFile('../header.eta', it) %>
 
-from typing import List, Optional, Tuple, Any, Dict
-from sqlalchemy import select, func, desc, asc
+from typing import List, Optional, Any
+
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import selectinload
 
 from ..models.<%= it.entityName.toLowerCase() %> import <%= it.entityName %>
 from ..schemas.<%= it.entityName.toLowerCase() %> import <%= it.entityName %>Create, <%= it.entityName %>Update
+from ..utils.query import QueryBuilder, QueryOptions, PaginatedResult
 
 
 class <%= it.entityName %>Service:
@@ -16,59 +16,13 @@ class <%= it.entityName %>Service:
 
     def __init__(self, db: AsyncSession):
         self.db = db
+        self._qb = QueryBuilder(<%= it.entityName %>, db)
 
-    async def get_many(
-        self,
-        skip: int = 0,
-        limit: int = 10,
-        sort: Optional[str] = None,
-        filters: Optional[Dict[str, Any]] = None,
-        joins: Optional[List[str]] = None,
-    ) -> Tuple[List[<%= it.entityName %>], int]:
+    async def get_many(self, options: QueryOptions) -> PaginatedResult:
         """
-        Retrieve a paginated list of <%= it.pluralEntityName %>.
+        Retrieve a paginated list of <%= it.pluralEntityName %> with filtering, sorting, and joins.
         """
-        # Build base query
-        query = select(<%= it.entityName %>)
-
-        # Apply filters
-        if filters:
-            for field, value in filters.items():
-                if hasattr(<%= it.entityName %>, field) and value is not None:
-                    query = query.where(getattr(<%= it.entityName %>, field) == value)
-
-        # Apply sorting
-        if sort:
-            if sort.startswith("-"):
-                query = query.order_by(desc(getattr(<%= it.entityName %>, sort[1:])))
-            else:
-                query = query.order_by(asc(getattr(<%= it.entityName %>, sort)))
-        else:
-            query = query.order_by(<%= it.entityName %>.id)
-
-        # Apply joins
-        if joins:
-            for join in joins:
-                if hasattr(<%= it.entityName %>, join):
-                    query = query.options(selectinload(getattr(<%= it.entityName %>, join)))
-
-        # Get total count
-        count_query = select(func.count()).select_from(<%= it.entityName %>)
-        if filters:
-            for field, value in filters.items():
-                if hasattr(<%= it.entityName %>, field) and value is not None:
-                    count_query = count_query.where(getattr(<%= it.entityName %>, field) == value)
-        total_result = await self.db.execute(count_query)
-        total = total_result.scalar() or 0
-
-        # Apply pagination
-        query = query.offset(skip).limit(limit)
-
-        # Execute query
-        result = await self.db.execute(query)
-        items = list(result.scalars().all())
-
-        return items, total
+        return await self._qb.get_many(options)
 
     async def get_one(
         self,
@@ -78,16 +32,7 @@ class <%= it.entityName %>Service:
         """
         Retrieve a single <%= it.entityName %> by ID.
         """
-        query = select(<%= it.entityName %>).where(<%= it.entityName %>.id == id)
-
-        # Apply joins
-        if joins:
-            for join in joins:
-                if hasattr(<%= it.entityName %>, join):
-                    query = query.options(selectinload(getattr(<%= it.entityName %>, join)))
-
-        result = await self.db.execute(query)
-        return result.scalar_one_or_none()
+        return await self._qb.get_one(id, joins=joins)
 
     async def create_one(self, data: <%= it.entityName %>Create) -> <%= it.entityName %>:
         """

package/dist/lib/templates/python/utils/init.eta

@@ -0,0 +1,21 @@
+<%~ includeFile('../header.eta', it) %>
+
+from .query import (
+    parse_query_params,
+    QueryBuilder,
+    QueryOptions,
+    PaginatedResult,
+    ParsedFilter,
+    ParsedSort,
+    ParsedJoin,
+)
+
+__all__ = [
+    "parse_query_params",
+    "QueryBuilder",
+    "QueryOptions",
+    "PaginatedResult",
+    "ParsedFilter",
+    "ParsedSort",
+    "ParsedJoin",
+]