WAIT — Slowing — last commit 11mo ago

• Last commit 11mo ago
• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 11mo ago
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

A lightweight JavaScript finite state machine (FSM) library that lets developers define states, transitions, and lifecycle event handlers to model complex stateful behavior (v3.1.0). It generates transition methods, validates allowed state changes, and fires observer callbacks during state lifecycle phases—no external dependencies, works in browsers and Node.js. Simple structure: lib/state-machine.js is the core engine (main entry point in package.json), lib/history.js extends it with state history tracking. Examples/ folder contains 5 runnable FSM demonstrations (atm.js, wizard.js, door.js, matter.js, demo/). Docs/ folder has 9 markdown guides covering lifecycle events, async transitions, initialization patterns. Dist/ holds pre-built browser bundles and minified versions.

JavaScript developers building interactive systems with complex state flows: form wizards, ATM interfaces, door lock mechanisms, game engines, or async workflows. Users need to model discrete state sequences with validation and side effects without heavy frameworks.

Production-ready and actively maintained. Version 3.0+ is a significant rewrite (see docs/upgrading-from-v2.md), indicating ongoing evolution. Published on npm, has CI via Travis CI (.travis.yml present), minified dist bundles (dist/state-machine.min.js), and test infrastructure (ava + nyc). No recent commit date visible in metadata, but structured releases and documentation signal stable maturity.

Low risk: zero runtime dependencies (only dev tools: webpack, uglify-js, ava for testing). Single maintainer (Jake Gordon) could be a bus factor concern. Version 3.x introduced breaking changes from v2.x, so users must read docs/upgrading-from-v2.md. Small issue surface (no visible backlog data), but check GitHub issues before upgrading production code.

No recent visible activity in metadata provided, but the project maintains structured releases (v3.1.0 current) and comprehensive documentation. Build pipeline (webpack + minify scripts) suggests active maintenance. Check GitHub's Issues and Releases tabs for current work; the codebase appears stable rather than rapidly evolving.

git clone https://github.com/jakesgordon/javascript-state-machine.git && cd javascript-state-machine && npm install && npm test

Daily commands: npm test (runs ava test suite with --watch flag available). npm run build (webpack bundle + minify). npm start aliases npm run watch (ava --watch). npm run bundle (webpack only) or npm run minify (bin/minify script only).

• src/jsm.js — Core state machine implementation—contains the main FSM class, transition logic, and lifecycle event system that all other features depend on.
• lib/state-machine.js — Compiled entry point exported to npm and browser—this is what users import; must understand how src/jsm.js gets built here.
• src/plugin.js — Plugin architecture foundation—defines how history and visualization plugins attach to the FSM, critical for extending behavior.
• src/plugin/history.js — State history tracking plugin—shows the pattern for augmenting FSM with stateful features; useful reference for custom plugins.
• webpack.config.js — Build configuration that transforms src/ into dist/ and lib/—necessary to understand the build-to-distribution pipeline.
• test/basics.js — Foundational test suite covering FSM construction, transitions, and state queries—establishes expected behavior contracts.

Add a new state machine example

1. Create a new .js file in examples/ that exports a StateMachine instance with your states and transitions (examples/my-workflow.js)
2. Create a corresponding .dot file describing the state diagram in GraphViz format (examples/my-workflow.dot)
3. Add example to examples/demo/demo.js to make it selectable in the interactive demo (examples/demo/demo.js)
4. Document the example with a markdown file in docs/ describing states, transitions, and use case (docs/my-workflow-example.md)

Create a custom FSM plugin

1. Create a new plugin file following the pattern in src/plugin/history.js with init(), onEnter(), onLeave(), and onTransition() hooks (src/plugin/my-feature.js)
2. Export the plugin from src/config.js in the PLUGINS map so it can be registered during FSM construction (src/config.js)
3. Add tests in test/plugin/my-feature.js covering plugin initialization and event handling (test/plugin/my-feature.js)
4. Document the plugin API in docs/ with configuration options and examples (docs/my-plugin.md)

Add a new lifecycle event or transition hook

1. Define the new event name constant in src/config.js (src/config.js)
2. Call fsm.emit() at the appropriate point in src/jsm.js transition logic (e.g., in the _transition method) (src/jsm.js)
3. Add test cases in test/lifecycle.js verifying the event fires with correct arguments and timing (test/lifecycle.js)
4. Document the new event in docs/lifecycle-events.md with timing diagram and callback signature (docs/lifecycle-events.md)

Add error handling for a new failure scenario

1. Define a new exception in src/util/exception.js extending the base FSM exception class (src/util/exception.js)
2. Throw the exception at the validation point in src/jsm.js (e.g., invalid state check, disallowed transition) (src/jsm.js)
3. Add test in test/errors.js verifying the exception is thrown with correct message and type (test/errors.js)
4. Document the error in docs/error-handling.md with example catch block and recovery patterns (docs/error-handling.md)

• Webpack — Bundles ES6 source code (src/) into CommonJS (lib/) and browser-ready UMD distributions (dist/); enables ES6 modules in source while maintaining backward compatibility
• AVA test runner — Modern test framework supporting concurrent test execution and async/await syntax; chosen for fast iteration on a library with many promise-based async tests
• GraphViz (.dot format) — Industry-standard format for state diagram visualization; the visualize plugin generates .dot files that can be rendered to PNG/SVG for documentation
• Event Emitter pattern — Decouples state transitions from side effects; enables plugins and user callbacks to hook into lifecycle without core FSM knowing about them

• Plugin system over built-in history/visualization

  • Why: Keeps core FSM lightweight and simple; users only pay for features they use
  • Consequence: More boilerplate to opt into features; slightly more complex API surface

• Fluent/chainable transition API (fsm.melt(), fsm.freeze()) over explicit transition(name) method

  • Why: More ergonomic and readable; matches user mental model of state machine verbs
  • Consequence: Requires dynamic method generation and camelCase name mangling; can hide invalid transitions until runtime

• Promise-based async transitions over callbacks

  • Why: Modern, composable async pattern; integrates well with async/await
  • Consequence: Requires ES6 Promise support; older browsers need polyfill

• Immutable state (no direct state mutation) with getters only

  • Why: Prevents accidental state corruption; forces transitions through fsm.melt() etc. for audit trail
  • Consequence: Users cannot inspect internal FSM object; slight runtime overhead for encapsulation

• Real-time multi-machine synchronization or networked state
• Hierarchical/nested states (no substates within states)
• Concurrent states (orthogonal regions) in a single FSM instance
• State memory/history replay beyond what the history plugin tracks
• Server-side session management or persistence (library provides no storage integration)

Version 3.0+ is a breaking rewrite; check docs/upgrading-from-v2.md before using v3.x if inheriting v2.x code. History and visualization are separate dist bundles (dist/state-machine-history.min.js, dist/state-machine-visualize.min.js); you must choose the right bundle based on features needed. The library itself has zero dependencies, but build scripts require Node.js toolchain (webpack, ava, nyc); ensure Node >= 4.x. No environment variables or service dependencies.

• Finite State Machine (FSM) — The entire library is built on FSM theory; understanding states as discrete, transitions as rules, and event handlers as side effects is foundational to using this correctly.
• Lifecycle Callbacks / Observer Pattern — The library's power comes from onBefore/onAfter/onLeave/onEnter hooks that fire during transitions; mastering callback order and error handling in each phase is critical.
• Async Transitions / Deferral — Modern apps need async state changes (API calls, timers); this library supports returning promises from onBefore callbacks to defer transitions—essential for real-world workflows.
• State History / Time Travel — lib/history.js enables undo/redo patterns and debugging; understanding how state branches and how to navigate history is useful for undo-heavy UIs.
• GraphViz Visualization — The visualize.js extension generates .dot files to render FSMs as diagrams (examples/matter.png); critical for communicating complex state flows to teams.
• Method Generation via Metaprogramming — The library dynamically creates fsm.melt(), fsm.freeze() etc. from the transitions array; understanding this reduces confusion about where those methods come from.
• UMD (Universal Module Definition) — dist/ bundles use UMD to support browser globals, CommonJS (Node.js), and ES6 modules; relevant when bundling or choosing import style.

• davidkpiano/xstate — Modern, actively developed FSM alternative with similar goals but more complex API; good comparison for understanding this library's minimalism.
• daaku/fsm — Alternative lightweight JavaScript FSM; contrasts design philosophy with jakesgordon's approach.
• MunGell/state-machine — Another FSM library in the JavaScript ecosystem; useful for benchmarking feature completeness and API patterns.
• getgauge/gauge.js — Uses state machines internally for test automation workflows; example of FSM applied to BDD tooling.
• visualstudio/TypeScript — Type definitions for this FSM library exist in DefinitelyTyped; relevant if adding TypeScript support or type safety.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for async transitions and error handling

The test directory has basic test files (basics.js, construction.js, defaults.js, empty.js) but is missing dedicated test suites for async-transitions.md and error-handling.md documented features. These are core features with complex state management that warrant thorough unit tests to catch edge cases and regressions.

• [ ] Create test/async-transitions.js with tests for promise-based transitions, timeout handling, and cancellation
• [ ] Create test/error-handling.js with tests for invalid transitions, exception callbacks, and error recovery
• [ ] Run nyc coverage report to verify both test files achieve >90% coverage of src/jsm.js and src/app.js
• [ ] Update package.json test script output to confirm all new tests pass

Add GitHub Actions CI workflow to replace Travis CI

.travis.yml indicates the repo uses outdated Travis CI. GitHub Actions is now the standard for GitHub-hosted projects, provides better integration, and doesn't require external service configuration. This modernizes the CI/CD pipeline and makes it easier for contributors to understand the build process.

• [ ] Create .github/workflows/test.yml with Node.js matrix testing (v12, v14, v16, v18)
• [ ] Configure workflow to run 'npm test' and upload nyc coverage reports
• [ ] Configure workflow to run 'npm run build' to verify dist/ artifacts are generated correctly
• [ ] Remove or archive .travis.yml and update README.md badge to reference GitHub Actions instead

Add integration tests for history and visualization plugins

The dist/ directory contains compiled plugin files (state-machine-history.js, state-machine-visualize.js) and docs/state-history.md and docs/visualization.md describe their usage, but there are no dedicated test files for these plugins. The current test suite doesn't verify plugin loading, integration with the core state machine, or their specific APIs.

• [ ] Create test/history.js with tests for state history tracking, restore functionality, and memory management
• [ ] Create test/visualization.js with tests for .dot file generation, graph output validation, and edge case handling
• [ ] Verify both plugins are required/imported correctly and interact properly with the main StateMachine instance
• [ ] Run full test suite with nyc to ensure plugin code paths are covered

• Add unit tests for lib/history.js state tracking and replay functions; test files exist but coverage for edge cases (branching history, reset behavior) appears incomplete.
• Write a new example in examples/ demonstrating async transition patterns with promises (docs/async-transitions.md exists but no runnable .js example showing retry logic or timeout handling).
• Expand docs/error-handling.md with concrete code snippets for each callback phase; currently sparse on try-catch patterns for onBefore rejection flows.

This JavaScript state machine library has moderate security concerns, primarily centered on significantly outdated development dependencies (dating to 2016-2017) that contain known vulnerabilities. While the library itself is focused on state management without direct injection vectors, the build toolchain relies on unmaintained packages like uglify-js and webpack 2 RC. The project should prioritize dependency updates and implement a robust supply chain security process for the dist/ artifacts that are distributed to end users. No critical code-level vulnerabilities were identified in the library logic itself, but the infrastructure and tooling require immediate attention.

• High · Outdated Development Dependencies with Known Vulnerabilities — package.json - devDependencies. The project uses significantly outdated dependencies including ava@0.17.0 (released 2016), uglify-js@2.7.5 (end-of-life), webpack@2.2.0-rc1 (pre-release from 2017), and nyc@10.0.0. These versions contain known security vulnerabilities and lack security patches. Webpack 2 RC1 is particularly concerning as it was never finalized for production use. Fix: Update all dependencies to current stable versions: ava to latest (v5+), uglify-js to latest or migrate to terser, webpack to v5 or later, and nyc to v15+. Run 'npm audit' and 'npm audit fix' to identify and remediate vulnerabilities.
• Medium · Missing package-lock.json Integrity Verification — package.json - minify script, bin/minify. While package-lock.json exists, the presence of outdated dependencies suggests it may not be regularly updated or verified. The minification build script uses uglify-js which has been unmaintained since 2019 and contains known vulnerabilities. Fix: Migrate from uglify-js to terser (actively maintained). Regularly audit dependencies using 'npm audit'. Consider using lock file verification in CI/CD pipelines.
• Medium · Potential Unrestricted Build Artifact Generation — dist/ directory, webpack.config.js, bin/minify. The build process generates minified and bundled JavaScript files that are committed to the dist/ directory. Without strict controls, this could lead to inclusion of unvetted code or supply chain attacks if the build process is compromised. Fix: Implement strict code review for all dist/ artifacts before committing. Consider generating dist/ files only during release with signed commits. Verify built artifacts against source code in CI/CD.
• Low · No Security Headers or Content Security Policy Configuration — examples/demo/, index.html. The demo application (examples/demo/) lacks security headers configuration. If deployed, it could be vulnerable to XSS, clickjacking, and other client-side attacks. Fix: If serving the demo application, implement CSP headers, X-Frame-Options, X-Content-Type-Options headers. Review examples/demo/demo.js for potential XSS vulnerabilities when handling user input.
• Low · Missing Input Validation in Example Code — examples/ directory (atm.js, wizard.js, etc.). Example files (examples/*.js) may not demonstrate secure coding practices for input validation, which could mislead users about proper security implementation when using this library. Fix: Review and document security best practices in example code. Add comments about input validation requirements when this library is used in applications that process untrusted input.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jakesgordon/javascript-state-machine shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jakesgordon/javascript-state-machine repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jakesgordon/javascript-state-machine.

What it runs against: a local clone of jakesgordon/javascript-state-machine — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jakesgordon/javascript-state-machine | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 374 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jakesgordon/javascript-state-machine. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jakesgordon/javascript-state-machine.git
#   cd javascript-state-machine
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jakesgordon/javascript-state-machine and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jakesgordon/javascript-state-machine(\\.git)?\\b" \\
  && ok "origin remote is jakesgordon/javascript-state-machine" \\
  || miss "origin remote is not jakesgordon/javascript-state-machine (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/jsm.js" \\
  && ok "src/jsm.js" \\
  || miss "missing critical file: src/jsm.js"
test -f "lib/state-machine.js" \\
  && ok "lib/state-machine.js" \\
  || miss "missing critical file: lib/state-machine.js"
test -f "src/plugin.js" \\
  && ok "src/plugin.js" \\
  || miss "missing critical file: src/plugin.js"
test -f "src/plugin/history.js" \\
  && ok "src/plugin/history.js" \\
  || miss "missing critical file: src/plugin/history.js"
test -f "webpack.config.js" \\
  && ok "webpack.config.js" \\
  || miss "missing critical file: webpack.config.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 374 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~344d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jakesgordon/javascript-state-machine"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.