@getvision/adapter-express 0.0.0-develop-20251031183955

package/dist/index.js

@@ -0,0 +1,435 @@
+import { VisionCore, autoDetectPackageInfo, autoDetectIntegrations, } from '@getvision/core';
+import { AsyncLocalStorage } from 'async_hooks';
+import { generateZodTemplate } from './zod-utils';
+const visionContext = new AsyncLocalStorage();
+/**
+ * Get current vision context (vision instance and traceId)
+ * Available in route handlers when using visionMiddleware
+ *
+ * @example
+ * ```ts
+ * app.get('/users', (req, res) => {
+ *   const { vision, traceId } = getVisionContext()
+ *   // ...
+ * })
+ * ```
+ */
+export function getVisionContext() {
+    const context = visionContext.getStore();
+    if (!context) {
+        throw new Error('Vision context not available. Make sure visionMiddleware is enabled.');
+    }
+    return context;
+}
+/**
+ * Create span helper using current trace context
+ * Child spans will be nested under the root http.request span
+ *
+ * @example
+ * ```ts
+ * app.get('/users', async (req, res) => {
+ *   const withSpan = useVisionSpan()
+ *
+ *   const users = withSpan('db.select', { 'db.table': 'users' }, () => {
+ *     return db.select().from(users).all()
+ *   })
+ * })
+ * ```
+ */
+export function useVisionSpan() {
+    const { vision, traceId, rootSpanId } = getVisionContext();
+    const tracer = vision.getTracer();
+    return (name, attributes = {}, fn) => {
+        // Start child span with parentId = rootSpanId
+        const span = tracer.startSpan(name, traceId, rootSpanId);
+        console.log(`[useVisionSpan] Created span: ${name} with parentId: ${rootSpanId}`);
+        // Add attributes
+        for (const [key, value] of Object.entries(attributes)) {
+            tracer.setAttribute(span.id, key, value);
+        }
+        try {
+            const result = fn();
+            const completedSpan = tracer.endSpan(span.id);
+            // Add span to trace store
+            if (completedSpan) {
+                vision.getTraceStore().addSpan(traceId, completedSpan);
+            }
+            return result;
+        }
+        catch (error) {
+            tracer.setAttribute(span.id, 'error', true);
+            tracer.setAttribute(span.id, 'error.message', error instanceof Error ? error.message : String(error));
+            const completedSpan = tracer.endSpan(span.id);
+            // Add span to trace store even on error
+            if (completedSpan) {
+                vision.getTraceStore().addSpan(traceId, completedSpan);
+            }
+            throw error;
+        }
+    };
+}
+let visionInstance = null;
+const discoveredRoutes = [];
+/**
+ * Express middleware for Vision Dashboard
+ *
+ * @example
+ * ```ts
+ * import express from 'express'
+ * import { visionMiddleware } from '@getvision/adapter-express'
+ *
+ * const app = express()
+ *
+ * if (process.env.NODE_ENV === 'development') {
+ *   app.use(visionMiddleware({ port: 9500 }))
+ * }
+ *
+ * app.get('/hello', (req, res) => {
+ *   res.json({ message: 'Hello!' })
+ * })
+ *
+ * app.listen(3000)
+ * ```
+ */
+export function visionMiddleware(options = {}) {
+    const enabled = options.enabled ?? (process.env.VISION_ENABLED !== 'false');
+    if (!enabled) {
+        return (req, res, next) => next();
+    }
+    // Initialize Vision instance
+    if (!visionInstance) {
+        visionInstance = new VisionCore({
+            port: options.port ?? parseInt(process.env.VISION_PORT || '9500'),
+            maxTraces: options.maxTraces ?? 1000,
+            maxLogs: options.maxLogs ?? 10000,
+        });
+        // Auto-detect service info
+        const pkgInfo = autoDetectPackageInfo();
+        const autoIntegrations = autoDetectIntegrations();
+        // Merge with user-provided config
+        const serviceName = options.service?.name || pkgInfo.name;
+        const serviceVersion = options.service?.version || pkgInfo.version;
+        const serviceDesc = options.service?.description;
+        const integrations = {
+            ...autoIntegrations,
+            ...options.service?.integrations,
+        };
+        // Filter out undefined values from integrations
+        const cleanIntegrations = {};
+        for (const [key, value] of Object.entries(integrations)) {
+            if (value !== undefined) {
+                cleanIntegrations[key] = value;
+            }
+        }
+        visionInstance.setAppStatus({
+            name: serviceName,
+            version: serviceVersion,
+            description: serviceDesc,
+            environment: process.env.NODE_ENV || 'development',
+            running: true,
+            metadata: {
+                framework: "Express",
+                integrations: Object.keys(cleanIntegrations).length > 0 ? cleanIntegrations : undefined,
+            }
+        });
+    }
+    const vision = visionInstance;
+    const enableCors = options.cors !== false;
+    const logging = options.logging !== false;
+    // Return middleware function
+    return (req, res, next) => {
+        // Add CORS headers for Vision
+        if (enableCors) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session');
+            res.setHeader('Access-Control-Expose-Headers', 'X-Vision-Trace-Id, X-Vision-Session');
+            // Handle preflight
+            if (req.method === 'OPTIONS') {
+                return res.status(204).end();
+            }
+        }
+        const startTime = Date.now();
+        // Create trace
+        const trace = vision.createTrace(req.method, req.path || req.url);
+        // Add trace ID to response header
+        res.setHeader('X-Vision-Trace-Id', trace.id);
+        // Start main root span for the entire request
+        const tracer = vision.getTracer();
+        const rootSpan = tracer.startSpan('http.request', trace.id);
+        // Add request attributes to span
+        tracer.setAttribute(rootSpan.id, 'http.method', req.method);
+        tracer.setAttribute(rootSpan.id, 'http.path', req.path || req.url);
+        tracer.setAttribute(rootSpan.id, 'http.url', req.originalUrl || req.url);
+        // Add query params if any
+        if (req.query && Object.keys(req.query).length > 0) {
+            tracer.setAttribute(rootSpan.id, 'http.query', req.query);
+        }
+        // Capture request metadata
+        const requestMeta = {
+            method: req.method,
+            url: req.originalUrl || req.url,
+            headers: req.headers,
+            query: Object.keys(req.query || {}).length ? req.query : undefined,
+            body: req.body,
+        };
+        tracer.setAttribute(rootSpan.id, 'http.request', requestMeta);
+        trace.metadata = { ...trace.metadata, request: requestMeta };
+        // Session ID tracking
+        const sessionId = req.headers['x-vision-session'];
+        if (sessionId) {
+            tracer.setAttribute(rootSpan.id, 'session.id', sessionId);
+            trace.metadata = { ...trace.metadata, sessionId };
+        }
+        // Log request start if logging enabled
+        if (logging) {
+            const parts = [`method=${req.method}`, `path=${req.path || req.url}`];
+            if (sessionId)
+                parts.push(`sessionId=${sessionId}`);
+            parts.push(`traceId=${trace.id}`);
+            console.info(`INF starting request ${parts.join(' ')}`);
+        }
+        // Capture response body
+        let responseBody = null;
+        let isJsonResponse = false;
+        const originalSend = res.send;
+        const originalJson = res.json;
+        res.send = function (body) {
+            // Only capture if not already captured by res.json
+            if (!isJsonResponse) {
+                responseBody = body;
+            }
+            return originalSend.call(this, body);
+        };
+        res.json = function (body) {
+            // Capture the object BEFORE it's stringified
+            responseBody = body;
+            isJsonResponse = true;
+            return originalJson.call(this, body);
+        };
+        // Wrap next() to handle completion in finally block (like Hono)
+        const wrappedNext = () => {
+            try {
+                // Run handler in AsyncLocalStorage context with rootSpanId
+                visionContext.run({ vision, traceId: trace.id, rootSpanId: rootSpan.id }, () => {
+                    next();
+                });
+            }
+            catch (error) {
+                // Track error in span
+                tracer.addEvent(rootSpan.id, 'error', {
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    stack: error instanceof Error ? error.stack : undefined,
+                });
+                tracer.setAttribute(rootSpan.id, 'error', true);
+                throw error;
+            }
+        };
+        // Listen for response finish to complete span
+        res.on('finish', () => {
+            try {
+                const duration = Date.now() - startTime;
+                // Add response attributes
+                tracer.setAttribute(rootSpan.id, 'http.status_code', res.statusCode);
+                const responseMeta = {
+                    status: res.statusCode,
+                    headers: res.getHeaders(),
+                    body: responseBody,
+                };
+                tracer.setAttribute(rootSpan.id, 'http.response', responseMeta);
+                trace.metadata = { ...trace.metadata, response: responseMeta };
+                // End span and add to trace
+                const completedSpan = tracer.endSpan(rootSpan.id);
+                if (completedSpan) {
+                    vision.getTraceStore().addSpan(trace.id, completedSpan);
+                }
+                // Complete trace (broadcasts to dashboard)
+                vision.completeTrace(trace.id, res.statusCode, duration);
+                // Log completion
+                if (logging) {
+                    console.info(`INF request completed code=${res.statusCode} duration=${duration}ms method=${req.method} path=${req.path || req.url} traceId=${trace.id}`);
+                }
+            }
+            catch (error) {
+                console.error('Vision: Error completing trace:', error);
+            }
+        });
+        // Execute next
+        wrappedNext();
+    };
+}
+/**
+ * Match route path against pattern (simple glob-like matching)
+ */
+function matchPattern(path, pattern) {
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -2);
+        return path === prefix || path.startsWith(prefix + '/');
+    }
+    return path === pattern;
+}
+/**
+ * Group routes by services (auto or manual)
+ */
+function groupRoutesByServices(routes, servicesConfig) {
+    const groups = {};
+    // Manual grouping if config provided
+    if (servicesConfig && servicesConfig.length > 0) {
+        servicesConfig.forEach((svc) => {
+            groups[svc.name] = { name: svc.name, description: svc.description, routes: [] };
+        });
+        groups['__uncategorized'] = { name: 'Uncategorized', routes: [] };
+        routes.forEach((route) => {
+            let matched = false;
+            for (const svc of servicesConfig) {
+                if (svc.routes.some((pattern) => matchPattern(route.path, pattern))) {
+                    groups[svc.name].routes.push(route);
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched) {
+                groups['__uncategorized'].routes.push(route);
+            }
+        });
+        if (groups['__uncategorized'].routes.length === 0) {
+            delete groups['__uncategorized'];
+        }
+    }
+    else {
+        // Auto-grouping: group by first path segment
+        groups['root'] = { name: 'Root', routes: [] };
+        const routesBySegment = new Map();
+        for (const route of routes) {
+            const segments = route.path.split('/').filter(Boolean);
+            const serviceName = segments.length > 0 ? segments[0] : 'root';
+            if (!routesBySegment.has(serviceName)) {
+                routesBySegment.set(serviceName, []);
+            }
+            routesBySegment.get(serviceName).push(route);
+        }
+        for (const [serviceName, serviceRoutes] of Array.from(routesBySegment.entries())) {
+            const hasMultiSegment = serviceRoutes.some((r) => r.path.split('/').filter(Boolean).length > 1);
+            if (hasMultiSegment || serviceName === 'root') {
+                const capitalizedName = serviceName === 'root' ? 'Root' : serviceName.charAt(0).toUpperCase() + serviceName.slice(1);
+                if (serviceName === 'root') {
+                    groups['root'].routes.push(...serviceRoutes);
+                }
+                else {
+                    groups[serviceName] = { name: capitalizedName, routes: serviceRoutes };
+                }
+            }
+            else {
+                groups['root'].routes.push(...serviceRoutes);
+            }
+        }
+        if (groups['root'].routes.length === 0) {
+            delete groups['root'];
+        }
+    }
+    return groups;
+}
+/**
+ * Enable automatic route discovery for Express app
+ *
+ * @example
+ * ```ts
+ * const app = express()
+ * app.use(visionMiddleware())
+ *
+ * // Define routes...
+ * app.get('/users', handler)
+ * app.post('/users', handler)
+ *
+ * // Enable auto-discovery after all routes defined
+ * enableAutoDiscovery(app)
+ * ```
+ */
+export function enableAutoDiscovery(app, options) {
+    if (!visionInstance) {
+        console.warn('⚠️ Vision not initialized. Call visionMiddleware() first.');
+        return;
+    }
+    const routes = [];
+    // Express stores routes in app._router.stack
+    const router = app._router;
+    if (!router) {
+        console.warn('⚠️ Express router not found');
+        return;
+    }
+    function extractRoutes(stack, basePath = '') {
+        stack.forEach((layer) => {
+            // Skip built-in middleware and Vision middleware
+            if (!layer.route && layer.name &&
+                ['query', 'expressInit', 'jsonParser', 'urlencodedParser', 'corsMiddleware'].includes(layer.name)) {
+                return;
+            }
+            if (layer.route) {
+                // Regular route
+                const methods = Object.keys(layer.route.methods);
+                methods.forEach(method => {
+                    const routePath = basePath + layer.route.path;
+                    const routeMethod = method.toUpperCase();
+                    // Try to get handler name and schema from stack
+                    let handlerName = 'anonymous';
+                    let schema = undefined;
+                    if (layer.route.stack && layer.route.stack.length > 0) {
+                        // Look for zValidator middleware with schema
+                        for (const stackItem of layer.route.stack) {
+                            if (stackItem.handle && stackItem.handle.__visionSchema) {
+                                schema = stackItem.handle.__visionSchema;
+                            }
+                            // Find the actual handler (last non-middleware function)
+                            if (stackItem.name && !['bound dispatch'].includes(stackItem.name)) {
+                                handlerName = stackItem.name;
+                            }
+                        }
+                    }
+                    const route = {
+                        method: routeMethod,
+                        path: routePath,
+                        handler: handlerName,
+                    };
+                    if (schema) {
+                        route.schema = schema;
+                        // Generate template from Zod schema
+                        const requestBody = generateZodTemplate(schema);
+                        if (requestBody) {
+                            route.requestBody = requestBody;
+                        }
+                    }
+                    routes.push(route);
+                });
+            }
+            else if (layer.name === 'router' && layer.handle && layer.handle.stack) {
+                // Nested router - try to extract base path from regexp
+                let routerPath = '';
+                if (layer.regexp) {
+                    const regexpSource = layer.regexp.source;
+                    // Try to extract simple path from regexp
+                    const match = regexpSource.match(/^\^\\\/([^\\?()]+)/);
+                    if (match) {
+                        routerPath = '/' + match[1].replace(/\\\//g, '/');
+                    }
+                }
+                extractRoutes(layer.handle.stack, basePath + routerPath);
+            }
+        });
+    }
+    extractRoutes(router.stack);
+    visionInstance.registerRoutes(routes);
+    // Group routes by services
+    const grouped = groupRoutesByServices(routes, options?.services);
+    const services = Object.values(grouped);
+    visionInstance.registerServices(services);
+    const schemasCount = routes.filter(r => r.schema).length;
+    console.log(`📋 Vision: Discovered ${routes.length} routes (${services.length} services, ${schemasCount} schemas)`);
+}
+/**
+ * Get the current Vision instance
+ */
+export function getVisionInstance() {
+    return visionInstance;
+}
+// Export Zod validator for schema-based validation
+export { zValidator, getRouteSchema, getAllRouteSchemas } from './zod-validator';

package/dist/zod-utils.d.ts

@@ -0,0 +1,7 @@
+import type { ZodType } from 'zod';
+import type { RequestBodySchema } from '@getvision/core';
+/**
+ * Generate JSON template with comments from Zod schema
+ */
+export declare function generateZodTemplate(schema: ZodType): RequestBodySchema | undefined;
+//# sourceMappingURL=zod-utils.d.ts.map

package/dist/zod-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../src/zod-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAyB,MAAM,KAAK,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAe,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAalF"}

package/dist/zod-utils.js

@@ -0,0 +1,145 @@
+/**
+ * Generate JSON template with comments from Zod schema
+ */
+export function generateZodTemplate(schema) {
+    try {
+        const fields = extractZodFields(schema);
+        const template = generateJsonTemplate(fields);
+        return {
+            template,
+            fields,
+        };
+    }
+    catch (error) {
+        console.warn('Failed to generate template from Zod schema:', error);
+        return undefined;
+    }
+}
+/**
+ * Extract fields from Zod schema (supports v3 and v4)
+ */
+function extractZodFields(schema, path = []) {
+    const fields = [];
+    // Support both v3 (_def) and v4 (def)
+    const def = schema.def || schema._def;
+    if (!def)
+        return fields;
+    // Unwrap ZodOptional, ZodNullable, ZodDefault - not needed for top level object
+    let unwrapped = schema;
+    const currentDef = unwrapped.def || unwrapped._def;
+    const typeName = currentDef?.type || currentDef?.typeName;
+    if (typeName === 'object' || typeName === 'ZodObject') {
+        // Get shape - it can be a function (getter) or direct object
+        const shapeValue = currentDef?.shape;
+        const shape = typeof shapeValue === 'function' ? shapeValue() : shapeValue;
+        for (const [key, value] of Object.entries(shape || {})) {
+            const fieldSchema = value;
+            const fieldDef = fieldSchema.def || fieldSchema._def;
+            const isOptional = fieldSchema.type === 'optional' ||
+                fieldDef?.type === 'optional' ||
+                fieldDef?.typeName === 'ZodOptional' ||
+                fieldDef?.typeName === 'ZodDefault';
+            // Get description - might be in wrapped schema for optional fields
+            let description = fieldDef?.description || fieldSchema.description;
+            if (!description && fieldDef?.wrapped) {
+                const wrappedDef = fieldDef.wrapped.def || fieldDef.wrapped._def;
+                description = wrappedDef?.description || fieldDef.wrapped.description;
+            }
+            // Determine type
+            let fieldType = getZodType(fieldSchema);
+            // Check for nested objects/arrays
+            const nested = extractZodFields(fieldSchema, [...path, key]);
+            fields.push({
+                name: key,
+                type: fieldType,
+                description,
+                required: !isOptional,
+                nested: nested.length > 0 ? nested : undefined,
+                example: getZodExample(fieldSchema, fieldType),
+            });
+        }
+    }
+    return fields;
+}
+/**
+ * Get Zod type as string (supports v3 and v4)
+ */
+function getZodType(schema) {
+    let unwrapped = schema;
+    let def = unwrapped.def || unwrapped._def;
+    // Unwrap optional/nullable/default
+    while (def?.type === 'optional' ||
+        def?.type === 'nullable' ||
+        def?.type === 'default' ||
+        def?.typeName === 'ZodOptional' ||
+        def?.typeName === 'ZodNullable' ||
+        def?.typeName === 'ZodDefault') {
+        unwrapped = def?.innerType || def?.wrapped || unwrapped;
+        def = unwrapped.def || unwrapped._def;
+    }
+    // Support both v4 (type) and v3 (typeName)
+    const typeName = def?.type || def?.typeName || unwrapped.type;
+    switch (typeName) {
+        case 'string':
+        case 'ZodString':
+            return 'string';
+        case 'number':
+        case 'ZodNumber':
+            return 'number';
+        case 'boolean':
+        case 'ZodBoolean':
+            return 'boolean';
+        case 'array':
+        case 'ZodArray':
+            return 'array';
+        case 'object':
+        case 'ZodObject':
+            return 'object';
+        case 'enum':
+        case 'ZodEnum':
+            return 'enum';
+        case 'date':
+        case 'ZodDate':
+            return 'date';
+        default:
+            return 'any';
+    }
+}
+/**
+ * Get example value for Zod type
+ */
+function getZodExample(schema, type) {
+    switch (type) {
+        case 'string': return '';
+        case 'number': return 0;
+        case 'boolean': return false;
+        case 'array': return [];
+        case 'object': return {};
+        default: return null;
+    }
+}
+/**
+ * Generate JSONC template with comments
+ */
+function generateJsonTemplate(fields, indent = 0) {
+    const lines = [];
+    const spacing = '  '.repeat(indent);
+    lines.push('{');
+    fields.forEach((field, index) => {
+        const isLast = index === fields.length - 1;
+        const description = field.description || field.name;
+        // Add comment
+        lines.push(`${spacing}  // ${description}`);
+        // Add field
+        let value;
+        if (field.nested && field.nested.length > 0) {
+            value = generateJsonTemplate(field.nested, indent + 1);
+        }
+        else {
+            value = JSON.stringify(field.example);
+        }
+        lines.push(`${spacing}  "${field.name}": ${value}${isLast ? '' : ','}`);
+    });
+    lines.push(`${spacing}}`);
+    return lines.join('\n');
+}

package/dist/zod-validator.d.ts

@@ -0,0 +1,44 @@
+import type { RequestHandler } from 'express';
+import type { ZodSchema } from 'zod';
+/**
+ * Get stored schema for a route
+ */
+export declare function getRouteSchema(method: string, path: string): ZodSchema | undefined;
+/**
+ * Get all stored schemas
+ */
+export declare function getAllRouteSchemas(): Map<string, {
+    method: string;
+    path: string;
+    schema: ZodSchema;
+}>;
+type ValidateTarget = 'body' | 'query' | 'params';
+/**
+ * Zod validator middleware for Express
+ * Similar to @hono/zod-validator but stores schema for Vision introspection
+ *
+ * @example
+ * ```ts
+ * import { zValidator } from '@getvision/adapter-express'
+ * import { z } from 'zod'
+ *
+ * const schema = z.object({
+ *   name: z.string().describe('User name'),
+ *   email: z.string().email().describe('User email'),
+ * })
+ *
+ * app.post('/users', zValidator('body', schema), (req, res) => {
+ *   // req.body is now typed and validated
+ *   const { name, email } = req.body
+ *   res.json({ name, email })
+ * })
+ * ```
+ */
+export declare function zValidator<T extends ZodSchema>(target: ValidateTarget, schema: T): RequestHandler;
+/**
+ * Extract Zod schema from validator middleware
+ * Used internally by Vision to generate API docs
+ */
+export declare function extractSchema(middleware: RequestHandler): ZodSchema | undefined;
+export {};
+//# sourceMappingURL=zod-validator.d.ts.map

package/dist/zod-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-validator.d.ts","sourceRoot":"","sources":["../src/zod-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,KAAK,CAAA;AAK9C;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAGlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,CAErG;AAED,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAC5C,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,CAAC,GACR,cAAc,CA6DhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,CAG/E"}