Bookshelf Relations
Insert, update and remove relationships on your Bookshelf models. This plugin supports all relationship types: belongs-to, belongs-to-many has-one and has-many.
Install
npm install bookshelf-relations --save
or
yarn add bookshelf-relations
Usage
Pre-word
- It's highly recommended to insert/update/delete your models within transactions when using this plugin, because updating nested relationships requires additional queries to the database. Otherwise if an error occurs during any query, you can't expect data to be rolled back fully.
Options
hook | type | default | description |
---|---|---|---|
autoHook | Boolean | true | The plugin takes over everything for you and hooks into the Bookshelf workflow. |
allowedOptions | Array | - | An array of allowed model options the plugin passes on when executing Bookshelf queries. |
unsetRelations | Boolean | true | The plugin will unset the relations after they are detected (e.g. model.unset('tags') ). If you are disabling "autoHook", you manually need to unset the relations. |
extendChanged | String | - | Define a variable name and Bookshelf-relations will store the information which relations were changed. |
attachPreviousRelations | Boolean | false | An option to attach previous relations. Bookshelf-relations attaches this information as _previousRelations on the target parent model. |
hooks | Object | - |
Example: hooks: {belongsToMany: {after: Function, beforeRelationCreation: Function}} |
Take a look at the plugin configuration in Ghost.
Automatic
The plugin will automatically deal with relationships upserts. It's required to register your relationships in Bookshelf before you can use bookshelf-relations, see this example.
- Register the plugin.
bookshelf.plugin('bookshelf-relations', {options});
- Define your relationships on each model.
bookshelf.Model.extend({
relationships: ['tags', 'news']
}, {...});
Manual
You manually need to call the plugin to update relationships. It's required to register your relationships in Bookshelf before you can use bookshelf-relations, see this example.
- Register the plugin.
bookshelf.plugin('bookshelf-relations', {options});
- Manually call bookshelf-relations.
bookshelf.manager.updateRelations({
model: model,
relations: {tags: [...]},
pluginOptions: {options}
})
Notations
// will detach & remove all existing relations
model.set('tags', []);
// will check if "test" exists and if not, it will insert the target tag
// will remove all previous relations if exist
model.set('tags', [{slug: 'test'}]);
Test
yarn test
to run tests & eslintyarn lint
to run eslint onlyNODE_ENV=testing-mysql yarn test
to run tests with mysql dbyarn perf
to run a performance testyarn coverage
to run test coverage
Publish
yarn ship
Copyright & License
Copyright (c) 2013-2020 Ghost Foundation - Released under the MIT license.