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 t

'a t is a stream consisting roughly of a buffer and a means to refill it.

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.