state-machine-graph-lib

Una librería simple y ligera para modelar máquinas de estado dirigidas a través de grafos, con control de permisos en las transiciones. Ideal para gestionar flujos de trabajo, aprobaciones y procesos empresariales.

🚀 Instalación

Instalá la versión estable desde npm:

npm install [email protected]

También podés usar Yarn:

yarn add [email protected]

🧩 Conceptos básicos

El paquete utiliza una estructura de grafo dirigida (StateMachineGraph) que contiene:

• nodes: Estados definidos por id y label.
• edges: Transiciones entre nodos con permisos necesarios.

interface StateMachineGraph {
  nodes: { id: string; label: string; }[];
  edges: { source: string; target: string; permissions: string[] }[];
}

📌 Uso

import { StateMachine, StateMachineGraph } from 'state-machine-graph-lib';

// 1. Definí tu grafo
const graph: StateMachineGraph = {
  nodes: [
    { id: 'pendiente', label: 'Pendiente' },
    { id: 'aprobado', label: 'Aprobado' },
    { id: 'rechazado', label: 'Rechazado' }
  ],
  edges: [
    { source: 'pendiente', target: 'aprobado', permissions: ['can_approve'] },
    { source: 'pendiente', target: 'rechazado', permissions: ['can_reject'] }
  ]
};

// 2. Creá una instancia de StateMachine
const sm = new StateMachine();

// 3. Consultá los estados disponibles
const userPerms = ['can_approve'];
const next = sm.getNextAvailableStates('pendiente', userPerms, graph);
console.log(next); // ["aprobado"]

// 4. Validá una transición específica
const transition = sm.validTransition(userPerms, 'pendiente', 'aprobado', graph);
/*
{
  state: "aprobado",
  nextAvailableStates: []  // futuros estados posibles desde "aprobado"
}
*/
console.log(transition);

📚 API rápida

| Método | Descripción | |--------------------------------------|-----------------------------------------------------------------------------| | getNextAvailableStates(state, permissions, graph): string[] | Retorna una lista de estados destino válidos desde state, según permissions. | | getNextAvailableStatesByStates(permissions, statesArray, graph): string[][] | Devuelve los estados alcanzables para cada estado en statesArray. | | validTransition(permissions, fromState, toState, graph): { state: string, nextAvailableStates: string[] } | Comprueba si un estado es alcanzable, devolviendo el nuevo estado y siguientes posibles estados, o vacío si la transición no es válida. |

✅ ¿Por qué usar esta librería?

• ✅ Fácil de usar: Interfaz simple para definir estados y permisos.
• 🔐 Control basado en roles: Las transiciones sólo se permiten si los permisos coinciden.
• 🧠 Ideal para procesos empresariales: Maneja workflows de aprobación, revisión, etc.
• 📦 Sin dependencias extra: Usa solo @dagrejs/graphlib bajo el capó.

🧪 Ejemplo avanzado

const graph: StateMachineGraph = {
  nodes: [
    { id: 'draft', label: 'Borrador' },
    { id: 'review', label: 'En revisión' },
    { id: 'published', label: 'Publicado' }
  ],
  edges: [
    { source: 'draft', target: 'review', permissions: ['editor'] },
    { source: 'review', target: 'published', permissions: ['publisher'] },
    { source: 'review', target: 'draft', permissions: ['editor'] }
  ]
};

const sm = new StateMachine();
const perms = ['editor'];
console.log(sm.getNextAvailableStates('draft', perms, graph)); // → ["review"]

const perms2 = ['publisher'];
console.log(sm.validTransition(perms2, 'review', 'published', graph));
// → { state: 'published', nextAvailableStates: [] }

📜 Licencia

MIT

Disfrutá usando state-machine-graph-lib para tus flujos de estado. Si querés apoyo o tenés sugerencias, abrí un issue en GitHub.