Wondering what’s next for npm?Check out our public roadmap! »

    @raid/streams

    6.0.0 • Public • Published

    @raid/streams

    Collection of event streams ready to mount to raid

    npm License: MIT Build Status Coverage Status js-standard-style

    Raid Documentation

    Getting Started

    Install with yarn or npm

    yarn add raid @raid/streams
    npm i -S raid @raid/streams

    Raid does one job, it helps to manage the state of your application. It does this job by piping action events through streams to observers who then decide what to do with that action.

    An application typically involves a number of different input streams that emit actions, such as a button press action.

    This is a disparate collection of input streams and whilst they were created with Raid in mind they could equally be used with other libraries. They always emit a Raid action signature {type<string>, payload<any>} and they are most.js streams which can be composed together to create more complex inputs.

    See the examples for more detailed usage.

    Streams

    Each collection of input streams typically exports a stream that can be consumed and an enum of actions that may be emitted.

    Keys

    The key streams convert regular key events into reliably emitted events. The natural key repeat behaviour is often inappropriate for applications and registering multi-key combos can get tricky, these input streams simplify listening to such events.

    Keys are referenced using their vkey definitions, i.e. keydown for the enter key emits an event containing key: '<enter>'.

    Actions

    • keydown Initial keydown event, happens only once per key depression.
    • keyup Triggered when the key is released.
    • keypress Emitted regularly on the animation frame whilst a key is pressed.
    • sequence Emits an array of the most recently pressed keys.
    • timedSequence Emits a sequence of keys pressed within a time window.

    Keys

    import { keys, actions } from '@raid/streams/keys'
    import { Signal } from 'raid'
     
    const signal = new Signal({key: ''})
     
    // Mount the keystream to the signal
    signal.mount(keys())
     
    // Respond to key events
    signal.register((state, { type, payload }) => {
      if (type === actions.keydown) {
        state.key = payload.key
      } else {
        state.key = ''
      }
      return state
    })

    keydown

    <Function <Map, Object>> => <Object>

    Keydown attaches to keydown events.

    {
      <Map> keys [required],
      <?Object> options: {
        <?HTMLDomElement> el: window,
        <?String> type: actions.keydown,
        <?Array<String>> exclude: excludeList
      }
    }
     
    signal.mount(keydown(new Map(), {
      el: window
    }))

    type can be used to specify the event type which this stream produces. exclude is a list of vkey definitions to ignore when they fire.

    Keydown fires on initial keydown event when pressing a key and emits an event of the type:

    {
      <String> key,
      <Map> keys,
      <HTMLDomEvent> event
    }
    import { keydown, actions } from '@raid/streams/keys'
     
    signal.mount(keydown(new Map()))
     
    signal.register((state, event) => {
      if (event.type === actions.keydown) {
        state.key = event.payload.key
      }
      return state
    })

    keyup

    <Function <Map, Object>> => <Object>

    Keyup attaches to keyup events.

    {
      <Map> keys [required],
      <?Object> options: {
        <?HTMLDomElement> el: window,
        <?String> type: actions.keyup,
        <?Array<String>> exclude: excludeList
      }
    }
     
    signal.mount(keyup(new Map(), {
      el: window
    }))

    type can be used to specify the event type which this stream produces. exclude is a list of vkey definitions to ignore when they fire.

    Keyup fires when a key is released and emits an event of the type:

    {
      <String> key,
      <Map> keys,
      <HTMLDomEvent> event
    }
    import { keyup, actions } from '@raid/streams/keys'
     
    signal.mount(keyup(new Map(), {
      el: window
    }))
     
    signal.register((state, { type, payload }) => {
      if (type === actions.keyup) {
        state.key = payload.key
      }
      return state
    })

    keys

    Keys is a stream that emits keydown, keyup and keypress events. The keypress event fires when a key is pressed at an interval equalling requestAnimationFrame.

    keys accepts a few parameters; the keymap to use can be shared with other streams and passed in, similarly, an element to attach to can specified. The rate parameter defines how frequently the keypress event will fire.

    Like all other streams, the event type can be specified, however, as keys emits 3 different action types the type parameter is prefixed with :up, :press, and :down to produce the action types emitted from this stream.

    The event signature for keyup and keydown matches the underlying key streams they come from, the keypress event signature is slightly simpler as its only concern is that something has been pressed:

    {
      <?Map> keys: null,
      <?Number> rate: 0,
      <?HTMLDomElement> el: window,
      <?String> type: '@@keys'
    }

    The key map holds how long a key has been pressed for mapped against its vkey definition.

    import { keys, actions } from '@raid/streams/keys'
     
    signal.mount(keys())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.keydown) {
        state.key = payload.key
      }
     
      if (type === actions.keyup) {
        state.key = ''
      }
     
      if (type === actions.keypress) {
        if (payload.keys.has('<enter>')) {
          // Grab the delta of the keypress from the key map
          state.heldDownFor = payload.keys.get('<enter>')
        }
      }
     
      return state
    })

    keySequence

    KeySequence keeps track of the last x keydown events and emits an array of keys.

    KeySequence options object looks like:

    {
      <?Number> length: 10,
      <?Map> keys: null,
      <?String> type: actions.sequence
    }
     
    signal.mount(keySequence({
      length: 10
    }))

    The event signature looks like:

    {
      <Array <String>> keys
    }

    The returned strings reference vkey definitions.

    import { keySequence, actions } from '@raid/streams/keys'
     
    signal.mount(keySequence())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.sequence) {
        state.sequence = payload.keys
      }
     
      return state
    })

    timedKeySequence

    timedKeySequence keeps track of the last x keydown events from the last y ms.

    The options object looks like:

    {
      <?Number> length: 10,
      <?Map> keys: null,
      <?Number> timeout: 200,
      <?String> type: actions.timedSequence
    }
     
    signal.mount(timedKeySequence({
      length: Number.MAX_SAFE_INTEGER,
      timeout: 300
    }))

    The event signature looks like:

    {
      <Array <String>> keys
    }

    The returned strings reference vkey definitions.

    import { timedKeySequence, actions } from '@raid/streams/keys'
     
    signal.mount(timedKeySequence())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.timedSequence) {
        state.sequence = payload.keys
      }
     
      return state
    })

    Tick

    Actions

    • tick Emitted each frame.

    Tick

    Tick stream maps requestAnimationFrame into a stream that emits a frame delta each frame increment.

    By default it attaches to the window but this can be configured:

    {
      <?HTMLDomElement> el: window,
      <?String> type: actions.tick
    }
     
    signal.mount(tick({
      el: document.querySelector('.js-gl')
    }))

    The event signature looks like this and contains the duration of the last frame:

    {
      <Number> dt
    }
    import { tick, actions } from '@raid/streams/tick'
     
    signal.mount(tick())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.tick) {
        state.lastElapsed = payload.dt
      }
     
      return state
    })

    Screen

    Screen streams manage common screen events that the browser might emit, screen emits separate streams for each event or a merged stream.

    import { screen, actions } from '@raid/streams/screen'
     
    signal.mount(screen())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.orientation) {
        state.orientation = payload.orientation
      }
      return state
    })

    Actions

    • resize Debounced resize event with new dimensions.
    • scroll Scroll event with new position.
    • orientation Emitted on the orientationchange event.

    resize

    resize triggers whenever the window changes its size and emits the new dimensions.

    Options object looks like:

    {
      <?Number> debounce: 100,
      <?String> type: actions.resize
    }
     
    signal.mount(resize({
      debounce: 50
    }))

    Event signature looks like:

    {
      <HTMLDomEvent> raw,
      <Number> width,
      <Number> height,
      <Number> timeStamp
    }
    import { resize, actions } from '@raid/streams/screen'
     
    signal.mount(resize())
     
    signal.register((state, { type, payload: { width, height } }) => {
      if (type === actions.resize) {
        state.dimensions = [width, height]
      }
      return state
    })

    scroll

    scroll triggers whenever the window is scrolled and emits the new scroll position.

    {
      <?String> type: actions.scroll
    }
    signal.mount(scroll())

    Event signature looks like:

    {
      <HTMLDomEvent> raw,
      <Number> left,
      <Number> top,
      <Number> timeStamp
    }
    import { scroll, actions } from '@raid/streams/screen'
     
    signal.mount(scroll())
     
    signal.register((state, { type, payload: { left, top } }) => {
      if (type === actions.scroll) {
        state.scrollPosition = [left, top]
      }
      return state
    })

    orientation

    orientation triggers whenever the window orientationchange event is triggered.

    {
      <?String> type: actions.orientation
    }
    signal.mount(orientation())

    Event signature looks like:

    {
      <HTMLDomEvent> raw,
      <Number> angle,
      <Number> orientation,
      <Number> timeStamp
    }
    import { orientation, actions } from '@raid/streams/screen'
     
    signal.mount(orientation())
     
    signal.register((state, { type, payload }) => {
      if (type === actions.orientation) {
        state.orientation = payload.orientation
      }
      return state
    })

    Stand-alone streams

    All these action streams are just regular most.js streams and can be consumed as normal, there is no restriction to use them with Raid. The only tie they have to Raid is that they emit {type, payload} objects. As they are regular streams all the regular stream functions work.

    import { keys, actions } from '@raid/streams/keys'
     
    keystream
      .map(event => ({
        ...event,
        meta: '@@foo'
      }))
      .observe(({ type, payload, meta }) => {
        if (type === actions.keydown) {
          console.log(`Pressing ${payload.key}, meta: ${meta}`)
        }
      })

    Running tests

    $ yarn
    $ yarn test

    Contributing

    Pull requests are always welcome, the project uses the standard code style. Please run yarn test to ensure all tests are passing and add tests for any new features or updates.

    For bugs and feature requests, please create an issue.

    See the root readme for more information about how the repository is structured.

    License

    MIT

    Install

    npm i @raid/streams

    DownloadsWeekly Downloads

    18

    Version

    6.0.0

    License

    MIT

    Unpacked Size

    67.1 kB

    Total Files

    23

    Last publish

    Collaborators

    • avatar