https://github.com/adrianhdezm/ngx-xstate

XState utilities for Angular
https://github.com/adrianhdezm/ngx-xstate

angular finite-state-machines state-management statecharts xstate

Last synced: about 2 months ago
JSON representation

XState utilities for Angular

• Host: GitHub
• URL: https://github.com/adrianhdezm/ngx-xstate
• Owner: adrianhdezm
• Created: 2023-10-23T17:50:44.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2023-10-25T06:08:35.000Z (about 1 year ago)
• Last Synced: 2024-11-09T23:49:07.836Z (about 2 months ago)
• Topics: angular, finite-state-machines, state-management, statecharts, xstate
• Language: TypeScript
• Homepage:
• Size: 1.94 MB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# ngx-xstate

This package contains utilities for using [XState](https://github.com/statelyai/xstate) with [Angular](https://github.com/angular/angular/).

## Requisites

- `ngx-xstate` requires Angular 15+. All tests were carried out using the standalone components approach. You can use Nx Angular Standalone Project or Angular CLI.

## Installation

To get started with `ngx-xstate`, simply install the library using NPM:

```bash

npm i xstate ngx-xstate

```

## Usage

To use `ngx-xstate` , create a new component inside your angular project. Create a statechart using the `createMachine` API and add it to your component using `inject(XStateService)`. For example:

```ts

import { Component, inject } from '@angular/core';

import { CommonModule } from '@angular/common';

import { HttpClient, HttpClientModule } from '@angular/common/http';

import { NgxXStateModule, XStateService } from 'ngx-xstate';

import { createMachine } from 'xstate';

type Data = Record;

interface DataMachineContext {

  data: Data[];

  error: Error | null;

}

type DataMachineEvent = { type: 'FETCH' } | { type: 'RETRY' } | { type: 'LOADED'; data: Data[] } | { type: 'ERROR'; message: string };

export const dataMachine = createMachine({

  id: 'dataMachine',

  predictableActionArguments: true,

  schema: {

    context: {} as DataMachineContext,

    events: {} as DataMachineEvent,

  },

  initial: 'idle',

  context: {

    data: [],

    error: null,

  },

  states: {

    idle: { on: { FETCH: 'loading' } },

    loading: {

      invoke: {

        src: 'fetchData',

        onError: {

          target: 'failure',

          actions: assign({

            error: (_, event) => new Error(event.data),

          }),

        },

      },

      on: {

        LOADED: {

          target: 'success',

          actions: [

            assign({

              data: (_, event) => event.data,

            }),

          ],

        },

      },

    },

    success: {},

    failure: { on: { RETRY: 'loading' } },

  },

});

@Component({

  standalone: true,

  imports: [CommonModule, HttpClientModule, NgxXStateModule],

  selector: 'example-app',

  template: `

    
Hello XState from Angular!

    Load

    


    

      Loading...

      

        


          {{ item['title'] }}

        

      

      {{ vm.state.context.error?.message }}

    

  `,

})

export class AppComponent {

  http = inject(HttpClient);


  actor = inject(XStateService).useMachine(dataMachine, {

    services: {

      fetchData: () => (send) => {

        this.http.get('https://jsonplaceholder.typicode.com/posts').subscribe((data) => {

          return send({

            type: 'LOADED',

            data,

          });

        });

      },

    },

    devTools: true,

  });

}

```

## Contributing

If you're interested in contributing to `ngx-xstate`, please feel free to submit a pull request or open an issue on GitHub. We welcome all contributions and feedback!

## License

`ngx-xstate` is licensed under the MIT license. See the LICENSE file for more information.