Skip to content

Mattchewone/feathers-shallow-populate

Repository files navigation

feathers-shallow-populate

Build Status

Feathers Shallow Populate

The fastest FeathersJS hook for populating relational data.

Installation

npm install feathers-shallow-populate --save

Complete Example

Here's an example of using feathers-shallow-populate.

const { shallowPopulate } = require('feathers-shallow-populate')

const options = {
  include: [
    {
      service: 'tags',
      nameAs: 'tags',
      keyHere: 'tagIds',
      keyThere: '_id',
      asArray: true, // by default
      params: {} // by default
    },
    {
      service: 'tags',
      nameAs: 'tags',
      params: function(params, context) {
        return { 
          query: { 
            userId: this.userId,
            companyId: this.companyId
          } 
        }
      }
    }
  ]
}

app.service('posts').hooks({
  after: {
    all: shallowPopulate(options)
  }
});

Options for the hook

  • include (required) Can be one include object or an array of include objects. See table below
  • catchOnError (optional) Wether the hook continues populating, if an error occurs (e.g. because of missing authentication) or throws. Also can be set per include individually

Options per include

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

Multiple Populates

const { shallowPopulate } = require('feathers-shallow-populate')

const options = {
  include: [
    {
      service: 'tags',
      nameAs: 'tags',
      keyHere: 'tagIds',
      keyThere: '_id',
      asArray: true,
      params: {}
    },
    {
      service: 'comments',
      nameAs: 'comments',
      keyHere: 'commentIds',
      keyThere: '_id',
      asArray: true,
      params: {}
    }
  ]
}

app.service('posts').hooks({
  after: {
    all: shallowPopulate(options)
  }
});

// result.data
[
  {
    id: 1,
    title: 'About Timothy',
    tagIds: [1, 2]
    tags: [
      {
        id: 1,
        name: 'tag 1'
      },
      {
        id: 2,
        name: 'tag 2'
      }
    ],
    commentIds: [3, 5],
    comments: [
      {
        id: 3,
        title: 'My first comment'
      },
      {
        id: 5,
        title: 'Another comment'
      }
    ]
  }
]

As Object

const { shallowPopulate } = require('feathers-shallow-populate')

const options = {
  include: {
    service: 'users',
    nameAs: 'publisher',
    keyHere: 'publisherId',
    keyThere: 'id',
    asArray: false,
    params: {}
  }
}

app.service('posts').hooks({
  after: {
    all: shallowPopulate(options)
  }
});

// result.data
[
  {
    id: 1,
    title: 'About Timothy',
    publisherId: 2,
    publisher: {
      id: 2,
      name: 'Timothy'
    }
  }
]

This will go through all the hook.data/hook.result and will create a single query to lookup the tags, it will then populate them back onto the data.

License

Copyright (c) 2020

Licensed under the MIT license.