{"id":21364844,"url":"https://github.com/fbn/yado-js","last_synced_at":"2025-03-16T07:26:42.817Z","repository":{"id":57154981,"uuid":"326794158","full_name":"FbN/yado-js","owner":"FbN","description":"Yet Another Javascript Do-Notation","archived":false,"fork":false,"pushed_at":"2021-01-26T20:15:15.000Z","size":156,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-03-25T20:36:57.406Z","etag":null,"topics":["composing","do-notation","functional-programming","monads"],"latest_commit_sha":null,"homepage":"https://github.com/FbN/yado-js","language":"JavaScript","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/FbN.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":"2021-01-04T19:59:59.000Z","updated_at":"2021-01-26T20:12:45.000Z","dependencies_parsed_at":"2022-09-06T20:12:41.876Z","dependency_job_id":null,"html_url":"https://github.com/FbN/yado-js","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FbN%2Fyado-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FbN%2Fyado-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FbN%2Fyado-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FbN%2Fyado-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FbN","download_url":"https://codeload.github.com/FbN/yado-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243839247,"owners_count":20356191,"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":["composing","do-notation","functional-programming","monads"],"created_at":"2024-11-22T07:07:57.089Z","updated_at":"2025-03-16T07:26:42.795Z","avatar_url":"https://github.com/FbN.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/FbN/yado-js\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/FbN/yado-js/HEAD/images/logo.png\" alt=\"YADO JS\" width=\"400\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eYet Another \u003cstrong\u003eDo-Notation\u003c/strong\u003e for Javascript\u003c/h3\u003e\n\u003c/p\u003e\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\n## Table of Contents\n\n-   [About the Project](#about-the-project)\n-   [Getting Started](#getting-started)\n-   [Usage](#usage)\n-   [Statements Types](#statements-types)\n-   [Fantasy Land](#fantasy-land)\n-   [License](#license)\n-   [Contact](#contact)\n-   [Related and similar projects](#related-and-similar-projects)\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n\n## About The Project\n\nHaskell [Do-Notation](https://en.wikibooks.org/wiki/Haskell/do_notation) is a great feature too works with monads.\n\nThere are different attempts to bring it Javascript world, that I can resume in these types:\n\n-   **Generator based**: Use generator functions and yield instruction as Haskell bind operator. This would be a great solution but with a very [heavy drawback](https://github.com/pelotom/burrido#caveats).\n\n-   **Language Extension**: Extend Javascript language to desugar your do code to vanilla javascript. This requires to precompile your code or use eval to dynamic evaluate your \"just in time\" desugared code (what about debugging? IDE?).\n\n-   **Emulate by Data structure**: The case of this library. We use a vanilla javascript data structure that will be interpreted as Do notation. This brings:\n\n    -   😄 Vannilla javascript. No pre-compilation / eval.\n\n    -   😄 Support non-deterministic Monads.\n\n    -   😄 Computationally Efficient\n\n    -   😔 Non as clean to write/read as generators or language extension.\n\n\u003c!-- GETTING STARTED --\u003e\n\n## Getting Started\n\nAdd to your project\n\n```sh\nyarn add yado-js\n```\n\n\u003c!-- USAGE EXAMPLES --\u003e\n\n## Usage\n\nYou write your Do block as an array of statements.\n\nEvery statement is a Javascript object or a function.\n\nWe have three types of objects: bind, returns, and to.\n\nYou can write these objects directly or using a utility function.\n\nDo keep all declared vars in an object that we call scope (it's like the javascript local scope in the case of the generator function). So every statement can act and change the vars in the scope (see the section about function to discover more).\n\nLet's discover by samples:\n\n_Burrido version_\n\n```js\nimport BurridoModule from 'burrido'\nconst Burrido = BurridoModule.default\n\nconst ArrayDo = Burrido({\n    pure: x =\u003e [x],\n    bind: (xs, f) =\u003e xs.map(f).reduce((a, b) =\u003e a.concat(b)\n}).Do\n\nArrayDo(function * () {\n    const x = yield [1, 2]\n    const y = yield [3, 4]\n    return x * y\n}) // [3, 4, 6, 8]\n```\n\n_Yado version (no utility function)_\n\n```js\nimport { Do } from 'yado-js'\n\nconst ArrayDo = Do({\n    pure: x =\u003e [x],\n    bind: xs =\u003e f =\u003e xs.map(f).reduce((a, b) =\u003e a.concat(b)\n})\n\nArrayDo([\n    { x: [1, 2] },\n    { y: [3, 4] },\n    {return: s =\u003e s.x * s.y}\n]) // [3, 4, 6, 8]\n```\n\n_Yado version (using utility function)_\n\n```js\nimport {Do, bind, returns} from 'yado-js'\n\nconst ArrayDo = Do({\n    pure: x =\u003e [x],\n    bind: xs =\u003e f =\u003e xs.map(f).reduce((a, b) =\u003e a.concat(b)\n})\n\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    returns(s =\u003e s.x * s.y)\n]) // [3, 4, 6, 8]\n```\n\n## Scope init\nBy default Do start the computation with an empty scope {}.\nIt's possibile to start computation with an initial scope using Exe.\n\n```js\nimport {Exe, bind, returns} from 'yado-js'\n\nconst ArrayDo = Exe({\n    pure: x =\u003e [x],\n    bind: xs =\u003e f =\u003e xs.map(f).reduce((a, b) =\u003e a.concat(b)\n})\n\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    returns(s =\u003e s.x * s.y + s.k)\n])({k: 1}) // [4, 5, 7, 9]\n```\n\n**See below for more example and use cases**\n\n\u003c!-- STATEMENTS --\u003e\n## Statements Types\n\nEvery element of the array passed to Do function is can be a plain object or a function and interpreted as described below.\n\n### Objects\n\n-   [`bind`](#bind)\n-   [`return`](#return)\n-   [`to`](#to)\n\n### Function\n\n-   [`Statement Returning`](#statements-returning)\n-   [`Scope Returning`](#scope-returning)\n\n## Objects\n\n### bind\n\nEvery plain object with keys that are not javascript reserver words (not this to be clear {return: 0})\n\n#### Example:\n\n```js\nimport { Do } from 'yado-js'\n\nconst ArrayDo = Do({\n    pure: x =\u003e [x],\n    bind: xs =\u003e f =\u003e xs.map(f).reduce((a, b) =\u003e a.concat(b), [])\n})\n\nArrayDo([\n    { x: [1, 2] },\n    { y: [3, 4] },\n    { return: s =\u003e s.x * s.y } // [3, 4, 6, 8]\n])\n\n```\nIn the example the object { x: [1, 2] } is desugared to as we call bind on the argument and assign result to x.\n\n```js\nbind([1, 2])(x =\u003e bind([3, 4])(y =\u003e pure(x * y)))\n```\n\nIs possible to group many binds in the same statement object:\n```js\n// see up for ArrayDo init\nArrayDo([\n    { x: [1, 2], y: [3, 4] },\n    { return: s =\u003e s.x * s.y } // [3, 4, 6, 8]\n])\n```\n\nInstead of directly set a monad instance as argument we can pass a function that takes as input the scope and return a monad instance.\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    { x: [1, 2] },\n    { y: s =\u003e [s.x + 1, s.x + 4] },\n    { return: s =\u003e s.x * s.y }\n])\n```\n\nsame as:\n\n```js\nbind([1, 2])(x =\u003e bind([x + 3, x + 4])(y =\u003e pure(x * y)))\n```\n\n---\n\n### return\n\nStatement used to return and the Do block. Take as argument a function from _scope_ to a value to be returned or directly a value.\n\nWe can have many return statements, look at this sample:\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    { x: [1, 2] },\n    { y: [3, 4] },\n    s =\u003e (s.x === 2 \u0026\u0026 s.y === 3 ? [{ return: 0 }] : []),\n    { return: s =\u003e s.x * s.y }\n]) // [ 3, 4, 0, 8 ]\n```\n\nWe can write it with utility functions:\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    s =\u003e (s.x === 2 \u0026\u0026 s.y === 3 ? [returns(0)] : []),\n    returns(s =\u003e s.x * s.y)\n]) // [ 3, 4, 0, 8 ]\n```\n\nN.B. The utility function is named return**s** for obvious reason.\n\n---\n\n### to\n\nShortcut to set a value into the scope.\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    to('z')(s =\u003e s.x === 2 \u0026\u0026 s.y === 3)\n    s =\u003e (s.z ? [returns(0)] : []),\n    returns(s =\u003e s.x * s.y)\n]) // [ 3, 4, 0, 8 ]\n```\n\nThe above is like.\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    { x: [1, 2] },\n    { y: [3, 4] },\n    s =\u003e ({ ...s, z: s.x === 2 \u0026\u0026 s.y === 3 }),\n    s =\u003e (s.z ? [{ return: 0 }] : []),\n    { return: s =\u003e s.x * s.y }\n]) // [ 3, 4, 0, 8 ]\n```\n\n---\n\n## functions\n\nWhen the statement is a function will be executed taking the scope as argument. The function can return two types: Array or Object.\n\n### scope =\u003e []\n\nFunction that returns an array of additional statements that will be interpreted before continue.\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    s =\u003e (s.x === 2 \u0026\u0026 s.y === 3 ? [returns(0)] : []),\n    returns(s =\u003e s.x * s.y)\n]) // [ 3, 4, 0, 8 ]\n```\n\n---\n\n### scope =\u003e {}\n\nA function that returns an object. The object will replace the block scope.\n\n```js\n// see up for ArrayDo init\nArrayDo([\n    bind('x')([1, 2]),\n    bind('y')([3, 4]),\n    s =\u003e ({ ...s, z: 1 }),\n    returns(s =\u003e s.x * s.y)\n]) // [ 4, 5, 7, 9 ]\n```\n---\n\n\u003c!-- FANTASYLAND --\u003e\n## Fantasy Land\n\nThe Do function recognize fantasy land compliant monads\n\n```js\nimport { Do } from 'yado-js'\nimport S from 'sanctuary'\n\nconst MaybeDo = Do(S.Maybe)\n\nMaybeDo([\n    { x: S.Just(3) },\n    { y: S.Nothing },\n    { return: s =\u003e s.x + s.y }\n]) // null\n```\n\n\u003c!-- LICENSE --\u003e\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n\u003c!-- CONTACT --\u003e\n\n## Contact\n\nFabiano Taioli - ftaioli@gmail.com\n\nProject Link: [https://github.com/FbN/yado-js](https://github.com/FbN/yado-js)\n\n\u003c!-- RELATED --\u003e\n## Related and similar projects\n\nSome library found looking around. In no any special order.\n\n-   [Burrido](https://github.com/pelotom/burrido):\n    Based on generator functions. Must re-run computation for every value. Pure and bind must be side-effect free. Inefficient, requiring O(n^2).\n-   [Fantasy Do](https://github.com/russellmcc/fantasydo):\n    Same as Burrido but target Fantasy land compliant monads. Same pro/contro.\n-   [Monadic](https://github.com/five-eleven/monadic):\n    Javascript language expansion. Compiled or by code eval.\n-   [@masaeedu/do](https://github.com/masaeedu/do):\n    Similar to this project. You must declare binded vars at start. Lack features (many return points).\n-   [monadicjs](https://github.com/coot/monadicjs):\n-   [monio](https://github.com/getify/monio):\n    Use generator and promises. Do not support non deterministic monads.\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n\n[contributors-shield]: https://img.shields.io/github/contributors/FbN/yado-js.svg?style=flat-square\n[contributors-url]: https://github.com/FbN/yado-js/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/FbN/yado-js.svg?style=flat-square\n[forks-url]: https://github.com/FbN/yado-js/network/members\n[stars-shield]: https://img.shields.io/github/stars/FbN/yado-js.svg?style=flat-square\n[stars-url]: https://github.com/FbN/yado-js/stargazers\n[issues-shield]: https://img.shields.io/github/issues/FbN/yado-js.svg?style=flat-square\n[issues-url]: https://github.com/FbN/yado-js/issues\n[license-shield]: https://img.shields.io/github/license/FbN/yado-js.svg?style=flat-square\n[license-url]: https://github.com/FbN/yado-js/blob/master/LICENSE.txt\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat-square\u0026logo=linkedin\u0026colorB=555\n[linkedin-url]: https://linkedin.com/in/othneildrew\n[product-screenshot]: images/screenshot.png\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbn%2Fyado-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffbn%2Fyado-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbn%2Fyado-js/lists"}