feature/add-parameterized-utility-function (#80)

Author: alessiofrittoli

README.md

@@ -1516,6 +1516,46 @@ console.log(parseValue("String value")); // Outputs: 'String value'
 
 ---
 
+##### `parameterized`
+
+Creates a parameterized string with placeholder values.
+
+###### Types
+
+###### `ParameterizedValue`
+
+Represents a value that can be used as a parameter in string operations.
+
+```ts
+type ParameterizedValue = string | boolean | number | bigint;
+```
+
+###### `Parameterized`
+
+Represents a parameterized string with its corresponding values.
+
+```ts
+type Parameterized = [string, ParameterizedValue[]];
+```
+
+<details>
+
+<summary style="cursor:pointer">Examples</summary>
+
+```ts
+import { parameterized } from "@alessiofrittoli/web-utils";
+
+const data = {
+  value: "parameterized",
+};
+
+console.log(parameterized`My string with ${data.value} values.`); // [ 'My string with ? values.', [ 'parameterized' ] ]
+```
+
+</details>
+
+---
+
 #### Types utilities
 
 ⚠️ Docs coming soon

__tests__/strings.test.ts

@@ -1,4 +1,4 @@
-import { lcFirst, parseValue, stringifyValue, toCamelCase, toKebabCase, ucFirst } from '@/strings'
+import { lcFirst, parameterized, parseValue, stringifyValue, toCamelCase, toKebabCase, ucFirst } from '@/strings'
 import { addLeadingCharacter, addTrailingCharacter, removeLeadingCharacter, removeTrailingCharacter } from '@/strings'
 import { recipientsToString, emailDataToString } from '@/strings'
 
@@ -607,4 +607,154 @@ describe( 'emailDataToString', () => {
 		)
 	} )
 
+} )
+
+
+describe( 'parameterized', () => {
+
+	it( 'creates a parameterized string with a single value', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id = ${ 1 }`
+		
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ?' )
+		expect( params ).toEqual( [ 1 ] )
+
+	} )
+
+
+	it( 'creates a parameterized string with multiple single values', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id = ${ 1 } AND name = ${ 'John' }`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ? AND name = ?' )
+		expect( params ).toEqual( [ 1, 'John' ] )
+
+	} )
+
+
+	it( 'expands array values into multiple placeholders', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE status IN ( ${ [ 'active', 'pending' ] } )`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE status IN ( ?, ? )' )
+		expect( params ).toEqual( [ 'active', 'pending' ] )
+
+	} )
+
+
+	it( 'handles mixed single and array values', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id = ${ 1 } AND status IN ( ${ [ 'active', 'pending' ] } )`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ? AND status IN ( ?, ? )' )
+		expect( params ).toEqual( [ 1, 'active', 'pending' ] )
+
+	} )
+
+
+	it( 'normalizes whitespace in the string string', () => {
+
+		const [ string, params ] = parameterized`SELECT  *  FROM   users   WHERE   id = ${ 1 }`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ?' )
+		expect( params ).toEqual( [ 1 ] )
+
+	} )
+
+
+	it( 'trims leading and trailing whitespace', () => {
+
+		const [ string, params ] = parameterized`  SELECT * FROM users WHERE id = ${ 1 }  `
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ?' )
+		expect( params ).toEqual( [ 1 ] )
+
+	} )
+
+
+	it( 'skips undefined values', () => {
+
+		// @ts-expect-error negative testing
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id = ${ undefined } AND name = ${ 'John' }`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = AND name = ?' )
+		expect( params ).toEqual( [ 'John' ] )
+
+	} )
+
+
+	it( 'handles boolean values', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE active = ${ true }`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE active = ?' )
+		expect( params ).toEqual( [ true ] )
+
+	} )
+
+
+	it( 'handles numeric values including bigint', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id = ${ 42 } OR count = ${ BigInt( 999999999999 ) }`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ? OR count = ?' )
+		expect( params ).toEqual( [ 42, BigInt( 999999999999 ) ] )
+
+	} )
+
+
+	it( 'handles empty array values', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE id IN (${ [] })`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id IN ()' )
+		expect( params ).toEqual( [] )
+
+	} )
+
+
+	it( 'handles array with single value', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE status IN (${ [ 'active' ] })`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE status IN (?)' )
+		expect( params ).toEqual( [ 'active' ] )
+
+	} )
+
+
+	it( 'handles multiple arrays in a string', () => {
+
+		const [ string, params ] = parameterized`SELECT * FROM users WHERE status IN (${ [ 'active', 'pending' ] }) AND id IN (${ [ 1, 2, 3 ] })`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE status IN (?, ?) AND id IN (?, ?, ?)' )
+		expect( params ).toEqual( [ 'active', 'pending', 1, 2, 3 ] )
+
+	} )
+
+
+	it( 'returns correct tuple structure', () => {
+
+		const result = parameterized`SELECT * FROM users WHERE id = ${ 1 }`
+
+		expect( Array.isArray( result ) ).toBe( true )
+		expect( result.length ).toBe( 2 )
+		expect( typeof result[ 0 ] ).toBe( 'string' )
+		expect( Array.isArray( result[ 1 ] ) ).toBe( true )
+
+	} )
+
+
+	it( 'handles newlines and tabs in template', () => {
+
+		const [ string, params ] = parameterized`
+			SELECT * FROM users
+			WHERE id = ${ 1 }
+		`
+
+		expect( string ).toBe( 'SELECT * FROM users WHERE id = ?' )
+		expect( params ).toEqual( [ 1 ] )
+
+	} )
+
 } )

src/strings.ts

@@ -341,4 +341,74 @@ export const emailDataToString = (
 		searchParams.size > 0 && `?${ searchParams.toString().replace( /\+/g, ' ' ) }`,
 	].filter( Boolean ).join( '' )
 
+}
+
+
+/**
+ * Represents a value that can be used as a parameter in string operations.
+ * 
+ */
+export type ParameterizedValue = string | boolean | number | bigint
+
+
+/**
+ * Represents a parameterized string with its corresponding values.
+ * 
+ * @property {string} 0 - The template string
+ * @property {ParameterizedValue[]} 1 - Array of values to be substituted into the template string
+ */
+export type Parameterized = [ string, ParameterizedValue[] ]
+
+
+/**
+ * Creates a parameterized string with placeholder values.
+ * 
+ * @param strings - The template string parts from a template literal.
+ * @param values - One or more parameter values or arrays of values to be substituted into the template.
+ * @returns A tuple containing the normalized string with `?` placeholders and an array of parameter values.
+ * 
+ * @example
+ * ```ts
+ * const [ string, params ] = parameterized`
+ *  SELECT * FROM users WHERE id = ${ 1 } AND status IN ( ${ [ 'active', 'pending' ] } )
+ * ` )
+ * 
+ * // string: "SELECT * FROM users WHERE id = ? AND status IN ( ?, ? )"
+ * // params: [ 1, 'active', 'pending' ]
+ * ```
+ * 
+ * @remarks
+ * - Whitespace is normalized (multiple spaces reduced to single space, trimmed).
+ * - Undefined values are skipped.
+ * - Array values are expanded into comma-separated placeholders.
+ * - Single values are replaced with a single `?` placeholder.
+ */
+export const parameterized = ( strings: TemplateStringsArray, ...values: ( ParameterizedValue | ParameterizedValue[] )[] ): Parameterized => {
+
+	const params: ParameterizedValue[] = []
+	let text = ''
+
+	strings.forEach( ( string, index ) => {
+		text += string
+
+		if ( index >= values.length ) return
+
+		const value = values[ index ]
+
+		if ( typeof value === 'undefined' ) return
+
+		if ( Array.isArray( value ) ) {
+
+			const placeholders = value.map( () => '?' ).join( ', ' )
+			text += placeholders
+			params.push( ...value )
+			return
+		}
+
+		text += '?'
+		params.push( value )
+
+	} )
+
+	return [ text.replace( /\s+/g, ' ' ).trim(), params ]
 }