go-duck-cli 1.0.4 → 1.0.6

package/generators/postgrest.js

@@ -35,11 +35,30 @@ func (sc *SearchController) GenericSearch(c *gin.Context) {
 			continue
 		}
 
+		// Security: Basic Sanitization for Key (Allowing letters, numbers, _, -, and JSON arrows)
+		// We split the key if it contains JSON operators to handle them specifically
+		processedKey := key
+		if strings.Contains(key, "->") {
+			parts := strings.SplitN(key, "->", 2)
+			column := parts[0]
+			path := parts[1]
+			operator := "->"
+			if strings.HasPrefix(path, ">") {
+				operator = "->>"
+				path = path[1:]
+			}
+			// Wrap column in quotes and path in single quotes for Postgres JSONB safety
+			processedKey = fmt.Sprintf("\"%s\"%s'%s'", column, operator, path)
+		} else {
+			// Standard column: Wrap in quotes for safety
+			processedKey = fmt.Sprintf("\"%s\"", key)
+		}
+
 		for _, val := range values {
 			parts := strings.SplitN(val, ".", 2)
 			if len(parts) < 2 {
 				// Default to equality
-				query = query.Where(fmt.Sprintf("%s = ?", key), val)
+				query = query.Where(processedKey+" = ?", val)
 				continue
 			}
 
@@ -48,24 +67,27 @@ func (sc *SearchController) GenericSearch(c *gin.Context) {
 
 			switch op {
 			case "eq":
-				query = query.Where(fmt.Sprintf("%s = ?", key), target)
+				query = query.Where(processedKey+" = ?", target)
 			case "neq":
-				query = query.Where(fmt.Sprintf("%s <> ?", key), target)
+				query = query.Where(processedKey+" <> ?", target)
 			case "gt":
-				query = query.Where(fmt.Sprintf("%s > ?", key), target)
+				query = query.Where(processedKey+" > ?", target)
 			case "gte":
-				query = query.Where(fmt.Sprintf("%s >= ?", key), target)
+				query = query.Where(processedKey+" >= ?", target)
 			case "lt":
-				query = query.Where(fmt.Sprintf("%s < ?", key), target)
+				query = query.Where(processedKey+" < ?", target)
 			case "lte":
-				query = query.Where(fmt.Sprintf("%s <= ?", key), target)
+				query = query.Where(processedKey+" <= ?", target)
 			case "like":
-				query = query.Where(fmt.Sprintf("%s LIKE ?", key), "%"+target+"%")
+				query = query.Where(processedKey+" LIKE ?", "%"+target+"%")
 			case "ilike":
-				query = query.Where(fmt.Sprintf("%s ILIKE ?", key), "%"+target+"%")
+				query = query.Where(processedKey+" ILIKE ?", "%"+target+"%")
 			case "in":
 				list := strings.Split(target, ",")
-				query = query.Where(fmt.Sprintf("%s IN ?", key), list)
+				query = query.Where(processedKey+" IN ?", list)
+			default:
+				// Fallback to equality if operator is unrecognized
+				query = query.Where(processedKey+" = ?", val)
 			}
 		}
 	}

package/generators/swagger.js

@@ -18,6 +18,19 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
         ],
         paths: {},
         components: {
+            securitySchemes: {
+                BearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT'
+                },
+                TenantID: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'X-Tenant-ID',
+                    description: 'The unique identifier for the tenant dashboard context'
+                }
+            },
             schemas: {
                 Error: {
                     type: 'object',
@@ -26,9 +39,16 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
                     }
                 }
             }
-        }
+        },
+        security: [
+            { BearerAuth: [], TenantID: [] }
+        ]
     };
 
+    const commonHeaders = [
+        { name: 'X-Tenant-ID', in: 'header', required: true, schema: { type: 'string', default: 'default' }, description: 'Multi-tenancy context identifier' }
+    ];
+
     // 1. Add Entity Paths
     for (const entity of entities) {
         const name = entity.name.toLowerCase();
@@ -53,6 +73,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             post: {
                 tags: [capitalized],
                 summary: `Create a new ${capitalized}`,
+                parameters: [...commonHeaders],
                 requestBody: {
                     required: true,
                     content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } }
@@ -65,9 +86,10 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
                 tags: [capitalized],
                 summary: `Get all ${capitalized}s`,
                 parameters: [
-                    { name: 'page', in: 'query', schema: { type: 'integer' } },
-                    { name: 'size', in: 'query', schema: { type: 'integer' } },
-                    { name: 'eager', in: 'query', schema: { type: 'boolean' } }
+                    ...commonHeaders,
+                    { name: 'page', in: 'query', schema: { type: 'integer' }, description: 'Zero-based page index' },
+                    { name: 'size', in: 'query', schema: { type: 'integer' }, description: 'Records per page' },
+                    { name: 'eager', in: 'query', schema: { type: 'boolean' }, description: 'If true, performs SQL Join to fetch relations' }
                 ],
                 responses: {
                     200: { description: 'OK', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
@@ -80,7 +102,11 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             get: {
                 tags: [capitalized],
                 summary: `Get ${capitalized} by ID`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [
+                    ...commonHeaders,
+                    { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
+                    { name: 'eager', in: 'query', schema: { type: 'boolean' } }
+                ],
                 responses: {
                     200: { description: 'OK', content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } } }
                 }
@@ -88,7 +114,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             put: {
                 tags: [capitalized],
                 summary: `Update ${capitalized}`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [...commonHeaders, { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
                 responses: {
                     200: { description: 'Updated', content: { 'application/json': { schema: { $ref: `#/components/schemas/${capitalized}` } } } }
                 }
@@ -96,32 +122,105 @@ export const generateSwaggerDocs = async (config, entities, outputDir) => {
             delete: {
                 tags: [capitalized],
                 summary: `Delete ${capitalized}`,
-                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
+                parameters: [...commonHeaders, { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }],
                 responses: {
                     204: { description: 'No Content' }
                 }
             }
         };
+
+        // BULK Operations /entities/bulk
+        swagger.paths[`/${name}s/bulk`] = {
+            post: {
+                tags: [capitalized],
+                summary: `Bulk Create ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } }
+                },
+                responses: {
+                    201: { description: 'Created', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
+                }
+            },
+            put: {
+                tags: [capitalized],
+                summary: `Bulk Update ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } }
+                },
+                responses: {
+                    200: { description: 'Updated', content: { 'application/json': { schema: { type: 'array', items: { $ref: `#/components/schemas/${capitalized}` } } } } }
+                }
+            },
+            patch: {
+                tags: [capitalized],
+                summary: `Bulk Patch ${capitalized}s`,
+                parameters: [...commonHeaders],
+                requestBody: {
+                    required: true,
+                    content: { 
+                        'application/json': { 
+                            schema: { 
+                                type: 'array', 
+                                items: { 
+                                    type: 'object',
+                                    properties: {
+                                        id: { type: 'integer' },
+                                        changes: { type: 'object' }
+                                    }
+                                } 
+                            } 
+                        } 
+                    }
+                },
+                responses: {
+                    200: { description: 'Patched' }
+                }
+            }
+        };
     }
 
     // 2. Add System Paths
     swagger.paths['/rpc/{table}'] = {
         get: {
-            tags: ['Search'],
-            summary: 'Generic PostgREST-like Search',
+            tags: ['Search Engine'],
+            summary: 'Generic PostgREST RPC Engine',
+            description: `Powerful dynamic querying system. 
+            
+            ### Dynamic Filtering
+            Append any column name as a query parameter using operator notation:
+            - \`?age=gt.20\` (Greater Than)
+            - \`?name=ilike.John\` (Case-insensitive search)
+            - \`?id=in.1,2,3\` (Set containment)
+            
+            ### JSONB Path Querying
+            For JSON fields, use arrow notation:
+            - \`?metadata->>role=eq.ADMIN\` (Nested text extraction)
+            - \`?details->count=gt.5\` (Nested numeric extraction)`,
             parameters: [
-                { name: 'table', in: 'path', required: true, schema: { type: 'string' } },
-                { name: 'order', in: 'query', schema: { type: 'string' } },
-                { name: 'limit', in: 'query', schema: { type: 'integer' } }
+                ...commonHeaders,
+                { name: 'table', in: 'path', required: true, schema: { type: 'string' }, description: 'The database table to query' },
+                { name: 'order', in: 'query', schema: { type: 'string' }, description: 'Sorting (e.g., id.desc)' },
+                { name: 'limit', in: 'query', schema: { type: 'integer' }, description: 'Row limit' },
+                { name: 'offset', in: 'query', schema: { type: 'integer' }, description: 'Query offset' }
             ],
-            responses: { 200: { description: 'OK' } }
+            responses: { 
+                200: { 
+                    description: 'OK', 
+                    content: { 'application/json': { schema: { type: 'array', items: { type: 'object' } } } } 
+                } 
+            }
         }
     };
 
     swagger.paths['/audit'] = {
         get: {
-            tags: ['Audit'],
-            summary: 'View Audit Logs',
+            tags: ['Observability'],
+            summary: 'Fetch Audit Trail',
+            parameters: [...commonHeaders],
             responses: { 200: { description: 'OK' } }
         }
     };
@@ -139,7 +238,10 @@ const mapToSwaggerType = (type) => {
         'Long': 'integer',
         'BigDecimal': 'number',
         'LocalDate': 'string',
-        'Instant': 'string'
+        'Instant': 'string',
+        'JSON': 'object',
+        'JSONB': 'object',
+        'Text': 'string'
     };
     return types[type] || 'string';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-duck-cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "go function generator",
   "main": "index.js",
   "type": "module",

package/templates/docs/pages/rest.hbs

@@ -124,6 +124,84 @@
             </div>
         </div>
     </div>
+
+    <!-- JSON Querying Section -->
+    <div class="bg-white border border-slate-200 rounded-2xl p-8 shadow-sm">
+        <h4 class="text-xl font-bold text-slate-900 mb-4 flex items-center">
+            <svg class="w-6 h-6 mr-3 text-indigo-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"></path></svg>
+            Deep JSON/JSONB Querying
+        </h4>
+        <p class="text-slate-600 text-sm mb-6 leading-relaxed">
+            The GO-DUCK generator natively supports PostgreSQL JSONB operators. You can drill down into nested fields directly from the URL using arrow notation.
+        </p>
+        
+        <div class="space-y-4">
+            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
+                <div class="flex items-center justify-between mb-2">
+                    <span class="text-xs font-bold text-indigo-600 uppercase tracking-widest">Text Extraction (->>)</span>
+                    <span class="px-2 py-0.5 rounded bg-indigo-100 text-indigo-700 text-[10px] font-bold">Standard Use</span>
+                </div>
+                <code class="text-xs text-slate-800">GET /api/rpc/users?metadata->>role=eq.ADMIN</code>
+                <p class="text-[11px] text-slate-500 mt-2">Extracts the value as text. Perfect for equality checks on nested strings.</p>
+            </div>
+
+            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
+                <div class="flex items-center justify-between mb-2">
+                    <span class="text-xs font-bold text-purple-600 uppercase tracking-widest">Object Extraction (->)</span>
+                </div>
+                <code class="text-xs text-slate-800">GET /api/rpc/orders?details->itemsCount=gt.5</code>
+                <p class="text-[11px] text-slate-500 mt-2">Treats the extracted value as a JSON object/numeric, allowing for range checks on nested numbers.</p>
+            </div>
+        </div>
+
+        <div class="mt-6 p-4 bg-amber-50 rounded-xl border border-amber-100">
+            <p class="text-[11px] text-amber-800 leading-relaxed">
+                <strong>Pro Tip:</strong> For high-performance JSON querying, ensure you have a <code>GIN</code> index on the JSONB column in your database.
+            </p>
+        </div>
+    </div>
+</section>
+
+<section class="mb-12">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-orange-100 text-orange-600 flex items-center justify-center mr-3 text-sm">
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
+        </span>
+        Bulk Mission Control (High Velocity)
+    </h2>
+    <p class="text-slate-600 text-sm mb-6 leading-relaxed">
+        For batch processing and migrations, avoid the overhead of multiple HTTP calls. Use the specialized <code class="bg-orange-50 px-1 rounded text-orange-700">/bulk</code> endpoints to process hundreds of records in a single transaction.
+    </p>
+
+    <div class="space-y-6">
+        <!-- Bulk Create -->
+        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
+            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
+                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Bulk Create Transaction</span>
+                <span class="px-2 py-0.5 rounded bg-emerald-100 text-emerald-700 text-[10px] font-bold">POST /api/:entities/bulk</span>
+            </div>
+            <div class="p-6">
+                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
+  { "title": "Bulk Article A", "status": "DRAFT" },
+  { "title": "Bulk Article B", "status": "PUBLISHED" }
+]</pre>
+            </div>
+        </div>
+
+        <!-- Bulk Patch -->
+        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
+            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
+                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Multi-Entity Patch</span>
+                <span class="px-2 py-0.5 rounded bg-blue-100 text-blue-700 text-[10px] font-bold">PATCH /api/:entities/bulk</span>
+            </div>
+            <div class="p-6">
+                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
+  { "id": 1, "changes": { "status": "ARCHIVED" } },
+  { "id": 2, "changes": { "title": "Updated Title via Bulk" } }
+]</pre>
+            </div>
+        </div>
+    </div>
 </section>
 
 <section class="mb-12">

package/templates/go/controller.go.hbs

@@ -205,6 +205,104 @@ return nil, nil
 c.JSON(http.StatusOK, gin.H{"message": "Updated successfully", "data": entity})
 }
 
+// BulkCreate handles creating multiple entities in one transaction
+func (ctrl *{{capitalize name}}Controller) BulkCreate(c *gin.Context) {
+	tenant, _ := c.Get("tenantDB")
+	tenantStr := fmt.Sprintf("%v", tenant)
+	ctx := c.Request.Context()
+
+	var entities []models.{{capitalize name}}
+	if err := c.ShouldBindJSON(&entities); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := ctrl.DB.WithContext(ctx).Create(&entities).Error; err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Dynamic Cache Invalidation (Tenant Aware)
+	cache.ClearPattern(tenantStr + ":{{capitalize name}}*")
+
+	// MQTT Event (Resilient)
+	resilience.Execute(func() (interface{}, error) {
+		messaging.PublishEvent(ctrl.Config.GoDuck.Messaging.MQTT.TopicPrefix, "BULK_CREATE", "{{capitalize name}}", entities, nil)
+		return nil, nil
+	})
+
+	c.JSON(http.StatusCreated, entities)
+}
+
+// BulkUpdate handles updating multiple entities in one transaction
+func (ctrl *{{capitalize name}}Controller) BulkUpdate(c *gin.Context) {
+	tenant, _ := c.Get("tenantDB")
+	tenantStr := fmt.Sprintf("%v", tenant)
+	ctx := c.Request.Context()
+
+	var entities []models.{{capitalize name}}
+	if err := c.ShouldBindJSON(&entities); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	err := ctrl.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, e := range entities {
+			if err := tx.Save(&e).Error; err != nil {
+				return err
+			}
+			cache.Delete(fmt.Sprintf("%s:{{capitalize name}}:%d", tenantStr, e.ID))
+		}
+		return nil
+	})
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// MQTT Event (Resilient)
+	resilience.Execute(func() (interface{}, error) {
+		messaging.PublishEvent(ctrl.Config.GoDuck.Messaging.MQTT.TopicPrefix, "BULK_UPDATE", "{{capitalize name}}", entities, nil)
+		return nil, nil
+	})
+
+	c.JSON(http.StatusOK, entities)
+}
+
+// BulkPatch handles partial updates for multiple entities
+func (ctrl *{{capitalize name}}Controller) BulkPatch(c *gin.Context) {
+	tenant, _ := c.Get("tenantDB")
+	tenantStr := fmt.Sprintf("%v", tenant)
+	ctx := c.Request.Context()
+
+	var updates []struct {
+		ID      uint                   `json:"id"`
+		Changes map[string]interface{} `json:"changes"`
+	}
+	if err := c.ShouldBindJSON(&updates); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	err := ctrl.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, u := range updates {
+			if err := tx.Model(&models.{{capitalize name}}{}).Where("id = ?", u.ID).Updates(u.Changes).Error; err != nil {
+				return err
+			}
+			cache.Delete(fmt.Sprintf("%s:{{capitalize name}}:%d", tenantStr, u.ID))
+		}
+		return nil
+	})
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "Bulk patch completed successfully"})
+}
+
 // Delete
 func (ctrl *{{capitalize name}}Controller) Delete(c *gin.Context) {
 id := c.Param("id")

package/templates/go/main.go.hbs

@@ -163,10 +163,13 @@ api.GET("/rpc/:table", searchCtrl.GenericSearch)
 // {{name}} Routes
 {{toLowerCase name}}Ctrl := controllers.{{capitalize name}}Controller{DB: masterDB, Config: appConfig}
 api.POST("/{{toLowerCase name}}s", {{toLowerCase name}}Ctrl.Create)
+api.POST("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkCreate)
 api.GET("/{{toLowerCase name}}s", {{toLowerCase name}}Ctrl.GetAll)
 api.GET("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.GetByID)
 api.PUT("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Update)
+api.PUT("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkUpdate)
 api.PATCH("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Patch)
+api.PATCH("/{{toLowerCase name}}s/bulk", {{toLowerCase name}}Ctrl.BulkPatch)
 api.DELETE("/{{toLowerCase name}}s/:id", {{toLowerCase name}}Ctrl.Delete)
 {{/each}}
 // go-duck-needle-add-route