@xstate/graph

@xstate/graph package 包含用于 XState 状态机的图形算法和实用程序。

快速开始

  1. 安装 xstate 和 @xstate/graph:
  1. npm install xstate @xstate/graph
  1. 导入图相关方法。例如：
  1. import { createMachine } from 'xstate';
  2. import { getSimplePaths } from '@xstate/graph';
  4. const machine = createMachine(/* ... */);
  5. const paths = getSimplePaths(machine);

API

getShortestPaths(machine, options?)

参数

  • machine - the Machine to traverse
  • options (optional) - options that customize how the algorithm will traverse the machine

Returns the shortest paths (Dijkstra’s algorithm) of a machine from the initial state to every other state as a mapped object, where the:

  • key is the stringified state
  • value is an object with the properties:
    • state - the target State
    • path - the shortest path to get from the initial state to the target state

The path is an array of segments, where each segment is an object with the properties:

  • state - the State of the segment
  • weight - the total weight#Weighted_graph>) of the path
    • Currently, each transition from one state to another has a weight of 1. This will be customizable in the future.
  • event - the event object that transitions the machine from the state to the next state in the path

Every path starts with the initial state.

The overall object structure looks like this:

  1. {
  2.   "<SERIALIZED STATE>": {
  3.     "state": State { ... },
  4.     "path": [
  5.       {
  6.         "state": State { ... },
  7.         "event": { "type": "<event.type>", "<PROP>": "<event.PROP>" }
  8.       },
  9.       {
  10.         "state": State { ... },
  11.         "event": { "type": "<event.type>", "<PROP>": "<event.PROP>" }
  12.       },
  13.       ...
  14.     ]
  15.   },
  16.   ...
  17. }

示例

  1. import { createMachine } from 'xstate';
  2. import { getShortestPaths } from '@xstate/graph';
  4. const feedbackMachine = createMachine({
  5.   id: 'feedback',
  6.   initial: 'question',
  7.   states: {
  8.     question: {
  9.       on: {
  10.         CLICK_GOOD: 'thanks',
  11.         CLICK_BAD: 'form',
  12.         CLOSE: 'closed',
  13.         ESC: 'closed'
  14.       }
  15.     },
  16.     form: {
  17.       on: {
  18.         SUBMIT: 'thanks',
  19.         CLOSE: 'closed',
  20.         ESC: 'closed'
  21.       }
  22.     },
  23.     thanks: {
  24.       on: {
  25.         CLOSE: 'closed',
  26.         ESC: 'closed'
  27.       }
  28.     },
  29.     closed: {
  30.       type: 'final'
  31.     }
  32.   }
  33. });
  35. const shortestPaths = getShortestPaths(feedbackMachine);
  37. console.log(shortestPaths);
  38. // => {
  39. //   '"question"': {
  40. //     state: State { value: 'question', context: undefined },
  41. //     weight: 0,
  42. //     path: []
  43. //   },
  44. //   '"thanks"': {
  45. //     state: State { value: 'thanks', context: undefined },
  46. //     weight: 1,
  47. //     path: [
  48. //       {
  49. //         state: State { value: 'question', context: undefined },
  50. //         event: { type: 'CLICK_GOOD' }
  51. //       }
  52. //     ]
  53. //   },
  54. //   '"form"': {
  55. //     state: State { value: 'form', context: undefined },
  56. //     weight: 1,
  57. //     path: [
  58. //       {
  59. //         state: State { value: 'question', context: undefined },
  60. //         event: { type: 'CLICK_BAD' }
  61. //       }
  62. //     ]
  63. //   },
  64. //   '"closed"': {
  65. //     state: State { value: 'closed', context: undefined },
  66. //     weight: 1,
  67. //     path: [
  68. //       {
  69. //         state: State { value: 'question', context: undefined },
  70. //         event: { type: 'CLOSE' }
  71. //       }
  72. //     ]
  73. //   }
  74. // };

getSimplePaths(machine, options?)

Arguments

  • machine - the Machine to traverse
  • options (optional) - options that customize how the algorithm will traverse the machine

Returns the simple paths#Definitions>) of a machine as a mapped object, where the:

  • key is the stringified state
  • value is an object with the properties:
    • state - the target State
    • paths - the array of paths to get from the initial state to the target state

Each path in paths is an array of segments, where each segment of the path is an object with the properties:

  • state - the State of the segment
  • event - the event object that transitions the machine from the state to the next state in the path

Every path starts with the initial state.

The overall object structure looks like this:

  1. {
  2.   "<SERIALIZED STATE>": {
  3.     "state": State { ... },
  4.     "paths": [
  5.       [
  6.         {
  7.           "state": State { ... },
  8.           "event": { "type": "<event.type>", "<PROP>": "<event.PROP>" }
  9.         },
  10.         {
  11.           "state": State { ... },
  12.           "event": { "type": "<event.type>", "<PROP>": "<event.PROP>" }
  13.         },
  14.         ...
  15.       ],
  16.       ...
  17.     ]
  18.   },
  19.   ...
  20. }

示例

  1. import { createMachine } from 'xstate';
  2. import { getSimplePaths } from '@xstate/graph';
  4. const feedbackMachine = createMachine({
  5.   id: 'feedback',
  6.   initial: 'question',
  7.   states: {
  8.     question: {
  9.       on: {
  10.         CLICK_GOOD: 'thanks',
  11.         CLICK_BAD: 'form',
  12.         CLOSE: 'closed',
  13.         ESC: 'closed'
  14.       }
  15.     },
  16.     form: {
  17.       on: {
  18.         SUBMIT: 'thanks',
  19.         CLOSE: 'closed',
  20.         ESC: 'closed'
  21.       }
  22.     },
  23.     thanks: {
  24.       on: {
  25.         CLOSE: 'closed',
  26.         ESC: 'closed'
  27.       }
  28.     },
  29.     closed: {
  30.       type: 'final'
  31.     }
  32.   }
  33. });
  35. const simplePaths = getSimplePaths(feedbackMachine);
  37. console.log(simplePaths);
  38. // => {
  39. //   '"question"': {
  40. //     state: { value: 'question', context: undefined },
  41. //     paths: [[]]
  42. //   },
  43. //   '"thanks"': {
  44. //     state: { value: 'thanks', context: undefined },
  45. //     paths: [
  46. //       [
  47. //         {
  48. //           state: { value: 'question', context: undefined },
  49. //           event: { type: 'CLICK_GOOD' }
  50. //         }
  51. //       ],
  52. //       [
  53. //         {
  54. //           state: { value: 'question', context: undefined },
  55. //           event: { type: 'CLICK_BAD' }
  56. //         },
  57. //         {
  58. //           state: { value: 'form', context: undefined },
  59. //           event: { type: 'SUBMIT' }
  60. //         }
  61. //       ]
  62. //     ]
  63. //   },
  64. //   '"closed"': {
  65. //     state: { value: 'closed', context: undefined },
  66. //     paths: [
  67. //       [
  68. //         {
  69. //           state: { value: 'question', context: undefined },
  70. //           event: { type: 'CLICK_GOOD' }
  71. //         },
  72. //         {
  73. //           state: { value: 'thanks', context: undefined },
  74. //           event: { type: 'CLOSE' }
  75. //         }
  76. //       ],
  77. //       [
  78. //         {
  79. //           state: { value: 'question', context: undefined },
  80. //           event: { type: 'CLICK_GOOD' }
  81. //         },
  82. //         {
  83. //           state: { value: 'thanks', context: undefined },
  84. //           event: { type: 'ESC' }
  85. //         }
  86. //       ],
  87. //       ...
  88. //     ]
  89. //   },
  90. //   ...
  91. // };

getPathFromEvents(machine, events)

参数

  • machine - the Machine to traverse
  • events - the sequence of events to generate a path from

Returns a path object with the following keys:

  • state - the target State
  • segments - an array of objects with the following shape:
    • state - the State of the segment
    • event - the event object that transitions the machine from the state to the next state in the path
  1. import { createMachine } from 'xstate';
  2. import { getSimplePaths } from '@xstate/graph';
  4. const feedbackMachine = createMachine({
  5.   id: 'feedback',
  6.   initial: 'question',
  7.   states: {
  8.     question: {
  9.       on: {
  10.         CLICK_GOOD: 'thanks',
  11.         CLICK_BAD: 'form',
  12.         CLOSE: 'closed',
  13.         ESC: 'closed'
  14.       }
  15.     },
  16.     form: {
  17.       on: {
  18.         SUBMIT: 'thanks',
  19.         CLOSE: 'closed',
  20.         ESC: 'closed'
  21.       }
  22.     },
  23.     thanks: {
  24.       on: {
  25.         CLOSE: 'closed',
  26.         ESC: 'closed'
  27.       }
  28.     },
  29.     closed: {
  30.       type: 'final'
  31.     }
  32.   }
  33. });
  35. const path = getPathFromEvents(feedbackMachine, [
  36.   { type: 'CLICK_GOOD' },
  37.   { type: 'SUBMIT' },
  38.   { type: 'CLOSE' }
  39. ]);
  41. console.log(path);
  42. // => {
  43. //   state: { value: 'closed' },
  44. //   segments: [
  45. //     {
  46. //       state: { value: 'question' },
  47. //       event: { type: 'CLICK_GOOD' },
  48. //     },
  49. //     {
  50. //       state: { value: 'form' },
  51. //       event: { type: 'SUBMIT' },
  52. //     },
  53. //     {
  54. //       state: { value: 'thanks' },
  55. //       event: { type: 'CLOSE' },
  56. //     },
  57. //   ],
  58. // }

toDirectedGraph(machine)

Converts a machine to a directed graph structure.

Argument Type Description
machine XState Machine created by createMachine(...) The machine to convert to a directed graph structure

示例

  1. import { toDirectedGraph } from '@xstate/graph';
  3. const machine = createMachine({/* ... */});
  5. const digraph = toDirectedGraph(machine);
  7. // returns an object with this structure:
  8. {
  9.   id: '...',
  10.   stateNode: /* StateNode */,
  11.   children: [
  12.     { id: '...', children: [/* ... */], edges: [/* ... */] },
  13.     { id: '...', /* ... */ },
  14.     // ...
  15.   ],
  16.   edges: [
  17.     { source: /* ... */, target: /* ... */, transition: /* ... */ }
  18.     // ...
  19.   ]
  20. }

选项

Options can be passed into getShortestPaths or getSimplePaths to customize how the graph represented by the machine should be traversed:

  • events - a mapping of event types to an array of event objects to be used for those events
  • filter - a function that determines whether a state should be traversed. If false, the traversal algorithm(s) will assume the state was “seen” and ignore traversing it.

示例

In the below example, the INC event is expanded to include two possible events, with value: 1 and value: 2 as the payload. It also ensures that the state.context.count <= 5; otherwise, this machine would be traversed infinitely.

  1. const counterMachine = createMachine({
  2.   id: 'counter',
  3.   initial: 'active',
  4.   context: { count: 0 },
  5.   states: {
  6.     active: {
  7.       on: {
  8.         INC: {
  9.           actions: assign({ count: (ctx, e) => ctx.count + e.value })
  10.         }
  11.       }
  12.     }
  13.   }
  14. });
  16. const shortestPaths = getShortestPaths(counterMachine, {
  17.   events: {
  18.     INC: [
  19.       { type: 'INC', value: 1 },
  20.       { type: 'INC', value: 2 }
  21.     ]
  22.   },
  23.   filter: (state) => state.context.count <= 5
  24. });
  26. console.log(shortestPaths);
  27. // => {
  28. //   '"active" | {"count":0}': {
  29. //     state: { value: 'active', context: { count: 0 } },
  30. //     weight: 0,
  31. //     path: []
  32. //   },
  33. //   '"active" | {"count":1}': {
  34. //     state: { value: 'active', context: { count: 1 } },
  35. //     weight: 1,
  36. //     path: [
  37. //       {
  38. //         state: { value: 'active', context: { count: 0 } },
  39. //         event: { type: 'INC', value: 1 }
  40. //       }
  41. //     ]
  42. //   },
  43. //   '"active" | {"count":2}': {
  44. //     state: { value: 'active', context: { count: 2 } },
  45. //     weight: 1,
  46. //     path: [
  47. //       {
  48. //         state: { value: 'active', context: { count: 0 } },
  49. //         event: { type: 'INC', value: 2 }
  50. //       }
  51. //     ]
  52. //   },
  53. //   '"active" | {"count":3}': {
  54. //     state: { value: 'active', context: { count: 3 } },
  55. //     weight: 2,
  56. //     path: [
  57. //       {
  58. //         state: { value: 'active', context: { count: 0 } },
  59. //         event: { type: 'INC', value: 1 }
  60. //       },
  61. //       {
  62. //         state: { value: 'active', context: { count: 1 } },
  63. //         event: { type: 'INC', value: 2 }
  64. //       }
  65. //     ]
  66. //   },
  67. //   ...
  68. // };