README

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.

Usage no npm install needed!