Build JavaScript server apps using effects as data. Requests and responses are represented as data and FX use this data to interact with the imperative IncomingMessage and ServerResponse APIs provided by Node.
$ npm i fxapp
const { app } = require("fxapp");
app({
routes: () => ({
response: {
text: "Hello World"
}
})
});
Default: 8080
The port on which the server will listen.
Optional initial dispatch
able(s) that are run on server start before accepting any requests. Use this to set initial global state or for side effectful initialization like opening required resources or network connections.
Optional dispatch
able(s) that are run on every request before the router. Use this for parsing custom request data, custom routing, sending custom responses, or side FX like logging.
Default: {}
Routes are defined as a nested object structure with some properties having special meanings. The first matching route value will be dispatched.
Example:
app({
routes: {
// GET /unknown/path
_: fallbackAction,
path: {
some: {
// GET /path/some
GET: someReadAction,
// POST /path/some
POST: someAddAction
},
other: {
// GET /path/other/123
// { request: { params: { id: "123" } } }
$id: otherAction
}
}
}
});
The special wildcard _
route is reserved for routes that match in the absence of a more specific route. Useful for 404 and related behaviors. Sending a GET
request to /unknown/path
will respond with the results of fallbackAction
.
Routes with the name of an HTTP request method will match any requests with that method. Sending a GET
request to /path/some
with the example route will respond with the results of someReadAction
. A POST
request to /path/some
will respond with the results of someAddAction
.
Routes beginning with $
are reserved and define a path parameter for matching at that position. In the example above sending a GET
request to /path/other/123
will respond with the results of passing {id: "123"}
as the request.params
to otherAction
.
{
request: {
method: "GET",
url: "/path/other/123?param=value&multiple=1&multiple=2",
path: "/path/other/123",
query: { param: "value", multiple: ["1", "2"] },
params: { id: "123" },
headers: {
Host: "localhost:8080"
}
},
response: {
statusCode: 200,
headers: { Server: "fxapp" },
text: "Hello World"
}
}
Normalized data parsed from the HTTP request that is currently being processed.
Examples: GET
, HEAD
, POST
, PUT
, DELETE
, CONNECT
, OPTIONS
, TRACE
, PATCH
The HTTP request method used to make the request.
The full request URL, including query parameters.
The request path, omitting query parameters.
An object containing the request query parameters. Multiple instances of the same parameter are stored as an array.
An object containing path parameters from the router.
An object containing all HTTP request headers.
The contents of the request body. Respects the Content-Length
header.
This will be set if the Content-Type
of the request is application/json
and the body content is valid JSON.
Data representing the HTTP response that will be sent to the client once all FX are done running.
Default: 200
The HTTP status code to send in the response.
The HTTP response headers to send.
Skip the default logic for sending the response body. Make sure you provide requestFx
to handle this response or the request will hang for the client.
The HTTP response body that will be sent as application/json
. Value will be formatted using JSON.stringify
.
The HTTP response body that will be sent as text/html
.
The HTTP response will pipe the contents of the file at the given path. Never pass user-provided data for this as that would introduce a vulnerability for arbitrary disk access. You may need to add response.contentType
in order for the client to interpret the response correctly.
The HTTP response body that will be sent as text/plain
unless a value is passed for response.contentType
.
StateUpdate = function(state: Object, props: Object) => newState: Object
StateUpdateWithProps = [StateUpdate, props: Object]
ReservedProps = {
concurrent: boolean? = false,
after: boolean? = false,
cancel: boolean? = false
}
FX = {
run: ({
dispatch: function(Dispatchable),
serverRequest: IncomingMessage,
serverResponse: ServerResponse,
...ReservedProps,
// Additional props
}) => Promise? | undefined,
...ReservedProps,
// Additional props
}
FXWithProps = [FX, props: Object]
Dispatchable = StateUpdate | StateUpdateWithProps | FX | FXWithProps | [Dispatchable]
Perform an immutable state update by receiving the current state as a parameter and returning the new state. Automatically shallow merges root properties in addition to one level under request
and response
. Optional props
may be passed at the time of dispatch using a tuple represented as an array of [stateMapping, props]
.
FX as data are represented with an object containing a run
function and properties that will be passed to that function. Props may also optionally be passed at the time of dispatch using a tuple represented as an array of [fx, props]
, which will be merged with the props defined on the FX object. Props passed during dispatch will override those defined on the FX when the same key is used.
The run
function returns a Promise
if the effect is async. Async FX are considered still running until resolved or rejected. Otherwise FX are considered sync and done once the run
function returns.
Some props are reserved and have special meaning:
Default: false
Used for running multiple FX in parallel where the results are unrelated. These FX will take priority and must all complete before running any nonconcurrent FX.
Default: false
Run FX after all others are complete. Use this for logging, cleanup, or providing custom response-sending logic.
Default: false
Cancel all other FX immediately. Cancelled FX are no longer able to dispatch. FX already dispatched with after
will still be run to allow for the response to be sent. Use this to enforce response timeouts or for handling errors.
The internal http.IncomingMessage used by the Node HTTP server implementation. Allows for FX to interact with the request object to get additional data.
The internal http.ServerResponse used by the Node HTTP server implementation. Allows for FX to send other types of responses.
A batch of state mapping functions and/or FX may be dispatched by wrapping them in an array.
FX App is MIT licensed. See LICENSE.