leoric 2.14.0 → 2.15.0-alpha.0

package/Readme.md

@@ -13,7 +13,7 @@ Leoric is an object-relational mapping library for Node.js, which is heavily inf
 Assume the tables of posts, users, and comments were setup already. We may declare the models as classes by extending from the base class `Bone` of Leoric. After the models are connected to the database, the columns of the tables are mapped as attributes, the associations are setup, feel free to start querying.
 
 ```js
-const { Bone, connect } = require('leoric')
+import { Bone, connect } from 'leoric'
 
 // define model
 class Post extends Bone {
@@ -45,7 +45,8 @@ async function main() {
 If table structures were intended to be maintained in the models, Leoric can be used as a table migration tool as well. We can just define attributes in the models, and call `realm.sync()` whenever we are ready.
 
 ```js
-const { BIGINT, STRING } = Bone.DataTypes;
+import Realm, { Bone, DataTypes } from 'leoric';
+const { BIGINT, STRING } = DataTypes;
 class Post extends Bone {
   static attributes = {
     id: { type: BIGINT, primaryKey: true },

package/dist/abstract_bone.d.ts

@@ -0,0 +1,478 @@
+import util from 'util';
+import DataTypes, { AbstractDataType, DataType } from './data_types';
+import Collection from './collection';
+import Spell from './spell';
+import Raw from './raw';
+import 'reflect-metadata';
+import { Pool, Literal, WhereConditions, QueryOptions, AttributeMeta, AssociateOptions, Connection, BoneColumns, ColumnMeta, BeforeHooksType, AfterHooksType, QueryResult, BoneCreateValues, BulkCreateOptions, Values } from './types/common';
+import { AbstractDriver, ConnectOptions } from './drivers';
+import Attribute from './drivers/abstract/attribute';
+export interface SyncOptions {
+    force?: boolean;
+    alter?: boolean;
+}
+export interface InitOptions {
+    underscored?: boolean;
+    tableName?: string;
+    hooks?: {
+        [key in BeforeHooksType]: (options: QueryOptions) => Promise<void>;
+    } | {
+        [key in AfterHooksType]: (instance: AbstractBone, result: object) => Promise<void>;
+    };
+    timestamps?: boolean;
+}
+export declare const columnAttributesKey: unique symbol;
+export declare const synchronizedKey: unique symbol;
+export declare const tableKey: unique symbol;
+export declare class AbstractBone {
+    #private;
+    static DataTypes: typeof DataTypes;
+    [key: string]: any;
+    isNewRecord: boolean;
+    static [columnAttributesKey]: {
+        [key: string]: Attribute;
+    } | null;
+    static [synchronizedKey]: boolean;
+    static [tableKey]: string;
+    static get synchronized(): boolean;
+    static set synchronized(value: boolean);
+    /**
+     * The driver that powers the model
+     */
+    static driver: AbstractDriver;
+    /**
+     * The connected models structured as `{ [model.name]: model }`, e.g. `Bone.model.Post => Post`
+     */
+    static models: {
+        [key: string]: typeof AbstractBone;
+    };
+    /**
+     * The plural model name in camelCase, e.g. `Post => posts`
+     */
+    static tableAlias: string;
+    /**
+     * The primary key of the model, defaults to `id`.
+     */
+    static primaryKey: string;
+    /**
+     * The primary column of the table, defaults to `id`. This is {@link Bone.primaryKey} in snake case.
+     */
+    static get primaryColumn(): string;
+    /**
+     * The attribute definitions of the model.
+     */
+    static attributes: {
+        [key: string]: Attribute;
+    };
+    /**
+     * The attribute definitions of the model, referenced by column name.
+     */
+    static attributeMap: {
+        [key: string]: Attribute;
+    };
+    /**
+     * The schema info of current model.
+     */
+    static columns: Array<AttributeMeta>;
+    /**
+     * If the table consists of multiple partition tables then a sharding key is needed to perform actual query. The sharding key can be specified through overridding this property, which will then be used to check the query before it hits database.
+     */
+    static shardingKey: string;
+    /**
+     * If the table name is just an alias and the schema info can only be fetched by one of its partition table names, physic tables should be specified.
+     */
+    static physicTables: string[];
+    static get physicTable(): string;
+    static set table(value: string);
+    static get table(): string;
+    static options: ConnectOptions;
+    static timestamps: {
+        createdAt: string;
+        updatedAt: string;
+        deletedAt: string;
+    };
+    static _scope: any;
+    static associations: {
+        [key: string]: any;
+    };
+    constructor(values?: {
+        [key: string]: Literal;
+    }, opts?: {
+        isNewRecord?: boolean;
+    });
+    static get shardingColumn(): string | undefined;
+    /**
+     * get the connection pool of the driver
+     */
+    static get pool(): Pool;
+    /**
+     * Override attribute metadata
+     * @example
+     * Bone.attribute('foo', { type: JSON })
+     */
+    static attribute(name: string, meta: AttributeMeta): void;
+    /**
+     * Model.hasAttribute(name)
+     * @static
+     * @param {string} name
+     * @returns {boolean}
+     */
+    static hasAttribute(name: string): boolean;
+    /**
+     * get attributes except virtuals
+     */
+    static get columnAttributes(): {
+        [key: string]: Attribute;
+    };
+    /**
+     * get actual update/insert columns to avoid empty insert or update
+     * @param {Object} data
+     */
+    static _getColumns(data: Record<string, Literal>): Record<string, Literal>;
+    /**
+     * Rename attribute
+     * @example
+     * Bone.renameAttribute('foo', 'bar')
+     */
+    static renameAttribute<T extends typeof AbstractBone>(this: T, originalName: any, newName: string): void;
+    static alias<T extends typeof AbstractBone>(this: T, name: BoneColumns<T>): string;
+    static alias<T extends typeof AbstractBone>(this: T, data: {
+        [key in BoneColumns<T>]: Literal;
+    }): Record<string, Literal>;
+    static alias<T extends typeof AbstractBone>(this: T, name: string): string;
+    static alias<T extends typeof AbstractBone>(this: T, data: Record<string, Literal>): Record<string, Literal>;
+    static unalias(name: string): string;
+    /**
+     * Load attribute definition to merge default getter/setter and custom descriptor on prototype
+     */
+    static loadAttribute(name: string): void;
+    static hasOne(name: string, options?: AssociateOptions): void;
+    static hasMany(name: string, options?: AssociateOptions): void;
+    static belongsTo(name: string, options?: AssociateOptions): void;
+    /**
+     * Mount association metadata, verifying existence and applying paranoid defaults.
+     */
+    static associate(name: string, opts: AssociateOptions): void;
+    /**
+     * INSERT rows
+     * @example
+     * Bone.create({ foo: 1, bar: 'baz' })
+     */
+    static create<T extends typeof AbstractBone>(this: T, values: BoneCreateValues<T>, opts?: QueryOptions): AbstractBone | Spell<typeof AbstractBone, AbstractBone>;
+    /**
+     * INSERT or UPDATE rows
+     * @example
+     * Bone.upsert(values, { hooks: false })
+     * @param values values
+     * @param opt query options
+     */
+    static upsert<T extends typeof AbstractBone>(this: T, values: BoneCreateValues<T>, options?: QueryOptions): Promise<number>;
+    static bulkCreate<T extends typeof AbstractBone>(this: T, records: Array<BoneCreateValues<T>>, options?: BulkCreateOptions): Promise<InstanceType<T>[]>;
+    /**
+     * SELECT all rows. In production, when the table is at large, it is not recommended to access records in this way. To iterate over all records, {@link Bone.batch} shall be considered as the better alternative. For tables with soft delete enabled, which means they've got `deletedAt` attribute, use {@link Bone.unscoped} to discard the default scope.
+     */
+    static get all(): Spell<typeof AbstractBone, Collection<InstanceType<typeof AbstractBone>>>;
+    /**
+     * SELECT rows OFFSET index LIMIT 1
+     * @example
+     * Bone.get(8)
+     * Bone.find({ foo: { $gt: 1 } }).get(42)
+     */
+    static get<T extends typeof AbstractBone>(this: T, index: number): Spell<T, InstanceType<T> | null>;
+    /**
+     * SELECT rows ORDER BY id ASC LIMIT 1
+     */
+    static get first(): Spell<typeof AbstractBone, InstanceType<typeof AbstractBone> | null>;
+    /**
+     * SELECT rows ORDER BY id DESC LIMIT 1
+     */
+    static get last(): Spell<typeof AbstractBone, InstanceType<typeof AbstractBone> | null>;
+    /**
+     * Short of `Bone.find().with(...names)`
+     * @example
+     * Post.include('author', 'comments').where('posts.id = ?', 1)
+     */
+    static include<T extends typeof AbstractBone>(this: T, ...names: string[]): Spell<T>;
+    /**
+     * Internal finder powering all query starts.
+     */
+    static _find<T extends typeof AbstractBone>(this: T, conditions?: WhereConditions<T> | string | number | number[] | bigint | bigint[], ...values: Literal[]): Spell<T, number | InstanceType<T> | import("./types/common").Collection<InstanceType<T>> | import("./types/common").ResultSet<T> | null>;
+    static select<T extends typeof AbstractBone>(this: T, ...names: Array<BoneColumns<T>> | string[]): Spell<T>;
+    static select<T extends typeof AbstractBone>(this: T, ...names: string[]): Spell<T>;
+    static select<T extends typeof AbstractBone>(this: T, ...names: Raw[]): Spell<T>;
+    static select<T extends typeof AbstractBone>(this: T, filter: (name: string) => boolean): Spell<T>;
+    /**
+     * JOIN arbitrary models with given ON conditions
+     * @example
+     * Bone.join(Muscle, 'bones.id == muscles.boneId')
+     */
+    static join<T extends typeof AbstractBone>(this: T, ...args: Parameters<typeof Spell.prototype.$join>): Spell<T, Collection<InstanceType<T>>>;
+    /**
+     * Set WHERE conditions
+     * @example
+     * Bone.where('foo = ?', 1)
+     * Bone.where({ foo: { $eq: 1 } })
+     */
+    static where<T extends typeof AbstractBone>(this: T, ...args: Parameters<typeof Spell.prototype.$where>): Spell<T, Collection<InstanceType<T>>>;
+    /**
+     * Set GROUP fields
+     * @example
+     * Bone.group('foo')
+     * Bone.group('MONTH(createdAt)')
+     */
+    static group<T extends typeof AbstractBone>(this: T, ...names: Parameters<typeof Spell.prototype.$group>): Spell<T, number | InstanceType<T> | import("./types/common").Collection<InstanceType<T>> | import("./types/common").ResultSet<T> | null>;
+    /**
+     * Set ORDER fields
+     * @example
+     * Bone.order('foo')
+     * Bone.order('foo', 'desc')
+     * Bone.order({ foo: 'desc' })
+     */
+    static order<T extends typeof AbstractBone>(this: T, ...args: Parameters<typeof Spell.prototype.$order>): Spell<T, number | InstanceType<T> | import("./types/common").Collection<InstanceType<T>> | import("./types/common").ResultSet<T> | null>;
+    static count<T extends typeof AbstractBone>(this: T, name?: BoneColumns<T> | Raw | string): Spell<T, number | import("./types/common").ResultSet<T> | Extract<InstanceType<T>, number | import("./types/common").ResultSet<T>> | Extract<import("./types/common").Collection<InstanceType<T>>, number | import("./types/common").ResultSet<T>>>;
+    static average<T extends typeof AbstractBone>(this: T, name: BoneColumns<T> | Raw | string): Spell<T, number | import("./types/common").ResultSet<T> | Extract<InstanceType<T>, number | import("./types/common").ResultSet<T>> | Extract<import("./types/common").Collection<InstanceType<T>>, number | import("./types/common").ResultSet<T>>>;
+    static minimum<T extends typeof AbstractBone>(this: T, name: BoneColumns<T> | Raw | string): Spell<T, number | import("./types/common").ResultSet<T> | Extract<InstanceType<T>, number | import("./types/common").ResultSet<T>> | Extract<import("./types/common").Collection<InstanceType<T>>, number | import("./types/common").ResultSet<T>>>;
+    static maximum<T extends typeof AbstractBone>(this: T, name: BoneColumns<T> | Raw | string): Spell<T, number | import("./types/common").ResultSet<T> | Extract<InstanceType<T>, number | import("./types/common").ResultSet<T>> | Extract<import("./types/common").Collection<InstanceType<T>>, number | import("./types/common").ResultSet<T>>>;
+    /**
+     * Update any record that matches conditions.
+     */
+    static _update<T extends typeof AbstractBone, Key extends BoneColumns<T>>(this: T, conditions: WhereConditions<T>, values: Record<Key, Literal | Raw>, options: QueryOptions): Spell<T, number>;
+    /**
+     * JSON merge convenience for update
+     */
+    static jsonMerge<T extends typeof AbstractBone, Key extends BoneColumns<T>>(this: T, conditions: WhereConditions<T>, values: Record<Key, Literal | Record<string, Literal> | Raw>, options?: QueryOptions & {
+        preserve?: boolean;
+    }): Promise<number>;
+    static jsonMergePreserve<T extends typeof AbstractBone, Key extends keyof Values<T>>(this: T, conditions: WhereConditions<T>, values: Record<Key, Record<string, Literal>>, options: QueryOptions): Promise<number>;
+    /**
+     * Remove rows. If soft delete is applied, an UPDATE query is performed instead of DELETing records directly. Set `forceDelete` to true to force a `DELETE` query.
+     */
+    static remove<T extends typeof AbstractBone>(this: T, conditions: WhereConditions<T>, forceDelete?: boolean, options?: QueryOptions): Spell<T, number>;
+    /**
+     * private method for internal calling
+     * Remove any record that matches `conditions`.
+     * - If `forceDelete` is true, `DELETE` records from database permanently.
+     * - If not, update `deletedAt` attribute with current date.
+     * - If `forceDelete` isn't true and `deleteAt` isn't around, throw an Error.
+     * @example
+     * Post.remove({ title: 'Leah' })         // mark Post { title: 'Leah' } as deleted
+     * Post.remove({ title: 'Leah' }, true)   // delete Post { title: 'Leah' }
+     * Post.remove({}, true)                  // delete all data of posts
+     */
+    static _remove<T extends typeof AbstractBone>(this: T, conditions: WhereConditions<T>, forceDelete?: boolean, options?: QueryOptions): Spell<T, number>;
+    /**
+     * Execute a raw query
+     * @example
+     * Bone.query('SELECT * FROM posts WHERE id = ?', [1])
+     * Bone.query('SELECT * FROM posts WHERE id = :id', { replacements: { id: 1 } })
+     */
+    static query<T extends typeof AbstractBone>(this: T, sql: string, values?: Literal[] | QueryOptions, opts?: QueryOptions): Promise<{
+        rows?: any[];
+        fields?: {
+            table: string;
+            name: string;
+        }[];
+    }>;
+    /**
+     * Grabs a connection and starts a transaction process. Both GeneratorFunction and AsyncFunction are acceptable. If GeneratorFunction is used, the connection of the transaction process will be passed around automatically.
+     * @example
+     * Bone.transaction(function* () {
+     *   const bone = yield Bone.create({ foo: 1 })
+     *   yield Muscle.create({ boneId: bone.id, bar: 1 })
+     * });
+     */
+    static transaction<T extends (options: {
+        connection: Connection;
+        commit: () => Promise<QueryResult>;
+        rollback: () => Promise<QueryResult>;
+    }) => Promise<any> | Generator>(callback: T): Promise<ReturnType<T>>;
+    static describe(): Promise<Record<string, ColumnMeta>>;
+    /**
+     * DROP the table
+     */
+    static drop(): Promise<void>;
+    /**
+     * TRUNCATE table to clear records.
+     */
+    static truncate(): Promise<void>;
+    static sync({ force, alter }?: SyncOptions): Promise<void>;
+    static initialize(): void;
+    static instantiate<T extends typeof AbstractBone>(this: T, row: any): InstanceType<T>;
+    static init(attributes: Record<string, AbstractDataType<DataType> | AttributeMeta>, opts?: InitOptions, overrides?: Record<string, PropertyDescriptor>): void;
+    static load<T extends typeof AbstractBone>(this: T, columns?: Array<ColumnMeta>): void;
+    static from<T extends typeof AbstractBone>(this: T, table: string | Spell<T>): Spell<T, number | InstanceType<T> | import("./types/common").Collection<InstanceType<T>> | import("./types/common").ResultSet<T> | null>;
+    /**
+     * Restore soft-deleted rows by clearing deletedAt.
+     * @example
+     * Bone.restore({ title: 'aaa' })
+     * Bone.restore({ title: 'aaa' }, { hooks: false })
+     */
+    static _restore<T extends typeof AbstractBone>(this: T, conditions: WhereConditions<T>, opts: QueryOptions): Spell<T, number>;
+    getRaw(key?: string): any;
+    getRawSaved(key?: string): any;
+    getRawPrevious(key?: string): any;
+    _setRaw(...args: any[]): void;
+    _getRawUnset(): Set<string>;
+    _setRawSaved(key: string, value: any): void;
+    attribute<T, Key extends keyof Values<T>, U extends T[Key]>(this: T, name: Key): U extends Literal ? U : Literal;
+    attribute<T, Key extends keyof T, U extends T[Key]>(this: T, name: Key): U extends Literal ? U : Literal;
+    attribute<T, Key extends keyof Values<T>>(this: T, name: Key, value: Literal): this;
+    attribute<T, Key extends keyof T>(this: T, name: Key, value: Literal): this;
+    /**
+     * instance.hasAttribute(name)
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasAttribute(name: string): boolean;
+    /**
+     * Get the original attribute value.
+     * @example
+     * bone.attributeWas('foo')  // => 1
+     */
+    attributeWas(name: string): any;
+    /**
+     * See if attribute has been changed or not.
+     * @deprecated {@link Bone#changed} is preferred
+     * @example
+     * bone.attributeChanged('foo')
+     */
+    attributeChanged(name: string): boolean;
+    /**
+     * Get changed attributes or check if given attribute is changed or not
+     */
+    changed(): string[] | false;
+    changed(name: string): boolean;
+    /**
+     * Get attribute changes
+     */
+    changes(name?: string): Record<string, [any, any]>;
+    /**
+     * See if attribute was changed previously or not.
+     */
+    previousChanged(name?: string): any;
+    previousChanges(name?: string): Record<string, [any, any]>;
+    /**
+     * Persist changes of current record to database. If current record has never been saved before, an INSERT query is performed. If the primary key was set and is not changed since, an UPDATE query is performed. If the primary key is changed, an INSERT ... UPDATE query is performed instead.
+     *
+     * If `affectedRows` is needed, consider using the corresponding methods directly.
+     * @example
+     * new Bone({ foo: 1 }).save()                   // => INSERT
+     * new Bone({ foo: 1, id: 1 }).save()            // => INSERT ... UPDATE
+     * (await Bone.fist).attribute('foo', 2).save()  // => UPDATE
+     * new Bone({ foo: 1, id: 1 }).save({ hooks: false })            // => INSERT ... UPDATE
+     */
+    save(opts?: QueryOptions): Promise<this>;
+    /**
+     * Internal save dispatcher deciding between create/update/upsert
+     */
+    _save(opts?: QueryOptions): Promise<this>;
+    /**
+     * Sync raw caches after persistence
+     */
+    syncRaw(): void;
+    /**
+     * Remove current record. If `deletedAt` attribute exists, then instead of DELETing records from database directly, the records will have their `deletedAt` attribute UPDATEd instead. To force `DELETE`, no matter the existence of `deletedAt` attribute, pass `true` as the argument.
+     * @example
+     * bone.remove()      // => UPDATE ... SET deleted_at = now() WHERE ...
+     * bone.remove(true)  // => DELETE FROM ... WHERE ...
+     * bone.remove(true, { hooks: false })
+     */
+    remove(forceDelete?: boolean, opts?: QueryOptions): Promise<number>;
+    /**
+     * Delete current instance. If `deletedAt` attribute exists, calling {@link Bone#remove} does not actually delete the record from the database. Instead, it updates the value of `deletedAt` attribute to current date. This is called [soft delete](../querying#scopes). To force a regular `DELETE`, use `.remove(true)`.
+     * @private
+     * @param {boolean} forceDelete
+     * @example
+     * const post = await Post.first
+     * post.remove()      // update the `deletedAt`
+     * post.remove(true)  // delete record
+     */
+    _remove(forceDelete?: boolean, opts?: QueryOptions): Promise<number>;
+    /**
+     * update or insert record.
+     * @example
+     * bone.upsert() // INERT ... VALUES ON DUPLICATE KEY UPDATE ...
+     * bone.upsert({ hooks: false })
+     * @param opts queryOptions
+     */
+    upsert(opts?: QueryOptions): Promise<number>;
+    /**
+     * Internal upsert implementation
+     */
+    _upsert(opts: QueryOptions): Promise<number>;
+    /**
+     * Persist changes on current instance back to database with `UPDATE`.
+     * @private
+     */
+    _update(values: Record<string, Literal>, options: QueryOptions): Promise<number>;
+    /**
+     * UPDATE JSONB column with JSON_MERGE_PATCH function
+     * @example
+     * /// before: bone.extra equals { name: 'zhangsan', url: 'https://alibaba.com' }
+     * bone.jsonMerge('extra', { url: 'https://taobao.com' })
+     * /// after: bone.extra equals { name: 'zhangsan', url: 'https://taobao.com' }
+    */
+    jsonMerge<Key extends keyof Extract<this, Literal>>(values: Record<Key, Record<string, Literal>>, opts?: QueryOptions & {
+        preserve?: boolean;
+    }): Promise<number>;
+    jsonMerge<Key extends keyof Extract<this, Literal>>(name: Key, jsonValue: Record<string, Literal>, opts?: QueryOptions & {
+        preserve?: boolean;
+    }): Promise<number>;
+    jsonMergePreserve<Key extends keyof Extract<this, Literal>>(values: Record<Key, Record<string, Literal>>, opts?: QueryOptions): Promise<number>;
+    jsonMergePreserve<Key extends keyof Extract<this, Literal>>(name: Key, jsonValue: Record<string, Literal>, opts?: QueryOptions): Promise<number>;
+    /**
+     * create instance
+     * @param opts query options
+     */
+    create(opts?: QueryOptions): Spell<typeof AbstractBone, this> | this;
+    /**
+     * Internal create implementation
+     */
+    _create(opts?: QueryOptions): Spell<typeof AbstractBone, this> | this;
+    /**
+     * reload instance
+     */
+    reload(): Promise<this>;
+    /**
+     * Protected clone
+     */
+    _clone(target: any): void;
+    /**
+     * Validate current changes
+     */
+    validate(): void;
+    /**
+     * Instance attribute validation
+     */
+    _validateAttributes(values?: Record<string, Literal>): void;
+    /**
+     * Static attribute validation
+     */
+    static _validateAttributes(values: Record<string, Literal>): void;
+    /**
+     * restore data
+     * @param opts query options
+     */
+    restore(opts?: QueryOptions): Promise<this>;
+    /**
+     * Gets called when `JSON.stringify(instance)` is invoked.
+     * {@link Bone#toJSON} might be called on descents of Bone that does not have attributes defined on them directly, hence for..in is preferred.
+     * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
+     * @example
+     * const post = await Post.first
+     * post.toJSON()  // => { id: 1, ... }
+     * @return {Object}
+     */
+    [util.inspect.custom](): string;
+    toJSON(): Record<string, any>;
+    /**
+     * This is the loyal twin of {@link Bone#toJSON} because when generating the result object, the raw values of attributes are used, instead of the values returned by custom getters (if any).
+     * {@link Bone#toObject} might be called on descents of Bone that does not have attributes defined on them directly, hence for..in is preferred.
+     * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
+     * @example
+     * const post = await Post.first
+     * post.toObject()  // => { id: 1, ... }
+     * @return {Object}
+     */
+    toObject(): any;
+}