{"id":19917237,"url":"https://github.com/athos/kitchen-async","last_synced_at":"2025-05-03T06:30:48.437Z","repository":{"id":41775694,"uuid":"83495935","full_name":"athos/kitchen-async","owner":"athos","description":"A Promise library for ClojureScript, or a poor man's core.async","archived":false,"fork":false,"pushed_at":"2022-12-06T15:05:44.000Z","size":202,"stargazers_count":163,"open_issues_count":11,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-07T11:51:30.464Z","etag":null,"topics":["async","asynchronous","clojurescript","promise","promise-library"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/athos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-01T01:09:47.000Z","updated_at":"2025-03-11T21:08:26.000Z","dependencies_parsed_at":"2023-01-24T02:17:01.662Z","dependency_job_id":null,"html_url":"https://github.com/athos/kitchen-async","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Fkitchen-async","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Fkitchen-async/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Fkitchen-async/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Fkitchen-async/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/athos","download_url":"https://codeload.github.com/athos/kitchen-async/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252154732,"owners_count":21702982,"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":["async","asynchronous","clojurescript","promise","promise-library"],"created_at":"2024-11-12T21:49:12.888Z","updated_at":"2025-05-03T06:30:48.148Z","avatar_url":"https://github.com/athos.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kitchen-async\n[![Clojars Project](https://img.shields.io/clojars/v/kitchen-async.svg)](https://clojars.org/kitchen-async)\n[![CircleCI](https://circleci.com/gh/athos/kitchen-async.svg?style=shield)](https://circleci.com/gh/athos/kitchen-async)\n\nA Promise library for ClojureScript, or a poor man's core.async\n\n## Features\n\n- syntactic support for writing asynchronous code handling Promises as easily as with `async/await` in ECMAScript\n- also available on self-hosted ClojureScript environments, such as [Lumo](https://github.com/anmonteiro/lumo)/[Planck](https://github.com/mfikes/planck)\n- seamless (opt-in) integration with core.async channels\n\nkitchen-async focuses on the ease of Promise handling, and is not specifically intended to be so much performant. If you would rather like such a library, [promesa](https://github.com/funcool/promesa) or [core.async](https://github.com/clojure/core.async) might be more suitable.\n\n## Example\n\nAssume you are writing some `Promise`-heavy async code in ClojureScript (e.g. [Google's Puppeteer](https://github.com/GoogleChrome/puppeteer) provides such a collection of APIs). Then, if you only use raw JavaScript interop facilities for it, you would have to write something like this:\n\n```clj\n(def puppeteer (js/require \"puppeteer\"))\n\n(-\u003e (.launch puppeteer)\n    (.then (fn [browser]\n             (-\u003e (.newPage browser)\n                 (.then (fn [page]\n                          (-\u003e (.goto page \"https://clojure.org\")\n                              (.then #(.screenshot page #js{:path \"screenshot.png\"}))\n                              (.catch js/console.error)\n                              (.then #(.close browser)))))))))\n```\n\n`kitchen-async` provides more succinct, \"direct style\" syntactic sugar for those things, which you may find similar to `async/await` in ECMAScript 2017:\n\n```clj\n(require '[kitchen-async.promise :as p])\n\n(def puppeteer (js/require \"puppeteer\"))\n\n(p/let [browser (.launch puppeteer)\n        page (.newPage browser)]\n  (p/try\n    (.goto page \"https://clojure.org\")\n    (.screenshot page #js{:path \"screenshot.png\"})\n    (p/catch :default e\n      (js/console.error e))\n    (p/finally\n      (.close browser))))\n```\n\n## Installation\n\nAdd the following to your `:dependencies`:\n\n[![Clojars Project](https://clojars.org/kitchen-async/latest-version.svg)](https://clojars.org/kitchen-async)\n\nOr, if you'd rather use an unstable version of the library, you can do that easily via [`deps.edn`](https://clojure.org/guides/deps_and_cli) as well:\n\n```clj\nathos/kitchen-async {:git/url \"https://github.com/athos/kitchen-async.git\" :sha \u003ccommit sha hash\u003e}\n```\n\n## Usage\n\nkitchen-async provides two major categories of APIs:\n- [thin wrapper APIs for JS Promise](#thin-wrapper-apis-for-js-promise)\n- [idiomatic Clojure style syntactic sugar](#idiomatic-clojure-style-syntactic-sugar)\n\nYou can use all these APIs once you `require` `kitchen-async.promise` ns, like the following:\n\n```clj\n(require '[kitchen-async.promise :as p])\n```\n\n### Thin wrapper APIs for JS Promise\n\n#### * `p/promise` macro\n\n`p/promise` macro creates a new Promise:\n\n```clj\n(p/promise [resolve reject]\n  (js/setTimeout #(resolve 42) 1000))  \n;=\u003e #object[Promise [object Promise]]\n```\n\nThis code is equivalent to:\n\n```clj\n(js/Promise. \n (fn [resolve reject]\n   (js/setTimeout #(resolve 42) 1000)))\n```\n\n#### * `p/then` \u0026 `p/catch*`\n\n`p/then` and `p/catch*` simply wrap Promise's `.then` and `.catch` methods, respectively. For example:\n\n```clj\n(-\u003e (some-promise-fn)\n    (p/then (fn [x] (js/console.log x)))\n    (p/catch* (fn [err] (js/console.error err))))\n```\n\nis almost equivalent to:\n\n```clj\n(-\u003e (some-promise-fn)\n    (.then (fn [x] (js/console.log x)))\n    (.catch (fn [err] (js/console.error err))))\n```\n\n#### * `p/resolve` \u0026 `p/reject`\n\n`p/resolve` and `p/reject` wraps `Promise.resolve` and `Promise.reject`, respectively. For example:\n\n```clj\n(p/then (p/resolve 42) prn)\n```\n\nis equivalent to:\n\n```clj\n(.then (js/Promise.resolve 42) prn)\n```\n\n#### * `p/all` \u0026 `p/race`\n\n`p/all` and `p/race` wraps `Promise.all` and `Promise.race`, respectively. For example:\n\n```clj\n(p/then (p/all [(p/resolve 21)\n                (p/promise [resolve]\n                  (js/setTimeout #(resolve 21) 1000))])\n        (fn [[x y]] (prn (+ x y))))\n```\n\nis almost equivalent to:\n\n```clj\n(.then (js/Promise.all #js[(js/Promise.resolve 42)\n                           (js/Promise.\n                             (fn [resolve]\n                               (js/setTimeout #(resolve 42) 1000)))])\n       (fn [[x y]] (prn (+ x y))))\n```\n\n#### * Coercion operator and implicit coercion\n\nkitchen-async provides a fn named `p/-\u003epromise`, which coerces an arbitrary value to a Promise. By default, `p/-\u003epromise` behaves as follows:\n\n- For Promises, acts like `identity` (i.e. returns the argument as is)\n- For any other type of values, acts like `p/resolve`\n\nIn fact, most functions defined as the thin wrapper API (and the macros that will be described below) implicitly apply `p/-\u003epromise` to their input values. Thanks to that trick, you can freely mix up non-Promise values together with Promises:\n\n```clj\n(p/then 42 prn) \n;; it will output 42 with no error\n\n(p/then (p/all [21 (p/resolve 21)])\n        (fn [[x y]] (prn (+ x y))))\n;; this also works well\n```\n\nMoreover, since it's defined as a protocol method, it's possible to extend `p/-\u003epromise` to customize its behavior for a specific data type. For details, see the section [\"Extension of coercion operator\"](#extension-of-coercion-operator). Also, the section [\"Integration with core.async channels\"](#integration-with-coreasync-channels) may help you grasp how we can utilize this capability.\n\n### Idiomatic Clojure style syntactic sugar\n\nkitchen-async also provides variant of several macros (including special forms) in `clojure.core` that return a Promise instead of returning the expression value.\n\n#### `p/do`\n\n`p/do` conjoins the expressions of the body with `p/then` ignoring the intermediate values. For example:\n\n```clj\n(p/do\n  (expr1)\n  (expr2)\n  (expr3))\n```\n\nis equivalent to:\n\n```clj\n(p/then (expr1)\n        (fn [_]\n          (p/then (expr2)\n                  (fn [_] (expr3)))))\n```\n\n#### `p/let`\n\n`p/let` is almost the same as `p/do` except that it names each intermediate value with the corresponding name. For example:\n\n```clj\n(p/let [v1 (expr1)\n        v2 (expr2)]\n  (expr3))\n```\n\nis equivalent to:\n\n```clj\n(p/then (expr1)\n        (fn [v1]\n          (p/then (expr2)\n                  (fn [v2] (expr3)))))\n```\n\nNote that the body of the `p/let` is implicitly wrapped with `p/do` when it has multiple expressions in it. For example, when you write some code like:\n\n```clj\n(p/let [v1 (expr1)]\n  (expr2)\n  (expr3))\n```\n\nthe call to `expr3` will be deferred until `(expr2)` is resolved. To avoid this behavior, you must wrap the body with `do` explicitly:\n\n```clj\n(p/let [v1 (expr1)]\n  (do\n    (expr2)\n    (expr3)))\n```\n\n#### Threading macros\n\nkitchen-async also has its own `-\u003e`, `-\u003e\u003e`, `some-\u003e` and `some-\u003e\u003e`. For example:\n\n```clj\n(p/-\u003e (expr) f (g c))\n```\n\nis equivalent to:\n\n```clj\n(-\u003e (expr)\n    (p/then (fn [x] (f x)))\n    (p/then (fn [y] (g y c))))\n```\n\nand\n\n```clj\n(p/some-\u003e (expr) f (g c))\n```\n\nis equivalent to:\n\n```clj\n(-\u003e (expr)\n    (p/then (fn [x] (some-\u003e x f)))\n    (p/then (fn [y] (some-\u003e y (g c))))\n```\n\n#### Loops\n\nFor loops, you can use `p/loop` and `p/recur`:\n\n```clj\n(defn timeout [ms v]\n  (p/promise [resolve]\n    (js/setTimeout #(resolve v) ms)))\n    \n(p/loop [i (timeout 1000 10)]\n  (when (\u003e i 0)\n    (prn i)\n    (p/recur (timeout 1000 (dec i)))))\n    \n;; Count down the numbers from 10 to 1\n```\n\nNote that the body of the `p/loop` is wrapped with `p/do`, as in the `p/let`.\n\n`p/recur` cannot be used outside of the `p/loop`, and also make sure to call `p/recur` at a tail position.\n\n#### Error handling\n\nFor error handling, you can use `p/try`, `p/catch` and `p/finally`:\n\n```clj\n(p/try\n  (expr)\n  (p/catch js/Error e\n    (js/console.error e))\n  (p/finally\n    (teardown)))\n```\n\nis almost equivalent to:\n\n```clj\n(-\u003e (expr)\n    (p/catch* \n     (fn [e]\n       (if (instance? js/Error e)\n         (js/console.error e)\n         (throw e))))\n    (p/then (fn [v] (p/do (teardown) v))))\n```\n\nNote that the body of the `p/try`, `p/catch` and `p/finally` is wrapped with `p/do`, as in the `p/let`.\n\n`p/catch` and `p/finally` (if any) cannot be used outside of the `p/try`, and also make sure to call them at the end of the `p/try`'s body.\n\n### Extension of coercion operator\n\n(TODO)\n\n### Integration with core.async channels\n\n(TODO)\n\n\u003c!--\n\n## Why not use core.async?\n\n[`core.async`](https://github.com/clojure/core.async) also provides similar async functionalities to `kitchen-async` (and as you may know, it's more powerful in fact), while I believe there are still some rooms where `kitchen-async` shines, such as blah blah blah\n\n--\u003e\n\n## License\n\nCopyright © 2017 Shogo Ohta\n\nDistributed under the Eclipse Public License 1.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathos%2Fkitchen-async","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fathos%2Fkitchen-async","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathos%2Fkitchen-async/lists"}