@luisrodrigues/nestjs-scheduler-dashboard 0.0.6 → 0.1.1

package/README.md

@@ -1,13 +1,12 @@
 # @luisrodrigues/nestjs-scheduler-dashboard
 
-A plug-and-play dashboard for [`@nestjs/schedule`](https://docs.nestjs.com/techniques/task-scheduling). Visualize cron job executions, track history and metrics, trigger jobs manually, and stop running executions — all from an embedded UI with zero external dependencies.
-
-The dashboard runs on its own dedicated port (default **3636**), completely isolated from your main application.
+A plug-and-play dashboard for [`@nestjs/schedule`](https://docs.nestjs.com/techniques/task-scheduling). Visualize cron job executions, track history and metrics, trigger jobs manually, and stop running executions — all from an embedded UI served on your existing application port.
 
 ---
 
 ## Features
 
+- Mounted directly on your app — no separate port or process
 - Execution history per job with status, duration, and error details
 - Persistent metrics: total runs, failed runs, average duration — independent of history retention
 - Manual job triggering and execution stop from the UI
@@ -15,7 +14,6 @@ The dashboard runs on its own dedicated port (default **3636**), completely isol
 - No-overlap mode: skip a job if it is already running
 - Optional HTTP Basic Auth to protect the dashboard
 - Light / dark mode
-- Zero external runtime dependencies — served from a single self-contained HTML file
 
 ---
 
@@ -30,37 +28,34 @@ pnpm add @luisrodrigues/nestjs-scheduler-dashboard
 **Peer dependencies** (install if not already present):
 
 ```bash
-npm install @nestjs/common @nestjs/core @nestjs/schedule
+npm install @nestjs/common @nestjs/core @nestjs/schedule express
 ```
 
 ---
 
 ## Quick start
 
-### 1. Call `setupSchedulerDash` in `main.ts`
+### 1. Import `SchedulerDashModule` in your `AppModule`
 
 ```ts
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import { setupSchedulerDash } from '@luisrodrigues/nestjs-scheduler-dashboard';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Must be called BEFORE app.listen() so storage is ready before cron jobs start
-  await setupSchedulerDash(app, { port: 3636 });
-
-  await app.listen(3000);
-  console.log('App running at   http://localhost:3000');
-  console.log('Dashboard at     http://localhost:3636');
-}
-
-bootstrap();
+import { Module } from '@nestjs/common';
+import { ScheduleModule } from '@nestjs/schedule';
+import { SchedulerDashModule } from '@luisrodrigues/nestjs-scheduler-dashboard';
+
+@Module({
+  imports: [
+    ScheduleModule.forRoot(),
+    SchedulerDashModule.forRoot({ route: '_scheduler' }),
+  ],
+})
+export class AppModule {}
 ```
 
-### 2. Decorate your jobs
+### 2. Replace `@Cron` with `@TrackJob` on every job
+
+`@TrackJob` is a wrapper around NestJS's `@Cron` decorator. It registers the cron schedule exactly as `@Cron` does, and additionally records every execution (start time, duration, status, errors) so the dashboard can display them.
 
-Replace `@Cron` with `@TrackJob` — it accepts the same arguments:
+> **Jobs decorated with `@Cron` instead of `@TrackJob` will still run on schedule but will not appear in the dashboard history.**
 
 ```ts
 import { Injectable } from '@nestjs/common';
@@ -69,29 +64,39 @@ import { TrackJob } from '@luisrodrigues/nestjs-scheduler-dashboard';
 
 @Injectable()
 export class ReportJob {
+  // Before: @Cron(CronExpression.EVERY_HOUR)
   @TrackJob(CronExpression.EVERY_HOUR, { name: 'generate-report' })
   async run() {
-    // your job logic
+    // your job logic — no other changes needed
   }
 }
 ```
 
-That's it. Open `http://localhost:3636` to see the dashboard.
+That's it. Start your app and open `http://localhost:3000/_scheduler`.
 
 ---
 
 ## Configuration
 
-`setupSchedulerDash(app, options?)` accepts:
+`SchedulerDashModule.forRoot(options?)` accepts:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `port` | `number` | `3636` | Port for the dashboard HTTP server |
+| `route` | `string` | `'_scheduler'` | URL path where the dashboard is mounted |
 | `storage` | `Storage` | `new MemoryStorage()` | Storage backend for execution history and metrics |
 | `maxConcurrent` | `number` | — | Maximum number of jobs that can run simultaneously. Excess jobs are queued |
 | `noOverlap` | `boolean` | `false` | Globally prevent a job from starting if it is already running |
 | `auth` | `{ username, password }` | — | Protect the dashboard with HTTP Basic Auth |
 
+### `route`
+
+The URL path where the dashboard is served, relative to your app's root.
+
+```ts
+SchedulerDashModule.forRoot({ route: 'admin/scheduler' })
+// dashboard → http://localhost:3000/admin/scheduler
+```
+
 ### `storage`
 
 The default `MemoryStorage` keeps everything in-process. You can limit how many history entries are kept per job:
@@ -99,11 +104,11 @@ The default `MemoryStorage` keeps everything in-process. You can limit how many
 ```ts
 import { MemoryStorage } from '@luisrodrigues/nestjs-scheduler-dashboard';
 
-await setupSchedulerDash(app, {
+SchedulerDashModule.forRoot({
   storage: new MemoryStorage({
     historyRetention: 50, // keep the last 50 executions per job (default: unlimited)
   }),
-});
+})
 ```
 
 > **Metrics are independent of `historyRetention`.** Even after old history entries are trimmed, the counters for total runs, failed runs, and average duration keep accumulating.
@@ -132,9 +137,7 @@ export class RedisStorage extends Storage {
 Limits how many `@TrackJob` jobs can run simultaneously across the entire application. Jobs that exceed the limit are saved to storage with status `"queued"` and run in FIFO order as slots free up.
 
 ```ts
-await setupSchedulerDash(app, {
-  maxConcurrent: 5,
-});
+SchedulerDashModule.forRoot({ maxConcurrent: 5 })
 ```
 
 ### `noOverlap`
@@ -142,12 +145,10 @@ await setupSchedulerDash(app, {
 Prevents a job from firing again if it is still running. Applies globally to all `@TrackJob` methods.
 
 ```ts
-await setupSchedulerDash(app, {
-  noOverlap: true,
-});
+SchedulerDashModule.forRoot({ noOverlap: true })
 ```
 
-Can also be overridden per job in the decorator:
+Can also be overridden per job via the decorator:
 
 ```ts
 @TrackJob(CronExpression.EVERY_MINUTE, { name: 'sync', noOverlap: true })
@@ -157,19 +158,21 @@ async sync() { /* ... */ }
 ### `auth`
 
 ```ts
-await setupSchedulerDash(app, {
+SchedulerDashModule.forRoot({
   auth: {
     username: process.env.DASH_USER ?? 'admin',
     password: process.env.DASH_PASS ?? 'secret',
   },
-});
+})
 ```
 
 ---
 
 ## `@TrackJob` decorator
 
-Drop-in replacement for `@Cron`. Accepts all the same options plus `noOverlap`.
+`@TrackJob` is a **wrapper around `@Cron`** from `@nestjs/schedule`. It accepts every argument that `@Cron` accepts and passes them through unchanged, so migrating an existing job is a one-line change. The only addition is the `noOverlap` option and the automatic execution tracking.
+
+**Every scheduled job must use `@TrackJob` instead of `@Cron`.** Jobs that remain on `@Cron` will run normally but their executions will not be recorded or visible in the dashboard.
 
 ```ts
 @TrackJob(cronTime, options?)
@@ -197,38 +200,54 @@ async cleanup() {
 
 ## API
 
-The dashboard exposes a small REST API on the same port as the UI.
+The dashboard exposes a small REST API under the configured route.
 
 | Method | Path | Description |
 |---|---|---|
-| `GET` | `/api` | Returns all jobs with history and metrics |
-| `POST` | `/api/:name/trigger` | Manually trigger a cron job by name |
-| `POST` | `/api/executions/:id/stop` | Stop a running or queued execution by ID |
+| `GET` | `/<route>/api` | Returns all jobs with history and metrics |
+| `GET` | `/<route>/api/:name` | Returns a single job with history and metrics |
+| `POST` | `/<route>/api/:name/trigger` | Manually trigger a cron job by name |
+| `POST` | `/<route>/api/executions/:id/stop` | Stop a running or queued execution by ID |
 
 ---
 
 ## Full example
 
 ```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ScheduleModule } from '@nestjs/schedule';
+import { SchedulerDashModule, MemoryStorage } from '@luisrodrigues/nestjs-scheduler-dashboard';
+import { ReportJob } from './jobs/report.job';
+
+@Module({
+  imports: [
+    ScheduleModule.forRoot(),
+    SchedulerDashModule.forRoot({
+      route: '_scheduler',
+      storage: new MemoryStorage({ historyRetention: 100 }),
+      maxConcurrent: 3,
+      noOverlap: true,
+      auth: {
+        username: process.env.DASH_USER ?? 'admin',
+        password: process.env.DASH_PASS ?? 'secret',
+      },
+    }),
+  ],
+  providers: [ReportJob],
+})
+export class AppModule {}
+```
+
+```ts
+// main.ts
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
-import { setupSchedulerDash, MemoryStorage } from '@luisrodrigues/nestjs-scheduler-dashboard';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
-
-  await setupSchedulerDash(app, {
-    port: 3636,
-    storage: new MemoryStorage({ historyRetention: 100 }),
-    maxConcurrent: 3,
-    noOverlap: true,
-    auth: {
-      username: process.env.DASH_USER ?? 'admin',
-      password: process.env.DASH_PASS ?? 'secret',
-    },
-  });
-
   await app.listen(3000);
+  // Dashboard at http://localhost:3000/_scheduler
 }
 
 bootstrap();

package/dist/index.d.ts

@@ -1,10 +1,8 @@
-import type { INestApplication } from '@nestjs/common';
-import { SchedulerDashOptions } from './scheduler-dash.options';
+export { SchedulerDashModule } from './scheduler-dash.module';
 export { TrackJob } from './decorators/track-job.decorator';
 export { Storage } from './storage/storage.abstract';
 export type { IStorageOptions } from './storage/storage.abstract';
 export { MemoryStorage } from './storage/memory.storage';
 export type { JobExecution } from './storage/job-execution.interface';
 export type { JobMetrics } from './storage/job-metrics.interface';
-export type { SchedulerDashOptions, SchedulerDashAuth } from './scheduler-dash.options';
-export declare function setupSchedulerDash(app: INestApplication, options?: SchedulerDashOptions): Promise<void>;
+export type { SchedulerDashOptions, SchedulerDashAuth, SchedulerDashAsyncOptions } from './scheduler-dash.options';

package/dist/index.js

@@ -1,44 +1,11 @@
 "use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryStorage = exports.Storage = exports.TrackJob = void 0;
-exports.setupSchedulerDash = setupSchedulerDash;
-const core_1 = require("@nestjs/core");
-const common_1 = require("@nestjs/common");
-const schedule_1 = require("@nestjs/schedule");
-const scheduler_dash_context_1 = require("./scheduler-dash.context");
-const scheduler_dash_schema_1 = require("./scheduler-dash.schema");
-const dashboard_module_1 = require("./dashboard.module");
-const jobs_service_1 = require("./jobs.service");
-const standalone_server_1 = require("./standalone-server");
+exports.MemoryStorage = exports.Storage = exports.TrackJob = exports.SchedulerDashModule = void 0;
+var scheduler_dash_module_1 = require("./scheduler-dash.module");
+Object.defineProperty(exports, "SchedulerDashModule", { enumerable: true, get: function () { return scheduler_dash_module_1.SchedulerDashModule; } });
 var track_job_decorator_1 = require("./decorators/track-job.decorator");
 Object.defineProperty(exports, "TrackJob", { enumerable: true, get: function () { return track_job_decorator_1.TrackJob; } });
 var storage_abstract_1 = require("./storage/storage.abstract");
 Object.defineProperty(exports, "Storage", { enumerable: true, get: function () { return storage_abstract_1.Storage; } });
 var memory_storage_1 = require("./storage/memory.storage");
 Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return memory_storage_1.MemoryStorage; } });
-const DEFAULT_PORT = 3636;
-async function setupSchedulerDash(app, options = {}) {
-    const parsed = scheduler_dash_schema_1.SchedulerDashOptionsSchema.safeParse(options);
-    if (!parsed.success) {
-        throw new Error(`[SchedulerDash] Invalid options:\n${parsed.error.issues.map(i => `  • ${i.path.join('.')}: ${i.message}`).join('\n')}`);
-    }
-    const port = options.port ?? DEFAULT_PORT;
-    const logger = new common_1.Logger('SchedulerDashboard', { timestamp: true });
-    let _InternalDashboardApp = class _InternalDashboardApp {
-    };
-    _InternalDashboardApp = __decorate([
-        (0, common_1.Module)({ imports: [dashboard_module_1.DashboardModule.forRoot(options)] })
-    ], _InternalDashboardApp);
-    await core_1.NestFactory.createApplicationContext(_InternalDashboardApp, { logger: false });
-    const storage = scheduler_dash_context_1.SchedulerDashContext.storage;
-    const schedulerRegistry = app.get(schedule_1.SchedulerRegistry);
-    const jobsService = new jobs_service_1.JobsService(schedulerRegistry, storage);
-    logger.log(`Dashboard initialized`);
-    await (0, standalone_server_1.startStandaloneServer)(port, jobsService, options.auth, logger);
-}

package/dist/jobs.service.js

@@ -1,8 +1,24 @@
 "use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JobsService = void 0;
+const common_1 = require("@nestjs/common");
+const schedule_1 = require("@nestjs/schedule");
+const storage_abstract_1 = require("./storage/storage.abstract");
 const job_concurrency_1 = require("./decorators/job-concurrency");
-class JobsService {
+const scheduler_dash_constants_1 = require("./scheduler-dash.constants");
+let JobsService = class JobsService {
     constructor(schedulerRegistry, storage) {
         this.schedulerRegistry = schedulerRegistry;
         this.storage = storage;
@@ -43,5 +59,11 @@ class JobsService {
     stopExecution(executionId) {
         return (0, job_concurrency_1.stopExecutionById)(executionId);
     }
-}
+};
 exports.JobsService = JobsService;
+exports.JobsService = JobsService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(scheduler_dash_constants_1.STORAGE_TOKEN)),
+    __metadata("design:paramtypes", [schedule_1.SchedulerRegistry,
+        storage_abstract_1.Storage])
+], JobsService);