murmuration 1.1.13 → 2.0.3

package/README.md

@@ -11,7 +11,7 @@ This readme file pertains to both, although there are specific instructions for
 
 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. 
 
-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.
+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 can be migrated if needed each time the former is deployed.
 
 ## Installation
 
@@ -31,15 +31,18 @@ Remember that it is the aforementioned specific packages that you should install
 
 ## Usage
 
-Aside from small differences in configuration and error handling the Functionality across the aforementioned specific packages is identical, and is therefore covered here.
-
-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.
+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 inside operations, which are themselves covered in the later subsection. If you do not want to use operations then you can in fact easily wrap statements in promises, again see the relevant subsection later on.
 
 ### Generating statements
 
-Statements are generated dynamically, in a similar vein to an ORM, in this case with a simple, promise-like syntax. 
+Statements are generated dynamically with a simple, promise-like syntax. Again it is worth noting that they can be executed inside either operations or promises. In the examples below operations are used. Wrapping statement in promises is covered later on.
+
+Note that the following points apply to all of the examples:
 
-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:
+* A local `using()` function has been employed rather the function supplied by the package, because the `Statement` class it utilities has been extended. See the relevant subsection below for more details.
+* Each operation provides a connection and a context as well as the `abort`, `proceed` and `compoete` callbacks. These allow the result of the statement's execution to determine whether the application should abort, proceed to the next operation or complete, respectively. Again see the relevant section on operations later on.
+
+In the first example a row is selected should its email address and password match the given values:
 
 ```
 const using = require("../using");
@@ -69,21 +72,12 @@ function checkAccountOperation(connection, abort, proceed, complete, context) {
 
 There are several points worth noting:
 
-* 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.
-
-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.
+In the following example rows in a table holding temporary reset codes are deleted once they expire:
 
 ```
 const using = require("../using");
@@ -108,10 +102,10 @@ function deleteExpiredResetCodesOperation(connection, abort, proceed, complete,
 
 The following points are worth noting:
 
-* The `where()` method takes a template literal this time.
+* The `where()` method takes a template literal this time, see below for further details.
 * The `success()` method takes a callback that is called should hte execution succeed.
 
-In the following example, a row is inserted into a table for software packages:
+In this example a row is inserted into a table for software packages:
 
 ```
 const using = require("../using");
@@ -154,32 +148,161 @@ 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.
+In general, the assumption with passing plain old JavaScript objects is that clauses and so forth can easily be constructed from them. The `set()`, `where()` and `values()` methods can also take appended template literals, however, so that you can define parts of the SQL with more freedom. More detail is given towards the end of the next subsection.
 
-### Statement class specification
+All of the methods that can be called against the instances of statements returned from the `using()` function are described in the statement specification subsection further below. 
 
-The following specification gives a complete and more detailed list of the methods available.
+### Operations and transactions
+
+Ideally, all statements should be executed in the context of a transaction. Murmuration provides a `transaction()` function that allows you to do this. It takes `configuration`, `operations`, `callback` and `context` arguments. The callback provided will have a `completed` argument while the context is mandatory and must be a plain old JavaScript object. The `transaction()` function makes use of the `context` object itself, in fact, with the object's `connection`, `operations` and `completed` properties being reserved.
+
+In the example below, three operations have been provided and the context has some example properties that they will make use of:
+
+```
+const configuration = ... ,
+      operations = [
+        checkUsernameOperation,
+        checkEmailAddressOperation,
+        addEmailOperation
+      ],
+      context = {
+        emailAddress,
+        username,
+        password
+      };
+
+transaction(configuration, operations, (completed) => {
 
-* One of the `selectFrom()`, `insertInto()`, `deleteFrom()` or `delete()` methods must be called. Each takes a string for the name of a table or view. 
+  ..
 
-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.
+}, context);
+```
 
-If the `selectFrom()` method is called, then one of the following of the following methods must be called. Each takes a callback:
+The signatures of the operations have already been demonstrated in the examples above. In fact the bodies of the operations are immaterial, they do not have to execute statements and can contain any application logic. However, if you do want to execute statement inside an operation then again see the examples for guidance on how to integration the statement methods with the operation callbacks. 
 
-* 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.
+What follows are general prescriptions for how to make use of transactions. They are meant to persuade that the small amount of boilerplate necessary to execute any statement inside a transaction is always worth the effort.
 
-In all but the last case, you must also call the `else()` method with a callback.
+* You can try to insert values into a table and test whether they are unique by whether or not the insert fails. However, the database will throw an error that is indistinguishable from errors that occur because of, say, syntax errors in the SQL. It could be argued that it is bad practice to knowingly run a query that may result in an error and use the presence of such as an indication of whether or not an otherwise correct query has been successful. Therefore a better approach is to precede the insert with a select statement and execute both in the context of a transaction. 
 
-* 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.
+* Often conflating operations means that application logic that is far more suited to, in this case, JavaScript must be added to the SQL itself. Or worse, the application logic is simply assumed to be implicit in the SQL. It is far better to implement this kind of logic explicitly in JavaScript than complicate SQL statements with it. In short, executing multiple SQL statements threaded together with SQL variables and the like is always best avoided.
+
+* As well as conditional branching, for example, often functionality needs to be implemented in the context of a transaction that cannot simply be added to an SQL statement. Unzipping a stored binary, for example, or checking some program variable dependent upon a prior query. Furthermore, a shared context means that even though several parts of the application logic might be related, they can still effectively communication with one another of the course of the transaction.
+
+The example above demonstrates the crux of the approach taken here, therefore. The application logic is to be found in easily readable, atomic form within the body of each operation. On the other hand the SQL statements are considered to be dumb in the sense that they do nothing but slavishly place or retrieve information into or from the database.
+
+### Supporting promises and the `async`/`await` syntax
+
+Murmuration's promise-like syntax for generating and executing statements is easily and elegantly adaptable to promises. Consider the following asynchronous function to return a user from a database:
+
+```
+async function getUser(connection, identifier) {
+  return new Promise((resolve, reject) => {
+    using(connection)
+      .selectFromUsers()
+      .where({ identifier })
+      .else(() => {
+        const user = null;
+
+        resolve(user);
+      })
+      .one(({ jsonString }) => {
+        const user = User.fromJSONString(jsonString);
+
+        resolve(user);
+      })
+      .catch(reject)
+      .execute();
+  });
+}
+```
+
+Now, rather then the `one()`, `else()` and `catch()` methods calling the callbacks passed by way of an enclosing operation, they call the `resolve` and `reject` callbacks of the promise. The function can be thus be utilised as follows:
+
+```
+try {
+  const user = await getUser(connection, identifier); ;
+  
+  /// Make use of the user 
+} catch (error) {
+  /// Handle any error
+}
+```
+
+Note that both the `one()` and `else()` methods call the `resolve` callback whereas the `catch()` method calls the `reject` callback, essentially passing the `error` argument on to body of the outermost `catch` block.
+
+The following example is even more succinct:
+
+```
+async function destroyUser(connection, identifier) {
+  return new Promise((resolve, reject) => {
+    using(connection)
+      .deleteFromUsers()
+      .where({ identifier })
+      .success(resolve)
+      .catch(reject)
+      .execute();
+  });
+}
+```
+
+If you want to interrupt the program flow for debugging purposes then replace the direct references to the `resolve` and `reject` callbacks with arrow functions that call them, as in the `one()` and `else()` methods in the first example.
+
+Of course both of these functions can be utilised using promises directly, that is calling the `then()` and `catch()` methods of the returned promises directly.
+
+Finally, note that it is easy to encapsulate the instantiation of promises into a function called `promisify()` or such like, but nothing is provided by this package.  
+
+### Extending the `Statement` class
+
+This is recommended for no other reason than to avoid repetitively passing table or view names to `selectFrom()` methods and the like. A simple exapmle will amply demonstrate:
 
-If  
+```
+"use strict";
+
+const { Statement: BaseStatement } = require("./murmuration-...");
+
+const USER_TABLE = "user",
+      RELEASE_TABLE = "release";
+
+class Statement extends BaseStatement {
+  updateUser() { return this.update(USER_TABLE); }
+  updateRelease() { return this.update(RELEASE_TABLE); }
+
+  insertIntoUser() { return this.insertInto(USER_TABLE); }
+  insertIntoRelease() { return this.insertInto(RELEASE_TABLE); }
+
+  deleteFromUser() { return this.deleteFrom(USER_TABLE); }
+  deleteFromRelease() { return this.deleteFrom(RELEASE_TABLE); }
+
+  selectFromUser() { return this.selectFrom(USER_TABLE); }
+  selectFromRelease() { return this.selectFrom(RELEASE_TABLE); }
+
+  static fromConnection(connection) { return BaseStatement.fromConnection(Statement, connection); }
+}
+
+module.exports = Statement;
+```
+
+Here the ellipsis in the `require()` statement should be replaced as needed.
+
+Now make use of this subclass in your own `using()` function...
+
+```
+"use strict";
+
+const Statement = require("./statement");
+
+function using(connection) {
+  const statement = Statement.fromConnection(connection);
+
+  return statement;
+}
+
+module.exports = using;
+```
 
-### Getting and releasing connections
+...or require and instantiate it directly. The `using()` function is purely for convenience.
+
+### Connections
 
 The static `fromConfiguration()` method of the `Connection` class takes a configuration and a callback argument:
 
@@ -218,70 +341,32 @@ In the event of an error, if a `log` property has been added to the `configurati
 
 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
-
-Ideally, all database operations should be run in the context of transactions. There is a single `transaction()` function that allows you to do this. It takes `configuration`, `operations`, `callback` and `context` arguments. The callback provided will have a `completed` argument while the context is mandatory and must be a plain old JavaScript object. The `transaction()` function makes use of the `context` object itself, in fact, with the object's `connection`, `operations` and `completed` properties being reserved.
-
-In the example below, four operations has been provided and the context has properties that they will make use of:
-
-```
-const configuration = ... ,
-      operations = [
-        checkUsernameAvailable,
-        checkEmailAddressAvailable,
-        addEmailAddressUsernamePasswordAndStatus,
-        retrieveUserIdentifier,
-      ],
-      context = {
-        emailAddress,
-        username,
-        password
-      };
-
-transaction(configuration, operations, (completed) => {
-
-  ..
-
-}, context);
-```
-The signature of the operations must be identical to the following example:
-
-```
-function checkUsernameAvailable(connection, abort, proceed, complete, context) {
-  const { username } = context;
-
-  selectUsername(connection, username, (error, rows) => {
-    if (error) {
-      abort();
-
-      return;
-    }
-
-    const rowsLength = rows.length;
-
-    (rowsLength === 0) ?
-      proceed() :
-        complete();
-  });
-}
-```
-Note the provision of the `abort()`, `proceed()` and `complete()` callbacks, each of which is utilised. Their utility should be self evident. One important point to note is that there is an explicit `return` statement after the call to the `abort()` callback. It is easy to forget that invoking a callback does not prevent execution continuing in the current context.
+### Statement class specification
 
-It is entirely possible to conflate the first three of these operations into a single SQL statement and then to combine that with the last SQL statement that recovers an auto-incremented identifier. Both of these statements can then be placed in a single SQL file and run with a call to the `query()` function. There is nothing to be gained from such a approach, however, and there are good reasons not to take it:
+The following specification gives a complete and more detailed list of the methods available.
 
-* You can try to insert values into a table and test whether they are unique by whether or not the insert fails. However, the database will throw an error that is indistinguishable from errors that occur because of, say, syntax errors in the SQL. It could be considered bad practice to knowingly run a query that may result in an error and use the presence of such as an indication of whether or not an otherwise correct query has been successful.
+* One of the `selectFrom()`, `insertInto()`, `deleteFrom()` or `delete()` methods must be called. Each takes a string for the name of a table or view.
 
-* Often conflating operations means that application logic that is far more suited to, in this case, JavaScript must be added to the SQL itself. Or worse, the application logic is simply assumed to be implicit in the SQL. It is far better to implement this kind of logic explicitly in JavaScript than complicate SQL statements with it.
+It is recommended that these methods are not called directly, by the way, 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.
 
-* As well as conditional branching, for example, often functionality needs to be implemented in the context of a transaction that cannot simply be added to an SQL statement. Unzipping a stored binary, for example, or checking some program variable dependent upon a prior query. Furthermore, a shared context means that even though several parts of the application logic might be related, they can still effectively communication with one another of the course of the transaction.
+* The `success()` method must accompany the `insertInto()`, `deleteFrom()` or `delete()` methods.
+* If the `selectFrom()` method is called, then one of the following of the following methods must also be called. Each takes a callback. In all but the last case, you must also call the `else()` method with a 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.
 
-The example above demonstrates the crux of the approach taken here, therefore. The application logic is to be found in easily readable, atomic form within the body of each operation. On the other hand the SQL statements are considered to be dumb in the sense that they do nothing but slavishly place or retrieve information into or from the database.
+* The `catch()` method must always be called with a callback for when an exception occurs.
+* The `set()` method must be called along with the `update()` method.
+* The `where()` method can be called with all but the `insertInto()` method.
+* The `values()` method must be called along with the `insertInto()` method.
+* Either the `getSQL()` or `execute()` methods must be called, usually the latter.
 
-This approach leads to less SQL and more JavaScript, however, as already mentioned but well worth repeating, that JavaScript is easily readable and atomic. The downside is a small amount of boilerplate JavaScript wrapping each operation, but this is a small price to pay.
+Each of the `set()`, `where()` and `values()` methods can take a plain old JavaScript object or an appended template literal. You cannot pass a string as an argument because there is a danger that it might contain an un-escaped value. By forcing you to pass an appended template literal, the method in question is able to pass the array of arguments it receives directly on to the underlying database package, thereby guaranteeing that they will be correctly cast and escaped.
 
-### Making use of migrations
+## Migrations
 
-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 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 database 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 called with the usual `error` argument, which is truthy if the migrations have succeeded and falsey otherwise.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "murmuration",
   "author": "James Smith",
-  "version": "1.1.13",
+  "version": "2.0.3",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/murmuration",
   "description": "Database statements, transactions and migrations.",