Implement extendable builders (knex#5041)

Co-authored-by: Olivier Cavadenti <[email protected]>

Author: DominicVonk

lib/knex-builder/Knex.js

@@ -5,6 +5,10 @@ const QueryInterface = require('../query/method-constants');
 const makeKnex = require('./make-knex');
 const { KnexTimeoutError } = require('../util/timeout');
 const { resolveConfig } = require('./internal/config-resolver');
+const SchemaBuilder = require('../schema/builder');
+const ViewBuilder = require('../schema/viewbuilder');
+const ColumnBuilder = require('../schema/columnbuilder');
+const TableBuilder = require('../schema/tablebuilder');
 
 function knex(config) {
   const { resolvedConfig, Dialect } = resolveConfig(...arguments);
@@ -28,4 +32,28 @@ knex.QueryBuilder = {
   },
 };
 
+knex.SchemaBuilder = {
+  extend: function (methodName, fn) {
+    SchemaBuilder.extend(methodName, fn);
+  },
+};
+
+knex.ViewBuilder = {
+  extend: function (methodName, fn) {
+    ViewBuilder.extend(methodName, fn);
+  },
+};
+
+knex.ColumnBuilder = {
+  extend: function (methodName, fn) {
+    ColumnBuilder.extend(methodName, fn);
+  },
+};
+
+knex.TableBuilder  = {
+  extend: function (methodName, fn) {
+    TableBuilder.extend(methodName, fn);
+  },
+};
+
 module.exports = knex;

lib/migrations/migrate/MigrationGenerator.js

@@ -41,7 +41,7 @@ class MigrationGenerator {
 
   _getNewMigrationName(name) {
     if (name[0] === '-') name = name.slice(1);
-    return yyyymmddhhmmss() + '_' + name + '.' + this.config.extension;
+    return yyyymmddhhmmss() + '_' + name + '.' + this.config.extension.split('-')[0];
   }
 
   _getNewMigrationPath(name) {

lib/migrations/migrate/stub/js-schema.stub

@@ -0,0 +1,22 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function({schema}) {
+  <% if (d.tableName) { %>
+  return schema.createTable("<%= d.tableName %>", function(t) {
+    t.increments();
+    t.timestamp();
+  });
+  <% } %>
+};
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function({schema}) {
+  <% if (d.tableName) { %>
+  return schema.dropTable("<%= d.tableName %>");
+  <% } %>
+};

lib/migrations/migrate/stub/ts-schema.stub

@@ -0,0 +1,21 @@
+import { Knex } from "knex";
+
+<% if (d.tableName) { %>
+export async function up({schema}: Knex): Promise<Knex.SchemaBuilder> {
+    return schema.createTable("<%= d.tableName %>", (t) => {
+        t.increments();
+        t.timestamps();
+    });
+}
+<% } else { %>
+export async function up({schema}: Knex): Promise<void> {
+}
+<% } %>
+<% if (d.tableName) { %>
+export async function down({schema}: Knex): Promise<Knex.SchemaBuilder> {
+    return schema.dropTable("<%= d.tableName %>");
+}
+<% } else { %>
+export async function down({schema}: Knex): Promise<void> {
+}
+<% } %>

lib/schema/builder.js

@@ -1,5 +1,6 @@
 const { EventEmitter } = require('events');
 const toArray = require('lodash/toArray');
+const assign = require('lodash/assign');
 const { addQueryContext } = require('../util/helpers');
 const saveAsyncStack = require('../util/save-async-stack');
 const {
@@ -96,6 +97,17 @@ class SchemaBuilder extends EventEmitter {
   };
 });
 
+
+SchemaBuilder.extend = (methodName, fn) => {
+  if (Object.prototype.hasOwnProperty.call(SchemaBuilder.prototype, methodName)) {
+    throw new Error(
+      `Can't extend SchemaBuilder with existing method ('${methodName}').`
+    );
+  }
+
+  assign(SchemaBuilder.prototype, { [methodName]: fn });
+};
+
 augmentWithBuilderInterface(SchemaBuilder);
 addQueryContext(SchemaBuilder);
 

lib/schema/columnbuilder.js

@@ -1,4 +1,5 @@
 const extend = require('lodash/extend');
+const assign = require('lodash/assign');
 const toArray = require('lodash/toArray');
 const { addQueryContext } = require('../util/helpers');
 
@@ -87,6 +88,17 @@ ColumnBuilder.prototype.notNull = ColumnBuilder.prototype.notNullable =
   };
 });
 
+
+ColumnBuilder.extend = (methodName, fn) => {
+  if (Object.prototype.hasOwnProperty.call(ColumnBuilder.prototype, methodName)) {
+    throw new Error(
+      `Can't extend ColumnBuilder with existing method ('${methodName}').`
+    );
+  }
+
+  assign(ColumnBuilder.prototype, { [methodName]: fn });
+};
+
 const AlterMethods = {};
 
 // Specify that the column is to be dropped. This takes precedence

lib/schema/tablebuilder.js

@@ -8,6 +8,7 @@
 // ------
 const each = require('lodash/each');
 const extend = require('lodash/extend');
+const assign = require('lodash/assign');
 const toArray = require('lodash/toArray');
 const helpers = require('../util/helpers');
 const { isString, isFunction, isObject } = require('../util/is');
@@ -360,4 +361,15 @@ AlterMethods.dropColumn = AlterMethods.dropColumns = function () {
   return this;
 };
 
+
+TableBuilder.extend = (methodName, fn) => {
+  if (Object.prototype.hasOwnProperty.call(TableBuilder.prototype, methodName)) {
+    throw new Error(
+      `Can't extend TableBuilder with existing method ('${methodName}').`
+    );
+  }
+
+  assign(TableBuilder.prototype, { [methodName]: fn });
+};
+
 module.exports = TableBuilder;

lib/schema/viewbuilder.js

@@ -1,5 +1,6 @@
 const helpers = require('../util/helpers');
 const extend = require('lodash/extend');
+const assign = require('lodash/assign');
 
 class ViewBuilder {
   constructor(client, method, viewName, fn) {
@@ -78,4 +79,15 @@ const AlterMethods = {
 
 helpers.addQueryContext(ViewBuilder);
 
+
+ViewBuilder.extend = (methodName, fn) => {
+  if (Object.prototype.hasOwnProperty.call(ViewBuilder.prototype, methodName)) {
+    throw new Error(
+      `Can't extend ViewBuilder with existing method ('${methodName}').`
+    );
+  }
+
+  assign(ViewBuilder.prototype, { [methodName]: fn });
+};
+
 module.exports = ViewBuilder;

test/db-less-test-suite.js

@@ -20,6 +20,7 @@ describe('Query Building Tests', function () {
   require('./unit/query/string');
   require('./unit/schema-builder/mysql')('mysql');
   require('./unit/schema-builder/mysql')('mysql2');
+  require('./unit/schema-builder/extensions');
   require('./unit/schema-builder/postgres');
   require('./unit/schema-builder/redshift');
   require('./unit/schema-builder/sqlite3');

test/unit/schema-builder/extensions.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const expect = require('chai').expect;
+const MySQL_Client = require('../../../lib/dialects/mysql');
+const knex = require('../../../knex');
+describe('SchemaBuilder Extensions', () => {
+  const client = new MySQL_Client({ client: 'mysql' });
+
+  const equal = require('assert').equal;
+  const functionToExtend = () => true;
+  knex.SchemaBuilder.extend('tryCreateTable', functionToExtend);
+  knex.TableBuilder.extend('testCol', functionToExtend);
+  knex.ColumnBuilder.extend('testCol', functionToExtend);
+  knex.ViewBuilder.extend('testCol', functionToExtend);
+
+  it('schemabuilder has method', () => {
+    equal(client.schemaBuilder().tryCreateTable, functionToExtend);
+    expect(client.schemaBuilder().tryCreateTable()).to.be.true;
+  });
+
+  it('tablebuilder has method', () => {
+    client
+      .schemaBuilder()
+      .createTable('users', function (table) {
+        equal(table.testCol, functionToExtend);
+      })
+      .toSQL();
+  });
+
+  it('columnbuilder has method', () => {
+    client
+      .schemaBuilder()
+      .createTable('users', function (table) {
+        equal(table.string('t').testCol, functionToExtend);
+      })
+      .toSQL();
+  });
+
+  it('viewbuilder has method', () => {
+    client
+      .schemaBuilder()
+      .createView('users', function (view) {
+        equal(view.testCol, functionToExtend);
+        view.as(
+          knex('users')
+            .join('user_roles', 'users.user_id', 'user_roles.user_id')
+            .select('users.*', 'user_roles.role_code')
+        );
+      })
+      .toSQL();
+  });
+});

types/index.d.ts

@@ -384,6 +384,43 @@ export declare namespace knex {
     ): void;
   }
 
+  class TableBuilder {
+    static extend(
+      methodName: string,
+      fn: (
+        this: Knex.TableBuilder,
+        ...args: any[]
+      ) => Knex.TableBuilder
+    ): void;
+  }
+  class ViewBuilder {
+    static extend(
+      methodName: string,
+      fn: (
+        this: Knex.ViewBuilder,
+        ...args: any[]
+      ) => Knex.ViewBuilder
+    ): void;
+  }
+  class SchemaBuilder {
+    static extend(
+      methodName: string,
+      fn: (
+        this: Knex.SchemaBuilder,
+        ...args: any[]
+      ) => Knex.SchemaBuilder
+    ): void;
+  }
+  class ColumnBuilder {
+    static extend(
+      methodName: string,
+      fn: (
+        this: Knex.ColumnBuilder,
+        ...args: any[]
+      ) => Knex.ColumnBuilder
+    ): void;
+  }
+
   export class KnexTimeoutError extends Error {}
 
   export const Client: typeof Knex.Client;