{"id":13724953,"url":"https://github.com/ycombinator/state-machine","last_synced_at":"2026-01-16T17:01:33.464Z","repository":{"id":66660387,"uuid":"9681421","full_name":"ycombinator/state-machine","owner":"ycombinator","description":"State machine as a service","archived":false,"fork":false,"pushed_at":"2014-03-05T03:09:48.000Z","size":260,"stargazers_count":22,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T19:43:48.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ycombinator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-25T21:09:43.000Z","updated_at":"2022-09-02T17:49:47.000Z","dependencies_parsed_at":"2023-02-20T09:00:52.083Z","dependency_job_id":null,"html_url":"https://github.com/ycombinator/state-machine","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ycombinator/state-machine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycombinator%2Fstate-machine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycombinator%2Fstate-machine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycombinator%2Fstate-machine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycombinator%2Fstate-machine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ycombinator","download_url":"https://codeload.github.com/ycombinator/state-machine/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycombinator%2Fstate-machine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28480081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-08-03T01:02:07.789Z","updated_at":"2026-01-16T17:01:33.443Z","avatar_url":"https://github.com/ycombinator.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# State machine as a service\n\nApplications sometimes find themselves managing process flows. These process flows consist of states and inputs that move the process along from one state to another.\n\nFor instance, consider a user registration process. When the application creates a new user, that user may start off in a *UNVERIFIED* state. When the application verifies the user's email address, the user may move to a *VERIFIED* state. On the other hand, if sufficient time passes and the user is still in the *UNVERIFIED* state, the application may choose to move the user to a *EXPIRED* state.\n\nApplications with such needs often end up implementing a state machine to manage the process flow. This service aims to save applications from that implementation effort.\n\nUsing this service such applications need only define the state machine that reflects the process flow and then tell the service each time a input is made to the process. The service will take care of properly transitioning to the next state in the flow and return that state to the application. The application may also, at any time, ask the service for the current state of a state machine it created. Furthermore, applications may store arbitrary data along with each state.\n\n# Usage\nThe service is currently provided as a REST API. \n\n## REST API\n\n### Base URIs\nURIs in the rest of this document start with `{baseuri}`. This is a placeholder that should be replaced with one of the URIs below, depending on the environment:\n\n| Environment           | `{baseuri}`                                  |\n| --------------------- | -------------------------------------------- |\n| Production            | `http://state-machine.herokuapp.com`         |\n| Staging (coming soon) | `http://state-machine-staging.herokuapp.com` |\n| Development           | `http://localhost:8080`                      |\n\n### Resources\n\n#### State Machines\n\n##### Create a new state machine\n\n###### Request\n\n```\nPOST {baseuri}/v1/state-machines\n```\n```json\n{\n  \"initialState\": \"foo\",\n  \"states\": {\n    \"foo\": {\n      \"transitions\": [\n        { \"match\": \"1|2|[a-bA-B]\",\"nextState\": \"bar\" },\n        { \"match\": \"3\",\"nextState\": \"baz\" }\n      ]\n    },\n    \"bar\": {\n      \"data\": \"data for state bar\",\n      \"transitions\": []\n    },\n    \"baz\": {\n      \"data\": \"data for state baz\"\n    }\n  }\n}\n```\n\n###### Response (upon successful creation)\n\n```\n201 Created\nLocation: {baseuri}/v1/state-machine/2345\n```\n```json\n{\n  \"meta\": {\n    \"links\": {\n      \"self\": \"{baseuri}/v1/state-machine/2345\"\n    }\n  }\n}\n```\n\n#### State machine current state\n\n##### Retrieve the current state the state machine is in\n\n###### Request\n\n```\nGET {baseuri}/v1/state-machine/2345/current-state\n```\n\n###### Response\n\n```\n303 See Other\nLocation: {baseuri}/v1/state-machine/2345/state/1\n```\n\n###### ... after redirection ...\n\n```\n200 OK\n```\n```json\n{\n  \"meta\": {\n    \"links\": {\n      \"self\": \"{baseuri}/v1/state-machine/2345/state/1\",\n      \"state-machine\": \"{baseuri}/v1/state-machine/2345\"\n    }\n  },\n  \"state\": {\n    \"name\": \"foo\"\n  }\n}\n```\n\n#### State machine input\n\n##### Provide input to the state machine\n\n###### Request\n\n```\nPOST {baseuri}/v1/state-machine/2345/input\n```\n```json\n{\n  \"input\": \"2\"\n}\n```\n\n###### Response (upon successful transition)\n\n```\n303 See Other\nLocation: {baseuri}/v1/state-machine/2345/state/3\n```\n\n###### ... after redirection ...\n\n```\n200 OK\n```\n```json\n{\n  \"links\": {\n    \"self\": \"{baseuri}/v1/state-machine/2345/state/3\",\n    \"state-machine\": \"{baseuri}/v1/state-machine/2345\"\n  },\n  \"state\": {\n    \"name\": \"baz\",\n    \"data\": \"data for state baz\"\n  }\n}\n```\n\n# Development Setup (on Mac OS X 10.8)\n\n### First-time setup\n\n1) Download and install [Node.js](http://nodejs.org/).\n\n2) Download, install and start [PostgreSQL server](http://postgresapp.com/).\n\n3) Clone this repository to a folder on your computer. The rest of this document will refer to this folder as `$PROJECT_ROOT`.\n\n4) Install project dependencies.\n\n    cd $PROJECT_ROOT\n    npm install\n\n5) Create the database user. When prompted, enter the password as defined in the [`config/default.js`](https://github.com/ycombinator/state-machine/blob/master/config/default.js) file.\n\n    createuser statemachine -P\n\n6) Create the database and make the just-created user its owner.\n\n    createdb statemachine -O statemachine\n\n7) Create the database schema.\n\n    node bin/update_db_schema.js\n\n### Every time you sync $PROJECT_ROOT with the remote GitHub repo\n\n1) Update the project dependencies.\n\n    cd $PROJECT_ROOT\n    npm install\n\n2) Update the database schema.\n\n    node bin/update_db_schema.js\n\n### To start the REST API server\n\n1) Start the REST API server.\n\n    cd $PROJECT_ROOT\n    node restapi/server.js\n\n# Coming Soon\n* Ability to specify input matchers in forms other than regular expressions.\n* Language bindings in Node.js, Python and Ruby.\n* TCP socket protocol as alternative to REST.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fycombinator%2Fstate-machine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fycombinator%2Fstate-machine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fycombinator%2Fstate-machine/lists"}