Koa-Client

NOTE: This project is not actively maintained. As an alternative check out Rill and it's http-server-in-the-browser implementation: @rill/http.

A client-side implementation of koa that automatically intercepts anchor clicks and form submissions. The goal of this project is to mimic the koa server implementation as closely as possible so that middleware can work on the client (such as koa-mount-route) while keeping file size to a minimum.

Install

npm install koa-client

Public API

###app.use(function) mount middleware function

###app.listen([selector|element]) intercept clicks and submissions from all children of the element. Default is document.body.

###app.request(req, [opts]) sends a request through app's middleware functions. It also updates the browser url using History API. This is the same function that is used internally to route requests that are intercepted from the element specified to app.listen. opts is an optional options object, the only option is replace_state, that when true uses history.replaceState instead of history.pushState to update the browser url.

###app.redirect(req) shorthand for app.request(req, { replace_state:true })

###app.refresh() shorthand for app.request(window.location.href, { replace_state:true })

Differences from Server

Context

Added Properties

ctx.browser = true

a variable that always returns true. helpful for middleware that you intend to run on both the client and server versions of koa.

Similar Properties

ctx.assert(test, status, message)

simple assertion, if test fails throws a plain Error with status attached. this is not an instance of a ClientError or ServerError.

ctx.throw(err|msg|status[, err|msg|status])

similar to above, throws a plain Error with status attached. this is not an instance of a ClientError or ServerError.

ctx.cookies.get(name)/ctx.cookies.set(name, val[, opts])

get and set cookies using document.cookie

ctx.app/ctx.request/ctx.response

references the same propeties as the server:

Removed Properties

• ctx.req removed
• ctx.res removed
• ctx.respond() removed

Accessors/Methods

Aside from those that have been removed, koa-client provides the same accessors that are on the server, although the implementation on the request/response may differ.

Request

• ctx.host
• ctx.hostname
• ctx.protocol
• ctx.header
• ctx.headers
• ctx.method
• ctx.method=
• ctx.url
• ctx.url=
• ctx.originalUrl
• ctx.path
• ctx.path=
• ctx.query
• ctx.query=
• ctx.querystring
• ctx.querystring=
• ctx.get()
• ctx.fresh removed
• ctx.stale removed
• ctx.socket removed
• ctx.secure removed
• ctx.ip removed
• ctx.ips removed
• ctx.subdomains removed
• ctx.is() removed
• ctx.accepts() removed
• ctx.acceptsEncodings() removed
• ctx.acceptsCharsets() removed
• ctx.acceptsLanguages() removed

Response

• ctx.body
• ctx.body=
• ctx.status
• ctx.status=
• ctx.message
• ctx.message=
• ctx.length=
• ctx.length
• ctx.type=
• ctx.type
• ctx.headerSent
• ctx.redirect()
• ctx.attachment()
• ctx.set()
• ctx.remove()
• ctx.lastModified=
• ctx.etag=

Request

Unmodified

The following are actually slightly modified, since there is no node req underlying the getters/setters, but the functionality should be exactly the same.

• request.host
• request.hostname
• request.protocol
• request.method
• request.method=
• request.url
• request.url=
• request.originalUrl
• request.path
• request.path=
• request.query
• request.query=
• request.querystring
• request.querystring=
• request.search
• request.search=

Similar Properties

request.header[s]/request.get()

does not get headers from an underlying node res object. expects lowercase header names.

Removed Properties

• request.fresh removed
• request.stale removed
• request.socket removed
• request.secure removed
• request.ip removed
• request.ips removed
• request.subdomains removed
• request.is() removed
• request.accepts() removed
• request.acceptsEncodings() removed
• request.acceptsCharsets() removed
• request.acceptsLanguages() removed

Response

Similar Properties

response.redirect(url[, alt])

does not set response.body or response.type, otherwise the same

response.header[s]/response.get()/response.set()/response.remove()

does not set headers on an underlying node res object. forces toLowerCase() on all header names.

Unspecified Properties

The following are unspecified properties of the response object. They have no getter/setter but you can still use them, they just won't do their magic behind the scence. (ex. request.body = {} will only set request.body to {}, it will not update content type/length headers.

• response.body
• response.status
• response.type
• response.headerSent
• response.message
• response.lastModified
• response.etag
• response.length

Removed Properties

• response.attachment() removed
• response.vary() removed
• response.socket removed
• response.is() removed
• response.writeable removed