@mayurbhusare/resilient-queue-ui 0.0.0-stage → 1.0.0

package/src/handlers/dlq.js

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * Pure handler for querying Dead-Letter Queue (DLQ) jobs.
+ *
+ * @param {import("@mayurbhusare/resilient-queue").ResilientQueue} queue
+ * @param {object} [options]
+ * @param {number} [options.start=0]
+ * @param {number} [options.limit=50]
+ * @param {string} [options.order="asc"]
+ * @returns {Promise<{ total: number, jobs: Array<object> }>}
+ */
+async function handleGetDLQ(queue, options = {}) {
+  if (!queue || (typeof queue !== "object" && typeof queue !== "function")) {
+    throw new TypeError("Valid ResilientQueue instance is required");
+  }
+
+  // Pre-dispatch closed check: ResilientQueue sets `isClosed = true` on queue.close()
+  if (Boolean(queue.isClosed)) {
+    const error = new Error("Queue is closed");
+    error.code = "QUEUE_CLOSED";
+    error.statusCode = 503;
+    throw error;
+  }
+
+  try {
+    const dlqResult = await queue.getDLQ(options);
+    return {
+      total: Number(dlqResult?.total) || 0,
+      jobs: Array.isArray(dlqResult?.jobs) ? dlqResult.jobs : []
+    };
+  } catch (err) {
+    // Defense-in-depth: Catch "Queue is closed" or closed errors
+    if (
+      err &&
+      (err.code === "QUEUE_CLOSED" ||
+        (typeof err.message === "string" && /queue is closed/i.test(err.message)))
+    ) {
+      const closedError = new Error("Queue is closed");
+      closedError.code = "QUEUE_CLOSED";
+      closedError.statusCode = 503;
+      throw closedError;
+    }
+
+    throw err;
+  }
+}
+
+module.exports = {
+  handleGetDLQ
+};

package/src/handlers/job.js

@@ -0,0 +1,87 @@
+"use strict";
+
+/**
+ * Safely serializes a Job descriptor, omitting non-serializable properties (such as updateProgress).
+ *
+ * @param {object} job Raw Job instance or object
+ * @returns {object|null}
+ */
+function serializeJob(job) {
+  if (!job || typeof job !== "object") {
+    return null;
+  }
+
+  const serialized = {};
+  for (const [key, value] of Object.entries(job)) {
+    // Explicitly omit function-valued properties (e.g. updateProgress)
+    if (typeof value === "function") {
+      continue;
+    }
+    // Omit undefined values
+    if (value !== undefined) {
+      serialized[key] = value;
+    }
+  }
+
+  return serialized;
+}
+
+/**
+ * Pure handler for retrieving a persisted job by ID.
+ *
+ * @param {import("@mayurbhusare/resilient-queue").ResilientQueue} queue
+ * @param {string} jobId
+ * @returns {Promise<object|null>}
+ */
+async function handleGetJob(queue, jobId) {
+  if (!queue || (typeof queue !== "object" && typeof queue !== "function")) {
+    throw new TypeError("Valid ResilientQueue instance is required");
+  }
+
+  if (jobId === undefined || jobId === null || typeof jobId !== "string" || jobId.trim().length === 0) {
+    throw new TypeError("jobId must be a non-empty string");
+  }
+
+  // Pre-dispatch closed check: ResilientQueue sets `isClosed = true` on queue.close()
+  if (Boolean(queue.isClosed)) {
+    const error = new Error("Queue is closed");
+    error.code = "QUEUE_CLOSED";
+    error.statusCode = 503;
+    throw error;
+  }
+
+  if (typeof queue.getJob !== "function") {
+    const notSupportedError = new Error("Queue instance does not implement getJob");
+    notSupportedError.code = "NOT_SUPPORTED";
+    notSupportedError.statusCode = 501;
+    throw notSupportedError;
+  }
+
+  try {
+    const job = await queue.getJob(jobId.trim());
+    if (!job) {
+      return null;
+    }
+
+    return serializeJob(job);
+  } catch (err) {
+    // Defense-in-depth: Catch "Queue is closed" or closed errors
+    if (
+      err &&
+      (err.code === "QUEUE_CLOSED" ||
+        (typeof err.message === "string" && /queue is closed/i.test(err.message)))
+    ) {
+      const closedError = new Error("Queue is closed");
+      closedError.code = "QUEUE_CLOSED";
+      closedError.statusCode = 503;
+      throw closedError;
+    }
+
+    throw err;
+  }
+}
+
+module.exports = {
+  handleGetJob,
+  serializeJob
+};

package/src/handlers/metrics.js

@@ -0,0 +1,60 @@
+"use strict";
+
+/**
+ * Pure handler for retrieving queue metrics and pause state.
+ *
+ * @param {import("@mayurbhusare/resilient-queue").ResilientQueue} queue
+ * @param {object} [options]
+ * @param {boolean} [options.localOnlyPaused=false]
+ * @returns {Promise<{ isPaused: boolean, metrics: { waiting: number, active: number, delayed: number, dlq: number } }>}
+ */
+async function handleGetMetrics(queue, options = {}) {
+  if (!queue || (typeof queue !== "object" && typeof queue !== "function")) {
+    throw new TypeError("Valid ResilientQueue instance is required");
+  }
+
+  // Pre-dispatch closed check: ResilientQueue sets `isClosed = true` on queue.close()
+  if (Boolean(queue.isClosed)) {
+    const error = new Error("Queue is closed");
+    error.code = "QUEUE_CLOSED";
+    error.statusCode = 503;
+    throw error;
+  }
+
+  const localOnly = Boolean(options && options.localOnlyPaused);
+
+  try {
+    const [isPaused, metrics] = await Promise.all([
+      queue.isPaused({ localOnly }),
+      queue.getMetrics()
+    ]);
+
+    return {
+      isPaused: Boolean(isPaused),
+      metrics: {
+        waiting: Number(metrics?.waiting) || 0,
+        active: Number(metrics?.active) || 0,
+        delayed: Number(metrics?.delayed) || 0,
+        dlq: Number(metrics?.dlq) || 0
+      }
+    };
+  } catch (err) {
+    // Defense-in-depth: Catch "Queue is closed" thrown by queue.getMetrics()
+    if (
+      err &&
+      (err.code === "QUEUE_CLOSED" ||
+        (typeof err.message === "string" && /queue is closed/i.test(err.message)))
+    ) {
+      const closedError = new Error("Queue is closed");
+      closedError.code = "QUEUE_CLOSED";
+      closedError.statusCode = 503;
+      throw closedError;
+    }
+
+    throw err;
+  }
+}
+
+module.exports = {
+  handleGetMetrics
+};

package/src/handlers/queues.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const { handleGetMetrics } = require("./metrics");
+
+/**
+ * Pure handler for retrieving a summary list of all explicitly registered queues,
+ * their current pause state, and instantaneous metrics.
+ *
+ * @param {import("../registry").QueueRegistry|Map<string, object>|Record<string, object>|Array<{ name: string, queue: object }>} registry
+ * @param {object} [options]
+ * @param {boolean} [options.localOnlyPaused=false]
+ * @returns {Promise<{ queues: Array<{ name: string, isPaused: boolean, metrics: { waiting: number, active: number, delayed: number, dlq: number } }> }>}
+ */
+async function handleGetQueues(registry, options = {}) {
+  if (!registry || typeof registry !== "object") {
+    throw new TypeError("Valid QueueRegistry instance or queue map is required");
+  }
+
+  let entries;
+  if (typeof registry.getEntries === "function") {
+    entries = registry.getEntries();
+  } else if (registry instanceof Map) {
+    entries = Array.from(registry.entries()).map(([name, queue]) => ({
+      name,
+      queue
+    }));
+  } else if (Array.isArray(registry)) {
+    entries = registry;
+  } else {
+    entries = Object.entries(registry).map(([name, queue]) => ({
+      name,
+      queue
+    }));
+  }
+
+  if (entries.length === 0) {
+    return { queues: [] };
+  }
+
+  const localOnlyPaused = Boolean(options && options.localOnlyPaused);
+
+  const queues = await Promise.all(
+    entries.map(async ({ name, queue }) => {
+      const result = await handleGetMetrics(queue, { localOnlyPaused });
+      return {
+        name,
+        isPaused: result.isPaused,
+        metrics: result.metrics
+      };
+    })
+  );
+
+  return { queues };
+}
+
+module.exports = {
+  handleGetQueues
+};

package/src/index.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * @mayurbhusare/resilient-queue-ui
+ * Standalone administration dashboard and API adapter for @mayurbhusare/resilient-queue.
+ */
+
+const { QueueRegistry, createQueueRegistry } = require("./registry");
+const { handleGetMetrics } = require("./handlers/metrics");
+const { handleGetDLQ } = require("./handlers/dlq");
+const { handleGetJob, serializeJob } = require("./handlers/job");
+const { handleGetQueues } = require("./handlers/queues");
+const {
+  DashboardDispatcher,
+  createDashboardDispatcher,
+  createErrorResponse,
+  parseDLQQueryParams,
+  sanitizeErrorMessage
+} = require("./dispatcher");
+const { createExpressAdapter } = require("./adapters/express");
+const { fastifyDashboardPlugin } = require("./adapters/fastify");
+const { ApiClient, ApiError } = require("./ui/api-client");
+
+const VERSION = "1.0.0";
+
+module.exports = {
+  VERSION,
+  QueueRegistry,
+  createQueueRegistry,
+  handleGetMetrics,
+  handleGetDLQ,
+  handleGetJob,
+  handleGetQueues,
+  serializeJob,
+  DashboardDispatcher,
+  createDashboardDispatcher,
+  createExpressAdapter,
+  fastifyDashboardPlugin,
+  createErrorResponse,
+  parseDLQQueryParams,
+  sanitizeErrorMessage,
+  ApiClient,
+  ApiError
+};

package/src/registry.js

@@ -0,0 +1,102 @@
+"use strict";
+
+/**
+ * Queue Registry for @mayurbhusare/resilient-queue-ui.
+ * Manages explicit registration and lookup of ResilientQueue instances.
+ */
+class QueueRegistry {
+  constructor(options) {
+    if (!options || typeof options !== "object") {
+      throw new TypeError("Dashboard adapter options must be an object");
+    }
+
+    if (!options.queues) {
+      throw new TypeError(
+        "options.queues is required and must be an object, Map, or array of queue entries"
+      );
+    }
+
+    this._queues = new Map();
+    this._normalize(options.queues);
+  }
+
+  _register(name, queue) {
+    if (!name || typeof name !== "string" || name.trim().length === 0) {
+      throw new TypeError("Queue name must be a non-empty string");
+    }
+
+    if (!queue || (typeof queue !== "object" && typeof queue !== "function")) {
+      throw new TypeError(`Queue instance is required for queue '${name}'`);
+    }
+
+    const normalizedName = name.trim();
+    if (this._queues.has(normalizedName)) {
+      throw new Error(`Duplicate queue name registered: '${normalizedName}'`);
+    }
+
+    this._queues.set(normalizedName, queue);
+  }
+
+  _normalize(queues) {
+    if (Array.isArray(queues)) {
+      for (const entry of queues) {
+        if (!entry || typeof entry !== "object") {
+          throw new TypeError(
+            "Each queue entry in the array must be an object with name and queue properties"
+          );
+        }
+        this._register(entry.name, entry.queue);
+      }
+    } else if (queues instanceof Map) {
+      for (const [name, queue] of queues.entries()) {
+        this._register(name, queue);
+      }
+    } else if (typeof queues === "object" && queues !== null) {
+      for (const [name, queue] of Object.entries(queues)) {
+        this._register(name, queue);
+      }
+    } else {
+      throw new TypeError(
+        "options.queues must be an object, Map, or array of queue entries"
+      );
+    }
+  }
+
+  get(name) {
+    if (!name || typeof name !== "string") {
+      return undefined;
+    }
+    return this._queues.get(name.trim());
+  }
+
+  has(name) {
+    if (!name || typeof name !== "string") {
+      return false;
+    }
+    return this._queues.has(name.trim());
+  }
+
+  getNames() {
+    return Array.from(this._queues.keys());
+  }
+
+  getEntries() {
+    return Array.from(this._queues.entries()).map(([name, queue]) => ({
+      name,
+      queue
+    }));
+  }
+
+  get size() {
+    return this._queues.size;
+  }
+}
+
+function createQueueRegistry(options) {
+  return new QueueRegistry(options);
+}
+
+module.exports = {
+  QueueRegistry,
+  createQueueRegistry
+};

package/src/ui/api-client.js

@@ -0,0 +1,228 @@
+"use strict";
+
+/**
+ * Custom error class for API errors returned by resilient-queue-ui endpoints or network issues.
+ */
+class ApiError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.status = typeof options.status === "number" ? options.status : 0;
+    this.code = options.code || "UNKNOWN_ERROR";
+    this.details = options.details !== undefined ? options.details : null;
+    this.rawResponse = options.rawResponse !== undefined ? options.rawResponse : null;
+  }
+}
+
+/**
+ * Frontend API client for interacting with @mayurbhusare/resilient-queue-ui REST endpoints.
+ * Conforms strictly to docs/api-contract.md.
+ */
+class ApiClient {
+  /**
+   * @param {object|string} [options={}] Configuration options or baseUrl string
+   * @param {string} [options.baseUrl=""] Base URL for API calls (e.g. "/admin/queues" or "http://localhost:3000")
+   * @param {typeof fetch} [options.fetch] Custom fetch implementation (defaults to globalThis.fetch)
+   */
+  constructor(options = {}) {
+    const config = typeof options === "string" ? { baseUrl: options } : options || {};
+    this.baseUrl = (config.baseUrl || "").replace(/\/+$/, "");
+    this.fetch = config.fetch || (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : undefined);
+  }
+
+  /**
+   * Constructs an absolute or relative URL with encoded path segments and query parameters.
+   *
+   * @param {string} path API path starting with "/"
+   * @param {Record<string, any>} [query={}] Optional query parameter dictionary
+   * @returns {string} Fully resolved URL string
+   */
+  buildUrl(path, query = {}) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const urlStr = `${this.baseUrl}${normalizedPath}`;
+
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") {
+        params.append(key, String(value));
+      }
+    }
+    const queryString = params.toString();
+    return queryString ? `${urlStr}?${queryString}` : urlStr;
+  }
+
+  /**
+   * Executes an HTTP GET request and normalizes responses or errors.
+   *
+   * @private
+   * @param {string} url
+   * @returns {Promise<any>}
+   */
+  async _request(url) {
+    if (typeof this.fetch !== "function") {
+      throw new ApiError("No fetch implementation available in the current environment", {
+        code: "ENVIRONMENT_ERROR",
+        status: 0
+      });
+    }
+
+    let response;
+    try {
+      response = await this.fetch(url, {
+        method: "GET",
+        headers: {
+          Accept: "application/json"
+        }
+      });
+    } catch (networkErr) {
+      throw new ApiError(networkErr?.message || "Network request failed", {
+        code: "NETWORK_ERROR",
+        status: 0,
+        details: networkErr
+      });
+    }
+
+    const text = await response.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch (parseErr) {
+      if (!response.ok) {
+        throw new ApiError(`HTTP error ${response.status}`, {
+          code: "HTTP_ERROR",
+          status: response.status,
+          rawResponse: text
+        });
+      }
+      throw new ApiError("Invalid JSON response from server", {
+        code: "PARSE_ERROR",
+        status: response.status,
+        rawResponse: text,
+        details: parseErr
+      });
+    }
+
+    if (!response.ok) {
+      const errorCode = data?.error?.code || "HTTP_ERROR";
+      const errorMessage = data?.error?.message || `HTTP error ${response.status}`;
+      const errorDetails = data?.error?.details !== undefined ? data.error.details : null;
+
+      throw new ApiError(errorMessage, {
+        code: errorCode,
+        status: response.status,
+        details: errorDetails,
+        rawResponse: data
+      });
+    }
+
+    return data;
+  }
+
+  /**
+   * GET /api/queues
+   * Retrieves summary and metrics for all explicitly registered queues.
+   *
+   * @returns {Promise<{ queues: Array<{ name: string, isPaused: boolean, metrics: { waiting: number, active: number, delayed: number, dlq: number } }> }>}
+   */
+  async getQueues() {
+    const url = this.buildUrl("/api/queues");
+    return this._request(url);
+  }
+
+  /**
+   * GET /api/queues/:queueName/metrics
+   * Retrieves instantaneous metrics and pause status for a single registered queue.
+   *
+   * @param {string} queueName
+   * @returns {Promise<{ queue: string, isPaused: boolean, metrics: { waiting: number, active: number, delayed: number, dlq: number } }>}
+   */
+  async getQueueMetrics(queueName) {
+    const normalizedQueueName = queueName !== undefined && queueName !== null ? String(queueName).trim() : "";
+    if (normalizedQueueName.length === 0) {
+      throw new ApiError("queueName must be a non-empty string", {
+        code: "VALIDATION_ERROR",
+        status: 400
+      });
+    }
+
+    const encodedName = encodeURIComponent(normalizedQueueName);
+    const url = this.buildUrl(`/api/queues/${encodedName}/metrics`);
+    return this._request(url);
+  }
+
+  /**
+   * GET /api/queues/:queueName/dlq
+   * Retrieves paginated DLQ jobs for a registered queue.
+   *
+   * @param {string} queueName
+   * @param {object} [query={}]
+   * @param {number} [query.start]
+   * @param {number} [query.limit]
+   * @param {"asc"|"desc"} [query.order]
+   * @returns {Promise<{ queue: string, total: number, start: number, limit: number, order: string, jobs: Array<object> }>}
+   */
+  async getQueueDLQ(queueName, query = {}) {
+    const normalizedQueueName = queueName !== undefined && queueName !== null ? String(queueName).trim() : "";
+    if (normalizedQueueName.length === 0) {
+      throw new ApiError("queueName must be a non-empty string", {
+        code: "VALIDATION_ERROR",
+        status: 400
+      });
+    }
+
+    const encodedName = encodeURIComponent(normalizedQueueName);
+    const queryParams = {};
+    if (query.start !== undefined && query.start !== null) queryParams.start = query.start;
+    if (query.limit !== undefined && query.limit !== null) queryParams.limit = query.limit;
+    if (query.order !== undefined && query.order !== null) queryParams.order = query.order;
+
+    const url = this.buildUrl(`/api/queues/${encodedName}/dlq`, queryParams);
+    return this._request(url);
+  }
+
+  /**
+   * GET /api/queues/:queueName/jobs/:jobId
+   * Retrieves single job descriptor by unique job ID.
+   *
+   * @param {string} queueName
+   * @param {string|number} jobId
+   * @returns {Promise<{ queue: string, job: object }>}
+   */
+  async getJob(queueName, jobId) {
+    const normalizedQueueName = queueName !== undefined && queueName !== null ? String(queueName).trim() : "";
+    if (normalizedQueueName.length === 0) {
+      throw new ApiError("queueName must be a non-empty string", {
+        code: "VALIDATION_ERROR",
+        status: 400
+      });
+    }
+
+    const normalizedJobId = jobId !== undefined && jobId !== null ? String(jobId).trim() : "";
+    if (normalizedJobId.length === 0) {
+      throw new ApiError("jobId must be a non-empty string", {
+        code: "VALIDATION_ERROR",
+        status: 400
+      });
+    }
+
+    const encodedName = encodeURIComponent(normalizedQueueName);
+    const encodedJobId = encodeURIComponent(normalizedJobId);
+    const url = this.buildUrl(`/api/queues/${encodedName}/jobs/${encodedJobId}`);
+    return this._request(url);
+  }
+}
+
+// Universal module definition supporting Node.js (CommonJS) and browser globals
+if (typeof module !== "undefined" && module.exports) {
+  module.exports = {
+    ApiClient,
+    ApiError
+  };
+}
+
+if (typeof globalThis !== "undefined") {
+  globalThis.ResilientQueueApiClient = {
+    ApiClient,
+    ApiError
+  };
+}