jssm 5.77.0 → 5.79.0

package/jssm.d.ts

@@ -1,8 +1,7 @@
 declare type StateType = string;
-import { circular_buffer } from 'circular_buffer_js';
 import { JssmGenericState, JssmGenericConfig, JssmTransition, JssmTransitionList, // JssmTransitionRule,
-JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult } from './jssm_types';
-import { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, JssmHistory, JssmSerialization, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult } from './jssm_types';
+import { seq, unique, find_repeated, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
 import { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { version } from './version';
 /*********
@@ -251,9 +250,12 @@ declare class Machine<mDT> {
     _post_main_transition_hook: HookHandler<mDT> | undefined;
     _post_forced_transition_hook: HookHandler<mDT> | undefined;
     _post_any_transition_hook: HookHandler<mDT> | undefined;
-    _history: circular_buffer<[StateType, mDT]>;
+    _property_keys: Set<string>;
+    _default_properties: Map<string, any>;
+    _state_properties: Map<string, any>;
+    _history: JssmHistory<mDT>;
     _history_length: number;
-    constructor({ start_states, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data }: JssmGenericConfig<mDT>);
+    constructor({ start_states, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, property_definition, state_property, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data }: JssmGenericConfig<mDT>);
     /********
      *
      *  Internal method for fabricating states.  Not meant for external use.
@@ -295,6 +297,105 @@ declare class Machine<mDT> {
      *
      */
     data(): mDT;
+    /*********
+     *
+     *  Get the current value of a given property name.
+     *
+     *  ```typescript
+     *
+     *  ```
+     *
+     *  @param name The relevant property name to look up
+     *
+     *  @returns The value behind the prop name.  Because functional props are
+     *  evaluated as getters, this can be anything.
+     *
+     */
+    prop(name: string): any;
+    /*********
+     *
+     *  Get the current value of every prop, as an object.  If no current definition
+     *  exists for a prop - that is, if the prop was defined without a default and
+     *  the current state also doesn't define the prop - then that prop will be listed
+     *  in the returned object with a value of `undefined`.
+     *
+     *  ```typescript
+     *  const traffic_light = sm`
+     *
+     *    property can_go     default true;
+     *    property hesitate   default true;
+     *    property stop_first default false;
+     *
+     *    Off -> Red => Green => Yellow => Red;
+     *    [Red Yellow Green] ~> [Off FlashingRed];
+     *    FlashingRed -> Red;
+     *
+     *    state Red:         { property stop_first true;  property can_go false; };
+     *    state Off:         { property stop_first true;  };
+     *    state FlashingRed: { property stop_first true;  };
+     *    state Green:       { property hesitate   false; };
+     *
+     *  `;
+     *
+     *  traffic_light.state();  // Off
+     *  traffic_light.props();  // { can_go: true,  hesitate: true,  stop_first: true;  }
+     *
+     *  traffic_light.go('Red');
+     *  traffic_light.props();  // { can_go: false, hesitate: true,  stop_first: true;  }
+     *
+     *  traffic_light.go('Green');
+     *  traffic_light.props();  // { can_go: true,  hesitate: false, stop_first: false; }
+     *  ```
+     *
+     */
+    props(): object;
+    /*********
+     *
+     *  Get the current value of every prop, as an object.  Compare
+     *  {@link prop_map}, which returns a `Map`.
+     *
+     *  ```typescript
+     *
+     *  ```
+     *
+     */
+    /*********
+     *
+     *  Get the current value of every prop, as an object.  Compare
+     *  {@link prop_map}, which returns a `Map`.  Akin to {@link strict_prop},
+     *  this throws if a required prop is missing.
+     *
+     *  ```typescript
+     *
+     *  ```
+     *
+     */
+    /*********
+     *
+     *  Check whether a given string is a known property's name.
+     *
+     *  ```typescript
+     *  const example = sm`property foo default 1; a->b;`;
+     *
+     *  example.known_prop('foo');  // true
+     *  example.known_prop('bar');  // false
+     *  ```
+     *
+     *  @param prop_name The relevant property name to look up
+     *
+     */
+    known_prop(prop_name: string): boolean;
+    /*********
+     *
+     *  List all known property names.  If you'd also like values, use
+     *  {@link props} instead.  The order of the properties is not defined, and
+     *  the properties generally will not be sorted.
+     *
+     *  ```typescript
+     *  ```
+     *
+     */
+    known_props(): string[];
     /********
      *
      *  Check whether a given state is final (either has no exits or is marked
@@ -330,10 +431,19 @@ declare class Machine<mDT> {
      *  console.log( final_test.is_final() );   // true
      *  ```
      *
+     */
+    is_final(): boolean;
+    /********
+     *
+     *  Serialize the current machine, including all defining state but not the
+     *  machine string, to a structure.  This means you will need the machine
+     *  string to recreate (to not waste repeated space;) if you want the machine
+     *  string embedded, call {@link serialize_with_string} instead.
+     *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
      */
-    is_final(): boolean;
+    serialize(comment?: string | undefined): JssmSerialization<mDT>;
     graph_layout(): string;
     dot_preamble(): string;
     machine_author(): Array<string>;
@@ -665,7 +775,7 @@ declare class Machine<mDT> {
     set history_length(to: number);
     /********
      *
-     *  Instruct the machine to complete an action.
+     *  Instruct the machine to complete an action.  Synonym for {@link do}.
      *
      *  ```typescript
      *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
@@ -683,16 +793,58 @@ declare class Machine<mDT> {
      *
      */
     action(actionName: StateType, newData?: mDT): boolean;
+    /********
+     *
+     *  Instruct the machine to complete an action.  Synonym for {@link action}.
+     *
+     *  ```typescript
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
+     *
+     *  light.state();       // 'off'
+     *  light.do('start');   // true
+     *  light.state();       // 'red'
+     *  light.do('next');    // true
+     *  light.state();       // 'green'
+     *  light.do('next');    // true
+     *  light.state();       // 'yellow'
+     *  light.do('dance');   // !! false - no such action
+     *  light.state();       // 'yellow'
+     *  light.do('start');   // !! false - yellow does not have the action start
+     *  light.state();       // 'yellow'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+  b   *
+     *  @param actionName The action to engage
+     *
+     *  @param newData The data change to insert during the action
+     *
+     */
+    do(actionName: StateType, newData?: mDT): boolean;
     /********
      *
      *  Instruct the machine to complete a transition.  Synonym for {@link go}.
      *
      *  ```typescript
-     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
      *
-     *  light.state();               // 'red'
-     *  light.transition('green');   // true
-     *  light.state();               // 'green'
+     *  light.state();       // 'off'
+     *  light.go('red');     // true
+     *  light.state();       // 'red'
+     *  light.go('green');   // true
+     *  light.state();       // 'green'
+     *  light.go('blue');    // !! false - no such state
+     *  light.state();       // 'green'
+     *  light.go('red');     // !! false - green may not go directly to red, only to yellow
+     *  light.state();       // 'green'
      *  ```
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
@@ -804,4 +956,5 @@ declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Par
 declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
 declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
 declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<mDT>;
-export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };
+declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
+export { version, transfer_state_properties, Machine, deserialize, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };

package/jssm_types.d.ts

@@ -1,3 +1,4 @@
+import { circular_buffer } from 'circular_buffer_js';
 declare type StateType = string;
 declare type JssmSuccess = {
     success: true;
@@ -25,6 +26,19 @@ declare type JssmCorner = 'regular' | 'rounded' | 'lined';
 declare type JssmLineStyle = 'solid' | 'dashed' | 'dotted';
 declare type FslDirection = 'up' | 'right' | 'down' | 'left';
 declare type FslTheme = 'default' | 'ocean' | 'modern' | 'none';
+declare type JssmSerialization<DataType> = {
+    jssm_version: string;
+    timestamp: number;
+    comment?: string | undefined;
+    state: StateType;
+    history: [string, DataType][];
+    history_capacity: number;
+    data: DataType;
+};
+declare type JssmPropertyDefinition = {
+    name: string;
+    default_value?: any;
+};
 declare type JssmTransitionPermitter<DataType> = (OldState: StateType, NewState: StateType, OldData: DataType, NewData: DataType) => boolean;
 declare type JssmTransitionPermitterMaybeArray<DataType> = JssmTransitionPermitter<DataType> | Array<JssmTransitionPermitter<DataType>>;
 declare type JssmTransition<DataType> = {
@@ -38,7 +52,7 @@ declare type JssmTransition<DataType> = {
     forced_only: boolean;
     main_path: boolean;
 };
-declare type JssmTransitions<DataType> = Array<JssmTransition<DataType>>;
+declare type JssmTransitions<DataType> = JssmTransition<DataType>[];
 declare type JssmTransitionList = {
     entrances: Array<StateType>;
     exits: Array<StateType>;
@@ -83,6 +97,7 @@ declare type JssmGenericMachine<DataType> = {
 declare type JssmStateDeclarationRule = {
     key: string;
     value: any;
+    name?: string;
 };
 declare type JssmStateDeclaration = {
     declarations: Array<JssmStateDeclarationRule>;
@@ -94,6 +109,10 @@ declare type JssmStateDeclaration = {
     backgroundColor?: JssmColor;
     borderColor?: JssmColor;
     state: StateType;
+    property?: {
+        name: string;
+        value: unknown;
+    };
 };
 declare type JssmGenericConfig<DataType> = {
     graph_layout?: JssmLayout;
@@ -115,7 +134,9 @@ declare type JssmGenericConfig<DataType> = {
     dot_preamble?: string;
     start_states: Array<StateType>;
     end_states?: Array<StateType>;
-    state_declaration?: Array<Object>;
+    state_declaration?: Object[];
+    property_definition?: JssmPropertyDefinition[];
+    state_property?: JssmPropertyDefinition[];
     arrange_declaration?: Array<Array<StateType>>;
     arrange_start_declaration?: Array<Array<StateType>>;
     arrange_end_declaration?: Array<Array<StateType>>;
@@ -150,6 +171,8 @@ declare type JssmCompileSeStart<DataType> = {
     key: string;
     value?: string | number;
     name?: string;
+    state?: string;
+    default_value?: any;
 };
 declare type JssmParseTree = Array<JssmCompileSeStart<StateType>>;
 declare type JssmParseFunctionType = (string: any) => JssmParseTree;
@@ -264,4 +287,5 @@ declare type PostHookHandler<mDT> = (hook_context: HookContext<mDT>) => void;
 declare type JssmErrorExtendedInfo = {
     requested_state?: StateType | undefined;
 };
-export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmLayout, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult };
+declare type JssmHistory<mDT> = circular_buffer<[StateType, mDT]>;
+export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult };

package/jssm_util.d.ts

@@ -35,6 +35,13 @@ declare function seq(n: number): number[];
 declare const histograph: Function;
 declare const weighted_sample_select: Function;
 declare const weighted_histo_key: Function;
+/*******
+ *
+ *  Internal method generating names for edges for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
+declare function name_bind_prop_and_state(prop: string, state: string): string;
 /*******
  *
  *  Internal method generating names for edges for the hook lookup map.  Not
@@ -57,4 +64,40 @@ declare const named_hook_name: (from: string, to: string, action: string) => str
  *
  */
 declare const make_mulberry_rand: (a?: number | undefined) => () => number;
-export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name, make_mulberry_rand };
+/*******
+ *
+ *  Reduces an array to its unique contents.  Compares with `===` and makes no
+ *  effort to deep-compare contents; two matching arrays or objects contained
+ *  will be treated as distinct, according to javascript rules.  This also means
+ *  that `NaNs` will be ***dropped***, because they do not self-compare.
+ *
+ *  ```typescript
+ *  unique( [] );                     // []
+ *  unique( [0,0] );                  // [0]
+ *  unique( [0,1,2, 0,1,2, 0,1,2] );  // [0,1,2]
+ *  unique( [ [1], [1] ] );           // [ [1], [1] ] because arrays don't match
+ *  unique( [0,NaN,2] );              // [0,2]
+ *  ```
+ *
+ */
+declare const unique: <T>(arr?: T[]) => T[];
+/*******
+ *
+ *  Lists all repeated items in an array along with their counts.  Subject to
+ *  matching rules of Map.  `NaN` is manually removed because of conflict rules
+ *  around {@link unique}.  Because these are compared with `===` and because
+ *  arrays and objects never match that way unless they're the same object,
+ *  arrays and objects are never considered repeats.
+ *
+ *  ```typescript
+ *  find_repeated<string>([ ]);                     // []
+ *  find_repeated<string>([ "one" ]);               // []
+ *  find_repeated<string>([ "one", "two" ]);        // []
+ *  find_repeated<string>([ "one", "one" ]);        // [ ["one", 2] ]
+ *  find_repeated<string>([ "one", "two", "one" ]); // [ ["one", 2] ]
+ *  find_repeated<number>([ 0, NaN, 0, NaN ]);      // [ [0,     2] ]
+ *  ```
+ *
+ */
+declare function find_repeated<T>(arr: T[]): [T, number][];
+export { seq, unique, find_repeated, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, name_bind_prop_and_state, hook_name, named_hook_name, make_mulberry_rand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.77.0",
+  "version": "5.79.0",
   "engines": {
     "node": ">=10.0.0"
   },