Exciting news!Announcing our $4.6M Series Seed. Learn more
Log in


Package Overview
File Explorer

Advanced tools


A mongoose plugin fomr Javascript State Machine


Version published
Yearly downloads
increased by95.41%

Weekly downloads



0.1.1 (2019-06-24)

<a name="0.1.0"></a>




Generated with nod NPM version Build Status Coverage Status

A mongoose plugin fomr Javascript State Machine

The plugin base the module on Javascript State Machine which had done really well on creating a State-like environment for Javascript.

This Plugin will merge Mongoose to Javascript State Machine! The goal is to make the API simple and allow a mongoose model to have the State machine API provided by Javascript State Machine.

This plugin simply intercetp the Model Initilizer to include Javascript State Machine instance to the model.


$ npm install --save @rentspree/mongoose-state-machine


First lets initialize our mongoose model

import stateMachinePlugin from "@rentspree/mongoose-state-machine" import mongoose from "mongoose" // first create your model const personSchema = new mongoose.Schema({ firstName: String, lastName: String, status: String // check this field out })

Then, we can define the State Machine definition. This is the exact same object which should be passed upon creating a StateMachine object here.

const stateMachine = { init: 'solid', transitions: [ { name: 'melt', from: 'solid', to: 'liquid' }, { name: 'freeze', from: 'liquid', to: 'solid' }, { name: 'vaporize', from: 'liquid', to: 'gas' }, { name: 'condense', from: 'gas', to: 'liquid' } ], methods: { onMelt: function() { console.log('I melted') }, onFreeze: function() { console.log('I froze') }, onVaporize: function() { console.log('I vaporized') }, onCondense: function() { console.log('I condensed') } } }

For more detail on this definitions, you can visit Javascript State Machine document. Every config in this part is passed to it.

Now, lets apply the plugin to our model

personSchema.plugin(stateMachinePlugin, { stateMachine: stateMachine } )

There are some options available, but we'll come back later.

const Person = mongoose.model("Person", personSchema)

Done!! The Person Model now become a StateMachine model. The field status declared earlier is the field responsible for the initial state of the State Machine. This is slightly different from the normal behaviour of the Javascript State Machine.

Usage Example

According to the example above, the first thing needs to clearify is that, the value in status field of this Person model would only have 3 states which are what declared in the State Machine; solid, liquid, and gas.


Let's do the query, assuming a Person in the database:

Person.create({ _id: "first-person-ever", firstName: "John", lastName: "Doe", status: "liquid" })

Now, on somewhere in the code, we can do this

const person = await Person.findOne({_id: "first-person-ever"}) console.log(person.status) // this will long "liquid" console.log(person.state) // this is the Javascript State Machine api and it will log "liquid" person.vaporize() // this will log "I vaporized" console.log(person.state) // "gas" console.log(person.status) // "liquid" --IMPORTANT, explain below await person.save() console.log(person.status) // "gas"

The Javascript State Machine API is available for the person model here and it will behave like Applying State Machine Behavior to Existing Objects.

Important Note The important thing to notice here is that, this plugin will not manipulate the data at the database level. The goal is to make Mongoose model work together with Javascript State Machine. From the example above, the code must run person.save() in order to update the latest status to the database. The purpose for this is to delegate database saving decision to the developer.

When the person.save() happen, it will move the value in the state of the Javascript State Machine into the field status which relate to value in the database.

New Model

Things get a little different while creating new model. According to Mongoose, it is not recommended to use middleware instead of overriding the model method.

Normally, when creating new model in Mongoose

const person = new Person({firstName: "hero"}) // this still work person.melt() // error

Instead, use the method provided by the plugin

const person = Person.new({firstName: "hero"}) person.melt() console.log(person.state) // liquid


These are the option available when defining plugin

personSchema.plugin(stateMachinePlugin, options )
stateMachineThe state machine definition object which will be passed to new StateMachine() of Javascript State Machinenull
statusFieldNameThe state field name in the database. This is the initial state for the state machine when getting Mongoose model from the database, also it's the field that the current state will be update upon save()"status"


Table of Contents


MIT © Putt




Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc