{"id":24556123,"url":"https://github.com/mattchewone/feathers-shallow-populate","last_synced_at":"2025-04-16T21:44:13.132Z","repository":{"id":25690870,"uuid":"105532474","full_name":"Mattchewone/feathers-shallow-populate","owner":"Mattchewone","description":"Feathersjs populate relational data","archived":false,"fork":false,"pushed_at":"2023-01-06T14:56:10.000Z","size":537,"stargazers_count":22,"open_issues_count":6,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T16:59:49.814Z","etag":null,"topics":["feathersjs","hooks","javascript","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mattchewone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-02T12:38:07.000Z","updated_at":"2022-06-30T18:25:50.000Z","dependencies_parsed_at":"2023-01-14T03:08:23.635Z","dependency_job_id":null,"html_url":"https://github.com/Mattchewone/feathers-shallow-populate","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattchewone%2Ffeathers-shallow-populate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattchewone%2Ffeathers-shallow-populate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattchewone%2Ffeathers-shallow-populate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattchewone%2Ffeathers-shallow-populate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mattchewone","download_url":"https://codeload.github.com/Mattchewone/feathers-shallow-populate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249280535,"owners_count":21243138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["feathersjs","hooks","javascript","nodejs"],"created_at":"2025-01-23T04:38:36.866Z","updated_at":"2025-04-16T21:44:13.117Z","avatar_url":"https://github.com/Mattchewone.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# feathers-shallow-populate\n\n[![Build Status](https://travis-ci.org/Mattchewone/feathers-shallow-populate.png?branch=master)](https://travis-ci.org/Mattchewone/feathers-shallow-populate)\n\u003c!-- [![Dependency Status](https://img.shields.io/david/feathers-plus/feathers-mocha-utils.svg?style=flat-square)](https://david-dm.org/feathers-plus/feathers-mocha-utils)\n[![Download Status](https://img.shields.io/npm/dm/feathers-mocha-utils.svg?style=flat-square)](https://www.npmjs.com/package/feathers-mocha-utils) --\u003e\n\n\u003e Feathers Shallow Populate\n\nThe fastest FeathersJS hook for populating relational data.\n\n## Installation\n\n```\nnpm install feathers-shallow-populate --save\n```\n\n## Complete Example\n\nHere's an example of using `feathers-shallow-populate`.\n\n```js\nconst { shallowPopulate } = require('feathers-shallow-populate')\n\nconst options = {\n  include: [\n    {\n      service: 'tags',\n      nameAs: 'tags',\n      keyHere: 'tagIds',\n      keyThere: '_id',\n      asArray: true, // by default\n      params: {} // by default\n    },\n    {\n      service: 'tags',\n      nameAs: 'tags',\n      params: function(params, context) {\n        return { \n          query: { \n            userId: this.userId,\n            companyId: this.companyId\n          } \n        }\n      }\n    }\n  ]\n}\n\napp.service('posts').hooks({\n  after: {\n    all: shallowPopulate(options)\n  }\n});\n```\n\n## Options for the hook\n- `include` (**required**) Can be one `include` object or an array of `include` objects. See table below\n- `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\n\n## Options per include\n\n| **Option**       | **Description** |\n|------------------|-----------------|\n| `service`        | The service to reference\u003cbr\u003e\u003cbr\u003e**required**\u003cbr\u003e**Type:** `String` |\n| `nameAs`         | The property to be assigned to on this entry\u003cbr\u003e\u003cbr\u003e**required**\u003cbr\u003e**Type:** `String` |\n| `keyHere`        | The primary or secondary key for this entry\u003cbr\u003e\u003cbr\u003e**required if `params` is not complex (most of the time)**\u003cbr\u003e**Type:** `String` |\n| `keyThere`       | The primary or secondary key for the referenced entry/entries\u003cbr\u003e\u003cbr\u003e**required if `keyHere` is defined**\u003cbr\u003e**Type:** `String` |\n| `asArray`        | Is the referenced item a single entry or an array of entries?\u003cbr\u003e\u003cbr\u003e**optional - default:** `true`\u003cbr\u003e**Type:** `Boolean`\n| `requestPerItem` | Decided wether your `params` object/function runs against each item individually or bundled. Most of the time you don't need this.\u003cbr\u003e\u003cbr\u003e**optional - default:\u003cbr\u003e- `false`** (if `keyHere` and `keyThere` are defined)\u003cbr\u003e- **`true`** (if `keyHere` and `keyThere` are not defined)\u003cbr\u003e**Type:** `String`\n| `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\u003cbr\u003e\u003cbr\u003e**optional - default:** `false`\u003cbr\u003e**Type:**: `Boolean` |\n| `params`         | Additional params to be passed to the underlying service.\u003cbr\u003eYou can mutate the passed `params` object or return a newly created `params` object which gets merged deeply \u003cbr\u003eMerged deeply after the params are generated internally.\u003cbr\u003e\u003cquote\u003e**ProTip #1:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss\u003c/quote\u003e\u003cbr\u003e\u003cquote\u003e**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.\u003c/quote\u003e\u003cbr\u003e\u003cquote\u003e**ProTip #3**: You can skip a `requestPerItem` if it returns `undefined`.\u003c/quote\u003e\u003cbr\u003e\u003cquote\u003e**ProTip #4**: The hook whats for async functions!\u003c/quote\u003e\u003cbr\u003e\u003cbr\u003e**optional - default:** `{}`\u003cbr\u003e**Possible types:**\u003cbr\u003e- `Object`: _will be merged with params - simple requests_\u003cbr\u003e- `Function(params, context, { path, service }) =\u003e params`: _needs to return the `params` or a new one which gets merged deeply - more complex_\u003cbr\u003e- `Function(params, context, { path, service }) =\u003e Promise\u003cparams\u003e`\u003cbr\u003e- `[Object | Function]` |\n\n## Multiple Populates\n```js\nconst { shallowPopulate } = require('feathers-shallow-populate')\n\nconst options = {\n  include: [\n    {\n      service: 'tags',\n      nameAs: 'tags',\n      keyHere: 'tagIds',\n      keyThere: '_id',\n      asArray: true,\n      params: {}\n    },\n    {\n      service: 'comments',\n      nameAs: 'comments',\n      keyHere: 'commentIds',\n      keyThere: '_id',\n      asArray: true,\n      params: {}\n    }\n  ]\n}\n\napp.service('posts').hooks({\n  after: {\n    all: shallowPopulate(options)\n  }\n});\n\n// result.data\n[\n  {\n    id: 1,\n    title: 'About Timothy',\n    tagIds: [1, 2]\n    tags: [\n      {\n        id: 1,\n        name: 'tag 1'\n      },\n      {\n        id: 2,\n        name: 'tag 2'\n      }\n    ],\n    commentIds: [3, 5],\n    comments: [\n      {\n        id: 3,\n        title: 'My first comment'\n      },\n      {\n        id: 5,\n        title: 'Another comment'\n      }\n    ]\n  }\n]\n```\n\n## As Object\n```js\nconst { shallowPopulate } = require('feathers-shallow-populate')\n\nconst options = {\n  include: {\n    service: 'users',\n    nameAs: 'publisher',\n    keyHere: 'publisherId',\n    keyThere: 'id',\n    asArray: false,\n    params: {}\n  }\n}\n\napp.service('posts').hooks({\n  after: {\n    all: shallowPopulate(options)\n  }\n});\n\n// result.data\n[\n  {\n    id: 1,\n    title: 'About Timothy',\n    publisherId: 2,\n    publisher: {\n      id: 2,\n      name: 'Timothy'\n    }\n  }\n]\n```\n\nThis 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.\n\n## License\n\nCopyright (c) 2020\n\nLicensed under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattchewone%2Ffeathers-shallow-populate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattchewone%2Ffeathers-shallow-populate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattchewone%2Ffeathers-shallow-populate/lists"}