Skip to content

http_readme.md

Latest commit

 

History

History
177 lines (131 loc) · 6.25 KB

http_readme.md

File metadata and controls

177 lines (131 loc) · 6.25 KB

Overview

http.mjs provides essential tools for HTTP servers and clients:

  • Shortcuts for making requests via native fetch.
  • Cookie decoding and encoding.
  • URL-based routing for SSR and SPA apps.

Also see http_bun for Bun HTTP servers, http_deno for Deno HTTP servers, and http_live for live-reload tools for development.

TOC

Usage

import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/js@0.1.85/http.mjs'

const reqBody = {msg: `hello world`}
const resBody = await h.reqBui().to(`/api`).post().json(reqBody).fetchOkJson()

API

function resOk

Links: source; test/example.

Signature: (res: Response | Promise<Response>) => Promise<Response>.

Missing feature of the fetch API. If the response is OK (HTTP code between 200 and 299, .ok === true), the resulting promise resolves to that response as-is. Otherwise the resulting promise is rejected with a descriptive #ErrHttp which includes the response status code, the response body (if any) as the error message, and the response itself for introspection if needed.

import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/js@0.1.85/http.mjs'

// If response is unsuccessful, this will throw `h.ErrHttp`.
const res = await h.resOk(await fetch(someUrl, someOpt))

const body = res.json()

function jsonDecode

Links: source; test/example.

Sanity-checking wrapper for JSON.parse. If the input is nil or an empty string, returns null. Otherwise the input must be a primitive string. Throws on other inputs, without trying to stringify them.

function jsonEncode

Links: source; test/example.

Sanity-checking wrapper for JSON.stringify. Equivalent to JSON.stringify(val ?? null). If the input is undefined, returns 'null' (string) rather than undefined (nil). Output is always a valid JSON string.

class Ctx

Links: source; test/example.

Subclass of built-in AbortController. Features:

  • Support for chaining / linking, like in Go.
    • When parent signal is aborted, every child is aborted.
  • Subclassable without further breakage.
    • Has workarounds for Safari bugs.
  • Implements our "standard" interface .deinit().

Optional chaining/linking:

const parent = new AbortController()
const child0 = new h.Ctx(parent.signal)
const child1 = new h.Ctx(child0.signal)

parent.abort()
parent.signal.aborted === true
child0.signal.aborted === true
child1.signal.aborted === true

class Rou

Links: source; test/example.

Simple router that uses only URL and pathname. Suitable for SPA. For servers, use #ReqRou which supports requests and HTTP methods.

Basics:

const rou = new h.Rou(`https://example.com/path?query#hash`)

rou.url // Url { https://example.com/path?query#hash }
rou.url.href === `https://example.com/path?query#hash`
rou.pathname === `/path`
rou.groups === undefined

rou.pat(`/`) === false
rou.pat(`/blah`) === false
rou.pat(`/path`) === true

rou.pat(/^[/](?<key>[^/]+)$/) === true
rou.groups // {key: `path`}

Routing is imperative:

import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/js@0.1.85/http.mjs'
import * as l from 'https://cdn.jsdelivr.net/npm/@mitranim/js@0.1.85/lang.mjs'

const nextPage = route(window.location)

function route(loc) {
  const rou = new h.Rou(loc)

  if (rou.pat(`/`)) return PageIndex(rou)
  if (rou.pat(`/articles`)) return PageArticles(rou)
  if (rou.pat(/^[/]articles[/](?<key>[^/]+)$/)) return PageArticle(rou)
  return Page404(rou)
}

function PageArticle(rou) {
  const key = l.reqPk(rou.reqGroups().key)
  return `page for article ${key}`
}

Undocumented

The following APIs are exported but undocumented. Check http.mjs.