{"id":21815294,"url":"https://github.com/iconshot/superbia","last_synced_at":"2026-04-22T23:34:43.629Z","repository":{"id":176999122,"uuid":"659767786","full_name":"iconshot/superbia","owner":"iconshot","description":"JavaScript library for creating powerful APIs.","archived":false,"fork":false,"pushed_at":"2026-02-11T22:26:31.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T07:20:21.011Z","etag":null,"topics":["api","backend","javascript","node"],"latest_commit_sha":null,"homepage":"https://superbia.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iconshot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-28T14:13:01.000Z","updated_at":"2026-02-11T22:26:35.000Z","dependencies_parsed_at":"2025-09-25T03:23:15.282Z","dependency_job_id":"0c2887af-d2f4-4405-bf13-8d4ed5dfa5cb","html_url":"https://github.com/iconshot/superbia","commit_stats":null,"previous_names":["iconshot/superbia"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iconshot/superbia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iconshot%2Fsuperbia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iconshot%2Fsuperbia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iconshot%2Fsuperbia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iconshot%2Fsuperbia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iconshot","download_url":"https://codeload.github.com/iconshot/superbia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iconshot%2Fsuperbia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32159959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","javascript","node"],"created_at":"2024-11-27T15:17:27.140Z","updated_at":"2026-04-22T23:34:43.612Z","avatar_url":"https://github.com/iconshot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Superbia](https://superbia.dev/)\r\n\r\nJavaScript library for creating powerful APIs.\r\n\r\n## Installation\r\n\r\n```\r\nnpm i superbia\r\n```\r\n\r\n## Get started\r\n\r\n### Server\r\n\r\n1. Let's create a new `server`.\r\n\r\n```js\r\nconst { Server } = require(\"superbia\");\r\n\r\nconst server = new Server();\r\n```\r\n\r\n2. We add a type.\r\n\r\n```js\r\nserver.setType(\"User\", { id: \"ID\", name: \"String\" });\r\n```\r\n\r\n3. We add a request endpoint.\r\n\r\n```js\r\nserver\r\n  .setRequest(\"user\") // endpoint name\r\n  .setParams({ id: \"ID\" }) // endpoint params\r\n  .setResult(\"User\") // type returned by resolver\r\n  .setResolver(({ params: { id } }) =\u003e {\r\n    // dummy resolver\r\n\r\n    const users = [\r\n      { id: \"1\", name: \"Jhon Doe\" },\r\n      { id: \"2\", name: \"Jane Cat\" },\r\n    ];\r\n\r\n    // only ids \"1\" and \"2\" will return a user, any other id will result in an error\r\n\r\n    const user = users.find((user) =\u003e user.id === id);\r\n\r\n    if (user === undefined) {\r\n      throw new Error(\"User not found.\");\r\n    }\r\n\r\n    return user;\r\n  });\r\n```\r\n\r\n4. We start the `server` on the port we want.\r\n\r\n```js\r\nserver.start(8080);\r\n```\r\n\r\nThat's it. Our `server` is up and running.\r\n\r\n### Client\r\n\r\nNow, using `@superbia/client` we can access the endpoint just created.\r\n\r\n```js\r\nconst response = await client.request({ user: { id: \"1\" } });\r\n\r\nconst data = response.data();\r\n\r\nconst {\r\n  user: { name },\r\n} = data;\r\n\r\nconsole.log(name); // Jhon Doe\r\n```\r\n\r\nMore on the `client` in the [@superbia/client's page](https://github.com/iconshot/superbia-client).\r\n\r\n## Basics\r\n\r\n### Types\r\n\r\nTypes can be objects, methods or arrays.\r\n\r\n```js\r\nserver.setType(\"User\", { id: \"ID\", name: \"String\" });\r\n\r\nserver.setType(\"EvenNumber\", (value) =\u003e value % 2 === 0);\r\n\r\nserver.setType(\"PrimaryColor\", [\"red\", \"green\", \"blue\"]);\r\n```\r\n\r\nThe basic types are: `String`, `ID`, `Int`, `Float`, `Boolean`, `Date`, `Upload`.\r\n\r\n### Composition\r\n\r\nYou can include a type in the schema of another type.\r\n\r\n```js\r\nserver.setType(\"Coordinates\", { latitude: \"Float\", longitude: \"Float\" });\r\n\r\nserver.setType(\"Restaurant\", { name: \"String\", coordinates: \"Coordinates\" });\r\n```\r\n\r\n### Null or not\r\n\r\nYou can specify if a value can be null or not. A trailing `!` will be enough.\r\n\r\n```js\r\nserver.setType(\"User\", {\r\n  id: \"ID!\", // can't be null\r\n  firstPostId: \"ID\", // can be null\r\n});\r\n```\r\n\r\n### Arrays\r\n\r\nYou can define arrays by using the syntax `[Type]`.\r\n\r\n```js\r\nserver.setType(\"User\", {\r\n  stories: \"[ID]\", // \"stories\" array can be null, \"stories\" items can be null\r\n  posts: \"[ID]!\", // \"posts\" array can't be null, \"posts\" items can be null\r\n  friends: \"[ID!]!\", // \"friends\" array can't be null, \"friends\" items can't be null\r\n});\r\n```\r\n\r\n## Uploads\r\n\r\nYou just need to add the `Upload` type as a parameter.\r\n\r\n```js\r\nserver\r\n  .setRequest(\"uploadPhoto\")\r\n  .setParams({ upload: \"Upload\" }) // notice the Upload type\r\n  .setResolver(async ({ params: { upload } }) =\u003e {\r\n    // get the name of the file\r\n\r\n    const name = upload.getName();\r\n\r\n    // uploads will be kept in memory until we save them\r\n\r\n    await upload.write(name);\r\n  });\r\n```\r\n\r\n## Subscriptions\r\n\r\nWe'll understand subscriptions better with an example.\r\n\r\nLet's say we have a `counter` and we want to create a subscription for listening to changes in this `counter`.\r\n\r\n```js\r\nlet counter = 0;\r\n```\r\n\r\nWe define the subscription endpoint:\r\n\r\n```js\r\nserver\r\n  .setSubscription(\"counter\")\r\n  .setResult(\"Int\") // it works the same way as in requests\r\n  .setResolver(() =\u003e {\r\n    // instead of returning the data right away\r\n    // we return an object with two properties\r\n    // subscribe (required) and unsubscribe (optional)\r\n\r\n    return {\r\n      subscribe: () =\u003e {\r\n        return \"counterRoom\"; // a room key\r\n      },\r\n    };\r\n  });\r\n```\r\n\r\nLater on your server you run:\r\n\r\n```js\r\ncounter++;\r\n\r\nserver.publish(\"counterRoom\", counter); // notice how we use the same room key as before\r\n```\r\n\r\nThe explanation is simple:\r\n\r\n`setSubscription` will attach a `roomKey` to a subscription. Then, when we publish data to that `roomKey`, the subscription will be notified.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficonshot%2Fsuperbia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficonshot%2Fsuperbia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficonshot%2Fsuperbia/lists"}