Getting Started

About

Add lightning fast, GraphQL-like populates to your FeathersJS API.

This project is built for FeathersJS. An open source web framework for building modern real-time applications.

Installation

npm i feathers-graph-populate

yarn add feathers-graph-populate

Getting Started

Setup feathers-graph-populate

Configuring feathers-graph-populate in the app.js file, allows the global use of graph-populate-hooks.

// src/app.js
const graphPopulate = require('feathers-graph-populate')
app.configure(graphPopulate({
  allowUnnamedQueryForExternal: false // default: false
}))

Define the Relationships

The first step is to create a populates object. It's recommended that you make the first-level key names match the nameAs property. Doing so will reduce cognitive overhead required when building queries, later. Each item represents a populate object and will be passed directly to shallow-populate hook.

const populates = {
  posts: {
    service: 'posts',
    nameAs: 'posts',
    keyHere: '_id',
    keyThere: 'authorId',
    asArray: true,
    params: {}
  },
  comments: {
    service: 'comments',
    nameAs: 'comments',
    keyHere: '_id',
    keyThere: 'userId',
    asArray: true,
    params: {}
  },
  tasks: {
    service: 'tasks',
    nameAs: 'tasks',
    keyHere: '_id',
    keyThere: 'ownerIds',
    asArray: true,
    params: {}
  },
  openTasks: {
    service: 'tasks',
    nameAs: 'openTasks',
    keyHere: '_id',
    keyThere: 'ownerIds',
    asArray: true,
    params: {
      query: {
        completedAt: null
      }
    }
  },
  role: {
    service: 'roles',
    nameAs: 'role',
    keyHere: 'roleId',
    keyThere: '_id',
    asArray: false,
    params: {}
  }
}

Options for each relationship

Each populate object must/can have the following properties:

Option	Description
service	The service to reference required Type: String
nameAs	The property to be assigned to on this entry required Type: String
keyHere	The primary or secondary key for this entry required if params is not complex (most of the time) Type: String
keyThere	The primary or secondary key for the referenced entry/entries required if keyHere is defined Type: String
asArray	Is the referenced item a single entry or an array of entries? optional - default: true Type: Boolean
requestPerItem	Decided wether your params object/function runs against each item individually or bundled. Most of the time you don't need this. optional - default: - false (if keyHere and keyThere are defined) - true (if keyHere and keyThere are not defined) Type: String
catchOnError	Wether the hook continues populating, if an error occurs (e.g. because of missing authentication) or throws. Also can be set on the prior options optional - default: false Type:: Boolean
params	Additional params to be passed to the underlying service. You can mutate the passed params object or return a newly created params object which gets merged deeply Merged deeply after the params are generated internally. ProTip #1: You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss ProTip #2: If you don't define keyHere and keyThere or set requestPerItem to true the function has access to the this keyword being the individual item the request will be made for. ProTip #3: You can skip a requestPerItem if it returns undefined. ProTip #4: The hook whats for async functions! optional - default: {} Possible types: - Object: will be merged with params - simple requests - Function(params, context, { path, service }) => params: needs to return the params or a new one which gets merged deeply - more complex - Function(params, context, { path, service }) => Promise<params> - `[Object

Create Named Queries

To keep API security simpler, this package only accepts a query name from extrnal requests. We need to pre-configure a few named queries for connected clients to use:

const namedQueries = {
  withPosts: {
    posts: {}
  },
  postsWithComments: {
    posts: {
      comments: {}
    }
  },
  postsWithCommentsWithUser: {
    posts: {
      comments: {
        user:{}
      }
    }
  }
}

The first level of keys in the namedQueries object contains the names of each query. So, the first query above is called withPosts. Its query is { posts: {} }. It tells feathers-graph-populate to load all records on the posts relationship that was defined in the previous step. All records are populated with a single query.

The second query, above, is called postsWithComments. The query is { posts: { comments: {} } }. This tells feathers-graph-populate to pull in the posts relationship. The posts are populated with a single query, then the comments are populated onto the posts with one additional query.

The last query, above, is called postsWithCommentsWithUser. The query is { posts: { comments: { user: {} } } }, which tells feathers-graph-populate to perform three queries, one at each level.

Register the Populate Hook

The populate hook will need to be registered on all services on which you wish to populate data AND their target populates. For the query examples, above, the posts, comments, and users services will all require the hook to be registered as an "after all" hook:

const { populate } = require('feathers-graph-populate')

const populates = { /* See above */ }
const namedQueries = { /* See above */ }

const hooks = {
  after: {
    all: [
      populate({ populates, namedQueries })
    ]
  }
}

The option object for the hook can have the following properties:

• populates {Object} (required) the possible relations (see above).
• namedQueries {Object} (optional) makes queries simpler - required for external queries, highly recommended for internal queries (see above).
• defaultQueryName {String} - (optional) You can set a default namedQuery. If set, it has to be one of the defined namedQueries.

Enable Custom Client-Side Params

Since FeathersJS only supports passing params.query from client to server, by default, we need to let it know about the new $populateParams object. We can do this using the paramsForServer and paramsFromClient hooks:

const { paramsForServer } = require('feathers-graph-populate')

feathersClient.hooks({
  before: {
    all: [
      paramsForServer('$populateParams')
    ]
  }
})

Now to allow the API server to receive the custom param:

const { paramsFromClient } = require('feathers-graph-populate')

feathersClient.hooks({
  before: {
    all: [
      paramsFromClient('$populateParams')
    ]
  }
})

Perform Queries

Use a named query from a connected client:

feathersClient.service('users').find({
  query: {},
  $populateParams: {
    name: 'postsWithCommentsWithUser'
  }
})

Notice that the $populateParams is a custom param, so it is outside of the query object.

Unnamed Queries (for internal requests only by default or with option: 'allowUnnamedQueryForExternal' for external requests)

In addition to supporting named queries, you can directly provide a query object. This allows custom, unnamed queries like the following:

app.service('users').find({
  query: {},
  $populateParams: {
    query: {
      posts: {
        comments: {
          user:{}
        }
      }
    }
  }
})

Custom Querying

In addition to the params object that can be defined in the relations object, you can also make a custom query within the named/unnamed queries. The filters $select, $limit, $skip and $sort are working by default. This can be used to narrow down the populated data for, for example:

app.service('users').find({
  query: {},
  $populateParams: {
    query: {
      posts: {
        $select: ["id", "title"]
        comments: {
          $select: ["id", "userId", "createdAt"],
          $sort: {
            createdat: -1
          },
          user:{
            $select: ["id", "nickname"]
          }
        }
      }
    }
  }
})

You can also define additional custom query parameter per service. For example if you want to query for posts with published: true or comments with createdAt: { $gt: { 1605971642 } }. To make this possible you have to whitelist these properties per service. feathers-graph-populate looks up this array at service.options.graphPopulate.whitelist. You can setup this as following:

// posts.service.js
const createService = ...
const createModel = ...
const hooks = ...
const graphPopulate = require('./posts.graph-populate') // containing `populates`, `namedQueries`, `defaultQueryName` and `whitelist`

module.exports = function (app) {
  let Model = createModel(app);
  let paginate = app.get('paginate');

  let options = {
    Model,
    paginate,
    graphPopulate
  };

  /* // alternatively:
    let options = {
      Model,
      paginate,
      graphPopulate: {
        whiteliste: ["published"]
      }
    }
  */

  app.use('/posts', createService(options));
};

Now you can perform queries like this:

app.service('users').find({
  query: {},
  $populateParams: {
    query: {
      posts: {
        published: true,
        $select: ["id", "title"]
        comments: {
          $select: ["id"]
        }
      }
    }
  }
})

Testing

npm test

Help

Open an issue or come talk on the FeathersJS Slack.

License

Licensed under the MIT license.