{"id":30528845,"url":"https://github.com/mitsunee/picoapi","last_synced_at":"2025-08-27T05:47:46.457Z","repository":{"id":40403590,"uuid":"461507369","full_name":"Mitsunee/picoapi","owner":"Mitsunee","description":"PicoApi is a tiny REST API Client with hooks. Supported in both NodeJs and Browsers!","archived":true,"fork":false,"pushed_at":"2022-05-10T16:22:27.000Z","size":228,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-09T13:08:13.264Z","etag":null,"topics":["javascript","nodejs","rest-api","rest-client"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/picoapi","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mitsunee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"mitsunee"}},"created_at":"2022-02-20T14:09:28.000Z","updated_at":"2023-01-15T12:22:12.000Z","dependencies_parsed_at":"2022-08-09T19:30:37.143Z","dependency_job_id":null,"html_url":"https://github.com/Mitsunee/picoapi","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Mitsunee/picoapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mitsunee%2Fpicoapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mitsunee%2Fpicoapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mitsunee%2Fpicoapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mitsunee%2Fpicoapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mitsunee","download_url":"https://codeload.github.com/Mitsunee/picoapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mitsunee%2Fpicoapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272295552,"owners_count":24908954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["javascript","nodejs","rest-api","rest-client"],"created_at":"2025-08-27T05:47:41.722Z","updated_at":"2025-08-27T05:47:46.423Z","avatar_url":"https://github.com/Mitsunee.png","language":"JavaScript","funding_links":["https://github.com/sponsors/mitsunee"],"categories":[],"sub_categories":[],"readme":"# PicoApi\n\nPicoApi is a tiny REST API Client with hooks. Supported in both NodeJs and Browsers!\n\n## Installation\n\nInstall the `picoapi` with the package manager used by your project, for example:\n\n```sh\nnpm install picoapi\n```\n\n## Experimental Feature Notice\n\n- Currently API Methods accept a `RequestInit` (either native or from node-fetch) as second argument. This will change in a future version and also affect what errors get passed to the error hook.\n- TypeScript typings are still experimental and may not be 100% functional yet.\n\n## Usage\n\nImport `createApi` to create your api proxy and use methods to access api routes:\n\n```js\nimport { createApi } from \"picoapi\";\n\nconst myApi = createApi(\"https://myapi.example.com\");\n\nconst users = await myApi.users();\n// =\u003e fetches 'https://myapi.example.com/users/'\n\nconst exampleUser = await myApi.users(\"example-user\");\n// =\u003e fetches 'https://myapi.example.com/users/example-user';\n```\n\n## Hooks\n\nUse the `on` and `unbind` methods to manage hooks:\n\n```js\nmyApi.on(\"success\", myFunction); // attach success hook\nmyApi.unbind(\"success\"); // unbinds success hook\nmyApi.unbind(); // unbinds all hooks\n```\n\nAll hook callbacks receive a `req` argument that contains at least the full request url, method and id.\n\n### Hook: prefetch\n\nThe `prefetch` hook runs before any fetch request is sent. Returning an object with a value in the `data` property will cancel the fetch request and return your value.\n\n```js\nmyApi.on(\"prefetch\", ({ method, id }) =\u003e {\n  if (method == \"users\" \u0026\u0026 id == \"0\") {\n    return { data: { name: \"Admin\" } };\n  }\n  // otherwise no return, fetch request continues as normal\n});\n```\n\n### Hook: error\n\nThe `error` hook is ran to handle errors. Its req argument also contains the status (status Code) and statusMessage of the request.\n\n```js\nmyApi.on(\"error\", req =\u003e {\n  console.error(`Could not fetch ${req.url}`);\n  console.error(`[ERROR] ${req.status}: ${req.statusMessage}`);\n});\n```\n\nReturning an object with a value in the data property will cancel the promise rejection and return your value. A value in the error property instead let's you customize the error.\n\n### Hook: success\n\nThe `success` will be ran at the end of a successful fetch request. Its argument will contain the result in the `req.data` property. Where possible (or forced) this this data will already have gone through `JSON.parse()`.\n\n```js\nmyApi.on(\"success\", req =\u003e {\n  console.log(`Successfully fetched ${req.url}`);\n  return { data: { ...req.data, time: Date.now() } };\n});\n```\n\nAs with the `prefetch` hook returning an object with a value in the data property lets you replace the returned response.\n\n## Browser \u0026 NodeJS Support\n\nPicoApi automatically checks `window` and `global` for an existing fetch API. This means Browser and NodeJS17.x (with experimental Fetch API enabled) are supported by default.\n\nFor NodeJS until the (currently experimental) fetch API is fully supported you can install `node-fetch` and use this import as a polyfill:\n\n```js\nimport \"picoapi/node-polyfill\";\n```\n\nThis sets a global variable that will be checked after `window.fetch` and `global.fetch`.\n\n## Typescript Support (experimental)\n\nTypes for this library require the `@types/node-fetch` package to be installed. You can use Generics to attach a type to your API like:\n\n```ts\ncreateApi\u003cMyInterfaceHere\u003e(urlGoesHere);\n```\n\nTo describe methods you can use the prebuilt `ApiMethod` type:\n\n```ts\ninterface MyApi extends Picoapi {\n  users: ApiMethod\u003cstring[]\u003e;\n}\n```\n\n**Note:** Typescript support is currently experimental. If you encounter any problems or would like to suggest improvements feel free to open an issue.\n\n## Examples\n\nSee [docs/examples](./docs/examples)\n\n## Planned features\n\n- Better url resolving\n  - ignore excess `/`s\n  - add `https://` if no protocol is set\n- Custom Init system\n- `ApiBuilder` class to enable re-useable hooks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitsunee%2Fpicoapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitsunee%2Fpicoapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitsunee%2Fpicoapi/lists"}