@leapfrogtechnology/db-model
Version:
Low-footprint database abstraction layer and model built on top of Knex.
472 lines (471 loc) • 16.4 kB
TypeScript
import * as Knex from 'knex';
import OrderBy from './domain/OrderBy';
import RawBindingParams, { ValueMap } from './domain/RawBindingParams';
import PaginationParams from './domain/PaginationParams';
export declare type ConnectionResolver = () => Knex;
/**
* Create Model for different connection
*
* @param {ConnectionResolver} [resolver]
* @returns {typeof BaseModel}
*/
export declare function createBaseModel(resolver?: ConnectionResolver): {
new (): {};
table: string;
defaultOrderBy: OrderBy[];
id: string;
connection?: Knex<any, unknown[]> | undefined;
/**
* Binds a database connection to the model.
*
* @param {Knex} connection
* @returns {void}
*/
bindConnection(connection: Knex<any, unknown[]>): void;
/**
* Binds a database connection to the model (chainable version of bindConnection()).
*
* @param {Knex} connection
* @returns {any}
*/
bind(connection: Knex<any, unknown[]>): any;
/**
* Resolves a database connection.
*
* Note: It would throw an Error on the run time if it couldn't resolve the
* connection by the time any DB methods are invoked on it.
* @returns {Knex}
*/
getConnection(): Knex<any, unknown[]>;
/**
* Generic query builder.
*
* @param {Transaction} [trx]
* @returns {(Knex.Transaction | Knex)}
*/
queryBuilder(trx?: Knex.Transaction<any, any> | undefined): Knex<any, unknown[]> | Knex.Transaction<any, any>;
/**
* Finds a record based on the params.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Knex.QueryBuilder}
*/
find<T>(params?: object, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Knex.QueryBuilder<any, any>;
/**
* Finds the first record based on the params.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Promise<T | null>}
*/
findFirst<T_1>(params?: object, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_1 | null>;
/**
* Find record by it's id.
* Throws an exception if not found.
*
* @param {any} id
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Promise<T | null>}
*/
findById<T_2>(id: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_2 | null>;
/**
* Find record by it's id.
* Throws an exception if not found.
*
* @param {any} id
* @param {Function} callback
* @param {Knex.Transaction} trx
* @throws {ModelNotFoundError}
* @returns {Promise<T | null>}
*/
findByIdOrFail<T_3>(id: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_3 | null>;
/**
* Finds records based on the params with records limit.
*
* @param {object} [params={}]
* @param {PaginationParams} pageParams
* @param {OrderBy[]} sortParams
* @param {Knex.Transaction} trx
* @param {Function} callback
* @returns {Knex.QueryBuilder}
*/
findWithPageAndSort(params: any, pageParams: PaginationParams, sortParams: OrderBy[], callback?: any, trx?: Knex.Transaction<any, any> | undefined): Knex.QueryBuilder<any, any>;
/**
* Count the total records.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Knex.QueryBuilder}
*/
count(params?: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<any>;
/**
* Insert all records sent in data object.
*
* @param {(object | object[])} data
* @param {Transaction} [trx]
* @returns {Promise<T[]>}
*/
insert<T_4>(data: object | object[], trx?: Knex.Transaction<any, any> | undefined): Promise<T_4[]>;
/**
* Update records by id.
*
* @param {number} id
* @param {object} params
* @param {Transaction} transaction
* @returns {Promise<object>}
*/
updateById<T_5>(id: any, params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_5[]>;
/**
* Update records by where condition.
*
* @param {object} where
* @param {object} params
* @param {Transaction} transaction
* @returns {Promise<T[]>}
*/
update<T_6>(where: object, params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_6[]>;
/**
* Delete row in table.
*
* @param {object} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
deleteById<T_7>(id: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_7[]>;
/**
* Delete row in table.
*
* @param {object} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
delete<T_8>(params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_8[]>;
/**
* Execute SQL raw query and return results.
*
* @param {string} sql
* @param {RawBindingParams | ValueMap} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
query<T_9>(sql: string, params?: ValueMap | RawBindingParams | undefined, trx?: Knex.Transaction<any, any> | undefined): Promise<T_9[]>;
/**
* Method to perform a transactional query execution.
*
* @param {(trx: Transaction) => any} callback
* @param {Transaction} trx
* @returns {any}
*/
transaction<T_10>(callback: (trx: Knex.Transaction<any, any>) => any, trx?: Knex.Transaction<any, any> | undefined): any;
/**
* Batch insert rows of data.
*
* @param {object[]} data
* @param {Transaction} [trx]
* @param {number} [chunksize=30]
* @returns {Promise<T[]>}
*/
batchInsert<T_11>(data: object[], trx?: Knex.Transaction<any, any> | undefined, chunksize?: number): Promise<T_11[]>;
/**
* Execute SQL raw query and return scalar value.
*
* @param {string} sql
* @param {any} params
* @param {Transaction} trx
* @returns {Promise<T | null>}
*/
getValue<T_12>(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_12 | null>;
/**
* Execute SQL raw query returning a boolean result.
*
* @param {string} sql
* @param {*} [params]
* @param {Transaction} [trx]
* @returns {Promise<boolean>}
*/
check(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<boolean>;
/**
* Execute SQL raw query returning a JSON encoded result
* and produce the parsed object.
*
* @param {string} sql
* @param {*} [params]
* @param {Transaction} [trx]
* @returns {(Promise<T | null>)}
*/
getJson<T_13>(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_13 | null>;
/**
* Invoke a scalar-valued function and return results.
*
* Example usage:
*
* const username = await User.invoke<string>('dbo.can_user_access_object', { userId: 10, objectId: 15 });
*
* // => Runs SQL: SELECT dbo.can_user_access_object(:userId, :objectId)
* // => Binds params: { userId: 10, objectId: 15 }
*
* @param {string} objectName
* @param {RawBindingParams | ValueMap} [params]
* @param {Knex.Transaction} [trx]
* @returns {Promise<T | null>}
*/
invoke<T_14>(objectName: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_14 | null>;
/**
* Execute a procedure and return the results returned (if any).
*
* Example usage:
*
* await Recommendation.exec<string>('dbo.update_top_recommendations', { userId: 10, type });
*
* // => Runs SQL: EXEC dbo.update_top_recommendations :userId, :type
* // => Binds params: { userId: 10, type }
*
* @param {string} objectName
* @param {RawBindingParams | ValueMap} [params]
* @param {Knex.Transaction} [trx]
* @returns {Promise<T[]>}
*/
exec<T_15>(objectName: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_15[]>;
/**
* Build param object for given id.
*
* @param {any} id
* @returns {object}
*/
buildIdParams(id: any): any;
};
export declare const Model: {
new (): {};
table: string;
defaultOrderBy: OrderBy[];
id: string;
connection?: Knex<any, unknown[]> | undefined;
/**
* Binds a database connection to the model.
*
* @param {Knex} connection
* @returns {void}
*/
bindConnection(connection: Knex<any, unknown[]>): void;
/**
* Binds a database connection to the model (chainable version of bindConnection()).
*
* @param {Knex} connection
* @returns {any}
*/
bind(connection: Knex<any, unknown[]>): any;
/**
* Resolves a database connection.
*
* Note: It would throw an Error on the run time if it couldn't resolve the
* connection by the time any DB methods are invoked on it.
* @returns {Knex}
*/
getConnection(): Knex<any, unknown[]>;
/**
* Generic query builder.
*
* @param {Transaction} [trx]
* @returns {(Knex.Transaction | Knex)}
*/
queryBuilder(trx?: Knex.Transaction<any, any> | undefined): Knex<any, unknown[]> | Knex.Transaction<any, any>;
/**
* Finds a record based on the params.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Knex.QueryBuilder}
*/
find<T>(params?: object, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Knex.QueryBuilder<any, any>;
/**
* Finds the first record based on the params.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Promise<T | null>}
*/
findFirst<T_1>(params?: object, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_1 | null>;
/**
* Find record by it's id.
* Throws an exception if not found.
*
* @param {any} id
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Promise<T | null>}
*/
findById<T_2>(id: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_2 | null>;
/**
* Find record by it's id.
* Throws an exception if not found.
*
* @param {any} id
* @param {Function} callback
* @param {Knex.Transaction} trx
* @throws {ModelNotFoundError}
* @returns {Promise<T | null>}
*/
findByIdOrFail<T_3>(id: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_3 | null>;
/**
* Finds records based on the params with records limit.
*
* @param {object} [params={}]
* @param {PaginationParams} pageParams
* @param {OrderBy[]} sortParams
* @param {Knex.Transaction} trx
* @param {Function} callback
* @returns {Knex.QueryBuilder}
*/
findWithPageAndSort(params: any, pageParams: PaginationParams, sortParams: OrderBy[], callback?: any, trx?: Knex.Transaction<any, any> | undefined): Knex.QueryBuilder<any, any>;
/**
* Count the total records.
*
* @param {object} [params={}]
* @param {Function} callback
* @param {Knex.Transaction} trx
* @returns {Knex.QueryBuilder}
*/
count(params?: any, callback?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<any>;
/**
* Insert all records sent in data object.
*
* @param {(object | object[])} data
* @param {Transaction} [trx]
* @returns {Promise<T[]>}
*/
insert<T_4>(data: object | object[], trx?: Knex.Transaction<any, any> | undefined): Promise<T_4[]>;
/**
* Update records by id.
*
* @param {number} id
* @param {object} params
* @param {Transaction} transaction
* @returns {Promise<object>}
*/
updateById<T_5>(id: any, params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_5[]>;
/**
* Update records by where condition.
*
* @param {object} where
* @param {object} params
* @param {Transaction} transaction
* @returns {Promise<T[]>}
*/
update<T_6>(where: object, params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_6[]>;
/**
* Delete row in table.
*
* @param {object} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
deleteById<T_7>(id: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_7[]>;
/**
* Delete row in table.
*
* @param {object} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
delete<T_8>(params: object, trx?: Knex.Transaction<any, any> | undefined): Promise<T_8[]>;
/**
* Execute SQL raw query and return results.
*
* @param {string} sql
* @param {RawBindingParams | ValueMap} params
* @param {Transaction} trx
* @returns {Promise<T[]>}
*/
query<T_9>(sql: string, params?: ValueMap | RawBindingParams | undefined, trx?: Knex.Transaction<any, any> | undefined): Promise<T_9[]>;
/**
* Method to perform a transactional query execution.
*
* @param {(trx: Transaction) => any} callback
* @param {Transaction} trx
* @returns {any}
*/
transaction<T_10>(callback: (trx: Knex.Transaction<any, any>) => any, trx?: Knex.Transaction<any, any> | undefined): any;
/**
* Batch insert rows of data.
*
* @param {object[]} data
* @param {Transaction} [trx]
* @param {number} [chunksize=30]
* @returns {Promise<T[]>}
*/
batchInsert<T_11>(data: object[], trx?: Knex.Transaction<any, any> | undefined, chunksize?: number): Promise<T_11[]>;
/**
* Execute SQL raw query and return scalar value.
*
* @param {string} sql
* @param {any} params
* @param {Transaction} trx
* @returns {Promise<T | null>}
*/
getValue<T_12>(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_12 | null>;
/**
* Execute SQL raw query returning a boolean result.
*
* @param {string} sql
* @param {*} [params]
* @param {Transaction} [trx]
* @returns {Promise<boolean>}
*/
check(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<boolean>;
/**
* Execute SQL raw query returning a JSON encoded result
* and produce the parsed object.
*
* @param {string} sql
* @param {*} [params]
* @param {Transaction} [trx]
* @returns {(Promise<T | null>)}
*/
getJson<T_13>(sql: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_13 | null>;
/**
* Invoke a scalar-valued function and return results.
*
* Example usage:
*
* const username = await User.invoke<string>('dbo.can_user_access_object', { userId: 10, objectId: 15 });
*
* // => Runs SQL: SELECT dbo.can_user_access_object(:userId, :objectId)
* // => Binds params: { userId: 10, objectId: 15 }
*
* @param {string} objectName
* @param {RawBindingParams | ValueMap} [params]
* @param {Knex.Transaction} [trx]
* @returns {Promise<T | null>}
*/
invoke<T_14>(objectName: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_14 | null>;
/**
* Execute a procedure and return the results returned (if any).
*
* Example usage:
*
* await Recommendation.exec<string>('dbo.update_top_recommendations', { userId: 10, type });
*
* // => Runs SQL: EXEC dbo.update_top_recommendations :userId, :type
* // => Binds params: { userId: 10, type }
*
* @param {string} objectName
* @param {RawBindingParams | ValueMap} [params]
* @param {Knex.Transaction} [trx]
* @returns {Promise<T[]>}
*/
exec<T_15>(objectName: string, params?: any, trx?: Knex.Transaction<any, any> | undefined): Promise<T_15[]>;
/**
* Build param object for given id.
*
* @param {any} id
* @returns {object}
*/
buildIdParams(id: any): any;
};