Hapi-footprints NPM

hapi-footprints

Docs WIP

Api-generator for hapi, using dogwater, which uses waterline.
Originally created for frill.
Configures hapi-swagger by default

Some codes are borrowed from bedwetter, which is an alternative for hapi-footprints.

Usage

$ npm install hapi-footprints --save

// ES6 Syntax
import Footprints from 'hapi-footprints';

API

`const footprints = new Footprints(options, overrideRoutes)`

Creates a new instance of footprint.

options (Object) Optional

prefix (string)
- Defaults to: /api
- Prefix for the routes created by footprints
excludeModels (Array)
- Defaults to: []
- Example: ['user', 'post']
- An array of model names to exclude from creating the routes.
excludeActions (Object)
- Defaults to: {}
- Example: {modelName: ['find', 'remove']}
- An object for excluding a particular action or actions.
routeDefaults (Object)
- Defaults to: {}
- Example: {config: {tags: ['api']}}
- An object which will be merged to every routes generated. Useful adding configurations for hapi.
cache (Object or false)
- Defaults to:
```
{
  cache: 'redisCache',
  expiresIn: 1000 * 60 * 5,
  segment: '!footprints',
  generateTimeout: 300,
}
```
- Disables cache when false, else configurations are passed down to hapi's server method's options. Caching is available for find, findCount, findOne actions. See here for more information about actions.

handler (Object)

See the comment-outs below for description of each keys available
Defaults to:

{
  // name of handler to register
  name: 'footprints',

  // override default options of the handler
  options: {
    // will be deleted
    model: null,

    // enable cache for this footprint
    // works only on 'GET' method actions
    cache: true,

    // function to inject before executing a query to the database
    // could be used for caching the response, custom errors, etc.
    // it is injected before caching, therefore caching will not work.
    // NOTE: this option will not be executed in association routes
    // example: (query, options, callback) => { query.exec(callback) };
    injectBeforeQuery: false,

    // primaryKey of model, defaults to 'id' when set to false
    primaryKey: false,

    // paginations
    pagination: true,

    // default limits for 'find'
    limit: 30,

    // max limit for 'find'
    maxLimit: 30,

    // default offset
    offset: 0,

    // soft deletes
    softDelete: {
      // enable soft deletes
      enabled: true,
      // set attribute for soft deletes
      attr: 'deletedAt',
    },

    // population
    populateByDefault: true,
    populateLimit: 30,

    // associations
    child: {
      // primaryKey for the child model
      primaryKey: false,
    },
  },
}

overrideRoutes (Object) Optional

Route configurations for specific route-actions.
Example:

  {
    modelName: {
      find: {
        // any hapi route configurations here,
        // but NOT "path" or "method", footprints will throw an error.
      },
      findCount: {},
      findOne: {},
      create: {},
      update: {},
      populate: {},
      populateWithId: {},
      populateCount: {},
      add: {},
      addWithId: {},
      destroy: {},
      remove: {},
    },
    // and so on...
  }

`footprints.plugin()`

Returns a plugin for hapi. See here for more about hapi's plugin.

Example

import hapi from 'hapi';
import dogwater from 'dogwater';
import models from './someModelFile.js';
import overrideRoutes from './someOtherFile.js';

const server = new Hapi.Server();
server.connection({ port: 3000 });

const footprints = new Footprints({
  // configurations for footprints...
}, overrideRoutes);

server.register([
  {
    register: dogwater,
    options: {
      models: models,
      // ... configurations for dogwater
    },
  },
  footprints.plugin(),
], (err) => {});

server.start(function () {
  console.log('Server running at:', server.info.uri);
});

Exposed by plugin

a handler, with a name passed in with options.handler.name
- this handler is used for the actual route.handler, and can be used inside the overrideRoutes
a server method called cacheQuery, when options.cache is not disabled.
- this server method is used for caching wateline model's query, by the criteria used in the query

Example of generated routes

GET /api/users
- Action name: find
- Find all users records
GET /api/users/count
- Action name: findCount
- Count all users records
GET /api/users/{id}
- Action name: findOne
- Find one user record
POST /api/users
- Action name: create
- Create a new user
POST, PATCH /api/users/{id}
- Action name: update
- Update user with {id}
GET /api/users/{id}/associatedModel
- Action name: populate
- Get all associated records for a user (records are associatedModel, in this case)
GET /api/users/{id}/associatedModel/{childId}
- Action name: populateWithId
- Get One associated record for user (associatedModel, in this case)
GET /api/users/{id}/associatedModel/count
- Action name: populateCount
- Count all associated records (count of associatedModels, in this case)
POST /api/users/{id}/associatedModel
- Action name: add
- Create a new associatedModel record, and adds a relation to the user with {id}
POST /api/users/{id}/associatedModel/{childId}
- Action name: addWithId
- Associates associatedModel with {childId}, with the user with {id}
DELETE /api/users/{id}
- Action name: destroy
- Deletes a user with {id}
DELETE /api/users/{id}/associatedModel/{childId}
- Action name: remove
- Removes association with {childId} from user with {id}