Packages

gossamer

10.0.0
10.0.0 9.2.0 9.1.0 9.0.0 8.5.0 8.4.0 8.3.0 8.2.0 8.1.0 8.0.0 7.0.0 6.8.0 6.7.0 6.6.0 6.5.0 6.4.0 6.3.0 6.2.0 6.1.0 6.0.0 5.0.0 4.1.0 4.0.1 4.0.0 3.4.0 3.3.0 3.2.0 3.1.0 3.0.0 2.0.0 1.0.1 1.0.0

Web Platform and ECMAScript API bindings for Gleam's JavaScript target

HexDocs

Current section

Files

Jump to
Readme
32 Versions
7 Dependencies
Dependants
Files
Activity
gossamer README.md
Raw

README.md 

# gossamer 🕸️



Cross-runtime JavaScript API bindings for [Gleam](https://gleam.run/).



[![Package Version](https://img.shields.io/hexpm/v/gossamer)](https://hex.pm/packages/gossamer)

[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gossamer/)



<!-- floors-badges:start -->



[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D%2024.7.0-339933?logo=nodedotjs&logoColor=fff)](https://nodejs.org/)

[![Deno](https://img.shields.io/badge/Deno-%3E%3D%202.8.2-70ffaf?logo=deno&logoColor=fff)](https://deno.com/)

[![Bun](https://img.shields.io/badge/Bun-%3E%3D%201.3.13-fbf0df?logo=bun&logoColor=fff)](https://bun.sh/)



<!-- floors-badges:end -->



gossamer covers Web Platform APIs

([WinterTC](https://min-common-api.proposal.wintertc.org/)) and ECMAScript

built-ins that don't have idiomatic Gleam wrappers yet. Bindings work across

Node.js, Deno, Bun, and browsers without polyfills — the badges above show the

minimum versions verified against gossamer's test suite.



## Reach for ecosystem packages first



gossamer is gap-fill. Where the Gleam ecosystem already covers a domain, use its

canonical types and functions directly:



| Domain                                     | Use this                                                      |

| ------------------------------------------ | ------------------------------------------------------------- |

| HTTP requests, responses, methods, headers | [`gleam_http`](https://hexdocs.pm/gleam_http/)                |

| `fetch`                                    | [`gleam_fetch`](https://hexdocs.pm/gleam_fetch/)              |

| URLs (RFC 3986 parsing, building)          | [`gleam/uri`](https://hexdocs.pm/gleam_stdlib/gleam/uri.html) |

| Timestamps and durations                   | [`gleam_time`](https://hexdocs.pm/gleam_time/)                |

| JSON                                       | [`gleam_json`](https://hexdocs.pm/gleam_json/)                |

| `Promise`, `Array`, `Symbol`               | [`gleam_javascript`](https://hexdocs.pm/gleam_javascript/)    |

| Iterators                                  | [`gleam_yielder`](https://hexdocs.pm/gleam_yielder/)          |

| Regular expressions                        | [`gleam_regexp`](https://hexdocs.pm/gleam_regexp/)            |

| Strong random bytes                        | [`gleam_crypto`](https://hexdocs.pm/gleam_crypto/)            |



gossamer fills the rest: `AbortSignal`, `Blob` / `File`, the Streams API,

`SubtleCrypto`, `WebSocket`, `Worker` / `MessageChannel` / `BroadcastChannel`,

`Intl` formatters, `TextDecoder` / `TextDecoderStream` / `TextEncoderStream`,

`CompressionStream` / `DecompressionStream`, `URLPattern`, `BigInt`,

`Performance` / `PerformanceObserver`, plus per-module extras (`fetch_extra`,

`form_data_extra`, `time_extra`, `string_extra`, `regexp_extra`, `symbol_extra`,

`int_extra`, `float_extra`). See the

[coverage page](https://hexdocs.pm/gossamer/coverage.html) for the full list.



Per-binding docs flag cross-runtime gaps where a runtime departs from spec.



## Installation



```sh

gleam add gossamer gleam_fetch gleam_http gleam_javascript

```



gossamer's API composes with the canonical ecosystem types, so code using it —

including the example below — typically imports `gleam_fetch`, `gleam_http`, and

`gleam_javascript` directly; add them as direct dependencies alongside gossamer.



## Usage



A fetch through `gossamer/fetch_extra` with cache and keepalive overrides —

chain setters on the `FetchOptions` builder, then pass it to `send`. The result

composes with `gleam/fetch`'s body readers:



```gleam

import gleam/fetch

import gleam/http/request

import gleam/javascript/promise

import gossamer/fetch_extra



pub fn main() {

  let assert Ok(req) = request.to("https://example.com/api")

  let opts =

    fetch_extra.options()

    |> fetch_extra.set_cache(fetch_extra.CacheNoStore)

    |> fetch_extra.set_keepalive(True)

  use resp <- promise.try_await(fetch_extra.send(req, with: opts))

  use resp <- promise.try_await(fetch.read_text_body(resp))

  promise.resolve(Ok(resp.body))

}

```



Further documentation lives at <https://hexdocs.pm/gossamer>.