npm package: @shirox/core
Description: Core library for Shirox.js
Author: Draiken
Latest version: 0.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:

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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}`)
  }
}
);
```