Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iconshot/superbia
JavaScript library for creating powerful APIs.
https://github.com/iconshot/superbia
api backend javascript node
Last synced: 16 days ago
JSON representation
JavaScript library for creating powerful APIs.
- Host: GitHub
- URL: https://github.com/iconshot/superbia
- Owner: iconshot
- License: mit
- Created: 2023-06-28T14:13:01.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-30T07:34:02.000Z (9 months ago)
- Last Synced: 2024-12-27T23:43:57.213Z (about 2 months ago)
- Topics: api, backend, javascript, node
- Language: JavaScript
- Homepage: https://superbia.dev
- Size: 56.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [Superbia](https://superbia.dev/)
JavaScript library for creating powerful APIs.
## Installation
```
npm i superbia
```## Get started
### Server
1. Let's create a new `server`.
```js
const { Server } = require("superbia");const server = new Server();
```2. We add a type.
```js
server.setType("User", { id: "ID", name: "String" });
```3. We add a request endpoint.
```js
server
.setRequest("user") // endpoint name
.setParams({ id: "ID" }) // endpoint params
.setResult("User") // type returned by resolver
.setResolver(({ params: { id } }) => {
// dummy resolverconst 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;
});
```4. We start the `server` on the port we want.
```js
server.start(8080);
```That's it. Our `server` is up and running.
### Client
Now, using `@superbia/client` we can access the endpoint just created.
```js
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](https://github.com/iconshot/superbia-client).
## Basics
### Types
Types can be objects, methods or arrays.
```js
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.
```js
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.
```js
server.setType("User", {
id: "ID!", // can't be null
firstPostId: "ID", // can be null
});
```### Arrays
You can define arrays by using the syntax `[Type]`.
```js
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.
```js
server
.setRequest("uploadPhoto")
.setParams({ upload: "Upload" }) // notice the Upload type
.setResolver(async ({ params: { upload } }) => {
// get the name of the fileconst 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`.
```js
let counter = 0;
```We define the subscription endpoint:
```js
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:
```js
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.