@forinda/kickjs-devtools 1.3.1 → 1.4.0

package/dist/adapter.d.ts

@@ -0,0 +1,109 @@
+import { type AppAdapter, type AdapterMiddleware, type Container, type Ref, type ComputedRef } from '@forinda/kickjs-core';
+/** Per-route latency stats */
+interface RouteStats {
+    count: number;
+    totalMs: number;
+    minMs: number;
+    maxMs: number;
+}
+export interface DevToolsOptions {
+    /** Base path for debug endpoints (default: '/_debug') */
+    basePath?: string;
+    /** Only enable when this is true (default: process.env.NODE_ENV !== 'production') */
+    enabled?: boolean;
+    /** Include environment variables (sanitized) at /_debug/config (default: false) */
+    exposeConfig?: boolean;
+    /** Env var prefixes to expose (default: ['APP_', 'NODE_ENV']). Others are redacted. */
+    configPrefixes?: string[];
+    /** Callback when error rate exceeds threshold */
+    onErrorRateExceeded?: (rate: number) => void;
+    /** Error rate threshold (default: 0.5 = 50%) */
+    errorRateThreshold?: number;
+    /** Other adapters to discover stats from (e.g., WsAdapter) */
+    adapters?: any[];
+    /**
+     * Secret token to guard DevTools access. When set, all requests must
+     * include this token as `x-devtools-token` header or `?token=` query param.
+     *
+     * Auto-generated on startup if not provided. The token is logged to the console.
+     * Set to `false` to disable the guard entirely (not recommended).
+     *
+     * @example
+     * ```ts
+     * new DevToolsAdapter({ secret: process.env.DEVTOOLS_SECRET })
+     * ```
+     */
+    secret?: string | false;
+}
+/**
+ * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.
+ *
+ * Exposes debug endpoints powered by reactive state (ref, computed, watch):
+ * - `GET /_debug/routes`    — all registered routes with middleware
+ * - `GET /_debug/container` — DI registry with scopes and instantiation status
+ * - `GET /_debug/metrics`   — live request/error counts, error rate, uptime
+ * - `GET /_debug/health`    — deep health check with adapter status
+ * - `GET /_debug/config`    — sanitized environment variables (opt-in)
+ * - `GET /_debug/state`     — full reactive state snapshot
+ *
+ * @example
+ * ```ts
+ * import { DevToolsAdapter } from '@forinda/kickjs-devtools'
+ *
+ * bootstrap({
+ *   modules: [UserModule],
+ *   adapters: [
+ *     new DevToolsAdapter({
+ *       enabled: process.env.NODE_ENV !== 'production',
+ *       exposeConfig: true,
+ *       configPrefixes: ['APP_', 'DATABASE_'],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export declare class DevToolsAdapter implements AppAdapter {
+    readonly name = "DevToolsAdapter";
+    private basePath;
+    private enabled;
+    private exposeConfig;
+    private configPrefixes;
+    private errorRateThreshold;
+    private secret;
+    /** Total requests received */
+    readonly requestCount: Ref<number>;
+    /** Total responses with status >= 500 */
+    readonly errorCount: Ref<number>;
+    /** Total responses with status >= 400 and < 500 */
+    readonly clientErrorCount: Ref<number>;
+    /** Server start time */
+    readonly startedAt: Ref<number>;
+    /** Computed error rate (server errors / total requests) */
+    readonly errorRate: ComputedRef<number>;
+    /** Computed uptime in seconds */
+    readonly uptimeSeconds: ComputedRef<number>;
+    /** Per-route latency tracking */
+    readonly routeLatency: Record<string, RouteStats>;
+    private routes;
+    private container;
+    private appRef;
+    private adapterStatuses;
+    private stopErrorWatch;
+    private peerAdapters;
+    constructor(options?: DevToolsOptions);
+    /**
+     * Resolve peer adapters at request time. Prefers live adapters from the
+     * Application registry (survives HMR rebuild) and falls back to the
+     * constructor-provided refs.
+     */
+    private getPeerAdapters;
+    beforeMount(app: any, container: Container): void;
+    middleware(): AdapterMiddleware[];
+    onRouteMount(controllerClass: any, mountPath: string): void;
+    afterStart(_server: any, _container: Container): void;
+    shutdown(): void;
+    /** Find the public/devtools directory relative to the built dist or source */
+    private resolvePublicDir;
+}
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,SAAS,EAOd,KAAK,GAAG,EACR,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAA;AAa7B,8BAA8B;AAC9B,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mFAAmF;IACnF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAA;IAEhB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAgB,YAAW,UAAU;IAChD,QAAQ,CAAC,IAAI,qBAAoB;IAEjC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,kBAAkB,CAAQ;IAClC,OAAO,CAAC,MAAM,CAAgB;IAG9B,8BAA8B;IAC9B,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAChC,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACtC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACvC,iCAAiC;IACjC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAGjD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,YAAY,CAAY;gBAEpB,OAAO,GAAE,eAAoB;IAmDzC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAQvB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IA4JjD,UAAU,IAAI,iBAAiB,EAAE;IAuCjC,YAAY,CAAC,eAAe,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IA8B3D,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI;IAQrD,QAAQ,IAAI,IAAI;IAKhB,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB;CAYzB"}