@engjts/nexus 0.1.0

package/src/advanced/swagger/types.ts

@@ -0,0 +1,206 @@
+import { Context } from 'vm';
+import { Application } from '../../core/application';
+import { HTTPMethod, SchemaConfig, RouteMeta, RouteConfig } from '../../core/types';
+import { Plugin } from '../static/spa';
+
+/**
+ * Extended Application interface for Swagger plugin
+ */
+
+export interface SwaggerApplication extends Application {
+  swaggerSchema?: (name: string, schema: OpenAPISchema) => SwaggerApplication;
+  [key: string]: unknown;
+}
+
+// ============================================
+// TYPES & INTERFACES
+// ============================================
+
+/**
+ * OpenAPI Info object
+ */
+export interface SwaggerInfo {
+  title?: string;
+  version?: string;
+  description?: string;
+  termsOfService?: string;
+  contact?: {
+    name?: string;
+    url?: string;
+    email?: string;
+  };
+  license?: {
+    name: string;
+    url?: string;
+  };
+}
+
+/**
+ * Custom theme for Swagger UI
+ */
+export interface SwaggerTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  headerColor?: string;
+  textColor?: string;
+  fontFamily?: string;
+}
+
+/**
+ * Swagger configuration options
+ */
+export interface SwaggerConfig {
+  /** Path to serve Swagger UI (default: /docs) */
+  path?: string;
+  /** Path to serve OpenAPI JSON spec (default: /openapi.json) */
+  specPath?: string;
+  /** API info - auto-detected from package.json if not provided */
+  info?: SwaggerInfo;
+  /** Server URLs - auto-detected if not provided */
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  /** Security schemes */
+  securitySchemes?: Record<string, SecurityScheme>;
+  /** Default security for all routes */
+  security?: Array<Record<string, string[]>>;
+  /** External docs */
+  externalDocs?: {
+    description?: string;
+    url: string;
+  };
+  /** Custom CSS for Swagger UI */
+  customCss?: string;
+  /** Custom favicon URL */
+  favicon?: string;
+  /** Theme: 'light' | 'dark' | custom theme object */
+  theme?: 'light' | 'dark' | SwaggerTheme;
+  /** Tags to group endpoints */
+  tags?: Array<{ name: string; description?: string }>;
+  /** Hide routes that don't have meta.tags */
+  hideUntagged?: boolean;
+  /** Sort tags alphabetically */
+  sortTags?: boolean;
+  /** Expand operations by default: 'list' | 'full' | 'none' */
+  docExpansion?: 'list' | 'full' | 'none';
+  /** Filter operations by tag */
+  filter?: boolean;
+  /** Try it out enabled by default */
+  tryItOutEnabled?: boolean;
+  /** Persist authorization */
+  persistAuthorization?: boolean;
+}
+
+/**
+ * Security scheme types
+ */
+export interface SecurityScheme {
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+  description?: string;
+  name?: string;
+  in?: 'query' | 'header' | 'cookie';
+  scheme?: string;
+  bearerFormat?: string;
+  flows?: OAuthFlows;
+  openIdConnectUrl?: string;
+}
+
+export interface OAuthFlows {
+  implicit?: OAuthFlow;
+  password?: OAuthFlow;
+  clientCredentials?: OAuthFlow;
+  authorizationCode?: OAuthFlow;
+}
+
+export interface OAuthFlow {
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes: Record<string, string>;
+}
+
+/**
+ * OpenAPI Schema object
+ */
+export interface OpenAPISchema {
+  type?: string;
+  format?: string;
+  properties?: Record<string, OpenAPISchema>;
+  items?: OpenAPISchema;
+  required?: string[];
+  enum?: any[];
+  description?: string;
+  example?: any;
+  default?: any;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  nullable?: boolean;
+  $ref?: string;
+}
+
+/**
+ * OpenAPI Operation object
+ */
+export interface OpenAPIOperation {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  parameters?: OpenAPIParameter[];
+  requestBody?: OpenAPIRequestBody;
+  responses: Record<string, OpenAPIResponse>;
+  deprecated?: boolean;
+  security?: Array<Record<string, string[]>>;
+}
+
+export interface OpenAPIParameter {
+  name: string;
+  in: 'query' | 'header' | 'path' | 'cookie';
+  description?: string;
+  required?: boolean;
+  schema: OpenAPISchema;
+  example?: any;
+}
+
+export interface OpenAPIRequestBody {
+  description?: string;
+  required?: boolean;
+  content: Record<string, { schema: OpenAPISchema; example?: any }>;
+}
+
+export interface OpenAPIResponse {
+  description: string;
+  content?: Record<string, { schema: OpenAPISchema; example?: any }>;
+  headers?: Record<string, { description?: string; schema: OpenAPISchema }>;
+}
+
+/**
+ * Full OpenAPI specification
+ */
+export interface OpenAPISpec {
+  openapi: string;
+  info: SwaggerInfo & { title: string; version: string };
+  servers?: Array<{ url: string; description?: string }>;
+  paths: Record<string, Record<string, OpenAPIOperation>>;
+  components?: {
+    schemas?: Record<string, OpenAPISchema>;
+    securitySchemes?: Record<string, SecurityScheme>;
+  };
+  security?: Array<Record<string, string[]>>;
+  tags?: Array<{ name: string; description?: string }>;
+  externalDocs?: { description?: string; url: string };
+}
+
+/**
+ * Internal route storage with full config
+ */
+export interface StoredRoute {
+  method: HTTPMethod;
+  path: string;
+  schema?: SchemaConfig;
+  meta?: RouteMeta;
+}

package/src/advanced/swagger/zodFieldToOpenAPI.ts

@@ -0,0 +1,94 @@
+import { OpenAPISchema } from './types';
+import { zodSchemaToOpenAPI } from './zodSchemaToOpenAPI';
+
+/**
+ * Convert individual Zod field to OpenAPI schema
+ */
+
+
+export function zodFieldToOpenAPI(field: any): OpenAPISchema {
+  if (!field?._def) {
+    return { type: 'string' };
+  }
+
+  const def = field._def;
+  const typeName = def.typeName;
+
+  switch (typeName) {
+    case 'ZodString': {
+      const schema: OpenAPISchema = { type: 'string' };
+
+      // Extract string constraints
+      for (const check of def.checks || []) {
+        if (check.kind === 'email') schema.format = 'email';
+        if (check.kind === 'url') schema.format = 'uri';
+        if (check.kind === 'uuid') schema.format = 'uuid';
+        if (check.kind === 'min') schema.minLength = check.value;
+        if (check.kind === 'max') schema.maxLength = check.value;
+        if (check.kind === 'regex') schema.pattern = check.regex.source;
+      }
+
+      return schema;
+    }
+
+    case 'ZodNumber': {
+      const schema: OpenAPISchema = { type: 'number' };
+
+      // Extract number constraints
+      for (const check of def.checks || []) {
+        if (check.kind === 'int') schema.type = 'integer';
+        if (check.kind === 'min') schema.minimum = check.value;
+        if (check.kind === 'max') schema.maximum = check.value;
+      }
+
+      return schema;
+    }
+
+    case 'ZodBoolean':
+      return { type: 'boolean' };
+
+    case 'ZodArray':
+      return {
+        type: 'array',
+        items: zodFieldToOpenAPI(def.type)
+      };
+
+    case 'ZodObject':
+      return zodSchemaToOpenAPI(field);
+
+    case 'ZodEnum':
+      return {
+        type: 'string',
+        enum: def.values
+      };
+
+    case 'ZodOptional':
+    case 'ZodNullable':
+      return zodFieldToOpenAPI(def.innerType);
+
+    case 'ZodDefault':
+      const innerSchema = zodFieldToOpenAPI(def.innerType);
+      innerSchema.default = def.defaultValue();
+      return innerSchema;
+
+    case 'ZodLiteral':
+      return {
+        type: typeof def.value === 'number' ? 'number' :
+          typeof def.value === 'boolean' ? 'boolean' : 'string',
+        enum: [def.value]
+      };
+
+    case 'ZodUnion':
+      // For simple unions, just use the first type
+      if (def.options?.length > 0) {
+        return zodFieldToOpenAPI(def.options[0]);
+      }
+      return { type: 'string' };
+
+    case 'ZodDate':
+      return { type: 'string', format: 'date-time' };
+
+    default:
+      return { type: 'string' };
+  }
+}

package/src/advanced/swagger/zodSchemaToOpenAPI.ts

@@ -0,0 +1,50 @@
+import { zodFieldToOpenAPI } from './zodFieldToOpenAPI';
+import { OpenAPISchema } from './types';
+
+// ============================================
+// ZOD TO OPENAPI CONVERSION
+// ============================================
+/**
+ * Convert Zod schema to OpenAPI schema
+ */
+
+
+export function zodSchemaToOpenAPI(zodSchema: any): OpenAPISchema {
+  if (!zodSchema) {
+    return { type: 'object' };
+  }
+
+  // If it's already an OpenAPI schema
+  if (zodSchema.type || zodSchema.$ref) {
+    return zodSchema;
+  }
+
+  try {
+    const shape = zodSchema._def?.shape?.() || zodSchema.shape;
+
+    if (shape) {
+      const properties: Record<string, OpenAPISchema> = {};
+      const required: string[] = [];
+
+      for (const [key, value] of Object.entries(shape)) {
+        properties[key] = zodFieldToOpenAPI(value);
+
+        // Check if field is required
+        const def = (value as any)?._def;
+        if (def?.typeName !== 'ZodOptional' && def?.typeName !== 'ZodDefault') {
+          required.push(key);
+        }
+      }
+
+      return {
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined
+      };
+    }
+  } catch {
+    // Fall through
+  }
+
+  return { type: 'object' };
+}

package/src/advanced/swagger/zodToOpenAPI.ts

@@ -0,0 +1,22 @@
+import { OpenAPISchema } from './types';
+import { zodFieldToOpenAPI } from './zodFieldToOpenAPI';
+
+/**
+ * Extract specific field from Zod schema
+ */
+
+
+export function zodToOpenAPI(zodSchema: any, fieldName: string): OpenAPISchema | null {
+  if (!zodSchema) return null;
+
+  try {
+    const shape = zodSchema._def?.shape?.() || zodSchema.shape;
+    if (shape && shape[fieldName]) {
+      return zodFieldToOpenAPI(shape[fieldName]);
+    }
+  } catch {
+    // Fall through
+  }
+
+  return null;
+}