Add support to custom reusable SQL fragments that the returning value can be optional or required depending on the provided arguments

Author: juanluispaz

docs/queries/sql-fragments.md

@@ -55,7 +55,7 @@ class DBConnection extends PostgreSqlConnection<'DBConnection'> {
 }
 ```
 
-You will define the function `bitwiseShiftLeft` that receives two `int` as argument and returns an `int`; this arguments can be numbers or elements in the database that represents integer numbers. If you create the argument using the function `valueArg` instead of the `arg` function, the defined function only will accept values but not elements of the database. You can use the defined function as a regular database function in your query.
+You will define the function `bitwiseShiftLeft` that receives two `int` as argument and returns an `int`; these arguments can be numbers or elements in the database that represent integer numbers. If you create the argument using the function `valueArg` instead of the `arg` function, the defined function will accept values only but not database elements. You can use the defined function as a regular database function in your query.
 
 ```ts
 const bitwiseMovements = 1;
@@ -115,7 +115,7 @@ class DBConnection extends PostgreSqlConnection<'DBConnection'> {
 }
 ```
 
-You will define the function `bitwiseShiftLeft` that receives two `int` as argument and returns an `int`; this arguments can be numbers or elements in the database that represents integer numbers. If you create the argument using the function `valueArg` instead of the `arg` function, the defined function only will accept values but not elements of the database. You can use the defined function as a regular database function in your query.
+You will define the function `bitwiseShiftLeft` that receives two `int` as argument and returns an `int`; these arguments can be numbers or elements in the database that represent integer numbers. If you create the argument using the function `valueArg` instead of the `arg` function, the defined function will accept values only but not database elements. You can use the defined function as a regular database function in your query.
 
 ```ts
 const noValue = null
@@ -148,6 +148,60 @@ const companiesUsingCustomFunctionFragment: Promise<{
 }[]>
 ```
 
+## Select with custom reusable SQL fragment (maybe optional)
+
+You can define functions in your connection that create custom reusable SQL fragments that detect if the returned value is required or optional based on the provided arguments, that give you the possibility to do some operations or functions not included in ts-sql-query allowing to have overloaded version where the returned type can be required or optional.
+
+If you define your connection like:
+
+```ts
+import { PostgreSqlConnection } from "ts-sql-query/connections/PostgreSqlConnection";
+
+class DBConnection extends PostgreSqlConnection<'DBConnection'> { 
+
+    bitwiseShiftLeft = this.buildFragmentWithMaybeOptionalArgs(
+        this.arg('int', 'optional'),
+        this.arg('int', 'optional')
+    ).as((left, right) => {
+        // The fragment here is: ${left} << ${right}
+        // Could be another fragment like a function call: myFunction(${left}, ${right})
+        return this.fragmentWithType('int', 'optional').sql`${left} << ${right}`
+    })
+}
+```
+
+You will define the function `bitwiseShiftLeft` that receives two `int` as argument and returns an `int`; these arguments can be numbers or elements in the database that represent integer numbers. If you create the argument using the function `valueArg` instead of the `arg` function, the defined function will accept values only but not database elements. You can use the defined function as a regular database function in your query. The function will return an optional value if any of the provided arguments when invoked is optional; otherwise, the return type will be marked as required. **Note**: All arguments that can be optional must be marked as optional; the return fragment must be marked as optional.
+
+```ts
+const bitwiseMovements = null;
+const multiplier = 2;
+
+const companiesUsingCustomFunctionFragment = connection.selectFrom(tCompany)
+    .select({
+        id: tCompany.id,
+        name: tCompany.name,
+        idMultiplyBy2: connection.bitwiseShiftLeft(tCompany.id, bitwiseMovements)
+    })
+    .executeSelectMany();
+```
+
+The executed query is:
+```sql
+select id as id, name as name, id << $1 as idMultiplyBy2 
+from company
+```
+
+The parameters are: `[ null, 2 ]`
+
+The result type is:
+```tsx
+const companiesUsingCustomFunctionFragment: Promise<{
+    id: number;
+    name: string;
+    idMultiplyBy2?: number;
+}[]>
+```
+
 ## Raw SQL
 
 ts-sql-query offers you to write raw sql to extends and customize the generated queries in several places

docs/supported-operations.md

@@ -796,6 +796,7 @@ interface Connection {
      */
     buildFragmentWithArgs(...argumentDefinitions: Argument[]): FragmentBuilder
     buildFragmentWithArgsIfValue(...argumentDefinitions: Argument[]): FragmentBuilderIfValue
+    buildFragmentWithMaybeOptionalArgs(...argumentDefinitions: Argument[]): FragmentBuilderMaybeOptional
 
     /**
      * Return the same special neutral boolean mark returned by the IfValue functions when there is no value
@@ -884,6 +885,18 @@ interface FragmentBuilderIfValue {
     as(impl: (...args: AnyValueSource[]) => AnyValueSource): (...args: any) => BooleanValueSource
 }
 
+interface FragmentBuilderMaybeOptional {
+    /*
+     * The impl function will receive the proper ValueSource type according to the argument definition.
+     * The nunber of arguments is the same specified in the function buildFragmentWithArgs (up to 5 arguments).
+     * The arguments of the returned function will have the proper parameters type.
+     * The function will return an optional value if any of the provided arguments when invoked is optional; 
+     * otherwise, the return type will be marked as required.
+     * All arguments that can be optional must be marked as optional; the return fragment must be marked as optional.
+     */
+    as(impl: (...args: AnyValueSource[]) => AnyValueSource): (...args: any) => AnyValueSource
+}
+
 interface Sequence<T> {
     nextValue(): T
     currentValue(): T

src/connections/AbstractConnection.ts

@@ -10,7 +10,7 @@ import type { TypeAdapter, DefaultTypeAdapter } from "../TypeAdapter"
 import type { int, double, LocalDate, LocalTime, LocalDateTime, stringInt, stringDouble, uuid } from "ts-extended-types"
 import type { QueryRunner } from "../queryRunners/QueryRunner"
 import type { IConnection } from "../utils/IConnection"
-import type { BooleanFragmentExpression, StringIntFragmentExpression, StringNumberFragmentExpression, IntFragmentExpression, NumberFragmentExpression, StringDoubleFragmentExpression, DoubleFragmentExpression, TypeSafeStringFragmentExpression, StringFragmentExpression, LocalDateFragmentExpression, DateFragmentExpression, LocalTimeFragmentExpression, TimeFragmentExpression, LocalDateTimeFragmentExpression, DateTimeFragmentExpression, EqualableFragmentExpression, ComparableFragmentExpression, FragmentBuilder1TypeSafe, FragmentBuilder0, FragmentBuilder1TypeUnsafe, FragmentBuilder2TypeSafe, FragmentBuilder2TypeUnsafe, FragmentBuilder3TypeSafe, FragmentBuilder3TypeUnsafe, FragmentBuilder4TypeSafe, FragmentBuilder4TypeUnsafe, FragmentBuilder5TypeSafe, FragmentBuilder5TypeUnsafe, FragmentBuilder0IfValue, FragmentBuilder1IfValueTypeSafe, FragmentBuilder1IfValueTypeUnsafe, FragmentBuilder2IfValueTypeSafe, FragmentBuilder2IfValueTypeUnsafe, FragmentBuilder3IfValueTypeSafe, FragmentBuilder3IfValueTypeUnsafe, FragmentBuilder4IfValueTypeSafe, FragmentBuilder4IfValueTypeUnsafe, FragmentBuilder5IfValueTypeSafe, FragmentBuilder5IfValueTypeUnsafe, BigintFragmentExpression, TypeSafeBigintFragmentExpression, TypeSafeUuidFragmentExpression, UuidFragmentExpression, CustomIntFragmentExpression, CustomDoubleFragmentExpression, CustomUuidFragmentExpression, CustomLocalDateFragmentExpression, CustomLocalTimeFragmentExpression, CustomLocalDateTimeFragmentExpression } from "../expressions/fragment"
+import type { BooleanFragmentExpression, StringIntFragmentExpression, StringNumberFragmentExpression, IntFragmentExpression, NumberFragmentExpression, StringDoubleFragmentExpression, DoubleFragmentExpression, TypeSafeStringFragmentExpression, StringFragmentExpression, LocalDateFragmentExpression, DateFragmentExpression, LocalTimeFragmentExpression, TimeFragmentExpression, LocalDateTimeFragmentExpression, DateTimeFragmentExpression, EqualableFragmentExpression, ComparableFragmentExpression, FragmentBuilder1TypeSafe, FragmentBuilder0, FragmentBuilder1TypeUnsafe, FragmentBuilder2TypeSafe, FragmentBuilder2TypeUnsafe, FragmentBuilder3TypeSafe, FragmentBuilder3TypeUnsafe, FragmentBuilder4TypeSafe, FragmentBuilder4TypeUnsafe, FragmentBuilder5TypeSafe, FragmentBuilder5TypeUnsafe, FragmentBuilder0IfValue, FragmentBuilder1IfValueTypeSafe, FragmentBuilder1IfValueTypeUnsafe, FragmentBuilder2IfValueTypeSafe, FragmentBuilder2IfValueTypeUnsafe, FragmentBuilder3IfValueTypeSafe, FragmentBuilder3IfValueTypeUnsafe, FragmentBuilder4IfValueTypeSafe, FragmentBuilder4IfValueTypeUnsafe, FragmentBuilder5IfValueTypeSafe, FragmentBuilder5IfValueTypeUnsafe, BigintFragmentExpression, TypeSafeBigintFragmentExpression, TypeSafeUuidFragmentExpression, UuidFragmentExpression, CustomIntFragmentExpression, CustomDoubleFragmentExpression, CustomUuidFragmentExpression, CustomLocalDateFragmentExpression, CustomLocalTimeFragmentExpression, CustomLocalDateTimeFragmentExpression, FragmentBuilderMaybeOptional0, FragmentBuilderMaybeOptional1TypeSafe, FragmentBuilderMaybeOptional1TypeUnsafe, FragmentBuilderMaybeOptional2TypeSafe, FragmentBuilderMaybeOptional2TypeUnsafe, FragmentBuilderMaybeOptional3TypeSafe, FragmentBuilderMaybeOptional3TypeUnsafe, FragmentBuilderMaybeOptional4TypeSafe, FragmentBuilderMaybeOptional4TypeUnsafe, FragmentBuilderMaybeOptional5TypeSafe, FragmentBuilderMaybeOptional5TypeUnsafe } from "../expressions/fragment"
 import type { AnyDB, TypeSafeDB, TypeUnsafeDB } from "../databases"
 import { InsertQueryBuilder } from "../queryBuilders/InsertQueryBuilder"
 import { UpdateQueryBuilder } from "../queryBuilders/UpdateQueryBuilder"
@@ -20,7 +20,7 @@ import { SqlOperationStatic0ValueSource, SqlOperationStatic1ValueSource, Aggrega
 import { DefaultImpl } from "../expressions/Default"
 import { SelectQueryBuilder } from "../queryBuilders/SelectQueryBuilder"
 import ChainedError from "chained-error"
-import { FragmentQueryBuilder, FragmentFunctionBuilder, FragmentFunctionBuilderIfValue } from "../queryBuilders/FragmentQueryBuilder"
+import { FragmentQueryBuilder, FragmentFunctionBuilder, FragmentFunctionBuilderIfValue, FragmentFunctionBuilderMaybeOptional } from "../queryBuilders/FragmentQueryBuilder"
 import { attachSource, attachTransactionSource } from "../utils/attachSource"
 import { database, outerJoinAlias, outerJoinTableOrView, tableOrView, tableOrViewRef, type, valueSourceTypeName, valueType } from "../utils/symbols"
 import { callDeferredFunctions, callDeferredFunctionsStoppingOnError, isPromise, UnwrapPromiseTuple } from "../utils/PromiseProvider"
@@ -907,6 +907,21 @@ export abstract class AbstractConnection<DB extends AnyDB> implements IConnectio
         return new FragmentFunctionBuilderIfValue(this as any, args) // make this protected fields as public
     }
 
+    protected buildFragmentWithMaybeOptionalArgs(): FragmentBuilderMaybeOptional0<DB>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>>(this: IConnection<TypeSafeDB>, a1: A1): FragmentBuilderMaybeOptional1TypeSafe<DB, A1>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>>(this: IConnection<TypeUnsafeDB>, a1: A1): FragmentBuilderMaybeOptional1TypeUnsafe<DB, A1>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>>(this: IConnection<TypeSafeDB>, a1: A1, a2: A2): FragmentBuilderMaybeOptional2TypeSafe<DB, A1, A2>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>>(this: IConnection<TypeUnsafeDB>, a1: A1, a2: A2): FragmentBuilderMaybeOptional2TypeUnsafe<DB, A1, A2>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>>(this: IConnection<TypeSafeDB>, a1: A1, a2: A2, a3: A3): FragmentBuilderMaybeOptional3TypeSafe<DB, A1, A2, A3>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>>(this: IConnection<TypeUnsafeDB>, a1: A1, a2: A2, a3: A3): FragmentBuilderMaybeOptional3TypeUnsafe<DB, A1, A2, A3>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>, A4 extends Argument<any, any, any, any>>(this: IConnection<TypeSafeDB>, a1: A1, a2: A2, a3: A3, a4: A4): FragmentBuilderMaybeOptional4TypeSafe<DB, A1, A2, A3, A4>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>, A4 extends Argument<any, any, any, any>>(this: IConnection<TypeUnsafeDB>, a1: A1, a2: A2, a3: A3, a4: A4): FragmentBuilderMaybeOptional4TypeUnsafe<DB, A1, A2, A3, A4>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>, A4 extends Argument<any, any, any, any>, A5 extends Argument<any, any, any, any>>(this: IConnection<TypeSafeDB>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5): FragmentBuilderMaybeOptional5TypeSafe<DB, A1, A2, A3, A4, A5>
+    protected buildFragmentWithMaybeOptionalArgs<A1 extends Argument<any, any, any, any>, A2 extends Argument<any, any, any, any>, A3 extends Argument<any, any, any, any>, A4 extends Argument<any, any, any, any>, A5 extends Argument<any, any, any, any>>(this: IConnection<TypeUnsafeDB>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5): FragmentBuilderMaybeOptional5TypeUnsafe<DB, A1, A2, A3, A4, A5>
+    protected buildFragmentWithMaybeOptionalArgs(...args: Argument<any, any, any, any>[]): any {
+        return new FragmentFunctionBuilderMaybeOptional(this as any, args)
+    }
+
     rawFragment(sql: TemplateStringsArray, ...params: Array<ValueSourceOfDB<DB> | IExecutableSelectQuery<DB, any, any, any> | IExecutableInsertQuery<any, any> | IExecutableUpdateQuery<any, any> | IExecutableDeleteQuery<any, any>>): RawFragment<DB> {
         return new RawFragmentImpl(sql, params)
     }

src/examples/documentation/MariaDB-modern.ts

@@ -22,6 +22,15 @@ class DBConnection extends MariaDBConnection<'DBConnection'> {
         return this.fragmentWithType('int', 'required').sql`${left} << ${right}`
     })
 
+    bitwiseShiftLeft2 = this.buildFragmentWithMaybeOptionalArgs(
+        this.arg('int', 'optional'),
+        this.arg('int', 'optional')
+    ).as((left, right) => {
+        // The fragment here is: ${left} << ${right}
+        // Could be another fragment like a function call: myFunction(${left}, ${right})
+        return this.fragmentWithType('int', 'optional').sql`${left} << ${right}`
+    })
+
     valuePlusOneEqualsIfValue = this.buildFragmentWithArgsIfValue(
         this.arg('int', 'required'),
         this.valueArg('int', 'optional')
@@ -531,6 +540,75 @@ async function main() {
         .executeSelectMany()
 
     assertEquals(companiesUsingCustomFunctionFragment, result)
+
+    /* *** Preparation ************************************************************/
+
+    result = [{id: 1, name: 'John'}]
+    expectedResult.push(result)
+    expectedQuery.push(`select id as id, name as name, id << ? as idMultiplyBy2 from company where (id * ?) = (id << ?)`)
+    expectedParams.push(`[null,2,null]`)
+    expectedType.push(`selectManyRows`)
+    
+    /* *** Example ****************************************************************/
+
+    const bitwiseMovements2 = null
+    //const multiplier = 2
+    const companiesUsingCustomFunctionFragment2 = await connection.selectFrom(tCompany)
+        .where(tCompany.id.multiply(multiplier).equals(connection.bitwiseShiftLeft2(tCompany.id, bitwiseMovements2)))
+        .select({
+            id: tCompany.id,
+            name: tCompany.name,
+            idMultiplyBy2: connection.bitwiseShiftLeft2(tCompany.id, bitwiseMovements2)
+        })
+        .executeSelectMany()
+    
+    assertEquals(companiesUsingCustomFunctionFragment2, result)
+
+    /* *** Preparation ************************************************************/
+
+    result = [{id: 1, name: 'John', idMultiplyBy2: 2}]
+    expectedResult.push(result)
+    expectedQuery.push(`select id as id, name as name, id << ? as idMultiplyBy2 from company where (id * ?) = (id << ?)`)
+    expectedParams.push(`[1,2,1]`)
+    expectedType.push(`selectManyRows`)
+    
+    /* *** Example ****************************************************************/
+
+    const bitwiseMovements3 = 1
+    //const multiplier = 2
+    const companiesUsingCustomFunctionFragment3 = await connection.selectFrom(tCompany)
+        .where(tCompany.id.multiply(multiplier).equals(connection.bitwiseShiftLeft2(tCompany.id, bitwiseMovements3)))
+        .select({
+            id: tCompany.id,
+            name: tCompany.name,
+            idMultiplyBy2: connection.bitwiseShiftLeft2(tCompany.id, bitwiseMovements3)
+        })
+        .executeSelectMany()
+    
+    assertEquals(companiesUsingCustomFunctionFragment3, result)
+
+    /* *** Preparation ************************************************************/
+
+    result = [{id: 1, name: 'John'}]
+    expectedResult.push(result)
+    expectedQuery.push(`select id as id, name as name, id << ? as idMultiplyBy2 from company where (id * ?) = (id << ?)`)
+    expectedParams.push(`[1,2,1]`)
+    expectedType.push(`selectManyRows`)
+    
+    /* *** Example ****************************************************************/
+
+    const bitwiseMovements4 = 1
+    //const multiplier = 2
+    const companiesUsingCustomFunctionFragment4 = await connection.selectFrom(tCompany)
+        .where(tCompany.id.multiply(multiplier).equals(connection.bitwiseShiftLeft2(tCompany.id, bitwiseMovements4)))
+        .select({
+            id: tCompany.id,
+            name: tCompany.name,
+            idMultiplyBy2: connection.bitwiseShiftLeft2(tCompany.id.asOptional(), bitwiseMovements4)
+        })
+        .executeSelectMany()
+    
+    assertEquals(companiesUsingCustomFunctionFragment4, result)
 
     /* *** Preparation ************************************************************/