# o-is

> Serializable object assertions.

Latest version **0.7.1** (published 2018-01-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install o-is
pnpm add o-is
yarn add o-is
bun add o-is
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.1 |
| Published | 2018-01-05 |
| First published | 2016-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jonathan Boudreau |
| Maintainers | aghost7 |
| Keywords | Assertion, Conditional, Serialization, Storable, Conditions, Validation |

## Links

- npm: https://www.npmjs.com/package/o-is
- npm.io page: https://npm.io/package/o-is

## Dependencies (3)

- [lodash.get](https://npm.io/package/lodash.get.md) ^4.2.1
- [lodash.clone](https://npm.io/package/lodash.clone.md) ^4.3.2
- [lodash.assign](https://npm.io/package/lodash.assign.md) ^4.0.8

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.7.1 (latest) — 2018-01-05
- 0.6.0 — 2017-12-12
- 0.5.2 — 2016-04-23
- 0.5.1 — 2016-04-19
- 0.5.0 — 2016-04-19

## README

Module for testing objects. `o-is` == "Object Is". There's a variety of uses
for this module, such as schema validation.

Motivation for this is that there isn't anything of expressive/flexible enough 
for my needs. The closest thing would have to be Joi, but for some reason there
isn't much in terms of serialization solutions. I also don't like the API...

Performance should be pretty good, since the underlying data structure used to
store the data is already json-convertable (just stringify it). The method
chaining only provides a more fluid api.

```javascript
const oIs = require('o-is');
const test = oIs()
	.equal('foo.bar', 'hello world!')
	.test;

test({
	foo: {
		bar: 'hello world!'
	}
}); // =>  true
```

This module can be useful for creating serializable conditions based on a certain context.
In other words, user defined logic.
```javascript
const data = oIs()
	.null('created')
	.serialize(); // outputs an array of objects ready to be stored.

// ... imagine pulling this out of a db
const test = oIs(data).test;

if(test({ created: new Date() })) {
	sendEmail({...}); // etc...
}

```

## Core Comparison Methods

### `equal(key, value)`
Does a strict equality check against a property in the object.

```javascript
const result = oIs.equal('foo', 1).test({ foo: 1 }) // => true
```

### `propsEqual(key1, key2)`
Does a strict equality check on two properties in the object.

```javascript
const result = oIs()
	.propsEqual('foo', 'bar')
	.test({ foo: 1, bar: 1 }) // => true
```

### `null(key)`
Will be true if the key is equal to null (not strict).

```javascript
const result = oIs().null('foo').test({ foo: null }) // => true
```
### `true(key)`
Checks if the given property is equal to true.

```javascript
const result = oIs().true('foo').test({ foo: false }) // => returns false
```

### `false(key)`
Checks if the given property is equal to false.

```javascript
const result = oIs().false('foo').test({ foo: false }) // => true
```

### `gt(key, value)`
Checks if the given property is greater than the given value.


```javascript
const result1 = oIs().gt('one', 1).test({ one: 1 }) // => false

const result2 = oIs().gt('two', 1).test({ two: 2 }) // => true
```

### `lt(key, value)`
Checks if the given property is less than the given value

```javascript
const result = oIs().lt('one', 2).test({ one: 1 }) // => true
```

### `any(key, values)`
Checks if the given property(key) is equal to any of the values.

```javascript
const result = oIs().any('letter', ['a', 'b']).test({ letter: 'a' }) // => true
```

## Not (Logical Inversion)
When you call `not`, the next method chain's result will be inverted.
```javascript
oIs()
	.not().equal('a', 1)
	.not().exist('c')
	.test({ a: 2 }); // => true
```

## Conditional Properties
```javascript
oIs()
	.if()
		.equal('type', 'human')
	.then()
		.exist('name')
	.end()
	.assert({
		type: 'bear',
		age: 5
	}); // doesn't throw an error
```

## Binding to a specific key
```javascript
oIs()
	.bind('fullName')
	.equal('firstName', 'Jonathan')
	.equal('lastName', 'Boudreau')
	.end()
	.test({
		fullName: {
			firstName: 'Jonathan',
			lastName: 'Boudreau'
		}
	}); // => true
```

## Or Statement
```javascript
oIs()
	.or()
		.equal('a', 1)
		.equal('a', 2)
	.end()
	.test({ a: 2 }); // => true

oIs()
	.or()
		.equal('a', 1)
		.and()
			.equal('a', 2)
			.equal('b', 3)
		.end()
	.end()
	.test({ a: 2, b: 3 }) // => true
```

## Composition
Because the instances are immutable, you can use an existing instance to
concatenate it with another.
```javascript
// you can currently do this
const cond = oIs().equal('name', 'Jonathan');
// You get a new object which will test for both properties.
const merged = oIs().equal('fullName.lastName', 'Boudreau').concat(cond);
```

## Extensions
This module is somewhat extendable. The first argument is the series of asserts runners,
and the second argument is the set of methods to add to the builder.
```javascript
const objectIs = oIs.extend({
	foo(context, args) {
		return oIs.get(context, args.key) === 'bar';
	}
}, {
	foo(key) {
		return this.concat({
			type: 'foo', // this specifies what assertion to call
			key
		});
	}
});

objectIs
	.foo('a')
	.exist('today') // previous methods remain, but they can be overriden.
	.test({ today: new Date(), a: 'bar' }); // returns true!
```

Or even...

```javascript
const eql = require('deep-eql');
const objectIs = oIs.extend({
	eql(context, args) {
		return eql(args.compare);
	}
}, {
	eql(compare) {
		return this.concat({
			type: 'eql',
			compare
		});
	}
});

```

To keep this module lightweight I decided to not include a ton of depdencies.
Instead the module aims to be extendable for your specific needs. Mainly, this
module defines a "grammar", you can add whatever "nouns" you want.

---
_Source: https://npm.io/package/o-is · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._