npm package: @othmane_lamrani_alaoui/queue-as-a-service
Description: TypeScript Queue as a Service SDK with Redis backend
Author: medeclipse/othmane_lamrani_alaoui
Latest version: 1.0.0

# @medeclipse/queue-as-a-service

Un SDK TypeScript simple et puissant pour la gestion de files d'attente avec Redis/Upstash.

## Installation

```bash
npm install @medeclipse/queue-as-a-service
```

## Configuration rapide

```typescript
import { createQueue } from '@medeclipse/queue-as-a-service';

const queue = createQueue({
  redisUrl: process.env.UPSTASH_REDIS_REST_URL!,
  redisToken: process.env.UPSTASH_REDIS_REST_TOKEN!,
  queueName: 'my-queue'
});
```

## Utilisation de base

### 1. Ajouter des jobs

```typescript
// Job simple
const job = await queue.addJob({
  userId: 123,
  action: 'send_email'
});

// Job avec priorité (plus élevé = plus prioritaire)
await queue.addJob(data, { priority: 10 });

// Job différé (5 secondes)
await queue.addJob(data, { delay: 5000 });

// Job avec ID personnalisé
await queue.addJob(data, { jobId: 'custom-id' });
```

### 2. Traitement des jobs

```typescript
// Traitement automatique avec worker
await queue.processJobs(async (job) => {
  console.log('Processing:', job.data);

  // Votre logique métier ici
  if (job.data.action === 'send_email') {
    await sendEmail(job.data.userId);
    return { success: true };
  }

  return { success: false, error: 'Unknown action' };
}, {
  concurrency: 3,        // 3 jobs en parallèle
  pollingInterval: 1000  // Vérifier toutes les secondes
});
```

### 3. Traitement manuel

```typescript
// Récupérer le prochain job
const job = await queue.processNextJob();

if (job) {
  try {
    // Traiter le job
    const result = await processJob(job.data);

    // Marquer comme terminé
    await queue.completeJob(job.id, result);
  } catch (error) {
    // Marquer comme échoué
    await queue.failJob(job.id, error.message);
  }
}
```

### 4. Monitoring

```typescript
// Statistiques de la queue
const stats = await queue.getStats();
console.log(stats); // { waiting: 5, active: 2, completed: 100, failed: 3, delayed: 1 }

// Récupérer les jobs par statut
const failedJobs = await queue.getJobs({
  status: 'failed',
  limit: 10
});

// Relancer un job échoué
await queue.retryJob(jobId);

// Nettoyer les jobs terminés
const deleted = await queue.clearJobs('completed');
```

## Configuration avancée

```typescript
const queue = createQueue({
  redisUrl: 'your-redis-url',
  redisToken: 'your-redis-token',
  queueName: 'my-queue'
}, {
  defaultMaxAttempts: 5,     // Tentatives par défaut
  retryDelay: 5000,          // Délai entre tentatives
  jobTTL: 7 * 24 * 60 * 60 * 1000  // TTL des jobs (7 jours)
});
```

## Variables d'environnement

```bash
UPSTASH_REDIS_REST_URL=your_upstash_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_token
```

## Types disponibles

```typescript
import type {
  QueueJob,
  QueueStats,
  JobStatus,
  AddJobOptions,
  QueueConfig
} from '@medeclipse/queue-as-a-service';
```

## API Reference

### QueueAsAService

- `addJob<T>(data: T, options?: AddJobOptions): Promise<QueueJob<T>>`
- `getJob<T>(jobId: string): Promise<QueueJob<T> | null>`
- `getJobs<T>(options?: GetJobsOptions): Promise<QueueJob<T>[]>`
- `processNextJob<T>(): Promise<QueueJob<T> | null>`
- `completeJob<T>(jobId: string, result?: T): Promise<void>`
- `failJob(jobId: string, error: string): Promise<void>`
- `retryJob(jobId: string): Promise<QueueJob | null>`
- `deleteJob(jobId: string): Promise<boolean>`
- `getStats(): Promise<QueueStats>`
- `clearJobs(status?: JobStatus): Promise<number>`
- `processDelayedJobs(): Promise<number>`
- `processJobs<T>(processor, options?): Promise<void>`

## Exemples complets

Voir le fichier `src/examples.ts` pour des exemples détaillés d'utilisation.

## License

MIT