README

ok.js

ok.js is a small object utility library for manipulating and testing object properties.

Installation

ok.js is available for both node.js and browser.

Through npm:
  npm install ok-js --save

Through bower
  bower install ok-js

Or build it yourself. Get the latest from git here and gulp build from the root directory.

What does it do?

I got sick of writing long, ugly lines of code to test and set defaults on nested object properties all the time, so i wrote this. I hope you find it useful.

ok-js aims to clean up the following situations:

// testing nested object properties
if (some && some.nested && some.nested.property) {
  doSomething();
}

// setting defaults on nested object properties
this.object = this.object || {};
this.object.should = this.object.should || {};
this.object.should.exist = this.object.should.exist || [];

// getting a nested property
var h = ((session || {}).user || {}).name || 'Spiderman';

At a glance

var make = { it: null };

// instead of this (yuk)
make.it = make.it || {};
make.it.look = make.it.look || {};
make.is.look.nice = make.it.look.nice || true;

// do this
ok.ensure(make, 'it.look.nice', true);

API

ok.ensure(context, [path], value)

Ensure a property exists at a given path within a given context.
If the resolved property is either null or undefined then the given value will be set.
If the given context is null or undefined, ensure will return a new object with this property set.

arguments
- context: Object - The context in which to ensure the property exists.
- path: String - An optional path to a property. To target nested properties delimit with dots ..
- value: Any - the value to set.
returns the given context or a new Object if context was null or undefined.

ok.get(context, path, [default])

Get the property specified by path within the given context.
The default will be returned, if specified, only when get yields null or undefined.

arguments
- context: Object - The context in which to find the property.
- path: String - The path to a property. To target nested properties delimit with dots ..
- default: Any - An optional value to return when get yields null or undefined.
returns the resolved property or default value.

ok.set(context, path, value)

Set the property specified by path within the given context to value.
If context is null or undefined, set will return a new object.

arguments
- context: Object - The context in which to set the property.
- path: String - The path to a property. To target nested properties delimit with dots ..
- value: Any - The value to set.
returns the given context or a new Object if context was null or undefined.

ok.check(context, [path])

Get an Assertion object which can be used to test the resolved property.

Inspired by chaijs, the assertion supports chainable .is and .not getters to be used in conjunction with the following complete list of endpoints:

  var it = ok.check(foo, 'bar.baz');
    // each of the following return a boolean

    // use it with the following functions:
    it.is.truthy();
    it.is.falsy();

    it.is.typeof('string'); // typeof operator
    it.is.kindof('array'); // same as typeof but distinguises null and array
    it.is.instanceof(String);

    it.equals(123); // ===
    it.is.gt(Infinity); // >
    it.is.gte(9000); // >=
    it.is.lt(0); // <
    it.is.lte(567); // <=

    // or these getters
    it.is.undefined; // === undefined
    it.is.defined; // !== undefined
    it.is.null; // === null
    it.is.value; // != null
    it.is.primitive; // null|undefined|String|Boolean|Number

    // NOTE: negate the assertion using `.not` before the endpoint.
    // NOTE: `.is` is merely aesthetic, and can be safely omitted.

ok.config()

config accepts either:

A single argument - an Object of key-value pairs to set multiple config options.
Two arguments - a String key and Any value to set a single config option.
A single argument - a String identifying a config value to get.

options

options.seperator [default = `'.'`]

A String to use as the separating character/pattern between object keys in the path parameter of ok.ensure, ok.get, ok.set and ok.check.

// by default
kkthxbye = ok.get(foo, 'kk.thx.bye');

// using a different seperator
ok.config('seperator', '_');
kkthxbye = ok.get(foo, 'kk_thx_bye');

Issues and Requests

Please submit any issues or feature requests to the repository's github issue tracker.

Version History

v0.1.0 - Initial release
v0.2.0 - Added instanceof and .primitive to check API
v0.2.2 - Fixed an issue with ok.get when property is null or undefined

Usage no npm install needed!