InsanusMokrassar/MicroUtils
1
0
Fork 0
mirror of https://github.com/InsanusMokrassar/MicroUtils.git synced 2026-03-11 12:52:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

generate docs for a lot of API (test try)

Browse Source
This commit is contained in:
InsanusMokrassar
2026-02-24 18:18:10 +06:00
parent 3df90b1993
commit 4f270d9047
81 changed files with 2519 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/KeyValuesRepo.kt
View File

@@ -6,13 +6,73 @@ import dev.inmo.micro_utils.pagination.utils.doForAllWithNextPaging
import dev.inmo.micro_utils.pagination.utils.getAllWithNextPaging
import kotlinx.coroutines.flow.Flow
/**
* Read part of [KeyValuesRepo] for one-to-many key-value relationships.
* This repository type allows multiple values to be associated with a single key.
*
* @param Key The type used as the key in all search operations
* @param Value The type of values associated with keys
*/
interface ReadKeyValuesRepo<Key, Value> : Repo {
/**
* Retrieves a paginated list of values associated with the given key.
*
* @param k The key to search for
* @param pagination The pagination parameters
* @param reversed Whether to reverse the order of results
* @return A [PaginationResult] containing values associated with the key
*/
suspend fun get(k: Key, pagination: Pagination, reversed: Boolean = false): PaginationResult<Value>
/**
* Retrieves a paginated list of keys.
*
* @param pagination The pagination parameters
* @param reversed Whether to reverse the order of results
* @return A [PaginationResult] containing keys
*/
suspend fun keys(pagination: Pagination, reversed: Boolean = false): PaginationResult<Key>
/**
* Retrieves keys that have the specified value associated with them.
*
* @param v The value to search for
* @param pagination The pagination parameters
* @param reversed Whether to reverse the order of results
* @return A [PaginationResult] containing keys associated with the value
*/
suspend fun keys(v: Value, pagination: Pagination, reversed: Boolean = false): PaginationResult<Key>
/**
* Checks if the specified key exists in the repository.
*
* @param k The key to check
* @return `true` if the key exists, `false` otherwise
*/
suspend fun contains(k: Key): Boolean
/**
* Checks if the specified key-value pair exists in the repository.
*
* @param k The key to check
* @param v The value to check
* @return `true` if the key-value pair exists, `false` otherwise
*/
suspend fun contains(k: Key, v: Value): Boolean
/**
* Returns the count of values associated with the specified key.
*
* @param k The key to count values for
* @return The number of values associated with the key
*/
suspend fun count(k: Key): Long
/**
* Returns the total count of key-value pairs in the repository.
*
* @return The total number of key-value pairs
*/
suspend fun count(): Long
suspend fun getAll(k: Key, reversed: Boolean = false): List<Value> {
@@ -37,39 +97,84 @@ interface ReadKeyValuesRepo<Key, Value> : Repo {
}
}
}
/**
* Type alias for [ReadKeyValuesRepo] emphasizing one-to-many relationships.
*/
typealias ReadOneToManyKeyValueRepo<Key,Value> = ReadKeyValuesRepo<Key, Value>
/**
* Write part of [KeyValuesRepo] for one-to-many key-value relationships.
* Provides methods for adding, removing, and clearing values associated with keys.
*
* @param Key The type used as the key in all write operations
* @param Value The type of values associated with keys
*/
interface WriteKeyValuesRepo<Key, Value> : Repo {
/**
* Flow that emits when a new value is added to a key.
*/
val onNewValue: Flow<Pair<Key, Value>>
/**
* Flow that emits when a value is removed from a key.
*/
val onValueRemoved: Flow<Pair<Key, Value>>
/**
* Flow that emits when all data for a key is cleared.
*/
val onDataCleared: Flow<Key>
/**
* Adds values to the specified keys.
*
* @param toAdd A map of keys to lists of values to add
*/
suspend fun add(toAdd: Map<Key, List<Value>>)
/**
* Removes [Value]s by passed [Key]s without full clear of all data by [Key]
* Removes specific values from keys without clearing all data for those keys.
*
* @param toRemove A map of keys to lists of values to remove
*/
suspend fun remove(toRemove: Map<Key, List<Value>>)
/**
* Removes [v] without full clear of all data by [Key]s with [v]
* Removes a specific value from all keys that contain it, without clearing all data for those keys.
*
* @param v The value to remove
*/
suspend fun removeWithValue(v: Value)
/**
* Fully clear all data by [k]
* Fully clears all data associated with the specified key.
*
* @param k The key to clear
*/
suspend fun clear(k: Key)
/**
* Clear [v] **with** full clear of all data by [Key]s with [v]
* Clears a specific value from all keys and removes those keys if they become empty.
*
* @param v The value to clear
*/
suspend fun clearWithValue(v: Value)
/**
* Sets the values for specified keys, clearing any existing values first.
*
* @param toSet A map of keys to lists of values to set
*/
suspend fun set(toSet: Map<Key, List<Value>>) {
toSet.keys.forEach { key -> clear(key) }
add(toSet)
}
}
/**
* Type alias for [WriteKeyValuesRepo] emphasizing one-to-many relationships.
*/
typealias WriteOneToManyKeyValueRepo<Key,Value> = WriteKeyValuesRepo<Key, Value>
suspend inline fun <Key, Value, REPO : WriteKeyValuesRepo<Key, Value>> REPO.add(

50
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/MapperRepo.kt
View File

@@ -2,28 +2,66 @@ package dev.inmo.micro_utils.repos
import dev.inmo.micro_utils.common.*
/**
* Interface for repositories that provide bidirectional mapping between two sets of key-value types.
* This is useful for adapting repositories to work with different key and value types.
*
* @param FromKey The original key type (inner/source)
* @param FromValue The original value type (inner/source)
* @param ToKey The target key type (outer/destination)
* @param ToValue The target value type (outer/destination)
*/
@Suppress("UNCHECKED_CAST")
interface MapperRepo<FromKey, FromValue, ToKey, ToValue> {
/**
* Provides a mapper for converting keys between inner and outer types.
*/
val keyMapper: SimpleSuspendableMapper<FromKey, ToKey>
get() = simpleSuspendableMapper(
{ it.toInnerKey() },
{ it.toOutKey() }
)
/**
* Provides a mapper for converting values between inner and outer types.
*/
val valueMapper: SimpleSuspendableMapper<FromValue, ToValue>
get() = simpleSuspendableMapper(
{ it.toInnerValue() },
{ it.toOutValue() }
)
/**
* Converts a key from the inner type to the outer type.
*/
suspend fun FromKey.toOutKey() = this as ToKey
/**
* Converts a value from the inner type to the outer type.
*/
suspend fun FromValue.toOutValue() = this as ToValue
/**
* Converts a key from the outer type to the inner type.
*/
suspend fun ToKey.toInnerKey() = this as FromKey
/**
* Converts a value from the outer type to the inner type.
*/
suspend fun ToValue.toInnerValue() = this as FromValue
companion object
}
/**
* Simple implementation of [MapperRepo] that uses provided conversion functions.
*
* @param FromKey The original key type
* @param FromValue The original value type
* @param ToKey The target key type
* @param ToValue The target value type
*/
class SimpleMapperRepo<FromKey, FromValue, ToKey, ToValue>(
private val keyFromToTo: suspend FromKey.() -> ToKey,
private val valueFromToTo: suspend FromValue.() -> ToValue,
@@ -36,6 +74,9 @@ class SimpleMapperRepo<FromKey, FromValue, ToKey, ToValue>(
override suspend fun ToValue.toInnerValue(): FromValue = valueToToFrom()
}
/**
* Factory function for creating a [SimpleMapperRepo] with custom conversion functions.
*/
operator fun <FromKey, FromValue, ToKey, ToValue> MapperRepo.Companion.invoke(
keyFromToTo: suspend FromKey.() -> ToKey,
valueFromToTo: suspend FromValue.() -> ToValue,
@@ -43,6 +84,15 @@ operator fun <FromKey, FromValue, ToKey, ToValue> MapperRepo.Companion.invoke(
valueToToFrom: suspend ToValue.() -> FromValue
) = SimpleMapperRepo(keyFromToTo, valueFromToTo, keyToToFrom, valueToToFrom)
/**
* Creates a [MapperRepo] with optional custom conversion functions.
* By default, uses casting for type conversions.
*
* @param keyFromToTo Function to convert keys from inner to outer type
* @param valueFromToTo Function to convert values from inner to outer type
* @param keyToToFrom Function to convert keys from outer to inner type
* @param valueToToFrom Function to convert values from outer to inner type
*/
inline fun <reified FromKey, reified FromValue, reified ToKey, reified ToValue> mapper(
noinline keyFromToTo: suspend FromKey.() -> ToKey = { this as ToKey },
noinline valueFromToTo: suspend FromValue.() -> ToValue = { this as ToValue },

5
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/Repo.kt
View File

@@ -1,3 +1,8 @@
package dev.inmo.micro_utils.repos
/**
* Base marker interface for all repository types in the MicroUtils library.
* This interface serves as a common ancestor for specialized repository interfaces like
* [ReadCRUDRepo], [WriteCRUDRepo], [ReadKeyValueRepo], [WriteKeyValueRepo], etc.
*/
interface Repo

26
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/diff/CRUDRepoDiff.kt
View File

@@ -7,14 +7,40 @@ import dev.inmo.micro_utils.repos.CRUDRepo
import dev.inmo.micro_utils.repos.ReadCRUDRepo
import dev.inmo.micro_utils.repos.unset
/**
* Computes the difference between this [ReadCRUDRepo] and a map of items.
* Retrieves all items from the repository and compares them with the provided map.
*
* @param Id The type of IDs
* @param Registered The type of objects stored in the repository
* @param other The map to compare against
* @return A [MapDiff] describing added, removed, and updated items
*/
suspend fun <Id, Registered> ReadCRUDRepo<Registered, Id>.diff(other: Map<Id, Registered>): MapDiff<Id, Registered> {
return getAll().diff(other)
}
/**
* Computes the difference between this map and a [ReadCRUDRepo].
* Retrieves all items from the repository and compares them with this map.
*
* @param Id The type of IDs
* @param Registered The type of objects
* @param other The repository to compare against
* @return A [MapDiff] describing added, removed, and updated items
*/
suspend fun <Id, Registered> Map<Id, Registered>.diff(other: ReadCRUDRepo<Registered, Id>): MapDiff<Id, Registered> {
return diff(other.getAll())
}
/**
* Applies the difference between this map and a [ReadCRUDRepo] to this map.
* Modifies this mutable map to match the state of the repository.
*
* @param Id The type of IDs
* @param Registered The type of objects
* @param other The repository to synchronize with
*/
suspend fun <Id, Registered> MutableMap<Id, Registered>.applyDiff(other: ReadCRUDRepo<Registered, Id>) {
applyDiff(diff(other))
}

48
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/mappers/CRUDMappers.kt
View File

@@ -6,6 +6,17 @@ import dev.inmo.micro_utils.repos.*
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
/**
* A [ReadCRUDRepo] wrapper that maps between different key and value types.
* Allows adapting a repository with one type system to work with another type system.
*
* @param FromId The external ID type exposed by this wrapper
* @param FromRegistered The external object type exposed by this wrapper
* @param ToId The internal ID type used by the underlying repository
* @param ToRegistered The internal object type used by the underlying repository
* @param to The underlying repository to wrap
* @param mapper The mapper that defines the bidirectional type conversions
*/
open class MapperReadCRUDRepo<FromId, FromRegistered, ToId, ToRegistered>(
private val to: ReadCRUDRepo<ToRegistered, ToId>,
mapper: MapperRepo<FromId, FromRegistered, ToId, ToRegistered>
@@ -41,11 +52,34 @@ open class MapperReadCRUDRepo<FromId, FromRegistered, ToId, ToRegistered>(
) ?.toInnerValue()
}
/**
* Wraps this [ReadCRUDRepo] with a mapper to expose different key and value types.
*
* @param FromKey The desired external ID type
* @param FromValue The desired external object type
* @param ToKey The current internal ID type
* @param ToValue The current internal object type
* @param mapper The mapper defining the type conversions
* @return A mapped repository with the new type system
*/
@Suppress("NOTHING_TO_INLINE")
inline fun <FromKey, FromValue, ToKey, ToValue> ReadCRUDRepo<ToValue, ToKey>.withMapper(
mapper: MapperRepo<FromKey, FromValue, ToKey, ToValue>
): ReadCRUDRepo<FromValue, FromKey> = MapperReadCRUDRepo(this, mapper)
/**
* Wraps this [ReadCRUDRepo] with custom conversion functions for keys and values.
*
* @param FromKey The desired external ID type
* @param FromValue The desired external object type
* @param ToKey The current internal ID type
* @param ToValue The current internal object type
* @param keyFromToTo Converts external keys to internal keys
* @param valueFromToTo Converts external values to internal values
* @param keyToToFrom Converts internal keys to external keys
* @param valueToToFrom Converts internal values to external values
* @return A mapped repository with the new type system
*/
@Suppress("NOTHING_TO_INLINE")
inline fun <reified FromKey, reified FromValue, reified ToKey, reified ToValue> ReadCRUDRepo<ToValue, ToKey>.withMapper(
noinline keyFromToTo: suspend FromKey.() -> ToKey = { this as ToKey },
@@ -56,6 +90,20 @@ inline fun <reified FromKey, reified FromValue, reified ToKey, reified ToValue>
mapper(keyFromToTo, valueFromToTo, keyToToFrom, valueToToFrom)
)
/**
* A [WriteCRUDRepo] wrapper that maps between different key, value, and input types.
* Allows adapting a repository to work with different type systems for both reading and writing.
*
* @param FromId The external ID type
* @param FromRegistered The external object type for read operations
* @param FromInput The external input type for write operations
* @param ToId The internal ID type
* @param ToRegistered The internal object type for read operations
* @param ToInput The internal input type for write operations
* @param to The underlying repository to wrap
* @param mapper The mapper for keys and values
* @param inputMapper The mapper for input types
*/
open class MapperWriteCRUDRepo<FromId, FromRegistered, FromInput, ToId, ToRegistered, ToInput>(
private val to: WriteCRUDRepo<ToRegistered, ToId, ToInput>,
mapper: MapperRepo<FromId, FromRegistered, ToId, ToRegistered>,

21
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/pagination/CRUDPaginationExtensions.kt
View File

@@ -5,6 +5,17 @@ import dev.inmo.micro_utils.pagination.*
import dev.inmo.micro_utils.pagination.utils.getAllWithNextPaging
import dev.inmo.micro_utils.repos.ReadCRUDRepo
/**
* Retrieves all items from a [ReadCRUDRepo] by iterating through pages starting from the given [pagination].
* Uses the provided [methodCaller] to fetch each page.
*
* @param T The type of objects in the repository
* @param ID The type of IDs in the repository
* @param REPO The specific repository type
* @param pagination The starting pagination parameters
* @param methodCaller A function that fetches a page of results from the repository
* @return A list of all items across all pages
*/
suspend inline fun <T, ID, REPO : ReadCRUDRepo<T, ID>> REPO.getAll(
pagination: Pagination,
@Suppress("REDUNDANT_INLINE_SUSPEND_FUNCTION_TYPE")
@@ -13,6 +24,16 @@ suspend inline fun <T, ID, REPO : ReadCRUDRepo<T, ID>> REPO.getAll(
methodCaller(this, it)
}
/**
* Retrieves all items from a [ReadCRUDRepo] by iterating through all pages.
* Uses [maxPagePagination] to determine the starting pagination and the provided [methodCaller] to fetch each page.
*
* @param T The type of objects in the repository
* @param ID The type of IDs in the repository
* @param REPO The specific repository type
* @param methodCaller A function that fetches a page of results from the repository
* @return A list of all items across all pages
*/
suspend inline fun <T, ID, REPO : ReadCRUDRepo<T, ID>> REPO.getAll(
@Suppress("REDUNDANT_INLINE_SUSPEND_FUNCTION_TYPE")
crossinline methodCaller: suspend REPO.(Pagination) -> PaginationResult<T>

20
repos/common/src/commonMain/kotlin/dev/inmo/micro_utils/repos/pagination/MaxPagePagination.kt
View File

@@ -6,6 +6,26 @@ import dev.inmo.micro_utils.repos.ReadCRUDRepo
import dev.inmo.micro_utils.repos.ReadKeyValueRepo
import dev.inmo.micro_utils.repos.ReadKeyValuesRepo
/**
* Creates a pagination starting from the first page with size equal to the total count of items in this [ReadCRUDRepo].
* This effectively creates a single page containing all items.
*
* @return A [FirstPagePagination] with size equal to the repository count
*/
suspend inline fun ReadCRUDRepo<*, *>.maxPagePagination() = FirstPagePagination(count().toCoercedInt())
/**
* Creates a pagination starting from the first page with size equal to the total count of items in this [ReadKeyValueRepo].
* This effectively creates a single page containing all items.
*
* @return A [FirstPagePagination] with size equal to the repository count
*/
suspend inline fun ReadKeyValueRepo<*, *>.maxPagePagination() = FirstPagePagination(count().toCoercedInt())
/**
* Creates a pagination starting from the first page with size equal to the total count of items in this [ReadKeyValuesRepo].
* This effectively creates a single page containing all items.
*
* @return A [FirstPagePagination] with size equal to the repository count
*/
suspend inline fun ReadKeyValuesRepo<*, *>.maxPagePagination() = FirstPagePagination(count().toCoercedInt())