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:

``bash
npm install state-machine-graph-lib@0.1.0
`

También podés usar Yarn:

`bash
yarn add state-machine-graph-lib@0.1.0
`

---

🧩 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.

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

---

📌 Uso

`ts
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

`ts
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.