Omniscient API Reference Edit on GitHub

omniscient(displayName, mixins, render)

Create components for functional views.

The API of Omniscient is pretty simple, you create a Stateless React Component but memoized with a smart implemented shouldComponentUpdate.

The provided shouldComponentUpdate handles immutable data and cursors by default. It also falls back to a deep value check if passed props isn’t immutable structures.

You can use an Omniscient component in the same way you’d use a React Stateless Function, or you can use some of the additional features, such as string defined display name and pass in life cycle methods. These are features normally not accessible for vanilla Stateless React Components.

If you simply pass one cursor, the cursor will be accessible on the props.cursor accessor.

Parameters

Properties

Returns Component,

omniscient.withDefaults(Options)

Create a “local” instance of the Omniscient component creator by using the .withDefaults method. This also allows you to override any defaults that Omniscient use to check equality of objects, unwrap cursors, etc.

Options

{
  // Goes directly to component
  shouldComponentUpdate: function(nextProps, nextState), // check update
  cursorField: '__singleCursor', // cursor property name to "unwrap" before passing in to render
  isNode: function(propValue), // determines if propValue is a valid React node
  classDecorator: function(Component), // Allows for decorating created class

  // Passed on to `shouldComponentUpdate`
  isCursor: function (cursor), // check if is props
  isEqualCursor: function (oneCursor, otherCursor), // check cursor
  isEqualState: function (currentState, nextState), // check state
  isImmutable: function (currentState, nextState), // check if object is immutable
  isEqualProps: function (currentProps, nextProps), // check props
  isIgnorable: function (propertyValue, propertyKey), // check if property item is ignorable
  unCursor: function (cursor) // convert from cursor to object
}

Examples

Un-wrapping curors

var localComponent = component.withDefaults({
  cursorField: 'foobar'
});

var Component = localComponent(function (myCursor) {
  // Now you have myCursor directly instead of having to do props.foobar
});

React.render(, mountingPoint);

Decorating class components

// Some third party libraries requires you to decorate the
// React class, not the created component. You can do that
// by creating a decorated component factory
var decoratedComponent = component.withDefaults({
  classDecorator: compose(Radium, function (Component) {
    var DecoratedComponent = doSomething(Component);
    return DecoratedComponent;
  })
});

var Component = decoratedComponent(function (props) {
  // ... some implementation
});

React.render(, mountingPoint);

Parameters

Properties

Returns Component,

omniscient.debug(pattern)

Activate debugging for components. Will log when a component renders, the outcome of shouldComponentUpdate, and why the component re-renders.

Example

Search>: shouldComponentUpdate => true (cursors have changed)
Search>: render
SearchBox>: shouldComponentUpdate => true (cursors have changed)
SearchBox>: render

Parameters

Example

omniscient.debug(/Search/i);

Returns Immstruct,

Component(displayName, props, ...rest)

Invoke component (rendering it)

Parameters

Returns ReactElement,

shouldComponentUpdate(nextProps, nextState)

Directly fetch shouldComponentUpdate mixin to use outside of Omniscient. You can do this if you don’t want to use Omniscients syntactic sugar.

Parameters

Properties

Returns Component,

shouldComponentUpdate.withDefaults([Options])

Create a “local” instance of the shouldComponentUpdate with overriden defaults.

Options

{
  isCursor: function (cursor), // check if is props
  isEqualCursor: function (oneCursor, otherCursor), // check cursor
  isEqualState: function (currentState, nextState), // check state
  isImmutable: function (currentState, nextState), // check if object is immutable
  isEqualProps: function (currentProps, nextProps), // check props
  isIgnorable: function (propertyValue, propertyKey), // check if property item is ignorable
  unCursor: function (cursor) // convert from cursor to object
}

Parameters

Returns Function, shouldComponentUpdate with overriden defaults

shouldComponentUpdate.isEqualState(value, other)

Predicate to check if state is equal. Checks in the tree for immutable structures and if it is, check by reference. Does not support cursors.

Override through shouldComponentUpdate.withDefaults.

Parameters

Returns Boolean,

shouldComponentUpdate.isEqualProps(value, other)

Predicate to check if props are equal. Checks in the tree for cursors and immutable structures and if it is, check by reference.

Override through shouldComponentUpdate.withDefaults.

Parameters

Returns Boolean,

shouldComponentUpdate.isEqualCursor(a, b)

Predicate to check if cursors are equal through reference checks. Uses unCursor. Override through shouldComponentUpdate.withDefaults to support different cursor implementations.

Parameters

Returns Boolean,

shouldComponentUpdate.isImmutable(value)

Predicate to check if a potential is an immutable structure or not. Override through shouldComponentUpdate.withDefaults to support different cursor implementations.

Parameters

Returns Boolean,

shouldComponentUpdate.unCursor(cursor)

Transforming function to take in cursor and return a non-cursor. Override through shouldComponentUpdate.withDefaults to support different cursor implementations.

Parameters

Returns Object,Number,String,Boolean,

shouldComponentUpdate.isCursor(potential)

Predicate to check if potential is Immutable cursor or not (defaults to duck testing Immutable.js cursors). Can override through .withDefaults().

Parameters

Returns Boolean,

shouldComponentUpdate.isIgnorable(value, key)

Predicate to check if a property on props should be ignored or not. For now this defaults to ignore if property key is statics, but that is deprecated behaviour, and will be removed by the next major release.

Override through shouldComponentUpdate.withDefaults.

Parameters

Returns Boolean,

cached(Function)

Directly fetch cache to use outside of Omniscient. You can do this if you want to define functions that caches computed result to avoid recomputing if invoked with equal arguments as last time.

Returns optimized version of given f function for repeated calls with an equal inputs. Returned function caches last input and a result of the computation for it, which is handy for optimizing render when computations are run on unchanged parts of state. Although note that only last result is cached so it is not practical to call it mulitple times with in the same render call.

Parameters

Returns Function, Optimized function

cached.withDefaults([Options])

Create a “local” instance of the cache with overriden defaults.

Options

{
  isEqualProps: function (currentProps, nextProps), // check props
}

Parameters

Returns Function, cached with overriden defaults

Private members

isNode(propValue)

Predicate showing whether or not the argument is a valid React Node or not. Can be numbers, strings, bools, and React Elements.

React’s isNode check from ReactPropTypes validator but adjusted to not accept objects to avoid collision with props.

Parameters

Returns Boolean,