adonisjs-server-stats 1.12.3 → 1.14.0

package/dist/src/dashboard/integrations/adonisjs_queue_store.d.ts

@@ -0,0 +1,166 @@
+import type { QueueJobSummary, QueueJobDetail, QueueJobListResult } from './queue_inspector.js';
+/** JobStatus as stored in the queue_jobs table / Redis hashes. */
+type BoringJobStatus = 'pending' | 'active' | 'delayed' | 'completed' | 'failed';
+/** JobData — the JSON blob stored in queue_jobs.data / Redis ::data hash. */
+interface BoringJobData {
+    id: string;
+    name: string;
+    payload?: unknown;
+    attempts: number;
+    priority?: number;
+    nextRetryAt?: Date;
+    stalledCount?: number;
+    groupId?: string;
+    /** Unix ms timestamp set when the job was dispatched. */
+    createdAt?: number;
+    /** Not persisted per-row; best-effort from static job options. */
+    maxRetries?: number;
+    [key: string]: unknown;
+}
+/** JobRecord — returned by adapter.getJob / stored in completed|failed hashes. */
+interface BoringJobRecord {
+    status: BoringJobStatus;
+    data: BoringJobData;
+    finishedAt?: number;
+    error?: string;
+}
+/** Minimal Lucid db service interface. */
+interface LucidDb {
+    primaryConnectionName: string;
+    connection(name?: string): {
+        getWriteClient(): unknown;
+    };
+}
+/** Minimal @adonisjs/redis manager interface. */
+interface AdonisRedisManager {
+    connection(name?: string): AdonisRedisConnection;
+}
+/**
+ * Minimal ioredis-compatible connection interface.
+ * All methods present on a real ioredis client that we call.
+ */
+interface AdonisRedisConnection {
+    zcard(key: string): Promise<number>;
+    hlen(key: string): Promise<number>;
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    hget(key: string, field: string): Promise<string | null>;
+    hscan(key: string, cursor: string, countKeyword: string, count: string): Promise<[string, string[]]>;
+    hset(key: string, field: string, value: string): Promise<number>;
+    zadd(key: string, score: number, member: string): Promise<number>;
+    hdel(key: string, field: string): Promise<number>;
+    zrem(key: string, member: string): Promise<number>;
+    zscore(key: string, member: string): Promise<string | null>;
+    hkeys(key: string): Promise<string[]>;
+}
+/** Minimal adapter interface (only what we need for driver detection). */
+interface BoringAdapter {
+    constructor: {
+        name: string;
+    };
+}
+/** Minimal QueueManagerSingleton (only what we call). */
+interface BoringQueueManager {
+    use(name?: string): BoringAdapter;
+}
+/** Config shape for @adonisjs/queue. */
+interface QueueConfig {
+    default?: string;
+    adapters?: Record<string, {
+        connectionName?: string;
+    }>;
+    queues?: Record<string, unknown>;
+}
+/** Job counts aggregated across all configured queues. */
+export interface QueueCounts {
+    active: number;
+    waiting: number;
+    delayed: number;
+    completed: number;
+    failed: number;
+}
+/** Thin interface implemented by both the database and redis readers. */
+export interface QueueStoreReader {
+    getCounts(): Promise<QueueCounts>;
+    listJobs(status: QueueJobSummary['status'] | 'all', page: number, perPage: number): Promise<QueueJobListResult>;
+    getJob(id: string): Promise<QueueJobDetail | null>;
+    retryJob(id: string): Promise<boolean>;
+    getWorkerCount(): Promise<number>;
+}
+/**
+ * Map a @boringnode `JobRecord` (plus optional DB `acquired_at` timestamp) to
+ * the `QueueJobSummary` shape used by the dashboard.
+ *
+ * Known gaps (no per-row data; documented inline):
+ *   - `progress`: always 0 — @boringnode/queue does not persist per-row progress.
+ *   - `returnValue`: always null — not stored in the queue table/hash.
+ *   - `maxAttempts`: best-effort from `data.maxRetries`; falls back to `attempts`.
+ *   - `stackTrace`: collapsed to `[record.error]`; no real stack trace in store.
+ *
+ * @param record       The raw job record from the store.
+ * @param acquiredAtMs Unix-ms timestamp from DB `acquired_at` column, or null.
+ */
+export declare function mapJobRecordToSummary(record: BoringJobRecord, acquiredAtMs: number | null): QueueJobSummary;
+/** Pre-resolved services, accepted by the factory for both call paths. */
+export interface QueueStoreReaderServices {
+    queueManager: BoringQueueManager;
+    config: QueueConfig;
+    /** Lucid db instance — required for the database driver. */
+    db?: LucidDb;
+    /** AdonisJS redis manager — required for the redis driver. */
+    redis?: AdonisRedisManager;
+    /** Override the database/redis connection name derived from config. */
+    connectionName?: string;
+}
+/**
+ * Build a {@link QueueStoreReader} from already-resolved services.
+ *
+ * Both the inspector path (`app.container.make`) and the collector path
+ * (`appImport`) resolve their own services and pass them here.
+ * Returns a safe-defaults no-op reader if driver detection fails or the
+ * required service (db or redis) is absent.
+ */
+export declare function buildQueueStoreReader(services: QueueStoreReaderServices): QueueStoreReader;
+/** Minimal shape of the AdonisJS Application instance we depend on. */
+interface ApplicationLike {
+    config: {
+        get(key: string): unknown;
+    };
+    container: {
+        make(binding: string): Promise<unknown>;
+    };
+}
+/**
+ * Resolve services from an AdonisJS Application instance and build a store reader.
+ *
+ * This is the canonical resolver: the queue config lives in the app's
+ * `config/queue.ts` (there is no package-level config export), so it can only
+ * be read from `app.config.get('queue')`. Both the inspector and collector
+ * paths funnel through here.
+ *
+ * Returns null if @adonisjs/queue is not registered (e.g. wrong environment).
+ */
+export declare function resolveFromApplication(app: ApplicationLike): Promise<QueueStoreReader | null>;
+/**
+ * Resolve services for the inspector path.
+ *
+ * Accepts either a full Application-like object (with `config` + `container`)
+ * or a bare container (legacy). When given a bare container it resolves the
+ * application via the `app` binding to read the queue config.
+ *
+ * Returns null if @adonisjs/queue is not registered (e.g. wrong environment).
+ */
+export declare function resolveFromContainer(appOrContainer: ApplicationLike | {
+    make(binding: string): Promise<unknown>;
+}): Promise<QueueStoreReader | null>;
+/**
+ * Resolve services via `appImport` and build a store reader.
+ *
+ * Designed for the collector path where no IoC container reference is held.
+ * Resolves the running Application via `@adonisjs/core/services/app` (the same
+ * service the official `@adonisjs/queue` package uses), then reads the queue
+ * config and services from it.
+ *
+ * Returns null if @adonisjs/queue is not installed in the host application.
+ */
+export declare function resolveFromAppImport(): Promise<QueueStoreReader | null>;
+export {};