Omniscient API Reference Edit on GitHub

Originally posted

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

param type description
displayName String Component’s display name. Used when debug()’ing and by React
mixins Array,Object React mixins. Object literals with functions, or array of object literals with functions.
render Function Stateless component to add memoization on.

Properties

property type description
shouldComponentUpdate Function Get default shouldComponentUpdate

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

param type description
Options Object Options with defaults to override

Properties

property type description
shouldComponentUpdate Function Get default shouldComponentUpdate

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

param type description
pattern RegExp Filter pattern. Only show messages matching pattern

Example

omniscient.debug(/Search/i);

Returns Immstruct,

Component(displayName, props, ...rest)

Invoke component (rendering it)

Parameters

param type description
displayName String Component display name. Used in debug and by React
props Object Properties (triggers update when changed). Can be cursors, object and immutable structures
...rest Object Child components (React elements, scalar values)

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

param type description
nextProps Object Next props. Can be objects of cursors, values or immutable structures
nextState Object Next state. Can be objects of values or immutable structures

Properties

property type description
isCursor Function Get default isCursor
isEqualState Function Get default isEqualState
isEqualProps Function Get default isEqualProps
isEqualCursor Function Get default isEqualCursor
isImmutable Function Get default isImmutable
isIgnorable Function Get default isIgnorable
debug Function Get default debug

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

param type description
[Options] Object optional: Options with defaults to override

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

param type description
value Object  
other Object  

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

param type description
value Object  
other Object  

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

param type description
a Cursor  
b Cursor  

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

param type description
value maybeImmutable to check if it is immutable.

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

param type description
cursor cursor to transform

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

param type description
potential potential to check if is cursor

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

param type description
value Object  
key String  

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

param type description
Function Function that does a computation.

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

param type description
[Options] Object optional: Options with defaults to override

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

param type description
propValue String Property value to check if is valid React Node

Returns Boolean,