nuxt-bee-queue 1.0.0 → 1.0.1

package/README.md

@@ -1,84 +1,185 @@
-<!--
-Get your module up and running quickly.
+# Nuxt BeeQueue 🐝
 
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: My Module
-- Package name: my-module
-- Description: My new Nuxt module
--->
+A powerful Nuxt module for handling background jobs using Redis and Bee-Queue. This module integrates seamlessly with Nuxt server routes and Nitro, allowing you to define, dispatch, and process jobs with ease.
 
-# My Module
+## Features
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
+- **Easy Job Definition**: Define jobs in server/jobs using a simple API.
+- **Type Safety**: Full TypeScript support for job payloads and returns.
+- **Flexible Execution**: Run workers inside the Nuxt process (dev) or as separate microservices.
+- **Zero Configuration**: Auto-imports and sensible defaults.
 
-My new Nuxt module for doing amazing things.
+## Installation
 
-- [✨ &nbsp;Release Notes](/CHANGELOG.md)
-<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
-<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+```bash
+npm install nuxt-bee-queue
+# or
+yarn add nuxt-bee-queue
+# or
+pnpm add nuxt-bee-queue
+```
 
-## Features
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt-bee-queue'],
+  // Optional configuration
+  queue: {
+    redis: 'redis://localhost:6379',
+    infernalQueue: true, // in false in dev mode queue not run automatically (must run node --watch path)
+  }
+})
+```
+
+## Usage
+
+### 1. Defining a Job
+
+Create a job file in your server directory. By convention, stick to `server/jobs/`. Example path: `server/jobs/user-create.ts`
+
+> **Note**: The name of the file becomes the name of the queue.
+
+You can use standard async/await or the callback style (done).
+
+```typescript
+// server/jobs/user-create.ts
+import { db, schema } from 'hub:db' // Example using Nuxt Hub
+
+interface JobPayload {
+  firstName: string
+  lastName: string
+}
+
+// Inferred return type for Type Safety
+type JobReturn = Array<typeof schema.users.$inferSelect>
+
+export default defineJob<JobPayload, JobReturn>({
+  // Option 1: Async/Await (Recommended)
+  process: async (job) => {
+    console.log(`Processing user: ${job.data.firstName}`)
+    
+    const user = await db.insert(schema.users).values({
+      firstName: job.data.firstName,
+      lastName: job.data.lastName,
+    }).returning()
+    
+    console.log('User Created!')
+    return user
+  },
+
+  // Option 2: Callback style
+  // process: (job, done) => {
+  //   // do work...
+  //   done(null, result)
+  // },
+
+  setting: {
+    sendEvents: false,
+    removeOnSuccess: true,
+  },
+})
+```
+
+### 2. Dispatching a Job
+
+You can dispatch jobs from your API routes or other server files using `useQueue`.
+
+```typescript
+// server/api/register.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
 
-<!-- Highlight some of the features your module provide here -->
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+  // The name 'user-create' matches the filename in server/jobs/
+  const queue = useQueue('user-create')
 
-## Quick Setup
+  const job = await queue.createJob({
+    firstName: body.firstName,
+    lastName: body.lastName
+  }).save()
 
-Install the module to your Nuxt application with one command:
+  return { jobId: job.id, status: 'queued' }
+})
+```
+
+## Running Workers
+
+### Development
+
+You have two options during development:
+
+1. **Integrated (Default)**: Do nothing. The queue workers will launch in the same process as your Nuxt/Nitro server.
+
+2. **Separate Process**: If you want to isolate the worker logs or performance, you can run the worker separately.
+
+Add the following to your `package.json` scripts:
+
+**Node:**
+```json
+"scripts": {
+  "queue:dev": "node --watch .nuxt/dev/workers/index.mjs"
+}
+```
+
+**Bun:**
+```json
+"scripts": {
+  "queue:dev": "bun --watch .nuxt/dev/workers/index.mjs"
+}
+```
+
+**Deno:**
+```json
+"scripts": {
+  "queue:dev": "deno run --allow-all --watch .nuxt/dev/workers/index.mjs"
+}
+```
+
+### Production
+
+For production deployment, the workers are built into a separate entry point.
 
 ```bash
-npx nuxi module add my-module
+node .output/server/workers/index.mjs
 ```
 
-That's it! You can now use My Module in your Nuxt app ✨
-
-
-## Contribution
-
-<details>
-  <summary>Local development</summary>
-  
-  ```bash
-  # Install dependencies
-  npm install
-  
-  # Generate type stubs
-  npm run dev:prepare
-  
-  # Develop with the playground
-  npm run dev
-  
-  # Build the playground
-  npm run dev:build
-  
-  # Run ESLint
-  npm run lint
-  
-  # Run Vitest
-  npm run test
-  npm run test:watch
-  
-  # Release new version
-  npm run release
-  ```
-
-</details>
-
-
-<!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-version-href]: https://npmjs.com/package/my-module
-
-[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-downloads-href]: https://npm.chart.dev/my-module
-
-[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[license-href]: https://npmjs.com/package/my-module
-
-[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
-[nuxt-href]: https://nuxt.com
+## Tips & Best Practices
+
+### 1. Queue Instance Management
+
+Every time you call `defineJob` or `useQueue('name')`, a BeeQueue client instance is created. **Rule**: Ensure you strictly use the filename (without extension) as the queue name when dispatching.
+
+### 2. Optimization (Singleton Pattern)
+
+For optimization purposes, every BeeQueue client is stored in memory as long as the server is running. Creating a new queue instance on every request is an anti-pattern.
+
+We highly recommend creating a wrapper for your queues to reuse the client instance.
+
+```typescript
+// server/utils/queue.ts
+export function useEmailQueue() {
+  // This reuses the existing client if strictly created before
+  return useQueue('email-sender', {
+    sendEvents: false
+    // ...other specific config
+  })
+}
+```
+
+Usage in API:
+
+```typescript
+// server/api/send.ts
+export default defineEventHandler(async () => {
+  // Uses the cached connection
+  await useEmailQueue().createJob({ email: '...' }).save()
+})
+```
+
+## Credits
+
+A special thanks to Aidan Hibbard and the [nuxt-processor](https://github.com/) repository. Parts of this module's architecture and logic were inspired by his work on queue processing in the Nuxt ecosystem.
+
+## License
+
+MIT

package/dist/module.d.mts

@@ -2,6 +2,7 @@ import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
     redis?: string;
+    infernalQueue?: boolean;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-bee-queue",
-  "configKey": "nuxtBeeQueue",
-  "version": "1.0.0",
+  "configKey": "queue",
+  "version": "1.0.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { useNuxt, createResolver, defineNuxtModule, addServerTemplate, addTemplate, addServerImports } from '@nuxt/kit';
+import { useNuxt, createResolver, defineNuxtModule, addServerTemplate, addTemplate, addServerImports, addServerPlugin } from '@nuxt/kit';
 import { parse, relative } from 'node:path';
 import fs from 'node:fs';
 import fg from 'fast-glob';
@@ -20,11 +20,12 @@ const scanFolder = async (path) => {
 const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-bee-queue",
-    configKey: "nuxtBeeQueue"
+    configKey: "queue"
   },
   // Default configuration options of the Nuxt module
   defaults: {
-    redis: "redis://localhost:6379"
+    redis: "redis://localhost:6379",
+    infernalQueue: true
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -123,6 +124,9 @@ const module$1 = defineNuxtModule({
       name: "useQueue",
       from: resolver.resolve("./runtime/server/utils/useQueue")
     }]);
+    if (options.infernalQueue && process.env.NODE_ENV == "development") {
+      addServerPlugin(resolver.resolve("./plugins/workerRunner"));
+    }
     function createWorkersRollupPlugin() {
       const VIRTUAL_ID = "\0nuxt-bee-queue-entry";
       let virtualCode = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-bee-queue",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Nuxt 3/4/5 adapter for bee-queue ",
   "repository": "https://github.com/nexthis/nuxt-bee-queue",
   "author": {