From 724b730468c54dd9d10def4edbd6735d27c38779 Mon Sep 17 00:00:00 2001 From: Benson Maruchu Date: Wed, 23 May 2018 14:41:39 +0300 Subject: [PATCH] improve model jsdoc --- lib/jurisdiction.model.js | 163 ++++++++++++++++++++++---------------- 1 file changed, 96 insertions(+), 67 deletions(-) diff --git a/lib/jurisdiction.model.js b/lib/jurisdiction.model.js index eaec71f9..3f5ba6cd 100644 --- a/lib/jurisdiction.model.js +++ b/lib/jurisdiction.model.js @@ -11,24 +11,15 @@ * entity(jurisdiction) in case there is hierarchy. * * @author lally elias + * @author Benson Maruchu * @license MIT * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @public - * @example - * const { Jurisdiction } = require('majifix-jurisdiction'); - * - * ... - * - * Jurisdiction.findOne().exec(done); - * Jurisdiction.find().exec(done); - * - * ... - * */ -/** +/* * @todo add list of contacts */ @@ -52,19 +43,18 @@ const { ObjectId } = Schema.Types; /* local constants */ const MODEL_NAME = 'Jurisdiction'; -const OPTION_AUTOPOPULATE = { +const SCHEMA_OPTIONS = ({ timestamps: true, emitIndexErrors: true }); +const OPTION_AUTOPOPULATE = ({ select: { code: 1, name: 1, color: 1 }, maxDepth: schema.POPULATION_MAX_DEPTH -}; - -const SCHEMA_OPTIONS = ({ timestamps: true, emitIndexErrors: true }); +}); /** * @name JurisdictionSchema * @type {Schema} * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @private */ const JurisdictionSchema = new Schema({ @@ -90,7 +80,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ jurisdiction: { @@ -119,7 +109,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ code: { @@ -130,7 +120,8 @@ const JurisdictionSchema = new Schema({ searchable: true, fake: { generator: 'finance', - type: 'account' + type: 'account', + unique: true }, index: true }, @@ -149,7 +140,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ name: { @@ -180,7 +171,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ phone: { @@ -212,7 +203,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ email: { @@ -244,7 +235,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ website: { @@ -274,10 +265,10 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ - about: { //TODO make it multi language + about: { type: String, trim: true, searchable: true, @@ -303,7 +294,7 @@ const JurisdictionSchema = new Schema({ * @property {boolean} index - ensure database index * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ address: { @@ -317,6 +308,7 @@ const JurisdictionSchema = new Schema({ index: true }, + /** * @name color * @description A color code(in hexadecimal format) eg. #363636 used to @@ -333,7 +325,7 @@ const JurisdictionSchema = new Schema({ * @property {object} fake - fake data generator options * * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ color: { @@ -351,10 +343,18 @@ const JurisdictionSchema = new Schema({ * by citizen(or customer) * * @type {object} + * @property {object} location - geo json point + * @property {string} location.type - Point + * @property {number[]} location.coordinates - longitude, latitude pair of the geo point * - * @since 0.1.0 - * @version 0.1.0 + * @since 0.1.0 + * @version 1.0.0 * @instance + * @example + * { + * type: 'Point', + * coordinates: [-76.80207859497996, 55.69469494228919] + * } */ location: Point, @@ -367,18 +367,30 @@ const JurisdictionSchema = new Schema({ * jurisdiction based on its geo coordinates. * * @type {object} + * @property {object} boundaries - geo json multi polygon + * @property {string} boundaries.type - MultiPolygon + * @property {number[]} boundaries.coordinates - collection of polygon * - * @since 0.1.0 - * @version 0.1.0 + * @since 0.1.0 + * @version 1.0.0 * @instance + * @example + * { + * type: 'MultiPolygon', + * coordinates: [ [ [ [-76.80207859497996, 55.69469494228919] ] ] ] + * } */ boundaries: MultiPolygon }, SCHEMA_OPTIONS); +/* +*----------------------------------------------------------------------------------- +* Indexes +*----------------------------------------------------------------------------------- +*/ -/* Indexes */ //ensure `unique` compound index on jurisdiction, code and name //to fix unique indexes on code and name in case they are used in more than @@ -386,15 +398,19 @@ const JurisdictionSchema = new Schema({ JurisdictionSchema.index({ jurisdiction: 1, code: 1, name: 1 }, { unique: true }); +/* +*----------------------------------------------------------------------------------- +* Virtual +*----------------------------------------------------------------------------------- +*/ -/* Virtual */ /** * @name longitude * @description obtain jurisdiction longitude - * @type {Number} + * @type {number} * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.virtual('longitude').get(function () { @@ -406,9 +422,9 @@ JurisdictionSchema.virtual('longitude').get(function () { /** * @name latitude * @description obtain jurisdiction latitude - * @type {Number} + * @type {number} * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.virtual('latitude').get(function () { @@ -417,8 +433,12 @@ JurisdictionSchema.virtual('latitude').get(function () { }); +/* +*----------------------------------------------------------------------------------- +* Hooks +*----------------------------------------------------------------------------------- +*/ -/* Hooks */ JurisdictionSchema.pre('validate', function (next) { @@ -451,16 +471,19 @@ JurisdictionSchema.pre('validate', function (next) { }); - -/* Instance */ +/* +*----------------------------------------------------------------------------------- +* Instance +*----------------------------------------------------------------------------------- +*/ /** * @name ensureLocation * @description compute account location - * @param {Function} done callback to invoke on success or error + * @param {function} done callback to invoke on success or error * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.methods.ensureLocation = function ensureLocation() { @@ -479,9 +502,9 @@ JurisdictionSchema.methods.ensureLocation = function ensureLocation() { /** * @name beforePost * @description pre save account logics - * @param {Function} done callback to invoke on success or error + * @param {function} done callback to invoke on success or error * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.methods.beforePost = function beforePost(done) { @@ -508,9 +531,9 @@ JurisdictionSchema.methods.beforePost = function beforePost(done) { /** * @name afterPost * @description post save jurisdiction logics - * @param {Function} done callback to invoke on success or error + * @param {function} done callback to invoke on success or error * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.methods.afterPost = function afterPost(done) { @@ -523,9 +546,9 @@ JurisdictionSchema.methods.afterPost = function afterPost(done) { /** * @name beforeDelete * @description pre delete jurisdiction logics - * @param {Function} done callback to invoke on success or error + * @param {function} done callback to invoke on success or error * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.methods.beforeDelete = function beforeDelete(done) { @@ -542,9 +565,9 @@ JurisdictionSchema.methods.beforeDelete = function beforeDelete(done) { /** * @name afterDelete * @description post delete jurisdiction logics - * @param {Function} done callback to invoke on success or error + * @param {function} done callback to invoke on success or error * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @instance */ JurisdictionSchema.methods.afterDelete = function afterDelete(done) { @@ -553,20 +576,25 @@ JurisdictionSchema.methods.afterDelete = function afterDelete(done) { done(); }; -/* Statics */ + +/* +*----------------------------------------------------------------------------------- +* Statics +*----------------------------------------------------------------------------------- +*/ + /** * @name findNearBy * @description find jurisdiction near a specified coordinates - * @param {Number} options.minDistance min distance in meters - * @param {Number} options.maxDistance max distance in meters - * @param {[Number]} options.coordinates coordinates of the location - * @param {Function} done a callback to invoke on success or error - * @return {[Object]} collection of jurisdiction near by - * specified coordinates + * @param {number} options.minDistance min distance in meters + * @param {number} options.maxDistance max distance in meters + * @param {number[]} options.coordinates coordinates of the location + * @param {function} done a callback to invoke on success or error + * @return {Object[]} collection of jurisdiction near by specified coordinates * @see {@link https://docs.mongodb.com/manual/reference/operator/query/nearSphere/#op._S_nearSphere} * @since 0.1.0 - * @version 0.1.0 + * @version 1.0.0 * @public * @static */ @@ -603,37 +631,38 @@ JurisdictionSchema.statics.findNearBy = function (options, done) { _.compact(criteria.$nearSphere.$geometry.coordinates.concat(options.coordinates)); } - //reference jurisdiction - const Jurisdiction = this; //find jurisdiction(s) which is near by provided coordinates async.waterfall([ function ensureIndexes(next) { - Jurisdiction.ensureIndexes(function (error) { + this.ensureIndexes(function (error) { next(error, true); }); - }, + }.bind(this), function query(indexed, next) { - Jurisdiction.find({ + this.find({ boundaries: criteria }, next); - } + }.bind(this) ], done); }; - /* expose model name */ JurisdictionSchema.statics.MODEL_NAME = MODEL_NAME; JurisdictionSchema.statics.OPTION_AUTOPOPULATE = OPTION_AUTOPOPULATE; +/* +*----------------------------------------------------------------------------------- +* Plugins +*----------------------------------------------------------------------------------- +*/ -/* Plugins */ /* use mongoose rest actions*/ JurisdictionSchema.plugin(actions);