Prepare for v0.2.0 (#4)

[v0.2.0] Enabled bool and inline lambda invoke

- Add boolean for enabled, removing contract extension. This is in favor
of java users, since kotlin ones already have sealed-class usage +
reactive one. Still, kotlin ones can use the property altough they are
losing contract for type inference (not a big deal since the existence
of sealed classes + reactive ones)
- Add examples in all documentations
- Add invoke companion operator to create lambda inlined providers
- Remove both creational methods in favor of a single overloaded one

Author: saantiaguilera

README.md

@@ -72,8 +72,8 @@ class RepositoryProvider(private val repository: RepositoryApi) : FeatureFlagPro
 
     override fun provide(feature: FeatureFlag): FeatureFlagResult {
         return repository.getFeatures()[feature.key]
-            ?.let { createExistingResult(it) } // If not null, we return an existing result with it's value 
-            ?: createMissingResult(feature.value) // If null we return the default value
+            ?.let { FeatureFlagResult.create(it) } // If not null, we return an existing result with it's value 
+            ?: FeatureFlagResult.create(feature.value, exists = false) // If null we return the default value
     }
 }
 ```
@@ -133,7 +133,7 @@ fun navigateHome(featureFlagProvider: FeatureFlagProvider) {
 fun navigateHome(featureFlagProvider: FeatureFlagProvider) {
     val result = featureFlagProvider.provide(FeatureCatalog.HomeV2)
 
-    if (result.isEnabled()) {
+    if (result.enabled) {
         // Navigate to home v2
     } else {
         // Navigate to home v1
@@ -171,6 +171,28 @@ fun navigateHome(featureFlagProvider: FeatureFlagProvider) {
 }
 ```
 
+### Tech FAQ
+
+#### Why isn't a simple interface with isFeatureEnabled and hasFeature?
+
+Because we would need 2 access to the provider on any request (we want to **always** know first if 
+it exists). There are no specifications on how the provider should retrieve a flag, hence we want
+to make the least possible calls per request. The feature of knowing (optionally) if a flag exists
+at the provider can easily be achieved with a sealed-class or a `Boolean?`.
+
+On a side note, it looks more neat to just ask once for something.
+
+#### Why isn't just a `Boolean` or `Boolean?` the result, instead of a sealed class
+
+While seeing the requirements we saw that there were chances our servers didn't have a flag (because
+of developers mistakes or accessing different scopes). We wanted to know about this edge cases,
+but we couldn't do it if the result was a Boolean (what if `false` means it's actually `false`, and not
+missing?).
+
+Still, using a `Boolean?` would be a pain for those who don't care about missing flags. People should 
+always have to validate 3 cases (`null` / `false` / `true`) instead of two. Hence, a sealed class result 
+gives all this advantages (with the only downside of having to use results instead of plain booleans)  
+
 ### Mentions
 
 The API was heavily inspired by the following contents:

docs/0.x/feature-flags/alltypes/index.md

@@ -10,23 +10,21 @@ A Feature Toggle (aka Feature Flags) Kotlin implementation
 
 ##### [com.saantiaguilera.featureflags.FeatureFlag](../com.saantiaguilera.featureflags/-feature-flag/index.md)
 
-data class for defining feature flags. The reason it's not an interface is because a
-feature flag shouldn't contain behaviours nor richer state, as it's solely reason of existence
-is to transfer data.
+Simple data class for defining feature flags.
 
 
 |
 
 ##### [com.saantiaguilera.featureflags.FeatureFlagProvider](../com.saantiaguilera.featureflags/-feature-flag-provider/index.md)
 
-Provider of feature flags.
+Provides responses against requested feature flags, potentially enabling or disabling a feature.
 
 
 |
 
 ##### [com.saantiaguilera.featureflags.FeatureFlagResult](../com.saantiaguilera.featureflags/-feature-flag-result/index.md)
 
-Result of a feature-flag fetch.
+Binary result of a feature-flag provision. It can be either [Enabled](../com.saantiaguilera.featureflags/-feature-flag-result/-enabled/index.md) or [Disabled](../com.saantiaguilera.featureflags/-feature-flag-result/-disabled/index.md).
 
 
 |

docs/0.x/feature-flags/com.saantiaguilera.featureflags.prioritized/-priority-feature-flag-provider/-init-.md

@@ -9,3 +9,39 @@ Priority grouping of feature-flag providers.
 This class will sort providers from a given comparator and one by one look for the given feature.
 If all results are missing types, then the default feature value (missing) will be returned.
 
+Example of a basic multi-prioritized group using static integers for priorities:
+
+```
+// Simple wrapper class for creating providers with an int priority
+class StaticPriorityProvider(
+    private val provider: FeatureFlagProvider,
+    override val priority: Int
+) : FeatureFlagProvider by provider, StaticPriority
+
+// Contract for comparing later priorities based on integers
+interface StaticPriority {
+    val priority: Int
+}
+
+// Comparator that sorts from highest to lowest priorities
+class StaticPriorityComparator : Comparator<StaticPriority> {
+    override fun compare(o1: StaticPriority?, o2: StaticPriority?): Int {
+        val x = o1?.priority ?: 0
+        val y = o2?.priority ?: 0
+        return if (x > y) -1 else if (x == y) 0 else 1
+    }
+}
+
+// Usage:
+fun using() {
+    val provider = PriorityFeatureFlagProvider(
+        listOf(
+            StaticPriorityProvider(yourProviderOne, priorityProviderOne),
+            StaticPriorityProvider(yourProviderTwo, priorityProviderTwo)
+            /* ... */
+            ),
+            StaticPriorityComparator()
+        }
+    )
+```
+

docs/0.x/feature-flags/com.saantiaguilera.featureflags.prioritized/-priority-feature-flag-provider/index.md

@@ -9,6 +9,42 @@ Priority grouping of feature-flag providers.
 This class will sort providers from a given comparator and one by one look for the given feature.
 If all results are missing types, then the default feature value (missing) will be returned.
 
+Example of a basic multi-prioritized group using static integers for priorities:
+
+```
+// Simple wrapper class for creating providers with an int priority
+class StaticPriorityProvider(
+    private val provider: FeatureFlagProvider,
+    override val priority: Int
+) : FeatureFlagProvider by provider, StaticPriority
+
+// Contract for comparing later priorities based on integers
+interface StaticPriority {
+    val priority: Int
+}
+
+// Comparator that sorts from highest to lowest priorities
+class StaticPriorityComparator : Comparator<StaticPriority> {
+    override fun compare(o1: StaticPriority?, o2: StaticPriority?): Int {
+        val x = o1?.priority ?: 0
+        val y = o2?.priority ?: 0
+        return if (x > y) -1 else if (x == y) 0 else 1
+    }
+}
+
+// Usage:
+fun using() {
+    val provider = PriorityFeatureFlagProvider(
+        listOf(
+            StaticPriorityProvider(yourProviderOne, priorityProviderOne),
+            StaticPriorityProvider(yourProviderTwo, priorityProviderTwo)
+            /* ... */
+            ),
+            StaticPriorityComparator()
+        }
+    )
+```
+
 ### Constructors
 
 | Name | Summary |

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag-provider/index.md

@@ -4,26 +4,76 @@
 
 `interface FeatureFlagProvider`
 
-Provider of feature flags.
+Provides responses against requested feature flags, potentially enabling or disabling a feature.
 
-There are no restrictions upon how to fetch the data, this can be an underlying cache, api-call,
-firebase remote config, shared-prefs, AB Test, etc. As long as it can return the state of a
-flag, it's ok.
+There are no restrictions upon how to fetch the available features, this can be an underlying
+cache, api-call, firebase remote config, shared-prefs, AB Test, etc. As long as it can return
+the state of a flag, it's ok.
+
+Basic example
+
+```
+val provider = FeatureFlagProvider { feature ->
+    // check if the feature is enabled or not.
+}
+```
+
+If a provider doesn't have the requested feature, it should respond with a missing one using
+[FeatureFlagResult.create](../-feature-flag-result/create.md) (specifying as a second parameter that it doesn't)
+
+```
+val provider = FeatureFlagProvider { feature ->
+    if (!/* check feature existence */) {
+         // feature.value is the default provided value. We should also denote it doesn't exists.
+         return FeatureFlagResult.create(feature.value, exists = false)
+     }
+
+     // If the feature exists. return it from somewhere
+     return FeatureFlagResult.create(/* get if the feature is enabled / disabled */)
+```
 
 On a more complex situation, you can create multi-providers such as
 [com.saantiaguilera.featureflags.prioritized.PriorityFeatureFlagProvider](../../com.saantiaguilera.featureflags.prioritized/-priority-feature-flag-provider/index.md) that will, whilst
 abiding this contract, group a lot of providers with a given decision-rule (in this case,
 sorting by priority).
 You can also provide state into providers. Eg. If you have flags that depend on Users,
 because you are performing an AB Test / are bound to it, you can create a custom provider
-that constructs with a "User" (or know how to retrieve it) and use it.
+that constructs with a "User" (or know how to retrieve it) and react from it.
+
+Example:
+
+```
+class UserBasedProvider(
+    private val userRepository: UserRepository,
+    private val flagsRepository: MyFlagsRepository
+) : FeatureFlagProvider {
+    override fun provide(feature: FeatureFlag): FeatureFlagResult {
+        // Somewhere to get the current user from.
+        val user = userRepository.getCurrentUser()
+        // Somewhere to get the flags based on this user from.
+        val flagsForUser = flagsRepository.getFlagsForUser(user)
+
+        // Simple lookup of a map
+        return flagsForUser.find { it.key == feature.key }
+            ?.value?.let { FeatureFlagResult.create(it) }
+            ?: FeatureFlagResult.create(feature.value, exists = false)
+        }
+    }
+}
+```
 
 ### Functions
 
 | Name | Summary |
 |---|---|
 | [provide](provide.md) | Provide for the given feature a result.`abstract fun provide(feature: `[`FeatureFlag`](../-feature-flag/index.md)`): `[`FeatureFlagResult`](../-feature-flag-result/index.md) |
 
+### Companion Object Functions
+
+| Name | Summary |
+|---|---|
+| [invoke](invoke.md) | Constructs a provider for a lambda. This compact syntax is most useful for inline providers.`operator fun invoke(block: (feature: `[`FeatureFlag`](../-feature-flag/index.md)`) -> `[`FeatureFlagResult`](../-feature-flag-result/index.md)`): `[`FeatureFlagProvider`](./index.md) |
+
 ### Inheritors
 
 | Name | Summary |

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag-provider/invoke.md

@@ -0,0 +1,15 @@
+[feature-flags](../../index.md) / [com.saantiaguilera.featureflags](../index.md) / [FeatureFlagProvider](index.md) / [invoke](./invoke.md)
+
+# invoke
+
+`operator inline fun invoke(crossinline block: (feature: `[`FeatureFlag`](../-feature-flag/index.md)`) -> `[`FeatureFlagResult`](../-feature-flag-result/index.md)`): `[`FeatureFlagProvider`](index.md)
+
+Constructs a provider for a lambda. This compact syntax is most useful for inline
+providers.
+
+```
+val provider = FeatureFlagProvider { feature: FeatureFlag ->
+    // Provide a result accordingly.
+}
+```
+

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag-result/create.md

@@ -0,0 +1,16 @@
+[feature-flags](../../index.md) / [com.saantiaguilera.featureflags](../index.md) / [FeatureFlagResult](index.md) / [create](./create.md)
+
+# create
+
+`@JvmStatic @JvmOverloads fun create(value: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`, exists: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)` = true): `[`FeatureFlagResult`](index.md)
+
+Create a result from a given value.
+
+This is a shortcut to using [Enabled.Existing](-enabled/-existing.md) or [Disabled.Existing](-disabled/-existing.md) depending on the
+input.
+
+By default, the result will be existing. You can specify as a second optional parameter
+if it wasn't found (hence, it was missing at the provider)
+This will also be a shortcut to using [Enabled.Missing](-enabled/-missing.md) or [Disabled.Missing](-disabled/-missing.md) if a
+second parameter is specified
+

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag-result/enabled.md

@@ -0,0 +1,5 @@
+[feature-flags](../../index.md) / [com.saantiaguilera.featureflags](../index.md) / [FeatureFlagResult](index.md) / [enabled](./enabled.md)
+
+# enabled
+
+`val enabled: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag-result/index.md

@@ -4,10 +4,10 @@
 
 `sealed class FeatureFlagResult`
 
-Result of a feature-flag fetch.
+Binary result of a feature-flag provision. It can be either [Enabled](-enabled/index.md) or [Disabled](-disabled/index.md).
 
-The result can only be either [Enabled](-enabled/index.md) or [Disabled](-disabled/index.md).
-Still, both could've been found or not, which is denoted through [exists](exists.md).
+On advanced usages, you can also check if it was found at a provider through a depth 2 lookup of
+[Enabled.Existing](-enabled/-existing.md) / [Enabled.Missing](-enabled/-missing.md) or the opposing [Disabled.Existing](-disabled/-existing.md) / [Disabled.Missing](-disabled/-missing.md)
 
 ### Types
 
@@ -20,13 +20,19 @@ Still, both could've been found or not, which is denoted through [exists](exists
 
 | Name | Summary |
 |---|---|
+| [enabled](enabled.md) | `val enabled: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) |
 | [exists](exists.md) | `open val exists: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) |
 
+### Companion Object Functions
+
+| Name | Summary |
+|---|---|
+| [create](create.md) | Create a result from a given value.`fun create(value: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`, exists: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)` = true): `[`FeatureFlagResult`](./index.md) |
+
 ### Extension Functions
 
 | Name | Summary |
 |---|---|
-| [isEnabled](../is-enabled.md) | Convenience method for checking if the feature is enabled, regardless of missing / existing in the provider.`fun `[`FeatureFlagResult`](./index.md)`.isEnabled(): `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) |
 | [onDisabled](../on-disabled.md) | Performs the given [action](../on-disabled.md#com.saantiaguilera.featureflags$onDisabled(com.saantiaguilera.featureflags.FeatureFlagResult, kotlin.Function1((com.saantiaguilera.featureflags.FeatureFlagResult.Disabled, kotlin.Unit)))/action) if this instance represents [disable](-disabled/index.md). Returns the original `FeatureFlagResult` unchanged.`fun `[`FeatureFlagResult`](./index.md)`.onDisabled(action: (result: Disabled) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`FeatureFlagResult`](./index.md) |
 | [onEnabled](../on-enabled.md) | Performs the given [action](../on-enabled.md#com.saantiaguilera.featureflags$onEnabled(com.saantiaguilera.featureflags.FeatureFlagResult, kotlin.Function1((com.saantiaguilera.featureflags.FeatureFlagResult.Enabled, kotlin.Unit)))/action) if this instance represents [enabled](-enabled/index.md). Returns the original `FeatureFlagResult` unchanged.`fun `[`FeatureFlagResult`](./index.md)`.onEnabled(action: (result: Enabled) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`FeatureFlagResult`](./index.md) |
 | [onMissing](../on-missing.md) | Performs the given [action](../on-missing.md#com.saantiaguilera.featureflags$onMissing(com.saantiaguilera.featureflags.FeatureFlagResult, kotlin.Function1((com.saantiaguilera.featureflags.FeatureFlagResult, kotlin.Unit)))/action) if this instance is a not existing queried feature. Returns the original `FeatureFlagResult` unchanged.`fun `[`FeatureFlagResult`](./index.md)`.onMissing(action: (result: `[`FeatureFlagResult`](./index.md)`) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`FeatureFlagResult`](./index.md) |

docs/0.x/feature-flags/com.saantiaguilera.featureflags/-feature-flag/-init-.md

@@ -4,9 +4,19 @@
 
 `FeatureFlag(key: `[`String`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`, value: `[`Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)`, usage: `[`String`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`)`
 
-data class for defining feature flags. The reason it's not an interface is because a
-feature flag shouldn't contain behaviours nor richer state, as it's solely reason of existence
-is to transfer data.
+Simple data class for defining feature flags.
 
 This definition is based on the [flag](https://golang.org/pkg/flag) package definition.
 
+Example:
+
+```
+object PaymentsFeatureCatalog {
+    val enableVisaPayments = FeatureFlag(
+        "feature.payments.cards.visa",
+        false,
+        "Denotes the user should be able to make payments using VISA cards"
+    )
+}
+```
+