Pathfinder

This library was generated with Angular CLI version 7.2.0.

Summary

Softheon Pathfinder is a deterministic finite automaton (DFA) based service that allows for highly configurable state logic to be provided and ran. The functionality will be described in regards to navigation, but the pathfinder service can be used on its own outside of the navigation scope.

Installation

npm install @softheon/pathfinder

Usage

The following sections will provide information code snippets on how to use and configure Pathfinder

Setup

First, the module must be imported into one of the existing modules in the project

import { PathfinderModule } from '@softheon/pathfinder';

NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    PathfinderModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})

This will initialize the PathfinderService and allow usage of any of the included components.

Configuration

This section will explain the configuration structure, and how to configure Pathfinder.

Terms

Path -- The main class for Pathfinder, the steps are all available states for the service

Step -- One step in the path, contains the information of the step and the conditions of where the step can lead to

Condition -- Logic for evaluating how to determine the next Step in the Path

Classes

Path

| Property | Description | Type | | --------- | ------------------------------------------ | ------------------------- | | snapshot$ | The observable of the snapshot of the path | Observable<Array<Step>> | | steps | The steps of the path | Array<Step> |

| Method Name | Description | Arguments | Return Type | | -------------- | ------------------------------------------------------------- | -------------------- | ----------- | | updateSnapshot | Updates the snapshot with the current steps or provided steps | steps: Array<Step> | void |

Step

| Property | Description | Type | | ---------- | --------------------------------------------------------- | ---------------------------------------------------- | | id | The step id | string | number | | label | The text to display for the step | string | | isMainStep | True if the step is a main step (navigation purposes) | boolean | | group | The group the step is a part of (navigation purposes) | string | number | | isStart | True if the step is a start step | boolean | | isEnd | True if the step is an end step | boolean | | isCurrent | True if the step is the current step | boolean | | isComplete | True if the step has been completed | boolean | | conditions | The array of conditions for determining what step is next | Array<Condition> | | action | The action used to get to the step | any | | actionType | The action type used to get to the step | 'route' | 'internalPath' | 'externalUrl' | 'dummy' |

Condition

| Property | Description | Type | | ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | | stepId | The id of the step the condition leads to | string | number | | predicateType | Determines the type of logic being given for resolving the condition | 'boolean' | 'object' | 'function' | 'previousSteps' | | predicate | The logic to be run to resolve the condition | unknown | | action | The action to take when a condition is resolved to true | any | | actionType | How to run the provided action | 'route' | 'internalPath' | 'externalUrl' | 'dummy' | | logicalOperators | Determines if all or some of the predicate conditions need to be met | 'and' | 'or' |

ArrayCondition

| Property | Description | Type | | ---------------- | -------------------------------------------------------------------- | ------------------------ | | logicalOperators | Determines if all or some of the predicate conditions need to be met | 'and' | 'or' | | predicate | The key values pairs to use for array matching | {[ key: string ]: any} |

Structure

The path class must be provided to the PathfinderService, currently, this done through the initialize function in the PathfinderService. it takes an argument of type Array<Step> which denotes all possible steps of the path. Each step contains an Array<Condition> which determines which step would be the next step in the Path. And example Step in JSON format is provided below.

{
    "id": "begin",
    "label": "Ascend",
    "isMainStep": true,
    "group": "group1",
    "isStart": true,
    "action": "/start",
    "actionType": "route",
    "conditions": [
      ...
    ]
}

Every Step available to the Path is provided in the Steps property of the Path. The conditions denote where the step can lead and how to get there. Below is the same Step json except the conditions array has been populated.

"steps": [
    {
        "id": "begin",
        "label": "Ascend",
        "isMainStep": true,
        "group": "group1",
        "isStart": true,
        "action": "/start",
        "actionType": "route",
        "conditions": [
            {
                "stepId": "minor-passive-1",
                "predicateType": "boolean",
                "predicate": true,
                "actionType": "route",
                "action": "./minor-passive-1"
            }
        ]
    },
    {
        "id": "minor-passive-1",
        "group": "group2",
        "label": "Minor Passive 1",
        "conditions": [
            ...
        ]
    }
]

The way the above example is read is the 'begin' step has a condition that leads to the 'minor-passive-1' step. The 'minor-passive-1' step has been provided in the 'steps' which signifies all possible steps of the Path. It should be noted that a step can have multiple conditions and that conditions are evaluated in the order provided. The first condition that is evaluated to be true, will be the one used and conditions following that will not be run.

Condition Predicates

The predicate and predicateType properties of the condition are what Pathfinder uses to determine the next step. The available predicate types are:

• boolean
• object
• function

Boolean

The boolean predicate type is a simple true or false conditional. The example condition shown below has boolean predicate type:

{
    "stepId": "minor-passive-1",
    "predicateType": "boolean",
    "predicate": true,
    "actionType": "route",
    "action": "./minor-passive-1"
}

The above condition will always resolve to true, which means this predicate type should be used when a step only has one possible next step (linear) or as a fall back for if none of the previous conditions resolve to true (default).

Object

The object predicate type is a bit more complex. The PathfinderService has a data property. This property plays a key role in the object predicate type. The data property can be any object or any value and the predicate provides paths to values of the data property and values to compare them to. An example condition is shown below with a JSON snippet of the data for this path.

"condition": {
    "stepId": "natures-reprisal",
    "predicateType": "object",
    "logicalOperator": "or",
    "predicate": {
        "ability.damageTypes": {
            "logicalOperator": "and",
            "predicate": {
                "element": "poison",
                "type": "dot",
                "amount": ">0"
            }
        }
    }
}

"data": {
    "ability" : {
        "damageTypes": [
            {
                "element": "poison",
                "type": "dot",
                "amount": "9000"
            }
        ]
    }
}

The above example is a condition regarding what is required to move to the natures-reprisal step. The selector in the condition follows the syntax used for accessing a JSON object. So first it will get the ability, then the damageTypes property. Since this property is an array, the predicate uses the ArrayCondition class. A logical operator is provided, in this case, and meaning all provided values must resolve to true when compared to the values in the data. An or logical operator means at least one of the provided values must resolve to true.

Translating to English, the data.ability.damageTypes list must contain an entry where the element property equals "poison" and the type property equals "dot" and the amount property is greater than 0. By fulfilling the requirements the condition will be resolved to true and the determined step will be the natures-reprisal step.

In order to get the data into the PathfinderService follow the code snippet bellow.

export class AppComponent {
    constructor(
        private pathfinder: PathfinderService
    ) {
        this.pathfinder.path = // provide your path here
        this.pathfinder.data = // provide your data here
        this.pathfinder.initialize();
    }
    ...

Numbers -- when dealing with numbers, Pathfinder supports the following character preceding the number value

< -- Less than value

> -- Greater than value

<= -- Less than or equal to value

>= -- Greater than or equal to

! -- Not equal (also works for strings)

Function

The function predicateType allows for writing typescript arrow function directly in the predicate property. This predicateType also works off the data property of the PathfinderService. This type allows for the most customization but is also the hardest to use as it requires knowledge of the typescript/javascript language. An example condition is provided below. The function mirrors the logic defined in the example above but shows an alternate way of writing it. The same data is used for this example

"condition": {
    "stepId": "natures-reprisal",
    "predicateType": "function",
    "predicate": "(context) => { return context.ability.damageTypes.findIndex(x => {x.element === 'poison' && x.type === 'dot' && x.amount > 0 }) > -1; }"
}

This condition has the same logic as the object predicateType example provided above except it uses the function predicateType note the use of the findIndex function of an array. This notation allows for extremely complex logic but requires knowledge of the language in order to utilize it. This predicate type is meant to fill in the gaps that the object predicate type can't fulfill and should be used only when needed.

Full Example

A complete navigation example is provided below with the example data, all from in JSON format so it can be loaded from a file or an API call.

"data": {
    "ability" : {
        "damageTypes": [
            {
                "element": "poison",
                "type": "dot",
                "amount": "9000"
            }
        ]
    }
}

"path": {
    "steps": [
        {
            "id": "start",
            "label": "Ascend",
            "group": "group1",
            "isStart": true,
            "action": "./start",
            "actionType": "route",
            "conditions": [
                {
                    "stepId": "minor-passive-1",
                    "predicateType": "object",
                    "logicalOperator": "or",
                    "action": "/minor-passive-1",
                    "actionType": "route",
                    "predicate": {
                        "ability.damageTypes": {
                            "logicalOperator": "and",
                            "predicate": {
                                "element": "poison",
                                "type": "dot",
                                "amount": ">0"
                            }
                        }
                    }
                },
                {
                    "stepId": "minor-passive-3",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./minor-passive-3",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "minor-passive-1",
            "label": "Flask Effect, Chaos Damage",
            "group": "group2",
            "conditions": [
                {
                    "stepId": "natures-reprisal",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./natures-reprisal",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "natures-reprisal",
            "label": "Nature's Reprisal",
            "group": "group2",
            "conditions": [
                {
                    "stepId": "minor-passive-2",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./minor-passive-2",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "minor-passive-2",
            "label": "Flask Effect, Chaos Damage",
            "group": "group2",
            "conditions": [
                {
                    "stepId": "master-toxicist",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./master-toxist",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "master-toxicist",
            "label": "Master Toxicist",
            "group": "group2",
            "isEnd": true
        },
        {
            "id": "minor-passive-3",
            "label": "Flask Effect and Charges Gained",
            "group": "group3",
            "conditions": [
                {
                    "stepId": "natures-boon",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./natures-boon",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "natures-boon",
            "label": "Nature's Boon",
            "group": "group3",
            "conditions": [
                {
                    "stepId": "minor-passive-4",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./minor-passive-4",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "minor-passive-4",
            "label": "Flask Effect and Charges Gained",
            "group": "group3",
            "conditions": [
                {
                    "stepId": "master-alchemist",
                    "predicateType": "boolean",
                    "predicate": true,
                    "action": "./master-alchemist",
                    "actionType": "route"
                }
            ]
        },
        {
            "id": "master-alchemist",
            "label": "Master Alchemist",
            "group": "group3",
            "isEnd": true
        }
    ]
}

The figure below shows a visual representation of the path provided

Action and Action Type

The action and actionType property control what should happen when the condition is resolved to true. The currently supported action types are listed below:

route -- Uses the angular router to navigate to the provided route, ex ./master-alchemist

internalPath -- Uses the base path of the site to navigation to the provide href, ex /some/url

externalUrl -- Opens a new tab with provided full URL, ex https://google.com

dummy -- skips the action and moves to the next step (allows for steps to show with out having actions)

Navfinder

The NavFinder component allows for a quick @softheon/workshop themed multi-stepper. This navigation is rendered off the provided path in the PathfinderService. Inputs can be found below:

| Name | Description | Required | Type | | ----------------- | -------------------------------------------------------- | -------- | ----------------- | | data | The data to use for the PathfinderService | True | any | | path | The path to use for the navigation | True | Path | | navText | The text that displays on top of the navigation | False | string | | currentMainStepId | Highlights the current main step based on provided value | False | string | number | | skipAhead | True if skip ahead is enabled | False | boolean |

The nav finder component uses a snapshot of the current path to display the navigation. In order to navigate to the next step, the PathfinderService's takeStepForward() function can be used. This will advance the stepper and update the snapshot re-running all the logic to show a preview of the path.