update docs

master
garrettmills 4 years ago
parent dda3038dd2
commit 1cc31ff341

@ -1,3 +1,7 @@
/**
* @module flitter-orm
*/
const Model = require('./src/model/Model')
const Connection = require('./src/services/Connection')
const Schema = require('./src/schema/Schema')

@ -1,46 +1,113 @@
/**
* @module flitter-orm/src/filter/Filter
*/
const Focus = require('./Focus')
const FilterProxy = require('./FilterProxy')
const { ObjectId } = require('mongodb')
/**
* An accumulating MongoDB filter object.
* @class
*/
class Filter {
constructor(model) {
/**
* The root query object.
* @type {{$and: []}}
* @private
*/
this._root = {$and: []}
/**
* The model in question.
* @type: {module:flitter-orm/src/model/Model}
*/
this._model = model
}
/**
* Focus on a particular field.
* @param {string} field
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
field(field) {
return new Focus(this, field)
}
/**
* End the filter and apply it to the model's proxy.
* @returns {module:flitter-orm/src/filter/FilterProxy~FilterProxy}
*/
end() {
return new FilterProxy(this._model, this)
}
/**
* Asserts that a field must equal the value.
* @param {string} field
* @param {*} value
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
equal(field, value) {
return this.field(field).equal(value).end()
}
/**
* Asserts that a field must be less than the value.
* @param {string} field
* @param {*} value
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
less_than(field, value) {
return this.field(field).less_than(value).end()
}
/**
* Asserts that a field must be greater than the value.
* @param {string} field
* @param {*} value
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
greater_than(field, value) {
return this.field(field).greater_than(value).end()
}
/**
* Asserts that a field must be less than or equal to the value.
* @param {string} field
* @param {*} value
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
less_than_equal(field, value) {
return this.field(field).less_than_equal(value).end()
}
/**
* Asserts that a field must be in the array of options for the value.
* @param {string} field
* @param {*} value
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
in(field, value) {
return this.field(field).in(value).end()
}
/**
* Write the accumulated filter to a MongoDB compatible filter object.
* @returns {object}
*/
write() {
if ( this._root.$and.length < 1 ) return {}
return this.__exec_resolve(this._root)
}
/**
* Resolve the filter object from structures to primitives.
* @param {object} object
* @returns {object}
* @private
*/
__exec_resolve(object) {
if ( Array.isArray(object) ) {
const return_arr = []
@ -64,6 +131,11 @@ class Filter {
}
}
/**
* Merge this filter with another.
* @param {module:flitter-orm/src/filter/Filter~Filter} other
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
absorb(other) {
if ( other._root ) {
this._root.$and = this._root.$and.concat(other._root.$and)
@ -80,6 +152,12 @@ class Filter {
return this
}
/**
* Callback to break a field's focus and merge the filters for that field into this filter.
* @param {module:flitter-orm/src/filter/Focus~Focus} focus
* @returns {module:flitter-orm/src/filter/Filter~Filter}
* @private
*/
_unfocus(focus) {
this._root.$and.push({ [focus._field]: focus._root })
return this

@ -1,29 +1,76 @@
/**
* @module flitter-orm/src/filter/FilterProxy
*/
/**
* A proxy that applies the provided filter to the common model query methods.
* @class
*/
class FilterProxy {
constructor(model, filter) {
/**
* The model to proxy.
* @type {module:flitter-orm/src/model/Model~Model}
*/
this.model = model
/**
* The filter to apply.
* @type {module:flitter-orm/src/filter/Filter~Filter}
*/
this.filter = filter
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#cursor}.
* @param {object} [opts = {}] - optional arguments
* @returns {mongodb/Cursor}
*/
cursor(opts = {}) {
return this.model.cursor(this.filter.write(), opts)
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#find}.
* @param {object} [opts = {}] - optional arguments
* @returns {Array<module:flitter-orm/src/model/Model~Model>}
*/
find(opts = {}) {
return this.model.find(this.filter.write(), opts)
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#findOne}.
* @param {object} [opts = {}] - optional arguments
* @returns {module:flitter-orm/src/model/Model~Model}
*/
findOne(opts = {}) {
return this.model.findOne(this.filter.write(), opts)
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#deleteOne}.
* @param {object} [opts = {}] - optional arguments
* @returns {*}
*/
deleteOne(opts = {}) {
return this.model.deleteOne(this.filter.write(), opts)
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#deleteMany}.
* @param {object} [opts = {}] - optional arguments
* @returns {*}
*/
deleteMany(opts = {}) {
return this.model.deleteMany(this.filter.write(), opts)
}
/**
* Apply the filter and call {@link module:flitter-orm/src/model/Model~Model#count}.
* @param {object} [opts = {}] - optional arguments
* @returns {number}
*/
count(opts = {}) {
return this.model.count(this.filter.write(), opts)
}

@ -1,52 +1,127 @@
/**
* @module flitter-orm/src/filter/Focus
*/
/**
* A filter, focused on a particular field.
* @class
*/
class Focus {
constructor(parent_filter, field) {
/**
* The parent filter.
* @private
* @type {module:flitter-orm/src/filter/Filter~Filter}
*/
this._parent = parent_filter
/**
* The field to focus on.
* @type {string}
* @private
*/
this._field = field
/**
* The root filter.
* @type {object}
* @private
*/
this._root = {}
/**
* Are we notting right now? Default false.
* @type {boolean}
* @private
*/
this._notting = false
}
/**
* Assert that the field must be equal to the value.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
equal(value) {
if ( this._notting ) this._root.$ne = value
else this._root.$eq = value
return this
}
/**
* Assert that the field must be less than the value.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
less_than(value) {
if ( this._notting ) this._root.$gte = value
else this._root.$lt = value
return this
}
/**
* Assert that the field must be greater than the value.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
greater_than(value) {
if ( this._notting ) this._root.$lte = value
else this._root.$gt = value
return this
}
/**
* Assert that the field must be less than or equal to the value.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
less_than_equal(value) {
if ( this._notting ) this._root.$gt = value
else this._root.$lte = value
return this
}
/**
* Assert that the field must be greater than or equal to the value.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
greater_than_equal(value) {
if ( this._notting ) this._root.$lt = value
else this._root.$gte = value
return this
}
/**
* Assert that the field must be in an array of possible values.
* (Or if were in notting mode, the opposite.)
* @param {*} value
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
in(...value_array) {
if ( this._notting ) this._root.$nin = value_array.flat()
else this._root.$in = value_array.flat()
return this
}
not(value) {
/**
* Enable notting mode.
* @returns {module:flitter-orm/src/filter/Focus~Focus}
*/
not() {
this._notting = true
return this
}
/**
* If notting, end notting mode. Otherwise, unfocus back to the parent filter.
* @returns {module:flitter-orm/src/filter/Filter~Filter|module:flitter-orm/src/filter/Focus~Focus}
*/
end() {
if ( this._notting ) {
this._notting = false

@ -1,3 +1,7 @@
/**
* @module flitter-orm/src/model/Model
*/
const { Injectable } = require('flitter-di')
const Schema = require('../schema/Schema')
const Filter = require('../filter/Filter')
@ -6,6 +10,7 @@ const Scope = require('./Scope')
/**
* The base model class. All model implementations should extend from this.
* @extends module:flitter-di/src/Injectable~Injectable
*/
class Model extends Injectable {
@ -28,20 +33,20 @@ class Model extends Injectable {
/**
* The holding variable for the instantiated schema.
* @private
* @type {Schema|boolean}
* @type {module:flitter-orm/src/schema/Schema~Schema|boolean}
*/
static __schema_instance = false
/**
* Array of instantiated references to Scopes that should be applied
* to this model.
* @type {Array<Scope>}
* @type {Array<module:flitter-orm/src/model/Scope~Scope>}
*/
static scopes = []
/**
* The instantiated schema for this model.
* @returns {Schema}
* @returns {module:flitter-orm/src/schema/Schema~Schema}
* @private
*/
static get __schema() {
@ -76,7 +81,7 @@ class Model extends Injectable {
*
* @param {object} [filter = {}] - the query filters for the cursor
* @param {object} [opts = {}] - optional settings
* @returns {Cursor}
* @returns {mongodb/Cursor}
*/
static async cursor(filter = {}, opts = {}) {
filter = (await this.filter()).absorb(filter).write()
@ -91,7 +96,7 @@ class Model extends Injectable {
*
* @param {object} [filter = {}] - the query filters for the cursor
* @param {object} [opts = {}] - optional settings
* @returns {Promise<Array<Model>>}
* @returns {Promise<Array<module:flitter-orm/src/model/Model~Model>>}
*/
static async find(filter, opts) {
const cursor = await this.cursor(filter, opts)
@ -112,7 +117,7 @@ class Model extends Injectable {
*
* @param {string|ObjectId} id - the ID of the model to query
* @param {object} [opts = {}] - optional settings
* @returns {Promise<Model>}
* @returns {Promise<Array<module:flitter-orm/src/model/Model~Model>>}
*/
static async findById(id, opts) {
if ( !(id instanceof ObjectId) ) {
@ -133,7 +138,7 @@ class Model extends Injectable {
*
* @param {object} [filter = {}] - the query filters for the cursor
* @param {object} [opts = {}] - optional settings
* @returns {Promise<Model>}
* @returns {Promise<Array<module:flitter-orm/src/model/Model~Model>>}
*/
static async findOne(filter, opts) {
const cursor = await this.cursor(filter, opts)
@ -191,7 +196,7 @@ class Model extends Injectable {
/**
* Create a new programmatic filter for this class,
* pre-loaded with any scopes.
* @returns {Filter}
* @returns {module:flitter-orm/src/filter/Filter~Filter}
*/
static async filter() {
let filter = new Filter(this)
@ -229,7 +234,7 @@ class Model extends Injectable {
* in the schema for this model, and, in so doing, will cast those values and fill in
* the specified defaults. These changes will be added to this instance after the save.
*
* @returns {Promise<Model>} - the current instance with updated properties
* @returns {Promise<module:flitter-orm/src/model/Model~Model>} - the current instance with updated properties
*/
async save() {
const schema = this.constructor.__schema
@ -267,7 +272,7 @@ class Model extends Injectable {
* specified property and immediately save the record.
* @param {string} field
* @param {*} value
* @returns {Promise<Model>}
* @returns {Promise<module:flitter-orm/src/model/Model~Model>}
*/
async set(field, value) {
this[field] = value
@ -278,7 +283,7 @@ class Model extends Injectable {
* Delete the current instance of this model from the database.
* This will remove the model's ID from this instance. Other properties
* will remain unchanged.
* @returns {Promise<Model>}
* @returns {Promise<module:flitter-orm/src/model/Model~Model>}
*/
async delete() {
if ( this._id ) {
@ -361,6 +366,11 @@ class Model extends Injectable {
return current_object
}
/**
* @deprecated
* @returns {Promise<Object>}
* @private
*/
async __db_object() {
const schema = this.constructor.__schema
const shallow_object = {}
@ -394,7 +404,7 @@ class Model extends Injectable {
* Normally, this would be automatically returned by a named method
* on the sub-class that implements the relationship.
*
* @param {Model} OtherModel - static class of the other model
* @param {module:flitter-orm/src/model/Model~Model} OtherModel - static class of the other model
* @param {string} local_key - local key of the field to match
* @param {string} [foreign_key = ''] - foreign key of the field to match (if none provided, assume the same as local_key)
* @returns {Promise<Model|undefined>} - the matching model instance
@ -412,10 +422,10 @@ class Model extends Injectable {
* Normally, this would be automatically returned by a named method
* on the sub-class that implements the relationship.
*
* @param {Model} OtherModel - static class of the other model
* @param {module:flitter-orm/src/model/Model~Model} OtherModel - static class of the other model
* @param {string} local_key - local key of the field to match
* @param {string} [foreign_key = ''] - foreign key of the field to match (if none provided, assume the same as local_key)
* @returns {Promise<Model|undefined>} - the matching model instance
* @returns {Promise<module:flitter-orm/src/model/Model~Model|undefined>} - the matching model instance
*/
async belongs_to_one(OtherModel, local_key, foreign_key = '') {
return this.has_one(OtherModel, local_key, foreign_key)
@ -428,10 +438,10 @@ class Model extends Injectable {
* Normally, this would be automatically returned by a named method
* on the sub-class that implements the relationship.
*
* @param {Model} OtherModel - static class of the other model
* @param {module:flitter-orm/src/model/Model~Model} OtherModel - static class of the other model
* @param {string} local_key - local key of the field to match
* @param {string} [foreign_key = ''] - foreign key of the field to match (if none provided, assume the same as local_key)
* @returns {Promise<Array<Model>>} - the matching model instances
* @returns {Promise<Array<module:flitter-orm/src/model/Model~Model>>} - the matching model instances
*/
async has_many(OtherModel, local_key, foreign_key = '') {
if ( !foreign_key ) foreign_key = local_key
@ -446,10 +456,10 @@ class Model extends Injectable {
* Normally, this would be automatically returned by a named method
* on the sub-class that implements the relationship.
*
* @param {Model} OtherModel - static class of the other model
* @param {module:flitter-orm/src/model/Model~Model} OtherModel - static class of the other model
* @param {string} local_key - local key of the field to match
* @param {string} [foreign_key = ''] - foreign key of the field to match (if none provided, assume the same as local_key)
* @returns {Promise<Array<Model>>} - the matching model instances
* @returns {Promise<Array<module:flitter-orm/src/model/Model~Model>>} - the matching model instances
*/
async belongs_to_many(OtherModel, local_key, foreign_key = '') {
return this.has_many(OtherModel, local_key, foreign_key)

@ -1,15 +1,42 @@
/**
* @module flitter-orm/src/model/Scope
*/
const { Injectable } = require('flitter-di')
/**
* Base class for a filter scope to apply to a model.
* @extends module:flitter-di/src/Injectable~Injectable
*/
class Scope extends Injectable {
/**
* Load in the scope config.
* @param {object} config
*/
constructor(config) {
super()
/**
* The scope config.
* @type {Object}
*/
this.config = config
}
/**
* Apply the scope to the filter.
* @param {module:flitter-orm/src/filter/Filter~Filter} to_filter - the Filter to modify
* @returns {Promise<module:flitter-orm/src/filter/Filter~Filter>}
*/
async filter(to_filter) {
return to_filter
}
/**
* Make modifications to the record before it is saved in the database.
* @param {object} record
* @returns {Promise<object>}
*/
async save(record) {
return record
}

@ -1,3 +1,7 @@
/**
* @module flitter-orm/src/schema/Schema
*/
const DateType = require('./types/Date')
const StringType = require('./types/String')
const NumberType = require('./types/Number')
@ -173,7 +177,7 @@ class Schema {
/**
* Parse the schema type from the specified type identifier.
* @param {Date|String|Number|Boolean|ObjectId|Array|Object} type
* @returns {Type}
* @returns {module:flitter-orm/src/schema/Type~Type}
*/
parse_type(type) {
const types = this.constructor.types

@ -1,3 +1,7 @@
/**
* @module flitter-orm/src/schema/Type
*/
/**
* Base class for all schema types. Used to determine
* the validity of a value and to coerce that value to

@ -1,9 +1,13 @@
/**
* @module flitter-orm/src/schema/types/Array
*/
const Type = require('../Type')
/**
* Schema type representing an array of a single other
* schema type.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class ArrayType extends Type {
/**

@ -1,8 +1,12 @@
/**
* @module flitter-orm/src/schema/types/Boolean
*/
const Type = require('../Type')
/**
* Schema type representing a boolean value.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class BooleanType extends Type {
/**

@ -1,8 +1,12 @@
/**
* @module flitter-orm/src/schema/types/Date
*/
const Type = require('../Type')
/**
* Schema type representing an ISODate value.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class DateType extends Type {
/**

@ -1,10 +1,28 @@
/**
* @module flitter-orm/src/schema/types/Model
*/
const ObjectType = require('./Object')
/**
* Schema type representing an embedded model.
* @extends module:flitter-orm/src/schema/types/Object
*/
class ModelType extends ObjectType {
/**
* Checks if an item can be cast to an object.
* @param {*} val
* @returns {boolean}
*/
static validate(val) {
return typeof val === 'object'
}
/**
* Casts a value to an object.
* @param {*} value
* @returns {*}
*/
static cast(val) {
return val
}

@ -1,8 +1,12 @@
/**
* @module flitter-orm/src/schema/types/Number
*/
const Type = require('../Type')
/**
* Schema type representing a standard number type.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class NumberType extends Type {
/**

@ -1,10 +1,14 @@
/**
* @module flitter-orm/src/schema/types/Object
*/
const Type = require('../Type')
const stringify = require('json-stringify-safe')
/**
* Schema type representing a 2-way serializable object
* comprised of keys of other schema types.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class ObjectType extends Type {
/**

@ -1,9 +1,13 @@
/**
* @module flitter-orm/src/schema/types/ObjectId
*/
const Type = require('../Type')
const { ObjectId } = require('mongodb')
/**
* Schema type representing a MongoDB ObjectId instance.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class ObjectIdType extends Type {

@ -1,8 +1,12 @@
/**
* @module flitter-orm/src/schema/types/String
*/
const Type = require('../Type')
/**
* Schema type representing a single string.
* @extends {Type}
* @extends {module:flitter-orm/src/schema/Type~Type}
*/
class StringType extends Type {
/**

@ -1,3 +1,7 @@
/**
* @module flitter-orm/src/services/Connection
*/
const { Service } = require('flitter-di')
const { MongoClient } = require('mongodb')
@ -8,7 +12,7 @@ const { MongoClient } = require('mongodb')
* This service is compatible with flitter-di and must
* be registered under the 'scaffold' name.
*
* @extends {Service}
* @extends {module:flitter-di/src/Service~Service}
*/
class Connection extends Service {
/**

Loading…
Cancel
Save