Flesh out model; add comments
This commit is contained in:
garrettmills
parent
b915fcedf9
commit
c0777f77b5
@ -1,76 +1,203 @@
|
||||
import { Builder } from '../builder/Builder.ts'
|
||||
import Database from '../service/Database.ts'
|
||||
import ModelResultOperator from './ModelResultOperator.ts'
|
||||
import ObjectResultOperator from '../builder/type/result/ObjectResultOperator.ts'
|
||||
import {Builder} from '../builder/Builder.ts'
|
||||
import {FieldSet, FieldValueObject, QuerySource} from '../builder/types.ts'
|
||||
import {make} from '../../../di/src/global.ts'
|
||||
import Database from '../service/Database.ts'
|
||||
import {QueryRow, ModelKey} from '../db/types.ts'
|
||||
import ModelResultOperator from './ModelResultOperator.ts'
|
||||
import {get_fields_meta, ModelField, set_model_fields_meta} from './Field.ts'
|
||||
import {Collection} from '../../../lib/src/collection/Collection.ts'
|
||||
import {logger} from '../../../lib/src/service/logging/global.ts'
|
||||
import ObjectResultOperator from '../builder/type/result/ObjectResultOperator.ts'
|
||||
import {QueryFilter} from './filter.ts'
|
||||
import {BehaviorSubject} from '../../../lib/src/support/BehaviorSubject.ts'
|
||||
import {Scope} from '../builder/Scope.ts'
|
||||
|
||||
// TODO separate read/write connections
|
||||
// TODO manual dirty flags
|
||||
|
||||
/**
|
||||
* Base class for database models.
|
||||
* @extends Builder
|
||||
*/
|
||||
export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
/**
|
||||
* The name of the connection this model should run through.
|
||||
* @type string
|
||||
*/
|
||||
protected static connection: string
|
||||
|
||||
/**
|
||||
* The name of the table this model is stored in.
|
||||
* @type string
|
||||
*/
|
||||
protected static table: string
|
||||
|
||||
/**
|
||||
* The name of the column that uniquely identifies this model.
|
||||
* @type string
|
||||
*/
|
||||
protected static key: string
|
||||
|
||||
/**
|
||||
* Optionally, the timestamp field set on creation.
|
||||
* @type string
|
||||
*/
|
||||
protected static readonly CREATED_AT = 'created_at'
|
||||
|
||||
/**
|
||||
* Optionally, the timestamp field set op update.
|
||||
* @type string
|
||||
*/
|
||||
protected static readonly UPDATED_AT = 'updated_at'
|
||||
|
||||
/**
|
||||
* If true, the CREATED_AT and UPDATED_AT columns will be automatically set.
|
||||
* @type boolean
|
||||
*/
|
||||
protected static timestamps = true
|
||||
|
||||
/**
|
||||
* Array of global scopes to be applied to this model.
|
||||
* @type Scope[]
|
||||
*/
|
||||
protected static global_scopes: Scope[] = []
|
||||
|
||||
/**
|
||||
* Array of additional fields on the class that should
|
||||
* be included in the object serializations.
|
||||
* @type string[]
|
||||
*/
|
||||
protected static appends: string[] = []
|
||||
|
||||
/**
|
||||
* Array of fields on the class that should be excluded
|
||||
* from the object serializations.
|
||||
* @type string[]
|
||||
*/
|
||||
protected static masks: string[] = []
|
||||
|
||||
/**
|
||||
* The original query row that was fetched from the database.
|
||||
* @type QueryRow
|
||||
*/
|
||||
protected _original?: QueryRow
|
||||
|
||||
/**
|
||||
* Behavior subject that fires after the model is populated.
|
||||
*/
|
||||
protected retrieved$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right before the model is saved.
|
||||
*/
|
||||
protected saving$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right after the model is saved.
|
||||
*/
|
||||
protected saved$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right before the model is updated.
|
||||
*/
|
||||
protected updating$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right after the model is updated.
|
||||
*/
|
||||
protected updated$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right before the model is inserted.
|
||||
*/
|
||||
protected creating$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right after the model is inserted.
|
||||
*/
|
||||
protected created$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right before the model is deleted.
|
||||
*/
|
||||
protected deleting$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Behavior subject that fires right after the model is deleted.
|
||||
*/
|
||||
protected deleted$ = new BehaviorSubject<Model<T>>()
|
||||
|
||||
/**
|
||||
* Get the model table name.
|
||||
* @return string
|
||||
*/
|
||||
public static table_name() {
|
||||
return this.table
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the model connection name.
|
||||
* @return string
|
||||
*/
|
||||
public static connection_name() {
|
||||
return this.connection
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the model connection.
|
||||
* @return Connection
|
||||
*/
|
||||
public static get_connection() {
|
||||
return make(Database).connection(this.connection_name())
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a SELECT statement scoped to the model.
|
||||
* @param {...string[]} fields
|
||||
* @return Select
|
||||
*/
|
||||
public static select(...fields: FieldSet[]) {
|
||||
return this.prototype.select(...fields)
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an UPDATE query scoped to this model.
|
||||
* @return Update
|
||||
*/
|
||||
public static update() {
|
||||
return this.prototype.update()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an INSERT query scoped to this model.
|
||||
* @return Insert
|
||||
*/
|
||||
public static insert() {
|
||||
return this.prototype.insert()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a DELETE query scoped to this model.
|
||||
* @return Delete
|
||||
*/
|
||||
public static delete() {
|
||||
return this.prototype.delete()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a TRUNCATE query scoped to this model.
|
||||
* @return Truncate
|
||||
*/
|
||||
public static truncate() {
|
||||
return this.prototype.truncate()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an UPDATE query scoped to this model.
|
||||
* @param {QuerySource} [target]
|
||||
* @param {string} [alias]
|
||||
* @return Update
|
||||
*/
|
||||
public update(target?: QuerySource, alias?: string) {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
return super.update()
|
||||
@ -80,6 +207,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
.target_operator(make(ModelResultOperator, constructor))
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a SELECT query scoped to this model.
|
||||
* @param {...FieldSet} fields
|
||||
*/
|
||||
public select(...fields: FieldSet[]) {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
return super.select(...fields)
|
||||
@ -89,6 +220,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
.target_operator(make(ModelResultOperator, constructor))
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an INSERT query scoped to this model.
|
||||
* @param {QuerySource} [target]
|
||||
* @param {string} [alias]
|
||||
* @return Insert
|
||||
*/
|
||||
public insert(target?: QuerySource, alias?: string) {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
return super.insert()
|
||||
@ -97,6 +234,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
.target_operator(make(ModelResultOperator, constructor))
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a DELETE query scoped to this model.
|
||||
* @param {QuerySource} [target]
|
||||
* @param {string} [alias]
|
||||
* @return Delete
|
||||
*/
|
||||
public delete(target?: QuerySource, alias?: string) {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
return super.delete()
|
||||
@ -106,6 +249,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
.target_operator(make(ModelResultOperator, constructor))
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a TRUNCATE query scoped to this model.
|
||||
* @param {QuerySource} [target]
|
||||
* @param {string} [alias]
|
||||
* @return Truncate
|
||||
*/
|
||||
public truncate(target?: QuerySource, alias?: string) {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
return super.truncate()
|
||||
@ -114,6 +263,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
.target_operator(make(ObjectResultOperator))
|
||||
}
|
||||
|
||||
/**
|
||||
* Instantiate the model.
|
||||
* @param {object} [values] - optionally, row values to populate the model
|
||||
*/
|
||||
constructor(
|
||||
values?: any
|
||||
) {
|
||||
@ -121,6 +274,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
this.boot(values)
|
||||
}
|
||||
|
||||
/**
|
||||
* Boot the model after creation.
|
||||
* @param [values]
|
||||
*/
|
||||
public boot(values?: any) {
|
||||
if ( values ) {
|
||||
get_fields_meta(this).each(field_def => {
|
||||
@ -131,6 +288,11 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a query row, load the values into this model.
|
||||
* @param {QueryRow} row
|
||||
* @return Model
|
||||
*/
|
||||
public assume_from_source(row: QueryRow) {
|
||||
this._original = row
|
||||
get_fields_meta(this).each(field_def => {
|
||||
@ -142,6 +304,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* If applicable get an object of normalized timestamps.
|
||||
* @return { updated_at?: Date, created_at?: Date }
|
||||
*/
|
||||
public timestamps(): { updated_at?: Date, created_at?: Date } {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
const timestamps: { updated_at?: Date, created_at?: Date } = {}
|
||||
@ -155,22 +321,41 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return timestamps
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a Select statement to pull back this model's database fields.
|
||||
* @param {...FieldSet} other_fields
|
||||
*/
|
||||
public static model_select(...other_fields: FieldSet[]) {
|
||||
const fields = get_fields_meta(this.prototype).pluck('database_key').toArray()
|
||||
return this.select(...[...fields, ...other_fields])
|
||||
}
|
||||
|
||||
/**
|
||||
* Find a collection of model instances given a filter.
|
||||
* @param {QueryFilter} filter
|
||||
* @return ResultCollection
|
||||
*/
|
||||
public static async find(filter: QueryFilter = {}) {
|
||||
// @ts-ignore
|
||||
return await this.model_select().filter(filter).results()
|
||||
}
|
||||
|
||||
/**
|
||||
* Find a single instance of the model given a filter.
|
||||
* @param {QueryFilter} filter
|
||||
* @return undefined | Model
|
||||
*/
|
||||
public static async find_one(filter: QueryFilter = {}) {
|
||||
// @ts-ignore
|
||||
const result = await this.model_select().filter(filter).limit(1).results()
|
||||
return result.first()
|
||||
}
|
||||
|
||||
/**
|
||||
* Find an instance of this model by primary key.
|
||||
* @param {ModelKey} key
|
||||
* @return undefined | Model
|
||||
*/
|
||||
public static async find_by_key(key: ModelKey): Promise<undefined | typeof Model> {
|
||||
const result = await this.model_select()
|
||||
.where(this.qualified_key_name(), '=', key)
|
||||
@ -180,11 +365,19 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return result.first()
|
||||
}
|
||||
|
||||
/**
|
||||
* Count the number of records of this model.
|
||||
* @return Promise<number>
|
||||
*/
|
||||
public static async count(): Promise<number> {
|
||||
const result = this.model_select().results()
|
||||
return await result.count()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a filter checking if a model field is dirty.
|
||||
* @private
|
||||
*/
|
||||
protected get _is_dirty() {
|
||||
return (field_def: ModelField) => {
|
||||
// @ts-ignore
|
||||
@ -192,6 +385,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a query row containing all database values from this model.
|
||||
* @return QueryRow
|
||||
*/
|
||||
public to_row(): QueryRow {
|
||||
const row = {}
|
||||
this.field_defs()
|
||||
@ -202,6 +399,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return row
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a query row containing the changed values from this model.
|
||||
* @return QueryRow
|
||||
*/
|
||||
public dirty_to_row(): QueryRow {
|
||||
const row = {}
|
||||
this.field_defs()
|
||||
@ -224,6 +425,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return get_fields_meta(this.prototype)
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a collection of field definitions that contains information
|
||||
* on which database fields correspond to which model fields, and
|
||||
* their types.
|
||||
* @return Collection<ModelField>
|
||||
*/
|
||||
public field_defs(): Collection<ModelField> {
|
||||
return (this.constructor as typeof Model).fields()
|
||||
}
|
||||
@ -299,6 +506,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return !this.is_dirty()
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if the given field has been changed from the original
|
||||
* value fetched from the database.
|
||||
* @param string field
|
||||
* @return boolean
|
||||
*/
|
||||
public was_changed(field: string) {
|
||||
// @ts-ignore
|
||||
return this.field_defs().pluck('model_key').includes(field) && this[field] !== this._original[field]
|
||||
@ -323,6 +536,9 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
// support for soft deletes!
|
||||
// force delete - for soft deleted models
|
||||
|
||||
/**
|
||||
* Touch the UPDATED_AT/CREATED_AT timestamps where appropriate.
|
||||
*/
|
||||
public touch() {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
if ( constructor.timestamps ) {
|
||||
@ -339,10 +555,20 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the result collection for all records of this model.
|
||||
* @return ResultCollection
|
||||
*/
|
||||
public static all() {
|
||||
return this.model_select().results()
|
||||
}
|
||||
|
||||
/**
|
||||
* Persist the model's record into the database. If we have a key,
|
||||
* update the record. Otherwise, perform an insert.
|
||||
* @param without_timestamps - if true, the UPDATED_AT/CREATED_AT timestamps will not be touched
|
||||
* @return Promise<Model>
|
||||
*/
|
||||
public async save({ without_timestamps = false }): Promise<Model<T>> {
|
||||
await this.saving$.next(this)
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
@ -409,6 +635,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Build a field value object from the values on this model to
|
||||
* populate an INSERT query.
|
||||
* @private
|
||||
* @return FieldValueObject
|
||||
*/
|
||||
protected _build_insert_field_object(): FieldValueObject {
|
||||
const fields = this.field_defs().whereNot('model_key', '=', this.key_name())
|
||||
const values = {}
|
||||
@ -419,11 +651,20 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return values
|
||||
}
|
||||
|
||||
/**
|
||||
* Return an array of fields that were loaded from the DB.
|
||||
* @private
|
||||
* @return string[]
|
||||
*/
|
||||
protected _loaded_database_fields(): string[] {
|
||||
if ( typeof this._original === 'undefined' ) return []
|
||||
return Object.keys(this._original).map(String)
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete one or more records from this model's table by ID.
|
||||
* @param {ModelKey | ModelKey[]} id_or_ids
|
||||
*/
|
||||
public static async destroy(id_or_ids: ModelKey | ModelKey[]) {
|
||||
const ids = Array.isArray(id_or_ids) ? id_or_ids : [id_or_ids]
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
@ -440,6 +681,9 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete this model's record from the database.
|
||||
*/
|
||||
public async destroy(): Promise<void> {
|
||||
await this.deleting$.next(this)
|
||||
|
||||
@ -459,6 +703,10 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
await this.deleted$.next(this)
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert this model's record to a plain object.
|
||||
* @return object
|
||||
*/
|
||||
public to_object(): { [key: string]: any } {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
const obj = {}
|
||||
@ -481,10 +729,18 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return obj
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert this model's record to a JSON string.
|
||||
* @return string
|
||||
*/
|
||||
public to_json(): string {
|
||||
return JSON.stringify(this.to_object())
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch a fresh instance of this model's record from the database.
|
||||
* @return Model
|
||||
*/
|
||||
public async fresh(): Promise<Model<T>> {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
const fields = this.field_defs()
|
||||
@ -499,6 +755,9 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return result.first()
|
||||
}
|
||||
|
||||
/**
|
||||
* Re-fetch the fields on this model from the database.
|
||||
*/
|
||||
public async refresh() {
|
||||
const constructor = (this.constructor as typeof Model)
|
||||
const values = await this.select(this._loaded_database_fields())
|
||||
@ -511,6 +770,11 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
if ( row ) this.assume_from_source(row)
|
||||
}
|
||||
|
||||
/**
|
||||
* Populate the fields on the given model from the fields on this model, except for the key.
|
||||
* @param Model other
|
||||
* @return Model
|
||||
*/
|
||||
public populate(other: Model<T>): Model<T> {
|
||||
const row = this.to_row()
|
||||
delete row[this.key_name()]
|
||||
@ -518,6 +782,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
return other
|
||||
}
|
||||
|
||||
/**
|
||||
* Given another model, determines if that model represents the same
|
||||
* record as this model.
|
||||
* @param Model other_instance
|
||||
* @return boolean
|
||||
*/
|
||||
public is(other_instance: Model<any>): boolean {
|
||||
const this_constructor = (this.constructor as typeof Model)
|
||||
const other_constructor = (other_instance.constructor as typeof Model)
|
||||
@ -527,6 +797,12 @@ export abstract class Model<T extends Model<T>> extends Builder<T> {
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Given another model, determines if that model represents a different
|
||||
* record as this model.
|
||||
* @param Model other_instance
|
||||
* @return boolean
|
||||
*/
|
||||
public is_not(other_instance: Model<any>): boolean {
|
||||
return !this.is(other_instance)
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user