Bring in packages/montar

packages/montar/README.md

@@ -0,0 +1,138 @@
+# montar
+
+manage state in typescript. inspired by [tolitius/mount](https://github.com/tolitius/mount) from clojure.
+
+What's this all about? Watch this [video from Stuart Sierra](https://www.youtube.com/watch?v=13cmHf_kt-Q) to learn more about the background of component, mount, and montar.
+
+## Install
+
+```console
+$ yarn add -D @digiresilience/montar
+```
+
+## Usage
+
+```
+import { defState } from "@digiresilience/montar"
+```
+
+### Creating State
+
+```
+// db.ts
+const db = defState("db", {
+  start: createDbConnection
+})
+
+export default db
+```
+
+where the createDbConnection function creates a connection (for example to a database) and is defined elsewhere.
+
+### Starting state
+
+```
+import { start } from "@digiresilience/montar"
+
+const bootYourApp = async () => {
+  // .. prepare for app boot
+  // ..
+
+  // boot!
+  return start()
+}
+```
+
+### Using State
+
+But wait, there is more.. this state is a top level being, which means it can be simply imported by other namespaces:
+
+For example let's say an app needs a connection above. No problem:
+
+```
+// server.ts
+import db from "./db"
+
+
+async function doStuff() {
+  return db.executeSql("foo")
+}
+```
+
+Note that before `start()` is called, `db` will be uninitialized and therefore unusable. You must call `start()` before accessing any states.
+
+### Starting/Stopping State
+
+`montar` has start and stop functions that will walk all the states created with `defState` and start / stop them accordingly: i.e. will call their start and stop defined functions.
+
+When testing you might be interested in starting only certain states. You can do this with
+
+- `startOnly(string[])` - only start the given states. WARNING: dependencies are not auto started, so you must ensure all dependencies are passed.
+- `startWithout(string[])` - start all states _except_ those passed
+
+### Start and Stop Order
+
+Since dependencies are "injected" by requiring on the namespace level, montar trusts the typescript compiler and node.js runtime to maintain the start and stop order for all the defStates.
+
+The "start" order is then recorded and replayed on each subsequent start
+
+The "stop" order is simply the reverse of the start order.
+
+### Troubleshooting / Debugging
+
+Set the `DEBUG=montar` environment variable for runtime debug logs.
+
+## Differences to mount
+
+montar was created to bring management of top-level application state under
+control. It steals greedily from
+[tolitius/mount](https://github.com/tolitius/mount) a well-known library in the
+clojure and clojurescript community.
+
+The problem solved is: how to load different sub-systems of your application while respecting dependency order? Also, how do achieve this without complicated dependency injection containers that make the code harder to read.
+
+With montar once you define your state, then every other module can import and
+use your state without special syntax or wrappers.
+
+montar differs from mount in these ways:
+
+- **start/stop are async** - the start and stop functions are async
+- **no var rebinding** - instead we use the little-known [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+  - this comes with limitations: only functions, arrays, objects can be defined as state. scalars do not work.
+- **not concerned with reloading** - in clj/cljs you have the repl and great hot-code reloading (thanks to immutable and persistent data structures). we do not have this in javascript.
+
+## Credits
+
+Copyright © 2020-present [Center for Digital Resilience][cdr]
+
+### Contributors
+
+| [![Abel Luck][abelxluck_avatar]][abelxluck_homepage]<br/>[Abel Luck][abelxluck_homepage] |
+| ---------------------------------------------------------------------------------------- |
+
+
+[abelxluck_homepage]: https://gitlab.com/abelxluck
+[abelxluck_avatar]: https://secure.gravatar.com/avatar/0f605397e0ead93a68e1be26dc26481a?s=100&d=identicon
+
+### License
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.en.html)
+
+    GNU AFFERO GENERAL PUBLIC LICENSE
+    Version 3, 19 November 2007
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as
+    published by the Free Software Foundation, either version 3 of the
+    License, or (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+[cdrtech]: https://digiresilience.org/tech/
+[cdr]: https://digiresilience.org