# std/jsfetch

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

- Fetch for the JavaScript target: https://developer.mozilla.org/docs/Web/API/Fetch_API

Example: cmd: -r:off

    import std/jsfetch
    import std/[asyncjs, jsconsole, jsformdata, jsheaders]
    from std/httpcore import HttpMethod
    from std/jsffi import JsObject
    from std/sugar import `=>`

    block:
      let options0: FetchOptions = unsafeNewFetchOptions(
        metod = "POST".cstring,
        body = """{"key": "value"}""".cstring,
        mode = "no-cors".cstring,
        credentials = "omit".cstring,
        cache = "no-cache".cstring,
        referrerPolicy = "no-referrer".cstring,
        keepalive = false,
        redirect = "follow".cstring,
        referrer = "client".cstring,
        integrity = "".cstring,
        headers = newHeaders()
      )
      assert options0.keepalive == false
      assert options0.metod == "POST".cstring
      assert options0.body == """{"key": "value"}""".cstring
      assert options0.mode == "no-cors".cstring
      assert options0.credentials == "omit".cstring
      assert options0.cache == "no-cache".cstring
      assert options0.referrerPolicy == "no-referrer".cstring
      assert options0.redirect == "follow".cstring
      assert options0.referrer == "client".cstring
      assert options0.integrity == "".cstring
      assert options0.headers.len == 0

    block:
      let options1: FetchOptions = newFetchOptions(
        metod =  HttpPost,
        body = """{"key": "value"}""".cstring,
        mode = fmNoCors,
        credentials = fcOmit,
        cache = fchNoCache,
        referrerPolicy = frpNoReferrer,
        keepalive = false,
        redirect = frFollow,
        referrer = "client".cstring,
        integrity = "".cstring,
        headers = newHeaders()
      )
      assert options1.keepalive == false
      assert options1.metod == $HttpPost
      assert options1.body == """{"key": "value"}""".cstring
      assert options1.mode == $fmNoCors
      assert options1.credentials == $fcOmit
      assert options1.cache == $fchNoCache
      assert options1.referrerPolicy == $frpNoReferrer
      assert options1.redirect == $frFollow
      assert options1.referrer == "client".cstring
      assert options1.integrity == "".cstring
      assert options1.headers.len == 0

    block:
      let response: Response = newResponse(body = "-. .. --".cstring)
      let request: Request = newRequest(url = "http://nim-lang.org".cstring)

    if not defined(nodejs):
      block:
        proc doFetch(): Future[Response] {.async.} =
          fetch "https://httpbin.org/get".cstring

        proc example() {.async.} =
          let response: Response = await doFetch()
          assert response.ok
          assert response.status == 200.cint
          assert response.headers is Headers
          assert response.body is cstring

        discard example()

      block:
        proc example2 {.async.} =
          await fetch("https://api.github.com/users/torvalds".cstring)
            .then((response: Response) => response.json())
            .then((json: JsObject) => console.log(json))
            .catch((err: Error) => console.log("Request Failed", err))

        discard example2()

# Imports

asyncjs, jsformdata, jsheaders, httpcore, jsffi

# Types

    FetchCaches = enum
      fchDefault = "default", fchNoStore = "no-store", fchReload = "reload",
      fchNoCache = "no-cache", fchForceCache = "force-cache"

  https://developer.mozilla.org/docs/Web/API/Request/cache Source Edit

    FetchCredentials = enum
      fcInclude = "include", fcSameOrigin = "same-origin", fcOmit = "omit"

  Credential options. See https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials Source Edit

    FetchModes = enum
      fmCors = "cors", fmNoCors = "no-cors", fmSameOrigin = "same-origin"

  Mode options. Source Edit

    FetchOptions = ref object of JsRoot
      keepalive*: bool
      metod* {.importjs: "method".}: cstring
      body*, integrity*, referrer*, mode*, credentials*, cache*, redirect*,
      referrerPolicy*: cstring
      headers*: Headers

  Options for Fetch API. Source Edit

    FetchRedirects = enum
      frFollow = "follow", frError = "error", frManual = "manual"

  Redirects options. Source Edit

    FetchReferrerPolicies = enum
      frpNoReferrer = "no-referrer",
      frpNoReferrerWhenDowngrade = "no-referrer-when-downgrade",
      frpOrigin = "origin", frpOriginWhenCrossOrigin = "origin-when-cross-origin",
      frpUnsafeUrl = "unsafe-url"

  Referrer Policy options. Source Edit

    Request = ref object of JsRoot
      bodyUsed*, ok*, redirected*: bool
      typ* {.importjs: "type".}: cstring
      url*, statusText*: cstring
      status*: cint
      headers*: Headers
      body*: cstring

  https://developer.mozilla.org/en-US/docs/Web/API/Request Source Edit

    Response = ref object of JsRoot
      bodyUsed*, ok*, redirected*: bool
      typ* {.importjs: "type".}: cstring
      url*, statusText*: cstring
      status*: cint
      headers*: Headers
      body*: cstring

  https://developer.mozilla.org/en-US/docs/Web/API/Response Source Edit

# Procs

    func `$`(self: Request | Response | FetchOptions): string

  Source Edit

    func clone(self: Response | Request): Response {.importjs: "#.$1()", ...raises: [],
        tags: [], forbids: [].}

  https://developer.mozilla.org/en-US/docs/Web/API/Response/clone Source Edit

    proc fetch(url: cstring | Request): Future[Response] {.importjs: "$1(#)",
        ...raises: [], tags: [], forbids: [].}

  `fetch()` API, simple `GET` only, returns a `Future[Response]`. Source Edit

    proc fetch(url: cstring | Request; options: FetchOptions): Future[Response] {.
        importjs: "$1(#, #)", ...raises: [], tags: [], forbids: [].}

  `fetch()` API that takes a `FetchOptions`, returns a `Future[Response]`. Source Edit

    proc formData(self: Response): Future[FormData] {.importjs: "#.$1()",
        ...raises: [], tags: [], forbids: [].}

  https://developer.mozilla.org/en-US/docs/Web/API/Response/formData Source Edit

    proc json(self: Response): Future[JsObject] {.importjs: "#.$1()", ...raises: [],
        tags: [], forbids: [].}

  https://developer.mozilla.org/en-US/docs/Web/API/Response/json Source Edit

    func newfetchOptions(metod = HttpGet; body: cstring = nil; mode = fmCors;
                         credentials = fcSameOrigin; cache = fchDefault;
                         referrerPolicy = frpNoReferrerWhenDowngrade;
                         keepalive = false; redirect = frFollow;
                         referrer = "client".cstring; integrity = "".cstring;
                         headers: Headers = newHeaders()): FetchOptions {.
        ...raises: [], tags: [], forbids: [].}

  Constructor for `FetchOptions`. Source Edit

    func newRequest(url: cstring): Request {.importjs: "(new Request(#))",
        ...raises: [], tags: [], forbids: [].}

  Constructor for `Request`. This does not call `fetch()`. Same as `new Request()`. Source Edit

    func newRequest(url: cstring; fetchOptions: FetchOptions): Request {.
        importjs: "(new Request(#, #))", ...raises: [], tags: [], forbids: [].}

  Constructor for `Request` with `fetchOptions`. Same as `fetch(url, fetchOptions)`. Source Edit

    func newResponse(body: cstring | FormData): Response {.
        importjs: "(new Response(#))", ...raises: [], tags: [], forbids: [].}

  Constructor for `Response`. This does not call `fetch()`. Same as `new Response()`. Source Edit

    proc text(self: Response): Future[cstring] {.importjs: "#.$1()", ...raises: [],
        tags: [], forbids: [].}

  https://developer.mozilla.org/en-US/docs/Web/API/Response/text Source Edit

    func toCstring(self: Request | Response | FetchOptions): cstring {.
        importjs: "JSON.stringify(#)", ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc unsafeNewFetchOptions(metod, body, mode, credentials, cache, referrerPolicy: cstring;
                               keepalive: bool; redirect = "follow".cstring;
                               referrer = "client".cstring; integrity = "".cstring;
                               headers: Headers = newHeaders()): FetchOptions {.importjs: "{method: #, body: #, mode: #, credentials: #, cache: #, referrerPolicy: #, keepalive: #, redirect: #, referrer: #, integrity: #, headers: #}",
        ...raises: [], tags: [], forbids: [].}

  Warning: Unsafe `newfetchOptions`.
  Source Edit

# Exports

$, toCstring, add, clear, put, []=, keys, hasKey, FormData, newFormData, values, len, add, [], delete, pairs, getAll, $, Headers, add, entries, clear, []=, keys, hasKey, toCstring, values, len, newHeaders, delete, []