jssm 5.76.2 → 5.78.0

package/jssm.d.ts

@@ -1,7 +1,6 @@
 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';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, JssmHistory, JssmSerialization, 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';
 import { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { version } from './version';
@@ -251,7 +250,7 @@ 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]>;
+    _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>);
     /********
@@ -330,10 +329,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 +673,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;`;
@@ -685,7 +693,27 @@ declare class Machine<mDT> {
     action(actionName: StateType, newData?: mDT): boolean;
     /********
      *
-     *  Instruct the machine to complete a transition.
+     *  Instruct the machine to complete an action.  Synonym for {@link action}.
+     *
+     *  ```typescript
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();           // 'red'
+     *  light.do('next');        // true
+     *  light.state();           // 'green'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @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;`;
@@ -703,6 +731,26 @@ declare class Machine<mDT> {
      *
      */
     transition(newState: StateType, newData?: mDT): boolean;
+    /********
+     *
+     *  Instruct the machine to complete a transition.  Synonym for {@link transition}.
+     *
+     *  ```typescript
+     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();       // 'red'
+     *  light.go('green');   // true
+     *  light.state();       // 'green'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param newState The state to switch to
+     *
+     *  @param newData The data change to insert during the transition
+     *
+     */
+    go(newState: StateType, newData?: mDT): boolean;
     /********
      *
      *  Instruct the machine to complete a forced transition (which will reject if
@@ -784,4 +832,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, 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,15 @@ 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 JssmTransitionPermitter<DataType> = (OldState: StateType, NewState: StateType, OldData: DataType, NewData: DataType) => boolean;
 declare type JssmTransitionPermitterMaybeArray<DataType> = JssmTransitionPermitter<DataType> | Array<JssmTransitionPermitter<DataType>>;
 declare type JssmTransition<DataType> = {
@@ -264,4 +274,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, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult };

package/package.json

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

package/rollup.config.deno.js

@@ -0,0 +1,45 @@
+
+import nodeResolve from '@rollup/plugin-node-resolve';
+import commonjs    from '@rollup/plugin-commonjs';
+import replace     from '@rollup/plugin-replace';
+
+const pkg = require('./package.json');
+
+
+
+
+const config = {
+
+  input: 'dist/es6/jssm.js',
+
+  output: {
+    file   : 'dist/deno/jssm.deno-esm.js',
+    format : 'esm',
+    name   : 'jssm'
+  },
+
+  plugins : [
+
+    nodeResolve({
+      mainFields     : ['module', 'main'],
+      browser        : true,
+      extensions     : [ '.js', '.json', '.ts', '.tsx' ],
+      preferBuiltins : false
+    }),
+
+    commonjs(),
+
+    replace({
+      preventAssignment      : true,
+      'process.env.NODE_ENV' : JSON.stringify( 'production' )
+    })
+
+  ]
+
+};
+
+
+
+
+
+export default config;

package/typedoc-options.js

@@ -27,7 +27,7 @@ module.exports = {
             { title: 'Node',        source: 'todo.md' },
             { title: 'Typescript',  source: 'todo.md' },
             { title: 'The browser', source: 'todo.md' },
-            { title: 'Deno',        source: 'todo.md' },
+//          { title: 'Deno',        source: 'todo.md' },
             { title: 'AWS Lambda',  source: 'todo.md' },
             { title: 'SQL',         source: 'todo.md' },
           ] },