Unify/Refine Public APIs

[hearnadam]

Unify public APIs:

• Define commonly used names for type parameters

  • eg, S is often used for 'pending effects'

• Define commonly used names for parameters (used in the same context)

• Define commonly used names for methods, as well as the semantic meaning of each

  • get/run

• Document all of these in a shared section to quickly ramp users to Kyo's patterns

[fwbrasil]

/bounty $100

[algora-pbc[bot]]

💎 $100 bounty • Kyo

Steps to solve:

1. Start working: Comment /attempt #317 with your implementation plan
2. Submit work: Create a pull request including /claim #317 in the PR body to claim the bounty
3. Receive payment: 100% of the bounty is received 2-5 days post-reward. Make sure you are eligible for payouts

Thank you for contributing to getkyo/kyo!

Add a bounty • Share on socials

Attempt	Started (GMT+0)	Solution
🟢 @hearnadam	May 21, 2024, 4:41:07 PM	WIP

[hearnadam]

/attempt #317

Algora profile	Completed bounties	Tech	Active attempts	Options
@hearnadam	1 getkyo bounty	Scala, Shell, Rust		Cancel attempt

[hearnadam]

Over the past few weeks I have been thinking about potential encodings. I will first cover type parameters/type names, then we can followup with function naming.

Pending Effects

• Current: S

When describing the pending set of effects to users, I have thought of 3 reasonable conclusions:

• pending Set -> S type parameter

  • Pros: consistent with existing code + not hard to understand
  • Con: without an explicit explanation, it's hard to tell where the S came from.

• Pending set -> P type parameter

  • Pros: users can (hopefully) infer from the language around pending type (<) where this comes from

• Using Effects -> U

  • Pros: more in line with the caprese alternative decisions
  • Cons: using is very overload, eg the Scala 3 using keyword

• My preference: S/P

Errors (Aborts)

• Current: V

I don't think there is much question here from me. Without a doubt, we should reuse what other effect systems use (ZIO, Cats).

• E -> Error

Results (All effects)

• Current: T

I have 3 ideas here:

• A -> historically used for result type in Scala.
  • Pros: f: A => B is extremely common, can easily 'enumerate' type parameters
• T -> more in line with Java developers/libraries, not my choice, but pre-existing
• R -> Result

Dependency Injection (Envs)

• Current: V

• R -> similar to ZIO[R, _, _]

• V -> not sure the reason behind the name, but I don't mind it

• D -> Dependency

[fwbrasil]

pending Set -> S type parameter

I think S has been working well. It indicates that the type is meant as a type-level representation of a set, which I think helps understanding. Also, < is already named "pending" so we'd use the same meaning for two different things if we adopt P.

E -> Error R -> similar to ZIO[R, , ]

ZIO needs different type parameter names because they're used in the same scope since short-circuiting and dependency injection are encoded in the same monad. Kyo is different given that definition of both effects are in completely isolated scopes. I wouldn't be opposed to changing it, though.

R -> Result

I like this option! It seems to improve clarity.

[hearnadam]

ZIO needs different type parameter names because they're used in the same scope since short-circuiting and dependency injection are encoded in the same monad. Kyo is different given that definition of both effects are in completely isolated scopes. I wouldn't be opposed to changing it, though.

Right, I just think for educating all new users, we should attempt to unify the type parameters we use. Instantly, some can infer most of the behaviors of an effect.

[fwbrasil]

@hearnadam would you be ok with reviewing file names as part of this issue as well? We have some with capitalized, some not. It's a mess 🤦🏽