{"id":16336426,"url":"https://github.com/justinwoo/purescript-milkis","last_synced_at":"2025-03-16T14:31:19.832Z","repository":{"id":23068562,"uuid":"98059439","full_name":"justinwoo/purescript-milkis","owner":"justinwoo","description":"A Purescript library for working with fetch for HTTP requests","archived":false,"fork":false,"pushed_at":"2022-05-14T22:14:46.000Z","size":56,"stargazers_count":49,"open_issues_count":7,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-27T10:59:06.620Z","etag":null,"topics":["fetch","node","purescript"],"latest_commit_sha":null,"homepage":"https://purescript-milkis.readthedocs.io","language":"PureScript","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/justinwoo.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}},"created_at":"2017-07-22T21:43:30.000Z","updated_at":"2023-04-03T19:16:53.000Z","dependencies_parsed_at":"2022-08-09T06:30:30.784Z","dependency_job_id":null,"html_url":"https://github.com/justinwoo/purescript-milkis","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinwoo%2Fpurescript-milkis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinwoo%2Fpurescript-milkis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinwoo%2Fpurescript-milkis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinwoo%2Fpurescript-milkis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinwoo","download_url":"https://codeload.github.com/justinwoo/purescript-milkis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243819033,"owners_count":20352807,"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","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":["fetch","node","purescript"],"created_at":"2024-10-10T23:44:05.769Z","updated_at":"2025-03-16T14:31:19.134Z","avatar_url":"https://github.com/justinwoo.png","language":"PureScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Purescript-Milkis\n\n[![Build Status](https://travis-ci.org/justinwoo/purescript-milkis.svg?branch=master)](https://travis-ci.org/justinwoo/purescript-milkis)\n\n[![Documentation Status](https://readthedocs.org/projects/purescript-milkis/badge/?version=latest)](https://purescript-milkis.readthedocs.io/en/latest/?badge=latest)\n\nA library for working with the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) both in the Browser and on Node via [node-fetch](https://github.com/bitinn/node-fetch), for all your HTTP request needs.\n\nAptly named for the greatest soft drink of all time, [Milkis](https://en.wikipedia.org/wiki/Milkis).\n\n![](https://i.imgur.com/StOQOAP.jpg)\n\nRead the [guide](https://purescript-milkis.readthedocs.io) to learn how to use this library.\n\n## Installation\n\n`npm install --save node-fetch`\n\n`bower install --save purescript-milkis`\n\n## Usage\n\nSee the [tests](./test/Main.purs)\n\n## Example Usage\n\nI use Milkis in my [ytcasts](https://github.com/justinwoo/ytcasts/blob/89617f69ceb7f6ceb4193ad7922c20fe1664c294/src/Main.purs#L133) project in order to download HTML from a Youtube page:\n\n```purs\ndownloadCasts ::\n  forall e.\n  DBConnection -\u003e\n  Url -\u003e\n  Aff\n    (Program e)\n    (Array CastStatus)\ndownloadCasts conn (Url url) = do\n  res \u003c- text =\u003c\u003c fetch url defaultFetchOptions\n  case getCasts res of\n    Right casts -\u003e for casts $ downloadCast conn\n    Left e -\u003e do\n      errorShow e\n      pure []\n```\n\n## Guide\n\n### `FetchImpl`\n\nTo use this library, you'll have to use a value of `FetchImpl`, which is a foreign data type. This library provides two bindings via the modules `Milkis.Impl.Window` and `Milkis.Impl.Node`. You may choose to bring your own, typing a foreign import as `FetchImpl`.\n\nYou can partially apply the function `Milkis.fetch` to get a value of `Fetch`. For example, with Node you could do this:\n\n```hs\nimport Milkis as M\nimport Milkis.Impl.Node (nodeFetch)\n\nfetch :: M.Fetch\nfetch = M.fetch nodeFetch\n```\n\n### `Fetch`\n\n`Fetch` is simply a type alias:\n\n```hs\ntype Fetch\n   = forall options trash\n   . Union options trash Options\n  =\u003e URL\n  -\u003e Record (method :: Method | options)\n  -\u003e Aff Response\n```\n\nWhat this signature says is given some type varaibles `options` and `trash` where there is a `Union` of `options` and `trash` together to form `Options`, we have a function that takes `URL` and a record with a `method :: Method` field and the fields specified in `options` to return an `Aff Response`. Let's look at the definition of `Options`:\n\n```hs\ntype Options =\n  ( method :: Method\n  , body :: String\n  , headers :: Headers\n  , credentials :: Credentials\n  )\n```\n\nSo what the `Union` constraint does here is declare that `options` must have some subset of this row type, and that there exists some `trash` row type that is the complement. *For more reading about `Union`, you might want to read a post about it here: \u003chttps://github.com/justinwoo/my-blog-posts#unions-for-partial-properties-in-purescript\u003e*\n\n### How using `Fetch` works\n\nLet's see an example of this at work:\n\n```hs\nmain = do\n  _response \u003c- Aff.attempt $ fetch (M.URL \"https://www.google.com\") M.defaultFetchOptions\n  case _response of\n    Left e -\u003e do\n      fail $ \"failed with \" \u003c\u003e show e\n    Right response -\u003e do\n      stuff \u003c- M.text response\n      let code = M.statusCode response\n      code `shouldEqual` 200\n      String.null stuff `shouldEqual` false\n```\n\nLet's also peek at the definition of `defaultFetchOptions`:\n\n```hs\ndefaultFetchOptions :: { method :: Method }\ndefaultFetchOptions =\n  { method: getMethod\n  }\n```\n\nSo in this case, we chose to only supply `method :: Method` and it worked. Let's see how this works with a POST request:\n\n```hs\nmain = do\n  let\n    opts =\n      { method: M.postMethod\n      , body: \"{}\"\n      , headers: M.makeHeaders { \"Content-Type\": \"application/json\" }\n      }\n  result \u003c- attempt $ fetch (M.URL \"https://www.google.com\") opts\n  isRight result `shouldEqual` true\n```\n\nThis time, we provided a body for the post method along with some headers. If we look at the type of `makeHeaders`, we can get a better idea of what is happening:\n\n```hs\nmakeHeaders\n  :: forall r . Homogeneous r String\n  =\u003e Record r\n  -\u003e Headers\n```\n\nHere, `makeHeaders` allows us to create headers from a homogeneous record of `String` types using the `Homogeneous` class from [Typelevel Prelude](https://pursuit.purescript.org/packages/purescript-typelevel-prelude).\n\nBy using these constraints, we are able to use `Fetch` in quite flexible ways that don't require having a large set of default options to be overridden. If you understand the content of this page, you'll be able to tackle any problems you run into with this library and understand how to use `Union`-based approaches in general.\n\nFor the browser usage, you should really only need to do `fetch = M.fetch windowFetch` and be on your way, so please look through the [tests](https://github.com/justinwoo/purescript-milkis/blob/master/test/Main.purs) for examples of how to use this library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinwoo%2Fpurescript-milkis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinwoo%2Fpurescript-milkis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinwoo%2Fpurescript-milkis/lists"}