README.md

feathers-harperdb

This library is a FeathersJS database adapter for HarperDB - a high-scale, LMDB & NodeJS database. It uses a combination of the raw HarperDB RESTful endpoints and KnexJS-translated queries through HarperDB's subset of supported SQL commands. It also uses Harperive for authentication, promise management, and connectivity. Harperive is exposed internally for developers wishing to build more complex queries in a HarperDB service.

npm install --save feathers-harperdb

Important: feathers-harperdb implements the Feathers Common database adapter API and querying syntax.

API

service(options)

const service = require('feathers-harperdb');
app.use('/messages', service({
    //...options
}););

Options:

• name (required) - The name of the table
• config (required) - Usually set in config/{ENV}.json. See "Connection Options" below
• client (optional) - The Harperive Client, can be manually overriden and accessed
• id (optional, default: id) - The name of the id field property.
• events (optional) - A list of custom service events sent by this service
• paginate (optional) - A pagination object containing a default and max page size
• multi (optional) - Allow create with arrays and update and remove with id null to change multiple items. Can be true for all methods or an array of allowed methods (e.g. [ 'remove', 'create' ])
• whitelist (optional) - A list of additional query parameters to allow (e..g [ '$regex', '$geoNear' ]). Default is the supported operators
• sortField (optional, default: __createdtime__) - By default all objects will be sorted ASC by created timestamp, similar to sorting by Integer auto-incremented id in most feather SQL operations
• sortDirection (optional, default: asc) - The default sort direction, can be one of [ 'asc', 'desc' ]
• limit (optional, default: 5000) - The max number of objects to return without pagination, will be overriden by pagination settings
• sync (optional, default: true ) - Setting true will create schema and table on load as part of the service.setup() function run by FeathersJS
• force (optional, default: false) , Settign true will delete the schema on setup, starting with fresh database with every boot, much like Sequelize's forceSync.

Connection Options: The connection options are passed in as a config object inside the options object (i.e. harper({ config: { ...connection_options } }))

• schema (required) - The name of the schema (i.e. DB-equivalent) in the HarperDB instance
• harperHost (required) - The location of the Harper Host
• username (required) - The username to connect with
• password (required) - The password to connect with
• table (optional) - The name of the table referenced by the service, defaults to the configured name, but can be overriden by setting config.table

These can also be set via a "harperdb" configuration field in the Feathers config/{ENV}.json:

  "harperdb":{
    "harperHost": "http://localhost:9925",
    "username": "admin",
    "password": "password",
    "schema": "test"
  }

Setting up Service

To set up your service, your service class.js and service.js files should look something like this:

//books.class.js
const { Service } = require('feathers-harperdb');
exports.Books = class Books extends Service{
  constructor(options, app) {
    super({
      ...options,
      name: 'books'
    });
  }
};

//books.service.js
const { Books } = require('./books.class');
const hooks = require('./books.hooks');
module.exports = function (app) {
  const options = {
    paginate: app.get('paginate'),
    config: {
      ...app.get('harperdb'),
      table: 'books'
    }
  };
  app.use('/books', new Books(options, app));
  const service = app.service('books');
  service.hooks(hooks);
};

Querying

In addition to the common querying mechanism, this adapter also supports direct NoSQL submissions via the Harperive client like this:

let service = app.service('books')
await service.client.insert({
  table: this.table,
  records: [
    {
      user_id: 43,
      username: 'simon_j',
      first_name: 'James',
      middle_name: 'J.',
      last_name: 'Simon'
    }
  ]
})
.then((res) => console.log(res))
.catch((err) => console.log(err));

You can also use Harperive's generic execution option like so:

const options = {
  operation: 'harperdb_operation',
  //other fields...
};

// Promise
let service = app.service('books')
await service.client.executeOperation(options)
  .then((res) => console.log(res))
  .catch((err) => console.log(err));