@expressots/adapter-express 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/adapter-express/studio/studio-integration.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Studio Integration - Auto-detects and integrates ExpressoTS Studio Agent
+ *
+ * This module provides automatic integration with @expressots/studio-agent
+ * when it's installed in the project. It enables request recording, tracing,
+ * and real-time monitoring without requiring manual setup.
+ */
+import type { Application, RequestHandler } from "express";
+interface StudioAgentInstance {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    createMiddleware(): RequestHandler;
+    scanRoutes(): Promise<void>;
+    /**
+     * Optional — older agents may not implement this. Used to push the
+     * actual listening port + boot duration once the host server is up.
+     */
+    updateRuntimeInfo?(patch: {
+        appPort?: number;
+        globalPrefix?: string;
+        startupMs?: number;
+        interceptorCount?: number;
+        providerCount?: number;
+        middlewareCount?: number;
+        runtimeItems?: StudioRuntimeItems;
+        middlewarePreset?: StudioMiddlewarePresetInfo;
+    }): void;
+}
+/**
+ * Itemised runtime view forwarded to the Studio Agent. Populated from
+ * DI metadata at boot — surfaces framework-registered items the agent's
+ * static file scanner can't see (e.g. built-in providers, interceptors
+ * registered via `@Interceptor()` on framework classes).
+ *
+ * Mirrors `RuntimeItems` in `@expressots/studio-agent` deliberately so
+ * the adapter doesn't need to import from the studio package (which is
+ * an optional peer dependency).
+ */
+export interface StudioRuntimeItems {
+    providers?: Array<{
+        name: string;
+        source?: string;
+    }>;
+    interceptors?: Array<{
+        name: string;
+        priority?: number;
+        source?: string;
+    }>;
+    middleware?: Array<{
+        name: string;
+        category: string;
+        type: "built-in" | "custom";
+        order: number;
+        path?: string;
+    }>;
+    /**
+     * Controller- and route-scoped middleware bindings, harvested from
+     * `ControllerMetadata.middleware` Reflect entries after
+     * `app.listen()`. Used by the agent to draw scope-aware
+     * "middleware → controller / route" edges on the architecture map.
+     *
+     * Mirrors `MiddlewareBinding` in `@expressots/studio-agent`.
+     */
+    middlewareBindings?: Array<{
+        middlewareName: string;
+        scope: "controller" | "route";
+        controllerName: string;
+        controllerMethod?: string;
+        httpMethod?: string;
+        routePath?: string;
+    }>;
+}
+/**
+ * Middleware preset info forwarded to the Studio Agent. Mirrors
+ * `MiddlewarePresetInfo` in `@expressots/studio-agent` so the adapter
+ * doesn't need to import from the studio package.
+ */
+export interface StudioMiddlewarePresetInfo {
+    name: string;
+    hasOverrides: boolean;
+    parse?: {
+        json?: {
+            limit?: string;
+        };
+        urlencoded?: {
+            limit?: string;
+            extended?: boolean;
+        };
+        cookies?: boolean;
+    };
+    security?: {
+        tier?: string;
+        helmet?: boolean;
+        cors?: {
+            origin?: boolean | string;
+            credentials?: boolean;
+            methods?: Array<string>;
+            allowedHeaders?: Array<string>;
+        };
+        rateLimit?: {
+            windowMs?: number;
+            max?: number;
+        } | false;
+    };
+    compress?: {
+        enabled: boolean;
+        level?: number;
+    };
+    logger?: {
+        enabled: boolean;
+        implementation?: string;
+    };
+}
+interface StudioIntegrationConfig {
+    enabled?: boolean;
+    port?: number;
+    dbPath?: string;
+    serviceName?: string;
+    /** Forwarded to the agent so the Status page can show the app URL. */
+    appPort?: number;
+    /** Global URL prefix of the host application. */
+    globalPrefix?: string;
+}
+/**
+ * Initialize the Studio Agent if available
+ */
+export declare function initializeStudio(app: Application, config?: StudioIntegrationConfig, appContainer?: unknown): Promise<boolean>;
+/**
+ * Push runtime details to the agent that the host only knows after the
+ * HTTP server has started — most importantly the actual listening port
+ * and total boot time. No-ops when:
+ *   - the agent isn't running, or
+ *   - the installed agent is from an older preview without
+ *     `updateRuntimeInfo()` (we feature-detect to stay forward-compatible).
+ */
+export declare function reportStudioRuntimeInfo(patch: {
+    appPort?: number;
+    globalPrefix?: string;
+    startupMs?: number;
+    interceptorCount?: number;
+    providerCount?: number;
+    middlewareCount?: number;
+    runtimeItems?: StudioRuntimeItems;
+    middlewarePreset?: StudioMiddlewarePresetInfo;
+}): void;
+/**
+ * Re-trigger the Studio Agent's route discovery. Used by the host
+ * after `app.listen()` so that the agent's runtime route scanner sees
+ * the fully-populated Express `_router` stack (controllers are bound
+ * by `InversifyExpressServer.build()` AFTER `initializeStudio()` runs,
+ * so the agent's first scan only catches static-source routes).
+ *
+ * No-ops when:
+ *   - Studio isn't enabled, or
+ *   - the installed agent is too old to expose `scanRoutes()`.
+ */
+export declare function rescanStudioRoutes(): Promise<void>;
+/**
+ * Stop the Studio Agent
+ */
+export declare function stopStudio(): Promise<void>;
+/**
+ * Check if Studio is enabled
+ */
+export declare function isStudioEnabled(): boolean;
+/**
+ * Get the Studio Agent instance
+ */
+export declare function getStudioAgent(): StudioAgentInstance | null;
+export {};

package/lib/esm/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./adapter-express/index.js";

package/lib/package.json

@@ -1,146 +1,170 @@
-{
-  "name": "@expressots/adapter-express",
-  "version": "3.0.0",
-  "description": "Expressots - modern, fast, lightweight nodejs web framework (@adapter-express)",
-  "author": "",
-  "main": "./lib/cjs/index.js",
-  "types": "./lib/cjs/types/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./lib/esm/types/index.d.ts",
-        "default": "./lib/esm/index.mjs"
-      },
-      "require": {
-        "types": "./lib/cjs/types/index.d.ts",
-        "default": "./lib/cjs/index.js"
-      }
-    }
-  },
-  "files": [
-    "lib/**/*"
-  ],
-  "license": "MIT",
-  "homepage": "https://expresso-ts.com",
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/expressots"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/expressots/adapter-express"
-  },
-  "bugs": {
-    "url": "https://github.com/expressots/adapter-express/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "expressots",
-    "nodejs",
-    "microservices",
-    "typescript",
-    "clean-architecture",
-    "typescript-framework",
-    "framework",
-    "server-side"
-  ],
-  "scripts": {
-    "prepare": "husky",
-    "clean": "node scripts/rm.js lib",
-    "copy": "node scripts/copy.js package.json README.md CHANGELOG.md lib",
-    "build": "npm run clean && npm run build:cjs && npm run copy",
-    "build:cjs": "tsc -p tsconfig.cjs.json",
-    "release": "release-it",
-    "prepublish": "npm run build && npm pack",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "coverage": "jest --coverage",
-    "format": "prettier --write \"src/**/*.ts\" --cache",
-    "lint": "eslint \"src/**/*.ts\"",
-    "lint:fix": "eslint \"src/**/*.ts\" --fix"
-  },
-  "dependencies": {
-    "express": "4.21.1",
-    "reflect-metadata": "0.2.2"
-  },
-  "devDependencies": {
-    "@codecov/vite-plugin": "0.0.1-beta.6",
-    "@commitlint/cli": "19.2.1",
-    "@commitlint/config-conventional": "19.2.2",
-    "@expressots/core": "3.0.0",
-    "@expressots/shared": "3.0.0",
-    "@release-it/conventional-changelog": "8.0.1",
-    "@types/express": "4.17.21",
-    "@types/jest": "29.5.14",
-    "@types/node": "20.14.10",
-    "@typescript-eslint/eslint-plugin": "7.16.1",
-    "@typescript-eslint/parser": "7.16.1",
-    "eslint": "8.57.0",
-    "eslint-config-prettier": "9.1.0",
-    "husky": "9.1.1",
-    "jest": "29.7.0",
-    "prettier": "3.3.3",
-    "release-it": "17.6.0",
-    "ts-jest": "29.2.5",
-    "typescript": "5.5.3"
-  },
-  "release-it": {
-    "git": {
-      "commitMessage": "chore(release): ${version}"
-    },
-    "github": {
-      "release": true
-    },
-    "npm": {
-      "publish": false
-    },
-    "plugins": {
-      "@release-it/conventional-changelog": {
-        "infile": "CHANGELOG.md",
-        "preset": {
-          "name": "conventionalcommits",
-          "types": [
-            {
-              "type": "feat",
-              "section": "Features"
-            },
-            {
-              "type": "fix",
-              "section": "Bug Fixes"
-            },
-            {
-              "type": "perf",
-              "section": "Performance Improvements"
-            },
-            {
-              "type": "revert",
-              "section": "Reverts"
-            },
-            {
-              "type": "docs",
-              "section": "Documentation"
-            },
-            {
-              "type": "refactor",
-              "section": "Code Refactoring"
-            },
-            {
-              "type": "test",
-              "section": "Tests"
-            },
-            {
-              "type": "build",
-              "section": "Build System"
-            },
-            {
-              "type": "ci",
-              "section": "Continuous Integrations"
-            }
-          ]
-        }
-      }
-    }
-  }
-}
+{
+  "name": "@expressots/adapter-express",
+  "version": "4.0.0-preview.3",
+  "description": "Expressots - modern, fast, lightweight nodejs web framework (@adapter-express)",
+  "author": "",
+  "main": "./lib/cjs/index.js",
+  "types": "./lib/cjs/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/esm/types/index.d.ts",
+        "default": "./lib/esm/index.mjs"
+      },
+      "require": {
+        "types": "./lib/cjs/types/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "lib/**/*"
+  ],
+  "license": "MIT",
+  "homepage": "https://expresso-ts.com",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/expressots"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/expressots/adapter-express"
+  },
+  "bugs": {
+    "url": "https://github.com/expressots/adapter-express/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.18.0"
+  },
+  "keywords": [
+    "expressots",
+    "nodejs",
+    "microservices",
+    "typescript",
+    "clean-architecture",
+    "typescript-framework",
+    "framework",
+    "server-side"
+  ],
+  "scripts": {
+    "prepare": "husky",
+    "clean": "node scripts/rm.js lib",
+    "copy": "node scripts/copy.js package.json README.md CHANGELOG.md lib",
+    "build": "npm run clean && npm run build:cjs && npm run build:esm && npm run copy",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "node scripts/build-esm.js",
+    "release": "release-it",
+    "release:prepare": "node scripts/release/prepare-publish.mjs",
+    "release:restore": "node scripts/release/restore-package-json.mjs",
+    "release:publish": "npm run build && npm run release:prepare && npm publish --tag next --access public && npm run release:restore",
+    "prepublish": "npm run build && npm pack",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "coverage": "jest --coverage",
+    "format": "prettier --write \"src/**/*.ts\" --cache",
+    "lint": "eslint \"src/**/*.ts\" --cache --cache-location node_modules/.cache/eslint/",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix --cache --cache-location node_modules/.cache/eslint/"
+  },
+  "dependencies": {
+    "@expressots/core": "file:../expressots/expressots-core-4.0.0-preview.3.tgz",
+    "@expressots/shared": "file:../shared/expressots-shared-4.0.0-preview.3.tgz",
+    "express": "^5.1.0",
+    "reflect-metadata": "0.2.2"
+  },
+  "peerDependencies": {
+    "@expressots/studio-agent": ">=4.0.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@expressots/studio-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@codecov/vite-plugin": "^2.0.1",
+    "@commitlint/cli": "19.2.1",
+    "@commitlint/config-conventional": "19.2.2",
+    "@expressots/studio-agent": "file:../expressots-studio/packages/studio-agent",
+    "@release-it/conventional-changelog": "^11.0.0",
+    "@types/express": "^5.0.0",
+    "@types/jest": "29.5.14",
+    "@types/node": "20.14.10",
+    "@typescript-eslint/eslint-plugin": "7.16.1",
+    "@typescript-eslint/parser": "7.16.1",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "husky": "9.1.1",
+    "jest": "29.7.0",
+    "lint-staged": "^15.2.10",
+    "prettier": "3.3.3",
+    "release-it": "^20.0.1",
+    "ts-jest": "29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "5.5.3"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --cache --cache-location node_modules/.cache/eslint/ --fix",
+      "prettier --write --cache"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore(release): ${version}"
+    },
+    "github": {
+      "release": true
+    },
+    "npm": {
+      "publish": false
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "infile": "CHANGELOG.md",
+        "preset": {
+          "name": "conventionalcommits",
+          "types": [
+            {
+              "type": "feat",
+              "section": "Features"
+            },
+            {
+              "type": "fix",
+              "section": "Bug Fixes"
+            },
+            {
+              "type": "perf",
+              "section": "Performance Improvements"
+            },
+            {
+              "type": "revert",
+              "section": "Reverts"
+            },
+            {
+              "type": "docs",
+              "section": "Documentation"
+            },
+            {
+              "type": "refactor",
+              "section": "Code Refactoring"
+            },
+            {
+              "type": "test",
+              "section": "Tests"
+            },
+            {
+              "type": "build",
+              "section": "Build System"
+            },
+            {
+              "type": "ci",
+              "section": "Continuous Integrations"
+            }
+          ]
+        }
+      }
+    }
+  }
+}