@getvision/server 0.0.0-develop-20251031183955

package/src/event-bus.ts

@@ -0,0 +1,286 @@
+import { Queue, Worker, QueueEvents } from 'bullmq'
+import type { z, ZodError } from 'zod'
+import { eventRegistry } from './event-registry'
+
+/**
+ * EventBus configuration
+ */
+export interface EventBusConfig {
+  redis?: {
+    host?: string
+    port?: number
+    password?: string
+  }
+  // Dev mode - use in-memory (no Redis required)
+  devMode?: boolean
+}
+
+/**
+ * EventBus - Abstraction over BullMQ
+ */
+export class EventBus {
+  private queues = new Map<string, Queue>()
+  private workers = new Map<string, Worker>()
+  private queueEvents = new Map<string, QueueEvents>()
+  private config: EventBusConfig
+  private devModeHandlers = new Map<string, Array<(data: any) => Promise<void>>>()
+
+  constructor(config: EventBusConfig = {}) {
+    this.config = {
+      devMode: config.devMode ?? process.env.NODE_ENV === 'development',
+      redis: config.redis ?? {
+        host: process.env.REDIS_HOST || 'localhost',
+        port: parseInt(process.env.REDIS_PORT || '6379'),
+      },
+    }
+  }
+
+  /**
+   * Get or create a queue for an event
+   */
+  private getQueue(eventName: string): Queue {
+    if (this.config.devMode) {
+      // In dev mode, we don't use actual queues
+      return null as any
+    }
+
+    let queue = this.queues.get(eventName)
+    if (!queue) {
+      const connection = this.config.redis || {
+        host: 'localhost',
+        port: 6379,
+      }
+      queue = new Queue(eventName, {
+        connection,
+      })
+      this.queues.set(eventName, queue)
+    }
+    return queue
+  }
+
+  /**
+   * Get or create a queue for a cron job
+   */
+  async getQueueForCron(cronName: string): Promise<Queue> {
+    if (this.config.devMode) {
+      // In dev mode, return a mock queue
+      return {
+        upsertJobScheduler: async () => {},
+      } as any
+    }
+
+    return this.getQueue(cronName)
+  }
+
+  /**
+   * Emit an event
+   */
+  async emit<T extends Record<string, any>>(
+    eventName: string,
+    data: T
+  ): Promise<void> {
+    // Get event metadata from registry
+    const eventMeta = eventRegistry.getEvent(eventName)
+    if (!eventMeta) {
+      throw new Error(`Event "${eventName}" not registered. Did you forget to add .on('${eventName}', {...})?`)
+    }
+
+    // Validate data with Zod schema (enforce no unknown keys when possible)
+    try {
+      // If the event schema is a ZodObject, use strict() to disallow unknown keys
+      const maybeStrictSchema: any = (eventMeta.schema as any)
+      const strictSchema = typeof maybeStrictSchema?.strict === 'function'
+        ? maybeStrictSchema.strict()
+        : eventMeta.schema
+
+      const validatedData = (strictSchema as typeof eventMeta.schema).parse(data)
+
+      if (this.config.devMode) {
+        // Dev mode - execute handlers immediately (in-memory)
+        const handlers = this.devModeHandlers.get(eventName) || []
+        
+        for (const handler of handlers) {
+          try {
+            await handler(validatedData)
+            eventRegistry.incrementEventCount(eventName, false)
+          } catch (error) {
+            console.error(`Error in handler for event "${eventName}":`, error)
+            eventRegistry.incrementEventCount(eventName, true)
+            throw error
+          }
+        }
+      } else {
+        // Production mode - use BullMQ
+        const queue = this.getQueue(eventName)
+        await queue.add(eventName, validatedData, {
+          attempts: 3,
+          backoff: {
+            type: 'exponential',
+            delay: 2000,
+          },
+        })
+        eventRegistry.incrementEventCount(eventName, false)
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === 'ZodError') {
+        const zodError = error as any
+        const errorMessages = zodError.errors?.map((e: any) => `  - ${e.path.join('.')}: ${e.message}`).join('\n') || error.message
+        throw new Error(
+          `Invalid data for event "${eventName}":\n${errorMessages}`
+        )
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Register event handler
+   */
+  registerHandler<T>(
+    eventName: string,
+    handler: (data: T) => Promise<void>
+  ): void {
+    if (this.config.devMode) {
+      // Dev mode - store handlers in memory
+      const handlers = this.devModeHandlers.get(eventName) || []
+      handlers.push(handler)
+      this.devModeHandlers.set(eventName, handlers)
+    } else {
+      // Production mode - create BullMQ worker
+      const connection = this.config.redis || {
+        host: 'localhost',
+        port: 6379,
+      }
+      const worker = new Worker(
+        eventName,
+        async (job) => {
+          try {
+            await handler(job.data)
+          } catch (error) {
+            eventRegistry.incrementEventCount(eventName, true)
+            throw error
+          }
+        },
+        {
+          connection,
+        }
+      )
+
+      this.workers.set(`${eventName}-${Date.now()}`, worker)
+
+      // Listen to queue events
+      if (!this.queueEvents.has(eventName)) {
+        const connection = this.config.redis || {
+          host: 'localhost',
+          port: 6379,
+        }
+        const queueEvents = new QueueEvents(eventName, {
+          connection,
+        })
+
+        queueEvents.on('completed', ({ jobId }) => {
+          console.log(`✅ Event "${eventName}" completed (job: ${jobId})`)
+        })
+
+        queueEvents.on('failed', ({ jobId, failedReason }) => {
+          console.error(`❌ Event "${eventName}" failed (job: ${jobId}):`, failedReason)
+        })
+
+        this.queueEvents.set(eventName, queueEvents)
+      }
+    }
+  }
+
+  /**
+   * Register cron job handler
+   */
+  registerCronHandler(
+    cronName: string,
+    handler: (context: any) => Promise<void>
+  ): void {
+    if (this.config.devMode) {
+      // Dev mode - cron jobs run immediately for testing
+      // We'll implement a simple interval-based scheduler
+      console.log(`🧹 Cron job "${cronName}" registered (dev mode - manual trigger only)`)
+      
+      // Store handler for manual trigger
+      const handlers = this.devModeHandlers.get(cronName) || []
+      handlers.push(handler)
+      this.devModeHandlers.set(cronName, handlers)
+    } else {
+      // Production mode - create BullMQ worker for cron jobs
+      const connection = this.config.redis || {
+        host: 'localhost',
+        port: 6379,
+      }
+      const worker = new Worker(
+        cronName,
+        async (job) => {
+          try {
+            // Create a simple context for cron handler
+            const context = {
+              jobId: job.id,
+              timestamp: Date.now(),
+            }
+            await handler(context)
+            eventRegistry.incrementCronCount(cronName, false)
+          } catch (error) {
+            eventRegistry.incrementCronCount(cronName, true)
+            throw error
+          }
+        },
+        {
+          connection,
+        }
+      )
+
+      this.workers.set(`${cronName}-${Date.now()}`, worker)
+
+      // Listen to cron job events
+      if (!this.queueEvents.has(cronName)) {
+        const queueEvents = new QueueEvents(cronName, {
+          connection,
+        })
+
+        queueEvents.on('completed', ({ jobId }) => {
+          console.log(`✅ Cron job "${cronName}" completed (job: ${jobId})`)
+        })
+
+        queueEvents.on('failed', ({ jobId, failedReason }) => {
+          console.error(`❌ Cron job "${cronName}" failed (job: ${jobId}):`, failedReason)
+        })
+
+        this.queueEvents.set(cronName, queueEvents)
+      }
+    }
+  }
+
+  /**
+   * Close all connections
+   */
+  async close(): Promise<void> {
+    if (this.config.devMode) {
+      this.devModeHandlers.clear()
+      return
+    }
+
+    // Close all queues
+    for (const queue of this.queues.values()) {
+      await queue.close()
+    }
+
+    // Close all workers
+    for (const worker of this.workers.values()) {
+      await worker.close()
+    }
+
+    // Close all queue events
+    for (const queueEvent of this.queueEvents.values()) {
+      await queueEvent.close()
+    }
+
+    this.queues.clear()
+    this.workers.clear()
+    this.queueEvents.clear()
+  }
+}

package/src/event-registry.ts

@@ -0,0 +1,158 @@
+import type { z } from 'zod'
+
+/**
+ * Event metadata for UI and runtime
+ */
+export interface EventMetadata<T = any> {
+  name: string
+  description?: string
+  icon?: string
+  tags?: string[]
+  schema: z.ZodSchema<T>
+  handlers: Array<(data: T) => Promise<void>>
+  lastTriggered?: Date
+  totalCount: number
+  failedCount: number
+}
+
+/**
+ * Cron job metadata
+ */
+export interface CronMetadata {
+  name: string
+  schedule: string
+  description?: string
+  icon?: string
+  tags?: string[]
+  handler: (context: any) => Promise<void>
+  lastRun?: Date
+  nextRun?: Date
+  totalRuns: number
+  failedRuns: number
+}
+
+/**
+ * Global event registry
+ */
+export class EventRegistry {
+  private events = new Map<string, EventMetadata>()
+  private crons = new Map<string, CronMetadata>()
+
+  /**
+   * Register an event with schema and handler
+   */
+  registerEvent<T>(
+    name: string,
+    schema: z.ZodSchema<T>,
+    handler: (data: T) => Promise<void>,
+    metadata?: {
+      description?: string
+      icon?: string
+      tags?: string[]
+    }
+  ): void {
+    const existing = this.events.get(name)
+    
+    if (existing) {
+      // Add handler to existing event
+      existing.handlers.push(handler)
+    } else {
+      // Create new event
+      this.events.set(name, {
+        name,
+        schema,
+        handlers: [handler],
+        description: metadata?.description,
+        icon: metadata?.icon,
+        tags: metadata?.tags,
+        totalCount: 0,
+        failedCount: 0,
+      })
+    }
+  }
+
+  /**
+   * Register a cron job
+   */
+  registerCron(
+    name: string,
+    schedule: string,
+    handler: (context: any) => Promise<void>,
+    metadata?: {
+      description?: string
+      icon?: string
+      tags?: string[]
+    }
+  ): void {
+    this.crons.set(name, {
+      name,
+      schedule,
+      handler,
+      description: metadata?.description,
+      icon: metadata?.icon,
+      tags: metadata?.tags,
+      totalRuns: 0,
+      failedRuns: 0,
+    })
+  }
+
+  /**
+   * Get event metadata
+   */
+  getEvent(name: string): EventMetadata | undefined {
+    return this.events.get(name)
+  }
+
+  /**
+   * Get all events
+   */
+  getAllEvents(): EventMetadata[] {
+    return Array.from(this.events.values())
+  }
+
+  /**
+   * Get all cron jobs
+   */
+  getAllCrons(): CronMetadata[] {
+    return Array.from(this.crons.values())
+  }
+
+  /**
+   * Increment event count
+   */
+  incrementEventCount(name: string, failed = false): void {
+    const event = this.events.get(name)
+    if (event) {
+      event.totalCount++
+      if (failed) {
+        event.failedCount++
+      }
+      event.lastTriggered = new Date()
+    }
+  }
+
+  /**
+   * Increment cron run count
+   */
+  incrementCronCount(name: string, failed = false): void {
+    const cron = this.crons.get(name)
+    if (cron) {
+      cron.totalRuns++
+      if (failed) {
+        cron.failedRuns++
+      }
+      cron.lastRun = new Date()
+    }
+  }
+
+  /**
+   * Clear all registrations (for testing)
+   */
+  clear(): void {
+    this.events.clear()
+    this.crons.clear()
+  }
+}
+
+// Global singleton
+export const eventRegistry = new EventRegistry()

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @getvision/server - Meta-framework with built-in observability
+ * 
+ * Features:
+ * - Built on Hono (ultra-fast, edge-ready)
+ * - Built-in Vision Dashboard (tracing, logging)
+ * - Type-safe Zod validation
+ * - Pub/Sub & Cron via BullMQ (automatic)
+ * - Service builder pattern
+ * - c.span() for custom tracing
+ * 
+ * @example
+ * ```ts
+ * import { Vision } from '@getvision/server'
+ * import { z } from 'zod'
+ * 
+ * const app = new Vision({
+ *   service: {
+ *     name: 'My API',
+ *     version: '1.0.0'
+ *   },
+ *   pubsub: {
+ *     schemas: {
+ *       'user/created': {
+ *         data: z.object({ userId: z.string() })
+ *       }
+ *     }
+ *   }
+ * })
+ * 
+ * const userService = app.service('users')
+ *   .endpoint('GET', '/users/:id', schema, async (data, c) => {
+ *     // c.span() is built-in!
+ *     const user = c.span('db.select', { 'db.table': 'users' }, () => {
+ *       return db.users.findOne(data.id)
+ *     })
+ *     return user
+ *   })
+ *   .on('user/created', async (event) => {
+ *     console.log('User created:', event.data)
+ *   })
+ * 
+ * app.start(3000)
+ * ```
+ */
+
+// Main Vision class
+export { Vision, getVisionContext } from './vision-app'
+export type { VisionConfig } from './vision-app'
+
+// Service builder (usually accessed via app.service())
+export { ServiceBuilder } from './service'
+
+// Types
+export type { 
+  EndpointConfig, 
+  Handler, 
+  VisionContext,
+  ExtendedContext
+} from './types'
+
+// Re-export from core for convenience
+export { VisionCore } from '@getvision/core'
+export type * from '@getvision/core'

package/src/router.ts

@@ -0,0 +1,100 @@
+import type { Hono } from 'hono'
+import { readdirSync, statSync } from 'fs'
+import { join, resolve, relative, sep } from 'path'
+import { pathToFileURL } from 'url'
+
+/**
+ * Autoload Vision/Hono sub-apps from a directory structure like app/routes/.../index.ts
+ * Each folder becomes a base path. Dynamic segments [id] are converted to :id.
+ *
+ * Examples:
+ * - app/routes/users/index.ts        -> /users
+ * - app/routes/users/[id]/index.ts   -> /users/:id
+ * - app/routes/index.ts              -> /
+ */
+export async function loadSubApps(app: Hono, routesDir: string = './app/routes'): Promise<Array<{ name: string; routes: any[] }>> {
+  const mounted: Array<{ base: string }> = []
+  const allSubAppSummaries: Array<{ name: string; routes: any[] }> = []
+
+  function toBasePath(dirPath: string): string {
+    const rel = relative(resolve(routesDir), resolve(dirPath))
+    if (!rel || rel === '' || rel === '.' ) return '/'
+    const segments = rel.split(sep).filter(Boolean).map((s) => {
+      if (s.startsWith('[') && s.endsWith(']')) return `:${s.slice(1, -1)}`
+      return s
+    })
+    return '/' + segments.join('/')
+  }
+
+  async function scan(dir: string) {
+    const entries = readdirSync(dir)
+    // If folder contains index.ts or index.js, treat it as a sub-app root
+    const hasTs = entries.includes('index.ts')
+    const hasJs = entries.includes('index.js')
+    if (hasTs || hasJs) {
+      const indexFile = resolve(dir, hasTs ? 'index.ts' : 'index.js')
+      const modUrl = pathToFileURL(indexFile).href
+      const mod: any = await import(modUrl)
+      const subApp = mod?.default
+      if (subApp) {
+        const base = toBasePath(dir)
+        // If it's a Vision sub-app, build its services before mounting
+        try {
+          if (typeof (subApp as any)?.service === 'function') {
+            await (subApp as any).buildAllServices?.()
+            // Collect sub-app services/routes for bulk registration later
+            const summaries = (subApp as any).getServiceSummaries?.()
+            if (Array.isArray(summaries) && summaries.length > 0) {
+              // Prefix all route paths with the base path
+              const prefixedSummaries = summaries.map(s => ({
+                ...s,
+                routes: s.routes.map((r: any) => ({
+                  ...r,
+                  path: base === '/' ? r.path : base + (r.path === '/' ? '' : r.path)
+                }))
+              }))
+              allSubAppSummaries.push(...prefixedSummaries)
+            }
+          }
+        } catch (e) {
+          console.error(`❌ Error preparing sub-app ${dir}:`, (e as any)?.message || e)
+        }
+        // Mount the sub-app only if it looks like a Hono/Vision instance with routes
+        const routes = (subApp as any)?.routes
+        if (Array.isArray(routes)) {
+          ;(app as any).route(base, subApp)
+          mounted.push({ base })
+        }
+      }
+    }
+    // Recurse into child directories
+    for (const name of entries) {
+      const full = join(dir, name)
+      const st = statSync(full)
+      if (st.isDirectory()) await scan(full)
+    }
+  }
+
+  // Only scan if directory exists
+  try {
+    statSync(routesDir)
+  } catch {
+    return []
+  }
+
+  await scan(routesDir)
+  
+  // Merge services by name (combine routes from same service name)
+  const mergedServices = new Map<string, { name: string; routes: any[] }>()
+  for (const summary of allSubAppSummaries) {
+    if (mergedServices.has(summary.name)) {
+      const existing = mergedServices.get(summary.name)!
+      existing.routes.push(...summary.routes)
+    } else {
+      mergedServices.set(summary.name, { name: summary.name, routes: [...summary.routes] })
+    }
+  }
+  
+  // Return merged services (don't register here - let caller handle it)
+  return Array.from(mergedServices.values())
+}