Namespace: q

@divine/uri.q

Functions

assign

▸ assign(data, columns?, quote?): DBQuery

Constructs a DBQuery to be used as part of SQL UPDATE statements.

Given an object containing the column/value pairs, constructs an assignment expression that can be used as part of an SQL UPDATE statement. Example:

const userID = 1337;
const entry = { name: 'Martin', language: 'sv', country: 'se' };
const query = q`update locale set ${q.assign(entry)} where id = ${userID}`;

assert(query.toString() === 'update locale set "name" = «Martin»,"language" = «sv»,"country" = «se» where id = «1337»');

If any of the object's values are undefined, the SQL DEFAULT keyword will be used in its place.

Parameters

Name	Type	Default value	Description
data	Params	undefined	The object to assign. The key represents the column name and the value is the column value.
columns?	string[]	undefined	Specifies what keys (columns) to fetch from the data object. Defaults to all keys from the object.
quote	(ident: string) => DBQuery	q.quote	Constructs a DBQuery by enclosing the provied string in quotes. This function is used to escape SQL identifiers, like table or column names. Quotes inside the string will be encoded as "". Example: ts const table = q.quote(debit ? 'debit-table' : 'credit-table'); const query = q`select * from ${table} where amount > 10`;

Returns

DBQuery

A DBQuery suitable to be used in an SQL UPDATE statement.

Defined in

uri/src/protocols/database.ts:223

---

join

▸ join(delimiter, queries): DBQuery

Constructs a DBQuery by concatenating a list of subqueries and separating then with the provided delimiter.

If the list of subqueries contains undefined, those elements will be filtered out. Example usage:

const users = [ 1, 3, 7 ];
const query = q`select * from users where ${q.join(' or ', users.map((u) => q`id = ${u}`))}`;

assert(query.toString() === 'select * from users where id = «1» or id = «3» or id = «7»');

Parameters

Name	Type	Description
delimiter	string	The raw sequence to separate the queries with. Must be trused and not be user-provided, or (very) bad things will happen eventually.
queries	(undefined | DBQuery)[]	The subqueries to concatenate. May contain undefined elements, which will simply be skipped.

Returns

DBQuery

A new DBQuery with all subqueries concatenated.

Defined in

uri/src/protocols/database.ts:125

---

list

▸ list(list): DBQuery

Constructs a DBQuery by creating a list of the provided parameters: (elem1, elem2, ...).

This utility function is suitable for SQL IN clauses. If the parameter list contains undefined, those elements will be filtered out. Example:

const users = [ 1, 3, undefined, 7 ];
const query = q`select * from users where id in ${q.list(users)}`;

assert(query.toString() === 'select * from users where id in («1»,«3»,«7»)');

Parameters

Name	Type	Description
list	(undefined | BasicTypes)[]	The parameters to include in the list. May contain undefined elements, which will simply be skipped.

Returns

DBQuery

A DBQuery suitable to be used in an SQL IN clause.

Defined in

uri/src/protocols/database.ts:147

---

quote

▸ quote(ident): DBQuery

Constructs a DBQuery by enclosing the provied string in quotes.

This function is used to escape SQL identifiers, like table or column names. Quotes inside the string will be encoded as "". Example:

const table = q.quote(debit ? 'debit-table' : 'credit-table');
const query = q`select * from ${table} where amount > 10`;

Parameters

Name	Type	Description
ident	string	The name of a table to column to escape.

Returns

DBQuery

A (partial) DBQuery with the identified escaped.

Defined in

uri/src/protocols/database.ts:85

---

raw

▸ raw(raw): DBQuery

Constructs a DBQuery by taking the provided raw string as-is.

This is useful if the database does not accept a parameter at this place in the query. However, you must be very careful not to introduce query injection vulnerabilities when using this function! Example:

const offset = q.raw(Number(100 * page));
const query  = q`select * from posts limit 100 offset ${offset}`;

Parameters

Name	Type	Description
raw	string | number | bigint	The raw query to create. Must be trused and not be user-provided, or (very) bad things will happen eventually.

Returns

DBQuery

A (partial) DBQuery with the unparsed query.

Defined in

uri/src/protocols/database.ts:104

---

values

▸ values(data, columns?, parts?, quote?): DBQuery

Constructs a DBQuery to be used as part of SQL INSERT statements.

Given an object (or list of objects) containing the column/value pairs, constructs either the columns list or the values list (or lists), or both, depending on the parts argument. Examples:

// Insert columns name, language, country
const entry = { name: 'Martin', language: 'sv', country: 'se' };
const query = q`insert into locale ${q.values(entry)}`;

assert(query.toString() === 'insert into locale ("name","language","country") values («Martin»,«sv»,«se»)');

// Insert multiple rows, but only columns name and country
const multi = [ { name: 'Martin', language: 'sv', country: 'se' }, { name: 'John', language: 'en', country: 'us' } ];
const query = q`insert into users ${q.values(multi, ['name', 'country'])}`;

assert(query.toString() === 'insert into users ("name","country") values («Martin»,«se»),(«John»,«us»)');

If any of the object's values are undefined, the SQL DEFAULT keyword will be used in its place.

Parameters

Name	Type	Default value	Description
data	Params | Params[]	undefined	The object or objects to insert. The key represents the column name and the value is the column value.
columns?	string[]	undefined	Specifies what keys (columns) to fetch from the data objects. Defaults to all keys from all objects.
parts	"values" | "columns" | "expr"	'expr'	What part of the statement to generate. Use columns to only generate a list of column names, values for a list of value tuples or expr, the default, for the complete subexpression.
quote	(ident: string) => DBQuery	q.quote	Constructs a DBQuery by enclosing the provied string in quotes. This function is used to escape SQL identifiers, like table or column names. Quotes inside the string will be encoded as "". Example: ts const table = q.quote(debit ? 'debit-table' : 'credit-table'); const query = q`select * from ${table} where amount > 10`;

Returns

DBQuery

A DBQuery suitable to be used in an SQL INSERT statement.

Defined in

uri/src/protocols/database.ts:189