knex/knex-utils — 7★ on GitHub (TypeScript). Useful utilities for Knex.js
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
checkHeartbeat(knex: Knex, heartbeatQuery?: string) - run a SQL query against DB to check if it is responding. If query is not specified, uses the default one, which should work on majority of RDBMS, other than Oracle. Returned entity structure:
HEARTBEAT_QUERIES - a map of SQL queries for performing a heartbeat check on various databases.
DB param object manipulation
copyWithoutUndefined(originalValue: T): T - returns a copy of provided object without properties that have undefined value. This is useful, because while Knex treats null as a SQL null value (e. g. "Return all rows where column XYZ is set to NULL"), it considers undefined to be an input error. Therefore, it is common to write update operations like this:
groupBy(inputArray: T[], propName: string): Record<string, T> - Creates an object composed of keys that are equal to the values of properties specified by propName in the original data. Values of that object's fields are arrays, filled with original objects from inputArray.
isEmptyObject(params: Record<string, any>): boolean - returns true, if object has only undefined properties. This is useful e. g. for optional update params, to determine whether whole operation can be skipped. For a full example see pick method.
pick(source: T, propNames: K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>> - returns a new object which includes all the properties, specified in the argument propNames. It is helpful for extracting a subset of parameters for passing across the layers, for an example, when a single service call results in two repository calls:
async function updateFullUser(
userId: number,
fullUserUpdate: FullUserUpdate,
): Promise<UserUpdateDto> {
const existingUser = await getUser(userId)
const existingEmployee = await getEmployeeByUserId(userId)
if (!existingUser) {
throw new Error('User does not exist')
}
if (!existingEmployee) {
throw new Error('Employee does not exist')
}
const userUpdates = pick(fullUserUpdate, [
'userId',
'name',
'email',
])
const employeeUpdate = pick(fullUserUpdate, [
'userId',
'employmentNumber',
'position',
'worksFrom',
'worksTo',
])
let updatedUser: UserRow = existingUser
let updatedEmployee: EmployeeRow = existingEmployee
if (!isEmptyObject(userUpdates)) {
updatedUser = await updateUser(userId, userUpdates)
}
if (!isEmptyObject(employeeUpdate)) {
updatedEmployee = await updateEmployee(userId, employeeUpdate)
}
return { ...updatedUser, ...updatedEmployee }
}
pickWithoutUndefined(source: T, propNames: K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>> - same as pick, but skips properties with value undefined.
strictPickWithoutUndefined(source: T, propNames: K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>> - same as pick, but skips properties with value undefined. Throws an error if source has any fields not included in propNames.
validateOnlyWhitelistedFieldsSet(source: Record<string, any>, propNames: Set<string>) - throws an error if source has any fields not included in propnames
DB relation difference operations
calculateEntityListDiff(oldList: T[], newList: T[], idFields: string[]): EntityListDiff<T> - given the two lists of entities, identity of said entities defined by a given set of properties, calculates two lists of entities: the ones that were removed, and the ones that were added in the new list, as compared to the old list.
updateJoinTable(knex: Knex, newList: T[], params: UpdateJoinTableParams): EntityListDiff<T> - compares a new list of entities to a current state of database, deletes all entries that are no longer in the list.
interface UpdateJoinTableParams {
filterCriteria: Record<string, any> // Parameters that will be used for retrieving the old list. Typically you would be using all or some fields from `idFields` param for the filter query, to ensure you are only updating relationships of a specific parent, although it is not impossible to imagine a scenario when you would like to potentially repopulate the whole table, which would require empty filter criteria.
table: string // DB table that will be used for retrieving existing data, and deleting removed / inserting added data.
idFields: string[] // Combination of fields that allows to uniquely identify each entity. For a join table that typically would be a combination of all the foreign key columns, but sometimes it may include additional columns as well (e. g. a columnm, specifying relation type between the linked entities). Note that it probably shouldn't be a synthetic, DB sequence-based primary key, because for new entries that were not yet inserted, you are unlikely to have them.
primaryKeyField?: string // If table has single primary key that uniquely identifies each row (typically a synthetic, DB sequence-based one), it can be used for batch deletion of removed entries, dramatically improving performance.
chunkSize?: number // How many rows per statement should be used for batch insert/delete operations. Default is 100
transaction?: Knex.Transaction // If set, whole operation will be executed in provided transaction
transactionProvider?: Knex.TransactionProvider // If set, whole operation will be executed using transaction resolved from provided transactionProvider
}
Note that this is not an upsert operation and should not be used as one. If there is a match based on idFields property combination, even if other fields are different, this method will leave the row as-is. As the name of the function suggests, this is primarily useful for the join table situation, when you might want to perform multiple deletion and insertion operations to reach the desired state.
Example:
const oldList = generateAssets(0, { orgId: 'kiberion', linkType: 'primaryAsset' }, 10)
await knex('joinTable').insert(oldList)
const newList = generateAssets(10000, { orgId: 'kiberion', linkType: 'primaryAsset' }, 4)
const mixedList = [oldList[0], ...newList]
// this will result in all the elements from the old list, other than the first one, to be deleted, and all the elements in the new list to be inserted
await updateJoinTable(knex, mixedList, {
primaryKeyField: 'id',
idFields: ['userId', 'orgId', 'linkType'],
table: 'joinTable',
filterCriteria: {
orgId: 'kiberion',
linkType: 'primaryAsset',
},
})
No homepage URL was recorded for knex/knex-utils in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Does knex/knex-utils have any tags?
TopGit's last sync did not record any GitHub topics for knex/knex-utils. GitHub topics appear in the right sidebar of a repository page; that's the authoritative place to check.
How active is development on knex/knex-utils?
The most recent commit recorded on knex/knex-utils was 3.2 years ago, based on the GitHub push timestamp. The repository has 5 forks — one of the better signals of community interest.
How many stars does knex/knex-utils have?
knex/knex-utils has 7 GitHub stars — refresh the page for the live number, or check github.com/knex/knex-utils. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What language is knex/knex-utils written in?
knex/knex-utils is written primarily in TypeScript. GitHub's language field is based on the largest share of bytes in the default branch.
What license does knex/knex-utils use?
knex/knex-utils is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about knex/knex-utils?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/knex/knex-utils is the definitive source.
Read full README in the tab above.
Want a second opinion on knex-utils?
Ask an AI that can read this page — one click and you get its take on knex-utils.
/knex-utils
