murmuration 1.1.7 → 1.1.13

package/README.md

@@ -1,19 +1,17 @@
 # Murmuration
 
-Database connections, transactions and migrations.
+Database statements, transactions and migrations.
 
 There are two specific packages that you should make use of instead this one:
 
 * [Murmuration-MariaDB](https://github.com/djalbat/murmuration-mariadb)
 * [Murmuration-PostGreSQL](https://github.com/djalbat/murmuration-postgresql)
 
-This readme file largely pertains to both, although there are also specific instructions given in readme file for each.
+This readme file pertains to both, although there are specific instructions for each of the above in their respective readme files.
 
-Murmuration is meant to be used as alternative to a database [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping). Aside from migrations, it is deliberately simple and low level, in the sense that it provides no more than the bare minimum functionality needed to connect to a database and run commands, optionally in the context of transactions.
+Murmuration can be used as alternative to a database [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping). It is deliberately simple and low level in the sense that it provides no more than the bare minimum functionality needed to connect to a database and generate statements to be executed ideally in the context of transactions. 
 
-The migration functionality, if used correctly, will guarantee that a Node application's codebase remains in line with the database it relies on, updating the latter each time the former is deployed.
-
-The prescriptions given below are an essential part of the package. They show how to write database utility functions at scale; how to employ them in the context of transactions; and they outline what needs to be done in order to guarantee the success of migrations.
+There is also some adjunct migration functionality that may or may not suit your use case. If used as prescribed then it guarantees that an application remains in line with its database, as the latter will be migrated if needed each time the former is deployed.
 
 ## Installation
 
@@ -33,120 +31,192 @@ Remember that it is the aforementioned specific packages that you should install
 
 ## Usage
 
-Functionality across the specific packages is identical, aside from small differences in configuration and error handling, and is therefore covered here.
+Aside from small differences in configuration and error handling the Functionality across the aforementioned specific packages is identical, and is therefore covered here.
 
-### Getting and releasing connections
+Statements are covered first up, but ideally they should be executed in the context of transactions and therefore the remainder of this section cannot be overlooked. In particular, the example statements that follow are executed within operations, which are covered in the later subsection on transactions.
 
-The static `fromConfiguration()` method of the `Connection` class takes a configuration and a callback argument:
+### Generating statements
 
-```
-Connection.fromConfiguration(configuration, (error, connection) => {
+Statements are generated dynamically, in a similar vein to an ORM, in this case with a simple, promise-like syntax. 
 
-  ...
+In the first example, a `SELECT` statement is generated that checks an `account` table and returns an `id` should the email address and password match:
 
-  connection.release();
-};
+```
+const using = require("../using");
+
+function checkAccountOperation(connection, abort, proceed, complete, context) {
+  const { emailAddress, password } = context;
+  
+  using(connection)
+    .selectFromAccont()
+    .where({ emailAddress, password })
+    .one(({ id }) => {
+      Object.assign(context, {
+        id
+      });
+    
+      proceed();
+    })
+    .else(() => {
+      ...
+    
+      complete()
+    })
+    .catch(abort)
+    .execute();
+}
 ```
 
-If successful, the `error` argument of the callback will be null and a `connection` object will be returned, otherwise the `error` argument will be truthy. Details of the format of the `configuration` object can be found in the configuration subsections of the specific package readme files.
+There are several points worth noting:
 
-### Logging
+* As already mentioned, ideally statements should be executed within operations. Each operation provides a connection and a context as well as three callbacks.
+* The three callbacks allow the result of the execution to determine whether the application should proceed to the next operation or if the transaction should be aborted or completed.
+* A local `using()` function has been employed rather the the function supplied by the package, because the `Statement` class it utilities has been extended for convenience. More on this later.
 
-Ideally you should add a `log` property to the `configuration` object that references an object of the following form:
+The remainder of the points pertain to the statement itself. An exhaustive description of the various methods available is given at the end of this subsection.
+
+* The `selectFromAccount()` is defined in the application's own `Statement` class, again more on this later.
+* The `where()` method takes a plain old JavaScript object.
+* The `one()` method takes a handler that is called if one row is returned.
+* The `else()` method takes a handler that is called in all other cases.
+* The `catch()` method takes a handler that is called should execution fail.
+
+Note that the assumption with passing a plain old JavaScript object in order to generate a `WHERE` clause is that the property values should be equated. Note also that the `abort()` function is provided directly to the `catch()` method.
+
+In the following example, rows in a table holding temporary reset codes are deleted once they expire.
 
 ```
-const log = {
-  trace: () => { ... },
-  debug: () => { ... },
-  info: () => { ... },
-  warning: () => { ... },
-  error: () => { ... },
-  fatal: () => { ... },
-});
+const using = require("../using");
+
+const { unauthorized } = require("../utilities/states");
+ 
+function deleteExpiredResetCodesOperation(connection, abort, proceed, complete, context) {
+  const { emailAddress, password } = context;
+    
+  using(connection)
+    .deleteFromResetCode()
+    .where`
+    
+      expires < NOW()
+    
+    `
+    .success(proceed)
+    .catch(abort)
+    .execute();
+}
 ```
-Currently only the `error()`, `info()` and `debug()` functions are made use of, but in future others may be utilised.
 
-If you do not provide a `log` object, all logging is suppressed.
+The following points are worth noting:
 
-### Error handling
+* The `where()` method takes a template literal this time.
+* The `success()` method takes a callback that is called should hte execution succeed.
 
-In the event of an error, if a `log` property has been added to the `configuration` object then the `log.error()` function will be called with a message containing a reasonable stab at the cause of the error. Details can be found in the subsections of the same name in the specific package readme files.
+In the following example, a row is inserted into a table for software packages:
 
-These messages are meant to help with debugging simple mistakes such as providing incorrect configuration. If you do not find them helpful, do not provide a `log` object and be assured that the errors are always returned by way of callback function arguments for you to deal with as you see fit.
+```
+const using = require("../using");
 
-### Running queries
+function createReleaseOperation(connection, abort, proceed, complete, context) {
+  const { name, entriesBlob, versionNumber } = context;
+
+  using(connection)
+    .insertIntoRelease()
+    .values({ name, entriesBlob, versionNumber })
+    .success(proceed)
+    .catch(abort)
+    .execute();
+}
+```
 
-Two functions are provided, namely `query()` and `execute()`. The former returns an error and an array of rows returned by the query by way of a callback, the latter only an error by way of a callback. Otherwise their signatures are the same:
+Note the following:
+
+* The `values()` method takes a plain old JavaScript object with the values to be inserted.
+
+Finally, the following operation updates a user profile:
 
 ```
-const sql = ... ;
+const using = require("../using");
+
+function editProfileOperation(connection, abort, proceed, complete, context) {
+  const { name, notes, userIdentifier } = context,
+        identifier = userIdentifier;	///
+
+  using(connection)
+    .updateUser()
+    .set({ name, notes })
+    .where({ identifier })
+    .success(proceed)
+    .execute();
+}
+```
 
-query(connection, sql, ...parameters, (error, rows) => {
+Note:
 
-  ...
+* The `set()` method takes a plain old JavaScript object.
 
-});
+Generally the idea is to be able to generate the most commonly used kinds of statements are deal with the outcomes of their execution with the minimum of fuss. If passing plain old JavaScript objects will not suffice then template literals can be used instead.
 
-execute(connection, sql, ...parameters, status, (error) => {
+### Statement class specification
 
-  ...
+The following specification gives a complete and more detailed list of the methods available.
 
-});
-```
-In both cases, a variable length list of parameters can be passed between the `sql` and `callback` arguments. These replace the placeholders in the SQL you provide. For more information, see the specific packages.
+* One of the `selectFrom()`, `insertInto()`, `deleteFrom()` or `delete()` methods must be called. Each takes a string for the name of a table or view. 
 
-To make use of these functions, it is recommended that you create a file corresponding to each table or view, naming the functions therein to reflect the SQL statements and parameters. The SQL they employ can be read from files, the names of which exactly match the function names. For example:
+It is recommended that these methods are not called directly, rather methods that call them indirectly are created on a subclass of the `Statement` class, in order to avoid repetition. This is covered in the later subsection on extending the `Statement` class.
 
-```
-const SELECT_USERNAME_FILE_NAME = "table/user/selectUsername.sql",
-      SELECT_IDENTIFIER_FILE_NAME = "table/user/selectIdentifier.sql",
-      SELECT_EMAIL_ADDRESS_FILE_NAME = "table/user/selectEmailAddress.sql",
-      UPDATE_NAME_IDENTIFIER_FILE_NAME = "table/user/updateNameIdentifier.sql",
-      ...
-      ;
+If the `selectFrom()` method is called, then one of the following of the following methods must be called. Each takes a callback:
 
-function selectUsername(connection, username, callback) { ... }
+* The `none()` method for when no rows are returned.
+* The `one()` method for when exactly one row is returned.
+* The `first()` method for when one or more rows are returned.
+* The `many()` method for when any number of rows are returned, including none.
 
-function selectIdentifier(connection, identifier, callback) { ... }
+In all but the last case, you must also call the `else()` method with a callback.
 
-function selectEmailAddress(connection, emailAddress, callback) { ... }
+* The `success()` method must accompany the `insertInto()`, `deleteFrom()` or `delete()` methods. 
+* The `catch()` method must always be called with a callback for when an exception occurs.
+* Either the `getSQL()` or `execute()` methods must be called, usually the latter.
 
-function updateNameIdentifier(connection, name, identifier, callback) { ... }
+If  
 
-...
-```
-The body of each of the function should be identical bar the parameters and the use of the `query()` versus the `execute()` function:
+### Getting and releasing connections
+
+The static `fromConfiguration()` method of the `Connection` class takes a configuration and a callback argument:
 
 ```
-function selectEmailAddress(connection, emailAddress, callback) {
-  const filePath = `${SQL_DIRECTORY_PATH}/${SELECT_EMAIL_ADDRESS_FILE_NAME}`,
-        sql = sqlFromFilePath(filePath);
+Connection.fromConfiguration(configuration, (error, connection) => {
 
-  query(connection, sql, emailAddress, (error, rows) => {
-    if (error) {
-      log.error("selectEmailAddress() failed.");
-    }
+  ...
 
-    callback(error, rows);
-  });
-}
+  connection.release();
+};
+```
 
-function updateNameIdentifier(connection, name, identifier, callback) {
-  const filePath = `${SQL_DIRECTORY_PATH}/${UPDATE_NAME_IDENTIFIER_FILE_NAME}`,
-        sql = sqlFromFilePath(filePath);
+If successful, the `error` argument of the callback will be null and a `connection` object will be returned, otherwise the `error` argument will be truthy. Details of the format of the `configuration` object can be found in the configuration subsections of the specific package readme files.
 
-  execute(connection, sql, name, identifier, (error) => {
-    if (error) {
-      log.error("updateNameIdentifier() failed.");
-    }
+### Logging
 
-    callback(error);
-  });
-}
+Ideally you should add a `log` property to the `configuration` object that references an object of the following form:
+
+```
+const log = {
+  trace: () => { ... },
+  debug: () => { ... },
+  info: () => { ... },
+  warning: () => { ... },
+  error: () => { ... },
+  fatal: () => { ... },
+});
 ```
-Note that the parameters, as well as matching the function names precisely, are passed directly to the `query()` or `execute()` functions. Essentially the only purpose of these functions is to retrieve the SQL, pass it to the requisite murmuration function and log an error if it occurs.
+Currently only the `error()`, `info()` and `debug()` functions are made use of, but in future others may be utilised.
+
+If you do not provide a `log` object, all logging is suppressed.
 
-Lastly, it is recommended that you avoid complex queries that span more than one table and always employ views instead. For information on views, see the MariaDB documentation [here](https://mariadb.com/kb/en/views/).
+### Error handling
+
+In the event of an error, if a `log` property has been added to the `configuration` object then the `log.error()` function will be called with a message containing a reasonable stab at the cause of the error. Details can be found in the subsections of the same name in the specific package readme files.
+
+These messages are meant to help with debugging simple mistakes such as providing incorrect configuration. If you do not find them helpful, do not provide a `log` object and be assured that the errors are always returned by way of callback function arguments for you to deal with as you see fit.
 
 ### Using transactions
 
@@ -213,7 +283,7 @@ This approach leads to less SQL and more JavaScript, however, as already mention
 
 The migration functionality will definitely not suit every use case, however it can provide surety for small applications running on multiple Node instances connecting to a single MariaDB instance. It is essential that the prescriptions below are followed pretty much to the letter. Failing to do so will doubtless result in failure.
 
-The `migrate()` function takes the usual `configuration` argument followed by `migrationsDirectoryPath` argument and a `callback` argument.  The callback is invoked with the usual `error` argument, which is truthy if the migrations have succeeded and falsey otherwise.
+The `migrate()` function takes the usual `configuration` argument followed by `migrationsDirectoryPath` argument and a `callback` argument.  The callback is called with the usual `error` argument, which is truthy if the migrations have succeeded and falsey otherwise.
 
 ```
 const configuration = ... ,

package/bin/statement.js

@@ -76,6 +76,10 @@ class Statement {
     this.query = query;
   }
 
+  setParameters(parameters) {
+    this.parameters = parameters;
+  }
+
   one(oneHandler) {
     this.oneHandler = oneHandler;
 
@@ -118,8 +122,21 @@ class Statement {
     return this;
   }
 
-  set(object) {
-    const assignments = this.assignmentsFromObject(object); ///
+  set(objectOrArray, ...parameters) {
+    let assignments;
+
+    const objectOrArrayIsArray = Array.isArray(objectOrArray);
+
+    if (objectOrArrayIsArray) {
+      const array = objectOrArray,  ///
+            strings = array;  ///
+
+      assignments = this.assignmentsFromStringsAndParameters(strings, parameters);
+    } else {
+      const object = objectOrArray;  ///
+
+      assignments = this.assignmentsFromObject(object); ///
+    }
 
     this.sql = ` ${this.sql} SET ${assignments}`;
 
@@ -132,7 +149,7 @@ class Statement {
     const objectOrArrayIsArray = Array.isArray(objectOrArray);
 
     if (objectOrArrayIsArray) {
-      const array = objectOrArray,
+      const array = objectOrArray,  ///
             strings = array;  ///
 
       clause = this.clauseFromStringsAndParameters(strings, parameters);
@@ -150,20 +167,21 @@ class Statement {
   values(objectOrArray, ...parameters) {
     const objectOrArrayIsArray = Array.isArray(objectOrArray);
 
+    let columnsAndValues;
+
     if (objectOrArrayIsArray) {
-      const array = objectOrArray,
-          strings = array,  ///
-          columnsAndValues = this.columnsAndValuesFromStringsAndParameters(strings, parameters);
+      const array = objectOrArray,  ///
+            strings = array;  ///
 
-      this.sql = `${this.sql} ${columnsAndValues}`;
+      columnsAndValues = this.columnsAndValuesFromStringsAndParameters(strings, parameters);
     } else {
-      const object = objectOrArray,  ///
-          values = this.valuesFromObject(object),
-          columns = this.columnsFromObject(object)
+      const object = objectOrArray;  ///
 
-      this.sql = `${this.sql} (${columns}) VALUES (${values})`;
+      columnsAndValues = this.columnsAndValuesFromObject(object);
     }
 
+    this.sql = `${this.sql} ${columnsAndValues}`;
+
     return this;
   }
 
@@ -182,18 +200,19 @@ class Statement {
     return object;
   }
 
-  valuesFromObject(object) {
-    const columns = this.columnsFromObject(object),
+  clauseFromObject(object) {
+    const keys = Object.keys(object),
+          columns = keys.map((key) => this.columnFromKey(key)),
           parameters = Object.values(object), ///
           firstIndex = 0,
-          values = columns.reduce((values, column, index) => {
+          clause = columns.reduce((clause, column, index) => {
             const placeholder = this.placeholder();
 
-            values = (index === firstIndex) ?
-                      `${placeholder}` :
-                        ` ${values}, ${placeholder}`;
+            clause = (index === firstIndex) ?
+                `${column}=${placeholder}` :
+                ` ${clause} AND ${column}=${placeholder}`;
 
-            return values;
+            return clause;
           }, EMPTY_STRING);
 
     this.parameters = [
@@ -201,21 +220,22 @@ class Statement {
       ...parameters
     ];
 
-    return values;
+    return clause;
   }
 
-  clauseFromObject(object) {
-    const columns = this.columnsFromObject(object),
+  assignmentsFromObject(object) {
+    const keys = Object.keys(object),
+          columns = keys.map((key) => this.columnFromKey(key)),
           parameters = Object.values(object), ///
           firstIndex = 0,
-          clause = columns.reduce((clause, column, index) => {
+          assignments = columns.reduce((assignments, column, index) => {
             const placeholder = this.placeholder();
 
-            clause = (index === firstIndex) ?
-                       `${column}=${placeholder}` :
-                         ` ${clause} AND ${column}=${placeholder}`;
+            assignments = (index === firstIndex) ?
+                `${column}=${placeholder}` :
+                ` ${assignments}, ${column}=${placeholder}`;
 
-            return clause;
+            return assignments;
           }, EMPTY_STRING);
 
     this.parameters = [
@@ -223,36 +243,31 @@ class Statement {
       ...parameters
     ];
 
-    return clause;
+    return assignments;
   }
 
-  columnsFromObject(object) {
+  columnsAndValuesFromObject(object) {
     const keys = Object.keys(object),
-          columns = keys.map((key) => this.columnFromKey(key));
-
-    return columns;
-  }
-
-  assignmentsFromObject(object) {
-    const columns = this.columnsFromObject(object),
+          columns = keys.map((key) => this.columnFromKey(key)),
           parameters = Object.values(object), ///
           firstIndex = 0,
-          assignments = columns.reduce((assignments, column, index) => {
+          values = columns.reduce((values, column, index) => {
             const placeholder = this.placeholder();
 
-            assignments = (index === firstIndex) ?
-                           `${column}=${placeholder}` :
-                             ` ${assignments}, ${column}=${placeholder}`;
+            values = (index === firstIndex) ?
+                        `${placeholder}` :
+                        ` ${values}, ${placeholder}`;
 
-            return assignments;
-          }, EMPTY_STRING);
+            return values;
+          }, EMPTY_STRING),
+          columnsAndValues = `(${columns}) VALUES (${values})`;
 
     this.parameters = [
       ...this.parameters,
       ...parameters
     ];
 
-    return assignments;
+    return columnsAndValues;
   }
 
   clauseFromStringsAndParameters(strings, parameters) {
@@ -272,12 +287,35 @@ class Statement {
 
     this.parameters = [
       ...this.parameters,
-        ...parameters
+      ...parameters
     ];
 
     return clause;
   }
 
+  assignmentsFromStringsAndParameters(strings, parameters) {
+    const stringsLength = strings.length,
+          lastIndex = stringsLength - 1,
+          assignments = strings.reduce((assignments, string, index) => {
+            if (index < lastIndex) {
+              const placeholder = this.placeholder();
+
+              assignments = `${assignments}${string}${placeholder}`
+            } else {
+              assignments = `${assignments}${string}`;
+            }
+
+            return assignments;
+          }, EMPTY_STRING);
+
+    this.parameters = [
+      ...this.parameters,
+      ...parameters
+    ];
+
+    return assignments;
+  }
+
   columnsAndValuesFromStringsAndParameters(strings, parameters) {
     const stringsLength = strings.length,
           lastIndex = stringsLength - 1,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "murmuration",
   "author": "James Smith",
-  "version": "1.1.7",
+  "version": "1.1.13",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/murmuration",
-  "description": "Database connections, transactions and migrations.",
+  "description": "Database statements, transactions and migrations.",
   "repository": {
     "type": "git",
     "url": "https://github.com/djalbat/murmuration"