feat: EXPOSED-388 Support for column type converters

[obabichevjb]

Here is the PR that allows to transform columns from their original types to another.

Transformations could be nested, and could be applied to nullable columns. Transformation of a non-nullable column produces a non-nullable column, and transformation of a nullable column produces a nullable one. Creating nullable columns requires not only types changing, but also set field nullable into true, so still the method nullable() must be used.

We already have transform() for columns on the DAO layer, so I took naming from there (toColumn, toReal methods):

.transform(
    toColumn: (TReal) -> TColumn,
    toReal: (TColumn) -> TReal
)

But probably it's not the perfect variant. I was initially thinking about Target/Source instead of TReal/TColumn respectively. If you prefer the first variant (or have other suggestions) I'd be happy to know. It would be breaking change, but it could be changed for DAO as well if needed.

[obabichevjb]

Updated PR. I tried to check how similar APIs look in other libraries and tried to make it more consistent inside Exposed.

At the current moment I stopped at the variant of type names for transformation as Source/Dest pair; we already have such namings across other methods, and it looks reasonable for generic transformation.

But for more specific cases there are changes:

• When transformation is applied to the column API looks like fun <TColumn : Any, Target : Any> Column<TColumn>.transform(transformer: ColumnTransformer<TColumn, Target>): Column<Target>, so it's clearer where is the original column value, and where is the transformed one
• When transformation applied to already transformed entity field API looks like fun <TColumn : Any?, CurrentTarget : Any?, NextTarget : Any?> EntityFieldWithTransform<TColumn, CurrentTarget>.transform(toCurrentTarget: (NextTarget) -> CurrentTarget, toNextTarget: (CurrentTarget) -> NextTarget): EntityFieldWithTransform<TColumn, NextTarget>. In this case Target is split into CurrentTarget and NextTarget.

Also in all the generic interfaces/methods the source/column type is the first. It was not aligned before.

One more change is the renaming of base transformation class for DSL into ColumnWithTransform, and for DAO into EntityFieldWithTransform.

[obabichevjb]

I would sum up the questions for the discussion:

• Do we need transformation for both DSL and DAO, probably we need it only for DSL?
• Naming:
  • Transformation methods
  • Generic types (first transform and chained transform cases)

Naming

The naming toSource/toTarget most chosen as a most generic to fit dsl column transform, entity column transform, and chained transformations. Another variant I had before (but finally changed) was toColumn/toTransformed, but it was looking a bit weird in the case of chained transformations.

So I made a generic transformation interface and specific parameters for specific cases. That's why transform() methods have toColumn/toTarget for the first call and toCurrentTarget/toNextTarget for the second one. But it looks like it's over complicated and not so meaningful.

The method name toColumn I chose by analogy with IColumnType::valueToDB, so the second variant I liked was to name it like in IColumnType, it could toColumn/fromColumn or valueToColumn/valueFromColumn. One more question in this case would be in the names of generic types. There are also several options (during implementation I wanted several times to write TTransformed but it looks weird..) like TTransformed,TransformedType,TransformedValue/TColumn,ColumnType,ColumnValue. TColumn is a good variant because we already use it in several places, but paired TTransformed looks weird.

From the comment above the variant wrap/unwrap looks interesting. It could be used with types TWrapped/TColumn.

DSL/DAO

I also do not see something blocking from removing DAO's transform. Anyway we could mark it as deprecated and check if somebody complains about the case that could not be covered with DSL's only variant.

Potential reasons to keep both variants I see:

• Using both DSL and DAO layers independently. Exposed allows to mis DSL and DAO in the code, so it's possible that for some cases (like scripting over the database) user may want to have original types, but for application logic transformed, in this case DAO one would be still needed.
• Adding DAO to the existing application. In this case it could be complicated to add transformation to the DSL table, but could be added without problems to the DAO entity.

[obabichevjb]

Updated PR.

Methods toTarget()/toColumn(), toTarget()/toSource() (and original toReal()/toColumn()) were renamed to wrap/unwrap. Generic types Source/Target, TColumn/TReal were renamed to Unwrapped/Wrapped