@mostajs/queue

Gestion de file d'attente : tickets numérotés, types de service, guichets, appels, écran d'affichage et événements temps réel. DB-agnostique.

Auteur : Dr Hamid MADANI [email protected] Licence : AGPL-3.0-or-later

Rôle

Couche domaine « file d'attente » pour agences, banques, administrations, cliniques. Le module fournit :

• les schémas d'entités (Ticket, Counter, ServiceType) ;
• les fonctions pures : numérotation, transitions d'état, sélection du prochain appelé, métriques d'attente ;
• les repositories et handlers serveur (persistance injectée) ;
• les hooks React client-safe ;
• le contrat d'événements temps réel, les permissions, le menu ;
• les traductions FR / AR.

Le module n'embarque aucune base de données : la persistance se branche par injection (QueueDataPort), typiquement via @mostajs/data-plug.

À ne pas confondre avec @mostajs/ticketing (billetterie / contrôle d'accès par scan QR + reconnaissance faciale) — domaine distinct.

Installation

npm i @mostajs/queue

Exemple — serveur

import { TicketRepository, CounterRepository } from '@mostajs/queue/server';
import type { QueueDataPort, QueueEventBus } from '@mostajs/queue/server';

// `data` : implémentation de QueueDataPort (via @mostajs/data-plug)
// `bus`  : implémentation de QueueEventBus (Socket.io / @mostajs/net)
const tickets = new TicketRepository(data, { numbering: 'continuous' }, bus);
const counters = new CounterRepository(data, bus);

const ticket = await tickets.create({ serviceType: 'depot' });   // "depot1"
const called = await tickets.callNext(3, 'depot');                // guichet 3
await tickets.complete(called!.ticketId);

Exemple — handlers (Express via adaptateur)

import { createTicketsHandler } from '@mostajs/queue/server';

const handler = createTicketsHandler(tickets);
// handler.GET(req) / handler.POST(req)  →  { status, body }

Exemple — client React

import { useQueue, useCounter } from '@mostajs/queue/hooks';

const { services, waiting, takeTicket } = useQueue({ baseUrl });
const { current, callNext, complete } = useCounter({ baseUrl, counterId: 3 });

Fonctions pures

import {
  formatTicketId, computeNextNumber,   // numérotation
  nextTicketState, canCall,            // règles
  pickNextTicket,                      // sélection
  waitTime, estimatedWait,             // métriques
} from '@mostajs/queue';

Sous-chemins

| Import | Contenu | |---|---| | @mostajs/queue | Types, schémas, fonctions pures, événements, permissions, menu | | @mostajs/queue/server | QueueDataPort, repositories, handlers | | @mostajs/queue/hooks | useQueue, useCounter | | @mostajs/queue/register | register(registry) | | @mostajs/queue/i18n/fr/queue.json · /i18n/ar/queue.json | Traductions |

États

• Ticket : waiting → serving ⇄ serving_paused → completed ; cancelled depuis tout état non terminal.
• Guichet : available / busy / paused / closed.

Développement

npm install
npm run build      # tsc → dist/
npm test           # tsc + node --test

Conformité

Schémas alignés sur les collections MongoDB de TicketFlow V0.1 (MonTour, CounterStatus) — migration non destructive.