@withbluedot/bookshelf-relations

    1.4.1 • Public • Published

    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 -
    • belongsToMany: Hook into the process of updating belongsToMany relationships.


    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 and cascading deletions through hasMany relationships. It's required to register your relationships in Bookshelf before you can use bookshelf-relations, see this example.

    1. Register the plugin.
        bookshelf.plugin('bookshelf-relations', {options});
    1. Define your relationships on each model.
        bookshelf.Model.extend({
            relationships: ['tags', 'news']
        }, {...});

    To opt-out of automatic child record deletion for hasMany relationships it's possible to define per-relationship config:

        bookshelf.Model.extend({
            relationships: ['tags', 'news', 'events'],
            relationshipConfig: {
                events: {
                    destroyRelated: false
                }
            }
        });

    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.

    1. Register the plugin.
        bookshelf.plugin('bookshelf-relations', {options});
    1. 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 & eslint
    • yarn lint to run eslint only
    • NODE_ENV=testing-mysql yarn test to run tests with mysql db
    • yarn perf to run a performance test
    • yarn coverage to run test coverage

    Publish

    • yarn ship

    Copyright & License

    Copyright (c) 2013-2020 Ghost Foundation - Released under the MIT license.

    Install

    npm i @withbluedot/bookshelf-relations

    DownloadsWeekly Downloads

    2

    Version

    1.4.1

    License

    MIT

    Unpacked Size

    53.2 kB

    Total Files

    9

    Last publish

    Collaborators

    • withbluedot