feathers-shallow-populate

    2.5.1 • Public • Published

    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.

    Install

    npm i feathers-shallow-populate

    DownloadsWeekly Downloads

    186

    Version

    2.5.1

    License

    MIT

    Unpacked Size

    73.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • marshallswain
    • mattchewone