koekiemonster/README.md

Browser and Nodejs compatible cookie interface

# koekiemonster

A node.js compatible version of `cookie-monster`, which is a clone of
`cookie-cutter`. We must fork deeper yessss?

## Installation

The package is released in the public npm registry as `koekiemonster` which is
the dutch name for `cookie monster` and can be installed by running:

```
npm install --save koekiemonster
```

## API

The module returns a single function that requires a reference to document. If
you are in a Node.js environment you can pass in a object instead and it should
still function as intended.

```js
var cookie = require('koekiemonster')(document, { /* advanced options */ });
var times = parseInt(cookie.getItem('times'), 10) || 0;

cookie.setItem('times', times + 1);
```

The first argument is a reference to the `document` so it can access `document.cookie`
the second argument is an object for advanced options. This allows you to specify
a custom `read` and `write` method for cookies.

- `read` Called when it needs to read all cookies and expects an array to be
  returned with `key=cookie` strings for each cookie.
- `write` Called when a cookie needs to be stored, with `cookie`, and `meta`
  as arguments. Assumes it returns the cookie string once it's stored. The `meta`
  is an object that contains the following properties:
  - `remove` Boolean indicating if this is a removal request.
  - `value` Cookie value.
  - `key` Key of the cookie.
  - `opts` Original supplied options.

It's worth noting that if you do not supply `document` as first argument we
will attempt to feature detect the existance of `document` and `document.cookie`
automatically and default to that. In the case where it's missing, we will
default to an empty object so the following will work fine in a browser based
environment:

```js
var cookie = require('koekiemonster')();

console.log(cookie.getItem('items')); // should output the same as above.
```

### getItem(key)

Return the contents of a cookie for the given key name.

### setItem(key, value, opts)

Set a new cookie with the given key as name and value as contents. You can use
the `opts` object to configure the cookie string.

- `expires` Sets the expiree of the cookie.
- `path` Path of the cookie.
- `domain` Domain of the cookie.
- `secure` Should the cookie be secure only.

### removeItem(key, opts)

Remove a cookie with the name of the key. You can use the same `opts` as the
`setItem` method.

#### clear

Remove all cookies.

## License

MIT/X11