knex-utils - npm Package Compare versions

Comparing version 5.0.0 to 5.1.0

dist/index.d.ts

@@ -1,2 +0,5 @@
-export { checkHeartbeat } from './lib/heartbeatUtils';
-export { copyWithoutUndefined, pick } from './lib/objectUtils';
+export { checkHeartbeat, HEARTBEAT_QUERIES } from './lib/heartbeatUtils';
+export { copyWithoutUndefined, pick, isEmptyObject } from './lib/objectUtils';
+export { chunk } from './lib/chunkUtils';
+export { updateJoinTable, calculateEntityListDiff } from './lib/diffUtils';
+export type { UpdateJoinTableParams, EntityListDiff } from './lib/diffUtils';

dist/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pick = exports.copyWithoutUndefined = exports.checkHeartbeat = void 0;
+exports.calculateEntityListDiff = exports.updateJoinTable = exports.chunk = exports.isEmptyObject = exports.pick = exports.copyWithoutUndefined = exports.HEARTBEAT_QUERIES = exports.checkHeartbeat = void 0;
 var heartbeatUtils_1 = require("./lib/heartbeatUtils");
 Object.defineProperty(exports, "checkHeartbeat", { enumerable: true, get: function () { return heartbeatUtils_1.checkHeartbeat; } });
+Object.defineProperty(exports, "HEARTBEAT_QUERIES", { enumerable: true, get: function () { return heartbeatUtils_1.HEARTBEAT_QUERIES; } });
 var objectUtils_1 = require("./lib/objectUtils");
 Object.defineProperty(exports, "copyWithoutUndefined", { enumerable: true, get: function () { return objectUtils_1.copyWithoutUndefined; } });
 Object.defineProperty(exports, "pick", { enumerable: true, get: function () { return objectUtils_1.pick; } });
+Object.defineProperty(exports, "isEmptyObject", { enumerable: true, get: function () { return objectUtils_1.isEmptyObject; } });
+var chunkUtils_1 = require("./lib/chunkUtils");
+Object.defineProperty(exports, "chunk", { enumerable: true, get: function () { return chunkUtils_1.chunk; } });
+var diffUtils_1 = require("./lib/diffUtils");
+Object.defineProperty(exports, "updateJoinTable", { enumerable: true, get: function () { return diffUtils_1.updateJoinTable; } });
+Object.defineProperty(exports, "calculateEntityListDiff", { enumerable: true, get: function () { return diffUtils_1.calculateEntityListDiff; } });
 //# sourceMappingURL=index.js.map

dist/lib/objectUtils.d.ts

 export declare function copyWithoutUndefined<T extends Record<K, V>, K extends string | number | symbol, V>(originalValue: T): T;
-export declare function pick<T, K extends string | number | symbol>(source: T, names: readonly K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>>;
+export declare function pick<T, K extends string | number | symbol>(source: T, propNames: readonly K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>>;
+export declare function isEmptyObject(params: Record<string, any>): boolean;

dist/lib/objectUtils.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pick = exports.copyWithoutUndefined = void 0;
+exports.isEmptyObject = exports.pick = exports.copyWithoutUndefined = void 0;
 function copyWithoutUndefined(originalValue) {
@@ -15,9 +15,9 @@ return Object.keys(originalValue).reduce((acc, key) => {
 exports.copyWithoutUndefined = copyWithoutUndefined;
-function pick(source, names) {
+function pick(source, propNames) {
     const result = {};
     let idx = 0;
-    while (idx < names.length) {
-        if (names[idx] in source) {
+    while (idx < propNames.length) {
+        if (propNames[idx] in source) {
             // @ts-ignore
-            result[names[idx]] = source[names[idx]];
+            result[propNames[idx]] = source[propNames[idx]];
         }
@@ -29,2 +29,11 @@ idx += 1;
 exports.pick = pick;
+function isEmptyObject(params) {
+    for (const key in params) {
+        if (params.hasOwnProperty(key) && params[key] !== undefined) {
+            return false;
+        }
+    }
+    return true;
+}
+exports.isEmptyObject = isEmptyObject;
 //# sourceMappingURL=objectUtils.js.map

package.json

 {
   "name": "knex-utils",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "license": "MIT",
@@ -19,2 +19,3 @@ "maintainers": [
     "test": "jest --config=jest.config.json --runInBand",
+    "test:update-snapshots": "jest --config=jest.config.json --runInBand -u",
     "test:coverage": "jest --config=jest.config.json --coverage --runInBand",
@@ -31,3 +32,3 @@ "test:ci": "npm run lint && npm run test:coverage",
     "@types/jest": "^26.0.23",
-    "@types/node": "^15.12.4",
+    "@types/node": "^15.12.5",
     "@typescript-eslint/eslint-plugin": "^4.28.0",
@@ -43,3 +44,3 @@ "@typescript-eslint/parser": "^4.28.0",
     "pg": "^8.6.0",
-    "prettier": "^2.3.1",
+    "prettier": "^2.3.2",
     "sqlite3": "^5.0.2",
@@ -62,3 +63,7 @@ "tedious": "^11.0.9",
     "utilities",
-    "heartbeat"
+    "heartbeat",
+    "join",
+    "batch",
+    "chunk",
+    "diff"
   ],
@@ -65,0 +70,0 @@ "files": [

README.md

 # knex-utils
 
-[![npm version](http://img.shields.io/npm/v/knex.svg)](https://npmjs.org/package/knex)
+[![npm version](http://img.shields.io/npm/v/knex-utils.svg)](https://npmjs.org/package/knex-utils)
+[![NPM Downloads](https://img.shields.io/npm/dm/knex-utils.svg)](https://npmjs.org/package/knex-utils)
 ![](https://github.com/knex/knex-utils/workflows/CI/badge.svg)
@@ -8,1 +9,113 @@ [![Coverage Status](https://coveralls.io/repos/knex/knex-utils/badge.svg?branch=master)](https://coveralls.io/r/knex/knex-utils?branch=master)
 Useful utilities for Knex.js
+
+## Library documentation
+
+### Database heartbeat
+
+* `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:
+```ts
+interface HeartbeatResult {
+    isOk: boolean
+    error?: Error
+}
+```  
+
+* `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:
+
+```ts
+  async function updateUser(knex: Knex, userId: number, userUpdate: UpdateUserRow): Promise<UserRow> {
+    const userUpdateParams = copyWithoutUndefined({
+      name: userUpdate.name,
+      email: userUpdate.email,
+    })
+
+    const updatedUserRows = await knex('users')
+      .where({ userId })
+      .update(updateUserParams)
+      .returning(['userId', 'name', 'email']])
+
+    return updatedUserRows[0]
+  }
+```
+
+* `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:
+
+```ts
+  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 }
+  }
+```
+
+### 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.
+
+```ts
+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
+}
+```
+
+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:
+```ts
+  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',
+    },
+  })
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

26454

increased by201.26%

Number of package files

18

increased by50%

Lines of code

265

increased by178.95%

Number of lines in readme file

121

increased by1412.5%

No dependency changes