# Module `Github.Stream`

The `Stream`

module provides an abstraction to GitHub's paginated endpoints. Stream creation does not initiate any network activity. When requests are made, results are buffered internally. Streams are not mutable.

`type 'a parse`

`= string -> 'a list Lwt.t`

`'a parse`

is the type of functions which extract elements from a paginated response.

`val next : 'a t -> ('a * 'a t) option Monad.t`

`next s`

is the next element of the stream and a stream continuation if one exists. The input stream is not modified. This function offers an efficient, lazy, and uniform means to iterate over ordered API results which may be too numerous to fit into a single request/response pair.

`val map : ('a -> 'b list Monad.t) -> 'a t -> 'b t`

`map f s`

is the lazy stream of`f`

applied to elements of`s`

as they are demanded.

`val fold : ('a -> 'b -> 'a Monad.t) -> 'a -> 'b t -> 'a Monad.t`

`fold f a s`

is the left fold of`f`

over the elements of`s`

with a base value of`a`

.**Warning:**this function may result in*many*successive API transactions.

`val find : ('a -> bool) -> 'a t -> ('a * 'a t) option Monad.t`

`find p s`

is the first value in`s`

satisfying`p`

if one exists and a stream continuation for further ingestion.

`val iter : ('a -> unit Monad.t) -> 'a t -> unit Monad.t`

`iter f s`

is activated after the application of`f`

to each element of`s`

.

`val to_list : 'a t -> 'a list Monad.t`

`to_list s`

is a list with each element of`s`

.**Warning:**this function may result in*many*successive API transactions.

`val of_list : 'a list -> 'a t`

`of_list l`

is a stream with each element of`l`

. Occasionally, it is useful to write interfaces which operate generically on streams.`of_list`

allows you to use list values with those interfaces.

`val poll : 'a t -> 'a t option Monad.t`

`poll stream`

is a stream with items newer than`stream`

's items and will not resolve until any timeouts indicated by GitHub have elapsed. By default, GitHub throttles polling requests to once per minute per URL endpoint.

`val since : 'a t -> Endpoint.Version.t -> 'a t`

`since stream version`

is`stream`

with`version`

but without any other change, i.e. the stream is not reset to its beginning. Used in conjunction with`poll`

,`since`

enables low-cost conditional re-synchronization of local state with GitHub state.

`val version : 'a t -> Endpoint.Version.t option`

`version stream`

is the version of`stream`

if one is known. After any stream element is forced, the stream version will be available unless GitHub violates its API specification.