murmuration 1.1.13 → 2.0.1

package/README.md

@@ -37,9 +37,9 @@ Statements are covered first up, but ideally they should be executed in the cont
 
 ### 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. 
 
-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:
+In the first example a row is selected should its email address and password match the given values:
 
 ```
 const using = require("../using");
@@ -69,21 +69,14 @@ 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.
+* A local `using()` function has been employed rather the function supplied by the package, because the `Statement` class it utilities has been extended for convenience. For example, `selectFromAccount()` is defined in the application's own `Statement` class.
+* Each operation provides a connection and a context as well as three callbacks. These 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.
 * 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");
@@ -111,7 +104,7 @@ The following points are worth noting:
 * The `where()` method takes a template literal this time.
 * 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,7 +147,7 @@ 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
 
@@ -162,22 +155,81 @@ The following specification gives a complete and more detailed list of the metho
 
 * 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.
-
-If the `selectFrom()` method is called, then one of the following of the following methods must be called. Each takes 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.
+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.
 
-In all but the last case, you must also call the `else()` method with a callback.
+* 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 `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.
+* 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.
 
-If  
+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.
+
+### 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:
+
+```
+"use strict";
+
+const { Statement: BaseStatement } = require("./murmuration-...");
+
+const USER_TABLE = "user",
+      RELEASE_TABLE = "release",
+      DISTRIBUTION_TABLE = "attribution",
+      LATEST_RELEASE_VIEW = "latest_release";
+
+class Statement extends BaseStatement {
+  updateUser() { return this.update(USER_TABLE); }
+  updateRelease() { return this.update(RELEASE_TABLE); }
+  updateDistribution() { return this.update(DISTRIBUTION_TABLE); }
+
+  insertIntoUser() { return this.insertInto(USER_TABLE); }
+  insertIntoRelease() { return this.insertInto(RELEASE_TABLE); }
+  insertIntoDistribution() { return this.insertInto(DISTRIBUTION_TABLE); }
+
+  deleteFromUser() { return this.deleteFrom(USER_TABLE); }
+  deleteFromRelease() { return this.deleteFrom(RELEASE_TABLE); }
+  deleteFromDistribution() { return this.deleteFrom(DISTRIBUTION_TABLE); }
+
+  selectFromUser() { return this.selectFrom(USER_TABLE); }
+  selectFromRelease() { return this.selectFrom(RELEASE_TABLE); }
+  selectFromDistribution() { return this.selectFrom(DISTRIBUTION_TABLE); }
+
+  selectFromLatestRelease() { return this.selectFrom(LATEST_RELEASE_VIEW); }
+
+  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;
+```
+
+...or require and instantiate it directly. The `using()` function is purely for convenience.
 
 ### Getting and releasing connections
 
@@ -222,15 +274,14 @@ These messages are meant to help with debugging simple mistakes such as providin
 
 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:
+In the example below, three operations has been provided and the context has properties that they will make use of:
 
 ```
 const configuration = ... ,
       operations = [
-        checkUsernameAvailable,
-        checkEmailAddressAvailable,
-        addEmailAddressUsernamePasswordAndStatus,
-        retrieveUserIdentifier,
+        checkUsernameOperation,
+        checkEmailAddressOperation,
+        addEmailOperation
       ],
       context = {
         emailAddress,
@@ -244,32 +295,10 @@ 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.
 
-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 signatures of the operations are given in the usage section. The bodies of the operations are immaterial, again see the usage section for idees. What follows are general prescriptions for how to make use of transactions. 
 
-* 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.
+* 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.
 
 * 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.
 
@@ -277,8 +306,6 @@ It is entirely possible to conflate the first three of these operations into a s
 
 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.
 
-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.
-
 ### Making use of 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.

package/package.json

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