DaoReturnTypeConverter

@Target(allowedTargets = [AnnotationTarget.FUNCTION])
@Retention(value = AnnotationRetention.BINARY)
public annotation DaoReturnTypeConverter

Marks a function as a DAO function return type converter.

This annotation is used on functions within a converter class (which is registered via the DaoReturnTypeConverters annotation on the Database or Dao annotated definitions).

This function intercepts the result of a DAO function and wraps or transforms it into a custom type (e.g., Result<T>).

The operations parameter is required and defines whether this converter applies to read operations, write operations, or both.

Converter Functions Rules

1. Converters that are suspend functions can only match with suspend DAO functions.

2. Lambda Parameter: The function MUST include a functional parameter (e.g. executeAndConvert), which MUST be a suspend lambda and have at most one androidx.room3.RoomRawQuery parameter.

3. Additional Parameters: The function can have optional parameters for database: RoomDatabase, inTransaction: Boolean and tableNames: List<String>.

Lambda Parameter Rules (executeAndConvert)

The lambda can have a parameter of type androidx.room3.RoomRawQuery to be used if query transformation is needed. The executeAndConvert lambda can return a List<T> (e.g. for a PagingSource) or an Array<T>.

Rules for Generics and Return Types

Generic Use Case:

• If a converter function has a generic type parameter (e.g., <T>), its return type must contain the same generic type parameter by name (e.g., Result<T>).

• The executeAndConvert lambda must return the generic type T (i.e., suspend () -> T).

Non-Generic Use Case:

• If a converter function has no generic type parameter, its return type must have no generic type argument (e.g., Int or Completable).

• The executeAndConvert lambda must return Unit (i.e., suspend () -> Unit).

Multiple Type Arguments:

• When attempting to match a converter with a DAO method's return type, if the DAO method return type has multiple type arguments (e.g., MyResult<T, Error>), only one type argument can be generic, and this single generic argument must match the generic type parameter on the converter function (<T>) at the corresponding position and must match the position of the generic type argument in the return type of the converter function.

Example Signatures

1. Generic Example Use-Case

@DaoReturnTypeConverter([OperationType.READ])
suspend fun <T> convertGeneric(
  database: RoomDatabase,
  tableNames: List<String>,
  executeAndConvert: suspend () -> T
): Result<T> {
  runCatching { executeAndConvert.invoke() }
}

1. Non-Generic Example Use-Case

@DaoReturnTypeConverter([OperationType.WRITE])
suspend fun convertNonGeneric(
  database: RoomDatabase,
  tableNames: List<String>,
  executeAndConvert: suspend () -> Unit
): OperationStatus {
  try {
    executeAndConvert.invoke()
    return OperationStatus.DONE
  } catch(th: Throwable) {
    return OperationStatus.FAILED
  }
}

Summary

public DaoReturnTypeConverter(@NonNull OperationType[] operations)

public final @NonNull OperationType[] getOperations()