Notorious Public Menace

    cerebral-operators

    0.2.5 • Public • Published

    cerebral-operators Build Status

    Common operators (actions) for Cerebral.

    Usage

    import set from 'cerebral/operators/set'
    import unset from 'cerebral/operators/unset'

    Data paths

    Cerebral operators allow you to set, copy, unset or check values across multiple data sources and destinations. To simplify the mechanism of addressing these values cerebral operators uses URLs.

    scheme:path
    

    where scheme can be one of:

    • input - (readonly)
    • state - (readwrite)
    • output - (writeonly)

    the path is the location of data to get or set.

    Cerebral will "pre-compile" these URLs into performant functions so that at run time the URL does not need to be parsed. See the Factory Helpers section below for information on how you can integrate these URLs into your own actions.

    Examples

    user name from the input (readonly) { user: { name: 'Brian' } }

    input:user.name
    

    user name from the root of the store

    state:user.name
    

    user name to the output (writeonly)

    output:user.name
    

    Action Factories

    copy

    Copies a value from input, global state or module state to output, global state or module state.

    • copy(from, to)
    // copy serverSettings from input to the store at /settings
    export default [
      [
        getServerSettings, {
          success: [
            copy('input:serverSettings', 'state:settings')
          ]
          error: []
        }
      ]
    ]
    // copy newAccount from account module state to output
    export default [
      copy('state:account.newAccount', 'output:newAccount'),
      [
        ajax.post('/new-account'), {
          success: []
          error: []
        }
      ]
    ]

    debounce

    • debounce(time, continueChain, { terminateChain = [], immediate = true, throttle = true })

    debounce can be used to limit the number a times an actionChain is called, for example on keyboard activity.

    By default the first signal call will execute the continueChain immediately and the last call during the time will execute at the end. To change this to only execute the most recent continueChain at the end, set the options to { immediate: false }.

    It is also possible to pass a terminateChain to the options which will be called whenever a signal is terminated.

    export default [
      copy('input:value', 'state:form.field'),
      debounce(500, [
        validateForm
      ])
    ]

    filter

    • filter(path, compare, acceptChain = null, options = { discardedChain: [] })

    filter accepts a path and compares the value at the path with compare value.

    export default [
      filter('input:user.isAdmin', true, [
        doAdminTasks
      ])
    ]

    If compare is a function then it will be executed and should return a truthy/falsy value.

    • compare function: (value, context) => value === 'what I expected'
    export default [
      filter('input:user', (user, { state }) => user.isAdmin && !user.name == 'Brian' && state.get('inAdminMode'), [
        doAdminTasks
      ])
    ]

    set

    • set(path, value)
    export default [
      set('state:isLoading', 'true'),
      [getOptionsFromServer, {
        success: [],
        error: []
      }],
      set('state:isLoading', 'false')
    ]

    throttle

    • throttle(time, continueChain, { terminateChain = [] })

    throttle can be used to limit the number a times an actionChain is called, for example on keyboard activity.

    It is also possible to pass a terminateChain to the options which will be called whenever a signal is terminated.

    export default [
      copy('input:value', 'state:form.field'),
      throttle(500, [
        validateForm
      ])
    ]

    toggle

    • toggle(path)
    // toggle the menu between true and false
    export default [
      toggle('state:isMenuOpen')
    ]
    // toggle the switch between "On" and "Off"
    export default [
      toggle('state:switch', 'On', 'Off')
    ]

    unset

    • unset(path)
    export default [
      unset('state:item')
    ]

    delay

    • delay(time, continueChain)
    export default [
      addItem,
      delay(500, [
        removeItemHighlight
      ])
    ]

    when

    When can be used to check input or state for a specific value, truthy or falsy and then run an action chain when the condition is matched. To check multiple paths, see the operators section below. If no when.otherwise condition is provided then an otherwise output path will be created for you.

    • when(path, conditions = { 'true': when.truthy, 'false': when.otherwise })

    when exports the following symbols

    • when.truthy
    • when.falsy
    • when.otherwise
    // simple when using default outputs
    export default [
      when('state:isLoading'), {
        true: [tryAgainLater],
        false: [doReload]
      }
    ]
    // create custom output path names
    let whenUser = when('state:users.currentUser', {
      isLoggedIn: when.truthy,
      isUnknown: when.otherwise
    })
     
    export default [
      whenUser, {
        isLoggedIn: [getPageData],
        isUnknown: [redirectToHome]
      }
    ]
    // check for specific values
    let whenFormIsValid = when('state:form.errorMessage', {
      valid: 'no errors found',
      invalid: when.otherwise
    })
     
    export default [
      validateForm,
      whenFormIsValid, {
        valid: [sendToServer],
        invalid: [showErrorSnackBarMessage]
      }
    ]
    // check for specific values against an array of possible matches
    export default [
      when('input:actionType', [ 'close', 'open' ]), {
        close: [],
        open: [],
        otherwise: []
      }
    ]

    Contribute

    Fork repo

    • npm install
    • npm start runs dev mode which watches for changes and auto lints, tests and builds
    • npm test runs the tests
    • npm run lint lints the code
    • npm run build compiles es6 to es5

    Install

    npm i cerebral-operators

    DownloadsWeekly Downloads

    4

    Version

    0.2.5

    License

    MIT

    Last publish

    Collaborators

    • cerebral.js
    • christianalfoni
    • guria
    • garthw