nvent 0.4.0

package/dist/runtime/server/utils/useServerLogger.js

@@ -0,0 +1,54 @@
+import { useRuntimeConfig } from "#imports";
+import { consola } from "consola";
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+const loggerCache = /* @__PURE__ */ new Map();
+export function useServerLogger(scope) {
+  const rc = useRuntimeConfig();
+  const debugConfig = rc?.queue?.debug;
+  const configLevel = debugConfig?.level || process.env.NQ_DEBUG_LEVEL || "info";
+  const globalLevelNum = configLevel === "silent" ? Infinity : LOG_LEVELS[configLevel] ?? LOG_LEVELS.info;
+  const scopeKey = scope.replace(/[^a-z0-9]/gi, "_").toLowerCase();
+  const envKey = `NQ_DEBUG_${scopeKey.toUpperCase()}`;
+  const isScopeDebugEnabled = debugConfig?.[scopeKey] === true || process.env[envKey] === "1";
+  let scopedConsola = loggerCache.get(scope);
+  if (!scopedConsola) {
+    scopedConsola = consola.withTag(scope);
+    loggerCache.set(scope, scopedConsola);
+  }
+  const logger = scopedConsola;
+  function isEnabled(level) {
+    const levelNum = LOG_LEVELS[level];
+    if (isScopeDebugEnabled && level === "debug") {
+      return true;
+    }
+    return levelNum >= globalLevelNum;
+  }
+  function log(level, message, context) {
+    if (!isEnabled(level)) return;
+    if (context && Object.keys(context).length > 0) {
+      logger[level](message, context);
+    } else {
+      logger[level](message);
+    }
+  }
+  return {
+    debug: (message, context) => log("debug", message, context),
+    info: (message, context) => log("info", message, context),
+    warn: (message, context) => log("warn", message, context),
+    error: (message, context) => log("error", message, context),
+    log,
+    isEnabled,
+    consola: logger
+  };
+}
+export function isDebugEnabled() {
+  const rc = useRuntimeConfig();
+  const debugConfig = rc?.queue?.debug;
+  const level = debugConfig?.level || process.env.NQ_DEBUG_LEVEL;
+  return level === "debug" || Object.keys(debugConfig || {}).some((key) => key !== "level");
+}

package/dist/runtime/server/utils/wsPeerManager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WebSocket Peer Manager
+ *
+ * Tracks active WebSocket connections for graceful shutdown during HMR.
+ * Auto-imported in Nitro server context.
+ */
+/**
+ * Register a peer to be tracked for graceful shutdown
+ */
+export declare function registerWsPeer(peer: any): void;
+/**
+ * Unregister a peer (called when connection closes normally)
+ */
+export declare function unregisterWsPeer(peer: any): void;
+/**
+ * Get all currently active WebSocket peers
+ */
+export declare function getActivePeers(): any[];
+/**
+ * Check if server is currently shutting down
+ */
+export declare function isServerShuttingDown(): boolean;
+/**
+ * Set the shutdown state
+ */
+export declare function setShuttingDown(state: boolean): void;
+/**
+ * Clear all tracked peers
+ */
+export declare function clearAllPeers(): void;
+/**
+ * Get the count of active peers
+ */
+export declare function getActivePeerCount(): number;

package/dist/runtime/server/utils/wsPeerManager.js

@@ -0,0 +1,23 @@
+const activePeers = /* @__PURE__ */ new Set();
+let isShuttingDown = false;
+export function registerWsPeer(peer) {
+  activePeers.add(peer);
+}
+export function unregisterWsPeer(peer) {
+  activePeers.delete(peer);
+}
+export function getActivePeers() {
+  return Array.from(activePeers);
+}
+export function isServerShuttingDown() {
+  return isShuttingDown;
+}
+export function setShuttingDown(state) {
+  isShuttingDown = state;
+}
+export function clearAllPeers() {
+  activePeers.clear();
+}
+export function getActivePeerCount() {
+  return activePeers.size;
+}

package/dist/runtime/server/worker/adapter.d.ts

@@ -0,0 +1,4 @@
+import { Worker } from 'bullmq';
+import { type NodeHandler } from './runner/node.js';
+export declare function closeAllWorkers(): Promise<void>;
+export declare function registerTsWorker(queueName: string, jobName: string, handler: NodeHandler, opts?: any): Promise<Worker<any, any, string>>;

package/dist/runtime/server/worker/adapter.js

@@ -0,0 +1,65 @@
+import { Worker } from "bullmq";
+import { createBullMQProcessor } from "./runner/node.js";
+import { useRuntimeConfig, useServerLogger } from "#imports";
+const registeredWorkers = /* @__PURE__ */ new Map();
+const logger = useServerLogger("worker-adapter");
+export async function closeAllWorkers() {
+  const closePromises = [];
+  for (const [queueName, info] of registeredWorkers.entries()) {
+    closePromises.push(
+      info.worker.close().catch((err) => {
+        if (err.code !== "EPIPE" && !err.message?.includes("Connection is closed")) {
+          logger.warn("Error closing worker for queue", { queueName, error: err });
+        }
+      })
+    );
+  }
+  await Promise.allSettled(closePromises);
+  registeredWorkers.clear();
+  logger.info("[closeAllWorkers] All workers closed");
+}
+export async function registerTsWorker(queueName, jobName, handler, opts) {
+  let info = registeredWorkers.get(queueName);
+  if (info) {
+    logger.info(`[registerTsWorker] Adding handler for job "${jobName}" to existing worker for queue "${queueName}"`);
+    info.handlers.set(jobName, handler);
+    return info.worker;
+  }
+  logger.info(`[registerTsWorker] Creating new worker for queue: ${queueName}`);
+  const handlers = /* @__PURE__ */ new Map();
+  handlers.set(jobName, handler);
+  const dispatcher = async (job) => {
+    const handler2 = handlers.get(job.name);
+    if (!handler2) {
+      const error = `[Worker] No handler registered for job "${job.name}" on queue "${queueName}". Available handlers: ${Array.from(handlers.keys()).join(", ")}`;
+      logger.error(error);
+      throw new Error(error);
+    }
+    const processor = createBullMQProcessor(handler2, queueName);
+    return processor(job);
+  };
+  const rc = useRuntimeConfig();
+  const connection = rc?.queue?.queue?.redis;
+  const shouldPause = opts?.autorun === false;
+  const worker = new Worker(queueName, dispatcher, { connection, ...opts || {} });
+  if (shouldPause) {
+    await worker.pause();
+    logger.info(`[registerTsWorker] Worker for queue "${queueName}" created but paused (autorun: false)`);
+  } else {
+    logger.info(`[registerTsWorker] Worker for queue "${queueName}" created and running`);
+  }
+  worker.on("error", (err) => {
+    logger.error(`[Worker] Error in worker for queue "${queueName}":`, err);
+  });
+  worker.on("failed", (job, err) => {
+    logger.error(`[Worker] Job failed in worker for queue "${queueName}":`, {
+      jobId: job?.id,
+      jobName: job?.name,
+      error: err.message,
+      stack: err.stack
+    });
+  });
+  info = { worker, handlers };
+  registeredWorkers.set(queueName, info);
+  return worker;
+}

package/dist/runtime/server/worker/runner/node.d.ts

@@ -0,0 +1,27 @@
+import type { Job as BullJob } from 'bullmq';
+import { useFlowEngine } from '#imports';
+export interface RunLogger {
+    log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string, meta?: any) => void;
+}
+export interface RunState {
+    get<T = any>(key: string): Promise<T | null>;
+    set<T = any>(key: string, value: T, opts?: {
+        ttl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface RunContext {
+    jobId?: string;
+    queue?: string;
+    flowId?: string;
+    flowName?: string;
+    stepName?: string;
+    stepId?: string;
+    attempt?: number;
+    logger: RunLogger;
+    state: RunState;
+    flow: ReturnType<typeof useFlowEngine>;
+}
+export declare function buildContext(partial?: Partial<RunContext>): RunContext;
+export type NodeHandler = (input: any, ctx: RunContext) => Promise<any>;
+export declare function createBullMQProcessor(handler: NodeHandler, queueName: string): (job: BullJob) => Promise<any>;

package/dist/runtime/server/worker/runner/node.js

@@ -0,0 +1,196 @@
+import { randomUUID } from "node:crypto";
+import { getStateProvider } from "../../state/stateFactory.js";
+import { useRuntimeConfig, useLogs, useFlowEngine, useEventManager, useServerLogger } from "#imports";
+const logger = useServerLogger("node-runner");
+const defaultState = {
+  async get() {
+    return null;
+  },
+  async set() {
+  },
+  async delete() {
+  }
+};
+function scopeKey(baseKey, flowId) {
+  if (!flowId) return baseKey;
+  return `flow:${flowId}:${baseKey}`;
+}
+export function buildContext(partial) {
+  const state = partial?.state || (() => {
+    try {
+      const state2 = getStateProvider();
+      const rc = useRuntimeConfig();
+      const cleanupCfg = rc?.queue?.state?.cleanup || { strategy: "never" };
+      return {
+        async get(key) {
+          return state2.get(scopeKey(key, partial?.flowId));
+        },
+        async set(key, value, opts) {
+          const ttl = opts?.ttl ?? (cleanupCfg?.strategy === "ttl" ? cleanupCfg?.ttlMs : void 0);
+          return state2.set(scopeKey(key, partial?.flowId), value, ttl ? { ttl } : void 0);
+        },
+        async delete(key) {
+          return state2.delete(scopeKey(key, partial?.flowId));
+        }
+      };
+    } catch {
+      return defaultState;
+    }
+  })();
+  const logger2 = partial?.logger || (() => {
+    const logs = useLogs();
+    return {
+      log: (level, msg, meta) => {
+        const mergedMeta = { ...meta || {} };
+        void logs.publishLog(level, msg, mergedMeta, { queue: partial?.queue, jobId: partial?.jobId, flowId: partial?.flowId });
+      }
+    };
+  })();
+  const baseFlowEngine = useFlowEngine();
+  const flow = {
+    ...baseFlowEngine,
+    emit: async (trigger, payload = {}) => {
+      const enrichedPayload = {
+        ...payload,
+        flowId: payload.flowId || partial?.flowId,
+        flowName: payload.flowName || partial?.flowName
+      };
+      return baseFlowEngine.emit(trigger, enrichedPayload);
+    }
+  };
+  return {
+    jobId: partial?.jobId,
+    queue: partial?.queue,
+    flowId: partial?.flowId,
+    flowName: partial?.flowName,
+    stepName: partial?.stepName,
+    stepId: partial?.stepId,
+    attempt: partial?.attempt,
+    logger: logger2,
+    state,
+    flow
+  };
+}
+export function createBullMQProcessor(handler, queueName) {
+  return async function processor(job) {
+    if (job.data?.__scheduledFlowStart) {
+      const { __flowName, __flowInput } = job.data;
+      try {
+        const { startFlow } = useFlowEngine();
+        const result2 = await startFlow(__flowName, __flowInput || {});
+        return {
+          scheduled: true,
+          flowId: result2.flowId,
+          flowName: __flowName
+        };
+      } catch (err) {
+        logger.error("[scheduled-flow] Failed to start flow:", err);
+        throw err;
+      }
+    }
+    const eventMgr = useEventManager();
+    const rc = useRuntimeConfig();
+    const autoScope = rc?.queue?.state?.autoScope || "always";
+    const providedFlow = job.data?.flowId;
+    const flowId = providedFlow || (autoScope === "always" ? randomUUID() : void 0);
+    const attempt = (job.attemptsMade || 0) + 1;
+    const maxAttempts = job.opts?.attempts || 1;
+    const isFinalAttempt = attempt >= maxAttempts;
+    const stepRunId = `${String(flowId || job.id)}__${job.name}__attempt-${attempt}`;
+    const flowName = job.data?.flowName || "unknown";
+    const ctx = buildContext({
+      jobId: job.id,
+      queue: queueName,
+      flowId,
+      flowName,
+      stepName: job.name,
+      stepId: stepRunId,
+      attempt
+    });
+    const attemptLogger = {
+      log: (level, msg, meta) => {
+        const enriched = { ...meta || {}, stepName: job.name, attempt, stepRunId, flowName };
+        ctx.logger.log(level, msg, enriched);
+      }
+    };
+    try {
+      await eventMgr.publishBus({
+        type: "step.started",
+        runId: flowId || "unknown",
+        flowName,
+        stepName: job.name,
+        stepId: stepRunId,
+        attempt,
+        data: { jobId: job.id, name: job.name, queue: queueName }
+      });
+    } catch {
+    }
+    let result;
+    try {
+      const workerInput = job.data?.input !== void 0 ? job.data.input : job.data;
+      result = await handler(workerInput, { ...ctx, logger: attemptLogger });
+    } catch (err) {
+      logger.error(`[worker] Job failed: ${job.name} (${job.id})`, {
+        queue: queueName,
+        flowId,
+        flowName,
+        stepName: job.name,
+        error: err?.message || String(err),
+        stack: err?.stack
+      });
+      const willRetry = !isFinalAttempt;
+      try {
+        await eventMgr.publishBus({
+          type: "step.failed",
+          runId: flowId || "unknown",
+          flowName,
+          stepName: job.name,
+          stepId: stepRunId,
+          attempt,
+          data: {
+            error: String(err?.message || err),
+            stack: err?.stack
+          }
+        });
+      } catch {
+      }
+      if (willRetry) {
+        try {
+          await eventMgr.publishBus({
+            type: "step.retry",
+            runId: flowId || "unknown",
+            flowName,
+            stepName: job.name,
+            stepId: stepRunId,
+            attempt,
+            data: {
+              stepName: job.name,
+              queue: queueName,
+              error: String(err?.message || err),
+              stack: err?.stack,
+              attempt,
+              maxAttempts,
+              nextAttempt: attempt + 1
+            }
+          });
+        } catch {
+        }
+      }
+      throw err;
+    }
+    try {
+      const eventMgr2 = useEventManager();
+      await eventMgr2.publishBus({
+        type: "step.completed",
+        runId: flowId || "unknown",
+        flowName,
+        stepName: job.name,
+        stepId: stepRunId,
+        attempt,
+        data: { result }
+      });
+    } catch {
+    }
+    return result;
+  };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,132 @@
+import type { WorkerOptions as BullmqWorkerOptions } from 'bullmq'
+import type z from 'zod'
+import type colors from 'tailwindcss/colors'
+import type { JobSchemaArray, JobSchema } from './schema'
+
+type NeutralColor = 'slate' | 'gray' | 'zinc' | 'neutral' | 'stone'
+export type Color = Exclude<keyof typeof colors, 'inherit' | 'current' | 'transparent' | 'black' | 'white' | NeutralColor> | NeutralColor
+
+export type Jobs = z.infer<typeof JobSchemaArray>
+export type Job = z.infer<typeof JobSchema>
+
+export type WorkerOptions = Omit<BullmqWorkerOptions, 'connection' | 'useWorkerThreads'>
+
+export type WorkerConfig = Record<string, WorkerOptions>
+
+export type QueueData = {
+  name: string
+  origin: 'remote' | 'local'
+  active: boolean
+  jobs: JobCounts
+  worker: number
+}
+
+// Declarations for worker authoring helpers available via auto-imports at runtime
+// These declarations make TS happy in worker files and tests.
+export declare function defineQueueWorker(processor: (...args: any[]) => any): any
+export declare function defineQueueConfig(cfg: any): any
+
+// v0.4 Event Schema
+export type EventType = 'flow.start' | 'flow.completed' | 'flow.failed' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retry' | 'log' | 'emit' | 'state'
+
+export interface BaseEvent {
+  id?: string // Redis stream ID (auto-generated, not present for ingress events)
+  ts?: string // ISO timestamp (auto-generated, not present for ingress events)
+  type: EventType
+  runId: string // Flow run UUID
+  flowName: string // Flow definition name
+}
+
+export interface StepEvent extends BaseEvent {
+  stepName: string
+  stepId: string
+  attempt: number
+}
+
+export interface FlowStartEvent extends BaseEvent {
+  type: 'flow.start'
+  data?: {
+    input?: any
+  }
+}
+
+export interface FlowCompletedEvent extends BaseEvent {
+  type: 'flow.completed'
+  data?: {
+    result?: any
+  }
+}
+
+export interface FlowFailedEvent extends BaseEvent {
+  type: 'flow.failed'
+  data?: {
+    error?: string
+    stack?: string
+  }
+}
+
+export interface StepStartedEvent extends StepEvent {
+  type: 'step.started'
+  data?: {
+    input?: any
+  }
+}
+
+export interface StepCompletedEvent extends StepEvent {
+  type: 'step.completed'
+  data?: {
+    result?: any
+  }
+}
+
+export interface StepFailedEvent extends StepEvent {
+  type: 'step.failed'
+  data?: {
+    error?: string
+    stack?: string
+  }
+}
+
+export interface StepRetryEvent extends StepEvent {
+  type: 'step.retry'
+  data?: {
+    stepName: string
+    queue: string
+    error?: string
+    stack?: string
+    attempt: number
+    maxAttempts: number
+    nextAttempt: number
+  }
+}
+
+export interface LogEvent extends StepEvent {
+  type: 'log'
+  data: {
+    level: 'debug' | 'info' | 'warn' | 'error'
+    message: string
+    [key: string]: any
+  }
+}
+
+export interface EmitEvent extends StepEvent {
+  type: 'emit'
+  data: {
+    topic: string
+    payload: any
+  }
+}
+
+export interface StateEvent extends StepEvent {
+  type: 'state'
+  data: {
+    operation: 'get' | 'set' | 'delete'
+    scope?: string
+    key: string
+    value?: any
+  }
+}
+
+export type FlowEvent = FlowStartEvent | FlowCompletedEvent | FlowFailedEvent | StepStartedEvent | StepCompletedEvent | StepFailedEvent | StepRetryEvent | LogEvent | EmitEvent | StateEvent
+
+export type EventRecord = FlowEvent

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "nvent",
+  "version": "0.4.0",
+  "description": "Nuxt queue service based on Bullmq",
+  "repository": "DevJoghurt/nuxt-queue",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "yarn dev:prepare && nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:preview": "nuxi preview playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "test": "vitest",
+    "lint": "eslint --ext .ts,.js,.mjs,.cjs,.vue .",
+    "cleanup": "rimraf dist*/ **/node_modules .nuxt* playground/.data",
+    "bumpp": "bumpp"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@iconify-json/devicon": "^1.2.46",
+    "@iconify-json/heroicons": "1.2.3",
+    "@iconify-json/lucide": "^1.2.72",
+    "@nuxt/kit": "4.2.1",
+    "@vue-flow/background": "^1.3.2",
+    "@vue-flow/controls": "^1.1.3",
+    "@vue-flow/core": "^1.47.0",
+    "@vue-flow/minimap": "^1.5.4",
+    "bullmq": "^5.63.0",
+    "chokidar": "^4.0.3",
+    "defu": "^6.1.4",
+    "globby": "15.0.0",
+    "ioredis": "^5.8.2",
+    "json-editor-vue": "^0.18.1",
+    "magicast": "^0.5.1",
+    "mlly": "^1.8.0",
+    "node-ts": "8.0.8",
+    "nuxt": "4.2.1",
+    "pathe": "^2.0.3",
+    "perfect-debounce": "^2.0.0",
+    "pkg-types": "^2.3.0",
+    "semver": "^7.7.3",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.0.1",
+    "@nuxt/eslint-config": "^1.10.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "4.2.1",
+    "@nuxt/test-utils": "^3.20.1",
+    "@nuxt/ui": "4.1.0",
+    "@types/node": "^24.10.0",
+    "bumpp": "10.3.1",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.1",
+    "nuxi": "^3.30.0",
+    "nuxt-mcp": "0.2.6",
+    "rimraf": "^6.1.0",
+    "typescript": "latest",
+    "vitest": "^4.0.7",
+    "vue-tsc": "^3.1.3"
+  },
+  "packageManager": "yarn@4.10.3"
+}