Exact DSL draft #6

ustitc · 2023-05-03T19:53:29Z

Usage example can be found in NotBlankTrimmedString in test package.

Decided to keep only one abstraction Exact. It both keeps a constraint and helper functions for creating "exact" type
Chose from instead of create because, imho, it sounds more natural, e.g. NotBlankString.fromOrThrow(str) versus NotBlankString.createOrThrow(str). Don't have a strong opinion here so it can be changed
Made Exact an interface otherwise the clients won't be able to extend from other classes if needed
There are two ways to define an Exact: interface implementation and exact() method call
Exact can be combined via and function like NotBlankString and TrimmedString

ILIYANGERMANOV

Thank you for taking the time to initiate the work @ustits! Overall, great design - I like it 👍
Added a couple of suggestions around:

reducing boilerplate
Arrow.Raise
naming improvements

Please, let me know what you think. The goal is discussion and perfection through iterations and feedback.

src/commonMain/kotlin/arrow.exact/Exact.kt

ILIYANGERMANOV · 2023-05-03T20:17:23Z

src/commonMain/kotlin/arrow.exact/ExactDsl.kt

+  }
+}
+
+fun <A, B> exact(predicate: Predicate<A>, constructor: (A) -> B): Exact<A, B> {


Two things:

I'd suggest switching the argument order like exact(constructor, predicate) so we can do:

companion object : Exact<Int, PositiveInt> by exact(::PositiveInt) { it > 0 }

Do we want exact to work only with predicates? I'm thinking about overloading a version `fun exact(constr: (A) -> B, constraint: (A) -> Either<ExactError, B>)

The benefit of this is that we can define types like NotBlankTrimmedString with much less boilerplate.

companion object : Exact<String, NotBlankTrimmedString> by exact(::NotBlankTrimmedString) { it.trim().takeIf(String::isNotBlank) ?: raise(...) }

On this, @ustits @nomisRev should we better use the new Raise API instead of Either for the method of Exact that must be implemented.

I think having it Raise based makes sense. In that case I would go for:

fun exact(constr: (A) -> B, constraint: Raise<ExactError>.(A) -> B) companion object : Exact<String, NotBlankTrimmedString> by exact(::NotBlankTrimmedString) { ensureNotNull(it.trim().takeIf(String::isNotBlank)) { ... } }

but both should exclude each-other 🤔 They shouldn't conflict with each other if we use OverloadResolutionByLambdaReturnType.

@ILIYANGERMANOV Unfortunately we can't implement it in such a way, kotlin compiler thinks that after { there must be a class body, not a lambda, so eventually there is no difference in arguments order. On the other hand exact can be used not only in delegation but also as regular method call:

fun main() { exact(::NotBlankString) { it.isNotBlank() } }

But it is rather synthetic example, doesn't look like a real use case

@nomisRev I am not quite familiar with Raise api, can you tell me where to look for implementation examples?

Thank you for the explanation @ustits! I did all the code examples from my Fold w/o an actual IDE/compiler - apologies for that! Regarding Raise - I'd recommend:

https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/

KDoc for Raise#raise, Raise#ensure and Raise#ensureNotNull arrow#3038 (I've put some KDoc for Raise with short examples if you're looking for a TL;DR;)

Raise TL;DR;

like throws but type-safe, in order to raise you need a Raise<A> context

to "catch" raise use recover

interoperable with Either

@nomisRev can give you a better explanation and details but that should be enough to get you started

Thanks @ILIYANGERMANOV , can you tell me, am I moving in the right direction? As I understood I need to use recover on the constraint and map the result onto Either. Btw in such scenario probably we don't need a constructor as an argument:

fun <A, B> exact(constraint: Raise<ExactError>.(A) -> B): Exact<A, B> { return object : Exact<A, B> { override fun from(value: A): Either<ExactError, B> { return recover({ constraint(value).right() }) { error -> error.left() } } } }

@ustits yes, it looks good to me! Thank you for making the change :)
A valid example usage would look like this, right?

companion object : Exact<String, NotBlankTrimmedString> by exact({ ensureNotNull(it.trim().takeIf(String::isNotBlank)?.let(::NotBlankTrimmedString)) { ExactError("Cannot be blank!") } })

companion object : Exact<Float, Percent> by exact({ Percent(it.coerceIn(0f, 1f)) })

I like this API a lot! It's a lot simpler when we get rid of the constructor.
The constructor can be required only for the predicate exact case.

@ustits instead of using recover with left and right you can also just use the either block. It works through Raise 😉. TL;DR Raise is a higher-level abstraction that can work over errors of E. So for Either it's just E, but for Option it's for example None or typealias Null = Nothing? for _nullable types`.

return either { constraint(value) }

src/commonMain/kotlin/arrow.exact/ExactError.kt

src/commonTest/kotlin/arrow/exact/Strings.kt

ILIYANGERMANOV · 2023-05-03T21:07:54Z

💡 In a nutshell, we have two types of operations:

validation: a predicate (A) -> Boolean that is:
- safe to compose
- commutative, composition order doesn't matter
- e.g NotBlankString
transformation: mapping (A) -> B:
- order matters
- e.g. TrimmedString

TL;DR;

A type-safe Exact builder pattern
Makes it clear that the order of operations matter

This is an overkill but just sharing for brainstorming purposes.
I'm thinking about creating an additional Exact DSL which makes building complex types easier similarly to the "builder" pattern.

companion object : Exact<String, CustomerId> by exact()
     .mustBe(String::isNotBlank) // predicate
     .transform(String::trim) // transformation
     .transformOrFail { // both
        when {
            it.startsWith("u/") -> User(it.drop(2))
            it.endsWith("@arrow"l -> Admin(it)
            else -> fail("Invalid id: $it")
        }
      }
     .mustBe { ... }
     .transform { it.uppercased() }
     .build(::CustomerId)

ILIYANGERMANOV · 2023-05-03T21:09:33Z

For visibility mentioning #4

nomisRev

Really nice work @ustits 🙌 Awesome to get a community effort going here 😍

I left some nits mostly, and some thoughts but I like everything I saw here.

src/commonMain/kotlin/arrow.exact/Exact.kt

nomisRev · 2023-05-04T09:16:08Z

src/commonMain/kotlin/arrow.exact/Exact.kt

+  fun fromOrThrow(value: A): B {
+    return when (val result = fromOrEither(value)) {


nit: I use expression bodies wherever possible 😁 I feel it makes it more explicit.

src/commonMain/kotlin/arrow.exact/ExactError.kt

nomisRev · 2023-05-04T09:22:05Z

src/commonMain/kotlin/arrow.exact/ExactDsl.kt

+  }
+}
+
+fun <A, B> exact(predicate: Predicate<A>, constructor: (A) -> B): Exact<A, B> {


I think having it Raise based makes sense. In that case I would go for:

fun exact(constr: (A) -> B, constraint: Raise<ExactError>.(A) -> B) companion object : Exact<String, NotBlankTrimmedString> by exact(::NotBlankTrimmedString) { ensureNotNull(it.trim().takeIf(String::isNotBlank)) { ... } }

but both should exclude each-other 🤔 They shouldn't conflict with each other if we use OverloadResolutionByLambdaReturnType.

nomisRev · 2023-05-04T09:27:11Z

@ustits I invited you to the repo, so you can also create branches directly not his repo.

ILIYANGERMANOV

The design is already good! I think we can merge it and build on top of it. @ustits feel free to merge 👍 Great work! 👏

After merging this one, we can start creating small PRs with minor improvements and have discussions inside them.

nomisRev · 2023-05-05T11:53:57Z

Agreed, let's merge this PR 💪 @ustits or @ILIYANGERMANOV can you confirm that you can merge this PR with the proper approvals? Just to know I gave you the correct permissions to the repo 😅

ILIYANGERMANOV · 2023-05-05T12:03:36Z

@nomisRev @ustits I merged it - we have the correct permissions. Wanted to merge it directly because I want to play around and build on top of it - it's more convenient to have it merged instead of doing stacked PRs.

ustitc · 2023-05-05T13:20:32Z

@ILIYANGERMANOV @nomisRev Thanks for the help!

I haven't included changes with Raise, will do a separate PR for this

nomisRev · 2023-05-05T15:08:26Z

Thank you so much @ustits & @ILIYANGERMANOV! 🙌 Super exciting to see this taking shape 😍 🥳

src/commonMain/kotlin/arrow.exact/Exact.kt

Add draft of Exact dsl

0ad87e3

ustitc mentioned this pull request May 3, 2023

[DISCUSSION] High-level scope and idea of Arrow Exact #4

Closed

ILIYANGERMANOV reviewed May 3, 2023

View reviewed changes

ILIYANGERMANOV requested review from serras, nomisRev and pacher May 3, 2023 20:33

nomisRev approved these changes May 4, 2023

View reviewed changes

ILIYANGERMANOV approved these changes May 4, 2023

View reviewed changes

Rename method, add ExactException, bump arrow version

ef67e17

ILIYANGERMANOV merged commit 4473dd6 into arrow-kt:main May 5, 2023

This was referenced May 5, 2023

[DRAFT] Exact Builder Dsl #7

Closed

[DISCUSSION] Exact Core 0.0.1 #8

Merged

CLOVIS-AI reviewed May 14, 2023

View reviewed changes

src/commonMain/kotlin/arrow.exact/Exact.kt Show resolved Hide resolved

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Exact DSL draft #6

Exact DSL draft #6

ustitc commented May 3, 2023

ILIYANGERMANOV left a comment •

edited

Loading

ILIYANGERMANOV May 3, 2023 •

edited

Loading

nomisRev May 4, 2023

ustitc May 4, 2023

ILIYANGERMANOV May 4, 2023 •

edited

Loading

ustitc May 5, 2023

ILIYANGERMANOV May 5, 2023

nomisRev May 5, 2023

ILIYANGERMANOV commented May 3, 2023 •

edited

Loading

ILIYANGERMANOV commented May 3, 2023

nomisRev left a comment

nomisRev May 4, 2023

nomisRev May 4, 2023

nomisRev commented May 4, 2023

ILIYANGERMANOV left a comment

nomisRev commented May 5, 2023

ILIYANGERMANOV commented May 5, 2023

ustitc commented May 5, 2023

nomisRev commented May 5, 2023

		fun fromOrThrow(value: A): B {
		return when (val result = fromOrEither(value)) {

Exact DSL draft #6

Exact DSL draft #6

Conversation

ustitc commented May 3, 2023

ILIYANGERMANOV left a comment • edited Loading

Choose a reason for hiding this comment

ILIYANGERMANOV May 3, 2023 • edited Loading

Choose a reason for hiding this comment

nomisRev May 4, 2023

Choose a reason for hiding this comment

ustitc May 4, 2023

Choose a reason for hiding this comment

ILIYANGERMANOV May 4, 2023 • edited Loading

Choose a reason for hiding this comment

ustitc May 5, 2023

Choose a reason for hiding this comment

ILIYANGERMANOV May 5, 2023

Choose a reason for hiding this comment

nomisRev May 5, 2023

Choose a reason for hiding this comment

ILIYANGERMANOV commented May 3, 2023 • edited Loading

ILIYANGERMANOV commented May 3, 2023

nomisRev left a comment

Choose a reason for hiding this comment

nomisRev May 4, 2023

Choose a reason for hiding this comment

nomisRev May 4, 2023

Choose a reason for hiding this comment

nomisRev commented May 4, 2023

ILIYANGERMANOV left a comment

Choose a reason for hiding this comment

nomisRev commented May 5, 2023

ILIYANGERMANOV commented May 5, 2023

ustitc commented May 5, 2023

nomisRev commented May 5, 2023

ILIYANGERMANOV left a comment •

edited

Loading

ILIYANGERMANOV May 3, 2023 •

edited

Loading

ILIYANGERMANOV May 4, 2023 •

edited

Loading

ILIYANGERMANOV commented May 3, 2023 •

edited

Loading