jssm 5.104.2 → 5.112.4

package/dist/deno/jssm_util.d.ts

@@ -0,0 +1,258 @@
+/*******
+ *
+ *  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`.
+ *
+ */
+declare function arr_uniq_p<T>(el: T, i: number, source: T[]): boolean;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const array_box_if_string: (n: any) => any;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const weighted_rand_select: Function;
+/*******
+ *
+ *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
+ *
+ *  ```typescript
+ *  import { seq } from './jssm';
+ *
+ *  seq(5);  // [0, 1, 2, 3, 4]
+ *  seq(0);  // []
+ *  ```
+ *
+ */
+declare function seq(n: number): number[];
+/*******
+ *
+ *  Returns the histograph of an array as a `Map`.  Makes no attempt to cope
+ *  with deep equality; will fail for complex contents, as such.
+ *
+ *  ```typescript
+ *  import { histograph } from './jssm';
+ *
+ *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
+ *  ```
+ *
+ */
+declare const histograph: Function;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const weighted_sample_select: Function;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const weighted_histo_key: Function;
+/*******
+ *
+ *  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.
+ *
+ */
+declare function name_bind_prop_and_state(prop: string, state: string): string;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const hook_name: (from: string, to: string) => string;
+/*******
+ *
+ *  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.
+ *
+ */
+declare const named_hook_name: (from: string, to: string, action: string) => string;
+/*******
+ *
+ *  Creates a SplitMix32 random generator.  Used by the randomness test suite.
+ *
+ *  Sourced from `bryc`: https://github.com/bryc/code/blob/master/jshash/PRNGs.md#splitmix32
+ *
+ *  Replaces the Mulberry generator, which was found to have problems
+ *
+ */
+declare function gen_splitmix32(a?: number | undefined): () => number;
+/*******
+ *
+ *  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][];
+/*******
+ *
+ *  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.
+ *
+ */
+declare function sleep(ms: number): Promise<unknown>;
+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, gen_splitmix32, sleep };

package/dist/deno/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;
+};

package/dist/deno/jssm_viz_colors.d.ts

@@ -0,0 +1,63 @@
+/**
+ *  Default color palette for jssm/viz dot/svg output.  Used by the graphviz
+ *  rendering helpers in jssm_viz.ts to colorize nodes and edges based on
+ *  state type (terminal/final/complete/normal) and arrow kind
+ *  (legal/main/forced).
+ *
+ *  Keys are flat strings of the form `<arrow_kind>_<modifier>_<position>`
+ *  (e.g. `legal_final_solo`, `main_terminal_2`); also the special node fill
+ *  colors (`fill_final`, `fill_terminal`, `fill_complete`) and the graph
+ *  background.
+ */
+declare const default_viz_colors: {
+    graph_bg_color: string;
+    fill_final: string;
+    fill_terminal: string;
+    fill_complete: string;
+    legal_1: string;
+    legal_2: string;
+    legal_solo: string;
+    legal_final_1: string;
+    legal_final_2: string;
+    legal_final_solo: string;
+    legal_terminal_1: string;
+    legal_terminal_2: string;
+    legal_terminal_solo: string;
+    legal_complete_1: string;
+    legal_complete_2: string;
+    legal_complete_solo: string;
+    main_1: string;
+    main_2: string;
+    main_solo: string;
+    main_final_1: string;
+    main_final_2: string;
+    main_final_solo: string;
+    main_terminal_1: string;
+    main_terminal_2: string;
+    main_terminal_solo: string;
+    main_complete_1: string;
+    main_complete_2: string;
+    main_complete_solo: string;
+    forced_1: string;
+    forced_2: string;
+    forced_solo: string;
+    forced_final_1: string;
+    forced_final_2: string;
+    forced_final_solo: string;
+    forced_terminal_1: string;
+    forced_terminal_2: string;
+    forced_terminal_solo: string;
+    forced_complete_1: string;
+    forced_complete_2: string;
+    forced_complete_solo: string;
+    text_final_1: string;
+    text_final_2: string;
+    text_final_solo: string;
+    text_terminal_1: string;
+    text_terminal_2: string;
+    text_terminal_solo: string;
+    text_complete_1: string;
+    text_complete_2: string;
+    text_complete_solo: string;
+};
+export { default_viz_colors };