feat(query): add identifier fn for templating table, column names

Signed-off-by: Vladislav Polyakov <[email protected]>

Author: polRk

packages/query/src/index.ts

@@ -8,7 +8,7 @@ import { defaultRetryConfig, isRetryableError, retry } from '@ydbjs/retry'
 
 import { Query } from './query.js'
 import { ctx } from './ctx.js'
-import { yql } from './yql.js'
+import { UnsafeString, identifier, yql } from './yql.js'
 
 export type SQL = <T extends any[] = unknown[], P extends any[] = unknown[]>(
 	strings: string | TemplateStringsArray,
@@ -48,6 +48,20 @@ export interface QueryClient extends SQL, AsyncDisposable {
 
 	transaction<T = unknown>(fn: TransactionContextCallback<T>): Promise<T>
 	transaction<T = unknown>(options: TransactionExecuteOptions, fn: TransactionContextCallback<T>): Promise<T>
+
+	/**
+	 * Create an UnsafeString that represents a DB identifier (table, column).
+	 * When used in a query, the identifier will be escaped.
+	 *
+	 * **WARNING: This function does not offer any protection against SQL injections,
+	 *            so you must validate any user input beforehand.**
+	 *
+	 * @example ```ts
+	 * const query = sql`SELECT * FROM ${sql.identifier('my-table')}`;
+	 * // 'SELECT * FROM `my-table`'
+	 * ```
+	 */
+	identifier(value: string | { toString(): string }): UnsafeString
 }
 
 const doImpl = function <T = unknown>(): Promise<T> {
@@ -191,6 +205,7 @@ export function query(driver: Driver): QueryClient {
 			do: doImpl,
 			begin: txIml,
 			transaction: txIml,
+			identifier: identifier,
 			async [Symbol.asyncDispose]() { },
 		}
 	)

packages/query/src/yql.ts

@@ -1,17 +1,13 @@
-import { fromJs, type Value } from "@ydbjs/value"
+import { type Value, fromJs } from "@ydbjs/value"
 
-const unsafe = Symbol("unsafe")
+const SymbolUnsafe = Symbol("unsafe")
 
 function isObject(value: unknown): boolean {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
 export class UnsafeString extends String {
-	constructor(public value: string) {
-		super(value)
-	}
-
-	[unsafe] = true
+	[SymbolUnsafe] = true
 }
 
 export function yql<P extends any[] = unknown[]>(
@@ -23,7 +19,7 @@ export function yql<P extends any[] = unknown[]>(
 
 	if (Array.isArray(values)) {
 		values.forEach((value, i) => {
-			if (value[unsafe]) {
+			if (value[SymbolUnsafe]) {
 				return
 			}
 
@@ -41,17 +37,17 @@ export function yql<P extends any[] = unknown[]>(
 		text += strings.reduce((prev, curr, i) => {
 			let value = values[i]
 
-			return prev + curr + (value ? value[unsafe] ? value.toString() : `$p${i}` : '')
+			return prev + curr + (value ? value[SymbolUnsafe] ? value.toString() : `$p${i}` : '')
 		}, '')
 	}
 
 	return { text, params }
 }
 
-export function usafe(value: string | { toString(): string }) {
+export function unsafe(value: string | { toString(): string }) {
 	return new UnsafeString(value.toString())
 }
 
-export function table(path: string) {
-	return usafe("`" + path + "`")
+export function identifier(path: string) {
+	return unsafe("`" + path + "`")
 }