apitree.js

Node.js module to create a SocketStream-style API tree from a file system directory.

Installation

npm install apitree

Usage

Call createApiTree to load all files in the given directory (and its subdirectories) and return an object, such that returnedObject.foo.bar.boz.fubar equals to exported function fubar of file boz in subdirectory foo/bar of the given directory. (Some of the described details are customizable via optional callbacks.)

Example:

var apitree = require('apitree');
var path    = require('path');

var api = apitree.createApiTree(path.join(__dirname, 'apiroot'))

api.somefile.func1(42);
api.sub.folder.anotherfile.func2(24);

createApiTree function accepts 2 arguments:

apitree.createApiTree(directory, options)

where options is an optional object with 3 possible keys:

• options.loadItem(path) loads the contents of file at path; returns either null or an object that will be merged into the tree; the default value is require.
• options.filter(name, names) determines whether given file should be processed or ignored; other names from the same directory are provided as the second argument; the default implementation returns true for .js files and files with a registered extension in require.extensions which don't have corresponding .js files. (Exludes .json files)
• options.nameToKey(name) returns a key to use in the tree object for the given file or folder name; the default implementation strips the file extension and replaces any non-identifier characters with underscores.

Additionally, options.readdirSync(directory) and options.isDirectory(path) can be provided to override the standard behavior of reading from the file system.

Somewhat more realistic example

See example/ directory. In CoffeeScript:

global.DB =
  put: (collection, object) ->
    @[collection].push object
    console.log "Added to #{collection}: #{JSON.stringify(object)}"

path = require 'path'
global.S = require('apitree').createApiTree(path.join(__dirname, 'server'))

S.app.init()
userId = S.users.create(name: 'admin', password: 'admin123')
postId = S.blog.posts.publish(authorId: userId, title: "Hello!", body: "Hey! This is my first post.")
S.blog.comments.publish(postId: postId, author: "Random Visitor", body: "Very excited about your new blog.")
S.blog.comments.publish(postId: postId, author: "spa.m@mer.go.ddam.it", body: "Send Your Name, Address...")

example/server/app.coffee:

exports.init = ->
  DB.users    = []
  DB.posts    = []
  DB.comments = []

example/server/users.coffee:

exports.create = ({ name, password }) ->
  user = { name, password, id: DB.users.length }
  DB.put 'users', user
  user.id

example/server/blog/posts.coffee:

exports.publish = ({authorId, title, body}) ->
  post = { authorId, title, body, id: DB.posts.length }
  DB.put 'posts', post
  post.id

example/server/blog/comments.coffee:

exports.publish = ({postId, author, body}) ->
  comment = { postId, author, body, id: DB.comments.length }
  DB.put 'comments', comment
  comment.id

Spec

Uses mocha, run npm test to execute tests.

API tree
    when given an empty folder
      ✓ should return an empty tree
    when given a folder with a single file
      ✓ should put the file node under the tree root
      ✓ should strip the extension when naming the tree node
      ✓ should put the file's contents under its node
    when given a file and a subfolder
      ✓ should put the file and subfolder nodes together under the tree root
    when given a file and a subfolder which have the same name after stripping extensions
      ✓ should merge the file and the subfolder into a single node under the tree root
    when given a folder hierarchy with nested subfolders
      ✓ should reproduce the folder hierarachy inside the API tree
    loadItem callback
      ✓ should be used to obtain file contents
    nameToKey callback
      ✓ should accept file name as the only argument
      ✓ should be used to translate file names into tree keys
      ✓ should be used to translate subfolder names into tree keys
      ✓ should not be used to modify keys returned by loadItem
    default nameToKey callback
      ✓ should strip file extension
      ✓ should replace any non-identifier characters with underscores
      ✓ should replace runs of multiple non-identifier characters with a single underscore
    filter callback
      ✓ should accept file name as the first argument
      ✓ should accept the list of all file names in the same folder as the second argument
      ✓ should be used to choose which files to process
      ✓ should have no effect on which folders are processed
    default filter callback
      ✓ should include .js files
      ✓ should include .coffee files that don't have corresponding .js files
      ✓ should include registered extension files that don't have corresponding .js files
      ✓ should only include .js file when both .js and .coffee files exist
      ✓ should only include .js file when both registered extension file and .js files exist
      ✓ should not include any other files

✔ 25 tests complete (47ms)

License

MIT license. Copyright 2011–2012, Andrey Tarantsov.