feat: custom drivers (#11)

* feat(types): define `Driver` class

* feat(util): add `isDriver` validator

* feat: add `driver` option;

note: --driver purposefully overrides `exports.driver` from config file

* chore: add `custom drivers` readme docs

* break: squash `opts.client` into `opts.driver`~!

They were basically the same thing. Now just check if the `driver` string matches a supplied driver name. Customize/override by passing a Driver class or a `path/to/file.js` that contains Driver class.

* chore: update readme docs

* fix(types): remove `opts.client` key

* chore: update `--driver` help text

Author: lukeed

bin.js

@@ -21,6 +21,7 @@ sade('ley')
 	.option('-C, --cwd', 'The current directory to resolve from', '.')
 	.option('-d, --dir', 'The directory of migration files to run', 'migrations')
 	.option('-c, --config', 'Path to `ley` config file', 'ley.config.js')
+	.option('-D, --driver', 'The name of a database client driver')
 	.option('-r, --require', 'Additional module(s) to preload')
 
 	.command('up')

index.js

@@ -9,15 +9,21 @@ async function parse(opts) {
 
 	[].concat(opts.require || []).filter(Boolean).forEach(name => {
 		const tmp = $.exists(name);
-		if (!tmp) throw new Error(`Cannot find module '${name}'`);
-		return require(tmp);
+		if (tmp) return require(tmp);
+		throw new Error(`Cannot find module '${name}'`);
 	});
 
-	const lib = opts.client || $.detect();
-	if (!lib) throw new Error('Unable to locate a SQL driver');
+	// cli(`--driver`) > config(exports.driver) > autodetect
+	let driver = opts.driver || opts.config.driver || $.detect();
+	if (!driver) throw new Error('Unable to locate a database driver');
 
-	const file = join(__dirname, 'lib', 'clients', lib);
-	const driver = require(file); // allow throw here
+	// allow `require` throws
+	if ($.drivers.includes(driver)) {
+		driver = require(join(__dirname, 'lib', 'clients', driver));
+	} else {
+		if (typeof driver === 'string') driver = require(driver);
+		$.isDriver(driver); // throws validation error(s)
+	}
 
 	const migrations = await $.glob(dir);
 

ley.d.ts

@@ -4,7 +4,7 @@ declare namespace Options {
 
 	declare interface Base {
 		cwd?: string;
-		client?: string;
+		driver?: string | Driver;
 		require?: string | string[];
 		config?: Config | Resolver;
 		dir?: string;
@@ -29,6 +29,43 @@ declare class MigrationError extends Error {
 	readonly migration: Record<'name'|'abs', string>;
 }
 
+declare namespace Migration {
+	type Method = 'up' | 'down';
+
+	type Existing = Pick<File, 'name'>;
+
+	interface File {
+		/** The absolute file path */
+		abs: string;
+		/** The relative file path from `opts.dir` */
+		name: string;
+	}
+}
+
+export declare class Driver<Client = unknown> {
+	/**
+	 * Create a new Client connection using supplied options/config.
+	 * @important Must return the `Client` for further usage.
+	 */
+	connect<Client>(config: Options.Config): Promise<Client> | Client;
+	/**
+	 * Create `migrations` table and query for existing/applied migrations.
+	 * @note You may `require('ley/lib/text')` for premade SQL-like queries.
+	 * @important Must return the `name` of any existing migrations.
+	 */
+	setup(client: Client): Promise<Migration.Existing[]>;
+	/**
+	 * Loop `files` and apply the target `method` action.
+	 * @note Whenever possible, *all* files should partake in the same transaction.
+	 */
+	loop(client: Client, files: Migration.File[], method: Migration.Method): Promise<void>;
+	/**
+	 * Gracefully terminate your client.
+	 * Runs after *all* migrations have been applied, or after an error is thrown.
+	 */
+	end(client: Client): Promise<void> | void;
+}
+
 export function up(opts?: Options.Up): Promise<string[]>;
 export function down(opts?: Options.Down): Promise<string[]>;
 export function status(opts?: Options.Base): Promise<string[]>;

lib/util.js

@@ -46,15 +46,23 @@ exports.exists = function (dep) {
 }
 
 // TODO: sqlite
+exports.drivers = ['postgres', 'pg', 'mysql', 'mysql2', 'better-sqlite3'];
+
 exports.detect = function () {
-	return ['postgres', 'pg', 'mysql', 'mysql2', 'better-sqlite3'].find(exports.exists);
+	return exports.drivers.find(exports.exists);
 }
 
 exports.local = function (str, cwd) {
 	str = resolve(cwd || '.', str);
 	return existsSync(str) && require(str);
 }
 
+exports.isDriver = function (ctx) {
+	['connect', 'setup', 'loop', 'end'].forEach(str => {
+		if (typeof ctx[str] !== 'function') throw new Error(`Driver must have "${str}" function`);
+	})
+}
+
 exports.MigrationError = class MigrationError extends Error {
 	constructor(err, file) {
 		super(err.message);

readme.md

@@ -23,8 +23,8 @@
 - [ ] driver support:
   - [x] [`pg`](https://www.npmjs.com/package/pg)
   - [x] [`postgres`](https://www.npmjs.com/package/postgres)
-  - [x] [`mysql`]()
-  - [x] [`mysql2`]()
+  - [x] [`mysql`](https://www.npmjs.com/package/mysql)
+  - [x] [`mysql2`](https://www.npmjs.com/package/mysql2)
   - [x] [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3)
   - [ ] [`sqlite`](https://www.npmjs.com/package/sqlite)
 - [ ] complete test coverage
@@ -33,7 +33,7 @@
 ## Features
 
 * **Agnostic**<br>
-  _Supports [`postgres`](https://www.npmjs.com/package/postgres), [`pg`](https://www.npmjs.com/package/pg), [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3), [`sqlite`](https://www.npmjs.com/package/sqlite), [`mysql`](https://www.npmjs.com/package/mysql), and [`mysql2`](https://www.npmjs.com/package/mysql2)_
+  _Supports [`postgres`](https://www.npmjs.com/package/postgres), [`pg`](https://www.npmjs.com/package/pg), [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3), [`sqlite`](https://www.npmjs.com/package/sqlite), [`mysql`](https://www.npmjs.com/package/mysql), [`mysql2`](https://www.npmjs.com/package/mysql2), and [custom drivers!](#drivers)_
 
 * **Lightweight**<br>
   _Does **not** include any driver dependencies._
@@ -148,6 +148,35 @@ const ley = require('ley');
 const successes = await ley.up({ ... });
 ```
 
+## Config
+
+> **TL;DR:** The contents of a `ley.config.js` file (default file name) is irrelevant to `ley` itself!
+
+A config file is entirely optional since `ley` assumes that you're providing the correct environment variable(s) for your client driver. However, that may not always be possible. In those instances, a `ley.config.js` file (default file name) can be used to adjust your [driver](#drivers)'s `connect` method.
+
+## Drivers
+
+Out of the box, `ley` includes drivers for the following npm packages:
+
+* [`postgres`](https://www.npmjs.com/package/postgres)
+* [`pg`](https://www.npmjs.com/package/pg)
+* [`mysql`](https://www.npmjs.com/package/mysql)
+* [`mysql2`](https://www.npmjs.com/package/mysql2)
+* [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3)
+
+When no driver is specified, `ley` will attempt to autodetect usage of these libraries in the above order.
+
+However, should you need a driver that's not listed – or should you need to override a supplied driver – you may easily do so via a number of avenues:
+
+1) CLI users can add `--driver <filename>` to any command; or
+2) Programmatic users can pass [`opts.driver`](#optsdriver) to any command; or
+3) A `ley.config.js` file can export a special `driver` config key.
+
+With any of these, if `driver` is a string then it will be passed through `require()` automatically. Otherwise, with the latter two, the `driver` is assumed to be a [`Driver`](/ley.d.ts#L45-L67) class and is validated as such.
+
+> **Important:** All drivers must adhere to the [`Driver` interface](/ley.d.ts#L45-L67)!
+
+
 ## API
 
 > **Important:** See [Options](#options) for common options shared all commands. <br>In this `API` section, you will only find **command-specific** options listed.
@@ -231,12 +260,13 @@ Default: `migrations`
 
 The directory (relative to `opts.cwd`) to find migration files.
 
-#### opts.client
-Type: `string`<br>
+#### opts.driver
+Type: `string` or `Driver`
 Default: `undefined`
 
-The **name** of your desired client driver; for example, `pg`.<br>
-When unspecified, `ley` searches for all supported client drivers in this order:
+When defined and a `string`, this is the **name** of your [driver](#drivers) implementation. It will pass through `require()` as written. Otherwise it's expected to match a [`Driver` interface](/ley.d.ts#L45-L67) and will be validated immediately.
+
+When undefined, `ley` searches for all supported client drivers in this order:
 
 ```js
 ['postgres', 'pg', 'mysql', 'mysql2', 'better-sqlite3']
@@ -249,8 +279,9 @@ Default: `undefined`
 A configuration object for your client driver to establish a connection.<br>
 When unspecified, `ley` assumes that your client driver is able to connect through `process.env` variables.
 
->**Note:** The `ley` CLI will search for a `ley.config.js` config file (configurable).<br>
-If found, this file may contain an object or a function that resolves to your config object.
+> **Note:** The `ley` CLI will search for a `ley.config.js` config file (configurable). <br>
+If found, this file may contain an object or a function that resolves to _anything_ of your chosing. <br>
+Please see [Config](#config) for more information.
 
 #### opts.require
 Type: `string` or `string[]`<br>
@@ -276,6 +307,7 @@ $ ley -r dotenv/config status
 $ ley --require dotenv/config status
 ```
 
+
 ## License
 
 MIT © [Luke Edwards](https://lukeed.com)

test/util.js

@@ -231,4 +231,58 @@ test('(utils) MigrationError', () => {
 	assert.equal(error.migration, migration, 'attaches custom "migration" key w/ file data');
 });
 
+test('(utils) isDriver :: connect', () => {
+	assert.throws(
+		() => $.isDriver({}),
+		'Driver must have "connect" function'
+	);
+
+	assert.throws(
+		() => $.isDriver({ connect: 123 }),
+		'Driver must have "connect" function'
+	);
+});
+
+test('(utils) isDriver :: setup', () => {
+	let noop = () => {};
+
+	assert.throws(
+		() => $.isDriver({ connect: noop }),
+		'Driver must have "setup" function'
+	);
+
+	assert.throws(
+		() => $.isDriver({ connect: noop, setup: 123 }),
+		'Driver must have "setup" function'
+	);
+});
+
+test('(utils) isDriver :: loop', () => {
+	let noop = () => {};
+
+	assert.throws(
+		() => $.isDriver({ connect: noop, setup: noop }),
+		'Driver must have "loop" function'
+	);
+
+	assert.throws(
+		() => $.isDriver({ connect: noop, setup: noop, loop: 123 }),
+		'Driver must have "loop" function'
+	);
+});
+
+test('(utils) isDriver :: end', () => {
+	let noop = () => {};
+
+	assert.throws(
+		() => $.isDriver({ connect: noop, setup: noop, loop: noop }),
+		'Driver must have "end" function'
+	);
+
+	assert.throws(
+		() => $.isDriver({ connect: noop, setup: noop, loop: noop, end: 123 }),
+		'Driver must have "end" function'
+	);
+});
+
 test.run();