qqtag

Quasi quote library for javascript template literals.

Motivation

Some database libraries like mssql supports embedding query parameters using tagged literals:

const sql = require('mssql')

sql.connect(config).then(() => {
    return sql.query`select * from mytable where id = ${value}`
}).then(result => {
    console.dir(result)
}).catch(err => {
    // ... error checks
})

But what to do if you want to embed a table name variable, or if you want to add optional WHERE conditions based on values of variables ?

Usage

• quasiquote expresses a template literal that is not yet evaluated and can be passed to other tag functions.

  import { quasiquote as qq } from 'qqtag'
  
  const sql = require('mssql')
  
  sql.connect(config).then(() => {
    const query = qq`select * from mytable where id = ${value}`
    return query.sendTo(sql.query.bind(sql))
  }) // ...

• quote can embed a string as a part of literals instead of passing it to a template literal place holder.

  import { quasiquote as qq, quote as qt } from 'qqtag'
  
  const tableName = 'tab1'
  const query1 = qq`select col1 from ${tableName}`
  const query2 = qq`select col1 from ${qt(tableName)}`
  
  query1.sendTo((ss, ...vs) => {
    console.log([ss, vs])
    // -> [ [ 'select col1 from ', '' ], [ 'tab1' ] ]
    //    This is not what is wanted.
  })
  query2.sendTo((ss, ...vs) => {
    console.log([ss, vs])
    // -> [ [ 'select col1 from tab1' ], [] ]
  })

• unquote can embed another quasiquote .

  import { quasiquote as qq, unquote as uq } from 'qqtag'
  
  let colvalue = '2'
  
  const query = qq`select col1 from tab1
  ${uq(() => {
    if (colvalue != null) {
      return qq`where col2 = ${colvalue}`
    }
  })}
  `
  query.sendTo((ss, ...vs) => {
    console.log([ss, vs])
    // -> [ [ 'select col1 from tab1\n  where col2 = ', '\n' ], [ '2' ] ]
  })
  
  colvalue = null
  
  query.sendTo((ss, ...vs) => {
    console.log([ss, vs])
    // -> [ [ 'select col1 from tab1\n  \n' ], [] ]
  })

Example

(These examples may be stale and may not work, but the concept will be apply.)

mysql

const newQuery = (conn) =>
  (ss, ...vs) => new Promise((resolve, reject) => {
    conn.query(newQueryOpts(ss, ...vs), (error, results, fields) => {
      if (error) return reject(error)
      return resolve({ results, fields })
    })
  })

const newQueryOpts = (ss, ...vs) => {
  const values = vs
  const sql = ss.slice(1).reduce((a, s, i) => `${a} ? ${s}`, ss[0])
  return { sql, values }
}

const newSql = (conn) =>
  (ss, ...vs) => vs.reduce((a, c, i) => `${a}${conn.escape(c)}${ss[i + 1]}`, ss[0])


const listUsers = async (conn, opts) => {
  return await qq`\
select * from users \
${uq(() => opts.userId != null ? qq`where user_id=${opts.userId}` : undefined)} ;\
`.sendTo(newQuery(conn))
}

const getLiteralSqlForListUsers = async (conn, opts) => {
  return await qq`\
select * from users \
${uq(() => opts.userId != null ? qq`where user_id=${opts.userId}` : undefined)} ;\
`.sendTo(newSql(conn))
}

@azure/cosmos (v2)

const newQuery = (ss, ...vs) => {
  const parameters = vs.reduce((a, v, i) => (a.push({ name: `@p_${i}`, value: vs[i] }), a), [])
  const query = ss.slice(1).reduce((a, s, i) => `${a} ${parameters[i].name} ${s}`, ss[0])
  return { query, parameters }
}

const querySpec = qq`select * from ${qt(collectionName)} t where t.UserId = ${userId}`.sendTo(newQuery)
const feedOptios = {
  // ...
}
const queryIterator = collection.container.items.query(querySpec, feedOptios)

mssql: pass typed query parameters

class BaseCustomSqlType {
  constructor(value) {
    this.value = value
  }
  valueOf() {
    return this.value
  }
}
class VarChar extends BaseCustomSqlType {}
class Numeric extends BaseCustomSqlType {}

sql.map.register(VarChar, sql.VarChar)
sql.map.register(Numeric, sql.Numeric)

const value = 123
const query = qq`select * from tab1 where col1 = ${new Numeric(value)}`

Public API

• quasiquote: (ss: TemplateStringsArray, ...vs: any[]) => QuasiQuote
  • Construct a quasisquote.
• quote: (value: any) => Quote
  • Construct a quote that can be embeded in a quasiquote.
• unquote: (qq: Quote | QuasiQuote | (() => any) | Promise<Quote> | Promise<QuasiQuote> | (() => Promise<any>)) => UnQuote
  • Construct an unquote that can be embeded in a quasiquote.
• concatQ: (sep: string, qs: QuasiQuote[]) => QuasiQuote
  • Concatenate quasiquotes.
• stringify: (ss: TemplateStringsArray, ...vs: any[]) => any
  • A tag function that stringify a string literal to the same string as that string literal.
• class QuasiQuote
  • (constructor is not intended to be used to create a instance directly)
  • sendTo<T>(f: ((ss: TemplateStringsArray, ...vs: any[]) => T) | ((ss: readonly string[], ...vs: any[]) => T)): T
    • Pass a quasiquote to a tag function.
  • sendToAsync<T>(f: ((ss: TemplateStringsArray, ...vs: any[]) => (T | Promise<T>)) | ((ss: readonly string[], ...vs: any[]) => (T | Promise<T>))): Promise<T>
    • The async version of sendTo.
      • If Promises are embedded in unquotes, the async version should be used.
      • If f returns a promise, it is also awaited.
  • intoTag(): [TemplateStringsArray, ...any[]]
    • Convert a quasiquote to a captured tagged literal that can be passed to a tag function.
  • intoTagAsync(): Promise<[TemplateStringsArray, ...any[]]>
    • The async version of intoTag.
      • If Promises are embedded in unquotes, the async version should be used.
  • evaluated(): QuasiQuote
    • Evaluate a captured quasiquote.
      • Before evaluated, sendTo or intoTag of a quasiquote evaluates embeded functions in unquotes lazily.
  • evaluatedAsync(): Promise<QuasiQuote>
    • The async version of evaluated.
  • get isEmpty(): boolean
    • Return if a quasiquote is empty (that is, just `` .)
  • static empty(): QuasiQuote
    • Construct an empty quasiquote.
  • static joinQ(sep: string, q1: QuasiQuote, q2: QuasiQuote): QuasiQuote
    • Join two quasiquotes.
• class Quote
  • (constructor is not intended to be used to create a instance directly)
• class UnQuote
  • (constructor is not intended to be used to create a instance directly)

References

• nest-literal seems to provide similar functionalities.

License

This library is licensed under the MIT License.