The `jamrock:conn` module

The connection context wraps the current request and response, also providing some useful stuff.

How it works?

Jamrock will execute your code in some order: matching middleware goest first, then actions and finally the page handlers.

Returned values will be used to produce a response:

number — just the status-code, without body
string — just the body, ends with a 200 OK
{ ... } — object-like values will be sent as JSON
[number, string, { ... }] — status, body, and headers
new Response(string | null, ...) — standarized Response

If you want to return an array, like a list of values, use an object with a property containing its value instead.
Otherwise, the framework will try to extract the status, body, and headers parameters from your value.

If no response is set, matching pages will be rendered and respond with 200 OK.

Available properties

req

The standard Request object as described on the MDN.

Supported runtimes will have their own implementation.

store

This is a simplified API to Redis (if enabled), falling back to memory.

Useful for saving saving data across instances, application state is saved here.

method

Returns any of the following values: GET, PUT, POST, PATCH or DELETE.

All non GET calls will require a valid csrf-token to be executed.

server

Instantiated server information like proto, host or port.

base_url

Use this property to get/set the <base href="/" /> path.

Usually you don't need to touch this, but if you're routing the application outside the root / you might need to change it.
This is because all paths from assets and resources are absolute once compiled.

cookies

Request cookies as object, to set cookies see the cookie() method below.

session

Saved session from the Redis store (or memory store).

headers

Request headers as object, Response headers can be set with resp_headers, see below.

options

Given framework options to the current instance (read-only).

aborted

Returns true if request has ended.

This value is derived from the req.signal found on the original Request object.

params

Mixed query, body and path params in that order.

path_info

List of path segments, i.e. for /a/b/c you'll get ['a', 'b', 'c'].

path_params

Route parameters, i.e. /foo/:bar would produce a { foo: 'bar' } object as value.

body_params

Request body as object.

The body is not parsed on every request, you need to call req.parseBody() to achieve that.
A common pattern is having an http middleware that you can use in your handlers.

request_path

Requested url's pathname, i.e. /path/to/x.

query_string

Requested url's query string, i.e. foo=bar&baz=buzz

query_params

Requested url's query as object, i.e. { foo: 'bar', baz: 'buzz' }

csrf_token

Calculated crsf-token for the request.

This is injected by the framework but you can use it as needed.
To enable it you need to call req.csrfProtect() on every request, try using a middleware for that.

resp_cookies

Response cookies (Map object).

Jamrock will use this to build the final response.

resp_headers

Response headers (Headers object).

Jamrock will use this to build the final response.

status_code

Low-level way to get/set the response status code.

Once set, the framework will stop executing handlers and page components, etc.
If you want to set a different status code without ending the response call status() instead.

resp_body

Low-level way to get/set the response body.

These low-level methods are intended for functions that may return values while setting the response directly on the conn object.
Jamrock use them to build a Response for you if already set.

has_body

Returns true if the response has a body value.

is_close

Returns true if the response is already closed.

Calls to status() will set the status_code but keep the response open.
Calls to redirect() set the status_code and close the response.

is_json

Returns true if the request accepts application/json.

is_xhr

Returns true if the request is XMLHttpRequest.

Available methods

Set response cookies, if value is null then the cookie will be set as expired (e.g. { expires: new Date(0) }).

If options is a number then the expiration is set N seconds in the future (e.g. { expires: Date.now() + N }).

Supported options are: { value, maxAge, domain, path, expires, httpOnly, secure, sameSite }.

The expires option can be an integer, Date object or a formatted date string.

header(key, value)

Set response headers directly on resp_headers.

This method is a shortcut for resp_headers.set().

status(code)

Sets the status_code without closing the response.

Use this method if you want your pages to be rendered with different statuses, useful for custom error-pages, etc.

You can set the status_code once, more calls are disallowed.

redirect(url[, code])

Ends the request with a redirection.

Calling this will close the response without blocking.

toJSON()

Serialized request-info without body.

flash(type, message)

Writes messages to the session flash.

Calling flash() without arguments will return and clear the whole flash-info from session.

Messages are stored and returned in a single array.

raise(code, message[, exception])

Ends the request with a failure.

It throws an exception with the given status as field, use exception to instantiate a different class than Error, e.g.

raise(404, 'User not found', class CustomError extends Error {});

send(code, [body, [headers]])

Ends the request with the given arguments.

The body will be calculated by the framework, it can be a string, Buffer or plain object.

send(201, { success: true });

Plain objects will be serialized as JSON and the { 'content-type': 'application/json' } header will be set.

The jamrock:conn module