Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marshallswain/feathers-graph-populate
Add lightning fast, GraphQL-like populates to your FeathersJS API
https://github.com/marshallswain/feathers-graph-populate
feathers-graph-populate feathersjs graphql
Last synced: 28 days ago
JSON representation
Add lightning fast, GraphQL-like populates to your FeathersJS API
- Host: GitHub
- URL: https://github.com/marshallswain/feathers-graph-populate
- Owner: marshallswain
- License: mit
- Created: 2019-08-04T17:51:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-19T19:03:08.000Z (10 months ago)
- Last Synced: 2024-10-05T03:51:01.243Z (about 1 month ago)
- Topics: feathers-graph-populate, feathersjs, graphql
- Language: TypeScript
- Homepage: https://feathers-graph-populate.netlify.app/
- Size: 4.93 MB
- Stars: 29
- Watchers: 3
- Forks: 5
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-feathersjs - feathers-graph-populate - Add lightning fast, GraphQL-like populates to your FeathersJS API (Plugins / Hooks)
README
# feathers-graph-populate
[](https://github.com/marshallswain/feathers-graph-populate/actions)
[](https://libraries.io/npm/feathers-graph-populate)
[](https://www.npmjs.com/package/feathers-graph-populate)
> NOTE: This is the version for Feathers v5. For Feathers v4 use [feathers-graph-populate v3](https://github.com/marshallswain/feathers-graph-populate/tree/crow)
Add lightning fast, GraphQL-like populates to your FeathersJS API.
This project is built for [FeathersJS](http://feathersjs.com). An open source web framework for building modern real-time applications.
## Documentation
See https://feathers-graph-populate.netlify.app/ for full documentation
## Getting Started
### Define your relationships
The top-level keys in the `populates` represent the name of the relationship.
```js
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: {}
},
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 for the relationship
**required**
**Type:** `{String}` |
| `nameAs` | The property to be assigned to on this entry. It's recommended that you make the populate object key name match the `nameAs` property.
**required**
**Type:** `{String}` |
| `keyHere` | The primary or secondary key for the current entry
**required**
**Type:** `{String}` |
| `keyThere` | The primary or secondary key for the referenced entry/entries
**required**
**Type:** `{String}` |
| `asArray` | Is the referenced item a single entry or an array of entries?
**optional - default:** `true`
**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:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss
**optional - default:** `{}`
**Type:** `{Object | Function(params, context): undefined|params}` |
### Create named queries to use from connected clients.
The top-level keys in the `nameQueries` object are the query names. Nested keys under the query name refer to the name of the relationship, found in the `populates` object from the previous code snippet.
```js
const namedQueries = {
withPosts: {
posts: {}
},
postsWithComments: {
posts: {
comments: {}
}
},
postsWithCommentsWithUser: {
posts: {
comments: {
user:{}
}
}
}
}
```
### Register the hook
```js
const { populate } = require('feathers-graph-populate')
const hooks = {
after: {
all: [
populate({ populates, namedQueries })
]
}
}
```
### Perform Queries
Use a named query from a connected client:
```js
feathersClient.service('users').find({
query: {},
$populateParams: {
name: 'postsWithCommentsWithUser'
}
})
```
Use a query object for internal requests. (named queries also work, internally):
```js
app.service('users').find({
query: {},
$populateParams: {
query: {
posts: {
comments: {
user:{}
}
}
}
}
})
```
### Handling 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:
```js
const { paramsForServer } = require('feathers-graph-populate')
feathersClient.hooks({
before: {
all: [
paramsForServer('$populateParams')
]
}
})
```
Now to allow the API server to receive the custom param:
```js
const { paramsFromClient } = require('feathers-graph-populate')
feathersClient.hooks({
before: {
all: [
paramsFromClient('$populateParams')
]
}
})
```
## Testing
Simply run `npm test` and all your tests in the `test/` directory will be run.
## Help
For more information on all the things you can do, visit [the generator](https://generator.feathers-plus.com/), [FeathersJS](http://docs.feathersjs.com) and [extensions](https://feathers-plus.github.io/).
## License
Licensed under the [MIT license](LICENSE).