escape

quoteStr

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

Import

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

Usage

function quoteStr(str: string): string;

Wraps a string in either double quotes (") or single quotes (').

Arguments

`str`

The string to be wrapped in quotes.

Return Value

Returns the string wrapped in quotes. The type of quote used depends on whether the provided 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.
- Double quotes are escaped with a backslash (\).

Examples

The following example shows strings without single quotes being wrapped 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 shows strings containing single quotes being wrapped 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 shows strings containing both single and double quotes being wrapped in double quotes with escaping where 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 quotes.

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 does not start with a number and consists only of alphanumeric characters and underscores:
- Returns the string as is.
If the given string contains double quotes:
- Escapes them.
If the given string contains backslashes (\):
- Escapes them.
If the given string starts with a number or contains characters other than alphanumeric characters and underscores:
- Wraps it in double quotes.

Examples

The following example shows a string consisting only of alphanumeric characters and underscores, resulting in the string being returned as is:

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

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

Output:

foo_bar

The following example shows strings being wrapped in double quotes with escaping where necessary:

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

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

Output:

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

escapeRid

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

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 number and consists only of alphanumeric characters and underscores:
- Returns the string as is.
If the given string contains closing brackets (⟩):
- Escapes them.
If the given string consists entirely of numbers or contains characters other than alphanumeric characters and underscores:
- Wraps it in brackets (⟨⟩).

Examples

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

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

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

Output:

foo_123

The following example shows strings being wrapped in brackets (⟨⟩) with escaping where 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 names of namespaces, databases, tables, and fields. For convenience, it also wraps empty strings in quotes.

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 number 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 number or contains characters other than alphanumeric characters and underscores:
- Wraps it in backticks (`).

Examples

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

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

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

Output:

foo_123

The following example shows strings being wrapped in backticks (`) with escaping where 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 perceived by a human:

Type	Representation	`.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 Marks	パ	2	`[ 0xE3, 0x83, 0x8F, 0xE3, 0x82, 0x9A ]`

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