@getvision/adapter-express 0.0.0-develop-20251031183955

package/.eslintrc.js

@@ -0,0 +1,9 @@
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  root: true,
+  extends: ["@repo/eslint-config/base.js"],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    project: true,
+  },
+};

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/README.md

@@ -0,0 +1,266 @@
+# @getvision/adapter-express
+
+Express.js adapter for Vision Dashboard.
+
+## Installation
+
+```bash
+bun add @getvision/adapter-express
+# or
+npm install @getvision/adapter-express
+```
+
+## Quick Start
+
+```typescript
+import express from 'express'
+import { visionMiddleware, enableAutoDiscovery, zValidator } from '@getvision/adapter-express'
+import { z } from 'zod'
+
+const app = express()
+
+// Add Vision middleware (development only)
+if (process.env.NODE_ENV === 'development') {
+  app.use(visionMiddleware({ port: 9500 }))
+}
+
+// JSON parser
+app.use(express.json())
+
+// Your routes
+app.get('/users', (req, res) => {
+  res.json({ users: [] })
+})
+
+// Zod validation (typed + auto-documented in Vision)
+const createUser = z.object({
+  name: z.string().min(1).describe('Full name'),
+  email: z.string().email().describe('Email'),
+  age: z.number().int().positive().optional().describe('Age (optional)'),
+})
+
+app.post('/users', zValidator('body', createUser), (req, res) => {
+  res.status(201).json(req.body)
+})
+
+// Enable auto-discovery after routes
+if (process.env.NODE_ENV === 'development') {
+  // Auto-group routes by first path segment (Users, Root, etc.)
+enableAutoDiscovery(app)
+
+// Or provide manual services grouping with glob-like patterns
+// e.g. `/users/*` → "Users" service
+//      `/auth/*`  → "Auth" service
+//      Unmatched  → "Uncategorized"
+//
+// enableAutoDiscovery(app, { services: [
+//   { name: 'Users', description: 'User management', routes: ['/users/*'] },
+//   { name: 'Auth', routes: ['/auth/*'] }
+// ]})
+}
+
+app.listen(3000)
+```
+
+Visit `http://localhost:9500` to see the dashboard! 🎉
+
+## Features
+
+### Automatic Request Tracing
+Every request is automatically traced with:
+- HTTP method, path, query params
+- Request/response headers and body (captured before/after send)
+- Status code and duration
+- Response capture
+ - Root `http.request` span with child spans (DB, etc.)
+
+### Custom Spans
+Track operations within requests:
+
+```typescript
+import { useVisionSpan } from '@getvision/adapter-express'
+
+app.get('/users', async (req, res) => {
+  const withSpan = useVisionSpan()
+  
+  const users = withSpan('db.query', {
+    'db.system': 'postgresql',
+    'db.table': 'users'
+  }, () => {
+    return db.select().from(users).all()
+  })
+  
+  res.json({ users })
+})
+```
+
+### Auto-Discovery (Services Catalog)
+Automatically discover all routes:
+
+```typescript
+enableAutoDiscovery(app)
+```
+
+This will register all routes with Vision for the service catalog.
+
+## API
+
+### `visionMiddleware(options?)`
+
+Express middleware for Vision.
+
+**Options:**
+```typescript
+interface VisionExpressOptions {
+  port?: number              // Dashboard port (default: 9500)
+  enabled?: boolean          // Enable Vision (default: true)
+  maxTraces?: number         // Max traces to store (default: 1000)
+  maxLogs?: number           // Max logs to store (default: 10000)
+  logging?: boolean          // Console logging (default: true)
+  cors?: boolean             // Auto CORS for dashboard (default: true)
+  service?: {
+    name?: string            // Service name
+    version?: string         // Service version
+    description?: string     // Service description
+    integrations?: {
+      database?: string      // Database connection
+      redis?: string         // Redis connection
+      [key: string]: string | undefined
+    }
+  }
+}
+```
+
+### `enableAutoDiscovery(app, options?)`
+
+Enable automatic route discovery for Express app.
+
+**Note:** Call this after all routes are defined.
+
+```ts
+type ServiceDefinition = {
+  name: string
+  description?: string
+  routes: string[] // e.g. ['/users/*']
+}
+
+enableAutoDiscovery(app, {
+  services: [
+    { name: 'Users', routes: ['/users/*'] },
+  ]
+})
+```
+
+### `useVisionSpan()`
+
+Get span helper for current request. Child spans are automatically parented to the root `http.request` span for the current request.
+
+**Returns:** `(name, attributes, fn) => result`
+
+```typescript
+const withSpan = useVisionSpan()
+
+const result = withSpan('operation.name', {
+  'attr.key': 'value'
+}, () => {
+  // Your operation
+  return result
+})
+```
+
+### `getVisionContext()`
+
+Get current Vision context.
+
+**Returns:** `{ vision: VisionCore, traceId: string, rootSpanId: string }`
+
+```typescript
+import { getVisionContext } from '@getvision/adapter-express'
+
+app.get('/debug', (req, res) => {
+  const { vision, traceId } = getVisionContext()
+  res.json({ traceId })
+})
+```
+
+### `getVisionInstance()`
+
+Get the global Vision instance.
+
+**Returns:** `VisionCore | null`
+
+## Environment Variables
+
+```bash
+VISION_ENABLED=true        # Enable/disable Vision
+VISION_PORT=9500           # Dashboard port
+NODE_ENV=development       # Environment
+
+# CORS notes
+# Dashboard adds/needs headers: X-Vision-Trace-Id, X-Vision-Session
+# The middleware auto-sets:
+#   Access-Control-Allow-Origin: *
+#   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
+#   Access-Control-Allow-Headers: Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session
+#   Access-Control-Expose-Headers: X-Vision-Trace-Id, X-Vision-Session
+```
+
+## Example
+
+See [examples/express-basic](../../examples/express) for a complete example.
+
+## Integration with ORMs
+
+### Prisma
+
+```typescript
+app.get('/users', async (req, res) => {
+  const withSpan = useVisionSpan()
+  
+  const users = await withSpan('db.query', {
+    'db.system': 'postgresql',
+    'db.operation': 'findMany'
+  }, async () => {
+    return await prisma.user.findMany()
+  })
+  
+  res.json({ users })
+})
+```
+
+### TypeORM
+
+```typescript
+app.get('/users', async (req, res) => {
+  const withSpan = useVisionSpan()
+  
+  const users = await withSpan('db.query', {
+    'db.system': 'postgresql',
+    'db.table': 'users'
+  }, async () => {
+    return await userRepository.find()
+  })
+  
+  res.json({ users })
+})
+```
+
+## TypeScript
+
+Full TypeScript support included.
+
+```typescript
+import type { VisionExpressOptions } from '@getvision/adapter-express'
+
+const options: VisionExpressOptions = {
+  port: 9500,
+  service: {
+    name: 'my-api',
+    version: '1.0.0'
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import type { Request, Response, NextFunction, Application } from 'express';
+import { VisionCore } from '@getvision/core';
+import type { VisionExpressOptions, ServiceDefinition } from '@getvision/core';
+interface VisionContext {
+    vision: VisionCore;
+    traceId: string;
+    rootSpanId: string;
+}
+/**
+ * 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 declare function getVisionContext(): VisionContext;
+/**
+ * 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 declare function useVisionSpan(): <T>(name: string, attributes: Record<string, any> | undefined, fn: () => T) => T;
+/**
+ * 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 declare function visionMiddleware(options?: VisionExpressOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 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 declare function enableAutoDiscovery(app: Application, options?: {
+    services?: ServiceDefinition[];
+}): void;
+/**
+ * Get the current Vision instance
+ */
+export declare function getVisionInstance(): VisionCore | null;
+export { zValidator, getRouteSchema, getAllRouteSchemas } from './zod-validator';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC3E,OAAO,EACL,UAAU,EAGX,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAiB,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAK7F,UAAU,aAAa;IACrB,MAAM,EAAE,UAAU,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CACnB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAMhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,KAInB,CAAC,EACP,MAAM,MAAM,EACZ,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAK,EACpC,IAAI,MAAM,CAAC,KACV,CAAC,CAqCL;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,oBAAyB,SAIlD,OAAO,OAAO,QAAQ,QAAQ,YAAY,UA8L1D;AAuFD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAAE,GAAG,IAAI,CA+FxG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,GAAG,IAAI,CAErD;AAGD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA"}