easy-peasy: easy global state for React

Note: Some prefer not to use a mutation based API. You can return new "immutable" instances of your state if you prefer:

addTodo: (state, payload) => {
  return { ...state, items: [...state.items, payload] };
}

npm install react-redux

import React from 'react';
import { render } from 'react-dom';
import { createStore } from 'easy-peasy';
import { Provider } from 'react-redux'; // :point_left: import the provider
import model from './model';
import TodoList from './components/TodoList';

// :point_down: then create your store
const store = createStore(model);

const App = () => (
  // :point_down: then pass it to the Provider
  <Provider store={store}>
    <TodoList />
  </Provider>
)

render(<App />, document.querySelector('#app'));

import React, { Component } from 'react';
import { connect } from 'react-redux'; // :point_left: import the connect

function TodoList({ todos, addTodo }) {
  return (
    <div>
      {todos.map(({id, text }) => <Todo key={id} text={text} />)}
      <AddTodo onSubmit={addTodo} />
    </div>
  )
}

export default connect(
  // :point_down: Map to your required state
  state => ({ todos: state.todos.items }
  // :point_down: Map your required actions
  dispatch => ({ addTodo: dispatch.todos.addTodo })
)(EditTodo)

Easy Peasy exports numerous types to help you declare your model correctly.

import { Action, Reducer, Thunk, Select } from 'easy-peasy'

interface TodosModel {
  items: Array<string>
  // represents a "select"
  firstItem: Select<TodosModel, string | void>
  // represents an "action"
  addTodo: Action<TodosModel, string>
}

interface UserModel {
  token?: string
  loggedIn: Action<UserModel, string>
  // represents a "thunk"
  login: Thunk<UserModel, { username: string; password: string }>
}

interface StoreModel {
  todos: TodosModel
  user: UserModel
  // represents a custom reducer
  counter: Reducer<number>
}

// Note that as we pass the Model into the `createStore` function. This allows
// full type checking along with auto complete to take place
//                          :point_down:
const store = createStore<StoreModel>({
  todos: {
    items: [],
    firstItem: select(state =>
      state.items.length > 0 ? state.items[0] : undefined,
    ),
    addTodo: (state, payload) => {
      state.items.push(payload)
    },
  },
  user: {
    token: undefined,
    loggedIn: (state, payload) => {
      state.token = payload
    },
    login: effect(async (dispatch, payload) => {
      const response = await fetch('/login', {
        method: 'POST',
        body: JSON.stringify(payload),
        headers: {
          'Content-Type': 'application/json',
        },
      })
      const { token } = await response.json()
      dispatch.user.loggedIn(token)
    }),
  },
  counter: reducer((state = 0, action) => {
    switch (action.type) {
      case 'COUNTER_INCREMENT':
        return state + 1
      default:
        return state
    }
  }),
})

console.log(store.getState().todos.firstItem)

store.dispatch({ type: 'COUNTER_INCREMENT' })

store.dispatch.todos.addTodo('Install typescript')

import { useStore, useActions, Actions, State } from 'easy-peasy';
import { StoreModel } from './your-store';

function MyComponent() {
  const token = useStore((state: State<StoreModel>) =>
    state.user.token
  )
  const login = useActions((actions: Actions<StoreModel>) =>
	  actions.user.login,
  )
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

The above can become a bit cumbersome - having to constantly provide your types to the hooks. Therefore we recommend using the bundled createTypedHooks helper in order to create pre-typed versions of the hooks.

// hooks.js

import { createTypedHooks } from "easy-peasy";
import { StoreModel } from "./model";

export default createTypedHooks<StoreModel>();

We could then revise our previous example.

import { useStore, useActions } from './hooks';

function MyComponent() {
  const token = useStore((state) => state.user.token)
  const login = useActions((actions) => actions.user.login)
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

That's far cleaner - and it's still fully type checked.

const Counter: React.SFC<{ counter: number }> = ({ counter }) => (
  <div>{counter}</div>
)

connect((state: State<StoreModel>) => ({
  counter: state.counter,
}))(Counter)

React Native, hybrid, desktop and server side Redux apps can use Redux Dev Tools using the [Remote Redux DevTools]( https://github.com/zalmoxisus/remote-redux-devtools ) library.

To use this library, you will need to pass the DevTools compose helper as part of theto createStore

import { createStore } from 'easy-peasy';
import { composeWithDevTools } from 'remote-redux-devtools';
import model from './model';

/**
 * model, is used for passing through the base model
 * the second argument takes an object for additional configuration
 */

const store = createStore(model, {
  compose: composeWithDevTools({ realtime: true, trace: true })
  // initialState: {}
});

export default store;

See https://github.com/zalmoxisus/remote-redux-devtools#parameters for all configuration options.

• model (Object, required)

  Your model representing your state tree, and optionally containing action functions.

• config (Object, not required)

  Provides custom configuration options for your store. It supports the following options:

  • compose (Function, not required, default=undefined)

    Custom compose function that will be used in place of the one from Redux or Redux Dev Tools. This is especially useful in the context of React Native and other environments. See the Usage with React Native notes.

  • devTools (bool, not required, default=true)

    Setting this to true will enable the Redux Dev Tools Extension .

  • disableInternalSelectFnMemoize (bool, not required, default=false)

    Setting this to true will disable the automatic memoisation of a fn that you may return in any of yourimplementations. Please see thedocumentation for more information.

  • initialState (Object, not required, default=undefined)

    Allows you to hydrate your store with initial state (for example state received from your server in a server rendering context).

  • injections (Any, not required, default=undefined)

    Any dependencies you would like to inject, making them available to your effect actions. They will become available as the 4th parameter to the effect handler. See thedocs for more.

  • middleware (Array, not required, default=[])

    Any additional middleware you would like to attach to your Redux store.

  • reducerEnhancer (Function, not required, default=(reducer => reducer))

    Any additional reducerEnhancer you would like to enhance to your root reducer (for example you want to use redux-persist ).

import { createStore } from 'easy-peasy';

const store = createStore({
  todos: {
    items: [],
    addTodo: (state, text) => {
      state.items.push(text)
    }
  },
  session: {
    user: undefined,
  }
})

• state (Object, required)

  The part of the state tree that the action is against. You can mutate this state value directly as required by the action. Under the hood we convert these mutations into an update against the Redux store.

• payload (Any)

  The payload, if any, that was provided to the action.

When your model is processed by Easy Peasy to create your store all of your actions will be made available against the store's dispatch . They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the example below.

import { createStore } from 'easy-peasy';

const store = createStore({
  todos: {
    items: [],
    add: (state, payload) => {
      state.items.push(payload)
    }
  },
  user: {
    preferences: {
      backgroundColor: '#000',
      changeBackgroundColor: (state, payload) => {
        state.backgroundColor = payload;
      }
    }
  }
});

store.dispatch.todos.add('Install easy-peasy');

store.dispatch.user.preferences.changeBackgroundColor('#FFF');

• action (Function, required)

  The thunk action definition. A thunk typically encapsulates side effects (e.g. calls to an API). It can be asynchronous - i.e. use Promises or async/await. Thunk actions cannot modify state directly, however, they can dispatch other actions to do so.

  It receives the following arguments:

  • actions (required)

    The actions that are bound to same section of your model as the thunk. This allows you to dispatch another action to update state for example.

  • payload (Any, not required)

    The payload, if any, that was provided to the action.

  • helpers (Object, required)

    Contains a set of helpers which may be useful in advanced cases. The object contains the following properties:

    • dispatch (required)

      The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

    • getState (Function, required)

      When executed it will provide the root state of your model. This can be useful in the cases where you require state in the execution of your effectful action.

    • injections (Any, not required, default=undefined)

      Any dependencies that were provided to the createStore configuration will be exposed as this argument. See thedocs on how to specify them.

    • meta (Object, required)

      This object contains meta information related to the effect. Specifically it contains the following properties:

      • parent (Array, string, required)

        An array representing the path of the parent to the action.

      • path (Array, string, required)

        An array representing the path to the action.

      This can be represented via the following example:

      const store = createStore({
        products: {
          fetchById: thunk((dispatch, payload, { meta }) => {
            console.log(meta);
            // {
            //   parent: ['products'],
            //   path: ['products', 'fetchById']
            // }
          })
        }
      });

When your model is processed by Easy Peasy to create your store all of your thunk actions will be made available against the store's dispatch . They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the examples below.

import { createStore, thunk } from 'easy-peasy'; // :point_left: import then helper

const store = createStore({
  session: {
    user: undefined,
    // :point_down: define your thunk action
    login: thunk(async (actions, payload) => {
      const user = await loginService(payload)
      actions.loginSucceeded(user)
    }),
    loginSucceeded: (state, payload) => {
      state.user = payload
    }
  }
});

// :point_down: you can dispatch and await on the thunk action
store.dispatch.session.login({
  username: 'foo',
  password: 'bar'
})
// :point_down: thunk actions _always_ return a Promise
.then(() => console.log('Logged in'));

import { createStore, thunk } from 'easy-peasy';

const store = createStore({
  foo: 'bar',
  // getState allows you to gain access to the  store's state
  //                                               :point_down:
  doSomething: thunk(async (dispatch, payload, { getState }) => {
    // Calling it exposes the root state of your store. i.e. the full
    // store state :point_down:
    console.log(getState())
    // { foo: 'bar' }
  }),
});

store.dispatch.doSomething()

import { createStore, thunk } from 'easy-peasy';

const store = createStore({
  audit: {
    logs: [],
    add: (state, payload) => {
      audit.logs.push(payload);
    }
  },
  todos: {
    // dispatch allows you to gain access to the store's dispatch
    //                                      :point_down:
    saveTodo: thunk((actions, payload, { dispatch }) => {
      // ...
      dispatch.audit.add('Added a todo');
    })
  }
});

store.dispatch.todos.saveTodo('foo');

We don't recommned doing this, and instead encourage you to use the listeners helper to invert responsibilites. However, there may be cases in which you need to do the above.

import { createStore, effect } from 'easy-peasy';
import api from './api' // :point_left: a dependency we want to inject

const store = createStore(
  {
    foo: 'bar',
    //                       injections are exposed here :point_down:
    doSomething: effect(async (dispatch, payload, { injections }) => {
      const { api } = injections
      await api.foo()
    }),
  },
  {
    // :point_down: specify the injections parameter when creating your store
    injections: {
      api,
    }
  }
);

store.dispatch.doSomething()

• fn (Function, required)

  The reducer function. It receives the following arguments.

  • state (Object, required)

    The current value of the property that the reducer was attached to.

  • action (Object, required)

    The action object, typically with the following shape.

    • type (string, required)

      The name of the action.

    • payload (any)

      Any payload that was provided to the action.

import { createStore, reducer } from 'easy-peasy';

const store = createStore({
  counter: reducer((state = 1, action) => {
    switch (action.type) {
      case 'INCREMENT': state + 1;
      default: return state;
    }
  })
});

store.dispatch({ type: 'INCREMENT' });

store.getState().counter;
// 2

• selector (Function, required)

  The selector function responsible for resolving the derived state. It will be provided the following arguments:

  • state (Object, required)

    The local part of state that the select property was attached to.

  You can return any derived state you like.

  It also supports returning a function. This allows you to support creating a "dynamic" selector that accepts arguments (e.g. productById(1) ). We will automatically optimise the function that you return - ensuring that any calls to the function will be automatically be memoised - i.e. calls to it with the same arguments will return cached results. This automatic memoisation of the function can be disabled via the disableInternalSelectFnMemoize setting on the createStore 's config argument.

• dependencies (Array, not required)

  If this selector depends on data from other selectors then you should provide the respective selectors within an array to indicate the case. This allows us to make guarantees of execution order so that your state is derived in the manner you expect it to.

import { select } from 'easy-peasy'; // :point_left: import then helper

const store = createStore({
  shoppingBasket: {
    products: [{ name: 'Shoes', price: 123 }, { name: 'Hat', price: 75 }],
    // :point_down: define your derived state
    totalPrice: select(state =>
      state.products.reduce((acc, cur) => acc + cur.price, 0)
    )
  }
};

// :point_down: access the derived state as you would normal state
store.getState().shoppingBasket.totalPrice;

import { select } from 'easy-peasy'; // :point_left: import then helper

const store = createStore({
  products: [{ id: 1, name: 'Shoes', price: 123 }, { id: 2, name: 'Hat', price: 75 }],

  productById: select(state =>
    // :point_down: return a function that accepts the arguments
    id => state.products.find(x => x.id === id)
  )
};

// :point_down: access the select fn and provide its required arguments
store.getState().productById(1);

// This next call will return a cached result
store.getState().productById(1);

import { select } from 'easy-peasy';

const totalPriceSelector = select(state =>
  state.products.reduce((acc, cur) => acc + cur.price, 0),
)

const netPriceSelector = select(
  state => state.totalPrice * ((100 - state.discount) / 100),
  [totalPriceSelector] // :point_left: declare that this selector depends on totalPrice
)

const store = createStore({
  discount: 25,
  products: [{ name: 'Shoes', price: 160 }, { name: 'Hat', price: 40 }],
  totalPrice: totalPriceSelector,
  netPrice: netPriceSelector // price after discount applied
});

• on (Function, required)

  Allows you to attach a listener to an action. It expects the following arguments:

  • action (Function | string, required)

    The target action you wish to listen to - you provide the direct reference to the action, or the string name of it.

  • thunk (Function, required)

    The handler thunk to be executed after the target action is fired successfully. It has the same arguments and characteristics of aaction. Please refer to the thunk API documentation for more information.

    The only difference is that the payload argument will be the payload value that the action being listened to received.

import { listen } from 'easy-peasy'; // :point_left: import the helper

const userModel = {
  user: null,
  loggedIn: (state, user) => {
    state.user = user;
  },
  logOut: (state) => {
    state.user = null;
  }
};

const notificationModel = {
  msg: '',
  set: (state, payload) => { state.msg = payload; },

  // :point_down: you can label your listeners as you like, e.g. "userListeners"
  listeners: listen((on) => {
    //             :point_down: pass in direct reference to target action
    on(userModel.loggedIn, (actions, payload) => {
      actions.set(`${payload.username} logged in`);
    })

    // you can listen to as many actions as you like in a block
    on(userModel.logOut, actions => {
      actions.set('Logged out');
    });
  })
};

const model = {
  user: userModel,
  notification: notificationModel
};

import { listen } from 'easy-peasy';

const model = {
  msg: '',
  set: (state, payload) => { state.msg = payload; },

  listeners: listen((on) => {
    //      :point_down: passing in action name
    on('ROUTE_CHANGED', (actions, payload) => {
      //                            :point_up_2:
      // We won't know the type of payload, so it will be "any".
      // You will have to annotate it manually if you are using
      // Typescript and care about the payload type.
      actions.set(`Route was changed`);
    });
  })
};

import { StoreProvider, createStore } from 'easy-peasy';
import model from './model'

const store = createStore(model);

const App = () => (
  <StoreProvider store={store}>
    <TodoList />
  </StoreProvider>
)

• mapState (Function, required)

  The function that is used to resolved the piece of state that your component requires. The function will receive the following arguments:

  • state (Object, required)

    The root state of your store.

• externals (Array of any, not required)

  If your useStore function depends on an external value (for example a property of your component), then you should provide the respective value within this argument so that the useStore knows to remap your state when the respective externals change in value.

Your mapState can either resolve a single piece of state. If you wish to resolve multiple pieces of state then you can either call useStore multiple times, or if you like resolve an object within your mapState where each property of the object is a resolved piece of state (similar to the connect from react-redux ). The examples will illustrate the various forms.

import { useStore } from 'easy-peasy';

const TodoList = () => {
  const todos = useStore(state => state.todos.items);
  return (
    <div>
      {todos.map((todo, idx) => <div key={idx}>{todo.text}</div>)}
    </div>
  );
};

import { useStore } from 'easy-peasy';

const BasketTotal = () => {
  const totalPrice = useStore(state => state.basket.totalPrice);
  const netPrice = useStore(state => state.basket.netPrice);
  return (
    <div>
      <div>Total: {totalPrice}</div>
      <div>Net: {netPrice}</div>
    </div>
  );
};

import { useStore } from 'easy-peasy';

const BasketTotal = () => {
  const { totalPrice, netPrice } = useStore(state => ({
    totalPrice: state.basket.totalPrice,
    netPrice: state.basket.netPrice
  }));
  return (
    <div>
      <div>Total: {totalPrice}</div>
      <div>Net: {netPrice}</div>
    </div>
  );
};

Please be careful in the manner that you resolve values from your `mapToState`. To optimise the rendering performance of your components we use equality checking (===) to determine if the mapped state has changed.

When an action changes the piece of state your mapState is resolving the equality check will break, which will cause your component to re-render with the new state.

Therefore deriving state within your mapState in a manner that will always produce a new value (for e.g. an array) is an anti-pattern as it will break our equality checks.

// :exclamation:️ Using .map will produce a new array instance every time mapState is called
//                                                     :point_down:
const productNames = useStore(state => state.products.map(x => x.name))

You have two options to solve the above.

Firstly, you could just return the products and then do the .map outside of your mapState :

const products = useStore(state => state.products)
const productNames = products.map(x => x.name)

Alternatively you could use thehelper to define derived state against your model itself.

import { select, createStore } from 'easy-peasy';

const createStore = ({
  products: [{ name: 'Boots' }],
  productNames: select(state => state.products.map(x => x.name))
});

Note, the same rule applies when you are using the object result form of mapState :

const { productNames, total } = useStore(state => ({
  productNames: state.products.map(x => x.name), // :exclamation:️ new array every time
  total: state.basket.total
}));

• mapActions (Function, required)

  The function that is used to resolved the action(s) that your component requires. Your mapActions can either resolve single or multiple actions. The function will receive the following arguments:

  • actions (Object, required)

    The actions of your store.

import { useState } from 'react';
import { useActions } from 'easy-peasy';

const AddTodo = () => {
  const [text, setText] = useState('');
  const addTodo = useActions(actions => actions.todos.add);
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => addTodo(text)}>Add</button>
    </div>
  );
};

import { useState } from 'react';
import { useActions } from 'easy-peasy';

const EditTodo = ({ todo }) => {
  const [text, setText] = useState(todo.text);
  const { saveTodo, removeTodo } = useActions(actions => ({
    saveTodo: actions.todos.save,
    removeTodo: actions.todo.toggle
  }));
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => saveTodo(todo.id)}>Save</button>
      <button onClick={() => removeTodo(todo.id)}>Remove</button>
    </div>
  );
};

import { useState } from 'react';
import { useDispatch } from 'easy-peasy';

const AddTodo = () => {
  const [text, setText] = useState('');
  const dispatch = useDispatch();
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => dispatch({ type: 'ADD_TODO', payload: text })}>Add</button>
    </div>
  );
};

// hooks.js
import { createTypedHooks } from 'easy-peasy';
import { StoreModel } from './store';

const { useActions, useStore, useDispatch } = createTypedHooks<StoreModel>();

export default {
  useActions,
  useStore,
  useDispatch
}

• action (Function, required)

  The action function to execute the effects. It can be asynchronous, e.g. return a Promise or use async/await. Effectful actions cannot modify state, however, they can dispatch other actions providing fetched data for example in order to update the state.

  It accepts the following arguments:

  • dispatch (required)

    The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

  • payload (Any, not required)

    The payload, if any, that was provided to the action.

  • getState (Function, required)

    When executed it will provide the root state of your model. This can be useful in the cases where you require state in the execution of your effectful action.

  • injections (Any, not required, default=undefined)

    Any dependencies that were provided to the createStore configuration will be exposed as this argument. See thedocs on how to specify them.

  • meta (Object, required)

    This object contains meta information related to the effect. Specifically it contains the following properties:

    • parent (Array, string, required)

      An array representing the path of the parent to the action.

    • path (Array, string, required)

      An array representing the path to the action.

    This can be represented via the following example:

    const store = createStore({
      products: {
        fetchById: effect((dispatch, payload, getState, injections, meta) => {
          console.log(meta);
          // {
          //   parent: ['products'],
          //   path: ['products', 'fetchById']
          // }
        })
      }
    });
    
    await store.dispatch.products.fetchById()

When your model is processed by Easy Peasy to create your store all of your actions will be made available against the store's dispatch . They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the example below.

import { createStore, effect } from 'easy-peasy'; // :point_left: import then helper

const store = createStore({
  session: {
    user: undefined,
    // :point_down: define your effectful action
    login: effect(async (dispatch, payload) => {
      const user = await loginService(payload)
      dispatch.session.loginSucceeded(user)
    }),
    loginSucceeded: (state, payload) => {
      state.user = payload
    }
  }
});

// :point_down: you can dispatch and await on the effectful actions
store.dispatch.session.login({
  username: 'foo',
  password: 'bar'
})
// :point_down: effectful actions _always_ return a Promise
.then(() => console.log('Logged in'));

import { createStore, effect } from 'easy-peasy';

const store = createStore({
  foo: 'bar',
  // getState allows you to gain access to the  store's state
  //                                               :point_down:
  doSomething: effect(async (dispatch, payload, getState, injections) => {
    // Calling it exposes the root state of your store. i.e. the full
    // store state :point_down:
    console.log(getState())
    // { foo: 'bar' }
  }),
});

store.dispatch.doSomething()

import { createStore, effect } from 'easy-peasy';
import api from './api' // :point_left: a dependency we want to inject

const store = createStore(
  {
    foo: 'bar',
    //                              injections are exposed here :point_down:
    doSomething: effect(async (dispatch, payload, getState, injections) => {
      const { api } = injections
      await api.foo()
    }),
  },
  {
    // :point_down: specify the injections parameter when creating your store
    injections: {
      api,
    }
  }
);

store.dispatch.doSomething()

• attach (Function, required)

  The attach callback function allows you to attach the listeners to specific actions. It is provided the following arguments:

  • actions (Object, required)

    The actions (and effects) of the store.

  • on (Function, required)

    Allows you to attach a listener to an action. It expects the following arguments:

    • action (Function, required)

      The target action you wish to listen to - you provide the direct reference to the action.

    • handler (Function, required)

      The handler function to be executed after the target action is fired successfully. It will receive the following arguments:

      • dispatch (required)

        The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

      • payload (Any, not required)

        The original payload that the targetted action received.

      • getState (Function, required)

        When executed it will provide the root state of your model.

      • injections (Any, not required, default=undefined)

        Any dependencies that were provided to the createStore configuration will be exposed as this argument. See thedocs on how to specify them.

import { listeners } from 'easy-peasy'; // :point_left: import the helper

const store = createStore({
  user: {
    token: '',
    loggedIn: (state, payload) => {
      state.token = payload;
    },
    logIn: effect(async (dispatch, payload) => {
      const token = await loginService(payload);
      dispatch.user.loggedIn(token);
    },
    logOut: (state) => {
      state.token = '';
    }
  },
  audit: {
    logs: [],
    add: (state, payload) => {
      state.logs.push(payload)
    },
    //  :point_down: name your listeners
    userListeners: listeners((actions, on) => {
      // :point_down: we attach a listener to the "logIn" effect
      on(actions.user.logIn, (dispatch, payload) => {
        dispatch.audit.add(`${payload.username} logged in`);
      });
      // :point_down: we attach a listener to the "logOut" action
      on(actions.user.logOut, dispatch => {
        dispatch.audit.add('User logged out');
      });
    }))
  }
});

// :point_down: the login effect will fire, and then any listeners will execute after complete
store.dispatch.user.login({ username: 'mary', password: 'foo123' });

• mapAction (Function, required)

  The function that is used to resolved the action that your component requires. The function will receive the following arguments:

  • dispatch (Object, required)

    The dispatch of your store, which has all the actions mapped against it.

Your mapAction can either resolve a single action. If you wish to resolve multiple actions then you can either call useAction multiple times, or if you like resolve an object within your mapAction where each property of the object is a resolved action. The examples below will illustrate these options.