feat: add sql.escape function

Author: jedwards1211

README.md

@@ -23,7 +23,7 @@ Requires `sequelize@^4.0.0`.  Once v5 is released I'll check if it's still
 compatible.  Not making any effort to support versions < 4, but you're welcome
 to make a PR.
 
-## Example
+## Examples
 
 ```js
 const Sequelize = require('sequelize')
@@ -44,3 +44,40 @@ WHERE ${User.attributes.birthday} = ${new Date('2346-7-11')} AND
   ${Sequelize.literal(lock ? 'FOR UPDATE' : '')}`).then(console.log);
 // => [ [ { name: 'Jimbob' } ], Statement { sql: 'SELECT "name" FROM "Users" WHERE "birthday" = $1 AND "active" = $2 FOR UPDATE' } ]
 ```
+
+Sometimes custom subqueries within a Sequelize `where` clause can be useful.
+In this case, there is no way to use query parameters.  You can use
+`sql.escape` in this context to inline the escaped values rather than using
+query parameters:
+
+```js
+const {Op} = Sequelize
+
+const User = sequelize.define('User', {
+  name: {type: Sequelize.STRING},
+})
+const Organization = sequelize.define('Organization', {
+  name: {type: Sequelize.STRING},
+})
+const OrganizationMember = sequelize.define('OrganizationMember', {
+  userId: {type: Sequelize.INTEGER},
+  organizationId: {type: Sequelize.INTEGER},
+})
+User.belongsToMany(Organization, {through: OrganizationMember})
+Organization.belongsToMany(User, {through: OrganizationMember})
+
+async function getUsersInOrganization(organizationId, where = {}) {
+  return await User.findAll({
+    where: {
+      ...where,
+      // Using a sequelize include clause to do this kind of sucks tbh
+      id: {[Op.in]: Sequelize.literal(sql.escape`
+        SELECT ${OrganizationMember.attributes.userId}
+        FROM ${OrganizationMember}
+        WHERE ${OrganizationMember.attributes.organizationId} = ${organizationId}
+      `)}
+      // SELECT "userId" FROM "OrganizationMembers" WHERE "organizationId" = 2
+    },
+  })
+}
+```

src/index.js

@@ -30,4 +30,32 @@ function sql(
   return {bind, query: parts.join('').trim().replace(/\s+/g, ' ')}
 }
 
+sql.escape = function escapeSql(
+  strings: $ReadOnlyArray<string>,
+  ...expressions: $ReadOnlyArray<mixed>
+): string {
+  const parts: Array<string> = []
+  let queryGenerator
+  for (let i = 0, length = expressions.length; i < length; i++) {
+    parts.push(strings[i])
+    const expression = expressions[i]
+    if (expression instanceof Literal) {
+      parts.push(expression.val)
+    } else if (expression && expression.prototype instanceof Model) {
+      const {QueryGenerator, tableName} = (expression: any)
+      queryGenerator = QueryGenerator
+      parts.push(QueryGenerator.quoteTable(tableName))
+    } else if (expression && expression.type instanceof Sequelize.ABSTRACT) {
+      const {field, Model: {QueryGenerator}} = (expression: any)
+      queryGenerator = QueryGenerator
+      parts.push(QueryGenerator.quoteIdentifier(field))
+    } else {
+      if (!queryGenerator) throw new Error(`at least one of the expressions must be a sequelize Model or attribute`)
+      parts.push(queryGenerator.escape(expression))
+    }
+  }
+  parts.push(strings[expressions.length])
+  return parts.join('').trim().replace(/\s+/g, ' ')
+}
+
 module.exports = sql

test/index.js

@@ -23,3 +23,23 @@ WHERE ${User.attributes.birthday} = ${new Date('2346-7-11')} AND
     })
   })
 })
+
+describe(`sql.escape`, function () {
+  it(`works`, function () {
+    const sequelize = new Sequelize('test', 'test', 'test', {dialect: 'postgres'})
+
+    const User = sequelize.define('User', {
+      name: {type: Sequelize.STRING},
+      birthday: {type: Sequelize.DATE},
+    })
+
+    expect(sql.escape`
+SELECT ${User.attributes.id} ${Sequelize.literal('FROM')} ${User}
+WHERE ${User.attributes.name} LIKE ${'and%'} AND
+  ${User.attributes.id} = ${1}
+    `).to.deep.equal(`SELECT "id" FROM "Users" WHERE "name" LIKE 'and%' AND "id" = 1`)
+  })
+  it(`throws if it can't get a QueryGenerator`, function () {
+    expect(() => sql.escape`SELECT ${1} + ${2};`).to.throw(Error, 'at least one of the expressions must be a sequelize Model or attribute')
+  })
+})