(.require
 [library
  [lux (.except or and)
   ["$" documentation (.only documentation:)]
   [data
    [text (.only \n)
     ["%" \\format (.only format)]]]
   [macro
    ["[0]" template]]]]
 [\\library
  ["[0]" /]])

(documentation: (/.Async it)
  "Represents values produced by asynchronous computations (unlike IO, which is synchronous).")

(documentation: (/.Resolver it)
  (format "The function used to give a value to an async."
          \n "Will signal 'true' if the async has been resolved for the 1st time, 'false' otherwise."))

(documentation: /.resolved
  "Produces an async that has already been resolved to the given value."
  [(resolved value)])

(documentation: /.async
  "Creates a fresh async that has not been resolved yet."
  [(async _)])

(documentation: /.value
  "Polls an async for its value.")

(documentation: /.upon!
  "Executes the given function as soon as the async has been resolved."
  [(upon! function async)])

(documentation: /.resolved?
  "Checks whether an async's value has already been resolved.")

(documentation: /.and
  "Combines the results of both asyncs, in-order."
  [(and left right)])

(documentation: /.or
  (format "Yields the results of whichever async gets resolved first."
          \n "You can tell which one was resolved first through pattern-matching.")
  [(or left right)])

(documentation: /.either
  (format "Yields the results of whichever async gets resolved first."
          \n "You cannot tell which one was resolved first.")
  [(either left right)])

(documentation: /.schedule!
  (format "Runs an I/O computation on its own thread (after a specified delay)."
          \n "Returns an async that will eventually host its result.")
  [(schedule! milli_seconds computation)])

(documentation: /.future
  (format "Runs an I/O computation on its own thread."
          \n "Returns an async that will eventually host its result.")
  [(future computation)])

(documentation: /.after
  "Delivers a value after a certain period has passed."
  [(after milli_seconds value)])

(documentation: /.delay
  "An async that will be resolved after the specified amount of milli-seconds."
  [(delay milli_seconds)])

(documentation: /.within
  "Wait for an async to be resolved within the specified amount of milli-seconds."
  [(within milli_seconds async)])

(.def .public documentation
  (.List $.Module)
  ($.module /._
            ""
            [..Async
             ..Resolver
             ..resolved
             ..async
             ..value
             ..upon!
             ..resolved?
             ..and
             ..or
             ..either
             ..schedule!
             ..future
             ..after
             ..delay
             ..within
             ($.default /.functor)
             ($.default /.apply)
             ($.default /.monad)]
            []))