diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryComposable.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryComposable.kt index b982a2b..f48d292 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryComposable.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryComposable.kt @@ -15,6 +15,15 @@ import soil.query.QueryClient import soil.query.QueryState import soil.query.QueryStatus +/** + * Remember a [InfiniteQueryObject] and subscribes to the query state of [key]. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @param key The [InfiniteQueryKey] for managing [query][soil.query.Query] associated with [id][soil.query.InfiniteQueryId]. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * @return A [InfiniteQueryObject] each the query state changed. + */ @Composable fun rememberInfiniteQuery( key: InfiniteQueryKey, @@ -30,6 +39,16 @@ fun rememberInfiniteQuery( } } +/** + * Remember a [InfiniteQueryObject] and subscribes to the query state of [key]. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @param key The [InfiniteQueryKey] for managing [query][soil.query.Query] associated with [id][soil.query.InfiniteQueryId]. + * @param select A function to select data from [QueryChunks]. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * @return A [InfiniteQueryObject] with selected data each the query state changed. + */ @Composable fun rememberInfiniteQuery( key: InfiniteQueryKey, diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryObject.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryObject.kt index d6d3903..3b0f86a 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryObject.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryObject.kt @@ -9,13 +9,38 @@ import soil.query.QueryFetchStatus import soil.query.QueryModel import soil.query.QueryStatus +/** + * A InfiniteQueryObject represents [QueryModel]s interface for infinite fetching data using a retrieval method known as "infinite scroll." + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + */ @Stable sealed interface InfiniteQueryObject : QueryModel { + + /** + * Refreshes the data. + */ val refresh: suspend () -> Unit + + /** + * Fetches data for the [InfiniteQueryKey][soil.query.InfiniteQueryKey] using the [parameter][loadMoreParam]. + */ val loadMore: suspend (param: S) -> Unit + + /** + * The parameter for next fetching. If null, it means there is no more data to fetch. + */ val loadMoreParam: S? } +/** + * A InfiniteQueryLoadingObject represents the initial loading state of the [InfiniteQueryObject]. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @constructor Creates a [InfiniteQueryLoadingObject]. + */ @Immutable data class InfiniteQueryLoadingObject( override val data: T?, @@ -33,6 +58,13 @@ data class InfiniteQueryLoadingObject( override val status: QueryStatus = QueryStatus.Pending } +/** + * A InfiniteQueryLoadingErrorObject represents the initial loading error state of the [InfiniteQueryObject]. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @constructor Creates a [InfiniteQueryLoadingErrorObject]. + */ @Immutable data class InfiniteQueryLoadingErrorObject( override val data: T?, @@ -50,6 +82,13 @@ data class InfiniteQueryLoadingErrorObject( override val status: QueryStatus = QueryStatus.Failure } +/** + * A InfiniteQuerySuccessObject represents the successful state of the [InfiniteQueryObject]. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @constructor Creates a [InfiniteQuerySuccessObject]. + */ @Immutable data class InfiniteQuerySuccessObject( override val data: T, @@ -67,6 +106,15 @@ data class InfiniteQuerySuccessObject( override val status: QueryStatus = QueryStatus.Success } +/** + * A InfiniteQueryRefreshErrorObject represents the refresh error state of the [InfiniteQueryObject]. + * + * This state is used when the data is successfully retrieved once, but an error occurs during the refresh or additional fetching. + * + * @param T Type of data to retrieve. + * @param S Type of parameter. + * @constructor Creates a [InfiniteQueryRefreshErrorObject]. + */ @Immutable data class InfiniteQueryRefreshErrorObject( override val data: T, diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationComposable.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationComposable.kt index e5f397c..f80f3f0 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationComposable.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationComposable.kt @@ -14,6 +14,15 @@ import soil.query.MutationRef import soil.query.MutationState import soil.query.MutationStatus +/** + * Remember a [MutationObject] and subscribes to the mutation state of [key]. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + * @param key The [MutationKey] for managing [mutation][soil.query.Mutation] associated with [id][soil.query.MutationId]. + * @param client The [MutationClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * @return A [MutationObject] each the mutation state changed. + */ @Composable fun rememberMutation( key: MutationKey, @@ -29,7 +38,6 @@ fun rememberMutation( } } - private fun MutationState.toObject( mutation: MutationRef, ): MutationObject { diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationObject.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationObject.kt index 26b2475..ceefa8b 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationObject.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationObject.kt @@ -8,13 +8,37 @@ import androidx.compose.runtime.Stable import soil.query.MutationModel import soil.query.MutationStatus +/** + * A MutationObject represents [MutationModel]s interface for mutating data. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + */ @Stable sealed interface MutationObject : MutationModel { + + /** + * Mutates the variable. + */ val mutate: suspend (variable: S) -> T + + /** + * Mutates the variable asynchronously. + */ val mutateAsync: suspend (variable: S) -> Unit + + /** + * Resets the mutation state. + */ val reset: suspend () -> Unit } +/** + * A MutationIdleObject represents the initial idle state of the [MutationObject]. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + */ @Immutable data class MutationIdleObject( override val data: T?, @@ -29,6 +53,12 @@ data class MutationIdleObject( override val status: MutationStatus = MutationStatus.Idle } +/** + * A Mutation Loading Object represents the waiting execution result state of the [Mutation Object]. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + */ @Immutable data class MutationLoadingObject( override val data: T?, @@ -43,6 +73,12 @@ data class MutationLoadingObject( override val status: MutationStatus = MutationStatus.Pending } +/** + * A MutationErrorObject represents the error state of the [MutationObject]. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + */ @Immutable data class MutationErrorObject( override val data: T?, @@ -57,6 +93,12 @@ data class MutationErrorObject( override val status: MutationStatus = MutationStatus.Failure } +/** + * A MutationSuccessObject represents the successful state of the [MutationObject]. + * + * @param T Type of the return value from the mutation. + * @param S Type of the variable to be mutated. + */ @Immutable data class MutationSuccessObject( override val data: T, diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryComposable.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryComposable.kt index dfd503b..480cf53 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryComposable.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryComposable.kt @@ -14,6 +14,14 @@ import soil.query.QueryRef import soil.query.QueryState import soil.query.QueryStatus +/** + * Remember a [QueryObject] and subscribes to the query state of [key]. + * + * @param T Type of data to retrieve. + * @param key The [QueryKey] for managing [query][soil.query.Query]. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * @return A [QueryObject] each the query state changed. + */ @Composable fun rememberQuery( key: QueryKey, @@ -29,6 +37,16 @@ fun rememberQuery( } } +/** + * Remember a [QueryObject] and subscribes to the query state of [key]. + * + * @param T Type of data to retrieve. + * @param U Type of selected data. + * @param key The [QueryKey] for managing [query][soil.query.Query]. + * @param select A function to select data from [T]. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * @return A [QueryObject] with selected data each the query state changed. + */ @Composable fun rememberQuery( key: QueryKey, diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryObject.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryObject.kt index 53d220c..6532c07 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryObject.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryObject.kt @@ -10,11 +10,25 @@ import soil.query.QueryModel import soil.query.QueryStatus +/** + * A QueryObject represents [QueryModel]s interface for fetching data. + * + * @param T Type of data to retrieve. + */ @Stable sealed interface QueryObject : QueryModel { + + /** + * Refreshes the data. + */ val refresh: suspend () -> Unit } +/** + * A QueryIdleObject represents the initial loading state of the [QueryObject]. + * + * @param T Type of data to retrieve. + */ @Immutable data class QueryLoadingObject( override val data: T?, @@ -30,6 +44,11 @@ data class QueryLoadingObject( override val status: QueryStatus = QueryStatus.Pending } +/** + * A QueryLoadingErrorObject represents the initial loading error state of the [QueryObject]. + * + * @param T Type of data to retrieve. + */ @Immutable data class QueryLoadingErrorObject( override val data: T?, @@ -45,6 +64,11 @@ data class QueryLoadingErrorObject( override val status: QueryStatus = QueryStatus.Failure } +/** + * A QuerySuccessObject represents the successful state of the [QueryObject]. + * + * @param T Type of data to retrieve. + */ @Immutable data class QuerySuccessObject( override val data: T, @@ -60,6 +84,14 @@ data class QuerySuccessObject( override val status: QueryStatus = QueryStatus.Success } +/** + * A QueryRefreshErrorObject represents the refresh error state of the [QueryObject]. + * + * This state is used when the data is successfully retrieved once, but an error occurs during the refresh. + * + * @param T Type of data to retrieve. + * @constructor Creates a [QueryRefreshErrorObject]. + */ @Immutable data class QueryRefreshErrorObject( override val data: T, diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/SwrClientProvider.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/SwrClientProvider.kt index b0df7d8..886abb0 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/SwrClientProvider.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/SwrClientProvider.kt @@ -10,6 +10,12 @@ import androidx.compose.runtime.staticCompositionLocalOf import soil.query.SwrClient import soil.query.internal.uuid +/** + * Provides a [SwrClient] to the [content] over [LocalSwrClient] + * + * @param client Applying to [LocalSwrClient]. + * @param content The content under the [CompositionLocalProvider]. + */ @Composable fun SwrClientProvider( client: SwrClient, @@ -27,6 +33,9 @@ fun SwrClientProvider( } } +/** + * CompositionLocal for [SwrClient]. + */ val LocalSwrClient = staticCompositionLocalOf { error("CompositionLocal 'SwrClient' not present") } diff --git a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/Util.kt b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/Util.kt index 3395a51..295f25f 100644 --- a/soil-query-compose/src/commonMain/kotlin/soil/query/compose/Util.kt +++ b/soil-query-compose/src/commonMain/kotlin/soil/query/compose/Util.kt @@ -8,14 +8,22 @@ import androidx.compose.runtime.LaunchedEffect import androidx.compose.runtime.remember import kotlinx.coroutines.flow.launchIn import soil.query.InfiniteQueryKey +import soil.query.MutationClient import soil.query.MutationKey +import soil.query.QueryClient import soil.query.QueryKey import soil.query.ResumeQueriesFilter import soil.query.SwrClient - typealias QueriesErrorReset = () -> Unit +/** + * Remember a [QueriesErrorReset] to resume all queries with [filter] matched. + * + * @param filter The filter to match queries. + * @param client The [SwrClient] to resume queries. By default, it uses the [LocalSwrClient]. + * @return A [QueriesErrorReset] to resume queries. + */ @Composable fun rememberQueriesErrorReset( filter: ResumeQueriesFilter = remember { ResumeQueriesFilter(predicate = { it.isFailure }) }, @@ -27,9 +35,20 @@ fun rememberQueriesErrorReset( return reset } +/** + * Keep the query alive. + * + * Normally, a query stays active only when there are one or more references to it. + * This function is useful when you want to keep the query active for some reason even if it's not directly needed. + * For example, it can prevent data for a related query from becoming inactive, moving out of cache over time, such as when transitioning to a previous screen. + * + * @param key The [QueryKey] to keep alive. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + */ @Composable fun KeepAlive( key: QueryKey<*>, + // TODO Use QueryClient instead of SwrClient client: SwrClient = LocalSwrClient.current ) { val query = remember(key) { client.getQuery(key) } @@ -38,9 +57,18 @@ fun KeepAlive( } } +/** + * Keep the infinite query alive. + * + * @param key The [InfiniteQueryKey] to keep alive. + * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * + * @see KeepAlive + */ @Composable fun KeepAlive( key: InfiniteQueryKey<*, *>, + // TODO Use QueryClient instead of SwrClient client: SwrClient = LocalSwrClient.current ) { val query = remember(key) { client.getInfiniteQuery(key) } @@ -49,9 +77,18 @@ fun KeepAlive( } } +/** + * Keep the mutation alive. + * + * @param key The [MutationKey] to keep alive. + * @param client The [MutationClient] to resolve [key]. By default, it uses the [LocalSwrClient]. + * + * @see KeepAlive + */ @Composable fun KeepAlive( key: MutationKey<*, *>, + // TODO Use MutationClient instead of SwrClient client: SwrClient = LocalSwrClient.current ) { val query = remember(key) { client.getMutation(key) }