Kefir Extra

A collection of combinators and helpers for the Kefir library.

import * as K from 'kefir-extra'
 
const bus = K.createPropertyBus('INITIAL')
const combined = K.combinePropertyObject({
  a: bus.property,
  b: K.constant(true),
})
 
combined.log()
// {a: 'INITIAL', b: true}
 
bus.set('OTHER')
// {a: 'OTHER', b: true}

API

The kefir-extra module exports all functions from the kefir package at version v3.6.1 plus the following.

import * as K from 'kefir-extra'

createStreamBus() | createPropertyBus() | combinePropertyObject() | eventSum() | onValue() | getValue() | getRef() | promiseProperty() | sampleFrom()

import * as KM from 'kefir-extra/mock'

createProperty() | createStream()

K.createStreamBus()

Create a bus that allows you to emit values on a stream.

const bus = K.createStreamBus()
bus.stream.log()
bus.emit('VALUE')
// <value> 'VALUE'
bus.end()
// <end>

The returned bus object has the following properties

• stream: Stream<T>
• emit(T): void
• end(): void

K.createPropertyBus(initial)

Create a bus that allows you to set the current value of a property.

const bus = K.createPropertyBus('INITIAL')
bus.property.log()
// <value:current> 'INITIAL'
bus.set('VALUE')
// <value> 'VALUE'
bus.end()
// <end>

The returned bus object has the following properties

• property: Stream<T>
• set(T): void
• end(): void

K.combinePropertyObject(props)

Combines an object with properties as values into a property whose current value is an object combining the current values.

const combined = K.combinePropertyObject({
  a: K.constant('A'),
  b: K.constant('B'),
})
combined.log()
// <value:current> {a: 'A', b: 'B'}

Note that this function asserts that all values in the argument are properties.

K.eventSum(events)

Since v0.5.2

Merges events by wrapping values in a {type, value} pair.

const sum = K.eventSum({
  a: K.sequentially(7, ['a1', 'a2'])
  b: K.sequentially(10, ['b1'])
})
sum.log()
//  7ms { type: 'a', value: 'a1' }
// 10ms { type: 'b', value: 'b2' }
// 14ms { type: 'a', value: 'a2' }

K.onValue(obs, handler)

Add a handler to be called when the observable emits a value.

Returns a function that unsubcribes the handler.

const off = K.onValue(obs, function (val) {
  console.log(val)
})
// Prints values
off()

While the handler is subscribed we throw all errors on the stream.

K.getValue(property)

Since v0.5.1

Gets the current value of a property and throws an error if the property does not have a value.

const p = K.constant('A')
K.getValue(p) // => 'A'

Calling this function might have side-effects since we subscribe to the property and then immediately unsubscribe again.

WARNING: Use this sparsely. Using this leads to un-idomatic code.

K.getRef(property)

Since v0.5.3

Returns a reference object to the current value of the property.

const ref = K.getRef(prop)
ref.value // => current value
ref.dispose() // => unsubcribes once and for all

The function subscribes to the property immediately and sets the value property of the reference object.

The reference object also has a dispose() function that unsubscribes from the property. In addition it cleans up the reference deleting both the value and dispose properties.

K.promiseProperty(promise)

Since v0.5.1

Turns a promise into a property that holds a promise state object.

The promise state object has a state property that is either 'pending', 'resolved', or 'rejected'. If the state is “resolved” then the object has a value property holding the resolved value. If the state is “rejected” the object has an error property.

K.promiseProperty(promise)
.onValue((state) => {
  if (state.state === 'pending') {
    console.log('pending')
  } else if (state.state === 'resolved') {
    console.log('resolved', state.value)
  } else if (state.state === 'rejected') {
    console.log('rejected', state.error)
  }
})

K.sampleFrom(obs, sampler)

Since v0.5.3

Create a property that is updated whenever the observable emits a new event. The sampler function is used to obtain the value.

const prop = K.sampleFrom(obs, () => {
  // called on initial subscription and whenever obs emits a new event
 
  // Return the current property value
  return value
})

KM.createProperty(initial)

Returns an object that has the same interface as a Kefir property and the additional set(value) and end() methods. These methods can be used to control the state of the property.

You should only use this for testing purposes.

KM.createStream()

Returns an object that has the same interface as a Kefir stream and the additional emit(value) and end() methods. These methods can be used to control the state of the stream.

You should only use this for testing purposes.