@villedemontreal/utils-knex 7.0.1

package/README.md

@@ -0,0 +1,236 @@
+# @villemontreal/core-utils-knex-nodejs-lib
+
+Module d'utilitaires pour la librairie Knex.
+
+## Availabililty
+
+https://bitbucket.org/villemontreal/core-utils-knex-nodejs-lib
+
+## Installation
+
+Installer la bibliothèque:
+
+```shell
+    npm install --save @villemontreal/test-core-utils-knex-nodejs-lib
+```
+
+## Utilisation
+
+# Configurations
+
+Un code utilisant cette librarie doit premièrement la configurer en appellant la fonction
+"`ìnit(...)`" exportée par le fichier "`src/config/init.ts`".
+
+La configuration "`loggerCreator`" est _requise_ par cette librairie. Cela signifie qu'un code utilisant la librairie
+(que ce soit du code d'un projet d'API ou d'une autre librairie) _doit_ setter cette configuration _avant_ que les composants
+de la librairie ne soient utilisés.
+
+Par exemple, dans un projet d'API basé sur le générateur
+[generator-mtl-node-api](https://bitbucket.org/villemontreal/generator-mtl-node-api), ceci sera effectué dans le
+fichier "`src/init.ts`", au début de la fonction `initComponents()` :
+
+```typescript
+import { init as initKnexUtilsLib } from '@villemontreal/core-utils-knex-nodejs-lib';
+import { createLogger } from './utils/logger';
+
+export async function initComponents() {
+  initKnexUtilsLib(createLogger);
+
+  //...
+}
+```
+
+Si vous configurez la librairie depuis _une autre librairie_, vous aurez à passer
+le "`Logger Creator`" que vous aurez _vous-même_ reçu comme configurations! :
+
+```typescript
+import { init as initKnexUtilsLib } from '@villemontreal/core-utils-knex-nodejs-lib';
+import { configs } from './configs';
+
+export async function initComponents() {
+  initKnexUtilsLib(configs.loggerCreator);
+
+  //...
+}
+```
+
+Le but étant que toutes les librairies utilisées dans un projet d'API, ainsi que leurs propres librairies
+transitives, puissent logger de la même manière et aient accès aux bons Correlation Ids.
+
+Finalement, notez qu'une fonction "`isInited()`" est exportée et permet au code appelant de valider que la librairie a été
+configurée correctement!
+
+# Builder le projet
+
+**Note**: Sur Linux/Mac assurz-vous que le fichier `run` est exécutable. Autrement, lancez `chmod +x ./run`.
+
+Pour lancer le build :
+
+- > `run compile` ou `./run compile` (sur Linux/Mac)
+
+Pour lancer les tests :
+
+- > `run test` ou `./run test` (sur Linux/Mac)
+
+# Mode Watch
+
+Lors du développement, il est possible de lancer `run watch` (ou `./run watch` sur Linux/mac) dans un terminal
+externe pour démarrer la compilation incrémentale. Il est alors possible de lancer certaines _launch configuration_
+comme `Debug current tests file - fast` dans VsCode et ainsi déboguer le fichier de tests présentement ouvert sans
+avoir à (re)compiler au préalable (la compilation incrémentale s'en sera chargé).
+
+Notez que, par défaut, des _notifications desktop_ sont activées pour indiquer visuellement si la compilation
+incrémentale est un succès ou si une erreur a été trouvée. Vous pouvez désactiver ces notifications en utilisant
+`run watch --dn` (`d`isable `n`otifications).
+
+# Déboguer le projet
+
+Trois "_launch configurations_" sont founies pour déboguer le projet dans VSCode :
+
+- "`Debug all tests`", la launch configuration par défaut. Lance les tests en mode debug. Vous pouvez mettre
+  des breakpoints et ils seront respectés.
+
+- "`Debug a test file`". Lance _un_ fichier de tests en mode debug. Vous pouvez mettre
+  des breakpoints et ils seront respectés. Pour changer le fichier de tests à être exécuté, vous devez modifier la ligne appropriée dans le fichier "`.vscode/launch.json`".
+
+- "`Debug current tests file`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Effectue la compîlation au préalable.
+
+- "`Debug current tests file - fast`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Aucune compilation
+  n'est effectuée au préalable. Cette launch configuration doit être utilisée lorsque la compilation incrémentale roule (voir la section "`Mode Watch`" plus haut)
+
+# Gérer les transactions SQL dans son projet/API
+
+Dans cette librairie est fourni un composant nommé `KnexTransactionManager` permettant d'exécuter
+plusieures requêtes SQL au sein d'une même transaction. Si une des requêtes échoue,
+toutes les requêtes déjà effectuées seront rollbackées. En d'autres mots, toutes les requêtes doivent
+résulter en un succès ou _aucune_ ne sera commitée.
+
+Le pattern utilisé pour arriver à gérer de telles transactions est de passer un `context` (implémentant
+l'interface `IDatabaseContext`) _à chaque méthodes suceptible d'exécuter, directement ou indirectement, une requête SQL_.
+En gros, il s'agit de passer l'object `context`, que nous recevrons nous-mêmes, à toutes les
+méthodes de _services_ ou de _repositories_ que nous appellons.
+
+Il est fortement recommandé que ce paramètre `context` soit _toujours_ le premier dans la signature d'une méthode.
+Par exemple, dans un service fictif `UserService`, il pourrait y avoir une méthode `updateUser`
+prennant ce `context` comme premier paramètre:
+
+```typescript
+public async updateUser(context: IAppContext, userId: number, userToUpdate: IUser) {
+
+  // On démarre un scope de transaction avec `withTransaction`
+  await txManager.withTransaction(context, async (client: knex.Transaction) => {
+
+    // Appel à une repository, en lui passant le contexte
+    const updatedUser = await userRepository.updateUser(context, userId, userToUpdate);
+
+    // Appel à un autre service, en lui passant  le contexte
+    await indexationService.updateUserIndex(context, updatedUser);
+
+    // Fait une requête SQL directement en utilisant
+    // le client fourni par `withTransaction`!
+    const res = await client(`statistics`).insert({
+        something: 'blablabla'
+    });
+  });
+}
+```
+
+Dans cet exemple on voit que:
+
+- la méthode `updateUser` du service reçoit un `context` comme premier paramètre. C'est ce
+  `context` qu'elle devra elle-même passer aux autres méthodes qu'elles appellera. Vous
+  avez peut-être remarqué que le type de ce `context` est ici `IAppContext` et non `IDatabaseContext`!
+  Il est en effet fréquent qu'une application crée son propre type de context
+  _implémentant `IDatabaseContext`_. Ceci lui permet de passer des informations supplémentaires,
+  de méthode en méthode! Par exemple, ce context spécialisé pourrait comprendre le `JWT` reçu lors de
+  la requête HTTP, les paramètres de cette requête HTTP, etc. Par exemple:
+  ```typescript
+  export interface IAppContext extends IDatabaseContext {
+    jwt: IJWTPayload;
+  }
+  ```
+- Les appels devant faire partie d'une même transaction sont exécutés dans le "scope" de
+  `txManager.withTransaction(...)`. Le code appellé reçoit un `client knex`, et c'est
+  ce client qu'il doit utiliser pour effectuer ses requêtes SQL. Dans notre exemple, le service
+  ne fait une seule requête SQL par lui-même: `client("statistics").insert(...)`. Mais il passe
+  son `context` à une repossitory et à un autre service pour que la transaction qu'il a démarrée soit
+  poursuivie correctement par ces composants.
+
+Il faut savoir que la création de l'objet `context` _original_, celui qui devra par la suite être
+passé de méthode en méthode, se fait en général _dans le contrôleur_ qui reçoit une requête HTTP.
+Ce `context` initial aura sa propriété `currentKnexClient` non définie. C'est le premier appel à
+`withClient` ou `withTransaction` qui s'occupera de le populer (puis de le tenir à jour).
+
+Notez qu'en plus de `withTransaction`, le composant `KnexTransactionManager` fournit aussi une méthode
+`withClient`. L'utilisation est la même, à la différence près qu'aucune transaction n'est
+démarrée avec `withClient`. Ceci dit, il est possible que la méthode où s'effectue la requête
+ne nécessitant pas de transaction _ait elle-même été appellée au sein d'un `withTransaction`_, bref dans le scope d'une transaction, par du code appelant! Dans cette situation, en utilisant le client knex fourni par `withClient`,
+la transaction se poursuivra correctement. C'est pour cette raison qu'il faut _toujours_ utiliser
+le client knex fourni par `withClient` et non un client knex créé manuellement...
+`withClient` et `withTransaction` inspectent le `context` qui leur est passé et retourne un client
+knex bien configuré, selon la situation.
+
+Notez aussi que si `withTransaction` est appellée mais que le code est _déjà_ dans le scope
+d'une transaction démarrée par du code appelant, la transaction déjà existante se poursuivera.
+Il n'y aura pas de nouvelle transaction de démarrée.
+
+Notez finalement qu'il peut être intéressant de wrapper les méthodes du `KnexTransactionManager`
+dans des méthodes custom, pour simplifier et modifier leur utilisation. Par exemple:
+
+```typescript
+  public async withTransaction<T>(
+    context: IAppContext,
+    fnt: (client: knex.Transaction) => Promise<T>
+  ): Promise<T> {
+    return this.getKnexTransactionManager().withTransaction<T>(context, async (client: knex) => {
+      try {
+        return await fnt(client as any);
+      } catch (err) {
+        // ==========================================
+        // Ici, nous pourrions avoir du code convertissant
+        // les erreurs BD en erreur d'API standardisées,
+        // par exemple.
+        // ==========================================
+        throw createErrorFromDatabaseError(err);
+      }
+    });
+  }
+```
+
+Par la suite:
+
+```typescript
+// Utilisation de notre méthode `withTransaction` custom.
+await withTransaction(context, async (client: knex.Transaction) => {
+  const res = await client(`statistics`).insert({
+    something: 'blablabla',
+  });
+});
+```
+
+**NOTE**: Voir le fichier de tests `src/transactionManager.test.ts` pour un exemple d'utilisation
+du `KnexTransactionManager`.
+
+# Versions et compatibilité
+
+### 5.0.0
+
+Utilise la version 5.0.0 de sqlite3
+
+#### Compatibilité
+
+- NodeJS : 16
+
+# Test et publication de la librairie sur Nexus
+
+En mergant une pull request dans la branche `develop`, un artifact "`-pre.build`" sera créé automatiquement dans Nexus. Vous
+pouvez utiliser cette version temporaire de la librairie pour bien la tester dans un réel projet.
+
+Une fois mergée dans `master`, la librairie est définitiement publiée dans Nexus, en utilisant la version spécifiée dans
+le `package.json`.
+
+# Aide / Contributions
+
+Pour obtenir de l'aide avec cette librairie, vous pouvez poster sur la salle Google Chat [dev-discussions](https://chat.google.com/room/AAAASmiQveI).
+
+Notez que les contributions sous forme de pull requests sont bienvenues.

package/dist/src/config/configs.d.ts

@@ -0,0 +1,19 @@
+import { ILogger } from '@villedemontreal/logger';
+export declare class Configs {
+    /**
+     * Absolute path to the root of the project.
+     */
+    root: string;
+    constructor();
+    private _loggerCreator;
+    /**
+     * The Logger creator
+     */
+    get loggerCreator(): (name: string) => ILogger;
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator: (name: string) => ILogger): void;
+}
+export declare const configs: Configs;
+//# sourceMappingURL=configs.d.ts.map

package/dist/src/config/configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.d.ts","sourceRoot":"","sources":["../../../src/config/configs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGlD,qBAAa,OAAO;IAClB;;OAEG;IACI,IAAI,EAAE,MAAM,CAAC;;IAMpB,OAAO,CAAC,cAAc,CAA4B;IAElD;;OAEG;IACH,IAAI,aAAa,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAK7C;IAED;;OAEG;IACI,gBAAgB,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO;CAGjE;AAED,eAAO,MAAM,OAAO,EAAE,OAAuB,CAAC"}

package/dist/src/config/configs.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.Configs = void 0;
+const path = require("path");
+class Configs {
+    constructor() {
+        this.root = path.normalize(`${__dirname}/../../..`);
+    }
+    /**
+     * The Logger creator
+     */
+    get loggerCreator() {
+        if (!this._loggerCreator) {
+            throw new Error(`The Logger Creator HAS to be set as a configuration`);
+        }
+        return this._loggerCreator;
+    }
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator) {
+        this._loggerCreator = loggerCreator;
+    }
+}
+exports.Configs = Configs;
+exports.configs = new Configs();
+//# sourceMappingURL=configs.js.map

package/dist/src/config/configs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.js","sourceRoot":"","sources":["../../../src/config/configs.ts"],"names":[],"mappings":";;;AACA,6BAA6B;AAE7B,MAAa,OAAO;IAMlB;QACE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,SAAS,WAAW,CAAC,CAAC;IACtD,CAAC;IAID;;OAEG;IACH,IAAI,aAAa;QACf,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;OAEG;IACI,gBAAgB,CAAC,aAAwC;QAC9D,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;IACtC,CAAC;CACF;AA5BD,0BA4BC;AAEY,QAAA,OAAO,GAAY,IAAI,OAAO,EAAE,CAAC"}

package/dist/src/config/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Application constants
+ */
+export declare class Constants {
+    /**
+     * The library root. When this library is used
+     * as a dependency in a project, the "libRoot"
+     * will be the path to the dependency folder,
+     * inside the "node_modules".
+     */
+    libRoot: string;
+    /**
+     * The app root. When this library is used
+     * as a dependency in a project, the "appRoot"
+     * will be the path to the root project!
+     */
+    appRoot: string;
+    constructor();
+}
+export declare const constants: Constants;
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/config/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/config/constants.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,qBAAa,SAAS;IACpB;;;;;OAKG;IACI,OAAO,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACI,OAAO,EAAE,MAAM,CAAC;;CAOxB;AAED,eAAO,MAAM,SAAS,EAAE,SAA2B,CAAC"}

package/dist/src/config/constants.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constants = exports.Constants = void 0;
+// ==========================================
+// Application constants
+// ==========================================
+const app_root_path_1 = require("app-root-path");
+const path = require("path");
+/**
+ * Application constants
+ */
+class Constants {
+    constructor() {
+        // From the "dist/src/config" folder
+        this.libRoot = path.normalize(__dirname + '/../../..');
+        this.appRoot = app_root_path_1.path;
+    }
+}
+exports.Constants = Constants;
+exports.constants = new Constants();
+//# sourceMappingURL=constants.js.map

package/dist/src/config/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/config/constants.ts"],"names":[],"mappings":";;;AAAA,6CAA6C;AAC7C,wBAAwB;AACxB,6CAA6C;AAC7C,iDAAgD;AAChD,6BAA6B;AAE7B;;GAEG;AACH,MAAa,SAAS;IAgBpB;QACE,oCAAoC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,oBAAO,CAAC;IACzB,CAAC;CACF;AArBD,8BAqBC;AAEY,QAAA,SAAS,GAAc,IAAI,SAAS,EAAE,CAAC"}

package/dist/src/config/init.d.ts

@@ -0,0 +1,16 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Inits the library.
+ */
+export declare function init(loggerCreator: (name: string) => ILogger): void;
+/**
+ * Is the library properly initialized?
+ *
+ * This function MUST be named "isInited()"!
+ * Code using this library may loop over all its "@villemontreal"
+ * dependencies and, if one of those exports a "isInited" fonction,
+ * it will enforce that the lib has been properly initialized before
+ * starting...
+ */
+export declare function isInited(): boolean;
+//# sourceMappingURL=init.d.ts.map

package/dist/src/config/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/config/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAKlD;;GAEG;AACH,wBAAgB,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,QAW5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC"}

package/dist/src/config/init.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+exports.isInited = isInited;
+const configs_1 = require("./configs");
+let libIsInited = false;
+/**
+ * Inits the library.
+ */
+function init(loggerCreator) {
+    if (!loggerCreator) {
+        throw new Error(`The Logger Creator is required.`);
+    }
+    configs_1.configs.setLoggerCreator(loggerCreator);
+    // ==========================================
+    // Set as being "properly initialized".
+    // At the very end of the "init()" function!
+    // ==========================================
+    libIsInited = true;
+}
+/**
+ * Is the library properly initialized?
+ *
+ * This function MUST be named "isInited()"!
+ * Code using this library may loop over all its "@villemontreal"
+ * dependencies and, if one of those exports a "isInited" fonction,
+ * it will enforce that the lib has been properly initialized before
+ * starting...
+ */
+function isInited() {
+    return libIsInited;
+}
+//# sourceMappingURL=init.js.map

package/dist/src/config/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/config/init.ts"],"names":[],"mappings":";;AAQA,oBAWC;AAWD,4BAEC;AA/BD,uCAAoC;AAEpC,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB;;GAEG;AACH,SAAgB,IAAI,CAAC,aAAwC;IAC3D,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,iBAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAExC,6CAA6C;IAC7C,uCAAuC;IACvC,4CAA4C;IAC5C,6CAA6C;IAC7C,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,QAAQ;IACtB,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/src/databaseContext.d.ts

@@ -0,0 +1,9 @@
+import { Knex } from 'knex';
+/**
+ * A Context that can be used to get the current database
+ * client, if any. This allows the use of nested transactions.
+ */
+export interface IDatabaseContext {
+    currentKnexClient?: Knex;
+}
+//# sourceMappingURL=databaseContext.d.ts.map

package/dist/src/databaseContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"databaseContext.d.ts","sourceRoot":"","sources":["../../src/databaseContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,EAAE,IAAI,CAAC;CAC1B"}

package/dist/src/databaseContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=databaseContext.js.map

package/dist/src/databaseContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"databaseContext.js","sourceRoot":"","sources":["../../src/databaseContext.ts"],"names":[],"mappings":""}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './config/init';
+export * from './databaseContext';
+export * from './knexUtils';
+export * from './transactionManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// ==========================================
+// We do not export the configs instance itself,
+// only the "init()" method, so we can define
+// which are the required parameters.
+// ==========================================
+__exportStar(require("./config/init"), exports);
+__exportStar(require("./databaseContext"), exports);
+__exportStar(require("./knexUtils"), exports);
+__exportStar(require("./transactionManager"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA6C;AAC7C,gDAAgD;AAChD,6CAA6C;AAC7C,qCAAqC;AACrC,6CAA6C;AAC7C,gDAA8B;AAC9B,oDAAkC;AAClC,8CAA4B;AAC5B,uDAAqC"}

package/dist/src/knexUtils.d.ts

@@ -0,0 +1,134 @@
+import { IPaginatedResult } from '@villedemontreal/general-utils';
+import { Knex } from 'knex';
+import * as sinon from 'sinon';
+/**
+ * Knex utilities
+ */
+export declare class KnexUtils {
+    protected static KNEX_TOTAL_COUNT_QUERY_COLUMN_NAME: string;
+    protected static TOTAL_COUNT_BUILDER_OPTION_NAME: string;
+    /**
+     * Takes a Knex.QueryBuilder, which is the object created
+     * when defining a Knex query, an returns the rows total count.
+     *
+     * This function is useful when you already have a SELECT Knex query,
+     * but you only need the rows total count instead of the rows themselves!
+     *
+     * Warning!! This function only works with SELECT queries, and
+     * may fail in some untested complex situations... It only has
+     * been tested with simple select/from/where/orderBy queries.
+     *
+     * Example :
+     *
+     * const queryBuilder = client
+     *       .from(BOOKS_TABLE_NAME)
+     *       .orderBy("author");
+     *
+     * ... and then, instead of executing the query, by using
+     * "then()" or "await", you pass the builder to the
+     * "totalCount()" function :
+     *
+     * let totalCount: number = await knexUtils.totalCount(client, queryBuilder);
+     *
+     */
+    totalCount(knex: Knex, selectBuilder: Knex.QueryBuilder): Promise<number>;
+    /**
+     * Takes a Knex.QueryBuilder, which is the object created
+     * when defining a Knex query, a limit and a current
+     * page, then return a IPaginatedResult.
+     *
+     * In other words, instead of executing the query you
+     * are building with Knex directly, you pass the unsent
+     * builder to this function and you get :
+     * - Pagination for your query
+     * - The total number of elements your query would return if it
+     *   wasn't paginated.
+     *
+     * Warning!! This function only works with SELECT queries, and
+     * may fail in some untested complex situations... It only has
+     * been tested with simple select/from/where/orderBy queries.
+     *
+     * If this function fails for one of your query, you'll have to
+     * duplicate the code of that query to make two separate queries :
+     * one for the rows only and one for the total count only.
+     *
+     * For example, to get 3 items starting at offset 9 :
+     *
+     *  const paginatedResult = await knexUtils.paginate(
+     *    client,
+     *    client
+     *      .select("id", "author", "title")
+     *      .from(BOOKS_TABLE_NAME)
+     *      .orderBy("author"),
+     *    9, 3);
+     */
+    paginate(knex: Knex, selectBuilder: Knex.QueryBuilder, offset: number, limit: number): Promise<IPaginatedResult<any>>;
+    /**
+     * Creates a mocked Knex client, linked to a dummy database.
+     * The client allows you to define stubs that will simulate
+     * the result from the DB.
+     *
+     * Useful for testing!
+     */
+    createKnexMockedClient: () => Promise<IKnexMockedClient>;
+    /**
+     * For Oracle.
+     * Wraps a column name (or a "?") with LOWER or with a CONVERT function
+     * which will strip accents.
+     */
+    wrapWithOracleModificationkeywords(columnNameOrInterrogationMark: string, isConvert: boolean, isLower: boolean): string;
+    /**
+     * For Oracle.
+     * Adds a LIKE clause, where the values can be compared lowercased (isLower), by removing the
+     * accents first (isConvert), and where the "val" can starts or ends with a "*" wildcard.
+     */
+    addOracleLikeClause(queryBuilder: Knex.QueryBuilder, columnName: string, val: string, isConvert: boolean, isLower: boolean): Knex.QueryBuilder;
+    /**
+     * For SQL Server.
+     * Wraps a column name (or a "?") with LOWER and/or with a CAST function
+     * which will strip accents.
+     */
+    wrapWithSqlServerModificationKeywords(columnNameOrInterrogationMark: string, isConvert: boolean, isLower: boolean): string;
+    /**
+     * For SQL Server.
+     * Adds a LIKE clause, where the values can be compared lowercased (lower), by removing the
+     * accents first (removeAccent), and where the "val" can starts or ends with a "*" wildcard
+     * (acceptWildcard).
+     */
+    addSqlServerLikeClause(queryBuilder: Knex.QueryBuilder, columnName: string, val: string, acceptWildcard: boolean, removeAccents: boolean, lower: boolean): Knex.QueryBuilder;
+    /**
+     * @param totalCountOnly if true, only the request to get the total count will
+     * be made and an empty array will be returned as the rows.
+     */
+    protected paginateOrTotalCount(knex: Knex, selectBuilder: Knex.QueryBuilder, offset: number, limit: number, totalCountOnly?: boolean): Promise<IPaginatedResult<any>>;
+}
+export declare const knexUtils: KnexUtils;
+/**
+ * A Mocked Knex client.
+ */
+export interface IKnexMockedClient extends Knex {
+    /**
+     * The stub that is going to return the result
+     * when the query is executed.
+     *
+     * Defaults to an empty array.
+     */
+    resultStub: sinon.SinonStub;
+    /**
+     * If the query is paginated, this stub
+     * will return the "totalCount" part of
+     * the result.
+     *
+     * Defaults to 0.
+     */
+    totalCountStub: sinon.SinonStub;
+    /**
+     * This spy is going to be called just before
+     * Knex actually execute the query. The builder
+     * has at this point been converted to a
+     * SQL string and you have access to this SQL and
+     * other informations.
+     */
+    beforeQuerySpy: sinon.SinonSpy;
+}
+//# sourceMappingURL=knexUtils.d.ts.map

package/dist/src/knexUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knexUtils.d.ts","sourceRoot":"","sources":["../../src/knexUtils.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAS,MAAM,gCAAgC,CAAC;AAEzE,OAAa,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B;;GAEG;AACH,qBAAa,SAAS;IACpB,SAAS,CAAC,MAAM,CAAC,kCAAkC,SAAW;IAC9D,SAAS,CAAC,MAAM,CAAC,+BAA+B,SAAyB;IAEzE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,QAAQ,CACnB,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,IAAI,CAAC,YAAY,EAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAKjC;;;;;;OAMG;IACI,sBAAsB,QAAa,OAAO,CAAC,iBAAiB,CAAC,CAsFlE;IAEF;;;;OAIG;IACI,kCAAkC,CACvC,6BAA6B,EAAE,MAAM,EACrC,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,GACf,MAAM;IAaT;;;;OAIG;IACI,mBAAmB,CACxB,YAAY,EAAE,IAAI,CAAC,YAAY,EAC/B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,GACf,IAAI,CAAC,YAAY;IAgCpB;;;;OAIG;IACI,qCAAqC,CAC1C,6BAA6B,EAAE,MAAM,EACrC,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,GACf,MAAM;IA0BT;;;;;OAKG;IACI,sBAAsB,CAC3B,YAAY,EAAE,IAAI,CAAC,YAAY,EAC/B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,OAAO,EACvB,aAAa,EAAE,OAAO,EACtB,KAAK,EAAE,OAAO,GACb,IAAI,CAAC,YAAY;IAmCpB;;;OAGG;cACa,oBAAoB,CAClC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,IAAI,CAAC,YAAY,EAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,cAAc,UAAQ,GACrB,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;CAiFlC;AACD,eAAO,MAAM,SAAS,EAAE,SAA2B,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI;IAC7C;;;;;OAKG;IACH,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC;IAE5B;;;;;;OAMG;IACH,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC;IAEhC;;;;;;OAMG;IACH,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC;CAChC"}