mfsm 2.0.0 → 3.0.0

package/README.md

@@ -2,12 +2,26 @@
 
 No really, this is probably not for you.
 
-## API
+## Installation
 
-```js
-const fsm = require('mfsm')
-const client = require('something')
-const clientFsm = fsm({
+```bash
+npm install mfsm
+```
+
+**Requirements:**
+- Node.js 22 or higher
+- ESM only (no CommonJS support)
+
+## Usage
+
+### TypeScript
+
+```typescript
+import fsm from 'mfsm'
+import type { FSMDefinition, FSMInstance } from 'mfsm'
+import client from 'something'
+
+const clientFsm: FSMInstance = fsm({
     api: {
         connect: function () {
             this.handle('connect')
@@ -63,7 +77,63 @@ clientFsm.connect()
     .then(() => { console.log("connection established") })
 ```
 
-### Declarative Handle Properties
+### JavaScript (ESM)
+
+```javascript
+import fsm from 'mfsm'
+
+const clientFsm = fsm({
+    api: {
+        connect() {
+            this.handle('connect')
+            return this.after('connected')
+        },
+        disconnect() {
+            this.handle('disconnect')
+            return this.after('disconnected')
+        }
+    },
+    init: {
+        url: process.env.HOST_URL,
+        client: client,
+        default: 'disconnected'
+    },
+    states: {
+        connected: {
+            disconnect() {
+                this.client.disconnect()
+                    .then(() => {
+                        this.handle('disconnect')
+                    })
+            }
+        },
+        connecting: {
+            disconnect: { deferUntil: 'connected' }
+        },
+        disconnecting: {
+            connect: { deferUntil: 'disconnected' }
+        },
+        disconnected: {
+            onEntry: { emit: 'ready', wait: 50 },
+            connect() {
+                this.client.connect(this.url)
+                    .then(() => {
+                        this.next('connected')
+                    })
+                this.next('connecting')
+                this.once('closed', () => {
+                    this.next('disconnected')
+                })
+            }
+        }
+    }
+})
+
+clientFsm.connect()
+    .then(() => { console.log("connection established") })
+```
+
+## Declarative Handle Properties
 
  * `emit` - emits an event from the FSM
  * `next` - transitions FSM to a new state
@@ -71,3 +141,30 @@ clientFsm.connect()
  * `deferUntil` - delays handling the event until after a specific state has occurred
  * `forward` - forwards the event to a new state (after + next)
  * `wait` - amount of time (in ms) to wait before emitting events or transitioning
+
+## Event Patterns
+
+The FSM uses [topic-dispatch](https://github.com/arobson/topic-dispatch) for event handling, which supports AMQP-style wildcard patterns:
+
+```typescript
+// Listen to all events
+machine.on('*', (event, topic) => {
+  console.log(`Event on ${topic}:`, event)
+})
+
+// Pattern matching (see topic-dispatch docs for more patterns)
+machine.on('state.*', handler)  // Match state.connected, state.idle, etc.
+```
+
+## Version 3.0.0 Changes
+
+This is a major rewrite with breaking changes:
+
+- **ESM-only**: No CommonJS support. Use ESM imports (`import`) only.
+- **TypeScript**: Full TypeScript support with complete type definitions.
+- **Node.js 22+**: Minimum Node.js version is now 22.
+- **Modern dependencies**: Updated to latest versions with ESM and TypeScript support.
+  - `fauxdash` ^1.8.6 (ESM + TypeScript)
+  - `topic-dispatch` ^3.0.0 (ESM + TypeScript)
+  - `logging` ^4.2.0 (ESM)
+- **Modern tooling**: Built with TypeScript, tested with Vitest.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { FSMDefinition, FSMInstance } from './types.js';
+export default function (definition: FSMDefinition): FSMInstance;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EAKZ,MAAM,YAAY,CAAA;AAmLnB,MAAM,CAAC,OAAO,WAAW,UAAU,EAAE,aAAa,GAAG,WAAW,CAsB/D"}

package/dist/index.js

@@ -0,0 +1,160 @@
+import _ from 'fauxdash';
+import Dispatch from 'topic-dispatch';
+import logging from 'logging';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const createLogger = logging.default || logging;
+const log = createLogger('fsm');
+function after(topic) {
+    const { promise, resolve } = _.future();
+    this.once(topic, () => resolve());
+    return promise;
+}
+function cleanup() {
+    log.debug(`${this.getContext()} cleaning up all listeners'`);
+    this.removeAllListeners();
+}
+function deferredLog(machine, f, data) {
+    if (f.debug) {
+        log.debug(interpret(machine, f.debug, data));
+    }
+    else if (f.info) {
+        log.info(interpret(machine, f.info, data));
+    }
+    else if (f.warn) {
+        log.warn(interpret(machine, f.warn, data));
+    }
+    else if (f.error) {
+        log.error(interpret(machine, f.error, data));
+    }
+}
+function deferUntil(state, event, data) {
+    log.debug(`${this.getContext()} deferring handling of '${event}' until '${state}'`);
+    return function () {
+        this.once(state, () => {
+            log.debug(`${this.getContext()} handling deferred event, '${event}', on change to state '${state}'`);
+            this.handle(event, data);
+        });
+    }.bind(this);
+}
+function forward(state, event, data) {
+    process.nextTick(() => {
+        this.next(state, data);
+    });
+    return this.deferUntil(state, event, data);
+}
+function getContext() {
+    return `(${this.getIdentifier()}[${this.currentState}])`;
+}
+function getIdentifier() {
+    const id = this.id;
+    const name = this.name;
+    return id || name || 'anonymous';
+}
+function handle(eventName, event) {
+    const current = this.states[this.currentState];
+    const handler = current?.[eventName];
+    log.debug(`${this.getContext()} handling event, '${eventName}'`);
+    if (handler) {
+        try {
+            ;
+            handler(event);
+        }
+        catch (e) {
+            log.error(`${this.getContext()} error occurred handling '${eventName}':\n${e}`);
+        }
+    }
+    else {
+        log.debug(`${this.getContext()} no handler for ${eventName}`);
+    }
+}
+function interpret(machine, logger, data) {
+    if (typeof logger === 'function') {
+        return logger.call(machine, data);
+    }
+    else {
+        return logger;
+    }
+}
+function next(state, data) {
+    log.debug(`${this.getContext()} transitioning to '${state}' from ${this.currentState}`);
+    this.previousState = this.currentState;
+    this.currentState = state;
+    const { promise, resolve, reject } = _.future();
+    process.nextTick(() => {
+        const s = this.states[state];
+        if (s?.onEntry) {
+            log.debug(`${this.getContext()} calling onEntry function`);
+            const result = s.onEntry(data);
+            resolve(result);
+        }
+        else if (!s) {
+            const err = `${this.getContext()} next was called for missing state '${state}'`;
+            log.error(err);
+            reject(new Error(err));
+        }
+        else {
+            resolve();
+        }
+        this.emit(state, data);
+    });
+    return promise;
+}
+function isDeclarative(handler) {
+    return typeof handler !== 'function';
+}
+function buildFromDeclarative(machine, eventName, definition) {
+    return function (data) {
+        const relay = data ?? definition.data;
+        const nextState = definition.next ?? definition.forward;
+        const after = definition.deferUntil ?? definition.forward ?? definition.after;
+        deferredLog(machine, definition, relay);
+        if (after) {
+            machine.once(after, () => {
+                log.debug(`${this.getContext()} replaying event ${eventName} in ${after}`);
+                machine.handle(eventName, relay);
+            });
+        }
+        if (definition.emit) {
+            setTimeout(() => {
+                machine.emit(definition.emit, relay);
+            }, definition.wait ?? 0);
+        }
+        if (nextState) {
+            setTimeout(() => {
+                log.debug(`${this.getContext()} transitioning to ${nextState} on event '${eventName}'`);
+                machine.next(nextState, relay);
+            }, definition.wait ?? 0);
+        }
+    }.bind(machine);
+}
+function bindHandles(machine) {
+    _.each(machine.states, (state, _name) => {
+        _.each(state, (definition, eventName) => {
+            if (!definition || typeof eventName !== 'string')
+                return;
+            if (isDeclarative(definition)) {
+                state[eventName] = buildFromDeclarative(machine, eventName, definition);
+            }
+            else {
+                state[eventName] = definition.bind(machine);
+            }
+        });
+    });
+}
+export default function (definition) {
+    const baseline = {
+        after,
+        cleanup,
+        deferUntil,
+        forward,
+        getContext,
+        getIdentifier,
+        handle,
+        next
+    };
+    const machine = _.melter({}, baseline, _.clone(definition.api ?? {}), _.clone(definition.init), { states: _.clone(definition.states) }, Dispatch());
+    bindHandles(machine);
+    machine.next(machine.default);
+    return machine;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,113 @@
+import type { EventEmitter } from 'events';
+/**
+ * Declarative handler configuration for state events
+ */
+export interface DeclarativeHandler {
+    /** Next state to transition to */
+    next?: string;
+    /** State to defer this event until */
+    deferUntil?: string;
+    /** State to forward to (alias for deferUntil) */
+    forward?: string;
+    /** State to wait for before handling */
+    after?: string;
+    /** Event to emit */
+    emit?: string;
+    /** Delay in milliseconds before executing next/emit */
+    wait?: number;
+    /** Data to pass with the transition/emit */
+    data?: unknown;
+    /** Debug log message (string or function) */
+    debug?: string | ((data: unknown) => string);
+    /** Info log message (string or function) */
+    info?: string | ((data: unknown) => string);
+    /** Warn log message (string or function) */
+    warn?: string | ((data: unknown) => string);
+    /** Error log message (string or function) */
+    error?: string | ((data: unknown) => string);
+}
+/**
+ * Functional handler - bound to FSM instance
+ */
+export type EventHandler = (data?: unknown) => void | Promise<void>;
+/**
+ * Handler can be either declarative config or functional
+ */
+export type StateHandler = DeclarativeHandler | EventHandler;
+/**
+ * State configuration - maps event names to handlers
+ */
+export interface StateConfig {
+    /** Special handler called when entering this state */
+    onEntry?: StateHandler;
+    /** Event handlers for this state */
+    [eventName: string]: StateHandler | undefined;
+}
+/**
+ * Collection of all states in the FSM
+ */
+export interface FSMStates {
+    [stateName: string]: StateConfig;
+}
+/**
+ * Custom API methods added to the FSM instance
+ */
+export interface FSMApi {
+    [methodName: string]: (this: FSMInstance, ...args: unknown[]) => unknown;
+}
+/**
+ * Initialization configuration
+ */
+export interface FSMInit {
+    /** Default/initial state name */
+    default: string;
+    /** Optional identifier for logging */
+    id?: string;
+    /** Optional name for logging */
+    name?: string;
+    /** Additional initialization properties */
+    [key: string]: unknown;
+}
+/**
+ * FSM definition passed to the factory function
+ */
+export interface FSMDefinition {
+    /** State definitions */
+    states: FSMStates;
+    /** Initialization config */
+    init: FSMInit;
+    /** Custom API methods */
+    api?: FSMApi;
+}
+/**
+ * Base FSM instance methods
+ */
+export interface FSMBaseMethods {
+    /** Wait for a state to be entered, returns a promise */
+    after(topic: string): Promise<void>;
+    /** Clean up all event listeners */
+    cleanup(): void;
+    /** Defer handling an event until a specific state is reached */
+    deferUntil(state: string, event: string, data?: unknown): () => void;
+    /** Forward to a state and defer event handling */
+    forward(state: string, event: string, data?: unknown): () => void;
+    /** Get context string for logging */
+    getContext(): string;
+    /** Get identifier for this FSM instance */
+    getIdentifier(): string;
+    /** Handle an event in the current state */
+    handle(eventName: string, event?: unknown): void;
+    /** Transition to a new state */
+    next(state: string, data?: unknown): Promise<void>;
+    /** Current state name */
+    currentState: string;
+    /** Previous state name */
+    previousState?: string;
+    /** State definitions */
+    states: FSMStates;
+}
+/**
+ * FSM instance combines base methods, custom API, init properties, and EventEmitter
+ */
+export type FSMInstance = FSMBaseMethods & EventEmitter & Record<string, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,40 +1,54 @@
 {
   "name": "mfsm",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "my finite state machine. not yours. don't use it.",
-  "main": "src/index.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "./node_modules/mocha/bin/mocha ./spec/**/*.spec.js",
-    "release": "standard-version"
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",
     "url": "github.com/deftly/mfsm"
   },
   "keywords": [
-    "fsm"
+    "fsm",
+    "finite state machine",
+    "typescript"
   ],
   "author": "Alex Robson",
   "license": "MIT",
   "dependencies": {
-    "fauxdash": "^1.7.0",
-    "logging": "^3.3.0",
-    "topic-dispatch": "^2.0.0"
+    "fauxdash": "^1.8.6",
+    "logging": "^4.2.0",
+    "topic-dispatch": "^3.0.0"
   },
   "devDependencies": {
-    "chai": "^4.2.0",
-    "chai-as-promised": "^7.1.1",
-    "mocha": "^8.2.1",
-    "mocha-lcov-reporter": "^1.3.0",
-    "nyc": "^15.1.0",
-    "standard": "^16.0.3",
-    "standard-version": "^9.1.0"
-  },
-  "standard": {
-    "env": [
-      "mocha",
-      "_",
-      "should"
-    ]
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "eslint": "^9.18.0",
+    "globals": "^17.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }

package/CHANGELOG.md

@@ -1,86 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
-
-## [1.6.0](///compare/v1.5.0...v1.6.0) (2021-04-06)
-
-
-### Features
-
-* add forward as an API call ([8621479](///commit/86214793b77e6330368bb37774eed93a388b004b))
-
-## [1.5.0](///compare/v1.4.0...v1.5.0) (2021-03-12)
-
-
-### Features
-
-* improve declarative handling by removing mutual exclusions ([323c37f](///commit/323c37f98597ba289f0640bd8c73bc8151f9333c))
-
-
-### Bug Fixes
-
-* bump topic-dispatch dependency to 1.3.1 ([b9fe650](///commit/b9fe650fac3fb8bbf6ae254ecff6cbabd81bbfcd))
-
-## [1.4.0](///compare/v1.3.3...v1.4.0) (2021-02-27)
-
-
-### Features
-
-* improve declarative ability by adding forwarding and deferred logs ([fbe4137](///commit/fbe41370452b0db6601408704554d55cd1d17264))
-
-### [1.3.3](///compare/v1.3.1...v1.3.3) (2021-02-24)
-
-
-### Bug Fixes
-
-* add debug level logging to assist with troubleshooting state transitions ([eddc5e3](///commit/eddc5e34e59d6dc7302370820b29e92f3595b1d0))
-* improve debug messages by including state. fix broken pass through of event between states ([ec876e4](///commit/ec876e4ec9267c55bc9f18bb38dfb1c0bd950dd7))
-
-### [1.3.2](///compare/v1.3.1...v1.3.2) (2021-02-22)
-
-
-### Bug Fixes
-
-* add debug level logging to assist with troubleshooting state transitions ([eddc5e3](///commit/eddc5e34e59d6dc7302370820b29e92f3595b1d0))
-
-### [1.3.1](///compare/v1.3.0...v1.3.1) (2021-02-22)
-
-
-### Bug Fixes
-
-* log error when next is called for a non-existent state ([48052c6](///commit/48052c6d6eb42a56b0432f3141e29050878336ec))
-
-## [1.3.0](///compare/v1.2.0...v1.3.0) (2021-02-22)
-
-
-### Features
-
-* support handling events by transitioning to a new state with declarative ([d1fe8b5](///commit/d1fe8b5edc2ada6a47771b39b26609bd25b7af00))
-
-## [1.2.0](///compare/v1.1.2...v1.2.0) (2021-01-27)
-
-
-### Features
-
-* update API to work with topic-dispatch 1.2.0 ([e7a5a6a](///commit/e7a5a6a8d226c082b06c5f7f82682c28e1e2bb2c))
-
-### [1.1.2](///compare/v1.1.1...v1.1.2) (2021-01-24)
-
-
-### Bug Fixes
-
-* bump topic dispatch to v 1.1.4 ([f626366](///commit/f626366aa67b6084f2ca8fce6ce18ad908160dcf))
-
-### [1.1.1](///compare/v1.1.0...v1.1.1) (2021-01-24)
-
-
-### Bug Fixes
-
-* bump topic dispatch to v 1.1.3 ([1a2bf5e](///commit/1a2bf5eed86a5a940c355f160d7088745d99926f))
-
-## [1.1.0](///compare/v1.0.0...v1.1.0) (2021-01-22)
-
-
-### Features
-
-* add entry handler and allow for dispatch handlers to be defined declaritively ([63f554f](///commit/63f554f4799fca89a3d3b635137d5a4dfceb2496))

package/CODE_OF_CONDUCT.md

@@ -1,46 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at asrobson@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/

package/src/index.js

@@ -1,156 +0,0 @@
-const _ = require('fauxdash')
-const Dispatch = require('topic-dispatch')
-const createLogger = require('logging').default
-const log = createLogger('fsm')
-
-function after (topic) {
-    var { promise, resolve } = _.future()
-    this.once(topic, () => resolve())
-    return promise
-}
-
-function cleanup () {
-    log.debug(`${this.getContext()} cleaning up all listeners'`)
-    this.removeAllListeners()
-}
-
-function deferredLog(machine, f, data) {
-  if (f.debug) {
-    log.debug(interpret(machine, f.debug, data))
-  } else if (f.info){
-    log.info(interpret(machine, f.info, data))
-  } else if (f.warn){
-    log.warn(interpret(machine, f.warn, data))
-  } else if (f.error){
-    log.error(interpret(machine, f.error, data))
-  }
-}
-
-function deferUntil(state, event, data) {
-    log.debug(`${this.getContext()} deferring handling of '${event}' until '${state}'`)
-    return function () {
-        this.once(state, () => {
-            log.debug(`${this.getContext()} handling deferred event, '${event}', on change to state '${state}'`)
-            this.handle(event, data)
-        })
-    }.bind(this)
-}
-
-function forward(state, event, data) {
-  process.nextTick(() => {
-    this.next(state, data)
-  })
-  return this.deferUntil(state, event, data)
-}
-
-function getContext() {
-  return `(${this.getIdentifier()}[${this.currentState}])`
-}
-
-function getIdentifier() {
-    return this.id || this.name || 'anonymous'
-}
-
-function handle (eventName, event) {
-    var current = this.states[this.currentState]
-    var handler = current[eventName]
-    log.debug(`${this.getContext()} handling event, '${eventName}'`)
-    if (handler) {
-        try {
-            handler(event)
-        } catch (e) {
-            log.error(`${this.getContext()} error occurred handling '${eventName}':\n${e}`)
-        }
-    } else {
-        log.debug(`${this.getContext()} no handler for ${eventName}`)
-    }
-}
-
-function interpret(machine, logger, data) {
-  if (typeof logger == 'function') {
-    return logger.call(machine, data)
-  } else {
-    return logger
-  }
-}
-
-function next (state, data) {
-  log.debug(`${this.getContext()} transitioning to '${state}' from ${this.currentState}`)
-  this.previousState = this.currentState
-  this.currentState = state
-  const { promise, resolve, reject } = _.future()
-  process.nextTick(() => {
-      const s = this.states[state]
-      if (s && s.onEntry) {
-          log.debug(`${this.getContext()} calling onEntry function`)
-          resolve(s.onEntry(data))
-      } else if (!s) {
-          const err = `${this.getContext()} next was called for missing state '${state}'`
-          log.error(err)
-          reject(new Error(err))
-      }
-      this.emit(state, data)
-  })
-  return promise
-}
-
-function buildFromDeclarative (machine, eventName, definition) {
-    return function (data) {
-        const relay = data || definition.data
-        const next = definition.next || definition.forward
-        const after = definition.deferUntil || definition.forward || definition.after
-        deferredLog(machine, definition, relay)
-        if (after) {
-            machine.once(after, () => {
-              log.debug(`${this.getContext()} replaying event ${eventName} in ${after}`)
-              machine.handle(eventName, relay)
-            })
-        }
-        if (definition.emit) {
-            setTimeout(() => {
-                machine.emit(definition.emit, relay)
-            }, definition.wait || 0)
-        }
-        if (next) {
-            setTimeout(() => {
-                log.debug(`${this.getContext()} transitioning to ${next} on event '${eventName}'`)
-                machine.next(next, relay)
-            }, definition.wait || 0)
-        }
-    }.bind(machine)
-}
-
-function bindHandles (machine) {
-    _.each(machine.states, (state, name) => {
-        _.each(state, (definition, eventName) => {
-            if (typeof definition === 'function') {
-                state[eventName] = definition.bind(machine)
-            } else {
-                state[eventName] = buildFromDeclarative(machine, eventName, definition)
-            }
-        })
-    })
-}
-
-module.exports = function (definition) {
-    const baseline = {
-        after,
-        cleanup,
-        deferUntil,
-        forward,
-        getContext,
-        getIdentifier,
-        handle,
-        next
-    }
-    var machine = _.melter({},
-        baseline,
-        _.clone(definition.api),
-        _.clone(definition.init),
-        {states: _.clone(definition.states)},
-        Dispatch()
-    )
-    bindHandles(machine)
-    machine.next(machine.default)
-    return machine
-}