Adding docs to action creators

src/StateNode.ts

@@ -1508,6 +1508,7 @@ class StateNode<
     // Case when state node is compound but no initial state is defined
     if (this.type === 'compound' && !this.initial) {
       if (!IS_PRODUCTION) {
+        // tslint:disable-next-line:no-console
         console.warn(`Compound state node '${this.id}' has no initial state.`);
       }
       return [this];

src/actions.ts

@@ -119,6 +119,12 @@ export const toActionObjects = <TContext>(
   return actions.map(subAction => toActionObject(subAction, actionFunctionMap));
 };
 
+/**
+ * Raises an event. This places the event in the internal event queue, so that
+ * the event is immediately consumed by the machine in the current step.
+ *
+ * @param eventType The event to raise.
+ */
 export function raise<TContext, TEvents extends EventObject>(
   eventType: TEvents['type']
 ): RaiseEvent<TContext, TEvents> {
@@ -128,6 +134,16 @@ export function raise<TContext, TEvents extends EventObject>(
   };
 }
 
+/**
+ * Sends an event. This returns an action that will be read by an interpreter to
+ * send the event in the next step, after the current step is finished executing.
+ *
+ * @param event The event to send.
+ * @param options Options to pass into the send event:
+ *  - `id` - The unique send event identifier (used with `cancel()`).
+ *  - `delay` - The number of milliseconds to delay the sending of the event.
+ *  - `target` - The target of this event (by default, the machine the event was sent from).
+ */
 export function send<TContext, TEvents extends EventObject>(
   event: Event<TEvents>,
   options?: SendActionOptions
@@ -144,6 +160,12 @@ export function send<TContext, TEvents extends EventObject>(
   };
 }
 
+/**
+ * Sends an event to this machine's parent machine.
+ *
+ * @param event The event to send to the parent machine.
+ * @param options Options to pass into the send event.
+ */
 export function sendParent<TContext, TEvents extends EventObject>(
   event: Event<TEvents>,
   options?: SendActionOptions
@@ -154,8 +176,16 @@ export function sendParent<TContext, TEvents extends EventObject>(
   });
 }
 
+/**
+ *
+ * @param expr The expression function to evaluate which will be logged.
+ *  Takes in 2 arguments:
+ *  - `ctx` - the current state context
+ *  - `event` - the event that caused this action to be executed.
+ * @param label The label to give to the logged expression.
+ */
 export function log<TContext, TEvents extends EventObject>(
-  expr: (ctx: TContext, event: TEvents) => void,
+  expr: (ctx: TContext, event: TEvents) => any,
   label?: string
 ) {
   return {
@@ -165,13 +195,25 @@ export function log<TContext, TEvents extends EventObject>(
   };
 }
 
+/**
+ * Cancels an in-flight `send(...)` action. A canceled sent action will not
+ * be executed, nor will its event be sent, unless it has already been sent
+ * (e.g., if `cancel(...)` is called after the `send(...)` action's `delay`).
+ *
+ * @param sendId The `id` of the `send(...)` action to cancel.
+ */
 export const cancel = (sendId: string | number): CancelAction => {
   return {
     type: actionTypes.cancel,
     sendId
   };
 };
 
+/**
+ * Starts an activity.
+ *
+ * @param activity The activity to start.
+ */
 export function start<TContext>(
   activity: string | ActivityDefinition<TContext>
 ): ActivityActionObject<TContext> {
@@ -184,6 +226,11 @@ export function start<TContext>(
   };
 }
 
+/**
+ * Stops an activity.
+ *
+ * @param activity The activity to stop.
+ */
 export function stop<TContext>(
   activity: string | ActivityDefinition<TContext>
 ): ActivityActionObject<TContext> {
@@ -196,6 +243,11 @@ export function stop<TContext>(
   };
 }
 
+/**
+ * Updates the current context of the machine.
+ *
+ * @param assignment An object that represents the partial context to update.
+ */
 export const assign = <TContext, TEvents extends EventObject = EventObject>(
   assignment: Assigner<TContext, TEvents> | PropertyAssigner<TContext, TEvents>
 ): AssignAction<TContext, TEvents> => {
@@ -211,15 +263,37 @@ export function isActionObject<TContext>(
   return typeof action === 'object' && 'type' in action;
 }
 
+/**
+ * Returns an event type that represents an implicit event that
+ * is sent after the specified `delay`.
+ *
+ * @param delay The delay in milliseconds
+ * @param id The state node ID where this event is handled
+ */
 export function after(delay: number, id?: string) {
   const idSuffix = id ? `#${id}` : '';
   return `${ActionTypes.After}(${delay})${idSuffix}`;
 }
 
+/**
+ * Returns an event type that represents that a final state node
+ * has been entered.
+ *
+ * @param id The final state node ID
+ */
 export function done(id: string) {
   return `${ActionTypes.DoneState}.${id}`;
 }
 
+/**
+ * Invokes (spawns) a child service, as a separate interpreted machine.
+ *
+ * @param invokeConfig The string service to invoke, or a config object:
+ *  - `src` - The source (URL) of the machine definition to invoke
+ *  - `forward` - Whether events sent to this machine are sent (forwarded) to the
+ *    invoked machine.
+ * @param options
+ */
 export function invoke<TContext>(
   invokeConfig: string | Invocation<TContext>,
   options?: Partial<Invocation<TContext>>

src/index.ts

@@ -3,7 +3,33 @@ import { mapState } from './mapState';
 import { StateNode } from './StateNode';
 import { State } from './State';
 import { Machine } from './Machine';
-import * as actions from './actions';
+import {
+  raise,
+  send,
+  sendParent,
+  log,
+  cancel,
+  start,
+  stop,
+  assign,
+  after,
+  done,
+  invoke
+} from './actions';
+
+const actions = {
+  raise,
+  send,
+  sendParent,
+  log,
+  cancel,
+  start,
+  stop,
+  assign,
+  after,
+  done,
+  invoke
+};
 
 export { Machine, StateNode, State, matchesState, mapState, actions };
 

src/types.ts

@@ -420,8 +420,8 @@ export enum SpecialTargets {
 }
 
 export interface SendActionOptions {
-  delay?: number;
   id?: string | number;
+  delay?: number;
   target?: string;
 }