escape

quoteStr

quoteStr is a function that wraps a string in quotation marks. For convenience, it also wraps empty strings in quotation marks.

Import

import { quoteStr } from "@tai-kun/surrealdb/utils";

Usage

function quoteStr(str: string): string;

Wraps a string in quotation marks (" or ').

Arguments

`str`

The string to be wrapped in quotation marks.

Return Value

Returns the string wrapped in quotation marks. The type of quotation marks used depends on whether the given string contains single quotes ('):

If the given string is empty:
- Returns ''.
If the given string does not contain single quotes:
- Wraps it in single quotes.
If the given string contains single quotes:
- Wraps it in double quotes.
If the given string contains both single and double quotes:
- Wraps it in double quotes.
- Escapes double quotes with a backslash (\).

Examples

The following example wraps strings that do not contain single quotes in single quotes:

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(``));
console.log(quoteStr(`a`));
console.log(quoteStr(`𩸽`));
console.log(quoteStr(`👍🏽`));
console.log(quoteStr(`パ`));

Output:

''
'a'
'𩸽'
'👍🏽'
'パ'

The following example wraps strings that contain single quotes in double quotes:

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(`cat's`));
console.log(quoteStr(`𩸽's`));
console.log(quoteStr(`'👍🏽`));
console.log(quoteStr(`'パ`));

Output:

"cat's"
"𩸽's"
"'👍🏽"
"'パ"

The following example wraps strings that contain both single and double quotes in double quotes, escaping them as necessary:

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(`cat's "toy"`));
console.log(quoteStr(`'\\"\\`));
console.log(quoteStr(`𩸽's "feed"`));
console.log(quoteStr(`'👍🏽"`));
console.log(quoteStr(`'パ"`));

Output:

"cat's \"toy\""
"'\\\"\\"
"𩸽's \"feed\""
"'👍🏽\""
"'パ\""

escapeKey

escapeKey is similar to quoteStr but is used for object keys. For convenience, it also wraps empty strings in quotation marks.

Import

import { escapeKey } from "@tai-kun/surrealdb/utils";

Usage

function escapeKey(key: string): string;

Arguments

`key`

The object key.

Return Value

Returns the escaped string, wrapped in double quotes if necessary:

If the given string is empty:
- Returns "".
If the given string consists only of alphanumeric characters and underscores:
- Returns the string as is.
If the given string contains characters other than alphanumeric characters and underscores:
- Wraps it in double quotes.
If the given string contains backslashes (\):
- Escapes them.
If the given string contains double quotes:
- Escapes them.

Examples

The following example shows that if the string consists only of alphanumeric characters and underscores, the string is returned as is:

import { escapeKey } from "@tai-kun/surrealdb/utils";

console.log(escapeKey(`123`));
console.log(escapeKey(`foo_bar`));

Output:

123
foo_bar

The following example wraps the string in double quotes and escapes characters as necessary:

import { escapeKey } from "@tai-kun/surrealdb/utils";

console.log(escapeKey(``));
console.log(escapeKey(`foo-bar`));
console.log(escapeKey(`'\\"\\`));
console.log(escapeKey(`𩸽's "feed"`));
console.log(escapeKey(`'👍🏽"`));
console.log(escapeKey(`'パ"`));

Output:

""
"foo-bar"
"'\\\"\\"
"𩸽's \"feed\""
"'👍🏽\""
"'パ\""

escapeRid

escapeRid is similar to quoteStr but is used for record IDs. For convenience, it also wraps empty strings in quotation marks.

Import

import { escapeRid } from "@tai-kun/surrealdb/utils";

Usage

function escapeRid(rid: string): string;

Arguments

`rid`

The ID part of the record ID.

Return Value

Returns the escaped string, wrapped in brackets (⟨⟩) if necessary:

If the given string is empty:
- Returns ⟨⟩.
If the given string does not start with a digit and consists only of alphanumeric characters and underscores:
- Returns the string as is.
If the given string contains brackets (⟩):
- Escapes them.
If the given string starts with a digit or contains characters other than alphanumeric characters and underscores:
- Wraps it in brackets (⟨⟩).

Examples

The following example shows that if the string does not start with a digit and consists only of alphanumeric characters and underscores, the string is returned as is:

import { escapeRid } from "@tai-kun/surrealdb/utils";

console.log(escapeRid(`foo_123`));

Output:

foo_123

The following example wraps the string in brackets (⟨⟩) and escapes characters as necessary:

import { escapeRid } from "@tai-kun/surrealdb/utils";

console.log(escapeRid(``));
console.log(escapeRid(`123`));
console.log(escapeRid(`foo-bar`));
console.log(escapeRid(`𩸽's ⟨feed⟩`));
console.log(escapeRid(`'👍🏽⟩`));
console.log(escapeRid(`'パ⟩`));

Output:

⟨⟩
⟨123⟩
⟨foo-bar⟩
⟨𩸽's ⟨feed\⟩⟩
⟨'👍🏽\⟩⟩
⟨'パ\⟩⟩

escapeIdent

escapeIdent is similar to quoteStr but is used for namespace, database, table, and field names. For convenience, it also wraps empty strings in quotation marks.

Import

import { escapeIdent } from "@tai-kun/surrealdb/utils";

Usage

function escapeIdent(ident: string): string;

Arguments

`ident`

The identifier.

Return Value

Returns the escaped string, wrapped in backticks (`) if necessary:

If the given string is empty:
- Returns .
If the given string does not start with a digit and consists only of alphanumeric characters and underscores:
- Returns the string as is.
If the given string contains backticks (`):
- Escapes them.
If the given string starts with a digit or contains characters other than alphanumeric characters and underscores:
- Wraps it in backticks (`).

Examples

The following example shows that if the string does not start with a digit and consists only of alphanumeric characters and underscores, the string is returned as is:

import { escapeIdent } from "@tai-kun/surrealdb/utils";

console.log(escapeIdent(`foo_123`));

Output:

foo_123

The following example wraps the string in backticks (`) and escapes characters as necessary:

import { escapeIdent } from "@tai-kun/surrealdb/utils";

console.log(escapeIdent(""));
console.log(escapeIdent("123"));
console.log(escapeIdent("foo-bar"));
console.log(escapeIdent("𩸽's `feed`"));
console.log(escapeIdent("'👍🏽`"));
console.log(escapeIdent("'パ`"));

Output:

``
`123`
`foo-bar`
`𩸽's \`feed\``
`'👍🏽\``
`'パ\``

Column

String Length

The strings used in the previous examples contain characters where the length of the string as seen by JavaScript differs from the length as seen by a human:

Type	Display	`.length`	`Uint8Array`
ASCII	a	1	`[ 0x61 ]`
Surrogate Pair	𩸽	2	`[ 0xF0, 0xA9, 0xB8, 0xBD ]`
Variation Selector	👍🏽	4	`[ 0xF0, 0x9F, 0x91, 0x8D, 0xF0, 0x9F, 0x8F, 0xBD ]`
Combining Char	パ	2	`[ 0xE3, 0x83, 0x8F, 0xE3, 0x82, 0x9A ]`

When the value of .length is counterintuitive, you must carefully consider the operations on the string.