# annotate

> Asserts your function invariants

Latest version **0.9.1** (published 2014-04-28) · 0 weekly downloads

## Install

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

## 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.9.1 |
| Published | 2014-04-28 |
| First published | 2013-02-10 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Juho Vepsalainen |
| Maintainers | bebraw |
| Keywords | testing, utilities |

## Links

- npm: https://www.npmjs.com/package/annotate
- Repository: git@github.com:annojs/annotate
- Homepage: https://github.com/annojs/annotate
- Issues: https://github.com/annojs/annotate/issues
- npm.io page: https://npm.io/package/annotate

## Dependencies (1)

- [annois](https://npm.io/package/annois.md) 0.3.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 0.9.1 (latest) — 2014-04-28
- 0.9.0 — 2013-12-23
- 0.8.0 — 2013-12-23
- 0.7.0 — 2013-06-29
- 0.6.7 — 2013-04-19
- 0.6.6 — 2013-04-16
- 0.6.5 — 2013-02-15
- 0.6.4 — 2013-02-15
- 0.6.3 — 2013-02-15
- 0.6.2 — 2013-02-10

## README

[![build status](https://secure.travis-ci.org/annojs/annotate)](http://travis-ci.org/annojs/annotate)
# annotate - Annotate your JavaScript function definitions

`annotate` allows you to ... guess what ... annotate your functions. For
instance you could document invariants of your function. Or attach a
description to it. It is possible to access this data later on.

This metadata can be used by tools such as [annofuzz](https://github.com/annojs/fuzz)
in order to generate tests. In addition you can access the metadata via REPL.

The usage is quite simple as the following example illustrates:

```javascript
// let's define some function to annotate
function add(a, b) {
    return a + b;
}

// type checkers from annois (https://npmjs.org/package/annois)
var addNumbers = annotate('addNumbers', 'Adds numbers').
    on(is.number, is.number, add);
var addStrings = annotate('addStrings', 'Adds strings').
    on(is.string, is.string, add);

// you can assert invariants too
var addPositive = annotate('addPositive', 'Adds positive').
    on(isPositive, isPositive, add).
    satisfies(isPositive); // postcondition

// it is possible to chain guards
var fib = annotate('fib', 'Calculates Fibonacci numbers').
    on(0, 0).on(1, 1).
    on(is.number, function(n) {
        return fib(n - 1) + fib(n - 2);
    });

// invariants may depend on each other
var clamp = annotate('clamp', 'Clamps given number between given bounds').
    on(is.number, is.number, function(a, args) {
        return is.number(a) && args[1] <= a;
    }, function(a, min, max) {
        return Math.max(Math.min(a, max), min);
    });

// furthermore it is possible to pass a variable amount of args
var min = annotate('min', 'Returns minimum of the given numbers').
    on([is.number], Math.min);

function isPositive(a) {
    return a >= 0;
}
```

The `annotate` function will create a new function that contains the metadata as
properties `_name`, `_doc`, `_preconditions` and `_postconditions`. In case
some pre- or postcondition doesn't pass it won't return and gives a warning
instead.

## Related Projects

* [suite.js](https://github.com/bebraw/suite.js) - Constructs tests based on invariant data (fuzzing)
* [funkit](https://github.com/bebraw/funkit) - Collection of utilities tested using `annotate.js` and `suite.js`

## Acknowledgements

* [Kris Jordan](http://krisjordan.com/)'s [multimethod.js](http://krisjordan.com/multimethod-js) - Provided inspiration for the API

## License

`annotate` is available under MIT. See LICENSE for more details.

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