mongoose-polymer
Polymorphic associations for mongoose inspired by laravel polymorphic relations and others.
What is it
mongoose-polymer
and thus polymorphic associations, allow a model to belong to more than one other model on a single association. For example, you might have a photo model that belongs to either a user model or an product model.
Installation
$ npm install --save mongoose-polymer
Usage
Require mongoose-polymer
after mongoose
prior to your schema definition. This allows mongoose-polymer
to patch Schema
and add all required polymorphism boilerplates.
var mongoose = ;var polymer = ;
Polymorphic One-to-One
To define polymorphic one-to-one
with mongoose-polymer
, use morphBy schema method on the owned model side and morphOne schema method on the owning model side. Consider a case where a user schema
and product schema
each having a single photo
. Here user schema
and product schema
form the owning side(or parent) and photo schema
is the owned side(or child).
Example
//photo schema defenitionvar PhotoSchema = ... ;PhotoSchema;PhotoSchema;var Photo = mongoose; //user schema definitionvar UserSchema = ... ;UserSchema;var User = mongoose; //product schema definitionvar ProductSchema = ... ;PhotoSchema;var Product = mongoose; //samples//adding user photouser ; //get user photouser ; //removing user photouser ; //get photo userphoto ;
Polymorphic One-to-Many
To define polymorphic one-to-many
with mongoose-polymer
, use morphBy schema method on the owned model side and morphMany schema method method in the owning model side. Consider a case where a user schema
and product schema
each having multiple photo
. Here user schema
and product schema
form the owning side(or parent) and photo schema
is the owned side(or child).
Example
//photo schema definitionvar PhotoSchema = ... ;PhotoSchema;PhotoSchema;var Photo = mongoose; //user schema definitionvar UserSchema = ... ;UserSchema;var User = mongoose; //product schema definitionvar ProductSchema = ... ;PhotoSchema;var Product = mongoose; //samples//add user photouser ; //add user photosuser ; //get all user photosuser ; //get one user photouser ; //remove all user photosuser ; //remove one user photouser ;
API
morphBy(modelName,morphName)
Specifies the owning model of polymorphism. In case of Product
and Photo
the owning model is Product
. modelName
is valid model name of the owning side and morpName
is the name of polymorphic association formed. morpName
controls the name of fields used to store the formed association.
Example
PhotoSchema;...
Following model instance methods will be added to the owned model instance
morphName(callback)
An instance method whose name is determines by morphName
will be added to owned side model instance to enable retrieving owning side model instance. For the above cases Photo
model instance will gain photoable
instance method to enable it to retrieve either Product
or User
instance.
Example
//when want to retrieve user from photo instancephoto ; //when want to retrieve product from photo instancephoto ;
morpOne(modelName,morphName)
Specifies the owned model in one-to-one polymorphism. In case of Product
and Photo
the owned model is Photo
. modelName
is valid model name of the owned side and morpName
is the name of polymorphic association formed. morpName
controls mongoose criteria building in the owning side.
Example
//one-to-onePhotoSchema;...
The following model instance methods will be added on owning model instance
getModelName(callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to retrieve its polymer. For the case of the above examples User
and Product
model instance will have instance method with name getPhoto
to enable them to get their photo. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when retrieving photo instance from the user instanceuser //more conditions ;
setModelName(morphOne,callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to set its polymer. For the case of the above examples User
and Product
model instance will have instance method with name setPhoto
to enable them to get their photo. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when set photo instance for the user instanceuser ;
removeModelName(callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to remove its polymer. For the case of the above examples User
and Product
model instance will have instance method with name removePhoto
to enable them to remove their photo. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when removing photo instance from the user instanceuser //more conditions ;
morphMany(modelName,morphName)
Specifies the owned model in one-to-many polymorphism. In case of Product
and Photo
the owned model is Photo
. modelName
is valid model name of the owned side and morpName
is the name of polymorphic association formed. morpName
controls mongoose criteria building in the owning side.
Example
//one-to-manyPhotoSchema;...
The following model instance methods will be added to the owning model instance
getModelName(id,callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to get one of its polymer. For the case of the above examples User
and Product
model instance will have instance method with name getPhoto
to enable them to retrieve one of their photo. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when retrieving one photo instance from the user instanceuser //more conditions ;
getModelNames(callback)
Additional instance method whose name is determined by pluralizing the name of the owned model, will be added to the owning model to enable it to get all of its polymer. For the case of the above examples User
and Product
model instance will have instance method with name getPhotos
to enable them to retrieve all their photos. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when retrieving all photos instance from the user instanceuser //more conditions ;
addModelName(morpOne,callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to add one or more polymer. For the case of the above examples User
and Product
model instance will have instance method with name addPhoto
to enable them to add one or more photo. If callback
is not supplied mongoose promise
will be returned for evaluation.
Example
//when adding one photo instance from the user instanceuser ; //when adding multiple photos instance from the user instanceuser ;
removeModelName(id,callback)
Additional instance method whose name is determined by the name of the owned model, will be added to the owning model to enable it to remove one of its polymer. For the case of the above examples User
and Product
model instance will have instance method with name removePhoto
to enable them to remove one of their photo. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when removing one of the photo instance from the user instanceuser //more conditions ;
removeModelNames(callback)
Additional instance method whose name is determined by pluralizing the name of the owned model, will be added to the owning model to enable it to remove its polymers. For the case of the above examples User
and Product
model instance will have instance method with name removePhotos
to enable them to remove their photos. If callback
is not supplied valid mongoose query
will be returned to allow additional chaining.
Example
//when removing photos instance from the user instanceuser //more conditions ;
Testing
-
Clone this repository
-
Install all development dependencies
$ npm install
- Then run test
$ npm test
Contribute
It will be nice, if you open an issue first so that we can know what is going on, then, fork this repo and push in your ideas. Do not forget to add a bit of test(s) of what value you adding.
Licence
The MIT License (MIT)
Copyright (c) 2015 lykmapipo & Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.