Binary UUID Conversion Process

[sfount]

Currently server API helper functions that execute SQL expect a binary UUID (buid) to be passed in as a parameter and this is directly templated into the SQL.

I propose that in general we should minimise the use of the binary format in JavaScript itself, that means that all controllers and methods should assume we dealing with strings (as passed from the client) and the conversion takes place at the last possible point (just before the SQL is executed).

For example:
Invoice Receipt Controller

var Invoices = require('finance/Invoices');
var Patients = require('medical/Patients');
var Enterprises = require('admin/Enterprises');

// Request is sent from the client - I can assume this is a string
var invoiceUuid = req.params.invoiceUuid;

// I can assume any function on the server handling uuids will expect a string
Invoices.details(invoiceUuid)
  //.then...

Invoice Controller

function details(invoiceUuid) { 
var sql = //...

// this is the last point of contact before the SQL query - at this point we can convert to binary 
var buid = db.bid(invoiceUuid);

// db.exec(sql, buid)...
}

Pros:

• Developer never has to question what format a UUID is in - only the very last method requesting information from the database will ever consider binary
• Uniform standard for treating UUIDs
• No manipulation required for working with UUIDs as a string within the JavaScript business logic (never done to my knowledge)

Cons:

• A long chain of requests (transactions for example) may have to be build using more verbose code to ensure the UUID is in the correct state at the correct time

[jniles]

This makes a lot of sense - JavaScript doesn't really need to know the uuids are binary until needing to interact with the database. Happy to see this improvement.

[jniles]

@IMA-WorldHealth/local-contributors

What would you think of a helper conversion function that converts uuids to binary if they exist, based on an array of keys? For example:

let data = req.body;

// do some logic

// convert the 'uuid' and 'debtor_uuid' properties to binary using db.bid()
data = db.convert(data, ['uuid', 'debtor_uuid']);

// now I can db.exec('INSERT...') or db.exec('UPDATE ...') easily.

It might help clean up the code a bit.

[sfount]

This could provide useful functionality.

I would still suggest that this is only done directly before reading or writing to the database - not immediately as the body is received.

The reason for this is passing req.body around with strings allows the controllers to easily access and pass values to other required controllers without considering if it a string or binary.

[jniles]

@sfount, I agree. Our logs with also be more readable the longer we avoid binary data.

I'll look into implementing this in a PR soon.