README.md

feathers-shallow-populate

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.