Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
jpodwys committed Apr 20, 2015
1 parent 63a512c commit 1c150eb
Showing 1 changed file with 33 additions and 33 deletions.
66 changes: 33 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Superagent with built-in tiered caching using [cache-service](https://github.com/fs-webdev/cache-service).

## Basic Usage
# Basic Usage

Require and instantiate superagent-cache as follows:
```javascript
Expand All @@ -21,50 +21,50 @@ superagent
```
Enjoy!

## Where does superagent-cache store data?
# Where does superagent-cache store data?

superagent-cache depends on [cache-service](https://github.com/fs-webdev/cache-service) to manage caches and store and retrieve data. cache-service supports any type of cache that has been wrapped in its interface (redis and node-cache wrappers are provided by default). See [cache-service's docs](https://github.com/fs-webdev/cache-service) for the complete API. See the [More Examples](#more-usage-examples) section for more detailed examples on caching specifics.

## Install
# Install

```javascript
npm install superagent-cache
```

## Run Tests
# Run Tests

```javascript
npm test
```

## API
# API

#### require('superagent-cache)(superagent [, cacheServiceConfig])
## require('superagent-cache)(superagent [, cacheServiceConfig])

###### Arguments
#### Arguments

* superagent: an instance of superagent
* cacheServiceConfig: an object that matches one of the following:
* {cacheService: an instance of cache-service}
* the same object you would pass to cache-service's [constructor](https://github.com/jpodwys/cache-service#constructor)

#### .get()
## .get()

Same as superagent except that superagent's response object will be cached.

#### .put(), .del()
## .put(), .del()

Same as superagent except that the generated cache key will be automatically invalidated when these HTTP verbs are used.

#### .responseProp(prop)
## .responseProp(prop)

If you know you want a single, top-level property from superagent's response object, you can optimize what you cache by passing the property's name here. When used, it causes the .end() function's response to return superagent's response[prop].

###### Arguments
#### Arguments

* prop: string

###### Example
#### Example

```javascript
//response will now be replaced with superagent's response.body
Expand All @@ -78,15 +78,15 @@ superagent
);
```

#### .prune(callback (response))
## .prune(callback (response))

If you need to dig several layers into superagent's response, you can do so by passing a function to .prune(). Your prune function will receive superagent's response and should return a truthy value or null.

###### Arguments
#### Arguments

* callback: a function that accepts superagent's response object and returns a truthy value or null

###### Example
#### Example

```javascript
var prune = funtion(r){
Expand All @@ -104,15 +104,15 @@ superagent
);
```

#### .pruneParams(params)
## .pruneParams(params)

In the event that you need certain query params to execute a query but cannot have those params as part of your cache key (useful when security or time-related params are sent), use .pruneParams() to remove those properties. Pass .pruneParams() an array containing the param keys you want omitted from the cache key.

###### Arguments
#### Arguments

* params: array of strings

###### Example
#### Example

```javascript
//the superagent query will be executed with all params
Expand All @@ -127,15 +127,15 @@ superagent
);
```

#### .pruneOptions(options)
## .pruneOptions(options)

This function works just like the .pruneParams() funciton except that it modifies the arguments passed to the .set() chainable method rather than those passed to the .query() chainable method.

###### Arguments
#### Arguments

* options: array of strings

###### Example
#### Example

```javascript
//the superagent query will be executed with all headers
Expand All @@ -150,53 +150,53 @@ superagent
);
```

#### .expiration(seconds)
## .expiration(seconds)

Use this function when you need to override all of your caches' `defaultExpiration` properties (set via cache-service) for a particular cache entry.

###### Arguments
#### Arguments

* seconds: integer

#### .cacheWhenEmpty(bool)
## .cacheWhenEmpty(bool)

Tell superagent-cache whether to cache the response object when it's `false`, `null`, or `{}`.This is especially useful when using .responseProp() or .prune() which can cause response to be falsy. By default, cacheWhenEmpty is true.

###### Arguments
#### Arguments

* bool: boolean, default: true

#### .doQuery(bool)
## .doQuery(bool)

Tell superagent-cache whether to perform an ajax call if the generated cache key is not found. By default, cacheWhenEmpty is true.

###### Arguments
#### Arguments

* bool: boolean, default: true

#### ._end(callback (err, response))
## ._end(callback (err, response))

This is a convenience method that allows you to skip all caching logic and use superagent as normal.

###### Arguments
#### Arguments

* callback: a function that accepts superagent's error and response objects

#### .cacheService
## .cacheService

If you don't have an external reference to superagent-cache's underlying cache-service instance, you can always get to it this way in case you need to manually add/invalidate keys you get from sources other than superagent queries.

###### Example
#### Example

```javascript
superagent.cacheService... //See cache-service's documentation for what you can do here
```

## More Usage Examples
# More Usage Examples

Coming soon.

## Roadmap
# Roadmap

* Make it so superagent-cache's `.end()` callback function does not require an `err` param
* Make sure that `resetProps()` gets called when `._end()` is called directly
Expand Down

0 comments on commit 1c150eb

Please sign in to comment.