dev.jaide.valkyrie.core — dev.jaide/valkyrie 2025.4.15

action cljs

(action fsm-spec-ref id & [validator-map])

Defines a valid action and validator

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• id - Keyword identifying the unique action for example :fetch
• validator-hash-map - An optional hash-map of action keywords to valhalla compatible validation functions

Returns the fsm-spec-ref atom with an action validator defined

assert-action cljs

(assert-action fsm-spec action)

Validates an action matches a defined action validator

Arguments:

• fsm-spec - An fsm-spec hash-map already derefed
• action - An action hash-map with a :type and arg attrs

Returns action hash-map

assert-alive cljs

(assert-alive fsm)

Helper function to assert fsm is alive (not destroyed)

Arguments:

• fsm - A FiniteStateMachine instance implementing the IStateMachine protocol

Returns nil

assert-effect cljs

(assert-effect fsm-spec effect)

Assert an effect matches a defined effect and passes validation. Mostly intended for internal use or implementing other state adapters.

Arguments:

• fsm-spec - An fsm-spec hash-map already derefed
• effect - A hash-map with :id keyword and arg attrs

Returns the parsed output of the effect validator

assert-fsm-spec cljs

(assert-fsm-spec fsm-spec-ref)

Asserts that the argument is an fsm-spec-ref atom or throws an error

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function

Returns nil

assert-state cljs

(assert-state fsm-spec state)

Assert a state matches a defined state and passes validation. Mostly intended for internal use or implementing other state adapters.

Arguments:

• fsm-spec - An fsm-spec hash-map already derefed
• state - A hash-map with :value keyword and :context hash-map

Returns the parsed output of the state validator

atom-fsm cljs

(atom-fsm spec {:keys [state effect atom] :or {atom atom}})

Create an FSM instance from a spec with an initial state based on an atom.

Notes:

• Every transition must be validated
• Returned FSM can be derefed @fsm as well as (get fsm :value)

Arguments:

• spec - An FSM spec atom created with the fsm/create function
• opts - Required hashmap of named options

Options:

• state - Hash map with :value and optional :context attrs

Returns an instance of FSMAtom

create cljs

(create id & {:keys [atom] :as opts :or {atom atom}})

Create an fsm-spec atom Arguments:

• id - Keyword used to identify the FSM-spec
• opts - Optional options hash-map

Options:

• :atom - A function to instantiate an atom. For example reagent.core/ratom

Returns an atom containing an empty fsm-spec hash-map

destroyed? cljs

(destroyed? fsm)

Helper function to determine if a FSM instance was destroyed

Arguments:

• fsm - A FiniteStateMachine instance implementing the IStateMachine protocol

Returns boolean, true if the state is :dev.jaide.valkyrie.core/destroyed

effect cljs

(effect fsm-spec-ref id handler)

(effect fsm-spec-ref id validator-map handler)

Defines a valid effect and validator

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• id - Keyword identifying the unique effect for example :start-timer
• validator-hash-map - An optional hash-map of effect argument keywords to valhalla compatible validation functions
• handler - Required function to receive a hash map with the following:
  • :fsm - Instance of the fsm
  • :state - Current state that was just transitioned to
  • :action - Action that caused the transition
  • :dispatch - Function to dispatch more actions
  • :effect - The effect hash-map with {:id <id>} and possible args

The handler can optionally return a function to cleanup the side-effect such as removing a DOM listener.

Returns the fsm-spec-ref atom with an effect validator defined

fsm? cljs

(fsm? fsm-spec-ref)

Determines if a possible fsm-spec-atom is likely an fsm-spec

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function

Returns true if the argument is an atom with the :fsm/id property

init cljs

(init fsm-spec-ref state & [effect])

Validate an initial state, context, and effect. Intended for internal use or implementing new state adapters.

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• state - A hash-map with :value state keyword and optional :context attr
• effect - Effect hash-map with :id and arg attrs, needs to match defined effect validator

Returns state hash-map with :value, :context, and :effect keys

initial cljs

(initial fsm-spec-ref state)

Set default initial state of fsm spec. Can be overwritten in atom-fsm function. Must be called after states are defined as state will be validated.

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• state - A state hashmap with :value and :context attrs or value keyword

Returns the fsm-spec-ref atom for chaining

IStateMachine cljs protocol

A protocol for defining state machines against a spec atom. Supports creating adapters for different state systems such as streams, reagent atoms, or other state management libraries.

It is also important to implement cljs.core/IDeref -deref and cljs.core/ILookup -lookup methods to add support for deref syntax and common get and get-in functions.

destroy cljs

(destroy machine)

Remove all subscriptions, clears any stored state, and stops any running effects.

Arguments:

• fsm - Instance of a FSM implementing the IStateMachine protocol

Returns nil

dispatch cljs

(dispatch machine action)

Dispatch actions to invoke defined transitions between states. States returned are validated against the fsm spec this machine was created against.

Arguments:

• fsm - Instance of a FSM implementing the IStateMachine protocol
• action - Hash-map with a :type and other types matching what an fsm spec action

Returns a transition hash-map with :next, :prev, and :action

internal-state cljs

(internal-state machine)

Intended for internal use or debugging.

Arguments:

• fsm - Instance of a FSM implementing the IStateMachine protocol

Returns internal state hash-map including the state, cleanup-effect, and subscriptions

subscribe cljs

(subscribe machine listener)

Add a listener function to receive transition hash-maps

Arguments:

• fsm - Instance of a FSM implementing the IStateMachine protocol
• listener - A function that accepts transition hash-maps

Returns a function to unsubscribe the listener from future transitions

prev-state->next-state cljs

(prev-state->next-state fsm-spec-ref prev-state action)

Perform a defined transition from one state to another with an action. Intended for internal use or implementing state adapters

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• prev-state - A hash-map with :value, :context, and :effect keys
• action - A hash-map with a :type and arg attrs

Returns a transition has-map with :prev state :next state and :action

run-effect! cljs

(run-effect! fsm-spec-ref fsm transition)

Given a transition, cancel previous running effects and perform another effect

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• fsm - An instance of the IStateMachine protocol
• transition - A transition hash-map with :next, :prev, and :action args

Returns a vector with a keyword like the following: [:unchanged function-or-nil] [:updated nil] [:updated function]

spec->diagram cljs

(spec->diagram fsm-spec-ref & {:keys [direction] :or {direction "TD"}})

Transform a FSM spec into a Mermaid flowchart diagram

Arguments:

• fsm-spec-ref - An FSM spec atom created with the fsm/create function
• opts - Required hashmap of named option

Options:

• direction - String should be a mermaid string TD or LR

Returns a mermaid chart string

state cljs

(state fsm-spec-ref id & [context-validator-map])

Defines a valid state and context validator

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• id - Keyword identifying the unique state for example :idle
• context-validator-map - An optional hash-map of context keywords to valhalla compatible validation functions

Returns the fsm-spec-ref atom with a state validator defined

transition cljs

(transition fsm-spec-ref {:keys [from actions to]} f-or-kw)

Define a transition function between states from actions

Arguments:

• fsm-spec-ref - An fsm-spec atom from the create function
• transition-map - A hash-map combining states, actions, and to states
• f-or-kw - A transition function that receives the current state and the action or keyword representing.

Transition Map:

• :from - Vector of state keywords to transition from
• :actions - Vector of keywords representing the :type keyword of actions
• :to - Vector of possible destination states

Returns the fsm-spec-ref atom with a transition function defined