jssm 5.104.2 → 5.112.3

package/dist/es6/jssm_util.js

@@ -1,26 +1,87 @@
 import { JssmError } from './jssm_error';
 /*******
  *
- *  Predicate for validating an array for uniqueness.  Not generally meant for
- *  external use.
+ *  Predicate for validating an array for uniqueness.  Returns `true` when
+ *  `el` is the first occurrence in `source`, `false` otherwise.  Intended
+ *  for use as an `Array.filter` callback.  Not generally meant for external
+ *  use.
+ *
+ *  ```typescript
+ *  [1, 2, 2, 3].filter(arr_uniq_p);  // [1, 2, 3]
+ *  ```
+ *
+ *  @param el     - The current element being tested.
+ *  @param i      - The index of the current element.
+ *  @param source - The full array being filtered.
+ *
+ *  @returns `true` if `el` is the first occurrence in `source`.
  *
  */
 function arr_uniq_p(el, i, source) {
     return source.indexOf(el) === i;
 }
+/*******
+ *
+ *  Wraps a string in an array, or passes through if already non-string.
+ *  Used to normalize arguments that accept either a single state name or
+ *  an array of state names.
+ *
+ *  ```typescript
+ *  array_box_if_string('hello');    // ['hello']
+ *  array_box_if_string(['a','b']); // ['a','b']
+ *  ```
+ *
+ *  @param n - A string to box, or a value to pass through unchanged.
+ *
+ *  @returns The input wrapped in an array if it was a string, otherwise the
+ *           input unchanged.
+ *
+ */
 const array_box_if_string = n => typeof n === 'string' ? [n] : n;
+/*******
+ *
+ *  Selects a single item from a weighted array of objects using cumulative
+ *  probability.  Each object in the array should have a numeric property
+ *  indicating its relative weight (defaults to `'probability'`).  Objects
+ *  missing the property are treated as weight 1.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'common',  probability: 0.8 },
+ *    { value: 'rare',    probability: 0.2 }
+ *  ];
+ *
+ *  weighted_rand_select(opts);  // most often { value: 'common', ... }
+ *  ```
+ *
+ *  @param options              - Non-empty array of objects to choose from.
+ *  @param probability_property - Name of the numeric weight property on each
+ *                                object.  Defaults to `'probability'`.
+ *  @param rng                  - Optional random number generator `() => number`
+ *                                in `[0, 1)`.  Defaults to `Math.random`.
+ *
+ *  @returns One element from `options`, chosen by weighted random selection.
+ *
+ *  @throws {TypeError} If `options` is not a non-empty array of objects.
+ *
+ */
 // this is explicitly about other peoples' data, so it has to be weakly typed
 /* eslint-disable flowtype/no-weak-types */
 const weighted_rand_select = (options, probability_property = 'probability', rng) => {
     if (!Array.isArray(options)) {
         throw new TypeError('options must be a non-empty array of objects');
     }
+    if (options.length === 0) {
+        throw new TypeError('options must be a non-empty array of objects');
+    }
     if (!(typeof options[0] === 'object')) {
         throw new TypeError('options must be a non-empty array of objects');
     }
-    const frand = (cap) => Math.random() * cap, or_one = (item) => item === undefined ? 1 : item, prob_sum = options.reduce((acc, val) => acc + or_one(val[probability_property]), 0), rnd = frand(prob_sum);
+    const frand = rng
+        ? (cap) => rng() * cap
+        : (cap) => Math.random() * cap, or_one = (item) => item === undefined ? 1 : item, prob_sum = options.reduce((acc, val) => acc + or_one(val[probability_property]), 0), rnd = frand(prob_sum);
     let cursor = 0, cursor_sum = 0;
-    while ((cursor_sum += or_one(options[cursor++][probability_property])) <= rnd) { } // eslint-disable-line no-empty,fp/no-loops
+    while (cursor < options.length && (cursor_sum += or_one(options[cursor++][probability_property])) <= rnd) { } // eslint-disable-line no-empty,fp/no-loops
     return options[cursor - 1];
 };
 /* eslint-enable flowtype/no-weak-types */
@@ -60,21 +121,82 @@ function seq(n) {
  *
  */
 const histograph = (ar) => // eslint-disable-line flowtype/no-weak-types
- ar.sort()
+ [...ar].sort()
     .reduce((m, v) => // TODO FIXME eslint-disable-line flowtype/no-weak-types,no-sequences
  (m.set(v, (m.has(v) ? m.get(v) + 1 : 1)), m), new Map());
-const weighted_sample_select = (n, options, probability_property) => // TODO FIXME no any // eslint-disable-line flowtype/no-weak-types
+/*******
+ *
+ *  Draws `n` weighted random samples from an array of objects.  Each draw is
+ *  independent (with replacement), delegating to {@link weighted_rand_select}.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'a', probability: 0.9 },
+ *    { value: 'b', probability: 0.1 }
+ *  ];
+ *
+ *  weighted_sample_select(3, opts, 'probability');
+ *  // e.g. [ { value: 'a', ... }, { value: 'a', ... }, { value: 'b', ... } ]
+ *  ```
+ *
+ *  @param n                    - Number of samples to draw.
+ *  @param options              - Non-empty array of weighted objects.
+ *  @param probability_property - Name of the numeric weight property.
+ *  @param rng                  - Optional random number generator.
+ *
+ *  @returns An array of `n` independently selected items.
+ *
+ */
+const weighted_sample_select = (n, options, probability_property, rng) => // TODO FIXME no any // eslint-disable-line flowtype/no-weak-types
  seq(n)
     .map((_i) => // TODO FIXME eslint-disable-line flowtype/no-weak-types
- weighted_rand_select(options, probability_property));
-const weighted_histo_key = (n, opts, prob_prop, extract) => // TODO FIXME no any // eslint-disable-line flowtype/no-weak-types
- histograph(weighted_sample_select(n, opts, prob_prop)
+ weighted_rand_select(options, probability_property, rng));
+/*******
+ *
+ *  Draws `n` weighted random samples, extracts a named key from each, and
+ *  returns a histograph (`Map`) of how often each key value appeared.  Useful
+ *  for validating that a probabilistic transition distribution is roughly
+ *  correct over many trials.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { to: 'a', probability: 0.7 },
+ *    { to: 'b', probability: 0.3 }
+ *  ];
+ *
+ *  weighted_histo_key(1000, opts, 'probability', 'to');
+ *  // Map { 'a' => ~700, 'b' => ~300 }
+ *  ```
+ *
+ *  @param n         - Number of samples to draw.
+ *  @param opts      - Non-empty array of weighted objects.
+ *  @param prob_prop - Name of the numeric weight property.
+ *  @param extract   - Name of the property to extract from each sample for
+ *                     histogramming.
+ *  @param rng       - Optional random number generator.
+ *
+ *  @returns A `Map` from extracted key values to their occurrence counts.
+ *
+ */
+const weighted_histo_key = (n, opts, prob_prop, extract, rng) => // TODO FIXME no any // eslint-disable-line flowtype/no-weak-types
+ histograph(weighted_sample_select(n, opts, prob_prop, rng)
     .map((s) => s[extract] // TODO FIXME eslint-disable-line flowtype/no-weak-types
 ));
 /*******
  *
- *  Internal method generating names for edges for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for the hook lookup map by
+ *  JSON-serializing a `[property, state]` pair.  Not meant for external use.
+ *
+ *  ```typescript
+ *  name_bind_prop_and_state('color', 'Red');  // '["color","Red"]'
+ *  ```
+ *
+ *  @param prop  - The property name (e.g. a data key or hook category).
+ *  @param state - The state name to bind to.
+ *
+ *  @returns A deterministic JSON string key for the `[prop, state]` pair.
+ *
+ *  @throws {JssmError} If either argument is not a string.
  *
  */
 function name_bind_prop_and_state(prop, state) {
@@ -82,21 +204,42 @@ function name_bind_prop_and_state(prop, state) {
         throw new JssmError(undefined, `Name of property must be a string; got ${prop}`);
     }
     if (typeof state !== 'string') {
-        throw new JssmError(undefined, `Name of state must be a string; got ${prop}`);
+        throw new JssmError(undefined, `Name of state must be a string; got ${state}`);
     }
     return JSON.stringify([prop, state]);
 }
 /*******
  *
- *  Internal method generating names for edges for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for transition hooks by
+ *  JSON-serializing a `[from, to]` state pair.  Used to look up hooks
+ *  registered on a specific edge.  Not meant for external use.
+ *
+ *  ```typescript
+ *  hook_name('Red', 'Green');  // '["Red","Green"]'
+ *  ```
+ *
+ *  @param from - The source state name.
+ *  @param to   - The target state name.
+ *
+ *  @returns A deterministic JSON string key for the `[from, to]` pair.
  *
  */
 const hook_name = (from, to) => JSON.stringify([from, to]);
 /*******
  *
- *  Internal method generating names for actions for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for named-action hooks by
+ *  JSON-serializing a `[from, to, action]` triple.  Used to look up hooks
+ *  registered on a specific action-labeled edge.  Not meant for external use.
+ *
+ *  ```typescript
+ *  named_hook_name('Red', 'Green', 'next');  // '["Red","Green","next"]'
+ *  ```
+ *
+ *  @param from   - The source state name.
+ *  @param to     - The target state name.
+ *  @param action - The action label on the edge.
+ *
+ *  @returns A deterministic JSON string key for the `[from, to, action]` triple.
  *
  */
 const named_hook_name = (from, to, action) => JSON.stringify([from, to, action]);
@@ -116,7 +259,7 @@ function gen_splitmix32(a) {
     return function () {
         a |= 0;
         a = a + 0x9e3779b9 | 0;
-        var t = a ^ a >>> 16;
+        let t = a ^ a >>> 16;
         t = Math.imul(t, 0x21f0aaad);
         t = t ^ t >>> 15;
         t = Math.imul(t, 0x735a2d97);
@@ -174,6 +317,20 @@ function find_repeated(arr) {
         return [];
     }
 }
+/*******
+ *
+ *  Returns a `Promise` that resolves after `ms` milliseconds.  Useful for
+ *  inserting delays in async test flows or demos.
+ *
+ *  ```typescript
+ *  await sleep(100);  // pauses execution for 100ms
+ *  ```
+ *
+ *  @param ms - Number of milliseconds to wait before resolving.
+ *
+ *  @returns A `Promise<void>` that resolves after the timeout.
+ *
+ */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }

package/dist/es6/jssm_viz.d.ts

@@ -0,0 +1,175 @@
+import * as jssm from './jssm';
+import { version, build_time } from './version';
+/**
+ *  Inject runtime configuration for jssm/viz.  Currently only accepts a
+ *  custom `DOMParser` constructor for use by `*_svg_element` functions in
+ *  environments that do not provide one globally (e.g. Node + jsdom).
+ *
+ *  Idempotent — last call wins.  No-op if called with no recognized keys.
+ *
+ *  ```typescript
+ *  // Node, with jsdom:
+ *  import { JSDOM } from 'jsdom';
+ *  import { configure, fsl_to_svg_element } from 'jssm/viz';
+ *
+ *  configure({ DOMParser: new JSDOM().window.DOMParser });
+ *  const el = await fsl_to_svg_element('a -> b;');
+ *  ```
+ *
+ *  @param opts Configuration overrides.
+ *  @param opts.DOMParser Constructor compatible with the WHATWG `DOMParser`
+ *  interface.  Used as a fallback when `globalThis.DOMParser` is undefined.
+ *
+ *  @throws {JssmError} if `DOMParser` is provided and is not a constructor.
+ */
+declare function configure(opts: {
+    DOMParser?: typeof globalThis.DOMParser;
+}): void;
+/**
+ *  Look up a color from the default viz palette by key, returning empty
+ *  string if the key is unknown (so it disappears in feature concatenation).
+ *
+ *  @internal
+ */
+declare function vc(col: string): string;
+/**
+ *  Build a graphviz-safe node identifier for a state, by index.  Accepts
+ *  either a `string[]` (used historically; O(n) per call) or a
+ *  precomputed `Map<state, index>` (used by rendering hot paths; O(1)
+ *  per call).  The map form is used during dot generation; the array
+ *  form is retained for direct test access via `_test`.
+ *
+ *  @internal
+ */
+declare function node_of(state: string, state_index: string[] | Map<string, number>): string;
+/**
+ *  Convert an 8-channel hex color (`#RRGGBBAA`) to a 6-channel hex color
+ *  (`#RRGGBB`), discarding the alpha channel.  Throws if the input is not
+ *  a 9-character `#`-prefixed string.
+ *
+ *  Graphviz dot does not support alpha; this is a lossy projection.
+ *
+ *  @internal
+ */
+declare function color8to6(color8: string): string;
+/**
+ *  Variant of {@link color8to6} that passes `undefined` through.
+ *
+ *  @internal
+ */
+declare function u_color8to6(color8?: string): string | undefined;
+/**
+ *  Read the graphviz shape for a state through {@link jssm.Machine.style_for},
+ *  so theme-supplied shapes are honoured along with per-state declarations.
+ *  Returns `undefined` if neither a theme nor a state declaration supplies a
+ *  shape.
+ *
+ *  @internal
+ */
+declare function shape_for_state<T>(u_jssm: jssm.Machine<T>, state: string): string | undefined;
+/**
+ *  Read the image filename for a state through {@link jssm.Machine.style_for},
+ *  so theme-supplied images are honoured along with per-state declarations.
+ *  Returns `undefined` if neither a theme nor a state declaration supplies an
+ *  image.
+ *
+ *  @internal
+ */
+declare function image_for_state<T>(u_jssm: jssm.Machine<T>, state: string): string | undefined;
+/**
+ *  Compose a graphviz `style` string for a state by looking up its merged
+ *  style via {@link jssm.Machine.style_for}, then delegating to
+ *  {@link compose_style_string}.  Theme-supplied `corners` and `lineStyle`
+ *  are honoured along with per-state declarations.
+ *
+ *  @internal
+ */
+declare function style_for_state<T>(u_jssm: jssm.Machine<T>, state: string): string;
+/**
+ *  Render a {@link jssm.Machine} as a graphviz dot string.
+ *
+ *  ```typescript
+ *  import { sm } from 'jssm';
+ *  import { machine_to_dot } from 'jssm/viz';
+ *
+ *  const dot = machine_to_dot(sm`a -> b;`);
+ *  // 'digraph G { ... }'
+ *  ```
+ *
+ *  @param u_jssm The machine to render.
+ *  @returns A complete graphviz dot source string.
+ */
+declare function machine_to_dot<T>(u_jssm: jssm.Machine<T>): string;
+/**
+ *  Render an FSL string directly to graphviz dot source.
+ *
+ *  ```typescript
+ *  import { fsl_to_dot } from 'jssm/viz';
+ *  const dot = fsl_to_dot('a -> b;');
+ *  ```
+ *
+ *  @param fsl The FSL source.
+ *  @returns A complete graphviz dot source string.
+ */
+declare function fsl_to_dot(fsl: string): string;
+/**
+ *  Render a graphviz dot source string to SVG using `@viz-js/viz`.  The
+ *  underlying viz instance is lazy-initialized on first call and cached for
+ *  the lifetime of the module.
+ *
+ *  ```typescript
+ *  const svg = await dot_to_svg('digraph G { a -> b }');
+ *  ```
+ *
+ *  @param dot Graphviz dot source.
+ *  @returns A promise resolving to an SVG XML string.
+ */
+declare function dot_to_svg(dot: string): Promise<string>;
+/**
+ *  Render an FSL string directly to SVG.
+ *
+ *  @param fsl The FSL source.
+ *  @returns A promise resolving to an SVG XML string.
+ */
+declare function fsl_to_svg_string(fsl: string): Promise<string>;
+/**
+ *  Render a {@link jssm.Machine} to SVG.
+ *
+ *  @param u_jssm The machine to render.
+ *  @returns A promise resolving to an SVG XML string.
+ */
+declare function machine_to_svg_string<T>(u_jssm: jssm.Machine<T>): Promise<string>;
+/**
+ *  Render an FSL string directly to a parsed `SVGSVGElement`.
+ *
+ *  @param fsl The FSL source.
+ *  @returns A promise resolving to a parsed `SVGSVGElement`.
+ *  @throws {JssmError} if no `DOMParser` is available (Node without `configure`).
+ */
+declare function fsl_to_svg_element(fsl: string): Promise<SVGSVGElement>;
+/**
+ *  Render a {@link jssm.Machine} to a parsed `SVGSVGElement`.
+ *
+ *  @param u_jssm The machine to render.
+ *  @returns A promise resolving to a parsed `SVGSVGElement`.
+ *  @throws {JssmError} if no `DOMParser` is available (Node without `configure`).
+ */
+declare function machine_to_svg_element<T>(u_jssm: jssm.Machine<T>): Promise<SVGSVGElement>;
+/**
+ *  Compatibility wrapper for {@link machine_to_dot}, retained from
+ *  jssm-viz.  Will be removed in the next major.
+ *
+ *  @deprecated Use {@link machine_to_dot} instead.
+ */
+declare function dot<T>(machine: jssm.Machine<T>): string;
+export { configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_string, fsl_to_svg_element, machine_to_dot, machine_to_svg_string, machine_to_svg_element, version, build_time };
+/** @internal — test-only access to private helpers. */
+export declare const _test: {
+    color8to6: typeof color8to6;
+    u_color8to6: typeof u_color8to6;
+    vc: typeof vc;
+    node_of: typeof node_of;
+    shape_for_state: typeof shape_for_state;
+    image_for_state: typeof image_for_state;
+    style_for_state: typeof style_for_state;
+};