Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Build Status

Noddity Butler

A library for interacting with a Noddity blog server thingy.


var Butler = require('noddity-butler')
var butler = new Butler(noddityUrlString | noddityRetrieval, levelUpDb, [options])
  • noddityUrlString | noddityRetrieval - can be either the url of a noddity root directory containing an index.json, or a noddity-retrieval object
  • levelUpDb - any levelUP object
  • options - an optional object with two properties:
    • refreshEvery: in milliseconds, how often the butler should automatically check the server to see if the index or a post has changed. Defaults to 12 hours for posts and 10 minutes for the index
    • cacheCheckIntervalMs: passed to the expire-unused-keys library to determine how often it should check to see if anything needs to be refreshed. Defaults to 1000ms,
    • loadPostsOnIndexChange: defaults to true. If true, any posts that do not exist locally will be downloaded whenever the index.json file changes (including the first time the butler is instantiated with an empty cache).
    • parallelPostRequests: defaults to undefined. If set to a number, the butler will make sure that no more than that number of requests for posts are happening at a time. See these browser limits on XHRs - maybe consider limiting it to 4 or so.


All callbacks are called with the error-first argument convention.

butler.getPosts([options], cb)

options is an optional object with these properties:

  • local: if true, will only return posts that have already been downloaded locally - if some of the files listed in the index.json haven't been downloaded yet, they will not be returned. If false, it makes sure that every file listed in the index.json has finished downloading before calling the callback. This usually only matters in the first few seconds after launching a butler and calling getPosts the first time. Defaults to false.
  • mostRecent: the number of recent posts to limit to - if you only need to get most recent 5 posts (sorted by the date metadata at the top of the post file), pass in 5. Defaults to undefined.

butler.getPost(filename, cb)

Produces the most recent cached post object for the given filename.

butler.getPost('', function(err, post) {
	console.log('this post was created on',
	console.log('words of wisdom:', post.content)


Returns true if all of the posts listed in the index.json file have been downloaded and are cached locally.

butler.refreshPost(filename, [cb])

Updates the cache by downloading the latest version of the post from the server. The optional callback returns the post.

butler.removePost(filename, [cb])

Removes the post from the cache.


Updates the cache by downloading the latest version of the index.json from the server. The optional callback returns the index.json contents as an array.


Makes the butler stop automatically refreshing content from the server.


These events do fire the first time an item is added to the cache.

  • post changed - emitted when a post is refreshed from the server and its metadata or content is different from the cached version. Emits the new post object.
  • index changed - emitted when the index.json is refreshed from the server and a file has been added to or removed from the index.json, or if the order has changed.




Hustles and bustles around, bringing you blog posts at your whim






No packages published