@portqueue/dashboard 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +23 -2
  3. package/dist/client/assets/index-Bi6fyaCo.js +111 -0
  4. package/dist/client/assets/index-rcTsR9lz.css +1 -0
  5. package/dist/client/index.html +24 -0
  6. package/dist/index.cjs +922 -0
  7. package/dist/index.cjs.map +1 -0
  8. package/dist/index.d.ts +18 -0
  9. package/dist/index.mjs +921 -0
  10. package/dist/index.mjs.map +1 -0
  11. package/dist/server/adapters/express.d.ts +5 -0
  12. package/dist/server/adapters/fastify.d.ts +5 -0
  13. package/dist/server/adapters/koa.d.ts +5 -0
  14. package/dist/server/adapters/nest.d.ts +5 -0
  15. package/dist/server/adapters/node.d.ts +5 -0
  16. package/dist/server/api/http.d.ts +30 -0
  17. package/dist/server/api/params.d.ts +19 -0
  18. package/dist/server/api/routes/actions/add.d.ts +9 -0
  19. package/dist/server/api/routes/actions/cancel.d.ts +8 -0
  20. package/dist/server/api/routes/actions/index.d.ts +5 -0
  21. package/dist/server/api/routes/actions/job-batch.d.ts +4 -0
  22. package/dist/server/api/routes/actions/pause-instance.d.ts +8 -0
  23. package/dist/server/api/routes/actions/pause.d.ts +8 -0
  24. package/dist/server/api/routes/actions/remove-instance.d.ts +9 -0
  25. package/dist/server/api/routes/actions/remove-queue.d.ts +8 -0
  26. package/dist/server/api/routes/actions/remove-schedule.d.ts +9 -0
  27. package/dist/server/api/routes/actions/remove.d.ts +8 -0
  28. package/dist/server/api/routes/actions/resume-instance.d.ts +3 -0
  29. package/dist/server/api/routes/actions/resume.d.ts +3 -0
  30. package/dist/server/api/routes/actions/retry.d.ts +8 -0
  31. package/dist/server/api/routes/actions/set-schedule-enabled.d.ts +8 -0
  32. package/dist/server/api/routes/actions/types.d.ts +16 -0
  33. package/dist/server/api/routes/actions/validate.d.ts +24 -0
  34. package/dist/server/api/routes/config.d.ts +9 -0
  35. package/dist/server/api/routes/index.d.ts +37 -0
  36. package/dist/server/api/routes/instances.d.ts +5 -0
  37. package/dist/server/api/routes/jobs.d.ts +14 -0
  38. package/dist/server/api/routes/queues.d.ts +9 -0
  39. package/dist/server/api/routes/schedules.d.ts +5 -0
  40. package/dist/server/api/routes/stats.d.ts +8 -0
  41. package/dist/server/api/routes/types.d.ts +22 -0
  42. package/dist/server/api/serialize.d.ts +25 -0
  43. package/dist/server/assets.d.ts +51 -0
  44. package/dist/server/client.d.ts +11 -0
  45. package/dist/server/create-dashboard.d.ts +10 -0
  46. package/dist/server/engine.d.ts +18 -0
  47. package/dist/server/request.d.ts +18 -0
  48. package/dist/server/types.d.ts +74 -0
  49. package/dist/shared/constants.d.ts +27 -0
  50. package/dist/shared/dto/action.d.ts +88 -0
  51. package/dist/shared/dto/config.d.ts +20 -0
  52. package/dist/shared/dto/job.d.ts +37 -0
  53. package/dist/shared/dto/queue.d.ts +50 -0
  54. package/dist/shared/dto/schedule.d.ts +15 -0
  55. package/dist/shared/dto.d.ts +7 -0
  56. package/package.json +84 -4
@@ -0,0 +1,22 @@
1
+ import { PortQueue } from '@portqueue/core';
2
+ import { HandlerResult } from '../http';
3
+ export interface RouteContext {
4
+ /** The dashboard's own headless client, already connected. */
5
+ readonly portQueue: PortQueue;
6
+ /** The request's query string. */
7
+ readonly query: URLSearchParams;
8
+ /**
9
+ * Path segments captured by a `path` pattern, already URL-decoded. A route with a literal string
10
+ * `path` never has any.
11
+ */
12
+ readonly params: readonly string[];
13
+ }
14
+ export interface Route {
15
+ /** Only `GET` today; reads are routed by path, mutations by {@link ActionKind}. */
16
+ readonly method: 'GET';
17
+ /** A literal path, or a pattern whose capture groups become {@link RouteContext.params}. */
18
+ readonly path: string | RegExp;
19
+ /** One-line description of what this route serves; the registry is the API's index. */
20
+ readonly summary: string;
21
+ handle(ctx: RouteContext): Promise<HandlerResult>;
22
+ }
@@ -0,0 +1,25 @@
1
+ import { JobSnapshot, InstanceInfo, QueueInfo, QueueStats, Page } from '@portqueue/core';
2
+ import { JobDto, JobPageDto, QueueDto, QueuePageDto, ScheduleDto, SchedulePageDto, StatsDto, InstanceDto, InstancePageDto } from '../../shared/dto';
3
+ /** A schedule as core's dashboard facade returns it: `ScheduleInfo` plus its queue. */
4
+ export interface ScheduleInfo {
5
+ scheduleId: string;
6
+ queue: string;
7
+ cron?: string | null;
8
+ /** For an interval schedule: the seconds between runs. */
9
+ everySeconds?: number | null;
10
+ timezone?: string | null;
11
+ nextRunAt?: Date | null;
12
+ lastRunAt?: Date | null;
13
+ enabled: boolean;
14
+ idempotencyKey?: string | null;
15
+ }
16
+ export declare function serializeJob(job: JobSnapshot): JobDto;
17
+ export declare function serializeQueue(q: QueueInfo): QueueDto;
18
+ export declare function serializeQueuePage(page: Page<QueueInfo>): QueuePageDto;
19
+ export declare function serializeStats(s: QueueStats): StatsDto;
20
+ export declare function serializeJobPage(page: Page<JobSnapshot>): JobPageDto;
21
+ export declare function serializeSchedule(s: ScheduleInfo): ScheduleDto;
22
+ export declare function serializeSchedulePage(page: Page<ScheduleInfo>): SchedulePageDto;
23
+ /** Serialize an instance overview row. */
24
+ export declare function serializeInstance(i: InstanceInfo): InstanceDto;
25
+ export declare function serializeInstancePage(page: Page<InstanceInfo>): InstancePageDto;
@@ -0,0 +1,51 @@
1
+ import { DashboardConfigDto } from '../shared/dto';
2
+ export interface AssetResult {
3
+ status: number;
4
+ body: Buffer | string;
5
+ contentType: string;
6
+ /** Extra response headers — caching and, for HTML, the CSP naming the inline script's nonce. */
7
+ headers?: Record<string, string>;
8
+ }
9
+ /**
10
+ * True when a built client bundle is present in the package.
11
+ *
12
+ * Resolved **once** and memoized: the bundle ships inside the package and cannot appear or disappear
13
+ * while the process runs, so asking the filesystem on every asset request was one `stat` per request
14
+ * for an answer that never changes. `createEngine` awaits it at mount to warn about a missing
15
+ * bundle, which is also what primes it.
16
+ */
17
+ export declare function hasBuiltClient(): Promise<boolean>;
18
+ /** Clear the memo. Test-only: a suite that creates and removes a fake bundle needs to re-ask. */
19
+ export declare function resetBuiltClientCache(): void;
20
+ /**
21
+ * Resolve a request path inside the bundle directory, or null if it escapes.
22
+ *
23
+ * `resolve` + `relative`, not a string prefix test: a prefix check accepts a sibling directory
24
+ * whose name merely starts with the root's (`…/client-evil` passes `startsWith('…/client')`), and
25
+ * it mishandles an absolute request path. Here anything resolving outside the root — a `..`
26
+ * segment, an absolute path — comes back as a relative path that starts with `..` or is itself
27
+ * absolute, and is rejected.
28
+ */
29
+ export declare function safeResolve(root: string, relPath: string): string | null;
30
+ /**
31
+ * Serve a static asset by relative path (already stripped of basePath). SPA fallback: unknown
32
+ * non-file paths resolve to index.html so client-side routing works.
33
+ */
34
+ export declare function serveAsset(relPath: string, config: DashboardConfigDto): Promise<AssetResult>;
35
+ /**
36
+ * The client is built with Vite `base: './'`, so `index.html` references its bundle relatively
37
+ * (`./assets/app.js`). The browser would resolve that against the *current* URL, which breaks
38
+ * for every mount-relative navigation: `/portqueue` → `/assets/app.js` (outside the mount) and
39
+ * `/portqueue/jobs/1` → `/portqueue/jobs/assets/app.js`. Rewriting the references to absolute
40
+ * paths under the mount makes them resolve identically from any URL, with or without a trailing
41
+ * slash. A root mount (`/`) needs no prefix — `//assets/...` would read as protocol-relative.
42
+ */
43
+ export declare function rewriteAssetUrls(html: string, basePath: string): string;
44
+ /**
45
+ * JSON for embedding inside a `<script>` element. `JSON.stringify` does not escape `<`, so a
46
+ * developer-supplied `basePath` of `</script>…` would otherwise close the element early and let
47
+ * what follows be parsed as markup. Escaping `<` and `>` — plus U+2028/U+2029, which are legal
48
+ * inside a JSON string but count as line terminators to a JS parser — makes the value inert while
49
+ * keeping it valid JSON.
50
+ */
51
+ export declare function serializeConfig(config: DashboardConfigDto): string;
@@ -0,0 +1,11 @@
1
+ import { PortQueue, Driver, Logger } from '@portqueue/core';
2
+ export interface DashboardClient {
3
+ /** The initialized client. Connects on the first call; every later call reuses it. */
4
+ get(): Promise<PortQueue>;
5
+ /** Disconnect, if a request ever caused a connection. Safe to call more than once. */
6
+ close(): Promise<void>;
7
+ }
8
+ export declare function createDashboardClient(options: {
9
+ driver: Driver;
10
+ logger?: Pick<Logger, 'warn'>;
11
+ }): DashboardClient;
@@ -0,0 +1,10 @@
1
+ import { DashboardClient } from './client';
2
+ import { Dashboard, DashboardOptions } from './types';
3
+ export declare function createDashboard(
4
+ /**
5
+ * `client` is an internal seam: it lets a test drive the router without a database and is never
6
+ * part of the documented option surface. Production always passes `driver` alone.
7
+ */
8
+ options: DashboardOptions & {
9
+ client?: DashboardClient;
10
+ }): Dashboard;
@@ -0,0 +1,18 @@
1
+ import { IncomingMessage, ServerResponse } from 'node:http';
2
+ import { DashboardClient } from './client';
3
+ import { DashboardOptions } from './types';
4
+ export interface DashboardEngine {
5
+ /** The resolved, normalized mount path. */
6
+ readonly basePath: string;
7
+ /** True when the URL falls under our mount. */
8
+ owns(url: string | undefined): boolean;
9
+ /** The core async serve routine — writes directly to the raw response. */
10
+ serve(req: IncomingMessage, res: ServerResponse): Promise<void>;
11
+ /** `serve` wrapped so any error becomes a 500 instead of an unhandled rejection. */
12
+ serveSafely(req: IncomingMessage, res: ServerResponse): void;
13
+ /** Release the dashboard's own client. */
14
+ close(): Promise<void>;
15
+ }
16
+ export declare function createEngine(options: DashboardOptions & {
17
+ client?: DashboardClient;
18
+ }): DashboardEngine;
@@ -0,0 +1,18 @@
1
+ import { IncomingMessage } from 'node:http';
2
+ /**
3
+ * Read a request body to a string, rejecting anything over {@link MAX_BODY_BYTES}.
4
+ *
5
+ * On overflow it stops accumulating and **keeps reading** rather than destroying the socket. The
6
+ * caller answers 413, and a client can only read that answer if the connection is still there —
7
+ * `req.destroy()` mid-stream closed a keep-alive connection instead, so the client saw a transport
8
+ * error where a clear status was available. The remaining bytes are discarded as they arrive, so
9
+ * nothing accumulates in memory either way.
10
+ */
11
+ export declare function readBody(req: IncomingMessage): Promise<string>;
12
+ /** Why {@link readBody} rejected: the body passed the cap, and the answer is a 413. */
13
+ export declare class BodyTooLargeError extends Error {
14
+ constructor();
15
+ }
16
+ export declare function toHeaders(req: IncomingMessage): Record<string, string | string[] | undefined>;
17
+ /** Normalize a mount path: ensure a leading slash, drop a trailing one. */
18
+ export declare function normalizeBase(basePath: string): string;
@@ -0,0 +1,74 @@
1
+ import { IncomingMessage, ServerResponse } from 'node:http';
2
+ import { Driver, Logger } from '@portqueue/core';
3
+ export interface DashboardOptions {
4
+ /**
5
+ * A driver pointed at the PortQueue database — and that is the whole of the wiring.
6
+ *
7
+ * The dashboard builds and owns its own **headless** client from this (see `server/client.ts`): it
8
+ * declares no queues, registers no instance, consumes no queue, runs no scheduler, and never migrates. It
9
+ * deliberately does **not** take the application's `PortQueue`: the dashboard is normally a
10
+ * different process from the workers, so riding on their client only ever worked when the two
11
+ * happened to share one — and it coupled an observer to a participant.
12
+ *
13
+ * The connection opens on the first request, not at mount.
14
+ */
15
+ driver: Driver;
16
+ /** Mount path (default `/portqueue`). */
17
+ basePath?: string;
18
+ /**
19
+ * Where the dashboard reports problems it can only notice at startup — most usefully a missing
20
+ * client bundle, which otherwise looks like a working server. Defaults to `console`.
21
+ */
22
+ logger?: Pick<Logger, 'warn'>;
23
+ }
24
+ /** A raw-Node request handler: returns true if it handled the request. */
25
+ export type NodeHandler = (req: IncomingMessage, res: ServerResponse) => boolean;
26
+ /** Express-style middleware `(req, res, next) => void`. */
27
+ export type ExpressMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
28
+ /** Koa-style middleware `(ctx, next) => Promise<void>`. */
29
+ export type KoaMiddleware = (ctx: KoaContext, next: () => Promise<void>) => Promise<void>;
30
+ /** Fastify plugin `(fastify, opts, done) => void`. */
31
+ export type FastifyPlugin = (fastify: FastifyLike, opts: unknown, done: () => void) => void;
32
+ /**
33
+ * NestJS functional middleware. Nest's default platform is Express, so the dashboard
34
+ * mounts as ordinary functional middleware — no `@nestjs/*` dependency required.
35
+ */
36
+ export type NestMiddleware = ExpressMiddleware;
37
+ /** Minimal structural Koa context (avoid a hard koa dependency). */
38
+ export interface KoaContext {
39
+ req: IncomingMessage;
40
+ res: ServerResponse;
41
+ respond?: boolean;
42
+ }
43
+ /**
44
+ * Minimal structural Fastify instance — only what the adapter touches, so the dashboard needs no
45
+ * `fastify` dependency of its own. The hook may return a promise: Fastify decides whether a
46
+ * two-parameter hook is finished by awaiting what it returns.
47
+ */
48
+ export interface FastifyLike {
49
+ addHook: (name: 'onRequest', fn: (req: {
50
+ raw: IncomingMessage;
51
+ }, reply: {
52
+ raw: ServerResponse;
53
+ hijack: () => void;
54
+ }) => void | Promise<void>) => void;
55
+ }
56
+ export interface Dashboard {
57
+ /** Raw Node: call in your handler; returns true when it served the request. */
58
+ node: () => NodeHandler;
59
+ /** Express middleware `(req, res, next) => void`. */
60
+ express: () => ExpressMiddleware;
61
+ /** Koa middleware `(ctx, next) => Promise<void>`. */
62
+ koa: () => KoaMiddleware;
63
+ /** Fastify plugin `(fastify, opts, done) => void`. */
64
+ fastify: () => FastifyPlugin;
65
+ /** NestJS functional middleware — `consumer.apply(dashboard.nest()).forRoutes(basePath)`. */
66
+ nest: () => NestMiddleware;
67
+ /** The resolved base path. */
68
+ basePath: string;
69
+ /**
70
+ * Disconnect the dashboard's own client. Call it when the host shuts down. A no-op if no request
71
+ * ever caused a connection, and safe to call more than once.
72
+ */
73
+ close: () => Promise<void>;
74
+ }
@@ -0,0 +1,27 @@
1
+ /** Constants shared between the dashboard client and server (avoid literal drift). */
2
+ /**
3
+ * The dashboard's name, in the browser tab and in the fallback shell. Fixed, not a host option:
4
+ * the product has one name, and a host-set title only made the tab disagree with the header, the
5
+ * docs and every screenshot.
6
+ */
7
+ export declare const DASHBOARD_TITLE = "PortQueue Dashboard";
8
+ /**
9
+ * Header + marker the client sends on every request, and the server **requires** on every mutation.
10
+ *
11
+ * This is the mount's CSRF defence, and it works because of what a browser will not do: a custom
12
+ * request header cannot be set on a cross-origin request unless a preflight allows it, and the
13
+ * dashboard answers no CORS preflight at all. So a form post or `fetch` from another page reaches
14
+ * the mount without the marker and is refused — which matters because the mount is usually behind
15
+ * cookie or basic auth, and a browser replays both on a cross-site request.
16
+ *
17
+ * It costs the host nothing: there is no option to set and nothing to configure.
18
+ */
19
+ export declare const REQUESTED_WITH_HEADER = "x-requested-with";
20
+ export declare const REQUESTED_WITH_MARKER = "portqueue-dashboard";
21
+ /**
22
+ * The largest request body the mount reads, in bytes.
23
+ *
24
+ * Here rather than in the reader that enforces it, because it is a property of the API the client
25
+ * talks to: the only mutation that carries a payload of any size is `add`, whose `data` this bounds.
26
+ */
27
+ export declare const MAX_BODY_BYTES: number;
@@ -0,0 +1,88 @@
1
+ import { PauseMode } from '@portqueue/core';
2
+ /**
3
+ * Every mutation the dashboard can ask for. An enum, so no route matches a magic string — and the
4
+ * value **is** the URL segment the mutation posts to (`POST {basePath}/api/actions/<kind>`), so an
5
+ * action has exactly one endpoint and there is no second spelling to keep in sync.
6
+ */
7
+ export declare enum ActionKind {
8
+ PAUSE = "pause",
9
+ RESUME = "resume",
10
+ RETRY = "retry",
11
+ REMOVE = "remove",
12
+ CANCEL = "cancel",
13
+ ADD = "add",
14
+ REMOVE_SCHEDULE = "removeSchedule",
15
+ SET_SCHEDULE_ENABLED = "setScheduleEnabled",
16
+ REMOVE_QUEUE = "removeQueue",
17
+ PAUSE_INSTANCE = "pauseInstance",
18
+ RESUME_INSTANCE = "resumeInstance",
19
+ REMOVE_INSTANCE = "removeInstance"
20
+ }
21
+ /** The payload an `add` action carries — the subset of core `AddJobOptions` the form exposes. */
22
+ export interface AddJobRequestDto {
23
+ data: unknown;
24
+ priority?: number;
25
+ idempotencyKey?: string;
26
+ singletonKey?: string;
27
+ /** Cap on automatic retries for this job. */
28
+ retryMaxAttempts?: number;
29
+ /** Regex matching the instance keys this job may run on. */
30
+ preferredInstanceKeyPattern?: string;
31
+ /** One-off: delay this many **seconds** from now. */
32
+ startAfterSeconds?: number;
33
+ /** Recurring: fixed interval, in **seconds**. */
34
+ startEverySeconds?: number;
35
+ /** Recurring: cron expression, optionally with a timezone. */
36
+ cron?: string | {
37
+ pattern: string;
38
+ tz?: string;
39
+ };
40
+ }
41
+ /**
42
+ * The body of a mutation — the per-action fields, and nothing that selects the action.
43
+ *
44
+ * Which mutation runs is decided by the URL alone (`/api/actions/<kind>`). The body carried a `kind`
45
+ * field once, back when every mutation posted to one endpoint; keeping both would be two doors to
46
+ * one room, and a body whose `kind` disagreed with its path would have to mean something.
47
+ */
48
+ export interface ActionPayloadDto {
49
+ /** Target queue name — required for all queue/job actions; omitted for instance actions. */
50
+ queue?: string;
51
+ /** Target instance key — required for `pauseInstance` / `resumeInstance` / `removeInstance`. */
52
+ instanceKey?: string;
53
+ jobId?: string;
54
+ /**
55
+ * Many job ids for a bulk retry / cancel / remove. The server applies them in **one transaction**,
56
+ * so the batch either lands whole or not at all. Capped at {@link MAX_BATCH_IDS} ids per request.
57
+ */
58
+ jobIds?: string[];
59
+ scheduleId?: string;
60
+ /** Many schedule ids for a bulk removal, in one transaction. */
61
+ scheduleIds?: string[];
62
+ /** For `setScheduleEnabled`: whether the schedule should be armed. */
63
+ enabled?: boolean;
64
+ mode?: PauseMode;
65
+ add?: AddJobRequestDto;
66
+ }
67
+ /**
68
+ * A mutation, as the client's `api.action` takes it: the payload plus the `kind` that names the
69
+ * endpoint. `kind` is stripped into the URL before the request goes out and never reaches the wire.
70
+ */
71
+ export interface ActionRequestDto extends ActionPayloadDto {
72
+ kind: ActionKind;
73
+ }
74
+ export interface ActionResultDto {
75
+ ok: boolean;
76
+ jobId?: string;
77
+ scheduleId?: string;
78
+ /** Rows the action actually changed. */
79
+ affected?: number;
80
+ /** Ids submitted, when the action was a batch — so the UI can say "3 of 5". */
81
+ requested?: number;
82
+ /**
83
+ * Jobs a cancel could only *ask* to stop, because they are running in the dashboard's own process.
84
+ * Reported apart from `affected`: nothing has been cancelled yet, and a handler that ignores
85
+ * `job.signal` finishes normally.
86
+ */
87
+ signalled?: number;
88
+ }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Static config the server injects into the SPA shell.
3
+ *
4
+ * Only the mount path: the dashboard's title and its theme are the dashboard's own business. A
5
+ * host-set title made the browser tab and the header disagree with every screenshot and doc page,
6
+ * and a host-set default theme only pre-empted a choice the visitor makes in one click (and which
7
+ * `localStorage` then remembers).
8
+ */
9
+ export interface DashboardConfigDto {
10
+ basePath: string;
11
+ /**
12
+ * The most ids one bulk action may carry — core's `MAX_BATCH_IDS`, delivered rather than copied.
13
+ *
14
+ * The client needs it to stop a selection growing past what the server will accept, and it cannot
15
+ * import it: `@portqueue/core` reaches for `node:os`, `node:v8` and friends, so pulling a constant
16
+ * out of it drags Node builtins into the browser bundle. Sending the value keeps one source of
17
+ * truth for a limit the server enforces anyway.
18
+ */
19
+ maxBatchIds: number;
20
+ }
@@ -0,0 +1,37 @@
1
+ import { JobStatus } from '@portqueue/core';
2
+ /** JobStatus → count map, wire form. */
3
+ export type CountsDto = Record<string, number>;
4
+ /** A read-side job, serialized for the wire (mirrors core `JobSnapshot`). */
5
+ export interface JobDto {
6
+ id: string;
7
+ queue: string;
8
+ status: JobStatus;
9
+ data: unknown;
10
+ returnValue?: unknown;
11
+ priority: number;
12
+ retryAttempt: number;
13
+ retryMaxAttempts: number;
14
+ createdAt: string;
15
+ updatedAt: string;
16
+ startAfter: string;
17
+ startedAt?: string | null;
18
+ completedAt?: string | null;
19
+ failedAt?: string | null;
20
+ cancelledAt?: string | null;
21
+ expiredAt?: string | null;
22
+ retriedAt?: string | null;
23
+ stalledAt?: string | null;
24
+ lockedUntil?: string | null;
25
+ preferredInstanceKeyPattern?: string | null;
26
+ processedOnInstanceKey?: string | null;
27
+ failureMessage?: string | null;
28
+ idempotencyKey?: string | null;
29
+ scheduleId?: string | null;
30
+ stalled: boolean;
31
+ }
32
+ /** Page of jobs. `total` counts every match; a search counts them all, not just this window. */
33
+ export interface JobPageDto {
34
+ items: JobDto[];
35
+ /** Rows matching the query across every page. A search counts every match, not a window. */
36
+ total: number;
37
+ }
@@ -0,0 +1,50 @@
1
+ import { CountsDto } from './job';
2
+ /**
3
+ * One page of rows plus the total matching the query. Every list endpoint returns this shape,
4
+ * so a table's "Results (n)" and its rows can never disagree and paging is uniform across pages.
5
+ * A page that wants "is there more?" derives it from its own offset plus `items.length` against
6
+ * `total` — the server never sends a second, redundant flag that could contradict the count.
7
+ */
8
+ export interface PageDto<T> {
9
+ items: T[];
10
+ /** Rows matching the query across every page. */
11
+ total: number;
12
+ }
13
+ /**
14
+ * Queue overview (core `QueueInfo`, minus `inUse`).
15
+ *
16
+ * `inUse` means "declared in the process that produced this info", and the dashboard now runs on its
17
+ * own client rather than the application's — so it cannot know which queues the workers declare. A
18
+ * field that always answered "no" would be worse than no field. `pq.getQueues()` still carries it for
19
+ * application code, where it is meaningful.
20
+ */
21
+ export interface QueueDto {
22
+ name: string;
23
+ processingPaused: boolean;
24
+ acceptingPaused: boolean;
25
+ counts: CountsDto;
26
+ }
27
+ export type QueuePageDto = PageDto<QueueDto>;
28
+ /** Aggregated stats — per-status counts, which is all the activity cards render. */
29
+ export interface StatsDto {
30
+ queue?: string;
31
+ counts: CountsDto;
32
+ }
33
+ /** An instance row with liveness, process health + per-instance job attribution (mirrors `InstanceInfo`). */
34
+ export interface InstanceDto {
35
+ instanceKey: string;
36
+ processingPaused: boolean;
37
+ alive: boolean;
38
+ createdAt: string;
39
+ updatedAt: string;
40
+ lastSeenAt: string;
41
+ /**
42
+ * The health of the **Node process** behind this instance, at its last heartbeat, both 0-100:
43
+ * `cpuPercent` over the cores available to it, `memoryPercent` over V8's heap limit. Neither is
44
+ * machine-wide. Null until the instance's first beat.
45
+ */
46
+ cpuPercent: number | null;
47
+ memoryPercent: number | null;
48
+ counts: CountsDto;
49
+ }
50
+ export type InstancePageDto = PageDto<InstanceDto>;
@@ -0,0 +1,15 @@
1
+ import { PageDto } from './queue';
2
+ export interface ScheduleDto {
3
+ scheduleId: string;
4
+ queue: string;
5
+ cron?: string | null;
6
+ /** For an interval schedule: the seconds between runs. */
7
+ everySeconds?: number | null;
8
+ timezone?: string | null;
9
+ nextRunAt?: string | null;
10
+ lastRunAt?: string | null;
11
+ enabled: boolean;
12
+ /** The dedup token this schedule was created with, if any. */
13
+ idempotencyKey?: string | null;
14
+ }
15
+ export type SchedulePageDto = PageDto<ScheduleDto>;
@@ -0,0 +1,7 @@
1
+ /** Barrel for the wire DTOs. Split by concern under `dto/`; import from here. */
2
+ export type * from './dto/job';
3
+ export type * from './dto/queue';
4
+ export type * from './dto/schedule';
5
+ export type * from './dto/config';
6
+ export type { ActionPayloadDto, ActionRequestDto, ActionResultDto, AddJobRequestDto, } from './dto/action';
7
+ export { ActionKind } from './dto/action';
package/package.json CHANGED
@@ -1,6 +1,86 @@
1
1
  {
2
2
  "name": "@portqueue/dashboard",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Self-hostable React dashboard middleware for PortQueue.",
5
+ "license": "MIT",
6
+ "homepage": "https://episclera.github.io/portqueue",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/episclera/portqueue.git",
10
+ "directory": "packages/dashboard"
11
+ },
12
+ "keywords": [
13
+ "queue",
14
+ "job-queue",
15
+ "dashboard",
16
+ "monitoring",
17
+ "express",
18
+ "koa",
19
+ "fastify",
20
+ "nestjs"
21
+ ],
22
+ "type": "module",
23
+ "engines": {
24
+ "node": ">=20.11.0"
25
+ },
26
+ "main": "./dist/index.cjs",
27
+ "module": "./dist/index.mjs",
28
+ "types": "./dist/index.d.ts",
29
+ "exports": {
30
+ ".": {
31
+ "types": "./dist/index.d.ts",
32
+ "import": "./dist/index.mjs",
33
+ "require": "./dist/index.cjs"
34
+ }
35
+ },
36
+ "files": [
37
+ "dist",
38
+ "README.md",
39
+ "LICENSE"
40
+ ],
41
+ "publishConfig": {
42
+ "access": "public"
43
+ },
44
+ "scripts": {
45
+ "build": "vite build && vite build --config vite.client.config.ts",
46
+ "build:server": "vite build",
47
+ "build:client": "vite build --config vite.client.config.ts",
48
+ "lint": "tsc --noEmit && eslint src",
49
+ "test": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js --passWithNoTests",
50
+ "test:coverage": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js --coverage --passWithNoTests"
51
+ },
52
+ "peerDependencies": {
53
+ "@portqueue/core": "^0.2.0"
54
+ },
55
+ "devDependencies": {
56
+ "@ant-design/icons": "^6.3.2",
57
+ "@portqueue/core": "*",
58
+ "@portqueue/eslint-config": "*",
59
+ "@portqueue/ui": "*",
60
+ "@tanstack/react-query": "^5.62.0",
61
+ "@testing-library/jest-dom": "^6.4.6",
62
+ "@testing-library/react": "^15.0.7",
63
+ "@types/express": "^4.17.21",
64
+ "@types/jest": "^29.5.14",
65
+ "@types/koa": "^2.15.0",
66
+ "@types/node": "^22.10.0",
67
+ "@types/react": "^18.3.0",
68
+ "@types/react-dom": "^18.3.0",
69
+ "@types/react-router-dom": "^5.3.3",
70
+ "axios": "^1.7.9",
71
+ "clsx": "^2.1.0",
72
+ "eslint": "^9.17.0",
73
+ "express": "^4.21.0",
74
+ "fastify": "^5.2.0",
75
+ "jest": "^29.7.0",
76
+ "jest-environment-jsdom": "^29.7.0",
77
+ "koa": "^2.15.3",
78
+ "react": "^18.3.0",
79
+ "react-dom": "^18.3.0",
80
+ "react-router-dom": "^5.3.4",
81
+ "ts-jest": "^29.2.5",
82
+ "typescript": "^5.7.0",
83
+ "vite": "^6.0.0",
84
+ "vite-plugin-dts": "^4.4.0"
85
+ }
86
+ }