`include module type of struct include Js_of_ocaml.Promise end`

### Type safety

Native JavaScript promises automatically flatten any thenable returned from a handler or passed to `Promise.resolve`. That means a JavaScript `Promise` can never resolve with another `Promise` as its value, which is unsound at the OCaml type level for, say, `'a t t`.

These bindings work around that by wrapping thenable values in a small container before resolving and unwrapping on the way out; non-thenable values are passed through unchanged so the common case pays no allocation. As a result, `'a t` values always resolve with a value of OCaml type `'a`, even when `'a` is itself `'_ t`.

### Interop with raw JavaScript promises

Use `of_any` / `to_any` to interoperate with promises coming from outside this module. A `'a t` obtained via `of_any` from a foreign promise will not be wrapped, so it is up to the caller to ensure the types line up.

`type +'a t = 'a Js_of_ocaml.Promise.t`
`type error = Js_of_ocaml.Promise.error`

The reason a promise was rejected. JavaScript allows rejecting with any value (not necessarily an `Error`), so `error` is opaque; use `error_to_any` to inspect it and `error_of_any` to construct one.

## Errors

`val error_of_any : Js_of_ocaml.Js.Unsafe.any -> error`
`val error_to_any : error -> Js_of_ocaml.Js.Unsafe.any`
`val error_of_exn : exn -> error`

Use an OCaml exception as a rejection reason.

## Building promises

`val resolve : 'a -> 'a t`

A promise already fulfilled with the given value.

`val reject : error -> 'a t`

A promise already rejected with the given reason.

`val make : (resolve:('a -> unit) -> reject:(error -> unit) -> unit) -> 'a t`

`make f` runs `f` synchronously with two callbacks; `f` is expected to eventually invoke either `resolve` or `reject` to settle the promise.

`val with_resolvers : unit -> 'a t * ('a -> unit) * (error -> unit)`

`with_resolvers ()` returns `(p, resolve, reject)` where `p` is a fresh promise that is settled by calling `resolve x` (to fulfill with `x`) or `reject e` (to reject with `e`). Bound to the `Promise.withResolvers()` static method (ES2024).

## Chaining

`val then_ : ?on_error:(error -> 'b t) -> ('a -> 'b t) -> 'a t -> 'b t`

`then_ f p` returns a new promise that, when `p` fulfills with `x`, fulfills (or rejects) like `f x`. If `p` is rejected, the rejection is propagated.

If `~on_error` is supplied, this is the two-callback form of `.then(f, g)` in JavaScript: `on_error` only fires for rejections of `p` itself. If `f` returns a rejected promise, `on_error` does not catch it; chain a `catch` afterwards if you need that.

`val catch : (error -> 'a t) -> 'a t -> 'a t`

`catch f p` returns a new promise that, when `p` is rejected with reason `e`, fulfills (or rejects) like `f e`. If `p` is fulfilled, its value is propagated.

`val finally : (unit -> unit) -> 'a t -> 'a t`

`finally f p` returns a new promise that settles the same way as `p`, after invoking `f` for its side effect.

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

`map f p` is `then_ (fun x -> resolve (f x)) p`.

`val bind : ('a -> 'b t) -> 'a t -> 'b t`

Alias for `then_`.

## Combinators

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

`all ps` resolves with the values of all promises in `ps`, in order, or rejects with the reason of the first promise to reject.

`val all_settled : 'a t list -> ('a, error) Stdlib.result list t`

`all_settled ps` resolves once every promise in `ps` has settled, with a list in the same order: `Ok v` for a fulfilled promise and `Error e` for a rejected one. The returned promise never rejects.

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

`any ps` fulfills as soon as any promise in `ps` fulfills. If every promise rejects, the returned promise rejects with an `AggregateError` whose `errors` property lists the rejection reasons.

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

`race ps` settles like the first promise in `ps` to settle, fulfilled or rejected.

## Unsafe interop

`val to_any : 'a t -> Js_of_ocaml.Js.Unsafe.any`

Expose the underlying JavaScript promise. The resolved value may be the internal wrapper rather than the raw payload; consumers that observe the value should chain a `.then` that unwraps via `of_any` → `then_` rather than reading `.then` directly from the foreign side.

`val of_any : Js_of_ocaml.Js.Unsafe.any -> 'a t`

Treat a foreign JavaScript promise as a `'a t`. The returned value is only sound if the underlying promise actually resolves with a value of type `'a`; raw foreign values are passed through `then_` unchanged.

## Capability detection

`val is_supported : unit -> bool`

Whether the JavaScript `Promise` global is available in the current environment.

`exception Rejected of Js_of_ocaml.Promise.error`

Raised by the `Lwt.t` returned by `to_lwt` when the underlying `Promise` rejects. The rejection reason is wrapped unchanged — even when it is an OCaml exception (e.g. produced via `Promise.error_of_exn`), use `Promise.error_to_any` to inspect it.

`val to_lwt : 'a Js_of_ocaml.Promise.t -> 'a Lwt.t`

`to_lwt p` is an Lwt thread that fulfils with the value `p` resolves with, or fails with `Rejected` if `p` is rejected.

`val of_lwt : 'a Lwt.t -> 'a Js_of_ocaml.Promise.t`

`of_lwt t` is a `Promise` that resolves with the value `t` returns, or rejects with `Promise.error_of_exn exn` if `t` fails.