v2.11 Roadmap

[gcanti]

(pretty much a big backporting from v3)

• Deprecation
  • array utils?: (see also Calling Task.traverseArray on a ReadonlyNonEmptyArray returns a ReadonlyArray #1404) to avoid a combinatorial explosion of functions add a single traverseReadonlyArrayWithIndex (and traverseReadonlyArrayWithIndexSeq when makes sense) to all data types and deprecate:
    • traverseArrayWithIndex
    • traverseArray
    • sequenceArray
    • traverseSeqArrayWithIndex
    • traverseSeqArray
    • sequenceSeqArray
  • Array / ReadonlyArray
    • deprecate range, use NonEmptyArray / ReadonlyNonEmptyArray APIs
  • Traversable
    • deprecate sequence?
  • ReadonlyTuple
    • add Tuple2 module and deprecate ReadonlyTuple?
  • Foldable
    • deprecate traverse_?
  • rename APIs that end with M to E: example reduceM -> reduceE
• Internal
  • internal module
• New Feature
  • EitherT
    • add bracket and refactor:
      • IOEither
      • ReaderEither
      • ReaderTaskEither
      • TaskEither
    • add (ref: [Feature Request] Error Handlers for Map Left #1360):
      • orLeft
      • orElseFirst
      • add them to (also orElseFirstW):
        • IOEither
        • ReaderEither
        • ReaderTaskEither
        • TaskEither
  • Witherable
    • add wiltDefault, witherDefault
      • and use them in:
        • Either
        • Option
        • ReadonlyArray
        • ReadonlyMap
        • ReadonlyRecord
  • These
    • add ApT
    • (internal) remove Option dependency
    • add traverseReadonlyNonEmptyArrayWithIndex e traverseReadonlyArrayWithIndex
  • TaskThese
    • add ApT
    • add traverseReadonlyNonEmptyArrayWithIndex e traverseReadonlyArrayWithIndex, traverseReadonlyNonEmptyArrayWithIndexSeq e traverseReadonlyArrayWithIndexSeq
  • function
    • add SK
  • Calling Task.traverseArray on a ReadonlyNonEmptyArray returns a ReadonlyArray #1404
    • Either
    • IO
    • IOEither
    • Option
    • Reader
    • ReaderEither
    • ReaderTask
    • ReaderTaskEither
    • State
    • StateReaderTaskEither
    • Task
    • TaskEither
    • TaskOption
  • add tuple module?
    • move tuple constructor from function
    • add evolve
  • add Predicate module
    • move Predicate type from function
      • change function.getMonoid example accordingly
    • move not from function
  • add Refinement module
    • move Refinement type from function
    • add not, or, and
  • add Endomorphism module
    • move Endomorphism type from function
    • move getEndomorphismSemigroup and rename, getEndomorphismMonoid and rename
  • add FromReader module
    • add fromReaderK (add to ReaderEither, ReaderTask, ReaderTaskEither, StateReaderTaskEither)
    • add chainReaderK (add to ReaderEither, ReaderTask, ReaderTaskEither, StateReaderTaskEither)
    • make sure that the following modules contain ask (derived from FromReader), asks (derived from FromReader), fromReader e FromReader
      • Reader (except fromReader)
      • ReaderEither
      • ReaderTask
      • ReaderTaskEither
      • StateReaderTaskEither
    • StateReaderTaskEither
      • add ask
      • add asks
  • add FromState module
    • add fromStateK (add to StateReaderTaskEither)
    • add chainStateK (add to StateReaderTaskEither)
  • add FromThese module
    • add fromTheseK
  • add void module
    • move semigroupVoid from Semigroup and rename to Semigroup
    • move monoidVoid from Monoid and rename to Monoid
  • struct
    • add evolve
  • function
    • add apply
  • Ord
    • add equals
    • add trivial
  • Eq
    • add fromOrd
  • FromEither
    • (internal) remove Either dependency
    • derive some Either combinators from FromEither
    • add FromEither1
      • add related overload to fromPredicate
      • add related overload to fromEitherK
      • add related overload to chainEitherK
    • Option
      • add FromEither instance
      • derive fromPredicate from FromEither.fromPredicate
      • add fromEitherK (derived form FromEither)
      • add chainEitherK (derived form FromEither)
    • Array
      • add fromEither constructor
      • add FromEither instance
    • ReadonlyArray
      • add fromEither constructor
      • add FromEither instance
  • number
    • add MagmaSub
  • string
    • add toUpperCase
  • Magma
    • add reverse
    • add concatAll
    • add filterSecond, filterFirst
    • add endo
  • Array / ReadonlyArray
    • make isEmpty a custom guard
    • add concat / concatW
    • add match, matchW, matchLeftW, matchRightW (Add Array match function #1427)
    • add fromOption
    • add fromOptionK
    • add fromPredicate (derived form FromEither)
    • add fromEitherK (derived form FromEither)
    • add getUnionSemigroup
    • add getUnionMonoid
    • add getIntersectionSemigroup
    • add getDifferenceMagma
    • deprecate unsafe API?
  • Set / ReadonlySet
    • add getUnionSemigroup
    • add getMonoidSemigroup
    • add getIntersectionSemigroup
    • add getDifferenceMagma
    • add reduceRight
  • NonEmptyArray / ReadonlyNonEmptyArray
    • add concat, concatW
    • add matchLeft, matchRight (NonEmptyArray and ReadonlyNonEmptyArray are missing functions from Array and ReadonlyArray #1420 (comment))
    • add makeBy
    • add modifyHead
    • add updateHead
    • add modifyLast
    • add updateLast
    • add range
    • add replicate
    • add rotate
    • add sortBy
    • add union
    • add uniq
  • ReadonlyMap
    • add union, intersection and difference
    • add getUnionSemigroup
    • add getUnionMonoid
    • add getIntersectionSemigroup
    • add getDifferenceMagma
    • add reduceWithIndex
    • add foldMapWithIndex
    • add reduceRightWithIndex
    • add reduce
    • add foldMap
    • add reduceRight
    • add traverseWithIndex
    • add traverse
    • add wither
    • add wilt
  • ReadonlyRecord
    • add union, intersection and difference
    • add getUnionSemigroup
    • add getUnionMonoid
    • add getIntersectionSemigroup
    • add getDifferenceMagma
    • add Ord constraint to?
      • keys
      • collect
      • toReadonlyArray
      • toUnfoldable
      • reduce
      • foldMap
      • reduceRight
      • reduceWithIndex
      • foldMapWithIndex
      • reduceRightWithIndex
      • traverseWithIndex
  • Alt
    • add altAll
  • Alternative
    • add altAll
  • TaskEither
    • add fromTaskOptionK
    • add chainTaskOptionK

[gcanti]

FYI all 2.11 features can be found in the 3.0.0 branch if you want to take a look.

(or run npm i fp-ts@next if you want to play with the v3 alpha release).

=> any early feedback is greatly appreciated <=

[steida]

I just switched to 2.10.0-rc.6 and everything is ok so far. Only one thing I had to google was option.option to option.Applicative. Great work!

[anthonyjoeseph]

Should the Array and Record modules (not-readonly) get deprecated as well? (Edit: also NonEmptyArray, Map & Set)

[gcanti]

Should the Array and Record modules (not-readonly) get deprecated as well?

I wouldn't go that far, at this point people should already know that in v3 they will be removed and I don't want to cause hundreds of deprecation warnings if you are fine with the mutable modules

[cdimitroulas]

Could we modify the original issue description to have checkboxes so we can easily keep track of what items have been backported already?

I see some work has already started in #1455 but I imagine there will be many more of these PRs coming soon to do the rest of the work (actually there was already #1450 and #1449 as well)

[gcanti]

there will be many more of these PRs coming soon

@cdimitroulas the heavy lifting is already done in the 3.0.0 branch, honestly I'd prefer to backport all those features by myself. Don't get me wrong, I really appreciate the help people is pouring into this version but reviewing n PRs is extremely time consuming for me, I just don't have the bandwidth, I'm sorry :(

[cdimitroulas]

OK no problem!

[cdimitroulas]

Are there items from this roadmap which you think would be suitable for others to help out with? Perhaps if you let us know whether there are any such items so that we can take some of the load off your end that would be easiest then :)

[gcanti]

@cdimitroulas sure, there are some items in the list that are tagged with a question mark:

• array utils?: (see also Calling Task.traverseArray on a ReadonlyNonEmptyArray returns a ReadonlyArray #1404) to avoid a combinatorial explosion of functions add a single traverseReadonlyArrayWithIndex (and traverseReadonlyArrayWithIndexSeq when makes sense) to all data types and deprecate:
  • traverseArrayWithIndex
  • traverseArray
  • sequenceArray
  • traverseSeqArrayWithIndex
  • traverseSeqArray
  • sequenceSeqArray
• Array / ReadonlyArray
  • deprecate unsafe API? (namely unsafeInsertAt, unsafeUpdateAt, unsafeDeleteAt)
• Traversable
  • deprecate sequence? (just use Traversable's traverse)
• ReadonlyTuple
  • add Tuple2 module and deprecate ReadonlyTuple? (perhaps it's not worth it)
• Foldable
  • deprecate traverse_? (just use Traversable's traverse)
• add tuple module? (looks like it's not possible because there's already a Tuple module)

I'm not totally sure about them, they derive from what I did in v3 but I would like to discuss with the community.

Also, when the backporting is over, I would like some help to double check the alignment with v3: perfect alignment (when possible of course) is especially important to make the migration path easier.

[thewilkybarkid]

Only just seen the comments here, will hold off on any more back-porting. 👍

Is there anything that can done in the meantime, especially getting 2.10.0 released? (Seems pretty stable now.)

Also, when the backporting is over, I would like some help to double check the alignment with v3: perfect alignment (when possible of course) is especially important to make the migration path easier.

This is always a great (but complex) approach to take, so thanks. Divergence then back-porting is definitely a tricker approach, but sometimes needed. Do you plan to merge the 2.x branch(es) into 3.0? I noticed there's a lot of non-functionality changes (eg reordering inside modules) which makes the diff far harder to read. I'm more than happy to help out making diffs show just the genuine differences if needed (but won't start without confirmation).

[gcanti]

I noticed there's a lot of non-functionality changes (eg reordering inside modules)

I still haven't found a good way to structure a module. I started with:

• model
• constructors
• guards
• destructors
• combinators
• instances
• utils

and it was fine, but then when I started deriving functions from instances I ended up with a mix:

• model
• constructors
• guards
• destructors
• combinators
• mix of instances, combinators, constructors...
• utils

If we come up with a standand way to organize a module I can try to comply while developing v3, which should result in lesser merge conflicts, WDYT?

[thewilkybarkid]

If we come up with a standand way to organize a module I can try to comply while developing v3, which should result in lesser merge conflicts, WDYT?

It's probably useful to have such a standard, but not sure I know enough on how to group. Sounds like the former option might still make sense, just the derived functions should be positioned by their signature rather than their implementation?

Either way, a module being consistent across branches is probably a more important goal?

[thewilkybarkid]

Just took a look at comparing the HEAD of 2.11 with 3.0.0 to see what type of changes there are which should be backported (outside of generated files).

src/Task.ts looks to have a fair amount of reorganisation, tweaks to documentation (etc @since appears to have changed everywhere) and some changes which haven't been backported yet.
dtslint/ts3.5/Task.ts has moved to dtslint/ts4.1/Task.ts but is unchanged.
test/Task.ts mostly seems to be structural changes in the tests (some reorganisation and added helpers).

I don't know which other modules are in a better/worse state, but it should be possible to closely align them with changes on both sides (though more on 2.11 than 3.0.0).

There look to be other changes on 3.0.0 like adding eslint, but they don't necessarily have to be backported.

[vinassefranche]

Is there something I can do to help with the release of this version?

[gcanti]

@vinassefranche v2.11 is almost ready but these questions are still open.

We may decide to postpone them to v2.12 though.

[vinassefranche]

I don't know if I can help on these. I don't have much input on them. Tell me if you need some code exploration to be done.
I'm fine with waiting for v2.12 to answer them as I'm really waiting for v2.11 but it's your call!

[gcanti]

@vinassefranche 2.11.0-rc.1 released

[kylegoetz]

If the mutable collections are deprecated, does it make sense to drop the "Readonly" prefix on the immutable ones? \

Avoids verbosity, and in FP generally you're defaulting to immutables anyway.

I know I could just import * as NEA from 'fp-ts/ReadonlyNonEmptyArray but I think someone coming to the lib might infer that if ReadonlyX exists, then X must exist as well, and it is mutable.

[mlegenhausen]

@kylegoetz How would you handle the already existing native Array and ReadonlyArray types when following this convention?