Repository files navigation

Monio (mō'ne-yo) provides an async-capable IO Monad (including "do" style) for JS, with several helpful companion monads (like Maybe and Either) thrown in.

Monio's IO/IOx is the most powerful IO monad implementation in JS, possibly in any language!

Note: This is obviously a marketing claim, not a provable mathematical/scientific assertion. Nevertheless, I believe it's true!

Just("Welcome, Monads").concat(Just(" And Friends")).map(v=>v.toUpperCase()).fold(Maybe.from).map(v=>v+"!").fold(()=>IO.of("--empty--"),greetings=>IO(()=>console.log(greetings))).run();// WELCOME, MONADS AND FRIENDS!

If you're already comfortable with Functional Programming (FP), and you're at least familiar with monads, and if the code snippet above doesn't scare you away,skip to "See Monio In Action". Or, if you're just looking for quick code examples of all the monads inMonio,check 'em out here!

But if terms like "higher-order function" or "monad" are confusing or intimidating to you, I encourage you to take some time first to build some comfort and familiarity; these are the foundations you need to get the most out ofMonio.

I don't want you to feel intimidated. This isn't going to require you to speak in mathematical notation or re-learn everything you thought you knew about programming.

Well... to be clear, what I mean is, you don't have to do all thatjust to get started. There are small and comfortable baby steps you can begin taking to kick off the journey. The further you explore down the path, I think the more FP and monads will "hook" you, nudging and tugging you into different ways of thinking about and solving problems.

Now, it's time todive into FP... and then Monads. But if you're already comfortable with FP, and ready to tackle learning monads specifically, you canjump directly to "Expansive Intro To Monads".

Make sure you take your time reading through that guide; it's pretty long and detailed, and there's a lot to digest.

To see how writingMonio-based code looks and feels, especially the use of IO/IOx monads (and all its variations), check out these demos. There's a variety of different approaches/styles demonstrated, which illustrate the flexibilityMonio's monads offer.

Here's a full demo app (client and server) featuringMonio:

Monio Demo App

In addition, here's some live codepen demos:

• Cancelable Countdown (demo)

• Order Lookup (demo)

• Cached Ajax (demo)

• Event Stream (demo)

• Event Stream: IOx Reactive Monad (demo)

• IOx Reactive Monad (demo)

• IOx Reactive Monad: Stream Operations (demo)

• IOx Countdown Timer (demo) andIOx Countdown Timer Alternative (demo)

Check outMonio's Monads for more example code snippets and detailed descriptions.

Monio balances the power of monads -- often dismissed by the non-FP programmer as academic and convoluted -- while pragmatically embracing the reality of the vast majority of JS programs: paradigm mixture (some OO, some FP, and probably a lot of imperative procedural code).

The driving inspiration behind Monio is theIO monad -- useful for managing side-effects -- that additionally supports "do-style" syntax with JS-ergonomic asynchrony (based on promises) in the style of familiarasync..await code. IOs are lazy, so their operations are not triggered until therun(..) method is called.

Monio'sIO is a transformer over promises, which means that when promises are produced in an IO, they are automatically unwrapped; of course, that means subsequent IO operations are deferred. If any IO in a chain produces a promise,run(..)'s result will be "lifted" to a promise that resolves when the entire IO chain is complete. Otherwise, the IO instance and itsrun(..) call will operate synchronously and immediately produce the result.

Monio intentionally chooses to model asynchrony over promises instead of Future monads, because of its goal of balancing FP with pragmatic and idomatic non-FP JS. However, there's nothing that should prevent you from using a Future monad with Monio if you prefer.

IO's "do-style" syntax is specified with thedo(..) method (automatically lifts the IO to promise-producing asynchrony), which accepts JS generators (including "async generators":async function *whatever(){ .. }).yield is used for chaining IOs (which can produce promises to defer), whereasawait is for explicitly deferring on a promise that's not already wrapped in an IO. The resulting style of code should be more broadly approachable for JS developers, while still benefitting from monads.

IO'sdo(..) is JS-ergonomic for exception handling: uncaught JS exceptions become promise rejections, and IO-produced promise rejections aretry..catch'able.IO also supports modeling exception handling through Either monads:doEither(..) transforms uncaught exceptions intoEither:Left values, and recognizes IO-producedEither:Left values astry..catch'able exceptions.

Monio'sIO is also a Reader monad, which carries side-effect read environments alongside IO operations.

Monio'sIO models a functione => IO a (Promise b c), which is strong enough to capture (optional) environment passing, side effects, async, and error handling without the pain of composing each type separately.

TypicallyIO does not take an argument, but given one, it acts like an effectfulReader. In addition, it can model sync or async functions so the innerPromise becomes optional.

In that way, you can think of it asReaderT (IOT (Promise|Identity a b)) wherePromise gets swapped forIdentity if you're not doing async.

Monio's IO is like Scala'sZIO / RIO, where we have all the functionality we need wrapped up in a single monad kind.

Just("Are you ready for Monio?");

Check outMonio's Monads for a bunch of code snippets and detailed descriptions of all the monads (and helpers) provided in this library.

To use monads/helpers from Monio,require(..) orimport .. themby name:

• CJS programs/modules in Node (requires Node v12+):

  var{ Maybe,IO}=require("monio");// or:varJust=require("monio/just");

• ESM in Node (requires Node v14+):

  import{Maybe,IO}from"monio";// or:importJustfrom"monio/just";

  Note: As of v0.32.0, the previously deprecated ESM import specifier segment/esm inMonioimport paths has been removed, in favor of unified import specifier paths viaNode Conditional Exports. For ESMimport statements, use the specifier style"monio" or"monio/just".

• ESM in browser (requires browser with ES6+ support):

  <scripttype="module"src="/path/to/my-app.mjs"></script>

  // my-app.mjs:import{Maybe,IO}from"/path/to/monio/dist/esm/index.mjs";// or:importJustfrom"/path/to/monio/dist/esm/just.mjs";

  It's clearly unfortunate/inconvenient to have to specify URL paths (including filename extensions!) toimport Monio entities when using ESM-format in the browser. This is an artifact of how browsers currently support ESM.

  The current best-option work-around is to use anImport-Map (if yourtarget browser environment supports them) on your site to create friendlierimport-path names that the browser then maps to the required URL paths.

  To use an Import-Map, include an inline<script type="importmap">..</script> block in each HTML page of your site, with the Import-Map JSON contents inside the block.

  If you'd like to useMonio ESM-format in the browser with the same friendlyimport names that are available for Nodeimport /require, and if Import-Mapsare supported in your target browser environment, you can start with the contents of the provideddist/esm/import-map-template.json file:

  <!-- your HTML page --><scripttype="importmap">{"imports":{"monio":"/monio/index.mjs","monio/just":"/monio/just.mjs","monio/nothing":"/monio/nothing.mjs",// .."monio/util":"/monio/lib/util.mjs"}}</script><!-- your HTML page -->

  As you can see in the above snippet, the assumed paths in this template file all expectMonio'sdist/esm directory to be deployed at the root of your site as/monio/*. Adjust those paths as necessary to match your site's deployment structure.

  • Important Note:

    Whether you use an Import-Map (as just described) or not, since ESM-format files are not bundled together, but loaded separately, thedist/esm files internally use relativeimport paths that reference each other. This directory/filename structuremust be preserved for ESM-formatMonio to operate in the browser as distributed. As such, make sure the entire contents of thedist/esm directory are deployed to your site exactly as provided.

    If that is not possible, you may use anImport-Map (if yourtarget browser environment supports them) to adapt the original relative ESMimport paths to a different deployment structure and/or file-naming. You could also useImport-Remap to force-rewrite theimport paths to different values.

• UMD in browser (requires browser with ES5+ support):

  <scriptsrc="/path/to/monio/dist/umd/bundle.js"></script><!-- or --><scriptsrc="/path/to/monio/dist/umd/just.js"></script>

  The UMDbundle.js file alone is sufficient forMonio deployment if using the UMD format. Rename thatbundle.js file (e.g.,monio.js) and deploy wherever is appropriate in your site. Youcould deploy and load the individual UMD files if you prefer, but it's generally easier and more efficient to use the single bundle file.

OnceMonio monads are imported into your module/program, instances are created from functions (nonew constructors necessary):

varhelloWorld=Just("Hello World");helloWorld._inspect();// Just("Hello World")Just.is(helloWorld);// true

Monio's monads can of course be used together in various expected ways:

varhelloWorld=Just("Hello World");vargreeting=Maybe(helloWorld);varlog=str=>IO(()=>console.log(str));varmain=IO.do(function*main(){varmsg=greeting.map(m=>`${m}!!`);// Uncomment this line to swap in an empty maybe// msg = Maybe.from(null);yieldmsg.fold(IO.of,log);});main.run();// Hello World!!

Note: For ESM-format usage in the browser, URL paths (with filename extensions!) or Import-Maps are required. To use the friendlier ESM-Node/CJS names while in the browser, an Import-Map is required.See above for explanation.

Here are the individualimport /require named-entity paths:

• Monio Index/Namespace (includes all named top-level entities):"monio"

  ESM (Node):import * as Monio from "monio"

  ESM (Node):import { Just, Maybe, IO } from "monio"

  ESM (Browser):import * as Monio from "/path/to/monio/dist/esm/index.mjs"

  ESM (Browser):import { Just, Maybe, IO } from "/path/to/monio/dist/esm/index.mjs"

  CJS:const Monio = require("monio")

  CJS:const { Just, Maybe, IO } = require("monio")

• Just:"monio/just"

  ESM (Node):import Just from "monio/just"

  ESM (Browser):import Just from "/path/to/monio/dist/esm/just.mjs"

  CJS:const Just = require("monio/just")

• Nothing:"monio/nothing"

  ESM (Node):import Nothing from "monio/nothing"

  ESM (Browser):import Nothing from "/path/to/monio/dist/esm/nothing.mjs"

  CJS:const Nothing = require("monio/nothing")

• Maybe:"monio/maybe"

  ESM (Node):import Maybe from "monio/maybe"

  ESM (Node):import Maybe from "/path/to/monio/dist/esm/maybe.mjs"

  CJS:const Maybe = require("monio/maybe")

• Either:"monio/either"

  ESM (Node):import Either from "monio/either"

  ESM (Node):import Either from "/path/to/monio/dist/esm/either.mjs"

  CJS:const Either = require("monio/either")

• AsyncEither:"monio/async-either"

  ESM (Node):import AsyncEither from "monio/async-either"

  ESM (Browser):import AsyncEither from "/path/to/monio/dist/esm/async-either.mjs"

  CJS:const AsyncEither = require("monio/async-either")

• IO:"monio/io"

  ESM (Node):import IO from "monio/io"

  ESM (Browser):import IO from "/path/to/monio/dist/esm/io/io.mjs"

  CJS:const IO = require("monio/io")

• IOx:"monio/iox" or"monio/io/x"

  ESM (Node):import IOx from "monio/iox"

  ESM (Browser):import IOx from "/path/to/monio/dist/esm/io/iox.mjs"

  CJS:const IOx = require("monio/iox")

• AnyIO:"monio/io/any"

  ESM (Node):import AnyIO from "monio/io/any"

  ESM (Browser):import AnyIO from "/path/to/monio/dist/esm/io/any.mjs"

  CJS:const AnyIO = require("monio/io/any")

• AllIO:"monio/io/all"

  ESM (Node):import AllIO from "monio/io/all"

  ESM (Browser):import AllIO from "/path/to/monio/dist/esm/io/all.mjs"

  CJS:const AllIO = require("monio/io/all")

• IOHelpers (named helpers forIO):"monio/io/helpers"

  ESM (Node):import * as IOHelpers from "monio/io/helpers"

  ESM (Node):import { waitAll, match, applyIO } from "monio/io/helpers"

  ESM (Browser):import * as IOHelpers from "/path/to/monio/dist/esm/io/helpers.mjs"

  ESM (Browser):import { waitAll, match, applyIO } from "/path/to/monio/dist/esm/io/helpers.mjs"

  CJS:const IOHelpers = require("monio/io/helpers")

  CJS:const { waitAll, match, applyIO } = require("monio/io/helpers")

• IOxHelpers (named helpers forIOx):"monio/iox/helpers" or"monio/io/x-helpers"

  ESM (Node):import * as IOxHelpers from "monio/iox/helpers"

  ESM (Node):import { filterIn, distinct, waitFor } from "monio/iox/helpers"

  ESM (Node):import * as IOxHelpers from "/path/to/monio/dist/esm/io/x-helpers.mjs"

  ESM (Node):import { filterIn, distinct, waitFor } from "/path/to/monio/dist/esm/io/x-helpers.mjs"

  CJS:const IOHelpers = require("monio/iox/helpers")

  CJS:const { filterIn, distinct, waitFor } = require("monio/iox/helpers")

• MonioUtil (helper utils for Monio):"monio/util"

  ESM (Node):import * as MonioUtil from "monio/util"

  ESM (Node):import { curry, fold } from "monio/util"

  ESM (Browser):import * as MonioUtil from "/path/to/monio/dist/esm/lib/util.mjs"

  ESM (Browser):import { curry, fold } from "/path/to/monio/dist/esm/lib/util.mjs"

  CJS:const MonioUtil = require("monio/util")

  CJS:const { curry, fold } = require("monio/util")

A test suite is included in this repository, as well as the npm package distribution. The default test behavior runs the test suite using the files insrc/.

1. The tests are run with QUnit.

2. To run the test utility with npm:

   npm test

If you haveNYC (Istanbul) already installed on your system (requires v14.1+), you can use it to check the test coverage:

npm run coverage

Then open upcoverage/lcov-report/index.html in a browser to view the report.

Note: The npm scriptcoverage:report is only intended for use by project maintainers. It sends coverage reports toCoveralls.

All code and documentation are (c) 2024 Kyle Simpson and released under theMIT License. A copy of the MIT Licenseis also included.