@shirox/core v0.1.9-alpha

@shirox/core

@shirox/core is the foundation of Shirox.js, a robust and flexible state machine library with integrated caching. Designed to simplify the management of complex state transitions and context updates, it offers a predictable and scalable solution for your TypeScript and JavaScript projects.

Features

• Powerful State Management: Easily define and manage complex state machines.
• Integrated Caching: Optimize performance with built-in caching mechanisms.
• TypeScript Support: Fully typed for enhanced developer experience and code quality.
• Event-Driven Architecture: Respond to events and trigger state transitions seamlessly. - Extensible Design: Integrate with existing projects or extend functionality as needed.

Installation

Install @shirox/core using your preferred package manager:

npm install @nier/core
# or
pnpm install @nier/core
# or
yarn add @nier/core

Quick Start

Get up and running with @shirox/core in just a few steps:

import { createAutomata, interpret, ShiroxDefinition as Def } from '@shirox/core';

interface MyContext {
  count: number;
}

const automata = createAutomata<MyContext>(
  {
    $id: 'custom-id',
    name: 'machineName',
    initial: 'idle',
    data: { count: 0 }, // the machine context
    states: {
      idle: {
        on: { START: { target: 'working' } },
      },
      working: {
        entry: {
          call: 'start',
        },
        on: { FINISH: { target: 'done' } },
      },
      done: {
        entry: {
          call: 'end',
        },
        type: 'final',
      },
    },
  },
  {
    actions: {
      start: (context) => console.log(`Starting work. Count: ${context.count}`),
      end: (context) => console.log(`Work done. Final count: ${context.count}`),
    },
  }
);

const service = interpret(automata);

// Start the machine
service.start();

// Send events to the machine
service.send({ event: 'START' });
service.send({ event: 'FINISH' });

Advanced Usage

Guarded Transitions

Use guards to conditionally allow state transitions:

const definition = ({
  // ... other properties
  states: {
    working: {
      on: {
        FINISH: {  
          target: 'done',
          cond: (context) => context.count > 5 
        },
      },
    },
  },
});

Actions and Side Effects

Perform actions during transitions or state entry/exit:

const automata = createAutomata<MyContext>({
  // ... other properties
  states: {
    working: {
      entry: {
        call: 'incrementCount' // Call the action 'incrementCount' implenented in 'actions'
      }, 
      exit: {
        call: 'logExit'  // Call the action 'logExit'
      },
      on: {
        PAUSE: {
          target: 'paused',
          actions: {
            call: 'saveToDB'  // Call the action 'saveToDB'
          },
        },
      },
    },
  },
},
{
  actions: {
    incrementCount: (context: MyContext) => context.count++,
    logExit: (context: MyContext) => console.log(`Exiting working state. Count: ${context.count}`),
    saveToDB: (context: MyContext) => { /* lógica para guardar en DB */ },
    start: (context: MyContext) => console.log(`Starting work. Count: ${context.count}`),
    end: (context: MyContext) => console.log(`Work done. Final count: ${context.count}`)
  }
}
);