reductive-dev-tools

reductive-dev-tools

reductive and reason-react reducer component integration with redux-devtools-extension

Installation

1. with npm:

npm install --save-dev reductive-dev-tools

1. add reductive-dev-tools to your "bs-dependencies" inside bsconfig.json.
2. add -bs-g into "bsc-flags" of your bsconfig.json to have variant and record field names available inside extension.

Peer depedencies
reason-react, reductive, redux-devtools-extension, redux (redux-devtools-extension's peer dep.) should be also installed.

Usage

Utilize provided store enhancer ReductiveDevTools.Connectors.enhancer for reductive or ReductiveDevTools.Connectors.useReducer for reason-react hooks (jsx3).

You need to pass devtools extension options as ~options and action creator that builds action when state update is dispatched from the monitor as ~devToolsUpdateActionCreator. Additionally you can also pass ~stateSerializer and ~actionSerializer to override default serialization behaviour. Take a look at Serialization to see if you need it.

reductive

let storeCreator = 
  ReductiveDevTools.Connectors.enhancer(
    ~options=ReductiveDevTools.Extension.enhancerOptions(
      ~name=__MODULE__, 
      ~actionCreators={
        "actionYouCanDispatchFromMonitor": (value: int) => `YourActionOfChoice(value)
          |. ReductiveDevTools.Utilities.Serializer.serializeAction
      },
      ()),
    ~devToolsUpdateActionCreator=(devToolsState) => `DevToolsUpdate(devToolsState),
    ()
  ) 
  @@ Reductive.Store.create;

React Hooks useReducer (jsx3)

let (state, send) = ReductiveDevTools.Connectors.useReducer(
  ~options=ReductiveDevTools.Extension.enhancerOptions(
    ~name=__MODULE__, 
    ~actionCreators={
      "actionYouCanDispatchFromMonitor": (value: int) => `YourActionOfChoice(value)
        |. ReductiveDevTools.Utilities.Serializer.serializeAction
    },
    ()),
  ~devToolsUpdateActionCreator=(devToolsState) => `DevToolsUpdate(devToolsState),
  ~reducer,
  ~initial=yourInitialState,
  ());

Usage with ReactReason legacy reducer component (jsx2)

No longer supported. Please install latest from 0.x:

npm install --save-dev reductive-dev-tools@0.2.6

And refer to old documentation.

Serialization

Actions

redux-devtools-extension uses value under type key of action object for its name in the monitor. Most likely you are going to use variants for actions, which need to be serialized into js objects to be usefully displayed inside the extension. Actions serialization is built-in. As an alternative, you can override default serializer by passing ~actionSerializer like:

ReductiveDevTools.Connectors.enhancer(
  ~options=ReductiveDevTools.Extension.enhancerOptions(
    ~name=__MODULE__, 
    ()),
  ~actionSerializer={
    serialize: obj => {
      // your serialization logic
      obj
    },
    deserialize: obj => {
      // your deserialization logic
      obj
    }
  },
  ())

There are few caveats that apply to default serialization though.

1. Make sure to add -bs-g into "bsc-flags" of your bsconfig.json to have variant names available.
2. Variants with constructors should be prefered to plain (SomeAction(unit) to SomeAction) since plain varaints do no carry debug metedata(in symbols) with them (represented as numbers in js).
3. Action names won't be displayed when using extensible variants, they also do not carry debug metadata. Extensible variant name becomes "update"
4. Records inside variants do not carry debug metadata in bucklescript yet, if needed you can tag them manually. See Additional Tagging.

State

There is no serialization applied to state by default. If you are on bs-platform 7.0, most likely you do not need it, since ocaml records are compiled to js objects. For earlier versions of bs-platform, please pass the next ~stateSerializer:

ReductiveDevTools.Connectors.enhancer(
  ~options=ReductiveDevTools.Extension.enhancerOptions(
    ~name=__MODULE__, 
    ()),
  ~stateSerializer={
    serialize: ReductiveDevTools.Utilities.Serializer.serializeObject,
    deserialize: ReductiveDevTools.Utilities.Serializer.deserializeObject
  },
  ())

Options

ReductiveDevTools.Extension.enhancerOptions(
  /* the instance name to be showed on the monitor page */
  ~name="SomeTest",
  
  /* action creators functions to be available in the Dispatcher. */
  ~actionCreators={
    "increment": () => `Increment(()) |. ReductiveDevTools.Utilities.Serializer.serializeAction,
    "decrement": () => `Decrement(()) |. ReductiveDevTools.Utilities.Serializer.serializeAction
  },
  
  /* if more than one action is dispatched in the indicated interval, all new actions will be collected and sent at once */
  ~latency=500,
  
  /* maximum allowed actions to be stored in the history tree. */
  ~maxAge=50,
  
  /* actions types to be hidden / shown in the monitors (while passed to the reducers), If `actionsWhitelist` specified, `actionsBlacklist` is ignored. */
  ~actionsBlacklist=[|"StringAction"|],
  
  /* actions types to be hidden / shown in the monitors (while passed to the reducers), If `actionsWhitelist` specified, `actionsBlacklist` is ignored. */
  ~actionsWhitelist=[|"CounterAction"|],
  
  /* if specified as `true`, whenever there's an exception in reducers, the monitors will show the error message, and next actions will not be dispatched. */
  ~shouldCatchErrors=false,
  
  /* If you want to restrict the extension, specify the features you allow. */
  ~features=ReductiveDevTools.Extension.enhancerFeatures(
    ~pause=true,
    ~persist=true,
    ~export=true,
    ~import=Obj.magic("custom"),
    ~jump=true,
    ~dispatch=true,
    ()),

  /* if set to true, will include stack trace for every dispatched action, so you can see it in trace tab */
  ~trace=true,

  /* maximum stack trace frames to be stored (in case trace option was provided as true) */
  ~traceLimit=50
  ())

Additional Tagging

You can also manually customize serialized objects keys and action names displayed inside extension. Two common usecases:

1. Labeling variants with constructors.

   type routerActions = [
     | `RouterLocationChanged(list(string), string, string)
   ];
   
   open ReductiveDevTools.Utilities;
   Reductive.Store.dispatch(store, 
     `RouterLocationChanged(url.path, url.hash, url.search)
       |. labelVariant([|"path", "hash", "search"|]));
   

2. Labeling record keys for records inside variants (since Records inside variants do not carry debug metadata in bucklescript yet).

   type url = {
     path: list(string),
     hash: string,
     search: string,
   };
   type routerActions = [
     | `RouterLocationChanged(url)
   ];
   
   open ReductiveDevTools.Utilities;
   Reductive.Store.dispatch(store, 
     `RouterLocationChanged(url
       |. tagRecord([|"path", "hash", "search"|]));
   

This can also be used to override bucklescript debug metadata(if really needed). Definitions are at: utilities.rei