Home Manual Reference Source Test Repository

src/index.js

'use strict'

/**
 * Module dependencies.
 *
 * @ignore
 */

import { combineReducers, createStore } from 'redux'
import { Parser, Template } from 'starplate'
import esprima from 'esprima'
import extend from 'extend'
import domify from 'domify'

/**
 * Container symbols.
 *
 * @private
 */

const $domElement = Symbol('Element')
const $middleware = Symbol('middleware')
const $children = Symbol('children')
const $pipes = Symbol('pipes')
const $model = Symbol('model')
const $store = Symbol('store')
const $uid = Symbol('uid')

/**
 * Private stardux data attached to
 * traversed DOM elements.
 *
 * @private
 * @const
 * @type {String}
 */

const STARDUX_PRIVATE_ATTR = '__starduxData'

/**
 * Reducer action type symbols.
 *
 * @private
 * @const
 * @type {Symbol)
 */

const $UPDATE_ACTION = Symbol('UPDATE')

/**
 * Known container map by ID
 *
 * @private
 * @type {Map}
 */

const CONTAINERS = new Map()

/**
 * Clones an object.
 *
 * @private
 * @param {Object} object
 * @return {Object}
 */

function clone (object) {
  return extend(true, {}, object)
}

/**
 * Detects if input is "like" an array.
 *
 * @private
 * @param {Mixed} a
 * @return {Boolean}
 */

function isArrayLike (a) {
  if ('object' != typeof a)
    return false
  else if (null == a)
    return false
  else
    return Boolean( Array.isArray(a)
                    || null != a.length
                    || a[0] )
}

/**
 * Make stardux data object on a
 * node if not already there.
 *
 * @private
 * @param {Object} node
 * @param {Object} [data = {}]
 * @return {Object}
 */

function mkdux (node, data = {}) {
  if (node instanceof Container)
    node = node.domElement
  node[STARDUX_PRIVATE_ATTR] = ( node[STARDUX_PRIVATE_ATTR] || data )
  return node[STARDUX_PRIVATE_ATTR]
}

/**
 * Remove stardux data object.
 *
 * @private
 * @param {Object} node
 */

function rmdux (node) {
  if (null == node) return
  if (node instanceof Container)
    node = node.domElement
  delete node[STARDUX_PRIVATE_ATTR]
}

/**
 * Returns an array of known tokens
 * in a javascript string.
 *
 * @private
 * @param {String} string
 * @return {Array}
 */

function getTokens (string) {
  let tokens = null
  try { tokens = esprima.tokenize('`'+ string +'`') }
  catch (e) { tokens = [] }
  return tokens
}

/**
 * Returns an object of identifiers with
 * empty string or NO-OP function
 * values.
 *
 * @private
 * @param {Array} tokens
 * @return {Object}
 */

function getIdentifiersFromTokens (tokens) {
  const identifiers = {}

  /**
   * Predicate to determine if token is an identifier.
   *
   * @private
   * @param {Object} token
   * @return {Boolean}
   */

  const isIdentifier = token => 'Identifier' == token.type

  /**
   * Mark token as a function identifier.
   *
   * @private
   * @param {Object} token
   * @param {Number} index
   * @return {Object} token
   */

  const markFunction = (token, index) => {
    const next = tokens[index + 1] || null
    token.isFunction = ( 'Identifier' == token.type
                        && 'object' == typeof next && next
                        && 'Punctuator' == next.type
                        && '(' == next.value
                          ? true : false )
    return token
  }

  /**
   * Mark token as a object identifier.
   *
   * @private
   * @param {Object} token
   * @param {Number} index
   * @return {Object} token
   */

  const markObject = (token, index) => {
    const next = tokens[index + 1] || null
    token.isObject = ( 'Identifier' == token.type
                      && 'object' == typeof next && next
                      && 'Punctuator' == next.type
                      && '.' == next.value
                        ? true : false )
    return token
  }

  /**
   * Assign token value to identifierss map.
   *
   * @private
   * @param {Object} map
   * @param {Object} token
   * @return {Object} map
   */

  const assign = (map, token) => {
    const value = token.value
    if (token.isFunction)
      map[value] = _ => ''
    else if (token.isObject)
      map[value] = {}
    else
      map[value] = ''
    return map
  }

  // resolve identifierss and return map
  return ( tokens
          .map((t, i) => markFunction(t, i))
          .map((t, i) => markObject(t, i))
          .filter(t => isIdentifier(t))
          .reduce((map, t) => assign(map, t), identifiers) )
}

/**
 * Ensures a DOM string from a given input.
 *
 * @private
 * @param {String} html
 * @return {String}
 */

function ensureDOMString (html = '') {
  html = 'string' == typeof html ? html : String(html || '')
  return html.trim()
}

/**
 * Ensure DOM element.
 *
 * @private
 * @param {Mixed} input
 * @return {Element}
 */

function ensureDOMElement (input) {
  let domElement = null
  let tmp = null
  if (input instanceof Element) {
    return input
  } else if ('string' == typeof input) {
    tmp = document.createElement('div')
    tmp.innerHTML = input
    domElement = tmp.innerHTML.length ? tmp.children[0] : new Template(input)
  } else {
    domElement = document.createElement('div')
  }
  return domElement
}

/**
 * Returns a template tring from a given
 * DOM Element. If the DOM Element given is a
 * string then it is simply returned.
 *
 * @public
 * @param {Element|String} domElement
 * @return {String}
 */

function getTemplateFromDomElement (domElement) {
  let data = {}
  let src = null

  if (domElement && domElement[STARDUX_PRIVATE_ATTR])
    data = mkdux(domElement)

  if ('string' == typeof domElement)
    src = domElement
  else if (data.src)
    src = data.src
  else if (domElement.children && 0 == domElement.children.length)
    src = ensureDOMString(domElement.textContent)
  else if (domElement.firstChild instanceof Text)
    src = ensureDOMString(domElement.innerHTML)
  else if (domElement instanceof Text)
    src = ensureDOMString(domElement.textContent)
  else if (domElement)
    src = domElement.innerHTML || domElement.textContent

  return src
}

/**
 * Ensures container state identifiers (tokens) derived from
 * the DOM element source are defined on the state if not
 * already. This is useful to prevent reference errors from
 * being thrown when ES6 templates are evaulated in starplate's
 * VM.
 *
 * @private
 * @param {Container} container
 * @return {Object} identifiers
 */

function ensureContainerStateIdentifiers (container) {
  const domElement = container[$domElement]
  const template = getTemplateFromDomElement(domElement)
  const tokens = getTokens(template)
  const identifiers = getIdentifiersFromTokens(tokens)
  const update = {}
  const state = container.state
  if (identifiers) {
    for (let key in identifiers) {
      if (undefined === state[key])
        update[key] = identifiers[key]
    }

    container.define(update)
  }
  return identifiers || null
}

/**
 * Creates a root reducer for a Container
 * instance.
 *
 * @private
 * @param {Container} container
 * @return {Function}
 */

function createRootReducer (container) {
  return (state = {}, action = {data: {}}) => {
    const identifiers = ensureContainerStateIdentifiers(container)
    const domElement = container[$domElement]
    const template = getTemplateFromDomElement(domElement)
    const middleware = container[$middleware].entries()
    const isBody = domElement == document.body

    action.data = action.data || {}

    /**
     * Loops over each middleware function
     * providing state and action values
     * given to use from redux.
     *
     * @private
     */

    void function next () {
      const step = middleware.next()
      const done = step.done
      const reducer = step.value ? step.value[0] : null
      if (done) return
      else if (null == reducer) next()
      else if (false === reducer(state, action)) return
      else next()
    }()

    switch (action.type) {
      case $UPDATE_ACTION:
        container.define(action.data)
        if (!isBody && identifiers) {
          const parser = new Parser()
          const partial = new Template(template)
          const src = partial.render(container.state, container)
          const patch = parser.createPatch(src)
          patch(domElement)
      }
      break
    }

    return extend(true, container.state, state, action.data)
  }
}

/**
 * Creates a pipe reducer for a Container
 * instance.
 *
 * @private
 * @param {Container} container
 * @return {Function}
 */

function createPipeReducer (container) {
  return (_, action = {data: {}}) => {
    const state = container.state
    const pipes = container[$pipes].entries()
    reduce()
    return container.state

    /**
     * Loops over each pipe function
     * providing state and action values
     * given to use from redux.
     *
     * @private
     */

    function reduce () {
      const step = pipes.next()
      const done = step.done
      const pipe = step.value ? step.value[1] : null
      if (done) return
      else if (false === pipe(state, action)) return
      else return reduce()
    }
  }
}

/**
 * Orphan container.
 *
 * @private
 * @param {Container} container
 * @param {Boolean} [rouge]
 */

function orphanContainerChildren (container, rouge = false) {
  container = fetchContainer(container)

  const children = container.children

  if (null == container)
    throw new TypeError( "orphanContainerChildren() Expecting a container " )

  for (let child of children) {
    container.removeChild(child)
    if (true === rouge) {
      orphanContainerChildren(child, true)
      CONTAINERS.delete(child.id)
    }
  }
}

/**
 * The action type dispatched by the update() method.
 *
 * @example <caption>Handle update actions in middleware and reducers.</caption>
 *
 *   // Use this value to determine what type of
 *   // action was dispatched in a reducer or
 *   // middleware function
 *   (state, action) => {
 *     if (UPDATE == action.type) {
 *        // reducer/middleware logic here
 *     }
 *   }
 *
 * @public
 * @const
 * @type {Symbol}
 */

export const UPDATE = $UPDATE_ACTION

/**
 * Create a new Container instance with optional
 * initial state and n reducers.
 *
 * @example <caption>Create an anonymouse container.</caption>
 *   const container = createContainer()
 *
 * @example <caption>Create a container for a DOM Element.</caption>
 *   const container = createContainer(domElement)
 *
 * @example <caption>Create a container for a DOM Element with initial state.</caption>
 *   const container = createContainer(domElement, {value: 0})
 *
 * @example <caption>Create a container for a DOM Element with initial state and reducers.</caption>
 *   const container = createContainer(domElement, {value: 0}, (state = {}, action) => {
 *     if (UPATE == action.type) {
 *        return {
 *          value: state.action + action.data.value
 *        }
 *     }
 *   })
 *
 * @public
 * @param {Element} domElement
 * @param {?(Object)} [initialState] - Initial state object
 * @param {...Function} [reducers]
 * @return {Container}
 */

export function createContainer (domElement, initialState = null, ...reducers) {
  const container = ( fetchContainer(domElement)
                   || new Container(domElement, ...reducers) )
  return container.update(initialState)
}

/**
 * Creates a or returns a new Container instance
 * from a given DOM element.
 *
 * If a DOM element is already associated with
 * a container then the container is just
 * returned, otherwise a new one is created.
 *
 * @example <caption>Make a container for a DOM Element.</caption>
 *   const container = makeContainer(document.body)
 *
 * @public
 * @param {Element} domElement
 * @return {Container}
 */

export function makeContainer (domElement) {
  let container = null
  if (false == (domElement instanceof Element))
    throw new TypeError("makeContainer() expects a DOM element.")
  container = fetchContainer(domElement) || new Container(domElement)
  return container
}

/**
 * Create or restore a Container instance
 * from a JSON object with an optional state
 * object a reducers.
 *
 * Containers are created if they do not already
 * exist internally.
 *
 * @example <caption>Restore or create a container from JSON.</caption>
 *   const container = restoreContainerFromJSON(json)
 *
 * @example <caption>Restore or create a container from JSON with initial state.</caption>
 *   const container = restoreContainerFromJSON(json, {value: 0})
 *
 * @example <caption>Restore or create a container from JSON with initial state and reducers.</caption>
 *   const container = restoreContainerFromJSON(json, {value: 0}, ...reducers)
 *
 * @public
 * @param {Object} json
 * @param {?(Object)} [initialState] - Initial state object
 * @param {...Function} [reducers]
 * @return {Container}
 */

export function restoreContainerFromJSON (json, initialState = null, ...reducers) {
  const id = json.id
  const src = json.src
  let data = null
  let children = []
  let container = fetchContainer(id)
  let domElement = null

  if (null == container)
    container = new Container(null, ...reducers)

  container[$uid] = id
  domElement = container.domElement
  data = mkdux(domElement)

  saveContainer(container)

  if (src != data.src)
    data.src = src

  if (initialState)
    container.update(initialState)

  for (let child of json.children)
    children.push(restoreContainerFromJSON(child, initialState))

  realignContainerTree(container, true, true)

  for (let child of children)
    if (false == container.contains(child))
      container.appendChild(child, false)

  return container.update()
}

/**
 * Compose a container from containers or DOM elements.
 * If a Container or Element is given as first argument then
 * it is treated as the root and all subsequent arguments are
 * treated as direct descendants of the root. If the second
 * argument is an array or an "array like" object then it is
 * treated as direct descendants of the root and all subsequent
 * arguments are ignored. If an array or "array like" object is
 * passed as the first argument a new root container is created
 * and the first argument is treated as direct descendants of
 * the newly created root container. The root container, newly
 * created or restored is returned.
 *
 * @example <caption>Compose containers together with new root.</caption>
 *   const a = createContainer()
 *   const b = createContainer()
 *   const composed = composeContainers([a, b])
 *
 * @example <caption>Compose containers together with given root.</caption>
 *   const a = createContainer()
 *   const b = createContainer()
 *   const c = createContainer()
 *   const composed = composeContainers(a, [b, c])
 *
 * @public
 * @param {?(Element|Container)} root
 * @param {?(...Element|Container|String)} containers
 * @return {Container}
 */

export function composeContainers (root, ...containers) {
  let composed = null
  let updateChildren = false
  const children = []

  // array of containers
  if (isArrayLike(root)) {
    containers = [ ...root ].map(createContainer)
    root = null
  } else {
    // derive containers from arguments
    if (isArrayLike(containers[0]))
      containers = [ ...containers[0] ]
    containers = [ ...containers ].map(createContainer)
  }

  composed = createContainer(root || undefined)

  // create composite
  let composite = composed
  for (let child of containers) {
    if (false == composite.contains(child))
      composite = composite.pipe(child)
  }

  // realign root tree
  realignContainerTree(composed, true)

  // allow consumer to unwind composition
  composed.decompose = _ => {
    let composite = composed
    for (let child of containers)
      composite = composite.unpipe(child)
    // remove this function
    delete composed.decompose
    return composed
  }

  return composed
}

/**
 * Returns immutable private stardux data for a given
 * input. Input can be a container, an Element,
 * or a string representing a container ID. If data is
 * not found then null is returned.
 *
 * @example <caption>Get container data for a container.</caption>
 *   const data = getContainerData(container)
 *
 * @example <caption>Get container data for a container from a given DOM element.</caption>
 *   const data = getContainerData(container)
 *
 * @example <caption>Get container data for a container from a given id.</caption>
 *   const data = getContainerData(id)
 *
 * @public
 * @param {Container|Element|String} arg
 * @return {Object}
 */

export function getContainerData (arg) {
  let data = null
  let domElement = null
  const container = fetchContainer(arg)

  if (!(arg instanceof Container
     || arg instanceof Element
     || 'string' == typeof arg)) {
    throw new TypeError( "Unexpected input for getContainerData. "
                       + "Expecting an instance of a Container or Element, "
                       + "or a string." )
  }

  if (container)
    domElement = container.domElement

  if (domElement)
    data = domElement[STARDUX_PRIVATE_ATTR]
  return data ? Object.freeze(data) : null
}

/**
 * Restores orphaned children containers
 * still attached to a container. An orphan
 * container is a container who belongs to
 * a set of containers and it's DOM element
 * is not attched to a DOM tree (The parent
 * container's DOM element).
 *
 * @public
 * @param {Container|Element} container
 * @param {Boolean} [recursive]
 */

export function restoreOrphanedTree (container, recursive = false) {
  if (container instanceof Element)
    container = fetchContainer(container)

  if (null == container)
    return

  const domElement = container.domElement
  const children = container[$children]

  for (let child of [ ...children ]) {
    const childDomElement = child.domElement

    if (false == domElement.contains(childDomElement))
      domElement.appendChild(childDomElement)

    if (recursive)
      restoreOrphanedTree(child, true)
  }
}

/**
 * Realign container DOM tree by removing containers
 * not found in container DOM tree. If recursive is set to
 * true then realignment is applied to all subsequent child
 * containers. If forceOrphanRestoration is set to true then
 * orphan containers are restored.
 *
 * @public
 * @param {Container} container
 * @param {Boolean} [recursive]
 * @param {Boolean} [forceOrphanRestoration]
 */

export function realignContainerTree (container,
                                      recursive = false,
                                      forceOrphanRestoration = false) {
  const domElement = container.domElement
  const children = container[$children]

  if (null == domElement.children)
    return

  const delta = [ ...children ].length - domElement.children.length

  if (delta > 0 || true === forceOrphanRestoration)
    restoreOrphanedTree(container, recursive)

  // purge child containers existing in tree where
  // the DOM element is not a child of the container
  // DOM element.
  for (let child of [ ...children ]) {
    const childElement = child.domElement
    if (false == domElement.contains(childElement))
      children.delete(child)
  }

  // traverse children
  for (let childElement of [ ...domElement.children ]) {
    const data = childElement[STARDUX_PRIVATE_ATTR]
    const child = 'object' == typeof data ? fetchContainer(data.id) : null

    // skip DOM elements which are not claimed
    // by any existing containers
    if (null == child)
      continue

    children.add(child)

    // recurse child containers
    if (true === recursive)
      realignContainerTree(child, true, forceOrphanRestoration)
  }
}


/**
 * Save a container to the known containers map. A
 * DOM element may be passed if it has been claimed by
 * a Container instance.
 *
 * @example <caption>Save a container</caption>
 *   saveContainer(container)
 *
 * @example <caption>Save a container by DOM element</caption>
 *   saveContainer(domElement)
 *
 * @public
 * @param {(Container|Element)} container
 * @return {Boolean}
 */

export function saveContainer (container) {
  container = fetchContainer(container) || container
  if (container && container.id && !CONTAINERS.has(container.id)) {
    CONTAINERS.set(container.id, container)
    return true
  }
  return false
}

/**
 * Fetch a saved container by container ID,
 * DOM element, or by a container instance.
 *
 * @example <caption>Fetch container by id.</caption>
 *   const container = fetchContainer(id)
 *
 * @example <caption>Fetch container by DOM element.</caption>
 *   const container = fetchContainer(domElement)
 *
 * @example <caption>Fetch container by object with id.</caption>
 *   const container = fetchContainer({id: id})
 *
 * @public
 * @param {(String|Element|Object)} arg
 * @param {String} [arg.id] - Container ID
 * @return {class Container}
 */

export function fetchContainer (arg) {
  const id = ( arg && arg.id )
             ? arg.id
             : ( arg && arg[STARDUX_PRIVATE_ATTR] )
               ? arg[STARDUX_PRIVATE_ATTR].id
               : arg
  return id ? CONTAINERS.get(id) : null
}

/**
 * Generates a unique hex ID for Container instances.
 *
 * @example <caption>Create a unique container ID</caption>
 *   const id = createContainerUid()
 *
 * @public
 * @return {String}
 */

export function createContainerUid () {
  return ( Math.random() ).toString('16').slice(1)
}

/**
 * Returns an interator for all containers.
 *
 * @example <caption>Get an iterator for all containers.</caption>
 *   const it = getAllContainers()
 *   for (let pair of [ ...it ])
 *     console.log(pair)
 *
 * @public
 * @return {MapIterator<String, Container>}
 */

export function getAllContainers () {
  return CONTAINERS.entries()
}

/**
 * Execute a function for each container.
 *
 * @example
 *   forEachContainer(container => {
 *     console.log(container)
 *   })
 *
 * @public
 * @param {Function} fn
 * @param {Object} [scope]
 */

export function forEachContainer (fn, scope = null) {
  const containers = getAllContainers()
  fn = 'function' == typeof fn ? fn : _ => void 0
  for (let kv of containers)
    fn.call(scope || global, kv[1], containers)
}

/**
 * Traverse a container's tree recursively.
 *
 * @example
 *   traverseContainer(container, child => {
 *     console.log(child)
 *   })
 *
 * @public
 * @param {Container} container
 * @param {Function} fn
 * @param {Object} [scope]
 */

export function traverseContainer (container, fn, scope) {
  const children = container.children
  for (let child of [ ...children ]) {
    fn.call(scope || global, child, children)
    traverseContainer(child, fn, scope)
  }
}

/**
 * Removes a container from the internal tree.
 * The container is also removed from its parent
 * if it is attched to one. A string ID, DOM element,
 * or Container may be used as an argument.
 *
 * @example <caption>Remove container by id.</caption>
 *   removeContainer(id)
 *
 * @example <caption>Remove container by DOM element.</caption>
 *   removeContainer(domElement)
 *
 * @example <caption>Remove container by object with id.</caption>
 *   removeContainer({id: id})
 *
 * @public
 * @param {(String|Container|Element)} arg
 * @param {Boolean} [recursive]
 * @return {Boolean}
 */

export function removeContainer (arg, recursive = false) {
  const container = fetchContainer(arg)
  const id = container ? container.id : null
  if (id && CONTAINERS.has(id)) {
    if (recursive) {
      for (let child of container.children)
        removeContainer(child, true)
    }

    // remove from parent
    if (container.parent)
      container.parent.removeChild(container, false, true)

    // remove stardux data
    rmdux(container.domElement)

    // remove from tree
    CONTAINERS.delete(id)
    return true
  }
  return false
}

/**
 * Clears all saved containers. This will call
 * removeContainer for every saved container.
 *
 * @public
 * @return {undefined}
 */

export function clearContainers () {
  // remove stardux data for each container
  forEachContainer(container => removeContainer(container))

  // sanity clear containers
  CONTAINERS.clear()
}

/**
 * Replace container element with another. This will remove all
 * children containers and realign the container tree.
 *
 * @public
 * @param {Container} container
 * @param {Element} domElement
 * @return {Container}
 */

export function replaceDOMElement (container, domElement) {
  const existingData = mkdux(domElement)
  const data = mkdux(container.domElement)
  if (domElement && domElement != container.domElement) {
    mkdux(domElement, data)

    const id = container.id
    const sources = []
    const childElements = [ ...domElement.children ]
    const parent = container.parent
    const children  = container.children
    const parentElement = parent ? parent.domElement : null
    const previousDomElement = container.domElement
    const existingContainer = fetchContainer(existingData.id)

    if (existingContainer) {
      throw new TypeError( "replaceDOMElement() expects an unclaimed "
                         + "DOM Element." )
    }

    orphanContainerChildren(id, 0 == children.length)

    // free DOM element of dux data
    rmdux(previousDomElement)
    container[$domElement] = domElement
    container[$children].clear()

    for (let childElement of childElements)
      storeChildSource(childElement)

    container.update(null, false)

    const stack = sources.slice()
    for (let childElement of [ ...domElement.children ])
      restoreChildElementSource(childElement, stack)

    container[$domElement].innerContents = domElement.innerHTML

    realignContainerTree(container, true, true)

    function storeChildSource (node) {
      const data = mkdux(node)
      sources.push(data.src || node.innerHTML)
      for (let child of [ ...node.children ])
        storeChildSource(child)
    }

    function restoreChildElementSource (node, stack) {
      const parser = new Parser()
      const source = stack.shift()
      const data = extend(mkdux(node), {src: source})
      const patch = source ? parser.createPatch(source) : null
      if (patch) patch(node)
      for (let child of [ ...node.children ])
        restoreChildElementSource(child, stack)
    }
  }
  return container
}


/**
 * Container class.
 *
 * @public
 * @class Container
 */

export class Container {

  /**
   * Container constructor.
   *
   * @public
   * @constructor
   * @param {Element|String} domElement
   * @param {Function} ...reducers
   */

  constructor (domElement = null, ...reducers) {
    // ensure DOM element instance
    domElement = ensureDOMElement(domElement)

    /**
     * Container UID
     *
     * @private
     * @type {String}
     */

    this[$uid] = createContainerUid()

    /**
     * Instance root DOM Element.
     *
     * @private
     * @type {Element}
     */

    this[$domElement] = domElement

    /**
     * Middleware set.
     *
     * @private
     * @type {Set}
     */

    this[$middleware] = new Set()

    /**
     * Known container pipes.
     *
     * @private
     * @type {Set}
     */

    this[$pipes] = new Map()

    /**
     * View model.
     *
     * @private
     * @type {Object}
     */

    this[$model] = {}

    /**
     * Child containers.
     *
     * @private
     * @type {Set}
     */

    this[$children] = new Set()

    /**
     * Redux store.
     *
     * @private
     * @type {Object}
     */

    this[$store] = createStore(combineReducers([
      // The root reducer handles container state updates
      // and propagates them to the internal DOM element
      // via starplate templates. The DOM tree is patched,
      // not redrawn. Middleware consumption is also applied
      // here. The state and action objects provided by redux
      // may be modified.
      createRootReducer(this),

      // User provided reducers from the class constructor. The
      // state and action objects may be modified from their original
      // states when dispatched due to middleware side effects applied
      // in  the root reducer.
      ...reducers,

      // Piped reducers are applied when composition occurs between
      // two containers. They are achievd with the pipe() method. All
      // dispatched actions are propagated to the piped container via
      // this reducer. They actually don't reduce state, but simply pass
      // it on. When an update action occurs via an update() on a container
      // all containers it has been piped to will effectively have their
      // update() methods called with the provided data arguments. Please
      // note that any middleware applied to parent of a pipe chain will
      // affect the input of the child of a pipe chain.
      createPipeReducer(this),
    ]))

    // Replace DOM element with itself effectively
    // restoring orphaned or lost stardux data.
    replaceDOMElement(this, domElement)

    // ensure container state identifers found in
    // DOM element source is predefined on the internal
    // state object.
    ensureContainerStateIdentifiers(this)

    // Save this container to the internal container map
    saveContainer(this)

    // Realign parent tree recursively if it exists and restore
    // orphaned child containers. This will cause all
    // child containers to realign themselves recursively.
    if (this.parent)
      realignContainerTree(this.parent, true, true)
    // Realign container and all orphaned child containers if
    // found in the tree. This will cause child containers to
    // realign themselves.
    else
      realignContainerTree(this, true, true)
  }

  /**
   * Copy of the internal state object.
   *
   * @public
   * @type {Object}
   */

  get state () {
    return clone(this[$model])
  }

  /**
   * Container id.
   *
   * @public
   * @type {String}
   */

  get id () {
    return this[$uid]
  }

  /**
   * Getter to return parent container if
   * available. Parent is determined with
   * DOM traversal up the tree. A container can
   * be considered orphaned if it doesn't have a
   * parent DOM element.
   *
   * @public
   * @type {Container|null}
   */

  get parent () {
    const domElement = this.domElement
    let parentElement = domElement && domElement.parentElement
    let parentContainerData = {}
    let parentElementContainer = null
    do {
      if (null == parentElement) break
      parentContainerData = parentElement[STARDUX_PRIVATE_ATTR] || {}
      parentElement = parentElement.parentElement
    } while (!(parentElementContainer = fetchContainer(parentContainerData.id)))
    return parentElementContainer
  }

  /**
   * Container DOM element.
   *
   * @public
   * @type {Element}
   */

  get domElement () {
    return this[$domElement]
  }

  /**
   * DOM element setter that basically just
   * calls replaceDOMElement(domElement).
   *
   * @ignore
   * @public
   * @type {Element}
   */

  set domElement (domElement) {
    if (domElement instanceof Element)
      replaceDOMElement(this, domElement)
    else throw new TypeError( "Cannot set property .domElement. Value must "
                            + "be an Element." )
    return this.domElement
  }

  /**
   * Internal contents of the container
   *
   * @public
   * @type {String}
   */

  get innerContents () {
    return this.domElement.innerHTML || ''
  }

  /**
   * Sets inner contents of DOM content.
   * This will set the template source
   * and update the container. If child
   * containers exist in tree they will
   * become orphaned. If value is null
   * then the value becomes an empty
   * string (''). undefined values result
   * in the string 'undefined'.
   *
   * @ignore
   * @public
   * @type {String}
   */

  set innerContents (value) {
    if (null === value)
      value = ''
    const data = mkdux(this)
    data.src = String(value)
    this.update()
  }

  /**
   * Child containers
   *
   * @public
   * @return {Array<Container>}
   */

  get children () {
    return [ ...this[$children].entries() ].map(kv => kv[0])
  }

  /**
   * Extend view model.
   *
   * @example <caption>Extend current state model.</caption>
   *   container.define({value: 0})
   *
   * @public
   * @param {Object} model
   * @return {Container}
   */

  define (model) {
    if ('object' == typeof model)
      extend(true, this[$model], model)
    return this
  }

  /**
   * Consume reducer middleware.
   *
   * @example <caption>Install reducer middleware plugin.</caption>
   *   container.use((state = {}, action) => { ... })
   *
   * @public
   * @param {...Function} plugins
   * @return {Container}
   */

  use (...plugins) {
    const middleware = this[$middleware]
    for (let plugin of plugins)
      middleware.add(plugin)
    return this
  }

  /**
   * Updates container and all child containers.
   *
   * @example <caption>Update container and its children</caption>
   *   container.update({value: 0})
   *
   * @example <caption>Update only container and not its children</caption>
   *   container.update({value: 0}, false)
   *
   * @public
   * @param {Object} [data] - New state data
   * @param {Boolean} [propagate] - Propagate updates to child containers.
   * @return {Container}
   */

  update (data, propagate = true) {
    const domElement = this.domElement
    const template = getTemplateFromDomElement(domElement)

    // init/update DOM data
    extend(mkdux(domElement), { id: this[$uid] })
    if (template) {
      extend(mkdux(domElement), {
        src: getTemplateFromDomElement(domElement)
      })
    }

    // pre alignment
    realignContainerTree(this, true, true)

    // update
    this.dispatch($UPDATE_ACTION, data, { propagate: propagate })

    if (propagate) {
      for (let child of [ ...this.children ]) {
        child.update(data || this.state)
      }
    }

    // post alignment
    realignContainerTree(this)
    return this
  }

  /**
   * Render container to a DOM element.
   *
   * @example <caption>Render container to a given domElement.</caption>
   *   container.render(document.body)
   *
   * @public
   * @param {Element} domElement
   * @return {Container}
   */

  render (domElement) {
    if (!domElement) return this
    if (false == domElement.contains(this[$domElement])) {
      domElement.appendChild(this[$domElement])
      realignContainerTree(this)
    }
    return this
  }

  /**
   * Dispatch an event with type, optional data
   * and optional arguments to the internal redux store.
   *
   * @example <caption>Dispatch an action with type and optional data and action argument.</caption>
   *   container.dispatch({
   *     type: 'MY_ACTION',
   *     data: {value: 123},
   *     propagate: false
   *   })
   *
   * @public
   * @param {Mixed} type
   * @param {Object} [data]
   * @param {Object} [args]
   * @return {Container}
   */

  dispatch (type, data = {}, args = {}) {
    if (!type) throw new TypeError("Failed to dispatch event without type.")
    const store = this[$store]
    const payload = {type: type, data: data}
    for (let key in args)
      payload[key] = args[key]
    store.dispatch(payload)
    return this
  }

  /**
   * Replace child tree with new children.
   * @public
   *
   * @example
   *  container.replaceChildren([childA, childB, createContainer()])
   *
   * @param {Array<Container|Element>} children
   * @return {Container}
   */

  replaceChildren (children) {
    for (let child of this.children)
      this.removeChild(child, false)

    for (let child of children)
      this.appendChild(child, false)
    return this.update()
  }

  /**
   * Returns the associated value of the
   * container.
   *
   * @public
   * @return {Element}
   */

  valueOf () {
    return this.domElement
  }

  /**
   * Returns the string reprenstation of
   * this container.
   *
   * @public
   * @return {String}
   */

  toString () {
    return this.domElement.textContent
  }

  /**
   * Converts container to a JSON
   * serializable object.
   *
   * @public
   * @return {Object}
   */

  toJSON () {
    const root = {}
    void function traverse (container, node) {
      node.id = container.id
      node.src = getTemplateFromDomElement(container.domElement)
      node.state = container.state || {}
      node.children = []
      for (let child of container.children) {
        const next = {}
        node.children.push(next)
        traverse(child, next)
      }
    }(this, root)
    return root
  }

  /**
   * Pipe container updates to a given container.
   *
   * @example
   *  containerA.pipe(containerB)
   *
   * @public
   * @param {Container} container
   * @return {Container} container
   */

  pipe (container) {
    const pipes = this[$pipes]
    const middleware = (state, action) => {
      switch (action.type) {
        case $UPDATE_ACTION:
          if (action.data) container.update(clone(action.data))
          break
        default:
          container.dispatch(action.type, action.data, action)
      }
    }

    if (false == pipes.has(container))
      pipes.set(container, middleware)

    return container
  }

  /**
   * Unpipe container updates for a given container.
   *
   * @example
   *  containerA.unpipe(containerB)
   *
   * @public
   * @param {Container} container
   * @return {Container} container
   */

  unpipe (container) {
    const pipes = this[$pipes]
    const reducers = this[$middleware]
    const middleware = pipes.get(container)
    if (middleware) {
      pipes.delete(container)
    }
    return container
  }

  /**
   * Append a child container. A child may be an
   * instance of a Container, Element, Text, or
   * a string. Containers are derived from their input
   * and will cause a DOM tree to be restructured.
   *
   * @example
   *   container.appendChild(child)
   *
   * @public
   * @param {Container|Element|Text|String} child
   * @param {Boolean} [update]
   * @param {Boolean} [realign]
   * @return {Container}
   */

  appendChild (child, update = true, realign = true) {
    const domElement = this.domElement
    let childDomElement = null
    let container = null

    if (child instanceof Container) {
      container = child
    } else if (child instanceof Element) {
      container = createContainer(child)
    } else if ('string' == typeof child || child instanceof Text) {
      container = createContainer(child)
    } else {
      throw new TypeError( "Unexpected input for appendChild. "
                         + "Expecting an instance of a Container, Element, Text "
                         + "or a string." )
    }

    childDomElement = container.domElement

    if (update) this.update()

    try {
      if (container.parent && container.parent != this) {
        container.parent.removeChild(container)
      }
      domElement.appendChild(childDomElement)
      this[$children].add(container)
    } catch (e) { console.warn(e) }

    if (realign) realignContainerTree(this)

    return container
  }

  /**
   * Remove a child container. A child may be an
   * instance of a Container or Element. Containers
   * are derived from their input and will cause a
   * DOM tree to be restructured.
   *
   * @example
   *   container.removeChild(child)
   *
   * @public
   * @param {Container|Element} child
   * @param {Boolean} [update]
   * @param {Boolean} [realign]
   * @return {Container}
   */

  removeChild (child, update = true, realign = true) {
    const domElement = this.domElement
    let childDomElement = null
    let container = fetchContainer(child)

    // bail if there is nothing to do
    if (null == container) return this

    childDomElement = container.domElement

    // remove child if it is in tree
    if (domElement.contains(childDomElement))
      domElement.removeChild(childDomElement)

    // remove from container children tree
    this[$children].delete(container)

    // realign tree
    if (realign) realignContainerTree(this)

    return this
  }

  /**
   * Predicate to determine if a container or its
   * DOM element is a child of the container.
   *
   * @example
   *   if (container.contains(child)) {
   *     ...
   *   }
   *
   * @public
   * @param {Container|Element} container
   * @param {Boolean} [recursive]
   * @return {Boolean}
   */

  contains (container, recursive = true) {
    container = fetchContainer(container)
    if (this[$children].has(container)) {
      return true
    } else if (recursive) {
      for (let child of this.children) {
        if (child.contains(container)) {
          return true
        }
      }
    }
    return false
  }
}