supply-next: Supply-chain interface for basic streaming

[ apache, library, streaming ] [ Propose Tags ]

Next is a supply-chain interface for possibly-finite enumeration. The TerminableStream generalizes Next so that more complex interfaces that incorporate enumeration can use some of these utilities. We offer type aliases Producer, Pipe, and Consumer to conveniently describe vendors and jobs that involve a Next interface.


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.0.0.0, 0.0.1.0, 0.0.1.1, 0.0.1.2
Change log changelog.md
Dependencies base (>=4.16 && <4.18), gambler (>=0.0.0 && <0.1 || >=0.1.0 && <0.2 || >=0.2.0 && <0.3 || >=0.3.0 && <0.4 || >=0.4.0 && <0.5), integer-types (>=0.1.0 && <0.2), quaalude (>=0.0.0 && <0.1), supply-chain (>=0.0.0 && <0.1), transformers (>=0.5.6 && <0.6) [details]
License Apache-2.0
Author Chris Martin
Maintainer Chris Martin, Julie Moronuki
Revised Revision 4 made by chris_martin at 2023-03-08T21:22:46Z
Category Streaming
Home page https://github.com/typeclasses/supply-next
Bug tracker https://github.com/typeclasses/supply-next/issues
Source repo head: git clone git://github.com/typeclasses/supply-next.git
Uploaded by chris_martin at 2023-02-10T07:16:09Z
Distributions
Downloads 177 total (8 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-02-10 [all 1 reports]

Readme for supply-next-0.0.1.2

[back to package description]

The interface

Next is a supply-chain interface for possibly-finite enumeration. It is defined in Next.Interface.Type as follows:

data Next item result =
    (result ~ Step item) => Next
data Step item = Item item | End

It is envisioned some of the utilities in this package may usefully extend to more complex supply-chain interfaces, in which "next" appears as one of many operations in a larger interface. The utilities we provide are therefore polymorphic where possible. The class that permits this polymorphism, defined in Next.Interface.Class, is called TerminableStream.

class TerminableStream item interface | interface -> item where
    next :: interface (Step item)

Type aliases

A producer is a vendor whose downward-facing interface is a stream; it provides items. A consumer is a job whose upward-facing interface is a stream; it consumes items. A pipe is a vendor whose up and down interfaces are both streams, possibly of differing item types; it both consumes and provides items.

type Producer action item         = Vendor (Const Void) (Next item)  action
type Pipe     action item1 item2  = Vendor (Next item1) (Next item2) action
type Consumer action item product = Job    (Next item) action product

The "plus" variants of these aliases are more general in their upstream interfaces and have an additional parameter to describe exactly what the upstream interface is.

type ProducerPlus up action item         =                              Vendor up (Next item)  action
type PipePlus     up action item1 item2  = TerminableStream item1 up => Vendor up (Next item2) action
type ConsumerPlus up action item product = TerminableStream item  up => Job    up action product

The Stream type

Stream is a bonus feature, simply a newtype for Producer. This can help abstract away from the supply-chain library to simplify compiler feedback, and it may be easier to use if you do not need the full generality of the supply-chain library.

newtype Stream action item =
    Stream{ producer :: Producer action item }

Stream has some class instances, but otherwise this library offers no utilities for working with Stream. Instead, work with the Producer type and wrap/unwrap the Stream constructor as needed.

Other libraries

supply-next is one contribution to the supply-chain library ecosystem.

A consumer can be constructed from an EffectfulFold; this type is from the gambler library, which contains a number of common ways to construct folds.

See also foldl, whose FoldM type is the same as EffectfulFold, for more ideas about what kinds of things you can express as folds.

The terms producer, pipe, and consumer are borrowed from pipes. The Stream type is also inspired by the inclusion of the ListT bonus type in pipes.

If you are only using Stream and do not need the general facilities of supply-chain at all, the ListT type in list-transformer may be a more appropriate choice. Consider also that a type as simple as IO (Maybe item) can also suffice to represent an effectful stream.