{"id":43691932,"url":"https://github.com/contactlab/appy","last_synced_at":"2026-02-05T03:38:11.828Z","repository":{"id":28860995,"uuid":"118134421","full_name":"contactlab/appy","owner":"contactlab","description":"A functional wrapper around Fetch API","archived":false,"fork":false,"pushed_at":"2024-04-15T05:27:00.000Z","size":2715,"stargazers_count":64,"open_issues_count":7,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-24T20:10:26.793Z","etag":null,"topics":["appy","contactlab","fetch","fp","fp-ts","typescript"],"latest_commit_sha":null,"homepage":"https://contactlab.github.io/appy","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contactlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2018-01-19T14:23:47.000Z","updated_at":"2025-03-21T15:02:24.000Z","dependencies_parsed_at":"2023-01-16T21:45:28.961Z","dependency_job_id":"388a9428-9dae-4a47-85ec-a3ad2593a866","html_url":"https://github.com/contactlab/appy","commit_stats":{"total_commits":693,"total_committers":8,"mean_commits":86.625,"dds":0.6406926406926408,"last_synced_commit":"e441e48451f5b77e1f28e75fd9d50f7f15b66bc4"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/contactlab/appy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contactlab%2Fappy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contactlab%2Fappy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contactlab%2Fappy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contactlab%2Fappy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contactlab","download_url":"https://codeload.github.com/contactlab/appy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contactlab%2Fappy/sbom","scorecard":{"id":303227,"data":{"date":"2025-08-11","repo":{"name":"github.com/contactlab/appy","commit":"62d4acf664dcc6ad85e05e3e3287c805621a7a01"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.4,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/3 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:28","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:29","Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/node-ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:71: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/codeql-analysis.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node-ci.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/node-ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/node-ci.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/contactlab/appy/node-ci.yml/master?enable=pin","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   1 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"SAST","score":7,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 0 commits out of 29 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":1,"reason":"9 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T21:18:09.211Z","repository_id":28860995,"created_at":"2025-08-17T21:18:09.211Z","updated_at":"2025-08-17T21:18:09.211Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29109304,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T03:27:05.906Z","status":"ssl_error","status_checked_at":"2026-02-05T03:26:43.416Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["appy","contactlab","fetch","fp","fp-ts","typescript"],"created_at":"2026-02-05T03:38:11.548Z","updated_at":"2026-02-05T03:38:11.817Z","avatar_url":"https://github.com/contactlab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @contactlab/appy\n\n![Node CI](https://github.com/contactlab/appy/workflows/Node%20CI/badge.svg) ![npm (scoped)](https://img.shields.io/npm/v/@contactlab/appy?logo=npm) ![node-current (scoped)](https://img.shields.io/node/v/@contactlab/appy) ![GitHub package.json dependency version (dev dep on branch)](https://img.shields.io/github/package-json/dependency-version/contactlab/appy/dev/typescript) ![GitHub package.json dependency version (dev dep on branch)](https://img.shields.io/github/package-json/dependency-version/contactlab/appy/dev/fp-ts) ![GitHub](https://img.shields.io/github/license/contactlab/appy)\n\nA functional wrapper around Fetch API.\n\n## Install\n\n```sh\n$ npm install @contactlab/appy fp-ts\n\n# --- or ---\n\n$ yarn add @contactlab/appy fp-ts\n```\n\n## Motivation\n\n`appy` tries to offer a better model for fetching resources, using the standard global `fetch()` function as a \"backbone\" and some principles from Functional Programming paradigm.\n\nThe model is built around the concepts of:\n\n- a function with some configurable options (`Reader`)\n- that runs asynchronous operations (`Task`)\n- which can fail for some reason (`Either`)\n\nIn order to achieve this, `appy` intensely uses:\n\n- [Typescript](https://www.typescriptlang.org) \u003e= v3.2.2\n- [`fp-ts`](https://github.com/gcanti/fp-ts)\n\n## API\n\n`appy` exposes a simple core API that can be extended with [\"combinators\"](#combinators).\n\nIt encodes through the `Req\u003cA\u003e` type a resource's request, or rather, an async operation that can fail or return a `Resp\u003cA\u003e`.\n\nFor better composability, the request is expressed in terms of `ReaderTaskEither` - a function that takes a `ReqInput` as parameter and returns a `TaskEither`: we can act on both side of operation (input and output) with the tools provided by `fp-ts`.\n\n```ts\ninterface Req\u003cA\u003e extends ReaderTaskEither\u003cReqInput, Err, Resp\u003cA\u003e\u003e {}\n```\n\n`ReqInput` encodes the `fetch()` parameters: a single [`RequestInfo`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) (simple string or [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object) or a tuple of `RequestInfo` and [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) (the object containing request's options, that it's optional in the original `fetch()` API).\n\n```ts\ntype ReqInput = RequestInfo | RequestInfoInit;\n\n// Just an alias for a tuple of `RequesInfo` and `RequestInit` (namely the `fetch()` parameters)\ntype RequestInfoInit = [RequestInfo, RequestInit];\n```\n\n`Resp\u003cA\u003e` is an object that carries the original `Response` from a `fetch()` call, the actual retrieved `data` (of type `A`) and the request's input (optional).\n\n```ts\ninterface Resp\u003cA\u003e {\n  response: Response;\n  data: A;\n  input?: RequestInfoInit;\n}\n```\n\n`Err` encodes (as tagged union) the two kind of error that can be generated by `Req`: a `RequestError` or a `ResponseError`.\n\n```ts\ntype Err = RequestError | ResponseError;\n```\n\n`RequestError` represents a request error. It carries the generated `Error` and the input of the request (`RequestInfoInit` tuple).\n\n```ts\ninterface RequestError {\n  type: 'RequestError';\n  error: Error;\n  input: RequestInfoInit;\n}\n```\n\n`ResponseError` represents a response error. It carries the generated `Error`, the original `Response` object and the request's input (optional).\n\n```ts\ninterface ResponseError {\n  type: 'ResponseError';\n  error: Error;\n  response: Response;\n  input?: RequestInfoInit;\n}\n```\n\n## Examples\n\n```ts\nimport {get} from '@contactlab/appy';\nimport {fold} from 'fp-ts/Either';\n\nconst users = get('https://reqres.in/api/users');\n\nusers().then(\n  fold(\n    err =\u003e console.error(err),\n    resp =\u003e console.log(resp.data)\n  )\n);\n```\n\nYou can find other examples [here](https://github.com/contactlab/appy/tree/master/examples).\n\n## Combinators\n\nTo make easier extending the library functionalities, any other feature should then be expressed as a simple combinator `Req\u003cA\u003e =\u003e Req\u003cA\u003e`.\n\nSo, for example, decoding the response body as JSON:\n\n```ts\nimport {get} from '@contactlab/appy';\nimport {withDecoder, Decoder} from '@contactlab/appy/combinators/decoder';\nimport {pipe} from 'fp-ts/function';\n\ninterface User {\n  id: number;\n  email: string;\n  first_name: string;\n  last_name: string;\n  avatar: string;\n}\n\ndeclare const userDec: Decoder\u003cUser\u003e;\n\nconst getUser = pipe(get, withDecoder(userDec));\n\nconst singleUser = getUser('https://reqres.in/api/users/1');\n```\n\nor adding headers to the request:\n\n```ts\nimport {get} from '@contactlab/appy';\nimport {withHeaders} from '@contactlab/appy/combinators/headers';\n\nconst asJson = pipe(get, withHeaders({'Content-Type': 'application/json'}));\n\nconst users = asJson('https://reqres.in/api/users');\n```\n\nor setting request's body (for `POST`s or `PUT`s):\n\n```ts\nimport {post} from '@contactlab/appy';\nimport {withBody} from '@contactlab/appy/combinators/body';\nimport {pipe} from 'fp-ts/function';\n\nconst send = pipe(\n  post,\n  withBody({email: 'foo.bar@mail.com', first_name: 'Foo', last_name: 'Bar'})\n);\n\nconst addUser = send('https://reqres.in/api/users');\n```\n\n### `io-ts` integration\n\n[`io-ts`](https://github.com/gcanti/io-ts) is recommended but not automatically installed as dependency.\n\nIn order to use it with the `Decoder` combinator you can write a simple helper like:\n\n```ts\nimport * as t from 'io-ts';\nimport {failure} from 'io-ts/PathReporter';\nimport {Decoder, toDecoder} from '@contactlab/appy/combinators/decoder';\n\nexport const fromIots = \u003cA\u003e(d: t.Decoder\u003cunknown, A\u003e): Decoder\u003cA\u003e =\u003e\n  toDecoder(d.decode, e =\u003e new Error(failure(e).join('\\n')));\n```\n\nOr, with the [Decoder](https://gcanti.github.io/io-ts/modules/Decoder.ts.html) module:\n\n```ts\nimport * as D from 'io-ts/Decoder';\nimport {Decoder, toDecoder} from '@contactlab/appy/combinators/decoder';\n\nexport const fromIots = \u003cA\u003e(d: D.Decoder\u003cunknown, A\u003e): Decoder\u003cA\u003e =\u003e\n  toDecoder(d.decode, e =\u003e new Error(D.draw(e)));\n```\n\n## About `fetch()` compatibility\n\nThe Fetch API is available only on \"modern\" browsers: if you need to support legacy browsers (e.g. **Internet Explorer 11** or older) or you want to use it in a Nodejs script we recommend you the excellent [`cross-fetch`](https://www.npmjs.com/package/cross-fetch) package.\n\n**Be aware that Nodejs lacks of some classes and directives which have to be exposed to the global scope (check out the [tests setup file](https://github.com/contactlab/appy/blob/master/test/_setup.ts)).**\n\n### Publish a new version\n\nIn order to keep the package's file structure as flat as possible, the \"usual\" npm `publish` command was disabled (via a `prepublishOnly` script) in favour of a `release` script:\n\n```sh\n$ npm run release\n```\n\nThis command will execute `npm publish` directly in the `/dist` folder, where the `postbuild` script previously copied the `package.json` and other usefull files (`LICENSE`, `CHANGELOG.md`, etc...).\n\n## License\n\nReleased under the [Apache 2.0](https://github.com/contactlab/appy/blob/master/LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontactlab%2Fappy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontactlab%2Fappy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontactlab%2Fappy/lists"}