Fanboy

The Fanboy Node.js package provides a caching proxy for a subset of the iTunes Search API.

Types

void()

null or undefined.

result(obj)

A map or filter callback applied with each JSON result obj.

• obj The original, JSON parsed, iTunes search result object.

Returns result or void().

The default callback adds the required guid property to obj and returns it.

database()

A Level database.

opts()

The options for the Fanboy cache:

• country = 'us' The country code for the search API.
• hostname = 'itunes.apple.com' The host name of the store.
• max = 500 Number of in-memory non-result terms to save round-trips.
• media = 'all' The media type to search for.
• port = 80 The port to access the store.
• result result()
• ttl = 24 * 3600 * 1000 Time in milliseconds before cached items go stale.

Exports

The main module exports the Fanboy class, a stateful cache object with a persistent Level cache and minor in-memory black-listing. To access the Fanboy class require('fanboy').

Creating a new cache

Fanboy(db, opts)

• db database() The name of the file system directory for the database.
• opts opts() Optional parameters of the cache.

const { Fanboy, createLevelDB } = require('fanboy')

function createCache () {
  const location = '/tmp/fanboy'
  const db = createLevelDB(location)

  return new Fanboy(db, opts())
}

const fanboy = createCache()

Searching the cache

fanboy.search(term, (error, items) => {
  if (error) {
    return console.error(error)
  }

  for (let item of items) {
    console.log(item))
  }
})

This will search remotely and cache the result. Until the term expires subsequent requests hit the cache.

Looking up a guid

fanboy.lookup(guid, (error, item) => {
  if (error) {
    return console.error(error)
  }

  console.log(item))
})

In iTunes you can lookup an item by its guid.

Obtaining suggestions for search terms

fanboy.suggest(term, limit, (error, terms) => {
  if (error) {
    return console.error(error)
  }

  for (let term of terms) {
    console.log(term))
  }
})

The suggestions index must be populated by prior searching to yield results. You can limit the number of suggested terms.

REPL

Try the REPL, its methods let you optionally select a property by name ('collectionName') for clearer output.

$ ./repl
fanboy> search('wnyc', 'collectionName')

Limits

By default the number of result items per term is limited to 50.

Installation

With npm, do:

$ npm install fanboy

License

MIT License