# its

> Preconditions for safe coding

Latest version **1.0.2** (published 2013-01-24) · 0 weekly downloads

## Install

```sh
npm install its
pnpm add its
yarn add its
bun add its
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2013-01-24 |
| First published | 2013-01-19 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ozan Turgut |
| Maintainers | ozanturgut |
| Keywords | test, it, its, is, assertion, assert, precondition |

## Links

- npm: https://www.npmjs.com/package/its
- Repository: https://github.com/ozanturgut/its
- npm.io page: https://npm.io/package/its

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2013-01-24
- 1.0.0 — 2013-01-19

## README

# its [![Build Status](https://secure.travis-ci.org/ozanturgut/its.png?branch=master)](http://travis-ci.org/ozanturgut/its)

Its a utility to simplify common precondition or state checking. It's useful for signaling
to calling methods when they've made invalid calls to a method.

## Usage
There are four available functions:
* `its(expression [, errorType] [, messageTemplate [, messageArgs...]])` for throwing custom errors
* `its.defined(expression [, messageTemplate [, messageArgs...]])` for throwing reference errors
* `its.range(expression [, messageTemplate [, messageArgs...]])` for throwing range errors
* `its.type(expression [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.undefined(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.null(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.boolean(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.array(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.object(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.func(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.args(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.string(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.number(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.date(obj [, messageTemplate [, messageArgs...]])` for throwing type errors
    * `its.regexp(obj [, messageTemplate [, messageArgs...]])` for throwing type errors

`expression` is a boolean value which determines whether the precondition will throw an error or not.

`messageTemplate` is a message with 0 or more '%s' placeholders for message arguments

`messageArgs` is a variable argument (0 or more) to fill the placeholders in the message template

`errorType` is used for throwing custom error objects. These objects should inherit from `Error`.

## Examples
```javascript
// Things that should pass
its.string('hi'); // returns true
its.func(function(){}); // returns true
its.date(new Date); //returns true
its.defined("anything"); // returns "anything"
its.type(typeof "something" === "string"); // returns true
its.range(1 < 2 && 1 > 0); // returns true
its(1 === 1); // returns true
its(1 === 1, ReferenceError); // throws true

// Things that shouldn't pass
its.defined(void 0); // throws ReferenceError
its.type(typeof "something" === "number"); // throws TypeError
its.range(1 < 2 && 1 > 2); // throws RangeError
its(1 !== 1); // throws Error
its(1 === void 0, ReferenceError); // throws ReferenceError

// Messages
its.defined(void 0, "This doesn't look right."); // throws ReferenceError with a message of "This doesn't look right."
its.defined(void 0, "This doesn't look %s.", "right"); // throws ReferenceError with a message of "This doesn't look right."
its.defined(void 0, "%s doesn't look %s.", "This", "right"); // throws ReferenceError with a message of "This doesn't look right."

// What real use may look like
var addOnlyNumbersBelow100 = function(number1, number2){
	its.number(number1);
	its.number(number2);
	its.range(number1 < 100);
	its.range(number2 < 100);
	return number1 + number2;
};

addOnlyNumbersBelow100(10, 20); // returns 30
addOnlyNumbersBelow100(10, 338484); // throws RangeError
addOnlyNumbersBelow100("10", 338484); // throws TypeError
```

## Developing
its uses grunt to build.
* `grunt` - Builds the standard and minified version of precondition in the dist folder
* `grunt test` - Builds precondition and runs unit tests (requires PhantomJS)

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