@avtechno/sfr 2.1.0 → 2.1.2

package/dist/index.mjs

@@ -58,16 +58,26 @@ async function write_combined_openapi_index(cfg, documents) {
     const combined = {
         openapi: "3.1.0",
         info: {},
-        paths: {}
+        paths: {},
+        components: {
+            schemas: {}
+        }
     };
     for (const [protocol, documentation] of Object.entries(documents)) {
         switch (protocol) {
             case "REST":
                 {
                     const rest_doc = documentation;
-                    // Merge REST OpenAPI info and paths into combined doc
+                    // Merge REST OpenAPI info, paths, and components into combined doc
                     combined.info = rest_doc.info;
                     combined.paths = rest_doc.paths;
+                    // Merge component schemas if they exist
+                    if (rest_doc.components?.schemas) {
+                        combined.components.schemas = {
+                            ...combined.components.schemas,
+                            ...rest_doc.components.schemas
+                        };
+                    }
                 }
                 break;
         }

package/dist/sfr-pipeline.mjs

@@ -509,7 +509,10 @@ export class SFRPipeline {
         const spec = {
             openapi: "3.0.0",
             info: Object.assign({}, this.oas_cfg),
-            paths: {}
+            paths: {},
+            components: {
+                schemas: {}
+            }
         };
         // Iterate through each protocol (e.g., REST, WS, MQ)
         Object.entries(declaration).forEach(([namespace, module]) => {
@@ -623,9 +626,30 @@ export class SFRPipeline {
                             document.description = (document.description || "") + rate_limit_note;
                         }
                     }
+                    // Generate schema name from namespace and endpoint
+                    const schema_name = this.generate_schema_name(namespace, endpoint, method);
                     //Insert either a parameter or a requestBody according to the method type
                     if (validator_type === "joi") {
-                        document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
+                        const swagger_schema = j2s(validator).swagger;
+                        if (method === "get") {
+                            // For GET requests, convert schema properties to query parameters
+                            document.parameters = this.convert_schema_to_query_parameters(swagger_schema, schema_name, spec);
+                        }
+                        else {
+                            // For POST/PUT/PATCH/DELETE, use requestBody with application/json
+                            // Store schema in components
+                            spec.components.schemas[schema_name] = swagger_schema;
+                            document.requestBody = {
+                                required: true,
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            $ref: `#/components/schemas/${schema_name}`
+                                        }
+                                    }
+                                }
+                            };
+                        }
                     }
                     // Convert Multer validators to multipart/form-data OpenAPI schema
                     if (validator_type === "multer") {
@@ -644,6 +668,71 @@ export class SFRPipeline {
         spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v]) => [`x-${k}`, v]));
         return spec;
     }
+    /**
+     * Generates a unique schema name from namespace, endpoint, and method.
+     */
+    generate_schema_name(namespace, endpoint, method) {
+        // Convert to PascalCase and create a descriptive schema name
+        const pascal_case = (str) => str
+            .split(/[-_]/)
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .join('');
+        const method_prefix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+        const namespace_part = pascal_case(namespace);
+        const endpoint_part = pascal_case(endpoint);
+        return `${method_prefix}${namespace_part}${endpoint_part}Request`;
+    }
+    /**
+     * Converts a JSON schema to OpenAPI query parameters array.
+     * Stores complex schemas in components and references them.
+     */
+    convert_schema_to_query_parameters(schema, base_name, spec) {
+        const parameters = [];
+        if (!schema || !schema.properties) {
+            return parameters;
+        }
+        const required_fields = schema.required || [];
+        for (const [prop_name, prop_schema] of Object.entries(schema.properties)) {
+            const param_schema = prop_schema;
+            const is_required = required_fields.includes(prop_name);
+            // Check if the property is a complex type (object or array of objects)
+            const is_complex = param_schema.type === 'object' ||
+                (param_schema.type === 'array' && param_schema.items?.type === 'object');
+            if (is_complex) {
+                // Store complex schemas in components and reference them
+                const component_name = `${base_name}${prop_name.charAt(0).toUpperCase() + prop_name.slice(1)}`;
+                spec.components.schemas[component_name] = param_schema;
+                parameters.push({
+                    name: prop_name,
+                    in: "query",
+                    required: is_required,
+                    description: param_schema.description || "",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                $ref: `#/components/schemas/${component_name}`
+                            }
+                        }
+                    }
+                });
+            }
+            else {
+                // Simple types can be defined inline
+                const param = {
+                    name: prop_name,
+                    in: "query",
+                    required: is_required,
+                    schema: { ...param_schema }
+                };
+                if (param_schema.description) {
+                    param.description = param_schema.description;
+                    delete param.schema.description;
+                }
+                parameters.push(param);
+            }
+        }
+        return parameters;
+    }
     // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
     generate_ws_async_api_document(declaration) {
         const spec = {

package/dist/types/sfr-pipeline.d.mts

@@ -68,6 +68,15 @@ export declare class SFRPipeline {
     private bind_mq_fns;
     private spec_generation;
     private generate_open_api_document;
+    /**
+     * Generates a unique schema name from namespace, endpoint, and method.
+     */
+    private generate_schema_name;
+    /**
+     * Converts a JSON schema to OpenAPI query parameters array.
+     * Stores complex schemas in components and references them.
+     */
+    private convert_schema_to_query_parameters;
     private generate_ws_async_api_document;
     private generate_mq_async_api_document;
     private print_to_console;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avtechno/sfr",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "An opinionated way of writing services using ExpressJS.",
   "type": "module",
   "files": [

package/src/index.mts

@@ -68,16 +68,27 @@ async function write_combined_openapi_index(cfg: ParserCFG, documents: ServiceDo
   const combined: any = {
     openapi: "3.1.0",
     info: {},
-    paths: {}
+    paths: {},
+    components: {
+      schemas: {}
+    }
   };
 
   for (const [protocol, documentation] of Object.entries(documents)) {
     switch (protocol) {
       case "REST": {
         const rest_doc = documentation as OAPI_Document;
-        // Merge REST OpenAPI info and paths into combined doc
+        // Merge REST OpenAPI info, paths, and components into combined doc
         combined.info = rest_doc.info;
         combined.paths = rest_doc.paths;
+        
+        // Merge component schemas if they exist
+        if (rest_doc.components?.schemas) {
+          combined.components.schemas = {
+            ...combined.components.schemas,
+            ...rest_doc.components.schemas
+          };
+        }
       } break;
     }
   }
@@ -178,6 +189,8 @@ export {
   type LoggerConfig
 } from "./observability/logger.mjs";
 
+export { sfr_rest_telemetry } from "./observability/middleware/rest.mjs";
+
 export { 
   REST, 
   WS, 

package/src/observability/logger.mts

@@ -9,23 +9,23 @@ import { trace } from "@opentelemetry/api";
 
 // Define log levels matching standard syslog levels
 const levels = {
-  error: 0,
-  warn: 1,
-  info: 2,
-  http: 3,
-  verbose: 4,
-  debug: 5,
-  silly: 6
+  error   : 0,
+  warn    : 1,
+  info    : 2,
+  http    : 3,
+  verbose : 4,
+  debug   : 5,
+  silly   : 6
 };
 
 const colors = {
-  error: "red",
-  warn: "yellow",
-  info: "green",
-  http: "magenta",
-  verbose: "cyan",
-  debug: "blue",
-  silly: "gray"
+  error   : "red",
+  warn    : "yellow",
+  info    : "green",
+  http    : "magenta",
+  verbose : "cyan",
+  debug   : "blue",
+  silly   : "gray"
 };
 
 winston.addColors(colors);
@@ -74,14 +74,10 @@ const pretty_format = winston.format.combine(
   winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss.SSS" }),
   winston.format.colorize({ all: true }),
   winston.format.printf((info) => {
-    const trace_suffix = info.trace_id
-      ? ` [${String(info.trace_id).slice(0, 8)}]`
-      : "";
+    const trace_suffix = info.trace_id ? ` [${String(info.trace_id).slice(0, 8)}]` : "";
 
     let meta_str = "";
-    const meta_keys = Object.keys(info).filter(
-      (k) => !["level", "message", "timestamp", "trace_id", "span_id", "trace_flags", "service"].includes(k)
-    );
+    const meta_keys = Object.keys(info).filter((k) => !["level", "message", "timestamp", "trace_id", "span_id", "trace_flags", "service"].includes(k));
 
     if (meta_keys.length > 0) {
       const meta_obj: Record<string, any> = {};
@@ -89,7 +85,7 @@ const pretty_format = winston.format.combine(
       meta_str = ` ${JSON.stringify(meta_obj)}`;
     }
 
-    return `${info.timestamp} ${info.level}${trace_suffix}: ${info.message}${meta_str}`;
+    return `[${info.timestamp}][${info.level}]${trace_suffix}: ${info.message} > ${meta_str}`;
   })
 );
 
@@ -150,13 +146,13 @@ export function create_child_logger(meta: Record<string, any>): winston.Logger {
  * Automatically includes trace context when available.
  */
 export const sfr_logger = {
-  error: (message: string, meta?: Record<string, any>) => get_logger().error(message, meta),
-  warn: (message: string, meta?: Record<string, any>) => get_logger().warn(message, meta),
-  info: (message: string, meta?: Record<string, any>) => get_logger().info(message, meta),
-  http: (message: string, meta?: Record<string, any>) => get_logger().http(message, meta),
-  verbose: (message: string, meta?: Record<string, any>) => get_logger().verbose(message, meta),
-  debug: (message: string, meta?: Record<string, any>) => get_logger().debug(message, meta),
-  silly: (message: string, meta?: Record<string, any>) => get_logger().silly(message, meta),
+  error   : (message: string, meta?: Record<string, any>) => get_logger().error(message, meta),
+  warn    : (message: string, meta?: Record<string, any>) => get_logger().warn(message, meta),
+  info    : (message: string, meta?: Record<string, any>) => get_logger().info(message, meta),
+  http    : (message: string, meta?: Record<string, any>) => get_logger().http(message, meta),
+  verbose : (message: string, meta?: Record<string, any>) => get_logger().verbose(message, meta),
+  debug   : (message: string, meta?: Record<string, any>) => get_logger().debug(message, meta),
+  silly   : (message: string, meta?: Record<string, any>) => get_logger().silly(message, meta),
 
   /**
    * Creates a child logger with additional context.

package/src/observability/metrics.mts

@@ -20,26 +20,26 @@ const METER_VERSION = "1.0.0";
  */
 export interface SFRMetrics {
   // REST Metrics
-  rest_requests_total: Counter;
-  rest_request_duration: Histogram;
-  rest_errors_total: Counter;
-  rest_request_size: Histogram;
-  rest_response_size: Histogram;
+  rest_requests_total   : Counter;
+  rest_request_duration : Histogram;
+  rest_errors_total     : Counter;
+  rest_request_size     : Histogram;
+  rest_response_size    : Histogram;
 
   // WebSocket Metrics
-  ws_connections_active: UpDownCounter;
-  ws_connections_total: Counter;
-  ws_events_total: Counter;
-  ws_event_duration: Histogram;
-  ws_errors_total: Counter;
+  ws_connections_active : UpDownCounter;
+  ws_connections_total  : Counter;
+  ws_events_total       : Counter;
+  ws_event_duration     : Histogram;
+  ws_errors_total       : Counter;
 
   // MQ Metrics
-  mq_messages_received: Counter;
-  mq_messages_published: Counter;
-  mq_processing_duration: Histogram;
-  mq_errors_total: Counter;
-  mq_messages_rejected: Counter;
-  mq_messages_acked: Counter;
+  mq_messages_received   : Counter;
+  mq_messages_published  : Counter;
+  mq_processing_duration : Histogram;
+  mq_errors_total        : Counter;
+  mq_messages_rejected   : Counter;
+  mq_messages_acked      : Counter;
 }
 
 let sfr_metrics: SFRMetrics | null = null;

package/src/observability/middleware/mq.mts

@@ -53,9 +53,7 @@ export function wrap_mq_handler(
     const ctx = trace.setSpan(parent_context, span);
 
     // Record received metric
-    if (metrics) {
-      metrics.mq_messages_received.add(1, { queue, pattern });
-    }
+    if (metrics) metrics.mq_messages_received.add(1, { queue, pattern });
 
     try {
       await context.with(ctx, async () => {

package/src/observability/middleware/rest.mts

@@ -48,7 +48,7 @@ export function sfr_rest_telemetry() {
           "http.user_agent": req.get("user-agent") ?? "unknown",
           "http.request_content_length": req.get("content-length") ?? 0,
           "sfr.protocol": "REST",
-          "sfr.route": route
+          "sfr.route": route,
         }
       },
       parent_context

package/src/sfr-pipeline.mts

@@ -88,6 +88,7 @@ export class SFRPipeline {
 
   async init(base_url?: string): Promise<ServiceDocuments> {
     this.base_url = base_url;
+    const observability_enabled = is_observability_enabled();
 
     // Initialize observability with service config from oas_cfg
     if (SFRPipeline.observability_options.enabled !== false) {
@@ -95,12 +96,12 @@ export class SFRPipeline {
     }
 
     // Add REST telemetry middleware if enabled
-    if (this.comms["REST"] && is_observability_enabled()) {
+    if (this.comms["REST"] && observability_enabled) {
       this.comms["REST"].use(sfr_rest_telemetry());
     }
 
     // Instrument Socket.IO if enabled
-    if (this.comms["WS"] && is_observability_enabled()) {
+    if (this.comms["WS"] && observability_enabled) {
       instrument_socket_io(this.comms["WS"]);
     }
 
@@ -562,7 +563,10 @@ export class SFRPipeline {
     const spec: OAPI_Document = {
       openapi: "3.0.0",
       info : Object.assign({}, this.oas_cfg),
-      paths: {}
+      paths: {},
+      components: {
+        schemas: {}
+      }
     };
 
     // Iterate through each protocol (e.g., REST, WS, MQ)
@@ -686,9 +690,32 @@ export class SFRPipeline {
             }
           }
 
+          // Generate schema name from namespace and endpoint
+          const schema_name = this.generate_schema_name(namespace, endpoint, method);
+
           //Insert either a parameter or a requestBody according to the method type
-          if(validator_type === "joi"){
-            document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
+          if (validator_type === "joi") {
+            const swagger_schema = j2s(validator).swagger;
+            
+            if (method === "get") {
+              // For GET requests, convert schema properties to query parameters
+              document.parameters = this.convert_schema_to_query_parameters(swagger_schema, schema_name, spec);
+            } else {
+              // For POST/PUT/PATCH/DELETE, use requestBody with application/json
+              // Store schema in components
+              spec.components.schemas[schema_name] = swagger_schema;
+              
+              document.requestBody = {
+                required: true,
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: `#/components/schemas/${schema_name}`
+                    }
+                  }
+                }
+              };
+            }
           }
 
           // Convert Multer validators to multipart/form-data OpenAPI schema
@@ -710,6 +737,83 @@ export class SFRPipeline {
     return spec;
   }
 
+  /**
+   * Generates a unique schema name from namespace, endpoint, and method.
+   */
+  private generate_schema_name(namespace: string, endpoint: string, method: string): string {
+    // Convert to PascalCase and create a descriptive schema name
+    const pascal_case = (str: string) => str
+      .split(/[-_]/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+    
+    const method_prefix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+    const namespace_part = pascal_case(namespace);
+    const endpoint_part = pascal_case(endpoint);
+    
+    return `${method_prefix}${namespace_part}${endpoint_part}Request`;
+  }
+
+  /**
+   * Converts a JSON schema to OpenAPI query parameters array.
+   * Stores complex schemas in components and references them.
+   */
+  private convert_schema_to_query_parameters(schema: any, base_name: string, spec: OAPI_Document): any[] {
+    const parameters: any[] = [];
+    
+    if (!schema || !schema.properties) {
+      return parameters;
+    }
+
+    const required_fields = schema.required || [];
+
+    for (const [prop_name, prop_schema] of Object.entries(schema.properties)) {
+      const param_schema: any = prop_schema;
+      const is_required = required_fields.includes(prop_name);
+      
+      // Check if the property is a complex type (object or array of objects)
+      const is_complex = param_schema.type === 'object' || 
+        (param_schema.type === 'array' && param_schema.items?.type === 'object');
+
+      if (is_complex) {
+        // Store complex schemas in components and reference them
+        const component_name = `${base_name}${prop_name.charAt(0).toUpperCase() + prop_name.slice(1)}`;
+        spec.components.schemas[component_name] = param_schema;
+
+        parameters.push({
+          name: prop_name,
+          in: "query",
+          required: is_required,
+          description: param_schema.description || "",
+          content: {
+            "application/json": {
+              schema: {
+                $ref: `#/components/schemas/${component_name}`
+              }
+            }
+          }
+        });
+      } else {
+        // Simple types can be defined inline
+        const param: any = {
+          name: prop_name,
+          in: "query",
+          required: is_required,
+          schema: { ...param_schema }
+        };
+
+        if (param_schema.description) {
+          param.description = param_schema.description;
+          delete param.schema.description;
+        }
+
+        parameters.push(param);
+      }
+    }
+
+    return parameters;
+  }
+
   // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
   private generate_ws_async_api_document(declaration: WSNamespaceDeclaration): AsyncAPIDocument {
     const spec: any = {