fix!: EXPOSED-288 Extend ANY and ALL operators to use ArrayColumnType

Introduce InternalApi annotation and add it to resolveColumnType().
Move other existing annotation classes to dedicated file.

exposed-core/api/exposed-core.api

@@ -1208,6 +1208,9 @@ public final class org/jetbrains/exposed/sql/IntegerColumnType : org/jetbrains/e
 	public synthetic fun valueFromDB (Ljava/lang/Object;)Ljava/lang/Object;
 }
 
+public abstract interface annotation class org/jetbrains/exposed/sql/InternalApi : java/lang/annotation/Annotation {
+}
+
 public final class org/jetbrains/exposed/sql/Intersect : org/jetbrains/exposed/sql/SetOperation {
 	public fun <init> (Lorg/jetbrains/exposed/sql/AbstractQuery;Lorg/jetbrains/exposed/sql/AbstractQuery;)V
 	public fun copy ()Lorg/jetbrains/exposed/sql/Intersect;

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Annotations.kt

@@ -0,0 +1,44 @@
+package org.jetbrains.exposed.sql
+
+/**
+ * API marked with this annotation is experimental.
+ * Any behavior associated with its use is not guaranteed to be stable.
+ */
+@RequiresOptIn(
+    message = "This database migration API is experimental. " +
+        "Its usage must be marked with '@OptIn(org.jetbrains.exposed.sql.ExperimentalDatabaseMigrationApi::class)' " +
+        "or '@org.jetbrains.exposed.sql.ExperimentalDatabaseMigrationApi'."
+)
+@Target(AnnotationTarget.FUNCTION)
+annotation class ExperimentalDatabaseMigrationApi
+
+/**
+ * API marked with this annotation is experimental.
+ * Any behavior associated with its use is not guaranteed to be stable.
+ */
+@RequiresOptIn(
+    message = "This API is experimental and the behavior defined by setting this value to 'true' is now the default. " +
+        "Its usage must be marked with '@OptIn(org.jetbrains.exposed.sql.ExperimentalKeywordApi::class)' " +
+        "or '@org.jetbrains.exposed.sql.ExperimentalKeywordApi'."
+)
+@Target(AnnotationTarget.PROPERTY)
+annotation class ExperimentalKeywordApi
+
+/**
+ * API marked with this annotation is internal and should not be used outside Exposed.
+ * It may be changed or removed in the future without notice.
+ * Using it outside Exposed may result in undefined and unexpected behaviour.
+ */
+@RequiresOptIn(
+    level = RequiresOptIn.Level.ERROR,
+    message = "This API is internal in Exposed and should not be used. It may be changed or removed in the future without notice."
+)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.CONSTRUCTOR,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.PROPERTY_SETTER,
+    AnnotationTarget.TYPEALIAS
+)
+annotation class InternalApi

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/ColumnType.kt

@@ -1114,6 +1114,7 @@ interface JsonColumnMarker {
  *
  * @throws IllegalStateException If no column type mapping is found and a [defaultType] is not provided.
  */
+@InternalApi
 fun <T : Any> resolveColumnType(
     klass: KClass<T>,
     defaultType: ColumnType? = null

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/DatabaseConfig.kt

@@ -141,11 +141,3 @@ class DatabaseConfig private constructor(
         }
     }
 }
-
-@RequiresOptIn(
-    message = "This API is experimental and the behavior defined by setting this value to 'true' is now the default. " +
-        "Its usage must be marked with '@OptIn(org.jetbrains.exposed.sql.ExperimentalKeywordApi::class)' " +
-        "or '@org.jetbrains.exposed.sql.ExperimentalKeywordApi'."
-)
-@Target(AnnotationTarget.PROPERTY)
-annotation class ExperimentalKeywordApi

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Op.kt

@@ -692,8 +692,10 @@ fun decimalLiteral(value: BigDecimal): LiteralOp<BigDecimal> = LiteralOp(Decimal
  *
  * @throws IllegalStateException If no column type mapping is found and a [delegateType] is not provided.
  */
-inline fun <reified T : Any> arrayLiteral(value: List<T>, delegateType: ColumnType? = null): LiteralOp<List<T>> =
-    LiteralOp(ArrayColumnType(delegateType ?: resolveColumnType(T::class)), value)
+inline fun <reified T : Any> arrayLiteral(value: List<T>, delegateType: ColumnType? = null): LiteralOp<List<T>> {
+    @OptIn(InternalApi::class)
+    return LiteralOp(ArrayColumnType(delegateType ?: resolveColumnType(T::class)), value)
+}
 
 // Query Parameters
 
@@ -769,8 +771,10 @@ fun blobParam(value: ExposedBlob, useObjectIdentifier: Boolean = false): Express
  *
  * @throws IllegalStateException If no column type mapping is found and a [delegateType] is not provided.
  */
-inline fun <reified T : Any> arrayParam(value: List<T>, delegateType: ColumnType? = null): Expression<List<T>> =
-    QueryParameter(value, ArrayColumnType(delegateType ?: resolveColumnType(T::class)))
+inline fun <reified T : Any> arrayParam(value: List<T>, delegateType: ColumnType? = null): Expression<List<T>> {
+    @OptIn(InternalApi::class)
+    return QueryParameter(value, ArrayColumnType(delegateType ?: resolveColumnType(T::class)))
+}
 
 // Misc.
 

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/SQLExpressionBuilder.kt

@@ -126,6 +126,7 @@ fun <T> anyFrom(subQuery: AbstractQuery<*>): Op<T> = AllAnyFromSubQueryOp(true,
  */
 inline fun <reified T : Any> anyFrom(array: Array<T>, delegateType: ColumnType? = null): Op<T> {
     // emptyArray() without type info generates ARRAY[]
+    @OptIn(InternalApi::class)
     val columnType = delegateType ?: resolveColumnType(T::class, if (array.isEmpty()) TextColumnType() else null)
     return AllAnyFromArrayOp(true, array, columnType)
 }
@@ -149,6 +150,7 @@ fun <T> allFrom(subQuery: AbstractQuery<*>): Op<T> = AllAnyFromSubQueryOp(false,
  */
 inline fun <reified T : Any> allFrom(array: Array<T>, delegateType: ColumnType? = null): Op<T> {
     // emptyArray() without type info generates ARRAY[]
+    @OptIn(InternalApi::class)
     val columnType = delegateType ?: resolveColumnType(T::class, if (array.isEmpty()) TextColumnType() else null)
     return AllAnyFromArrayOp(false, array, columnType)
 }

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/SchemaUtils.kt

@@ -888,11 +888,3 @@ object SchemaUtils {
         }
     }
 }
-
-@RequiresOptIn(
-    message = "This database migration API is experimental. " +
-        "Its usage must be marked with '@OptIn(org.jetbrains.exposed.sql.ExperimentalDatabaseMigrationApi::class)' " +
-        "or '@org.jetbrains.exposed.sql.ExperimentalDatabaseMigrationApi'."
-)
-@Target(AnnotationTarget.FUNCTION)
-annotation class ExperimentalDatabaseMigrationApi

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Table.kt

@@ -844,8 +844,10 @@ open class Table(name: String = "") : ColumnSet(), DdlAware {
      * when using the PostgreSQL dialect is allowed, but this value will be ignored by the database.
      * @throws IllegalStateException If no column type mapping is found.
      */
-    inline fun <reified T : Any> array(name: String, maximumCardinality: Int? = null): Column<List<T>> =
-        array(name, resolveColumnType(T::class), maximumCardinality)
+    inline fun <reified T : Any> array(name: String, maximumCardinality: Int? = null): Column<List<T>> {
+        @OptIn(InternalApi::class)
+        return array(name, resolveColumnType(T::class), maximumCardinality)
+    }
 
     // Auto-generated values
 

exposed-json/src/main/kotlin/org/jetbrains/exposed/sql/json/JsonFunctions.kt

@@ -44,6 +44,7 @@ inline fun <reified T : Any> ExpressionWithColumnType<*>.extract(
     vararg path: String,
     toScalar: Boolean = true
 ): Extract<T> {
+    @OptIn(InternalApi::class)
     val columnType = resolveColumnType(
         T::class,
         defaultType = JsonColumnType(