combining joi validation schemas and koa middlewares

Author: sombriks

03-address-book-joi/.env

@@ -0,0 +1,5 @@
+# default env values. can be complemented by .env.development or .env.test
+# override values using .env.local, .env.development.local or .env.test.local
+PORT=3000
+ORIGINS=*
+PG_DATA=./pgdata

03-address-book-joi/.env.test

@@ -0,0 +1,3 @@
+# extra configs complementing default .env when running in test mode
+PORT=3001
+PG_DATA=memory://pgdata-testing

03-address-book-joi/README.md

@@ -35,7 +35,7 @@ npm i @electric-sql/pglite cross-env dotenv-flow signale joi
 npm i -D nodemon xo c8 ava supertest
 mkdir -p app/{configs/migrations,controllers,services}
 touch .env .env.development .env.test index.js app/{app.spec.js,server.js} 
-touch app/configs/{cross-origin.js,database.js,security.js,logging.js} 
+touch app/configs/{cross-origin.js,database.js,security.js,logging.js,validation.js} 
 touch app/configs/{hook-test-context.js,no-rollback.js}
 touch app/configs/migrations/{2024-07-13-start-schema.sql,3000-test-data.sql}
 touch app/controllers/{controllers.spec.js,addresses.js,people.js}

03-address-book-joi/app/app.spec.js

@@ -0,0 +1,14 @@
+import test from 'ava';
+import request from 'supertest';
+import {testSetup, testTeardown} from './configs/hook-test-context.js';
+
+test.before(testSetup);
+
+test.after.always(testTeardown);
+
+test('it should be ONLINE', async t => {
+	const result = await request(t.context.app.callback()).get('/health/status');
+	t.truthy(result);
+	t.is(result.status, 200);
+	t.is(result.text, 'ONLINE');
+});

03-address-book-joi/app/configs/database.js

@@ -0,0 +1,34 @@
+// Database.js
+import {PGlite} from '@electric-sql/pglite';
+import {noRollback} from './no-rollback.js';
+
+/**
+ * @type {PGlite} database - ref to connection singleton
+ */
+let connection;
+
+/**
+ * Provision a database connection with {PGLite}
+ *
+ * @param {*} config config options to prepare the database connection
+ * @param {String} config.dataDir path or dsn to database
+ *
+ * @returns {Promise<PGlite>} valid database connection instance
+ */
+export const prepareDatabase = async config => {
+	// Config fallback
+	config ||= {dataDir: process.env.PG_DATA};
+	// https://github.com/sombriks/pglite/tree/main?tab=readme-ov-file#limitations
+	if (!connection || connection.closed) {
+		connection = new PGlite(config.dataDir, {debug: 0});
+		const {rows: [{result}]} = await connection.query('select 1 + 1 as result');
+		if (result !== 2) {
+			throw new Error('database issue');
+		}
+
+		const migrate = await noRollback(connection);
+		console.log(migrate);
+	}
+
+	return connection;
+};

03-address-book-joi/app/configs/hook-test-context.js

@@ -0,0 +1,30 @@
+import {prepareAddressesServices} from '../services/addresses.js';
+import {prepareAddressesRequests} from '../controllers/addresses.js';
+import {preparePeopleServices} from '../services/people.js';
+import {preparePhonesServices} from '../services/phones.js';
+import {preparePeopleRequests} from '../controllers/people.js';
+import {prepareServer} from '../server.js';
+import {prepareDatabase} from './database.js';
+
+export const testSetup = async t => {
+	const database = await prepareDatabase();
+
+	const addressesServices = await prepareAddressesServices({db: database});
+	const addressesRequests = await prepareAddressesRequests({addressesServices});
+
+	const peopleServices = await preparePeopleServices({db: database});
+	const phonesServices = await preparePhonesServices({db: database});
+	const peopleRequests = await preparePeopleRequests({peopleServices, phonesServices});
+
+	const app = await prepareServer({addressesRequests, peopleRequests});
+
+	t.context.addressesService = addressesServices;
+	t.context.peopleServices = peopleServices;
+	t.context.phonesServices = phonesServices;
+	t.context.database = database;
+	t.context.app = app;
+};
+
+export const testTeardown = async t => {
+	await t.context.database.close();
+};

03-address-book-joi/app/configs/logging.js

@@ -0,0 +1,14 @@
+import Signale from 'signale/signale.js';
+
+/**
+ * Logger to better track info
+ */
+export const logger = new Signale({
+	config: {
+		displayTimestamp: true,
+		displayLabel: false,
+		displayBadge: true,
+		displayScope: true,
+		displayDate: true,
+	},
+});

03-address-book-joi/app/configs/migrations/2024-07-13-start-schema.sql

@@ -0,0 +1,36 @@
+--
+-- base tables
+--
+-- addresses in the book
+create table addresses(
+  id serial primary key,
+  "description" text not null,
+  "complement" text not null,
+  created timestamp not null default now(),
+  updated timestamp not null default now()
+);
+-- people, a person with zero or more addresses
+create table people(
+  id serial primary key,
+  "name" text not null,
+  created timestamp not null default now(),
+  updated timestamp not null default now()
+);
+-- N:N cardinality
+create table addresses_people(
+  addresses_id integer not null,
+  people_id integer not null,
+  foreign key (addresses_id) references addresses(id) on delete cascade,
+  foreign key (people_id) references people(id) on delete cascade,
+  primary key (addresses_id, people_id)
+);
+-- people might have more than one phone number, but any number belongs to someone
+create table phones(
+  id serial primary key,
+  people_id integer not null,
+  "number" text unique not null,
+  -- no number belongs to two distinct people
+  created timestamp not null default now(),
+  updated timestamp not null default now(),
+  foreign key (people_id) references people(id) on delete cascade
+);

03-address-book-joi/app/configs/migrations/3000-test-data.sql

@@ -0,0 +1,25 @@
+--
+-- test data so we have a known state in database to run tests
+--
+insert into addresses("description", complement)
+values ('Road 01 residence', 'Flower block'),
+  ('Dead end street', ''),
+  ('Horses alley, no number ', 'Burrow #2'),
+  ('Tomato avenue 110', ''),
+  ('Old boulevard 45', 'uphill cabin');
+insert into people("name")
+values ('Alice'),
+  ('Bob'),
+  ('Caesar'),
+  ('David'),
+  ('Edward');
+insert into addresses_people (addresses_id, people_id)
+values (1, 1),
+  (1, 2),
+  (2, 3),
+  (3, 4),
+  (4, 5);
+insert into phones(people_id, "number")
+values (1, '1234'),
+  (2, '5678'),
+  (5, '9101112');

03-address-book-joi/app/configs/no-rollback.js

@@ -0,0 +1,76 @@
+import {readFileSync} from 'node:fs';
+import {logger} from './logging.js';
+
+const log = logger.scope('no-rollback.js');
+
+/**
+ * Apply database migrations
+ *
+ * @param {import('@electric-sql/pglite')} database database connection instance
+ */
+export const noRollback = async database => {
+	log.info('check database desired state/migrations...');
+	const metadata = `
+	  -- store script names already executed
+    create table if not exists no_rollback_from_here(
+      created timestamp default now(),
+      path text unique not null,
+      primary key (created, path)
+    );
+		-- lock while applying migrates to avoid possible concurrent executions
+		create table if not exists lock_no_rollback(
+			locked integer not null default 1 check (locked = 1),
+			created timestamp default now(),
+			primary key (locked)
+		);
+  `;
+	await database.exec(metadata);
+
+	// Lock table to avoid concurrent migrations
+	try {
+		await database.exec('insert into lock_no_rollback default values');
+	} catch (error) {
+		log.error(`
+		=====
+		failed to lock for migration.
+		either something went wrong or there is a migration happening.
+		bailing out. 
+		=====
+		`);
+		throw error;
+	}
+
+	// Add new migrate files here, in this array.
+	const files = ['app/configs/migrations/2024-07-13-start-schema.sql'];
+	// Desired state for test suite
+	if (process.env.NODE_ENV === 'test') {
+		files.push('app/configs/migrations/3000-test-data.sql');
+	}
+
+	const result = {executed: [], status: 'success', total: files.length};
+	for await (const file of files) {
+		await database.transaction(async tx => {
+			const migrate = readFileSync(file, 'utf8');
+
+			const skip = await tx.query(`
+        select created, path 
+        from no_rollback_from_here
+        where path = $1  
+      `, [file]);
+			if (skip.rows.length > 0) {
+				const {created, path} = skip.rows[0];
+				log.debug(`already executed: [${created.toISOString()}] [${path}]`);
+			} else {
+				log.debug(`prepare to execute [${file}]`);
+				await tx.exec(migrate);
+				log.debug('done!');
+				await tx.query('insert into no_rollback_from_here (path) values ($1)', [file]);
+				result.executed.push(file);
+			}
+		});
+	}
+
+	await database.exec('delete from lock_no_rollback');
+	log.info('done with database migration!');
+	return result;
+};

03-address-book-joi/app/configs/validation.js

@@ -0,0 +1,27 @@
+import Joi from 'joi';
+import { logger } from "./logging.js";
+
+const log = logger.scope('validation.js')
+
+const addressSchema = Joi.object({
+  id: Joi.number(),
+  description: Joi.string(),
+  complement: Joi.string(),
+  created: Joi.date()
+})
+
+/**
+ * middleware to validate address payload with joi schema
+ * 
+ * @param {*} context 
+ * @param {*} next 
+ */
+export const ifValidAddress = async (context, next) => {
+  log.info('validating address...')
+  const { error } = addressSchema.validate(context.request.body)
+  if (error) {
+    log.warn(error);
+    return context.throw(400, error);
+  }
+  return await next()
+}

03-address-book-joi/app/controllers/addresses.js

@@ -0,0 +1,86 @@
+import { prepareAddressesServices } from '../services/addresses.js';
+import { logger } from '../configs/logging.js';
+
+// Define a scope so you can better track from where the log message came from
+const log = logger.scope('controllers', 'addresses.js');
+
+export const prepareAddressesRequests = async options => {
+	options ||= { addressesServices: await prepareAddressesServices() };
+	const { addressesServices } = options;
+	return {
+		async list(context) {
+			log.info('list addresses');
+			const { q = '' } = context.request.query;
+			context.body = await addressesServices.list({ q });
+		},
+		async find(context) {
+			log.info('find address');
+			const result = await addressesServices.find(context.request.params);
+			if (result) {
+				context.body = result;
+			} else {
+				log.warn('No address found');
+				context.throw(404, 'Not Found');
+			}
+		},
+		async create(context) {
+			log.info('create address');
+			const { description, complement } = context.request.body;
+			const id = await addressesServices.create({ address: { description, complement } });
+			context.status = 201;
+			context.set('Location', `/addresses/${id}`); // Politely guide clients to somewhere else
+			context.body = { message: `#${id} created` };
+		},
+		async update(context) {
+			log.info('update address');
+			const { id } = context.params;
+			const { body: address } = context.request;
+			const affected = await addressesServices.update({ id, address });
+			if (!affected) {
+				log.warn('No address updated');
+			}
+			context.status = 303; // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/303
+			context.set('Location', `/addresses/${id}`);
+			context.body = { message: `${affected} updated` };
+		},
+		async del(context) {
+			log.info('delete address');
+			const affected = await addressesServices.del(context.request.params);
+			if (!affected) {
+				log.warn('No address removed');
+			}
+			context.status = 303;
+			context.set('Location', '/addresses');
+			context.body = { message: `${affected} deleted` };
+		},
+		people: {
+			async list(context) {
+				log.info('list people from address');
+				const { id: addresses_id } = context.params;
+				context.body = await addressesServices.people.list({ addresses_id });
+			},
+			async add(context) {
+				log.info('add people into address');
+				const { id: addresses_id, people_id } = context.params;
+				const affected = await addressesServices.people.add({ addresses_id, people_id });
+				if (!affected) {
+					log.warn('No people added into address #' + addresses_id);
+				}
+				context.status = 303;
+				context.set('Location', `/addresses/${addresses_id}/people`);
+				context.body = { message: `${affected} added` };
+			},
+			async del(context) {
+				log.info('remove people from address');
+				const { id: addresses_id, people_id } = context.params;
+				const affected = await addressesServices.people.del({ addresses_id, people_id });
+				if (!affected) {
+					log.warn('No people removed from address #' + addresses_id);
+				}
+				context.status = 303;
+				context.set('Location', `/addresses/${addresses_id}/people`);
+				context.body = { message: `${affected} removed` };
+			},
+		},
+	};
+};