Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oakserver/acorn
A focused RESTful server framework for Deno 🌰🦕
https://github.com/oakserver/acorn
bun cloudflare-workers deno javascript json nodejs restful typescript
Last synced: 2 months ago
JSON representation
A focused RESTful server framework for Deno 🌰🦕
- Host: GitHub
- URL: https://github.com/oakserver/acorn
- Owner: oakserver
- License: mit
- Created: 2022-05-05T05:12:10.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-11T02:10:54.000Z (2 months ago)
- Last Synced: 2024-11-11T03:19:23.809Z (2 months ago)
- Topics: bun, cloudflare-workers, deno, javascript, json, nodejs, restful, typescript
- Language: TypeScript
- Homepage: https://oakserver.org/acorn
- Size: 383 KB
- Stars: 54
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# acorn
[](https://jsr.io/@oak/acorn)
[](https://jsr.io/@oak/acorn)
A focused framework for creating RESTful JSON services across various JavaScript
and TypeScript runtime environments including [Deno runtime](https://deno.com/),
[Deno Deploy](https://deno.com/deploy), [Node.js](https://nodejs.org/),
[Bun](https://bun.sh/) and
[Cloudflare Workers](https://workers.cloudflare.com/).
It focuses on providing a router which handles inbound requests and makes it
trivial to respond to those requests with JSON. It also provides several other
features which make creating API servers with acorn production ready. acorn is a
focused framework for creating RESTful JSON services across
## Basic usage
acorn is designed to work on many different JavaScript and TypeScript runtimes,
including Deno, Node.js, Bun, and Cloudflare Workers. Basic usage requires
installing acorn to your project and then creating a router to handle requests.
### Installing for Deno
To install acorn for Deno, you can install it via the Deno runtime CLI:
```
deno add jsr:@oak/acorn
```
### Installing for Node.js or Cloudflare Workers
To install acorn for Node.js or Cloudflare Workers, you can install it via your
preferred package manager.
#### npm
```
npx jsr add @oak/acorn
```
#### yarn
```
yarn dlx jsr add @oak/acorn
```
#### pnpm
```
pnpm dlx jsr add @oak/acorn
```
### Installing for Bun
To install acorn for Bun, you can install it via the Bun runtime CLI:
```
bunx jsr add @oak/acorn
```
### Usage with Deno, Node.js, and Bun
Basic usage of acorn for Deno, Node.js, and Bun is the same. You import the
`Router`, create an instance of it, register routes on the router, and then
called the `.listen()` method on the router to start listening for requests:
```ts
import { Router } from "@oak/acorn";
const router = new Router();
router.get("/", () => ({ hello: "world" }));
router.listen({ port: 3000 });
```
### Usage with Cloudflare Workers
Basic usage for Cloudflare Workers requires exporting a fetch handler which is
integrated into the router, and therefore you export the router as the default
export of the module:
```ts
import { Router } from "@oak/acorn";
const router = new Router();
router.get("/", () => ({ hello: "world" }));
export default router;
```
## Router
The `Router` is the core of acorn and is responsible for handling inbound
requests and routing them to the appropriate handler. The router provides
methods for registering routes for different HTTP methods and handling requests
for those routes.
### Default behaviors
The router provides several automatic behaviors which are designed to make
creating RESTful JSON services easier. These behaviors include handling
`404 Not Found` responses, `405 Method Not Allowed` responses, and providing a
default response for `OPTIONS` requests.
#### Not Found
When a request is received by the router and no route is matched, the router
will send a `404 Not Found` response to the client. This is the default behavior
of the router and can be overridden by providing a `onNotFound` hook to the
router.
#### Method Not Allowed
When a request is received by the router and a route is matched but there is no
handler for the method of the request, the router will send a
`405 Method Not Allowed` response to the client which will provide the allowed
methods. This is the default behavior of the router and can be overridden by
providing a status handler.
#### Options
When a request is received by the router and the method of the request is
`OPTIONS`, the router will send a response to the client with the allowed
methods for the route. This is the default behavior of the router and can be
overridden by providing an `options()` route.
## Context
The `Context` is the object passed to route handlers and provides information
about the request and runtime environment. The context object provides access to
the `Request` object as well as other useful properties and methods for handling
requests.
### `addr`
The network address of the originator of the request as presented to the runtime
environment.
### `cookies`
The cookies object which can be used to get and set cookies for the request. If
encryptions keys are provided to the router, the cookies will be
cryptographically verified and signed to ensure their integrity.
### `env`
The environment variables available to the runtime environment. This assists in
providing access to the environment variables for the runtime environment
without having to code specifically for each runtime environment.
### `id`
A unique identifier for the request event. This can be useful for logging and
tracking requests.
### `params`
The parameters extracted from the URL path by the router.
### `request`
The Fetch API standard `Request` object which should be handled.
### `responseHeaders`
The headers that will be sent with the response. This will be merged with other
headers to finalize the reponse.
### `url`
The URL object representing the URL of the request.
### `userAgent`
A parsed version of the `User-Agent` header from the request. This can be used
to determine the type of client making the request.
### `body()`
A method which returns a promise that resolves with the body of the request
assumed to be JSON. If the body is not JSON, an error will be thrown. If a body
schema is provided to the route, the body will be validated against that schema
before being returned.
### `conflict()`
A method which throws a `409 Conflict` error and takes an optional message and
optional cause.
### `created()`
A method which returns a `Response` with a `201 Created` status code. The method
takes the body of the response and an optional object with options for the
response. If a `location` property is provided in the options, the response will
include a `Location` header with the value of the location.
If `locationParams` is provided in the options, the location will be
interpolated with the parameters provided.
### `notFound()`
A method which throws a `404 Not Found` error and takes an optional message and
optional cause.
### `queryParams()`
A method which returns a promise that resolves with the query parameters of the
request. If a query parameter schema is provided to the route, the query
parameters will be validated against that schema before being returned.
### `redirect()`
A method which sends a redirect response to the client. The method takes a
location and an optional init object with options for the response. If the
location is a path with parameters, the `params` object can be provided to
interpolate the parameters into the URL.
### `throw()`
A method which can be used to throw an HTTP error which will be caught by the
router and handled appropriately. The method takes a status code and an optional
message which will be sent to the client.
### `created()`
A method which returns a `Response` with a `201 Created` status code. The method
takes the body of the response and an optional object with options for the
response.
This is an appropriate response when a `POST` request is made to a resource
collection and the resource is created successfully. The options should be
included with a `location` property set to the URL of the created resource. The
`params` property can be used to provide parameters to the URL. For example if
`location` is `/books/:id` and `params` is `{ id: 1 }` the URL will be
`/books/1`.
### `conflict()`
A method which throws a `409 Conflict` error and takes an optional message and
optional cause.
This is an appropriate response when a `PUT` request is made to a resource that
cannot be updated because it is in a state that conflicts with the request.
### `sendEvents()`
A method which starts sending server-sent events to the client. This method
returns a `ServerSentEventTarget` which can be used to dispatch events to the
client.
### `upgrade()`
A method which can be used to upgrade the request to a `WebSocket` connection.
When the request is upgraded, the request will be handled as a web socket
connection and the method will return a `WebSocket` which can be used to
communicate with the client.
**Note:** This method is only available in the Deno runtime and Deno Deploy
currently. If you call this method in a different runtime, an error will be
thrown.
## Router Handlers
The `RouteHandler` is the function which is called when a route is matched by
the router. The handler is passed the `Context` object and is expected to return
a response. The response can be a plain object which will be serialized to JSON,
a `Response` object. The handler can also return `undefined` if the handler
wishes to return a no content response. The handler can also return a promise
which resolves with any of the above.
### Registering Routes
Routes can be registered on the router using the various methods provided by the
router. The most common methods are `get()`, `post()`, `put()`, `patch()`, and
`delete()`. In addition `options()` and `head()` are provided.
The methods take a path pattern and a handler function, and optionally an object
with options for the route (`RouteInit`). The path pattern is a string which can
include parameters and pattern matching syntax. The handler function is called
when the route is matched and is passed the context object.
For example, to register a route which responds to a `GET` request:
```ts
router.get("/", () => ({ hello: "world" }));
```
The methods also accept a `RouteDescriptor` object, or a path along with a set
of options (`RouteInitWithHandler`) which includes the handler function.
For example, to register a route which responds to a `POST` request:
```ts
router.post("/", {
handler: () => ({ hello: "world" }),
});
```
And for a route which responds to a `PUT` request with the full descriptor:
```ts
router.put({
path: "/",
handler: () => ({ hello: "world" }),
});
```
### Hooks
The router provides hooks which can be used to get information about the routing
process and to potentially modify the response. The hooks are provided when
creating the router and are called at various points in the routing process.
#### `onRequest()`
The `onRequest` hook is called when a request is received by the router. The
`RequestEvent` object is provided to the hook and can be used to inspect the
request.
The `onRequest` could invoke the `.respond()` method on the `RequestEvent` but
this should be avoided.
#### `onNotFound()`
As a request is being handled by the router, if no route is matched or the route
handler returns a `404 Not Found` response the `onNotFound` hook is called.
There is a details object which provides the `RequestEvent`being handled, any
`Response` that has been provided (but not yet sent to the client) and the
`Route` that was matched, if any.
The `onNotFound` hook can return a response to be sent to the client. If the
hook returns `undefined`, the router will continue processing the request.
#### `onHandled()`
After a request has been processed by the router and a response has been sent to
the client, the `onHandled` hook is called. The hook is provided with a set of
details which include the `RequestEvent`, the `Response`, the `Route` that was
matched, and the time in milliseconds that the request took to process.
#### `onError()`
If an unhandled error occurs in a handler, the `onError` hook is called. The
hook is provided with a set of details which include the `RequestEvent`, the
`Response` that was provided, the error that occurred, and the `Route` that was
matched, if any.
## Route Parameters
The router can extract parameters from the URL path and provide them to the
route handler. The parameters are extracted from the URL path based on the
pattern matching syntax provided by the
[`path-to-regexp`](https://github.com/pillarjs/path-to-regexp) library. The
parameters are provided to the handler as an object with the parameter names as
the keys and the values as the values.
For example, to register a route which extracts a parameter from the URL path:
```ts
router.get("/:name", (ctx) => {
return { hello: ctx.params.name };
});
```
## Status Handlers
acorn provides a mechanism for observing or modifying the response to a request
based on the status of the response. This is done using status handlers which
are registered on the router. The status handlers are called when a response is
being sent to the client and the status of the response matches the status or
status range provided to the handler.
This is intended to be able to provide consistent and customized responses to
status codes across all routes in the router. For example, you could provide a
status handler to handle all `404 Not Found` responses and provide a consistent
response to the client:
```ts
import { Router } from "@oak/acorn";
import { Status, STATUS_TEXT } from "@oak/commons/status";
const router = new Router();
router.on(Status.NotFound, () => {
return Response.json(
{ error: "Not Found" },
{ status: Status.NotFound, statusText: STATUS_TEXT[Status.NotFound] },
);
});
```
## Schema Validation
acorn integrates the [Valibot](https://valibot.dev/) library to provide schema
validation for query strings, request bodies, and responses. This allows you to
define the shape of the data you expect to receive and send and have it
validated automatically.
You can provide a schema to the route when registering it on the router. The
schema is an object which describes the shape of the data you expect to receive
or send. The schema is defined using the Valibot schema definition language.
For example, to define a schema for a request body:
```ts
import { Router, v } from "@oak/acorn";
const router = new Router();
router.post("/", () => ({ hello: "world" }), {
schema: {
body: v.object({
name: v.string(),
}),
},
});
```
This ensures that the request body is an object with a `name` property which is
a string. If the request body does not match this schema, an error will be
thrown and the request will not be processed and a `Bad Request` response will
be sent to the client.
You can provide an optional invalid handler to the schema which will be called
when the schema validation fails. This allows you to provide a custom response
to the client when the request does not match the schema.
## RESTful JSON Services
acorn is designed to make it easy to create RESTful JSON services. The router
provides a simple and expressive way to define routes and has several features
which make it easy to create production ready services.
### HTTP Errors
acorn provides a mechanism for throwing HTTP errors from route handlers. The
`throw()` method on the context object can be used to throw an HTTP error. HTTP
errors are caught by the router and handled appropriately. The router will send
a response to the client with the status code and message provided to the
`throw()` method with the body of the response respecting the content
negotiation headers provided by the client.
### No Content Responses
If a handler returns `undefined`, the router will send a `204 No Content`
response to the client. This is useful when a request is successful but there is
no content to return to the client.
No content responses are appropriate for `PUT` or `PATCH` requests that are
successful but you do not want to return the updated resource to the client.
### Created Responses
The `created()` method on the context object can be used to send a `201 Created`
response to the client. This is appropriate when a `POST` request is made to a
resource collection and the resource is created successfully. The method takes
the body of the response and an optional object with options for the response.
The options should be included with a `location` property set to the URL of the
created resource. The `params` property can be used to provide parameters to the
URL. For example if `location` is `/books/:id` and `params` is `{ id: 1 }` the
URL will be `/books/1`.
### Conflict Responses
The `conflict()` method on the context object can be used to throw a
`409 Conflict` error. This is appropriate when a `PUT` request is made to a
resource that cannot be updated because it is in a state that conflicts with the
request.
### Redirect Responses
If you need to redirect the client to a different URL, you can use the
`redirect()` method on the context object. This method takes a URL and an
optional status code and will send a redirect response to the client.
In addition, if the `location` is a path with parameters, you can provide the
`params` object to the `redirect()` method which will be used to populate the
parameters in the URL.
## Logging
acorn integrates the [LogTape](https://jsr.io/@logtape/logtape) library to
provide logging capabilities for the router and routes.
To enable logging, you can provide a `LoggerOptions` object on the property
`logger` to the router when creating it:
```ts
const router = new Router({
logger: {
console: { level: "debug" },
},
});
```
Alternatively, you can simply set the `logger` property to `true` to log events
at the `"WARN"` level to the console:
```ts
const router = new Router({
logger: true,
});
```
---
Copyright 2018-2024 the oak authors. All rights reserved. MIT License.