/pogo

Server framework for Deno

Primary LanguageJavaScriptMozilla Public License 2.0MPL-2.0

pogo Build status for Pogo

Server framework for Deno

Pogo is an easy to use, safe, and expressive framework for writing web servers and applications. It is inspired by hapi.

Contents

Why?

  • Designed to encourage reliable and testable applications.
  • Routes are simple, pure functions that return values directly.
  • Automatic JSON responses from objects.

Usage

import pogo from 'https://deno.land/x/pogo/main.js';

const app = pogo.server({ port : 3000 });

app.route({
    method : 'GET',
    path   : '/hello',
    handler() {
        return 'Hello, world!';
    }
});

app.start();

API

server = pogo.server(option)

Returns a server instance, which can then be used to add routes and start listening for requests.

option

Type: object

hostname

Type: string
Default: localhost

Specifies which domain or IP address the server will listen on when server.start() is called. Use 0.0.0.0 to listen on any hostname.

port

Type: number
Example: 3000

Specifies which port number the server will listen on when server.start() is called. Use 0 to listen on any available port.

server.route(option)

Adds a route to the server so that the server knows how to respond to requests for the given HTTP method and path, etc.

option

Type: object

method

Type: string
Example: GET

Any valid HTTP method. Used to limit which requests will trigger the route handler.

path

Type: string
Example: /

Any valid URL path. Used to limit which requests will trigger the route handler.

handler(request, h)

Type: function

  • request is a ServerRequest instance with properties for headers, method, url, and more.
  • h is a Response Toolkit instance, which has utility methods for modifying the response.

The implementation for the route that handles requests. Called when a request is received that matches the method and path specified in the route options.

Should return one of:

  • A string, which will be sent as HTML.
  • A JSON value, which will be sent as JSON using JSON.stringify().
  • A Response Toolkit instance, which will send the h.body() value, if any.

An appropriate Content-Type header will be set automatically based on the response body before the response is sent. You can use h.type() to override the default behavior.

server.start()

Begins listening on the hostname and port specified when the server was created.

Response Toolkit

The response toolkit is an object that is passed to route handlers, with utility methods that make it easy to modify the response. For example, you can use it to set headers or a status code.

By convention, this object is assigned to a variable named h in code examples.

h.body(body)

Sets the response body. This is the same as returning the body directly from the route handler, but it's useful in order to begin a chain with other toolkit methods.

h.code(statusCode)

Sets the response status code. When possible, it is better to use a more specific method instead, such as h.redirect().

Tip: Use Deno's status constants to define the status code.

import { Status as status } from 'https://deno.land/x/http/http_status.ts';
const handler = (request, h) => {
    return h.code(status.Teapot);
};

h.created(url)

Sets the response status to 201 Created and sets the Location header to the value of url.

Returns the toolkit so other methods can be chained.

h.header(name, value)

Sets a response header. Always replaces any existing header of the same name. Headers are case insensitive.

Returns the toolkit so other methods can be chained.

h.location(url)

Sets the Location header on the response to the value of url. When possible, it is better to use a more specific method instead, such as h.created() or h.redirect().

Returns the toolkit so other methods can be chained.

h.permanent()

Only available after calling the h.redirect() method.

Sets the response status to 301 Moved Permanently or 308 Permanent Redirect based on whether the existing status is considered rewritable (see "method handling" on Redirections in HTTP for details).

Returns the toolkit so other methods can be chained.

h.redirect(url)

Sets the response status to 302 Found and sets the Location header to the value of url.

Also causes some new toolkit methods to become available for customizing the redirect behavior:

Returns the toolkit so other methods can be chained.

h.rewritable(isRewritable)

Only available after calling the h.redirect() method.

Sets the response status to 301 Moved Permanently or 302 Found based on whether the existing status is a permanent or temporary redirect code. If isRewritable is false, then the response status will be set to 307 Temporary Redirect or 308 Permanent Redirect.

Returns the toolkit so other methods can be chained.

h.temporary()

Only available after calling the h.redirect() method.

Sets the response status to 302 Found or 307 Temporary Redirect based on whether the existing status is considered rewritable (see "method handling" on Redirections in HTTP for details).

Returns the toolkit so other methods can be chained.

h.type(mediaType)

Sets the Content-Type header on the response to the value of mediaType.

Overrides the media type that is set automatically by the framework.

Returns the toolkit so other methods can be chained.

Contributing

See our contributing guidelines for more details.

  1. Fork it.
  2. Make a feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request.

License

MPL-2.0 © Seth Holladay

Go make something, dang it.