superbia v1.3.14
Superbia
JavaScript library for creating powerful APIs.
Installation
npm i superbia
Get started
Server
- Let's create a new
server
.
const { Server } = require("superbia");
const server = new Server();
- We add a type.
server.setType("User", { id: "ID", name: "String" });
- We add a request endpoint.
server
.setRequest("user") // endpoint name
.setParams({ id: "ID" }) // endpoint params
.setResult("User") // type returned by resolver
.setResolver(({ params: { id } }) => {
// dummy resolver
const users = [
{ id: "1", name: "Jhon Doe" },
{ id: "2", name: "Jane Cat" },
];
// only ids "1" and "2" will return a user, any other id will result in an error
const user = users.find((user) => user.id === id);
if (user === undefined) {
throw new Error("User not found.");
}
return user;
});
- We start the
server
on the port we want.
server.start(8080);
That's it. Our server
is up and running.
Client
Now, using @superbia/client
we can access the endpoint just created.
const response = await client.request({ user: { id: "1" } });
const data = response.data();
const {
user: { name },
} = data;
console.log(name); // Jhon Doe
More on the client
in the @superbia/client's page.
Basics
Types
Types can be objects, methods or arrays.
server.setType("User", { id: "ID", name: "String" });
server.setType("EvenNumber", (value) => value % 2 === 0);
server.setType("PrimaryColor", ["red", "green", "blue"]);
The basic types are: String
, ID
, Int
, Float
, Boolean
, Date
, Upload
.
Composition
You can include a type in the schema of another type.
server.setType("Coordinates", { latitude: "Float", longitude: "Float" });
server.setType("Restaurant", { name: "String", coordinates: "Coordinates" });
Null or not
You can specify if a value can be null or not. A trailing !
will be enough.
server.setType("User", {
id: "ID!", // can't be null
firstPostId: "ID", // can be null
});
Arrays
You can define arrays by using the syntax [Type]
.
server.setType("User", {
stories: "[ID]", // "stories" array can be null, "stories" items can be null
posts: "[ID]!", // "posts" array can't be null, "posts" items can be null
friends: "[ID!]!", // "friends" array can't be null, "friends" items can't be null
});
Uploads
You just need to add the Upload
type as a parameter.
server
.setRequest("uploadPhoto")
.setParams({ upload: "Upload" }) // notice the Upload type
.setResolver(async ({ params: { upload } }) => {
// get the name of the file
const name = upload.getName();
// uploads will be kept in memory until we save them
await upload.write(name);
});
Subscriptions
We'll understand subscriptions better with an example.
Let's say we have a counter
and we want to create a subscription for listening to changes in this counter
.
let counter = 0;
We define the subscription endpoint:
server
.setSubscription("counter")
.setResult("Int") // it works the same way as in requests
.setResolver(() => {
// instead of returning the data right away
// we return an object with two properties
// subscribe (required) and unsubscribe (optional)
return {
subscribe: () => {
return "counterRoom"; // a room key
},
};
});
Later on your server you run:
counter++;
server.publish("counterRoom", counter); // notice how we use the same room key as before
The explanation is simple:
setSubscription
will attach a roomKey
to a subscription. Then, when we publish data to that roomKey
, the subscription will be notified.
1 month ago
1 month ago
1 month ago
6 months ago
6 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago