Merge the commit history and changes from the template repository

.github/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Install NodeJS
       uses: actions/setup-node@v1
       with:
-        node-version: 12.x
+        node-version: 14.x
     - name: Install Dependencies
       run: npm install
     - name: Execute Tests

.gitignore

@@ -1,3 +1,5 @@
 /coverage/
-/index.cjs
+/dist/*
 /node_modules/
+
+!/dist/package.json

CONTRIBUTING.md

@@ -16,3 +16,47 @@
 1. Checkout `master` and make sure it's up to date with the remote
 1. Run `npm run release <level>`, where `<level>` can be any of: 'major',
    'minor', 'patch', 'premajor', 'preminor', 'prepatch', or 'prerelease'.
+
+## Dependency Management
+
+When adding a dependency, first consider whether to add it as
+a *regular* or as a *peer* dependency.
+
+Make sure to update `rollup.config.js` and the usage instructions in `index.js`
+after installing a new dependency . Peer dependencies need to be included in the
+`npm install` example, and all dependencies need to be mentioned in the UMD
+scripting instructions.
+
+### Regular Dependency
+
+Choose a regular dependency when its internal structure is hidden from the
+end-user. For example, if you depend on Fluture internally, but never expose
+Future instances from any of your public facing functions.
+
+The version of a regular dependency should be pinned at the major version
+number. For example `^1.1.0` would allow any versions greater than `1.1.0` and
+smaller than `2.0.0`.
+
+### Peer Dependency
+
+Choose a peer dependency when any of its internal structure is exposed to the
+end-user. For example, if you depend on Fluture and return Future instances
+from public-facing functions, then you should add Fluture as a peer dependency.
+
+The version range of peer dependencies should be as wide as you can make it.
+For example, if you code works with Fluture version 1 as well as version 2, then
+your dependency range should be `>=1.0.0 <3.0.0`. Then whenever a new compatible
+version of Fluture is released, you bump the upper bound to include it. If you
+have to make a breaking change to support the new version of the peer dependency
+then you reset the lower bound.
+
+### Package Lock
+
+We don't use a package lock file, because this is a library, not a tool. The
+reproducible builds provided by a package lock would benefit the developers of
+the library, but not its users. When users install this library, the
+`package.json` file is used to resolve the versions of sub-depdencies. This
+means that even if the developers of this library would have a working
+reproducible build, the library might be installing broken dependencies for its
+users. The trade-off we're making here is that we lose build reproducibility in
+development, but we gain an earlier insight in when a dependency is broken.

LICENSE

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright (c) 2020 Aldwin Vlasblom
+Copyright (c) 2021 Aldwin Vlasblom
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

index.js

@@ -5,6 +5,34 @@
 //.
 //. ## Usage
 //.
+//. ### Node
+//.
+//. ```console
+//. $ npm install --save fluture-observe
+//. ```
+//.
+//. On Node 12 and up, this module can be loaded directly with `import` or
+//. `require`. On Node versions below 12, `require` or the [esm][]-loader can
+//. be used.
+//.
+//. ### Deno and Modern Browsers
+//.
+//. You can load the EcmaScript module from various content delivery networks:
+//.
+//. - [Skypack](https://cdn.skypack.dev/[email protected])
+//. - [JSPM](https://jspm.dev/[email protected])
+//. - [jsDelivr](https://cdn.jsdelivr.net/npm/[email protected]/+esm)
+//.
+//. ### Old Browsers and Code Pens
+//.
+//. There's a [UMD][] file included in the NPM package, also available via
+//. jsDelivr: https://cdn.jsdelivr.net/npm/[email protected]/dist/umd.js
+//.
+//. This file adds `flutureObserve` to the global scope, or use CommonJS/AMD
+//. when available.
+//.
+//. ### Usage Example
+//.
 //. ```js
 //. import {observe, cata} from 'fluture-observe/index.js';
 //.
@@ -32,6 +60,9 @@
 //.   }
 //. }));
 //. ```
+//.
+//. ## API
+
 import daggy from 'daggy';
 import {forkCatch, isFuture} from 'fluture/index.js';
 
@@ -143,3 +174,5 @@ export function observe(f) {
 //. [Fluture]: https://github.com/fluture-js/Fluture
 //. [Daggy]: https://github.com/fantasyland/daggy
 //. [types from Fluture]: https://github.com/fluture-js/Fluture#types
+//. [esm]: https://github.com/standard-things/esm
+//. [UMD]: https://github.com/umdjs/umd

package.json

@@ -2,14 +2,21 @@
   "name": "fluture-observe",
   "version": "1.0.2",
   "description": "Consume a Future, observing changes to its state",
-  "tags": [
+  "keywords": [
     "consume",
     "fluture",
     "observe"
   ],
   "type": "module",
-  "main": "index.cjs",
+  "main": "./dist/umd.js",
   "module": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./dist/umd.js"
+    },
+    "./index.js": "./index.js"
+  },
   "scripts": {
     "build": "rollup -c rollup.config.js",
     "codecov": "codecov",
@@ -23,7 +30,7 @@
     "url": "git://github.com/fluture-js/fluture-observe.git"
   },
   "files": [
-    "/index.cjs",
+    "/dist",
     "/index.js",
     "/LICENSE",
     "/package.json",

rollup.config.js

@@ -1,9 +1,18 @@
+import pkg from './package.json';
+
+const dependencyNames = Array.prototype.concat.call (
+  Object.keys (pkg.dependencies),
+  Object.keys (pkg.peerDependencies)
+);
+
 export default {
   input: 'index.js',
+  external: dependencyNames,
   output: {
     format: 'umd',
-    file: 'index.cjs',
+    file: 'dist/umd.js',
     name: 'flutureObserve',
-    interop: false
+    exports: 'named',
+    globals: {}
   }
 };

scripts/prepublish

@@ -11,6 +11,16 @@ if ! npm outdated --long; then
   fi
 fi
 
+source 'node_modules/sanctuary-scripts/functions'
+
+pkg="$(get repo-name)"
+files=($(get source-files))
+
+sed --in-place "s/$pkg@0.0.0/$pkg@$VERSION/" "${files[@]}"
+sed --in-place "s/$pkg@$PREVIOUS_VERSION/$pkg@$VERSION/" "${files[@]}"
+
+git add -- "${files[@]}"
+
 npm run build
 
 sanctuary-prepublish "$@"

scripts/test

@@ -9,6 +9,5 @@ branches="$(get min-branch-coverage)"
 c8 --check-coverage \
    --branches "$branches" \
    --reporter lcov \
-   node --experimental-modules \
-        --no-warnings \
-        ./node_modules/.bin/oletus
+   --reporter text \
+   oletus