{"id":17981476,"url":"https://github.com/francisrstokes/react-machinery","last_synced_at":"2025-03-25T18:31:16.622Z","repository":{"id":32675449,"uuid":"139281536","full_name":"francisrstokes/React-Machinery","owner":"francisrstokes","description":"🔥 React Machinery provides a simple to use, component based approach to state machines in react.","archived":false,"fork":false,"pushed_at":"2022-12-08T17:18:13.000Z","size":1928,"stargazers_count":108,"open_issues_count":24,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-20T16:47:49.586Z","etag":null,"topics":["javascript","react","state","state-machine"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/francisrstokes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-30T21:31:24.000Z","updated_at":"2024-10-07T21:38:25.000Z","dependencies_parsed_at":"2023-01-14T22:00:39.203Z","dependency_job_id":null,"html_url":"https://github.com/francisrstokes/React-Machinery","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrstokes%2FReact-Machinery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrstokes%2FReact-Machinery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrstokes%2FReact-Machinery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrstokes%2FReact-Machinery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/francisrstokes","download_url":"https://codeload.github.com/francisrstokes/React-Machinery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245519954,"owners_count":20628804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","react","state","state-machine"],"created_at":"2024-10-29T18:10:03.119Z","updated_at":"2025-03-25T18:31:16.268Z","avatar_url":"https://github.com/francisrstokes.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Machinery\n\n[![npm version](https://badge.fury.io/js/react-machinery.svg)]()\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)]()\n[![CircleCI](https://circleci.com/gh/francisrstokes/React-Machinery.png?circle-token=46dc2a2f9571dfc783c03c6550c3119c18c5b8ce\u0026style=shield)]()\n\n\u003cimg src=\"img/logo.svg\" align=\"center\" height=\"200\" width=\"200\" \u003e\n\n\n⚙️ State Machine Modelling for React\n\n- [Description](#description)\n  - [Examples](#examples)\n- [Installation](#installation)\n- [API](#api)\n  - [StateMachine](#statemachine)\n    - [getCurrentState](#getcurrentstate)\n    - [setNewState](#setnewstate)\n    - [states](#states)\n    - [data](#data)\n\n## Description\n\n🔥 `React Machinery` provides a simple to use, component based approach to state machines in react.\n\nDescribe your states, transitions, and which component each renders, and plug it into the `StateMachine` component. It accepts two extra functions; one for getting the current state name and one for setting it. This allows your app to flexibly use and swap out different ways of storing data - be it in component state, redux, mobx, whatever.\n\n### Examples\n\nExamples of how the following state diagram can be implemented in both vanilla react and using redux can be found in the examples folder.\n\n- [Example using react](examples/1.Normal-Component-State.js)\n- [Example using redux](examples/2.With-Redux.js)\n\n![State diagram of code below](StateDiagram.png)\n\n## Installation\n\n```bash\n# with yarn\nyarn add react-machinery\n\n# or with npm\nnpm i react-machinery\n```\n\n## API\n\n### StateMachine\n\nAll props for the `StateMachine` component are required.\n\n#### getCurrentState\n\n##### function()\n\nA function returning the current state name, stored somewhere like a react component state, or in redux.\n\n#### setNewState\n\n##### function(newStateName)\n\nA function that updates the current state, stored somewhere like a react component state, or in redux.\n\n#### states\n\n##### Array of state definitions\n\nA state definition is a plain javascript object with the following properties:\n\n```javascript\n{\n  // This name corresponds to the one coming from getCurrentState() and\n  // being set by setNewState()\n  name: 'State Name',\n\n  // Array of plain objects that describe automatic transitions\n  // These are evaluated after a transition and when props change\n  autoTransitions: [\n    // A transition object must contain two properties:\n    // test, which is a function that recieves the StateMachine data, and returns true if a state change should take place\n    // newState, which is the name of the state to transition to when the test function returns true\n    {\n      test: data =\u003e data === 'expected for state change',\n      newState: 'Name of new state'\n    }\n  ],\n\n  // This is a list of states that can be transitioned to from the current state using the transitionTo\n  // prop passed to a state component. Trying to use transitionTo with a state not specified in this list\n  // will throw an error. This list, together with any 'newState's described in autoTransitions form the\n  // full set of valid transitions for this state.\n  validTransitions: [\n    'Name of valid state'\n  ],\n\n  // beforeRender is an optional function that can run some code before this states component\n  // is rendered. For anything sufficiently complex however, it's better to use a react class\n  // component and take advantage of lifecycle hooks\n  beforeRender: (data) =\u003e {\n    data.startAPIRequest();\n  },\n\n    // One of the following two properties must be implemented:\n\n  // a render prop that recieves the 'props' object supplied to the StateMachine\n  // the props object will also include a 'transitionTo' function and a 'currentState' string\n  render: (data) =\u003e {\n    return \u003cSomeComponent propUsingStateName={data.currentState} {...data} /\u003e\n  },\n\n  // Or just a regular react component\n  component: SomeReactComponent\n}\n```\n\n#### data\n\n##### object\n\nAn object contains data that defines all the states in the state machine. This data is supplied to the component rendered by any state, to `test` functions in autoTransitions. If a render prop is used for the state, then the props are passed as the argument, along with a `transitionTo` function and `currentState` name.\n\n# Logo\n\nThe awesome logo was designed by @ayushs08, who graciously provided under CC BY 3.0. Many thanks!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancisrstokes%2Freact-machinery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrancisrstokes%2Freact-machinery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancisrstokes%2Freact-machinery/lists"}