murmuration 2.0.1 → 2.0.4

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,13 +31,16 @@ 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 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:
+
+* 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:
 
@@ -69,14 +72,12 @@ function checkAccountOperation(connection, abort, proceed, complete, context) {
 
 There are several points worth noting:
 
-* 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.
 
-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");
@@ -101,7 +102,7 @@ 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 this example a row is inserted into a table for software packages:
@@ -149,30 +150,108 @@ Note:
 
 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
 
-* One of the `selectFrom()`, `insertInto()`, `deleteFrom()` or `delete()` methods must be called. Each takes a string for the name of a table or view. 
+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.
 
-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 the example below, three operations have been provided and the context has some example properties that they will make use of:
 
-* 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.
+```
+const configuration = ... ,
+      operations = [
+        checkUsernameOperation,
+        checkEmailAddressOperation,
+        addEmailOperation
+      ],
+      context = {
+        emailAddress,
+        username,
+        password
+      };
 
-* 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.
+transaction(configuration, operations, (completed) => {
 
-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.
+  ..
+
+}, context);
+```
+
+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. 
+
+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.
+
+* 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. 
+
+* 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();
+  });
+}
+```
 
-### Extending the Statement class
+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:
 
@@ -182,28 +261,20 @@ This is recommended for no other reason than to avoid repetitively passing table
 const { Statement: BaseStatement } = require("./murmuration-...");
 
 const USER_TABLE = "user",
-      RELEASE_TABLE = "release",
-      DISTRIBUTION_TABLE = "attribution",
-      LATEST_RELEASE_VIEW = "latest_release";
+      RELEASE_TABLE = "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); }
 }
@@ -231,7 +302,7 @@ module.exports = using;
 
 ...or require and instantiate it directly. The `using()` function is purely for convenience.
 
-### Getting and releasing connections
+### Connections
 
 The static `fromConfiguration()` method of the `Connection` class takes a configuration and a callback argument:
 
@@ -270,45 +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, three operations has been provided and the context has properties that they will make use of:
-
-```
-const configuration = ... ,
-      operations = [
-        checkUsernameOperation,
-        checkEmailAddressOperation,
-        addEmailOperation
-      ],
-      context = {
-        emailAddress,
-        username,
-        password
-      };
-
-transaction(configuration, operations, (completed) => {
-
-  ..
+### Statement class specification
 
-}, context);
-```
+The following specification gives a complete and more detailed list of the methods available.
 
-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. 
+* One of the `selectFrom()`, `insertInto()`, `deleteFrom()` or `delete()` methods must be called. Each takes a string for the name of a table or view.
 
-* 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.
+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.
 
-* 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.
+* 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.
 
-* 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 `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.
 
-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.
+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/license.txt

@@ -1,6 +1,6 @@
 MIT And Anti-996 Licenses
 
-Copyright (c) 2019 James Smith
+Copyright (c) 2023 James Smith
 
 These licenses shall be included in all copies or substantial portions of
 this software and associated documentation files (the "Software").

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "murmuration",
   "author": "James Smith",
-  "version": "2.0.1",
+  "version": "2.0.4",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/murmuration",
   "description": "Database statements, transactions and migrations.",
@@ -10,7 +10,7 @@
     "url": "https://github.com/djalbat/murmuration"
   },
   "dependencies": {
-    "necessary": "^11.1.3"
+    "necessary": "^11.7.6"
   },
   "devDependencies": {},
   "scripts": {}