@metreeca/flow - v0.12.0
    Preparing search index...

    Function flat

    Creates a task splicing nested feeds into a single feed, with or without a task opening the feeds to splice, or opens a feed splicing the nested feeds of another feed.

    • Creates a task splicing a feed of feeds into a single feed.

      Nested feeds are consumed one at a time, each fully drained before the next is opened, so items are emitted in source order, those of every nested feed kept together and in their own order; a nested feed contributing nothing simply drops out. Nothing is drawn from a nested feed until its turn comes, so one deferring retrieval until consumption is left untouched until then.

      Nested feeds may be any sync or async iterable, an array, a set or an async generator among them, so a sequence is spliced as is, with no feed opened around it; a string, being iterable, is spliced into its characters.

      Warning

      • Incremental: items are emitted as the nested feeds are drained, so the reported feed runs dry as the source and its nested feeds do; an infinite nested feed starves the ones behind it, which are never opened.
      • Streaming: nested feeds are drained one at a time, none held.
      • Stateless: nested feeds are spliced without state carried across them.

      Type Parameters

      • V

        The type of items carried by the nested feeds

      Returns Task<Awaitables<V>, V>

      A task yielding the items of every nested feed in source order

      await pipe(
        (items([items([1, 2]), items([3, 4])]))
        (flat())
        (toArray())
      );  // [1, 2, 3, 4]

    • Creates a task splicing the feeds another task reports into a single feed.

      Hands the feed drawn from to task and splices the feeds it reports as the overload taking no argument does, so that an item mapped to a feed of its own is expanded in place into the items of that feed. As with that overload, the feeds task reports may be any sync or async iterable, so an item is mapped straight to an array of its expansions, with no feed opened around it.

      Warning

      • Incremental: items are emitted as the reported feeds are drained, so the reported feed runs dry as the source, task and the feeds it reports do; an infinite one starves the feeds behind it, never opened.
      • Streaming: reported feeds are drained one at a time, none held, whatever task holds.
      • Stateless: the splice carries no state across the reported feeds, whatever task carries across the items it draws.
      Note

      task draws from the whole feed, so state it initialises on invocation decides on every item, as it would anywhere else in the pipe. Where a source already carries feeds and a task is to be scoped to each of them, apply it within map(): flat(map(feed => feed(sort()))) orders every nested feed on its own.

      Type Parameters

      • V

        The type of items drawn from the feed

      • R

        The type of items carried by the feeds task reports

      Parameters

      • task: Task<V, Awaitables<R>> & { "[asyncIterator]"?: undefined }

        The task opening the feeds to splice

      Returns Task<V, R>

      A task yielding the items of every feed task reports, in source order

      await pipe(
        (items([1, 2, 3]))
        (flat(map(n => [n, n*10])))
        (toArray())
      );  // [1, 10, 2, 20, 3, 30]

    • Opens a feed splicing the nested feeds of another feed.

      Splices a feed in place, without routing it through a pipe: flat(feed) carries the same items as feed(flat()). Nested feeds are consumed one at a time, each fully drained before the next is opened, so items are emitted in source order, those of every nested feed kept together and in their own order. As with the overload taking no argument, nested feeds may be any sync or async iterable.

      Warning

      • Incremental: items are emitted as the nested feeds are drained, so the opened feed runs dry as feed and its nested feeds do; an infinite nested feed starves the ones behind it, which are never opened.
      • Streaming: nested feeds are drained one at a time, none held.
      • Stateless: nested feeds are spliced without state carried across them.

      Type Parameters

      • V

        The type of items carried by the nested feeds

      Parameters

      • feed: Feed<Awaitables<V>>

        The feed carrying the nested feeds to splice

      Returns Feed<V>

      A feed carrying the items of every nested feed of feed in source order

      await flat(items([items([1, 2]), items([3, 4])]))(toArray());  // [1, 2, 3, 4]

    Settings

    Member Visibility