Home
Welcome to the hydrogen wiki! This is a work in progress and will be constantly updated. Below you will find pages to this wiki but also feel free to view some nice features and information about the package.
- Home
- Examples
- Creating an Endpoint
- Understanding Requests
- Understanding Responses
- Dealing with Files
- Enforcing Types
- Endpoint Groups
- Creating a Server
- Using
HObject
- Error Handling
- Dynamic Endpoints
- Post Process Handler
import {HEndpointGroup, HHTTPServer, HRequest, HResponse, StandardType} from "@element-ts/hydrogen";
const rootEndpoint: HEndpointGroup = new HEndpointGroup();
const userEndpoint: HEndpointGroup = new HEndpointGroup();
userEndpoint.post("/sign-up", {
handler: async(req: HRequest, res: HResponse): Promise<void> => {
const body: {name: string, age: number} = req.getBody();
res.send({id: "xxx", name: body.name});
},
types: {
name: StandardType.STRING,
age: StandardType.NUMBER
}
});
rootEndpoint.get("/hello", async(req: HRequest, res: HResponse) => {
res.sendFile("/path-to-file");
});
rootEndpoint.attach("/user", userEndpoint);
new HHTTPServer(rootEndpoint).start(3000);
You can easily require that a request follows a specific type. This project uses
@element-ts/oxygen which is another package in the
element-ts family. All you need to do is specify a types
object when creating a new
endpoint. If an incoming request does not provide the required types, an error will be sent and then the socket will be
closed. View the types page.
All errors are handled with hydrogen if you use an HError
or err(code?: HErrorStatusCode, msg?: string, show: boolean = true): void
it will be handled. You can also throw errors in a handler and hydrogen will handle them for you. If they are of type HError
then errors codes and messages can be send to your client, if not, a 500 - Internal Server Error
will be sent.
Requests and responses are automatically encoded and decoded for you however you still have the option to send raw Buffer
objects through the TCP socket that is open with your client.
You can send files or streams to your client but you can also receive file uploads from your client. To do this all you have to do is define a upload
object on your endpoint you can limit things like mime, size, and where you want the file.
You can handle everything down on the binary level if you like by using the write(b: Buffer)
and writeEnd()
methods on HResponse
but you also have helper methods like res.send(o: object)
, res.sendFile(path: string)
, res.sendString(s: string)
and many many more. They are just sugar on top as everything ends up calling write()
and writeEnd()
I use this package with another package of mine called @element-ts/silicon which is a package for communicating with MongoDB databases. It is very easy to use and I built it to sort of replicate what Parse used to be. In hydrogen I provide an interface called HObject
that requires just one method with the signature bond(): object
. On HResponse
you can use sendHObject(obj: HObject)
and it will take the object you provide and then use the object returned by bond()
and send it using res.send()
. This is helpful if you have properties that you may not want to send to the client all the time yet still provide a super fast way to send an object to your client.
Everything revolves around HEndpointGroup
objects. Once you have created an endpoint group you can either instantiate a HHTTPServer
or HHTTPSServer
(forgive me on the names lol). When you create a new server you must pass in an endpoint group to be used as the root endpoint group of your server. If you want an HTTPS server, simply use an HHTTPSServer
, you will also have to pass in a key and certificate with the signature: new HHTTPSServer(endpointGroup: HEndpointGroup, key: Buffer, cert: Buffer)
and voila you have HTTPS instead of 💩y ol' HTTP.
All of hydrogen is written in TypeScript. If you do not know how to use TypeScript don't worry. It is completely compatible with JavaScript.
I started this package to use in all my different projects. This is sort of a V2 to a package I wrote in 2018. I took everything I learned from the original package and used it. I named it hydrogen because I think element names are cool and hydrogen is kind of a building block for different bonds.
My name is Elijah Cobb. I am a computer science student at Michigan Technological University. I have worked for a few start ups, one right out of high school. I am now the back-end developer for a few small projects and so this package is sort of the base of all my projects. When I need a feature I add it to this package.
Created by Elijah Cobb provided under the MIT license.
- Home
- Examples
- Creating an Endpoint
- Requests
- Responses
- Files
- Enforcing Types
- Endpoint Groups
- Creating a Server
- Using
HObject
- Error Handling
- Dynamic Endpoints
- Post Process Handler
Element is a group of developer tools I have built in TypeScript. Check them out at: element-ts.com.
Author: Elijah Cobb
NPM: @element-ts/hydrogen
Issue Reporting: Github Issues