HTTP server for Deno with local JSON REST API for rapid prototyping.
$ deno run --allow-net --allow-read --allow-write https://deno.land/x/tino@v1.0.5/tino.js
Internally Tino uses jsondb responder
which opens /api
path for playing around. It uses db.json
file by default as a database.
$ cp ./tests/jsondb.test.json ./db.json
Run: $ deno test
All tests are included in ./tests
directory.
// app.js
import tino from "https://deno.land/x/tino@v1.0.5/tino.js";
const app = tino.create();
const controller = () => ({ resp: "pong", status: 200 }) // must return { resp, status?, type? }
app.get(() => ({ path: "/ping", use: controller }));
tino.listen({ app, port: 8000 });
console.log(`Server running at 8000`);
$ deno run --allow-net app.js
$ http :8000/ping
(HTTPie, curl, Postman, etc.)"pong"
as text/plain
content type// Shorter: Use `resp` directly with status 200
app.get(() => ({ path: "/ping", resp: "pong" }));
// `resp` can be anything:
app.get(() => ({ path: "/ping", use: () => ({ resp: () => "pong", status: 200 }) }));
// Or (use: can also be async)
app.get(() => ({ path: "/ping-async", use: () => ({ resp: async () => "pong", status: 201 }) }));
app.not_found(() => ({ resp: "Oops" }));
Tino application app
supports following HTTP methods: GET, POST, PUT, PATCH, DELETE. Method names are lowercased. Also there is not_found
for status 404, so you can define custom response.
resp
can be anything, but if it’s a function it will return it’s result of execution, and it will be called no matter if it’s async or not. If it’s an object (or returned as an object), content type will be application/json
.
The only requirement for controller use
is that it must return { resp, status?, type? }
object. It can also be defined as async function.
What I’ve seen and used is that usually there are one or more global variables or internally modified variables through the request cycle. This results in following pseudo code:
myController = ctx => {
ctx.type = "text/html";
ctx.status = 200;
ctx.body = "<p>Greetings!</p>";
}
While in Tino idea is that all functions are composed and there is no global variable but what you want in next step is what you pass further, through the chain. That might look like:
myController = () => {
const type = "text/html";
const status = 200;
const body = "<p>Greetings!</p>";
return { type, status, body };
}
If you read further on about middlewares for example you’ll see how this plays well with composition. These functions must be pure, easy to unit test and able to be recursive.
Parameters are defined as :param
in your path definition. Optionals are defined as :param?
. Some examples:
app.get(() => ({ path: "/user/:id", use: () => ({ resp: ({ params }) => params.id }));
app.get(() => ({ path: "/notes/:id?", use: () => ({ resp: ({ params, notes }) => params.id ? [] : notes }));
props
definitionIf defined as a function, resp
receives following parameters:
body
- body payload for POST, PUT or PATCH methodsparams
- parameters from path definition, e.g. /path/:id
query
- query object from string like ?p=1&q=2
custom params
- anything else provided to method definition, except path
, resp
or use
matchedPath
- information about path regexpathPattern
- information about path definitionreq
- in form of { method, url }
Basically you can test this with following have-it-all definition:
// $ http POST :8000/post/123?q=1 foo=bar
const composed = withMiddlewares(
() => ({ isAdmin: true }),
);
app.post(() => ({
path: "/post/:id", // or optional with :id?
use: composed((props) => ({ resp: { ...props } })),
something: "else",
}));
Response received should be:
{
"body": {
"foo": "bar"
},
"isAdmin": true,
"matchedPath": {
"index": 0,
"params": {
"id": "123"
},
"path": "/post/123"
},
"params": {
"id": "123"
},
"pathPattern": "/post/:id",
"query": {
"q": "1"
},
"something": "else"
}
When you define resp
, you can define content type such as text/html
:
const use = () => ({ resp: "<p>Works!</p>", status: 200, type: 'text/html' });
app.get(() => ({ path: "/ping", use }));
Middlewares offer you way to extend response by injecting additional information to your controllers. In Tino it is done by async functional composition so your middlewares can be both sync and async. It is offered by withMiddlewares
helper from tino.js
.
import { withMiddlewares } from "tino.js";
// Initial props are provided: https://github.com/Vertrical/tino#props-definition
const auth = (props) => ({ isUser: true });
const isAdmin = (props) => ({ isAdmin: false, ...props });
const withDB = (props) => ({ coll: {}, ...props });
const composed = withMiddlewares(auth, isAdmin, withDB);
// Define your endpoint:
const use = composed(({ isUser, isAdmin, coll }) => ({ resp: "Hello", status: /*...*/ }));
app.get(() => ({ path: "/ping", use }));
Any prop that is returned will be passed over to next function in chain, until the end - end result is what is passed to your controller.
It’s similar to previous case only that if any of the middlewares throws an exception it will be used as end result of your controller, i.e. replace it.
import { withMiddlewares } from "tino.js";
const auth = (props) => { throw { resp: "Boom", status: 401 }; };
const isAdmin = (props) => ({ isAdmin: false, ...props });
const withDB = (props) => ({ coll: {}, ...props });
const composed = withMiddlewares(auth, isAdmin, withDB);
// Define your endpoint:
const use = composed(({ isUser, isAdmin, coll }) => ({ resp: "Hello" }));
app.get(() => ({ path: "/ping", use }));
// HTTP Response headers and content: (if you call "localhost:{port}/ping)
`
HTTP/1.1 401 Unauthorized
content-length: 4
content-type: text/plain
Boom
`
Note: Whatever you want to be returned from middlewares to your controller, you should propagate these props through the chain. (As seen above with ...props
for example)
In Tino responders are your implementations of custom APIs which don’t rely on paths pattern matching.
You define a responder by adding root: true
to your endpoint definition.
For example:
import myAwesomeAPI, { v2 } from "somewhere";
app.any(() => ({ path: "/awesome-api", use: myAwesomeAPI, root: true })); // <-- Notice the `root: true` part
app.any(() => ({ path: "/awesome-api/v2", use: v2, root: true }));
Setting the root
part is because we will match here only by startsWith
against your request, disregarding any parameter matching.
Example of a responder is jsondb
which comes integrated with Tino and is located in jsondb.js file.
jsondb
responderThis responder is just a small package included by default in Tino which handles CRUD operations on db.json
file.
Each response is wrapped with response
parent, like:
// GET /api/users/1234
{
"response": {
"id": "1234",
"name": "Smith"
}
}
jsondb
responder defined?jsondb
responder is already integrated with Tino so you don’t need to do anything. But, if you want to define it nevertheless, you can do it like below:
import tino, { jsondb } from "tino.js";
const app = tino.create();
app.any(() => ({ path: "/api", use: jsondb(), root: true })); // notice the ()
// If you want some other namespace
app.any(() => ({ path: "/awesome-api", use: jsondb(), root: true }));
tino.listen({ app });
(Please note that jsondb
must be called. This is because it is a higher order function.)
any
is needed because we want ANY HTTP METHOD to be used with this.
Test JSON file is included in tests/jsondb.test.json. You need to create your ./db.json
file to operate agains it.
Having the content same as in jsondb.test.json file, we would have following requests returning respective responses:
# Get list of items:
$ http :8000/api/laptops
# Get item by id: (jsondb treats any "id" found in an entity as ID)
$ http :8000/api/laptops/123
# Create new item:
$ http POST :8000/api/laptops id=789 brand=apple
# Replace an item:
$ http PUT :8000/api/laptops/789 brand=asus
# Update an item:
$ http PATCH :8000/api/laptops/789 brand=asus
# DELETE an item:
$ http DELETE :8000/api/laptops/789
You can see many examples in tests/requests.http file.
If you want to change endpoint from /api
to something else, just replace it:
app.any(() => ({ path: "/myapi", use: jsondb(), root: true }));
// you can optionally "close" /api
app.any(() => ({ path: "/api", status: 404 }));
Remember that you need to create file db.json
yourself. If not, the response will be empty and status 404.
If you want only to check how a request would modify db.json database without touching it, you can do a dry run.
# --allow-write is not necessary
deno run --allow-net --allow-read tino.js --dry=true
In your code you can achieve same by passing true
to jsondb
responder:
app.get(() => ({ path: "/ping", use: jsondb(true), root: true }));
You can run Tino on custom port:
deno run --allow-net --allow-read --allow-write tino.js --port=7000
Similarly, in your code you can pass it to listen
method:
// if you omit port, it will be 8000
tino.listen({ app, port: 7777 });
You can find maintained list of exampes in examples.js file.
Author: Vertrical
Source Code: https://github.com/Vertrical/tino
#deno #node #nodejs #javascript