1.0.5 • Published 2 years ago

tamed-state-machine-frontend v1.0.5

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

WHY?

This is the frontend part of the tamed-state-machine library. For full setup please refer to https://github.com/MehmetKaplan/tamed-state-machine.

This, tamed-state-machine-frontend library, is a set of functions that communicate with a backend that utilize tamed-state-machine-backend library to expose the state machine functionality.

Altogether these libraries give a generic method to handle most state machine related tasks.

The frontend functions are handlers that can be embedded into any client application that connects to the backend. This can be a real frontend app like the ones written with, react, react-native or expo. On the other hand there is no limitation for this library for frontend to be a presentation layer. That's why it can also be a backend node application as well.

One of the important features of this library is that it helps you to call pre and post functions just before and right after state machine transitions. The pre and post functions are your frontend application's functions and their names are defined in the database as described in the state machine configuration manual.

Note: Whenever the database is modified with new state machines, states, transitions, etc, the backend server will be able to read and use the definitions since we do not cache the state machine configurations. The rationale behind this is that we do not want to restart the backend server each time a new state machine is defined.

You can use the following functions defined in the API section to present state machine to your end users.

IMPORTANT: This library does not focus on the authorization. It should be handled separately.

SETUP

  1. Add the request handlers as a dependency of your project.
yarn add tamed-state-machine-frontend
  1. Include the tamed-state-machine-frontend library in your project.
const tamedStateMachineFrontendHandlers = require('https://github.com/MehmetKaplan/tamed-state-machine/blob/master/tamed-state-machine-frontend');
  1. Define the backend url.
const apiBackend = 'http://...'; // modify this with your backend that utilize the tamed-state-machine-backend library
  1. Define your pre transition and post transition functions.
const pre1 = (props) => { return "pre1 is called" }
const pre2 = (props) => { return "pre2 is called" }
//...
const post1 = (props) => { return "post1 is called" }
const post2 = (props) => { return "post2 is called" }
//...
  1. Register your pre and post transition functions and backend API to the library.
tamedStateMachineFrontendHandlers.init({
	apiBackend: apiBackend,
	preFunctions: {
		"pre1": pre1
		"pre2": pre2
	},
	postFunctions: {
		"post1": post1
		"post2": post2
	}
});
  1. Now the state machine frontend is ready to be consumed by your application.

API

Callbacks

For all functions (except the init function), there are 2 callback functions that should be passed as parameters. These functions are successCallback and failCallback. These functions are called when the function is successful or not successful respectively with following parameters:

  • props: the data that is posted to the backend
  • retval: the data that is returned from the backend. The details are as described in the API section of the tamed-state-machine-backend library. You can refer to Returns subsection for each route.

init

This function should be called before any other function. It initializes the library with the backend url and pre and post transition functions.

ParameterTypeDescription
p_paramsObjectThe object that contains the backend url and pre and post transition functions.

p_params should have following format:

KeyTypeDescription
apiBackendStringThe backend url.
preFunctionsObjectThe object that contains the pre transition functions.
postFunctionsObjectThe object that contains the post transition functions.

preFunctions and postFunctions should have following format:

The below Key for "Function Name" is the name of the function that will be called before or after the transition. It is configured in the database as stated in the state machine configuration manual.

KeyTypeDescription
Key for "Function Name"FunctionThe function that will be called before or after the transition.
Returns

If successful, resolves to true If not successful, rejects with an error message.

initiateInstance

Initializes a state machine instance. This instance is association between your application and a configured state machine.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that is configured within the database.
generatedByStringThe user that initiated the state machine.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

getInstance

Gets the instance of the state machine. This instance is association between your application and a configured state machine.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that is being queried.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

getPossibleTransitions

Finds the state machine instance and returns the possible transitions for the current state.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that the current state transitions are being queried.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

transitionInstance

Finds the state machine instance and performs the desired transition.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that the state is requested to be transitioned.
transitionNameStringName of the transition that is being requested.
transitionMadeByStringThe user that requested the transition.
commentStringComment for the transition for instance history.
possibleTransitionsArrayArray of possible transitions for the current state. This should be obtained prior to calling transitionInstance from previous transitionInstance or initiateInstance calls. If this value is provided, the pre and post functions are called.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

getInstanceHistory

Finds the state machine instance and returns the history of the transitions.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that the history is being queried.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

getAllPossibleTransitions

Gives the state machine transition configurations.

ParameterTypeDescription
smNameStringName of the state machine that the transitions are being queried.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

deleteInstance

Deletes the state machine instance.

ParameterTypeDescription
externalNameStringConnection to an application, here the value is a free-text.
externalIdStringConnection to an application, here the value is usually the primary key of the connected document. (For example if you are implementing a document approval process, this is the internal id of the document).
smNameStringName of the state machine that the instance is being deleted.
successCallbackFunctionCallback function that is called when the function is successful as described above in the Callbacks section.
failCallbackFunctionCallback function that is called when the function fails as described above in the Callbacks section.

Example

For a better understanding of how to use this library, please refer to this example.

License

The license is MIT and full text here.

Used Modules

  • tick-log license here
  • tamed-pg license here
  • fetch-lean license here