plugin-development.md

⬅ Back to 🍕

Plugin Development

👨🏽‍💻 Plugin Developer Template

Dev Helpers

There are helper functions located available via 🍕 that you should utilize throughout plugin development.

import { util } from "state-machine-snacks";

const {
    configEditor,
    extractMetadata,
} = util;

Helper	Description	Function
Config Editor	Useful during the config hook.	configEditor
Extract Metadata From State Chart	Generates a map of states that have matadata.	extractMetadata

Config Editor

Append things like events, context, and states to a users config without affecting any original values.

Note: These helpers can only be used in the config hook during the plugin lifecycle.

import { assign } from "xstate";
import { util } from "state-machine-snacks";

const {
    configEditor,
} = util;

export default () => {
    config : (config) => {
        let result = { ...config };
        
        // Add context, a place where we can store values that the user can also read.
        result = configEditor.addContext(result, { someContext : "some value" })
    

        // Add an update event used to update context.
        result = configEditor.addEventListener(result, { plugin:myPluginName:UPDATE_STATE : {
            actions : assign({
                someContext : (ctx, event) => event.data,
            })
        }})

        // Add a new state.
        result = configEditor.addState(result, {
            coolState : {
                entry : () => console.log("cool state bro)
            },
        })
        
        return result;
    },
})

Adding Events

configEditor.addEventListener(config, event) You can add events to the users config during the config hook with the addEventListener function.

When adding event listeners, it is recommended that you prefix events with a pattern similar to the following example.

Example: { plugin:yourPluginName:WHATEVER_YOU_WANT : ".stateTwo" }

Args	Description
config	XState state machine config.	Required
event	XState event object.	Required

Adding Context

configEditor.addContext(config, context) You can add context to the users config during the config hook with the addContext function.

Example: { myPluginsContext : "some values for my plugin or the user" }

Args	Description
config	XState state machine config.	Required
context	Object to be appended to machine context.	Required

Adding States

configEditor.addState(config, context) You can add states to the users config during the config hook with the addState function.

Example: { myPluginsState : { entry : () => console.log("made it")}}

Args	Description
config	XState state machine config.	Required
state	Object to be appended to machine states.	Required

Extract Metadata

Extract metadata from a service. Often times plugins require user input provided via metadata in the state chart config. This function accepts a service, plus a list of metadata keys you wish to extract.

This would build a map of all state machine states that have metatadata property "component".

const componentsMap = extractMetadataFromState(service, [ "component" ]);

// Output:
// Map([
//      [
//          "exampleState.anotherState",
//          metadataValue
//     ],
//      [
//          "someStateWithMeta",
//          otherMetadataValue
//     ]
// ])