8000 More ZIO 2.0 Renames by adamgfraser · Pull Request #5229 · zio/zio · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

More ZIO 2.0 Renames #5229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 31 commits into from
Jun 24, 2021
Merged

More ZIO 2.0 Renames #5229

merged 31 commits into from
Jun 24, 2021

Conversation

adamgfraser
Copy link
Contributor
@adamgfraser adamgfraser commented Jun 20, 2021 •
edited
Loading

Resolves #5221. Resolves #5224.

Follow up work on ZIO 2.0 renames. To keep track of things here is a table listing the old and new names of operators. Operating marked as Done are already changed in the series/2.x brach. Operators marked as Pending are done in this PR. Other ones still need to be done and some have proposed changes for discussion.

They fall into a couple of categories:

  • _ suffix variants - we have a lot of these where the return value isn't necessary. In other cases we have used the XYZ versus XYZWith convention but I don't think that really works with a lot of these. For example, neither collectAll nor collectAll_ take an additional argument beyond the collection so calling one of them collectAllWith seems a little weird. We could use a new convention for this.
  • effect constructors - with the existing changes we are moving away from the effectXYZ convention and I think need to do the same thing for other operators. Proposals are below.
  • ZManaged constructors - there are a bunch of ZManaged constructors that fit a little uneasily with the renaming of make and makeExit to bracket and bracketExit.

Also, I am thinking we should change all fromEffect operators (e.g. ZManaged.fromEffect) to fromZIO.

@jdegoes Can you let me know if you are on board with these changes and if you have any ideas on the question marks?

foldM
Data Type Old Operator Name New Operator Name Status
Chunk collectM collectZIO
Chunk collectWhileM collectWhileZIO
Chunk dropWhileM dropWhileZIO
Chunk filterM filterZIO
Chunk findM findZIO
Chunk foldZIO
Chunk foldWhileM foldWhileZIO
Chunk mapAccumM mapAccumZIO
Chunk mapM mapZIO
Chunk mapM_ mapZIODiscard
Chunk mapMPar mapZIOPar
Chunk mapMPar_ mapZIOParDiscard
Chunk takeWhileM takeWhileZIO
Chunk unfoldM unfoldZIO
Exit flatMapM flatMapZIO
Exit mapM mapZIO
Fiber mapM mapZIO
NonEmptyChunk mapAccumM mapAccumZIO
NonEmptyChunk mapM mapZIO
NonEmptyChunk mapMPar mapZIOPar
Runtime unsafeRunAsync_ unsafeRunAsync Pending
Runtime unsafeRunAsync unsafeRunAsyncWith Pending
Schedule addDelayM addDelayZIO
Schedule checkM checkZIO
Schedule contramapM contramapZIO
Schedule delayedM delayedZIO
Schedule dimapM dimapZIO
Schedule foldM foldZIO
Schedule mapM mapZIO
Schedule modifyDelayM modifyDelayZIO
Schedule reconsiderM reconsiderZIO
Schedule untilInputM untilInputZIO
Schedule untilOutputM untilOutputZIO
Schedule whileInputM whileInputZIO
Schedule whileOutputM whileOutputZIO
Schedule collectWhileM collectWhileZIO
Schedule collectUntilM collectUntilZIO
Schedule recurWhileM recurWhileZIO
Schedule recurUntilM recurUntilZIO
ZHub contramapM contramapZIO
ZHub dimapM dimapZIO
ZHub filterInputM filterInputZIO
ZHub filterOuputM filterOutputZIO
ZHub mapM mapZIO
ZIO bracket acquireReleaseWith
ZIO bracket_ acquireRelease
ZIO collectM collectZIO
ZIO filterOrElse filterOrElseWith
ZIO filterOrElse_ filterOrElse
ZIO foldCauseM foldCauseZIO
ZIO foldM foldZIO
ZIO foldTraceM foldTraceZIO
ZIO onExit ensuringWith
ZIO rejectM rejectZIO
ZIO repeatUntilM repeatUntilZIO
ZIO repeatWhileM repeatWhileZIO
ZIO retryUntilM retryUntilZIO
ZIO retryWhileM retryWhileZIO
ZIO someOrElseM someOrElseZIO
ZIO unlessM unlessZIO
ZIO whenM whenZIO
ZIO accessM accessZIO
ZIO collectAll_ collectAllDiscard
ZIO collectAllPar_ collectAllParDiscard
ZIO collectAllParN_ collectAllParNDiscard
ZIO effect attempt Done
ZIO effectAsync async
ZIO effectAsyncInterrupt asyncInterrupt
ZIO effectAsyncM effectAsyncZIO
ZIO effectAsyncMaybe asyncMaybe
ZIO effectBlocking attemptBlocking Pending
ZIO effectBlockingCancelable attemptBlockingCancelable
ZIO effectBlockingIO attemptBlockingIO
ZIO effectBlockingInterrupt attemptBlockingInterrupt
ZIO effectSuspend suspend Done
ZIO effectSuspendMaybeWith suspendMaybeWith
ZIO effectSuspendTotal suspendSucceed Done
ZIO effectSuspendTotalWith suspendSucceedWith Done
ZIO effectSuspendWith suspendWith Done
ZIO effectTotal succeed Done
ZIO foreach_ foreachDiscard
ZIO foreachPar_ foreachParDiscard
ZIO foreachParN_ foreachParNDiscard
ZIO forkAll_ forkAllDiscard
ZIO fromFiberM fromFiberZIO
ZIO fromFunctionM fromFunctionZIO
ZIO ifM ifZIO
ZIO loop_ loopDiscard
ZIO replicateM replicateZIO
ZIO replicateM_ replicateZIODiscard
ZIO unlessM unlessZIO
ZIO whenCaseM whenCaseZIO
ZIO whenM whenZIO
ZIO validate_ validateDiscard
ZIO validatePar_ validateParDiscard
ZLayer fromFunctionM fromFunctionZIO
ZLayer fromFunctionManyM fromFunctionManyZIO
ZLayer fromServiceM fromServiceZIO
ZLayer fromServicesM fromServicesZIO
ZLayer fromServiceManyM fromServiceManyZIO
ZLayer fromServicesManyM fromServicesManyZIO
ZManaged mapM mapZIO
ZManaged onExit ensuringWith
ZManaged onExitFirst ensuringWithFirst
ZManaged use_ useDiscard
ZManaged collectAll_ collectAllDicard
ZManaged collectAllPar_ collectAllParDiscard
ZManaged collectAllParN_ collecrAllParNDiscard
ZManaged foreach_ foreachDiscard
ZManaged foreachPar_ foreachParDiscard
ZManaged foreachParN_ foreachParNDiscard
ZManaged loop_ loopDiscard
ZManaged make acquireReleaseWith
ZManaged make_ acquireRelease
ZManaged makeEffect acquireReleaseAttemptWith
ZManaged makeEffect_ acquireReleaseAttempt
ZManaged makeEffectTotal acquireReleaseSucceedWith
ZManaged makeEffectTotal_ acquireReleaseSucceed
ZManaged makeExit acquireReleaseExitWith
ZManaged makeExit_ acquireReleaseExit
ZManaged makeInterruptible acquireReleaseInterruptibleWith
ZManaged makeInterruptible_ acquireReleaseInterruptible
ZManaged makeReserve fromReservation
ZQueue contramapM contrmapZIO
ZQueue dimapM dimapZIO
ZQueue filterInputM filterInputZIO
ZQueue filterOutputM filterOutputZIO
ZQueue mapM mapZIO
ZRef collectM collectZIO
ZRef contramapM contrmapZIO
ZRef dimapM dimapZIO
ZRef filterInputM filterInputZIO
ZRef filterOutputM filterOutputZIO
ZRef foldAllM foldAllZIO
ZRef foldM foldZIO
ZRef mapM mapZIO
ZRef getAndUpdateM getAndUpdateZIO
ZRef getAndUpdateSomeM getAndUpdateSomeZIO
ZRef modifyM modifyZIO
ZRef modifySomeM modifySomeZIO
ZRef updateM updateZIO
ZRef updateAndGetM updateAndGetZIO
ZRef updateSomeM updateSomeZIO
ZRef updateSomeAndGetM updateSomeAndGetZIO
ZSTM collectM collectSTM
ZSTM filterOrElse_ filterOrElse
ZSTM filterOrElse filterOrElseWith
ZSTM foldM foldSTM
ZSTM rejectM rejectSTM
ZSTM accessM accessSTM
ZSTM foreach_ foreachDiscard
ZSTM fromFunctionM fromFunctionSTM
ZSTM ifM ifSTM
ZSTM loop_ loopDiscard
ZSTM replicateM replicateSTM
ZSTM replicateM_ replicateSTMDiscard
ZSTM unlessM unlessSTM
ZSTM whenM whenSTM
ZSTM whenCaseM whenCaseSTM
TArray collectFirstM collectFirstSTM
TArray countM countSTM
TArray existsM existsSTM
TArray findLastM findLastSTM
TArray findM findSTM
TArray foldM foldSTM
TArray forallM forallSTM
TArray indexWhereM indexWhereSTM
TArray reduceOptionM reduceSTM
TArray transformM transformSTM
TArray updateM updateSTM
TMap foldM foldSTM
TMap transformM transformSTM
TMap transformValuesM transformValuesSTM
TSet foldM foldSTM
TSet transformM transformSTM
ZTRef foldAllM foldAllSTM
ZTRef foldM foldSTM
Take foldM foldZIO
ZChannel mapM mapZIO
ZPipeline mapM mapZIO
ZSink contramapM contramapZIO
ZSink contramapChunksM contramapChunksZIO
ZSink dimapM dimapZIO
ZSink dimapChunksM dimapChunksZIO
ZSink foldChunksM foldChunksZIO
ZSink foldM foldZIO
ZSink mapM mapZIO
ZSink untilOutputM untilOutputZIO
ZSink foldLeftM foldLeftZIO
ZSink foldLeftChunksM foldLeftChunksZIO
ZStream mapM mapZIO
ZTransducer mapM mapZIO
BoolAlgebra mapM mapZIO
Gen mapM mapZIO
TestAspect around aroundWith
TestAspect around_ around
TestAspect aroundAll aroundAllWith
TestAspect aroundAll_ aroundAll

@adamgfraser adamgfraser requested a review from iravid as a code owner June 20, 2021 18:13
@iravid
Copy link
Member
iravid commented Jun 20, 2021 •
edited
Loading

Suggestion for the foreach_ variants - foreachDiscard. Agree that using foreachWith for the current foreach would be awkward. The usage of the _ variants is an optimization after all, as you do fine with foreach and ignoring its result; its usage would therefore be less common and the slightly more awkward name could be a decent tradeoff.

Unfortunately it's not perfect with the other combinators. collectAllDiscard sounds a bit strange :-)

@adamgfraser
Copy link
Contributor Author

Yes. Could also do foreachUnit along similar lines.

@jdegoes
Copy link
Member
jdegoes commented Jun 21, 2021

Just brainstorming on convention here:

  • A with variant could be used if the operator accepts a function to perform the operation "with". All of these cases should be parameterized operators.
  • A "with-less" variant could be used if the operator does not accept a function, and returns useful information.
  • A "discard" variant could be used if the callee returns no useful information.

@adamgfraser
Copy link
Contributor Author

I think that generally makes sense. One potential issue to think about there is bracket and bracket_ since I think that implies bracket should be renamed to bracketWith which is bit unfortunate for such a fundamental operator.

@adamgfraser
Copy link
Contributor Author

Updated the table with the above suggestions if people want to see how everything looks. Seems pretty good other than the bracket / ZManaged variants. For the discard variants could also consider AndDiscard, e.g. collectAllParAndDiscard, which is wordy but maybe is a little more like English than a collection of keywords.

@iravid
Copy link
Member
iravid commented Jun 21, 2021

Re bracket - if we’re going from first principles here then bracket is a totally arbitrary word that’s not directly associated with resources. We could name it tryAcquireWith, for example.

@adamgfraser
Copy link
Contributor Author

I like that idea. Maybe bracket goes to acquireReleaseWith and bracket_ goes to acquireRelease?

@iravid
Copy link
Member
iravid commented Jun 21, 2021

I like acquireRelease 👍🏻 I suggested tryAcquire because that refers to Java's try-with-resources, which has been a helpful analogy in the past, but not sure how important that is.

@jdegoes
Copy link
Member
jdegoes commented Jun 21, 2021

@adamgfraser I like that.

@adamgfraser
Copy link
Contributor Author

@jdegoes Okay updated table with proposals for everything. Can you confirm you are good with the above and then I will make the changes?

@jdegoes
Copy link
Member
jdegoes commented Jun 21, 2021

@adamgfraser This looks mostly perfect.

However, thinking about what we want to do with: fromEffect. It is a convention in some libraries to call such an operator "evaluate" or "execute", e.g. ZStream.eval(putStrLn("Hello")). On the one hand, it breaks with the fromXYZ convention that is common in ZIO libraries for alternate (non-primary) constructors that do data type conversion. On the other hand, it somewhat reflects intention: the intention to embed execution of a ZIO effect inside another effect.

The reason I bring this up now is because it has implications for mapM. If ZStream.fromEffect were renamed to ZStream.eval, then this would imply mapM should be renamed to mapEval. Similarly for all M variants.

The M, like the _, comes from Haskell and does not have an easy explanation.

@adamgfraser
Copy link
Contributor Author

@jdegoes Yeah, I agree about the M. I'm not sure about Eval though because that potentially requires a significant amount of explanation of you want to evaluate it but you don't want to evaluate it now you actually want to evaluate it in the context of this other structure. What about mapZIO?

@iravid
Copy link
Member
iravid commented Jun 21, 2021

+1 for eval

@adamgfraser
Copy link
Contributor Author

Updated the list with the M suffix operators. One other thing to think about there is what we do with data types that have M suffices like RefM.

@jdegoes
Copy link
Member
jdegoes commented Jun 22, 2021

@adamgfraser mapZIO, fromZIO, etc. It can work, is close to our existing naming convention (mapError, etc.) and it also generalizes to effects beyond ZIO, potentially, e.g. ZIO#mapZPure, although I don't see that being common.

@iravid
Copy link
Member
iravid commented Jun 22, 2021

Importing zio.prelude._ could bring in syntax for mapZPure etc; importing zio.interop.cats._ would bring in syntax for mapF. It does generalize better than mapEval.

@adamgfraser
Copy link
Contributor Author

Even in our own code base we use mapM for ZIO and STM right now whereas mapZIO and mapSTM actually seems quite clear.

@adamgfraser
Copy link
Contributor Author

Okay, updated the table with everything. I think we have a plan here. Only thing I think we have not addressed is RefM. I guess in this world it would be RefZIO but that feels a little weird.

@jdegoes
Copy link
Member
jdegoes 6D40 commented Jun 23, 2021

One thing I think we should standardize on:

  • If all the variants of a method end in XYZ, then we should omit XYZ. e.g. if we have 4 methods fooXWith, fooYWith, fooZWith, then we should instead rename them all fooX, fooY, fooZ, because with is not needed for disambiguation.

In words, "disambiguate only when necessary".

@adamgfraser
Copy link
Contributor Author

@jdegoes I think that is a good principle. Is there a place where we are not doing that?

@adamgfraser
Copy link
Contributor Author

In ZIO Test testM and suiteM need alternatives.

@adamgfraser
Copy link
Contributor Author

The testM situation is interesting. In code involving transactions or managed effects a very common pattern is for someone to commit the transaction or use the managed resource so there could be value in having testZIO, testSTM, and so on, but I don't know if the extra couple of characters to write a test would be acceptable.

@jdegoes
Copy link
Member
jdegoes commented Jun 23, 2021

How about a polymorphic test that uses implicits to distinguish between a ZIO value and a non-ZIO value? A "smart test" and "smart assert"?

@adamgfraser
Copy link
Contributor Author

Yes I think we could do something there. Let me work on it. May also make sense to do in a follow up PR.

@jdegoes
Copy link
Member
jdegoes commented Jun 23, 2021

Agreed to do in followup. Let me know when this one is ready!

@adamgfraser
Copy link
Contributor Author

@jdegoes This is ready.

@jdegoes jdegoes merged commit bceea1d into zio:series/2.x Jun 24, 2021
@jdegoes
Copy link
Member
jdegoes commented Jun 24, 2021

A colossal undertaking. Prepares us for the next phase of ZIO. Thank you for your work on this! 🙏

@adamgfraser adamgfraser deleted the 5221 branch June 24, 2021 13:36
This was referenced Jun 24, 2021
Closed
Closed
@ashprakasan ashprakasan mentioned this pull request Jul 1, 2021
Merged
@kluen kluen mentioned this pull request Apr 2, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jdegoes jdegoes jdegoes approved these changes

@iravid iravid Awaiting requested review from iravid

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@adamgfraser @iravid @jdegoes
0